4 Nearly all commands have the following common options:
8 Path to configuration file. May be overridden by @env{NNCPCFG}
9 environment variable. If file file is an encrypted @ref{EBlob,
10 eblob}, then ask for passphrase to decrypt it first.
12 Print debug messages. Normally this option should not be used.
15 Minimal required resulting packet size, in KiBs. For example if you
16 send 2 KiB file and set @option{-minsize 4}, then resulting packet
17 will be 4 KiB (containing file itself and some junk).
19 Set desired outgoing packet @ref{Niceness, niceness level}.
21 Set desired reply packet @ref{Niceness, niceness level}. Only freq
22 and exec packets look at that niceness level.
24 Override @ref{CfgVia, via} configuration option for destination node.
25 Specified nodes must be separated with comma: @verb{|NODE1,NODE2|}.
26 With @verb{|-via -|} you can disable relaying at all.
28 Override path to spool directory. May be specified by
29 @env{NNCPSPOOL} environment variable.
31 Override path to logfile. May be specified by @env{NNCPLOG}
34 Print only errors, omit simple informational messages. In any case
35 those messages are logged, so you can reread them using
36 @ref{nncp-log} command.
37 @item -progress, -noprogress
38 Either force progress showing, or disable it.
40 Print version information.
42 Print warranty information (no warranty).
49 $ nncp-bundle [options] -tx [-delete] NODE [NODE ...] > ...
50 $ nncp-bundle [options] -rx -delete [-dryrun] [NODE ...] < ...
51 $ nncp-bundle [options] -rx [-check] [-dryrun] [NODE ...] < ...
54 With @option{-tx} option, this command creates @ref{Bundles, bundle} of
55 @ref{Encrypted, encrypted packets} from the spool directory and writes
58 With @option{-rx} option, this command takes bundle from @code{stdin}
59 and copies all found packets for our node to the spool directory. Pay
60 attention that @strong{no} integrity checking is done by default. Modern
61 tape drives could easily provide too much throughput your CPU won't be
62 able to verify on the fly. So if you won't @ref{nncp-toss, toss}
63 received packets at the place, it is advisable either to run
64 @ref{nncp-check} utility for packets integrity verification, or to use
65 @option{-check} option to enable on the fly integrity check.
67 You can specify multiple @option{NODE} arguments, telling for what nodes
68 you want to create the stream, or take it from. If no nodes are
69 specified for @option{-rx} mode, then all packets aimed at us will be
72 When packets are sent through the stream, they are still kept in the
73 spool directory, because there is no assurance that they are transferred
74 to the media (media (CD-ROM, tape drive, raw hard drive) can end). If
75 you want to forcefully delete them (after they are successfully flushed
76 to @code{stdout}) anyway, use @option{-delete} option.
78 But you can verify produced stream after, by digesting it by yourself
79 with @option{-rx} and @option{-delete} options -- in that mode, stream
80 packets integrity will be checked and they will be deleted from the
81 spool if everything is good. So it is advisable to recheck your streams:
84 $ nncp-bundle -tx ALICE BOB WHATEVER | cdrecord -tao -
85 $ dd if=/dev/cd0 bs=2048 | nncp-bundle -rx -delete
88 @option{-dryrun} option prevents any writes to the spool. This is
89 useful when you need to see what packets will pass by and possibly check
106 NODE[:ADDR] [FORCEADDR]
109 Call (connect to) specified @option{NODE} and run @ref{Sync,
110 synchronization} protocol with the @ref{nncp-daemon, daemon} on the
111 remote side. Normally this command could be run any time you wish to
112 either check for incoming packets, or to send out queued ones.
113 Synchronization protocol allows resuming and bidirectional packets
116 If @option{-rx} option is specified then only inbound packets
117 transmission is performed. If @option{-tx} option is specified, then
118 only outbound transmission is performed.
120 @option{-onlinedeadline} overrides @ref{CfgOnlineDeadline, @emph{onlinedeadline}}.
121 @option{-maxonlinetime} overrides @ref{CfgMaxOnlineTime, @emph{maxonlinetime}}.
122 @option{-rxrate}/@option{-txrate} override @ref{CfgXxRate, rxrate/txrate}.
123 Read @ref{CfgNoCK, more} about @option{-nock} option.
125 @option{-list} option allows you to list packets of remote node, without
126 any transmission. You can specify what packets your want to download, by
127 specifying @option{-pkts} option with comma-separated list of packets
130 Each @option{NODE} can contain several uniquely identified
131 @option{ADDR}esses in @ref{CfgAddrs, configuration} file. If you do
132 not specify the exact one, then all will be tried until the first
133 success. Optionally you can force @option{FORCEADDR} address usage,
134 instead of addresses taken from configuration file. You can specify both
135 @verb{|host:port|} and @verb{#|some command#} formats.
137 Pay attention that this command runs integrity check for each completely
138 received packet in the background. This can be time consuming.
139 Connection could be lost during that check and remote node won't be
140 notified that file is done. But after successful integrity check that
141 file is renamed from @file{.part} one and when you rerun
142 @command{nncp-call} again, remote node will receive completion
145 @option{-autotoss} option runs tosser on node's spool every second
146 during the call. All @option{-autotoss-*} options is the same as in
147 @ref{nncp-toss} command.
153 $ nncp-caller [options] [NODE ...]
156 Croned daemon that calls remote nodes from time to time, according to
157 their @ref{CfgCalls, @emph{calls}} configuration field.
159 Optional number of @option{NODE}s tells to ignore other ones.
160 Otherwise all nodes with specified @emph{calls} configuration
161 field will be called.
163 Look at @ref{nncp-call} for more information.
169 $ nncp-cfgenc [options] [-s INT] [-t INT] [-p INT] cfg.hjson > cfg.hjson.eblob
170 $ nncp-cfgenc [options] -d cfg.hjson.eblob > cfg.hjson
173 This command allows you to encrypt provided @file{cfg.hjson} file with
174 the passphrase, producing @ref{EBlob, eblob}, to safely keep your
175 configuration file with private keys. This utility was written for users
176 who do not want (or can not) to use either @url{https://gnupg.org/,
177 GnuPG} or similar tools. That @file{eblob} file can be used directly in
178 @option{-cfg} option of nearly all commands.
180 @option{-s}, @option{-t}, @option{-p} are used to tune @file{eblob}'s
181 password strengthening function. Space memory cost (@option{-s}),
182 specified in number of BLAKE2b-256 blocks (32 bytes), tells how many
183 memory must be used for hashing -- bigger values are better, but slower.
184 Time cost (@option{-t}) tells how many rounds/iterations must be
185 performed -- bigger is better, but slower. Number of parallel jobs
186 (@option{-p}) tells how many computation processes will be run: this is
187 the same as running that number of independent hashers and then joining
188 their result together.
190 When invoked for encryption, passphrase is entered manually twice. When
191 invoked for decryption (@option{-d} option), it is asked once and exits
192 if passphrase can not decrypt @file{eblob}.
194 @option{-dump} options parses @file{eblob} and prints parameters used
195 during its creation. For example:
197 $ nncp-cfgenc -dump /usr/local/etc/nncp.hjson.eblob
198 Strengthening function: Balloon with BLAKE2b-256
199 Memory space cost: 1048576 bytes
201 Number of parallel jobs: 2
209 $ nncp-cfgmin [options] > stripped.hjson
212 Print out stripped configuration version: only path to @ref{Spool,
213 spool}, path to log file, neighbours public keys are stayed. This is
214 useful mainly for usage with @ref{nncp-xfer} that has to know only
215 neighbours, without private keys involving.
221 $ nncp-cfgnew [options] [-nocomments] > new.hjson
224 Generate new node configuration: private keys, example configuration
225 file and print it to @code{stdout}. You must use this command when you
226 setup the new node. @option{-nocomments} will create configuration file
227 without descriptive huge comments -- useful for advanced users.
229 Pay attention that private keys generation consumes an entropy from your
236 $ nncp-check [-nock] [options]
239 Perform @ref{Spool, spool} directory integrity check. Read all files
240 that has Base32-encoded filenames and compare it with recalculated
241 BLAKE2b hash output of their contents.
243 The most useful mode of operation is with @option{-nock} option, that
244 checks integrity of @file{.nock} files, renaming them to ordinary
245 (verified) encrypted packets.
248 @section nncp-cronexpr
251 $ nncp-cronexpr -num 12 "*/1 * * * * SAT,SUN 2021"
254 Check validity of specified @ref{CronExpr, cron expression} and print 12
261 $ nncp-daemon [options]
262 [-maxconn INT] [-bind ADDR] [-inetd]
266 Start listening TCP daemon, wait for incoming connections and run
267 @ref{Sync, synchronization protocol} with each of them. You can run
268 @ref{nncp-toss} utility in background to process inbound packets from
271 @option{-maxconn} option specifies how many simultaneous clients daemon
272 can handle. @option{-bind} option specifies @option{addr:port} it must
275 It could be run as @command{inetd} service, by specifying
276 @option{-inetd} option. Pay attention that because it uses
277 @code{stdin}/@code{stdout}, it can not effectively work with IO timeouts
278 and connection closing can propagate up to 5 minutes in practice.
282 uucp stream tcp6 nowait nncpuser /usr/local/bin/nncp-daemon nncp-daemon -quiet -inetd
285 @option{-autotoss} option runs tosser on node's spool every second
286 during the call. All @option{-autotoss-*} options is the same as in
287 @ref{nncp-toss} command.
289 Read @ref{CfgNoCK, more} about @option{-nock} option.
295 $ nncp-exec [options] [-use-tmp] [-nocompress] NODE HANDLE [ARG0 ARG1 ...]
298 Send execution command to @option{NODE} for specified @option{HANDLE}.
299 Body is read from @code{stdin} into memory and compressed (unless
300 @option{-nocompress} is specified). After receiving, remote side will
301 execute specified @ref{CfgExec, handle} command with @option{ARG*}
302 appended and decompressed body fed to command's @code{stdin}.
304 If @option{-use-tmp} option is specified, then @code{stdin} data is read
305 into temporary file first, requiring twice more disk space, but no
306 memory requirements. @ref{StdinTmpFile, Same temporary file} rules
307 applies as with @ref{nncp-file, nncp-file -} command.
309 For example, if remote side has following configuration file for your
314 sendmail: [/usr/sbin/sendmail, "-t"]
315 appender: ["/bin/sh", "-c", "cat >> /append"]
319 then executing @verb{|echo My message | nncp-exec -replynice 123 REMOTE
320 sendmail root@localhost|} will lead to execution of:
325 NNCP_SENDER=OurNodeId \
327 /usr/sbin/sendmail -t root@@localhost
330 If @ref{CfgNotify, notification} is enabled on the remote side for exec
331 handles, then it will sent simple letter after successful command
332 execution with its output in message body.
334 @strong{Pay attention} that packet generated with this command won't be
341 $ nncp-file [options] [-chunked INT] SRC NODE:[DST]
344 Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies
345 destination file name in remote's @ref{CfgIncoming, incoming}
346 directory. If this file already exists there, then counter will be
349 This command queues file in @ref{Spool, spool} directory immediately
350 (through the temporary file of course) -- so pay attention that sending
351 2 GiB file will create 2 GiB outbound encrypted packet.
353 @anchor{StdinTmpFile}
354 If @file{SRC} equals to @file{-}, then create an encrypted temporary
355 file and copy everything taken from @code{stdin} to it and use for outbound
356 packet creation. Pay attention that if you want to send 1 GiB of data
357 taken from @code{stdin}, then you have to have more than 2 GiB of disk space
358 for that temporary file and resulting encrypted packet. You can control
359 temporary file location directory with @env{TMPDIR} environment
360 variable. Encryption is performed in AEAD mode with
361 @url{https://cr.yp.to/chacha.html, ChaCha20}-@url{https://en.wikipedia.org/wiki/Poly1305, Poly1305}
362 algorithms. Data is splitted on 128 KiB blocks. Each block is encrypted
363 with increasing nonce counter. File is deletes immediately after
364 creation, so even if program crashes -- disk space will be reclaimed, no
365 need in cleaning it up later.
367 If @file{SRC} points to directory, then
368 @url{https://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13_01, pax archive}
369 will be created on the fly with directory contents and destination
370 filename @file{.tar} appended. It @strong{won't} contain any entities
371 metainformation, but modification time with the names. UID/GID are set
372 to zero. Directories have 777 permissions, files have 666, for being
373 friendly with @command{umask}. Also each entity will have comment like
374 @verb{|Autogenerated by NNCP version X.Y.Z built with goXXX|}.
376 If @option{-chunked} is specified, then source file will be split
377 @ref{Chunked, on chunks}. @option{INT} is the desired chunk size in
378 KiBs. This mode is more CPU hungry. Pay attention that chunk is saved in
379 spool directory immediately and it is not deleted if any error occurs.
380 @option{-minsize} option is applied per each chunk. Do not forget about
381 @ref{ChunkedZFS, possible} ZFS deduplication issues. Zero
382 @option{-chunked} disables chunked transmission.
384 If @ref{CfgNotify, notification} is enabled on the remote side for
385 file transmissions, then it will sent simple letter after successful
392 $ nncp-freq [options] NODE:SRC [DST]
395 Send file request to @option{NODE}, asking it to send its @file{SRC}
396 file from @ref{CfgFreq, freq.path} directory to our node under @file{DST}
397 filename in our @ref{CfgIncoming, incoming} one. If @file{DST} is not
398 specified, then last element of @file{SRC} will be used.
400 If @ref{CfgNotify, notification} is enabled on the remote side for
401 file request, then it will sent simple letter after successful file
411 Parse @ref{Log, log} file and print out its records in short
418 $ nncp-pkt [options] < pkt
419 $ nncp-pkt [options] [-decompress] -dump < pkt > payload
420 $ nncp-pkt -overheads
423 Low level packet parser. Normally it should not be used, but can help in
426 By default it will print packet's type, for example:
428 Packet type: encrypted
430 Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ
433 If you specify @option{-dump} option and provide an @ref{Encrypted,
434 encrypted} packet, then it will verify and decrypt it to @code{stdout}.
435 Encrypted packets contain @ref{Plain, plain} ones, that also can be fed
436 to @command{nncp-pkt}:
440 Payload type: transitional
441 Path: VHMTRWDOXPLK7BR55ICZ5N32ZJUMRKZEMFNGGCEAXV66GG43PEBQ
445 Path: stargrave@@stargrave.org
448 And with the @option{-dump} option it will give you the actual payload
449 (the whole file, mail message, and so on). @option{-decompress} option
450 tries to zstd-decompress the data from plain packet (useful for mail
453 @option{-overheads} options print encrypted, plain and size header overheads.
459 $ nncp-reass [options] [-dryrun] [-keep] [-dump] [-stdout] FILE.nncp.meta
460 $ nncp-reass [options] [-dryrun] [-keep] @{-all | -node NODE@}
463 Reassemble @ref{Chunked, chunked file} after @ref{nncp-toss, tossing}.
465 When called with @option{FILE} option, this command will reassemble only
466 it. When called with @option{-node} option, this command will try to
467 reassemble all @file{.nncp.meta} files found in @option{NODE}'s
468 @ref{CfgIncoming, incoming} directory. When called with @option{-all}
469 option, then cycle through all known nodes to do the same.
471 Reassembling process does the following:
474 @item Parses @ref{Chunked, @file{.nncp.meta}} file.
475 @item Checks existence and size of every @file{.nncp.chunkXXX}.
476 @item Verifies integrity of every chunk.
477 @item Concatenates all chunks, simultaneously removing them from filesystem.
480 That process reads the whole data twice. Be sure to have free disk
481 space for at least one chunk. Decrypted chunk files as a rule are saved
482 in pseudo-random order, so removing them during reassembly process will
483 likely lead to filesystem fragmentation. Reassembly process on
484 filesystems with deduplication capability should be rather lightweight.
486 If @option{-dryrun} option is specified, then only existence and
487 integrity checking are performed.
489 If @option{-keep} option is specified, then no
490 @file{.nncp.meta}/@file{.nncp.chunkXXX} files are deleted during
493 @option{-stdout} option outputs reassembled file to @code{stdout},
494 instead of saving to temporary file with renaming after. This could be
495 useful for reassembling on separate filesystem to lower fragmentation
496 effect, and/or separate storage device for higher performance.
498 @option{-dump} option prints meta-file contents in human-friendly form.
499 It is useful mainly for debugging purposes. For example:
501 Original filename: testfile
502 File size: 3.8 MiB (3987795 bytes)
503 Chunk size: 1.0 MiB (1048576 bytes)
506 0: eac60d819edf40b8ecdacd0b9a5a8c62de2d15eef3c8ca719eafa0be9b894017
507 1: 013a07e659f2e353d0e4339c3375c96c7fffaa2fa00875635f440bbc4631052a
508 2: f4f883975a663f2252328707a30e71b2678f933b2f3103db8475b03293e4316e
509 3: 0e9e229501bf0ca42d4aa07393d19406d40b179f3922a3986ef12b41019b45a3
512 Do not forget about @ref{ChunkedZFS, possible} ZFS deduplication issues.
518 $ nncp-rm [options] -tmp
519 $ nncp-rm [options] -lock
520 $ nncp-rm [options] -node NODE -part
521 $ nncp-rm [options] -node NODE -seen
522 $ nncp-rm [options] -node NODE -nock
523 $ nncp-rm [options] -node NODE [-rx] [-tx]
524 $ nncp-rm [options] -node NODE -pkt PKT
527 This command is aimed to delete various files from your spool directory:
531 @item If @option{-tmp} option is specified, then it will delete all
532 temporary files in @file{spool/tmp} directory. Files may stay in it when
533 commands like @ref{nncp-file} fail for some reason.
535 @item If @option{-lock} option is specified, then all @file{.lock} files
536 will be deleted in your spool directory.
538 @item If @option{-pkt} option is specified, then @file{PKT} packet (its
539 Base32 name) will be deleted. This is useful when you see some packet
540 failing to be processed.
542 @item When either @option{-rx} or @option{-tx} options are specified
543 (maybe both of them), then delete all packets from that given queues.
544 @option{-part} option deletes @file{.part}ly downloaded files.
545 @option{-seen} option deletes @file{.seen} files. @option{-nock} option
546 deletes non-checksummed (non-verified) @file{.nock} files.
548 @item @option{-dryrun} option just prints what will be deleted.
550 @item You can also select files that only have modification date older
551 than specified @option{-older} time units (@code{10s} (10 seconds),
552 @code{5m} (5 minutes), @code{12h} (12 hours), @code{2d} (2 days)).
560 $ nncp-stat [options] [-pkt] [-node NODE]
563 Print current @ref{Spool, spool} statistics about unsent and unprocessed
564 packets. For each node (unless @option{-node} specified) and each
565 niceness level there will be printed how many packets (with the total
566 size) are in inbound (Rx) and outbound (Tx) queues. @option{-pkt} option
567 show information about each packet.
573 $ nncp-toss [options]
584 Perform "tossing" operation on all inbound packets. This is the tool
585 that decrypts all packets and processes all payload packets in them:
586 copies files, sends mails, sends out file requests and relays transition
587 packets. It should be run after each online/offline exchange.
589 @option{-dryrun} option does not perform any writing and sending, just
590 tells what it will do.
592 @option{-cycle} option tells not to quit, but to repeat tossing every
593 @option{INT} seconds in an infinite loop. That can be useful when
594 running this command as a daemon.
596 @option{-seen} option creates empty @file{XXX.seen} file after
597 successful tossing of @file{XXX} packet. @ref{nncp-xfer},
598 @ref{nncp-bundle}, @ref{nncp-daemon} and @ref{nncp-call} commands skip
599 inbound packets that has been already seen, processed and tossed. This
600 is helpful to prevent duplicates.
602 @option{-nofile}, @option{-nofreq}, @option{-noexec}, @option{-notrns}
603 options allow to disable any kind of packet types processing.
609 $ nncp-xfer [options] [-node NODE] [-mkdir] [-keep] [-rx|-tx] DIR
612 Search for directory in @file{DIR} containing inbound packets for us and
613 move them to local @ref{Spool, spool} directory. Also search for known
614 neighbours directories and move locally queued outbound packets to them.
615 This command is used for offline packets transmission.
617 If @option{-mkdir} option is specified, then outbound neighbour(s)
618 directories will be created. This is useful for the first time usage,
619 when storage device does not have any directories tree.
621 If @option{-keep} option is specified, then keep copied files, do not
624 @option{-rx} option tells only to move inbound packets addressed to us.
625 @option{-tx} option tells exactly the opposite: move only outbound packets.
627 @ref{nncp-cfgmin} could be useful for creating stripped minimalistic
628 configuration file version without any private keys.
630 @file{DIR} directory has the following structure:
631 @file{RECIPIENT/SENDER/PACKET}, where @file{RECIPIENT} is Base32 encoded
632 destination node, @file{SENDER} is Base32 encoded sender node.
634 Also look for @ref{nncp-bundle}, especially if you deal with CD-ROM and