Documentation updates

[nncp.git] / doc / cmds.texi

@node Commands
@unnumbered Commands

Nearly all commands have the following common options:

@table @code
@item -debug
    Print debug messages. Normally this option should not be used.
@item -nice
    Set desired outgoing packet niceness level. 1-255 values are
    allowed. Higher value means lower priority. In some commands that
    means processing of packets that have equal or lower nice value.
    That is used for controlling network QoS.
@item -node
    Process only single specified node.
@item -quiet
    Print only errors, omit simple informational messages. In any case
    those messages are logged, so you can reread them using
    @ref{nncp-log} command.
@item -version
    Print version information.
@item -warranty
    Print warranty information (no warranty).
@end table

@node nncp-call
@section nncp-call

@verbatim
% nncp-call [options] [-rx|-tx] NODE[:ADDR] [FORCEADDR]
@end verbatim

Call (connect to) specified @code{NODE} and run @ref{Sync,
synchronization} protocol with the @ref{nncp-daemon, daemon} on the
remote side. Normally this command could be run any time you wish to
either check for incoming packets, or to send out queued ones.
Synchronization protocol allows resuming and bidirectional packets
transfer.

If @code{-rx} option is specified then only inbound packets transmission
is performed. If @code{-tx} option is specified, then only outbound
transmission is performed.

Each @code{NODE} can contain several uniquely identified
@code{ADDR}esses in @ref{Configuration, configuration} file. If you do
not specify the exact one, then all will be tried until the first
success. Optionally you can force @code{FORCEADDR} address usage,
instead of addresses taken from configuration file.

Pay attention that this command run integrity check for each completely
received packet in the background. This can be time consuming and
connection could be lost during that check time and remote node won't be
notified that file is done. But after successful integrity check that
file will be renamed from @code{.part} one and when you rerun
@code{nncp-call} again, remote node will receive completion at once.

@node nncp-check
@section nncp-check

@verbatim
% nncp-check [options]
@end verbatim

Perform @ref{Spool, spool} directory integrity check. Read all files
that has Base32-encoded filenames and compare it with recalculated
BLAKE2b hash output of their contents. This supplementary command should
not be used often in practice, if ever.

@node nncp-daemon
@section nncp-daemon

@verbatim
% nncp-daemon [options] [-maxconn INT] [-bind ADDR]
@end verbatim

Start listening TCP daemon, wait for incoming connections and run
@ref{Sync, sync protocol} with each of them. You can run @ref{nncp-toss}
utility in background to process inbound packets from time to time.

@code{-maxconn} option specifies how many simultaneous clients daemon
can handle. @code{-bind} option specifies @code{addr:port} it must bind
to and listen.

@node nncp-file
@section nncp-file

@verbatim
% nncp-file [options] SRC NODE:[DST]
@end verbatim

Send @code{SRC} file to remote @code{NODE}. @code{DST} specifies
destination file name in remote's @ref{Configuration, incoming}
directory. If this file already exists there, then counter will be
appended to it.

This command queues file in @ref{Spool, spool} directory immediately
(through the temporary file of course) -- so pay attention that sending
2 GiB file will create 2 GiB outbound encrypted packet.

If @ref{Configuration, notification} is enabled on the remote side for
file transmissions, then it will sent simple letter after successful
file receiving.

@node nncp-freq
@section nncp-freq

@verbatim
% nncp-freq [options] NODE:SRC DST
@end verbatim

Send file request to @code{NODE}, asking it to send its @code{SRC} file
from @ref{Configuration, freq} directory to our node under @code{DST}
filename in our @ref{Configuration, incoming} one.

If @ref{Configuration, notification} is enabled on the remote side for
file request, then it will sent simple letter after successful file
queuing.

@node nncp-log
@section nncp-log

@verbatim
% nncp-log [options]
@end verbatim

Parse @ref{Log, log} file and print out its records in human-readable form.

@node nncp-mail
@section nncp-mail

@verbatim
% nncp-mail [options] NODE USER ...
@end verbatim

Send mail, that is read from stdin, to @code{NODE} and specified
@code{USER}s. Mail message will be compressed. After receiving, remote
side will execute specified @ref{Configuration, sendmail} command with
@code{USER}s appended as a command line argument and feed decompressed
mail body to that command's stdin.

@node nncp-newnode
@section nncp-newnode

@verbatim
% nncp-newnode [options] > mynewnode.yaml
@end verbatim

Generate new node: private keys, example configuration file and print it
to stdout. You must use this command when you setup the new node.

Pay attention that private keys generation consumes an entropy from your
operating system.

@node nncp-pkt
@section nncp-pkt

@verbatim
% nncp-pkt [options] < pkt
% nncp-pkt [options] -dump < pkt > payload
@end verbatim

Low level packet parser. Normally it should not be used, but can help in
debugging.

By default it will print packet's type, for example:
@verbatim
Packet type: encrypted
Niceness: 64
Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ
Payload size: 4.0 MiB (4162852 bytes)
@end verbatim

If you specify @code{-dump} option and provide an @ref{Encrypted,
encrypted} packet, then it will verify and decrypt it to stdout.
Encrypted packets contain @ref{Plain, plain} ones, that also can be fed
to @code{nncp-pkt}:

@verbatim
Packet type: plain
Payload type: transitional
Path: VHMTRWDOXPLK7BR55ICZ5N32ZJUMRKZEMFNGGCEAXV66GG43PEBQ

Packet type: plain
Payload type: mail
Path: stargrave@stargrave.org
@end verbatim

And with the @code{-dump} option it will give you the actual payload
(the whole file, mail message, and so on).

@node nncp-stat
@section nncp-stat

@verbatim
% nncp-stat [options]
@end verbatim

Print current @ref{Spool, spool} statistics about unsent and unprocessed
packets. For each node and each niceness level there will be printed how
many packets (with the total size) are in inbound (Rx) and outbound (Tx)
queues.

@node nncp-toss
@section nncp-toss

@verbatim
% nncp-toss [options] [-dryrun]
@end verbatim

Perform "tossing" operation on all inbound packets. This is the tool
that decrypts all packets and processes all payload packets in them:
copies files, sends mails, sends out file requests and relays transition
packets. It should be run after each online/offline exchange.

@code{-dryrun} option does not perform any writing and sending, just
tells what it will do.

@node nncp-xfer
@section nncp-xfer

@verbatim
% nncp-xfer [options] [-force] [-keep] [-rx|-tx] DIR
@end verbatim

Search for directory in @code{DIR} containing inbound packets for us and
move them to local @ref{Spool, spool} directory. Also search for known
neighbours directories and move locally queued outbound packets to them.
This command is used for offline packets transmission.

If @code{-force} option is specified, then outbound neighbour(s)
directories will be created. This is useful for the first time usage,
when storage device does not have any directories tree.

If @code{-keep} option is specified, then keep copied files, do not
remove them.

@code{-rx} option tells only to move inbound packets addressed to us.
@code{-tx} option tells exactly the opposite: move only outbound packets.

@code{DIR} directory has the following structure:
@code{RECIPIENT/SENDER/PACKET}, where @code{RECIPIENT} is Base32 encoded
destination node, @code{SENDER} is Base32 encoded sender node.