+++ /dev/null
-@node Commands
-@unnumbered Commands
-
-Nearly all commands have the following common options:
-
-@table @option
-@item -cfg
- Path to configuration file. May be overridden by @env{NNCPCFG}
- environment variable. If file file is an encrypted @ref{EBlob,
- eblob}, then ask for passphrase to decrypt it first.
-@item -debug
- Print debug messages. Normally this option should not be used.
-@item -minsize
- @anchor{OptMinSize}
- Minimal required resulting packet size, in KiBs. For example if you
- send 2 KiB file and set @option{-minsize 4}, then resulting packet
- will be 4 KiB (containing file itself and some junk).
-@item -nice
- Set desired outgoing packet @ref{Niceness, niceness level}.
-@item -replynice
- Set desired reply packet @ref{Niceness, niceness level}. Only freq
- and exec packets look at that niceness level.
-@item -via
- Override @ref{CfgVia, via} configuration option for destination node.
- Specified nodes must be separated with comma: @verb{|NODE1,NODE2|}.
- With @verb{|-via -|} you can disable relaying at all.
-@item -spool
- Override path to spool directory. May be specified by
- @env{NNCPSPOOL} environment variable.
-@item -log
- Override path to logfile. May be specified by @env{NNCPLOG}
- environment variable.
-@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 -progress, -noprogress
- Either force progress showing, or disable it.
-@item -version
- Print version information.
-@item -warranty
- Print warranty information (no warranty).
-@end table
-
-@node nncp-bundle
-@section nncp-bundle
-
-@example
-$ nncp-bundle [options] -tx [-delete] NODE [NODE ...] > ...
-$ nncp-bundle [options] -rx -delete [-dryrun] [NODE ...] < ...
-$ nncp-bundle [options] -rx [-check] [-dryrun] [NODE ...] < ...
-@end example
-
-With @option{-tx} option, this command creates @ref{Bundles, bundle} of
-@ref{Encrypted, encrypted packets} from the spool directory and writes
-it to @code{stdout}.
-
-With @option{-rx} option, this command takes bundle from @code{stdin}
-and copies all found packets for our node to the spool directory. Pay
-attention that @strong{no} integrity checking is done by default. Modern
-tape drives could easily provide too much throughput your CPU won't be
-able to verify on the fly. So if you won't @ref{nncp-toss, toss}
-received packets at the place, it is advisable either to run
-@ref{nncp-check} utility for packets integrity verification, or to use
-@option{-check} option to enable on the fly integrity check.
-
-You can specify multiple @option{NODE} arguments, telling for what nodes
-you want to create the stream, or take it from. If no nodes are
-specified for @option{-rx} mode, then all packets aimed at us will be
-processed.
-
-When packets are sent through the stream, they are still kept in the
-spool directory, because there is no assurance that they are transferred
-to the media (media (CD-ROM, tape drive, raw hard drive) can end). If
-you want to forcefully delete them (after they are successfully flushed
-to @code{stdout}) anyway, use @option{-delete} option.
-
-But you can verify produced stream after, by digesting it by yourself
-with @option{-rx} and @option{-delete} options -- in that mode, stream
-packets integrity will be checked and they will be deleted from the
-spool if everything is good. So it is advisable to recheck your streams:
-
-@example
-$ nncp-bundle -tx ALICE BOB WHATEVER | cdrecord -tao -
-$ dd if=/dev/cd0 bs=2048 | nncp-bundle -rx -delete
-@end example
-
-@option{-dryrun} option prevents any writes to the spool. This is
-useful when you need to see what packets will pass by and possibly check
-their integrity.
-
-@node nncp-call
-@section nncp-call
-
-@example
-$ nncp-call [options]
- [-onlinedeadline INT]
- [-maxonlinetime INT]
- [-rx|-tx]
- [-list]
- [-pkts PKT,PKT,...]
- [-rxrate INT]
- [-txrate INT]
- [-autotoss*]
- [-nock]
- NODE[:ADDR] [FORCEADDR]
-@end example
-
-Call (connect to) specified @option{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 @option{-rx} option is specified then only inbound packets
-transmission is performed. If @option{-tx} option is specified, then
-only outbound transmission is performed.
-
-@option{-onlinedeadline} overrides @ref{CfgOnlineDeadline, @emph{onlinedeadline}}.
-@option{-maxonlinetime} overrides @ref{CfgMaxOnlineTime, @emph{maxonlinetime}}.
-@option{-rxrate}/@option{-txrate} override @ref{CfgXxRate, rxrate/txrate}.
-Read @ref{CfgNoCK, more} about @option{-nock} option.
-
-@option{-list} option allows you to list packets of remote node, without
-any transmission. You can specify what packets your want to download, by
-specifying @option{-pkts} option with comma-separated list of packets
-identifiers.
-
-Each @option{NODE} can contain several uniquely identified
-@option{ADDR}esses in @ref{CfgAddrs, configuration} file. If you do
-not specify the exact one, then all will be tried until the first
-success. Optionally you can force @option{FORCEADDR} address usage,
-instead of addresses taken from configuration file. You can specify both
-@verb{|host:port|} and @verb{#|some command#} formats.
-
-Pay attention that this command runs integrity check for each completely
-received packet in the background. This can be time consuming.
-Connection could be lost during that check and remote node won't be
-notified that file is done. But after successful integrity check that
-file is renamed from @file{.part} one and when you rerun
-@command{nncp-call} again, remote node will receive completion
-notification.
-
-@option{-autotoss} option runs tosser on node's spool every second
-during the call. All @option{-autotoss-*} options is the same as in
-@ref{nncp-toss} command.
-
-@node nncp-caller
-@section nncp-caller
-
-@example
-$ nncp-caller [options] [NODE ...]
-@end example
-
-Croned daemon that calls remote nodes from time to time, according to
-their @ref{CfgCalls, @emph{calls}} configuration field.
-
-Optional number of @option{NODE}s tells to ignore other ones.
-Otherwise all nodes with specified @emph{calls} configuration
-field will be called.
-
-Look at @ref{nncp-call} for more information.
-
-@node nncp-cfgenc
-@section nncp-cfgenc
-
-@example
-$ nncp-cfgenc [options] [-s INT] [-t INT] [-p INT] cfg.hjson > cfg.hjson.eblob
-$ nncp-cfgenc [options] -d cfg.hjson.eblob > cfg.hjson
-@end example
-
-This command allows you to encrypt provided @file{cfg.hjson} file with
-the passphrase, producing @ref{EBlob, eblob}, to safely keep your
-configuration file with private keys. This utility was written for users
-who do not want (or can not) to use either @url{https://gnupg.org/,
-GnuPG} or similar tools. That @file{eblob} file can be used directly in
-@option{-cfg} option of nearly all commands.
-
-@option{-s}, @option{-t}, @option{-p} are used to tune @file{eblob}'s
-password strengthening function. Space memory cost (@option{-s}),
-specified in number of BLAKE2b-256 blocks (32 bytes), tells how many
-memory must be used for hashing -- bigger values are better, but slower.
-Time cost (@option{-t}) tells how many rounds/iterations must be
-performed -- bigger is better, but slower. Number of parallel jobs
-(@option{-p}) tells how many computation processes will be run: this is
-the same as running that number of independent hashers and then joining
-their result together.
-
-When invoked for encryption, passphrase is entered manually twice. When
-invoked for decryption (@option{-d} option), it is asked once and exits
-if passphrase can not decrypt @file{eblob}.
-
-@option{-dump} options parses @file{eblob} and prints parameters used
-during its creation. For example:
-@example
-$ nncp-cfgenc -dump /usr/local/etc/nncp.hjson.eblob
-Strengthening function: Balloon with BLAKE2b-256
-Memory space cost: 1048576 bytes
-Number of rounds: 16
-Number of parallel jobs: 2
-Blob size: 2494
-@end example
-
-@node nncp-cfgmin
-@section nncp-cfgmin
-
-@example
-$ nncp-cfgmin [options] > stripped.hjson
-@end example
-
-Print out stripped configuration version: only path to @ref{Spool,
-spool}, path to log file, neighbours public keys are stayed. This is
-useful mainly for usage with @ref{nncp-xfer} that has to know only
-neighbours, without private keys involving.
-
-@node nncp-cfgnew
-@section nncp-cfgnew
-
-@example
-$ nncp-cfgnew [options] [-nocomments] > new.hjson
-@end example
-
-Generate new node configuration: private keys, example configuration
-file and print it to @code{stdout}. You must use this command when you
-setup the new node. @option{-nocomments} will create configuration file
-without descriptive huge comments -- useful for advanced users.
-
-Pay attention that private keys generation consumes an entropy from your
-operating system.
-
-@node nncp-check
-@section nncp-check
-
-@example
-$ nncp-check [-nock] [options]
-@end example
-
-Perform @ref{Spool, spool} directory integrity check. Read all files
-that has Base32-encoded filenames and compare it with recalculated
-@ref{MTH} hash output of their contents.
-
-The most useful mode of operation is with @option{-nock} option, that
-checks integrity of @file{.nock} files, renaming them to ordinary
-(verified) encrypted packets.
-
-@node nncp-cronexpr
-@section nncp-cronexpr
-
-@example
-$ nncp-cronexpr -num 12 "*/1 * * * * SAT,SUN 2021"
-@end example
-
-Check validity of specified @ref{CronExpr, cron expression} and print 12
-next time entities.
-
-@node nncp-daemon
-@section nncp-daemon
-
-@example
-$ nncp-daemon [options]
- [-maxconn INT] [-bind ADDR] [-inetd]
- [-autotoss*] [-nock] [-mcd-once]
-@end example
-
-Start listening TCP daemon, wait for incoming connections and run
-@ref{Sync, synchronization protocol} with each of them. You can run
-@ref{nncp-toss} utility in background to process inbound packets from
-time to time.
-
-@option{-maxconn} option specifies how many simultaneous clients daemon
-can handle. @option{-bind} option specifies @option{addr:port} it must
-bind to and listen.
-
-It could be run as @command{inetd} service, by specifying
-@option{-inetd} option. Pay attention that because it uses
-@code{stdin}/@code{stdout}, it can not effectively work with IO timeouts
-and connection closing can propagate up to 5 minutes in practice.
-Example inetd-entry:
-
-@verbatim
-uucp stream tcp6 nowait nncpuser /usr/local/bin/nncp-daemon nncp-daemon -quiet -inetd
-@end verbatim
-
-@option{-autotoss} option runs tosser on node's spool every second
-during the call. All @option{-autotoss-*} options is the same as in
-@ref{nncp-toss} command.
-
-Read @ref{CfgNoCK, more} about @option{-nock} option.
-
-@option{-mcd-once} option sends @ref{MCD} announcements once and quits.
-Could be useful with inetd-based setup, where daemons are not running.
-
-@node nncp-exec
-@section nncp-exec
-
-@example
-$ nncp-exec [options] [-use-tmp] [-nocompress] NODE HANDLE [ARG0 ARG1 ...]
-@end example
-
-Send execution command to @option{NODE} for specified @option{HANDLE}.
-Body is read from @code{stdin} into memory and compressed (unless
-@option{-nocompress} is specified). After receiving, remote side will
-execute specified @ref{CfgExec, handle} command with @option{ARG*}
-appended and decompressed body fed to command's @code{stdin}.
-
-If @option{-use-tmp} option is specified, then @code{stdin} data is read
-into temporary file first, requiring twice more disk space, but no
-memory requirements. @ref{StdinTmpFile, Same temporary file} rules
-applies as with @ref{nncp-file, nncp-file -} command.
-
-For example, if remote side has following configuration file for your
-node:
-
-@verbatim
-exec: {
- sendmail: [/usr/sbin/sendmail, "-t"]
- appender: ["/bin/sh", "-c", "cat >> /append"]
-}
-@end verbatim
-
-then executing @verb{|echo My message | nncp-exec -replynice 123 REMOTE
-sendmail root@localhost|} will lead to execution of:
-
-@example
-echo My message |
- NNCP_SELF=REMOTE \
- NNCP_SENDER=OurNodeId \
- NNCP_NICE=123 \
- /usr/sbin/sendmail -t root@@localhost
-@end example
-
-If @ref{CfgNotify, notification} is enabled on the remote side for exec
-handles, then it will sent simple letter after successful command
-execution with its output in message body.
-
-@strong{Pay attention} that packet generated with this command won't be
-be chunked.
-
-@node nncp-file
-@section nncp-file
-
-@example
-$ nncp-file [options] [-chunked INT] SRC NODE:[DST]
-@end example
-
-Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies
-destination file name in remote's @ref{CfgIncoming, 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.
-
-@anchor{StdinTmpFile}
-If @file{SRC} equals to @file{-}, then create an encrypted temporary
-file and copy everything taken from @code{stdin} to it and use for outbound
-packet creation. Pay attention that if you want to send 1 GiB of data
-taken from @code{stdin}, then you have to have more than 2 GiB of disk space
-for that temporary file and resulting encrypted packet. You can control
-temporary file location directory with @env{TMPDIR} environment
-variable. Encryption is performed in AEAD mode with
-@url{https://cr.yp.to/chacha.html, ChaCha20}-@url{https://en.wikipedia.org/wiki/Poly1305, Poly1305}
-algorithms. Data is divided on 128 KiB blocks. Each block is encrypted
-with increasing nonce counter. File is deletes immediately after
-creation, so even if program crashes -- disk space will be reclaimed, no
-need in cleaning it up later.
-
-If @file{SRC} points to directory, then
-@url{https://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13_01, pax archive}
-will be created on the fly with directory contents and destination
-filename @file{.tar} appended. It @strong{won't} contain any entities
-metainformation, but modification time with the names. UID/GID are set
-to zero. Directories have 777 permissions, files have 666, for being
-friendly with @command{umask}. Also each entity will have comment like
-@verb{|Autogenerated by NNCP version X.Y.Z built with goXXX|}.
-
-If @option{-chunked} is specified, then source file will be split
-@ref{Chunked, on chunks}. @option{INT} is the desired chunk size in
-KiBs. This mode is more CPU hungry. Pay attention that chunk is saved in
-spool directory immediately and it is not deleted if any error occurs.
-@option{-minsize} option is applied per each chunk. Do not forget about
-@ref{ChunkedZFS, possible} ZFS deduplication issues. Zero
-@option{-chunked} disables chunked transmission.
-
-If @ref{CfgNotify, 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
-
-@example
-$ nncp-freq [options] NODE:SRC [DST]
-@end example
-
-Send file request to @option{NODE}, asking it to send its @file{SRC}
-file from @ref{CfgFreq, freq.path} directory to our node under @file{DST}
-filename in our @ref{CfgIncoming, incoming} one. If @file{DST} is not
-specified, then last element of @file{SRC} will be used.
-
-If @ref{CfgNotify, notification} is enabled on the remote side for
-file request, then it will sent simple letter after successful file
-queuing.
-
-@node nncp-hash
-@section nncp-hash
-
-@example
-$ nncp-log [-file ...] [-seek X] [-debug] [-progress]
-@end example
-
-Calculate @ref{MTH} hash of either stdin, or @option{-file} if
-specified.
-
-You can optionally force seeking the file first, reading only part of
-the file, and then prepending unread portion of data, with the
-@option{-seek} option. It is intended only for testing and debugging of
-MTH hasher capabilities.
-
-@option{-debug} option shows all intermediate MTH hashes.
-And @option{-progress} will show progress bar.
-
-@node nncp-log
-@section nncp-log
-
-@example
-$ nncp-log [options]
-@end example
-
-Parse @ref{Log, log} file and print out its records in short
-human-readable form.
-
-@node nncp-pkt
-@section nncp-pkt
-
-@example
-$ nncp-pkt [options] < pkt
-$ nncp-pkt [options] [-decompress] -dump < pkt > payload
-$ nncp-pkt -overheads
-@end example
-
-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:
-@example
-Packet type: encrypted
-Niceness: 64
-Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ
-@end example
-
-If you specify @option{-dump} option and provide an @ref{Encrypted,
-encrypted} packet, then it will verify and decrypt it to @code{stdout}.
-Encrypted packets contain @ref{Plain, plain} ones, that also can be fed
-to @command{nncp-pkt}:
-
-@example
-Packet type: plain
-Payload type: transitional
-Path: VHMTRWDOXPLK7BR55ICZ5N32ZJUMRKZEMFNGGCEAXV66GG43PEBQ
-
-Packet type: plain
-Payload type: mail
-Path: stargrave@@stargrave.org
-@end example
-
-And with the @option{-dump} option it will give you the actual payload
-(the whole file, mail message, and so on). @option{-decompress} option
-tries to zstd-decompress the data from plain packet (useful for mail
-packets).
-
-@option{-overheads} options print encrypted, plain and size header overheads.
-
-@node nncp-reass
-@section nncp-reass
-
-@example
-$ nncp-reass [options] [-dryrun] [-keep] [-dump] [-stdout] FILE.nncp.meta
-$ nncp-reass [options] [-dryrun] [-keep] @{-all | -node NODE@}
-@end example
-
-Reassemble @ref{Chunked, chunked file} after @ref{nncp-toss, tossing}.
-
-When called with @option{FILE} option, this command will reassemble only
-it. When called with @option{-node} option, this command will try to
-reassemble all @file{.nncp.meta} files found in @option{NODE}'s
-@ref{CfgIncoming, incoming} directory. When called with @option{-all}
-option, then cycle through all known nodes to do the same.
-
-Reassembling process does the following:
-
-@enumerate
-@item Parses @ref{Chunked, @file{.nncp.meta}} file.
-@item Checks existence and size of every @file{.nncp.chunkXXX}.
-@item Verifies integrity of every chunk.
-@item Concatenates all chunks, simultaneously removing them from filesystem.
-@end enumerate
-
-That process reads the whole data twice. Be sure to have free disk
-space for at least one chunk. Decrypted chunk files as a rule are saved
-in pseudo-random order, so removing them during reassembly process will
-likely lead to filesystem fragmentation. Reassembly process on
-filesystems with deduplication capability should be rather lightweight.
-
-If @option{-dryrun} option is specified, then only existence and
-integrity checking are performed.
-
-If @option{-keep} option is specified, then no
-@file{.nncp.meta}/@file{.nncp.chunkXXX} files are deleted during
-reassembly process.
-
-@option{-stdout} option outputs reassembled file to @code{stdout},
-instead of saving to temporary file with renaming after. This could be
-useful for reassembling on separate filesystem to lower fragmentation
-effect, and/or separate storage device for higher performance.
-
-@option{-dump} option prints meta-file contents in human-friendly form.
-It is useful mainly for debugging purposes. For example:
-@example
-Original filename: testfile
-File size: 3.8 MiB (3987795 bytes)
-Chunk size: 1.0 MiB (1048576 bytes)
-Number of chunks: 4
-Checksums:
- 0: eac60d819edf40b8ecdacd0b9a5a8c62de2d15eef3c8ca719eafa0be9b894017
- 1: 013a07e659f2e353d0e4339c3375c96c7fffaa2fa00875635f440bbc4631052a
- 2: f4f883975a663f2252328707a30e71b2678f933b2f3103db8475b03293e4316e
- 3: 0e9e229501bf0ca42d4aa07393d19406d40b179f3922a3986ef12b41019b45a3
-@end example
-
- Do not forget about @ref{ChunkedZFS, possible} ZFS deduplication issues.
-
-@node nncp-rm
-@section nncp-rm
-
-@example
-$ nncp-rm [options] -tmp
-$ nncp-rm [options] -lock
-$ nncp-rm [options] -node NODE -part
-$ nncp-rm [options] -node NODE -seen
-$ nncp-rm [options] -node NODE -nock
-$ nncp-rm [options] -node NODE [-rx] [-tx]
-$ nncp-rm [options] -node NODE -pkt PKT
-@end example
-
-This command is aimed to delete various files from your spool directory:
-
-@itemize
-
-@item If @option{-tmp} option is specified, then it will delete all
-temporary files in @file{spool/tmp} directory. Files may stay in it when
-commands like @ref{nncp-file} fail for some reason.
-
-@item If @option{-lock} option is specified, then all @file{.lock} files
-will be deleted in your spool directory.
-
-@item If @option{-pkt} option is specified, then @file{PKT} packet (its
-Base32 name) will be deleted. This is useful when you see some packet
-failing to be processed.
-
-@item When either @option{-rx} or @option{-tx} options are specified
-(maybe both of them), then delete all packets from that given queues.
-@option{-part} option deletes @file{.part}ly downloaded files.
-@option{-seen} option deletes @file{.seen} files. @option{-nock} option
-deletes non-checksummed (non-verified) @file{.nock} files.
-
-@item @option{-dryrun} option just prints what will be deleted.
-
-@item You can also select files that only have modification date older
-than specified @option{-older} time units (@code{10s} (10 seconds),
-@code{5m} (5 minutes), @code{12h} (12 hours), @code{2d} (2 days)).
-
-@end itemize
-
-@node nncp-stat
-@section nncp-stat
-
-@example
-$ nncp-stat [options] [-pkt] [-node NODE]
-@end example
-
-Print current @ref{Spool, spool} statistics about unsent and unprocessed
-packets. For each node (unless @option{-node} specified) and each
-niceness level there will be printed how many packets (with the total
-size) are in inbound (Rx) and outbound (Tx) queues. @option{-pkt} option
-show information about each packet.
-
-@node nncp-toss
-@section nncp-toss
-
-@example
-$ nncp-toss [options]
- [-node NODE]
- [-dryrun]
- [-cycle INT]
- [-seen]
- [-nofile]
- [-nofreq]
- [-noexec]
- [-notrns]
-@end example
-
-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.
-
-@option{-dryrun} option does not perform any writing and sending, just
-tells what it will do.
-
-@option{-cycle} option tells not to quit, but to repeat tossing every
-@option{INT} seconds in an infinite loop. That can be useful when
-running this command as a daemon.
-
-@option{-seen} option creates empty @file{XXX.seen} file after
-successful tossing of @file{XXX} packet. @ref{nncp-xfer},
-@ref{nncp-bundle}, @ref{nncp-daemon} and @ref{nncp-call} commands skip
-inbound packets that has been already seen, processed and tossed. This
-is helpful to prevent duplicates.
-
-@option{-nofile}, @option{-nofreq}, @option{-noexec}, @option{-notrns}
-options allow to disable any kind of packet types processing.
-
-@node nncp-xfer
-@section nncp-xfer
-
-@example
-$ nncp-xfer [options] [-node NODE] [-mkdir] [-keep] [-rx|-tx] DIR
-@end example
-
-Search for directory in @file{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 @option{-mkdir} 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 @option{-keep} option is specified, then keep copied files, do not
-remove them.
-
-@option{-rx} option tells only to move inbound packets addressed to us.
-@option{-tx} option tells exactly the opposite: move only outbound packets.
-
-@ref{nncp-cfgmin} could be useful for creating stripped minimalistic
-configuration file version without any private keys.
-
-@file{DIR} directory has the following structure:
-@file{RECIPIENT/SENDER/PACKET}, where @file{RECIPIENT} is Base32 encoded
-destination node, @file{SENDER} is Base32 encoded sender node.
-
-Also look for @ref{nncp-bundle}, especially if you deal with CD-ROM and
-tape drives.