@table @option
@item -cfg
- Path to configuration file. May be overrided by @env{NNCPCFG}
- environment variable.
+ 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
- Minimal required resulting packet size. For example if you send 2
- KiB file and set @option{-minsize 4096}, then resulting packet will
- be 4 KiB (containing file itself and some junk).
+ @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}.
- 1-255 values are allowed.
-@item -node
- Process only single specified node.
+@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
+
+@verbatim
+$ nncp-bundle [options] -tx [-delete] NODE [NODE ...] > ...
+$ nncp-bundle [options] -rx -delete [-dryrun] [NODE ...] < ...
+$ nncp-bundle [options] -rx [-check] [-dryrun] [NODE ...] < ...
+@end verbatim
+
+With @option{-tx} option, this command creates @ref{Bundles, bundle} of
+@ref{Encrypted, encrypted packets} from the spool directory and writes
+it to stdout.
+
+With @option{-rx} option, this command takes bundle from 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 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:
+
+@verbatim
+$ nncp-bundle -tx ALICE BOB WHATEVER | cdrecord -tao -
+$ dd if=/dev/cd0 bs=2048 | nncp-bundle -rx -delete
+@end verbatim
+
+@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
@verbatim
-% nncp-call [options] [-onlinedeadline INT] [-maxonlinetime INT] [-rx|-tx]
- NODE[:ADDR] [FORCEADDR]
+$ nncp-call [options]
+ [-onlinedeadline INT]
+ [-maxonlinetime INT]
+ [-rx|-tx]
+ [-list]
+ [-pkts PKT,PKT,...]
+ [-rxrate INT]
+ [-txrate INT]
+ NODE[:ADDR] [FORCEADDR]
@end verbatim
Call (connect to) specified @option{NODE} and run @ref{Sync,
only outbound transmission is performed. @option{-onlinedeadline}
overrides @ref{CfgOnlineDeadline, @emph{onlinedeadline}}.
@option{-maxonlinetime} overrides @ref{CfgMaxOnlineTime,
-@emph{maxonlinetime}}.
+@emph{maxonlinetime}}. @option{-rxrate}/@option{-txrate} override
+@ref{CfgXxRate, rxrate/txrate}. @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.
@node nncp-caller
@section nncp-caller
@verbatim
-% nncp-caller [options] [NODE ...]
+$ nncp-caller [options] [NODE ...]
@end verbatim
Croned daemon that calls remote nodes from time to time, according to
Otherwise all nodes with specified @emph{calls} configuration
field will be called.
-@option{-onlinedeadline} overrides @ref{CfgOnlineDeadline,
-@emph{onlinedeadline}} configuration option.
+Look @ref{nncp-call} for more information.
-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.
+@node nncp-cfgenc
+@section nncp-cfgenc
-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.
+@verbatim
+$ nncp-cfgmin [options] [-s INT] [-t INT] [-p INT] cfg.hjson > cfg.hjson.eblob
+$ nncp-cfgmin [options] -d cfg.hjson.eblob > cfg.hjson
+@end verbatim
+
+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:
+@verbatim
+$ 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 verbatim
+
+@node nncp-cfgmin
+@section nncp-cfgmin
+
+@verbatim
+$ nncp-cfgmin [options] > stripped.hjson
+@end verbatim
+
+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
+
+@verbatim
+$ nncp-cfgnew [options] [-nocomments] > new.hjson
+@end verbatim
+
+Generate new node configuration: private keys, example configuration
+file and print it to 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
@verbatim
-% nncp-check [options]
+$ 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 is
+BLAKE2b hash output of their contents. That supplementary command is
not used often in practice, if ever.
@node nncp-daemon
@section nncp-daemon
@verbatim
-% nncp-daemon [options] [-maxconn INT] [-bind ADDR]
+$ nncp-daemon [options] [-maxconn INT] [-bind ADDR] [-inetd]
@end verbatim
Start listening TCP daemon, wait for incoming connections and run
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. Example inetd-entry:
+
+@verbatim
+uucp stream tcp6 nowait nncpuser /usr/local/bin/nncp-daemon nncp-daemon -inetd
+@end verbatim
+
+@node nncp-exec
+@section nncp-exec
+
+@verbatim
+$ nncp-exec [options] NODE HANDLE [ARG0 ARG1 ...]
+@end verbatim
+
+Send execution command to @option{NODE} for specified @option{HANDLE}.
+Body is read from stdin and compressed. After receiving, remote side
+will execute specified @ref{CfgExec, handle} command with @option{ARG*}
+appended and decompressed body fed to command's stdin.
+
+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:
+
+@verbatim
+echo My message |
+ NNCP_SELF=REMOTE \
+ NNCP_SENDER=OurNodeId \
+ NNCP_NICE=123 \
+ /usr/sbin/sendmail -t root@localhost
+@end verbatim
+
+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.
+
@node nncp-file
@section nncp-file
@verbatim
-% nncp-file [options] SRC NODE:[DST]
+$ nncp-file [options] [-chunked INT] SRC NODE:[DST]
@end verbatim
Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies
(through the temporary file of course) -- so pay attention that sending
2 GiB file will create 2 GiB outbound encrypted packet.
+If @file{SRC} equals to @file{-}, then create an encrypted temporary
+file and copy everything taken from stdin to it and use for outbound
+packet creation. Pay attention that if you want to send 1 GiB of data
+taken from stdin, then you have to have more than 2 GiB of disk space
+for that temporary file and resulting encrypted packet. You can control
+where temporary file will be stored using @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 splitted on 128 KiB blocks. Each block is encrypted
+with increasing nonce counter.
+
+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.
@section nncp-freq
@verbatim
-% nncp-freq [options] NODE:SRC DST
+$ nncp-freq [options] NODE:SRC [DST]
@end verbatim
Send file request to @option{NODE}, asking it to send its @file{SRC}
-file from @ref{CfgFreq, freq} directory to our node under @file{DST}
-filename in our @ref{CfgIncoming, incoming} one.
+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
@section nncp-log
@verbatim
-% nncp-log [options]
+$ 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 @option{NODE} and specified
-@option{USER}s. Mail message will be compressed. After receiving, remote
-side will execute specified @ref{CfgSendmail, sendmail} command with
-@option{USER}s appended as a command line argument and feed decompressed
-mail body to that command's stdin.
-
-@node nncp-mincfg
-@section nncp-mincfg
-
-@verbatim
-% nncp-mincfg [options] > stripped.yaml
-@end verbatim
-
-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-newcfg
-@section nncp-newcfg
-
-@verbatim
-% nncp-newcfg [options] > new.yaml
-@end verbatim
-
-Generate new node configuration: 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] [-decompress] -dump < pkt > payload
+$ nncp-pkt [options] < pkt
+$ nncp-pkt [options] [-decompress] -dump < pkt > payload
+$ nncp-pkt -overheads
@end verbatim
Low level packet parser. Normally it should not be used, but can help in
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 zlib-decompress the data from plain packet (useful for mail
+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
+
+@verbatim
+$ nncp-reass [options] [-dryrun] [-keep] [-dump] [-stdout] FILE.nncp.meta
+$ nncp-reass [options] [-dryrun] [-keep] {-all | -node NODE}
+@end verbatim
+
+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 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:
+@verbatim
+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 verbatim
+
+ Do not forget about @ref{ChunkedZFS, possible} ZFS deduplication issues.
+
+@node nncp-rm
+@section nncp-rm
+
+@verbatim
+$ 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 [-rx] [-tx]
+$ nncp-rm [options] -node NODE -pkt PKT
+@end verbatim
+
+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. If
+@option{-part} is given, then delete only @file{.part}ly downloaded
+ones. If @option{-seen} option is specified, then delete only
+@file{.seen} files.
+@end itemize
+
@node nncp-stat
@section nncp-stat
@verbatim
-% nncp-stat [options]
+$ nncp-stat [options] [-node NODE]
@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.
+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.
@node nncp-toss
@section nncp-toss
@verbatim
-% nncp-toss [options] [-dryrun] [-cycle INT]
+$ nncp-toss [options]
+ [-node NODE]
+ [-dryrun]
+ [-cycle INT]
+ [-seen]
+ [-nofile]
+ [-nofreq]
+ [-noexec]
+ [-notrns]
@end verbatim
Perform "tossing" operation on all inbound packets. This is the tool
@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
@verbatim
-% nncp-xfer [options] [-force] [-keep] [-rx|-tx] DIR
+$ nncp-xfer [options] [-node NODE] [-mkdir] [-keep] [-rx|-tx] DIR
@end verbatim
Search for directory in @file{DIR} containing inbound packets for us and
neighbours directories and move locally queued outbound packets to them.
This command is used for offline packets transmission.
-If @option{-force} option is specified, then outbound neighbour(s)
+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.
@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-mincfg} could be useful for creating stripped minimalistic
+@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.