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}.
20 1-255 values are allowed.
22 Process only single specified node.
24 Print only errors, omit simple informational messages. In any case
25 those messages are logged, so you can reread them using
26 @ref{nncp-log} command.
28 Print version information.
30 Print warranty information (no warranty).
37 % nncp-bundle [options] -tx [-delete] NODE [NODE ...] > ...
38 % nncp-bundle [options] -rx -delete [-dryrun] [NODE ...] < ...
39 % nncp-bundle [options] -rx [-check] [-dryrun] [NODE ...] < ...
42 With @option{-tx} option, this command creates @ref{Bundles, bundle} of
43 @ref{Encrypted, encrypted packets} from the spool directory and writes
46 With @option{-rx} option, this command takes bundle from stdin and
47 copies all found packets for our node to the spool directory. Pay
48 attention that @strong{no} integrity checking is done by default. Modern
49 tape drives could easily provide too much throughput your CPU won't be
50 able to verify on the fly. So if you won't @ref{nncp-toss, toss}
51 received packets at the place, it is advisable either to run
52 @ref{nncp-check} utility for packets integrity verification, or to use
53 @option{-check} option to enable on the fly integrity check.
55 You can specify multiple @option{NODE} arguments, telling for what nodes
56 you want to create the stream, or take it from. If no nodes are
57 specified for @option{-rx} mode, then all packets aimed at us will be
60 When packets are sent through the stream, they are still kept in the
61 spool directory, because there is no assurance that they are transferred
62 to the media (media (CD-ROM, tape drive, raw hard drive) can end). If
63 you want to forcefully delete them (after they are successfully flushed
64 to stdout) anyway, use @option{-delete} option.
66 But you can verify produced stream after, by digesting it by yourself
67 with @option{-rx} and @option{-delete} options -- in that mode, stream
68 packets integrity will be checked and they will be deleted from the
69 spool if everything is good. So it is advisable to recheck your streams:
72 % nncp-bundle -tx ALICE BOB WHATEVER | cdrecord -tao -
73 % dd if=/dev/cd0 bs=2048 | nncp-bundle -rx -delete
76 @option{-dryrun} option prevents any writing to the spool. This is
77 useful when you need to see what packets will pass by and possibly check
84 % nncp-call [options] [-onlinedeadline INT] [-maxonlinetime INT] [-rx|-tx]
85 NODE[:ADDR] [FORCEADDR]
88 Call (connect to) specified @option{NODE} and run @ref{Sync,
89 synchronization} protocol with the @ref{nncp-daemon, daemon} on the
90 remote side. Normally this command could be run any time you wish to
91 either check for incoming packets, or to send out queued ones.
92 Synchronization protocol allows resuming and bidirectional packets
95 If @option{-rx} option is specified then only inbound packets
96 transmission is performed. If @option{-tx} option is specified, then
97 only outbound transmission is performed. @option{-onlinedeadline}
98 overrides @ref{CfgOnlineDeadline, @emph{onlinedeadline}}.
99 @option{-maxonlinetime} overrides @ref{CfgMaxOnlineTime,
100 @emph{maxonlinetime}}.
106 % nncp-caller [options] [NODE ...]
109 Croned daemon that calls remote nodes from time to time, according to
110 their @ref{CfgCalls, @emph{calls}} configuration field.
112 Optional number of @option{NODE}s tells to ignore other ones.
113 Otherwise all nodes with specified @emph{calls} configuration
114 field will be called.
116 @option{-onlinedeadline} overrides @ref{CfgOnlineDeadline,
117 @emph{onlinedeadline}} configuration option.
119 Each @option{NODE} can contain several uniquely identified
120 @option{ADDR}esses in @ref{CfgAddrs, configuration} file. If you do
121 not specify the exact one, then all will be tried until the first
122 success. Optionally you can force @option{FORCEADDR} address usage,
123 instead of addresses taken from configuration file.
125 Pay attention that this command runs integrity check for each completely
126 received packet in the background. This can be time consuming.
127 Connection could be lost during that check and remote node won't be
128 notified that file is done. But after successful integrity check that
129 file is renamed from @file{.part} one and when you rerun
130 @command{nncp-call} again, remote node will receive completion
137 % nncp-cfgmin [options] [-s INT] [-t INT] [-p INT] cfg.yaml > cfg.yaml.eblob
138 % nncp-cfgmin [options] -d cfg.yaml.eblob > cfg.yaml
141 This command allows you to encrypt provided @file{cfg.yaml} file with
142 the passphrase, producing @ref{EBlob, eblob}, to safely keep your
143 configuration file with private keys. This utility was written for users
144 who do not want (or can not) to use either @url{https://gnupg.org/,
145 GnuPG} or similar tools. That @file{eblob} file can be used directly in
146 @option{-cfg} option of nearly all commands.
148 @option{-s}, @option{-t}, @option{-p} are used to tune @file{eblob}'s
149 password strengthening function. Space memory cost (@option{-s}),
150 specified in number of BLAKE2b-256 blocks (32 bytes), tells how many
151 memory must be used for hashing -- bigger values are better, but slower.
152 Time cost (@option{-t}) tells how many rounds/iterations must be
153 performed -- bigger is better, but slower. Number of parallel jobs
154 (@option{-p}) tells how many computation processes will be run: this is
155 the same as running that number of independent hashers and then joining
156 their result together.
158 When invoked for encryption, passphrase is entered manually twice. When
159 invoked for decryption (@option{-d} option), it is asked once and exits
160 if passphrase can not decrypt @file{eblob}.
162 @option{-dump} options parses @file{eblob} and prints parameters used
163 during its creation. For example:
165 % nncp-cfgenc -dump /usr/local/etc/nncp.yaml.eblob
166 Strengthening function: Balloon with BLAKE2b-256
167 Memory space cost: 1048576 bytes
169 Number of parallel jobs: 2
177 % nncp-cfgmin [options] > stripped.yaml
180 Print out stripped configuration version: only path to @ref{Spool,
181 spool}, path to log file, neighbours public keys are stayed. This is
182 useful mainly for usage with @ref{nncp-xfer} that has to know only
183 neighbours, without private keys involving.
189 % nncp-cfgnew [options] > new.yaml
192 Generate new node configuration: private keys, example configuration
193 file and print it to stdout. You must use this command when you setup
196 Pay attention that private keys generation consumes an entropy from your
203 % nncp-check [options]
206 Perform @ref{Spool, spool} directory integrity check. Read all files
207 that has Base32-encoded filenames and compare it with recalculated
208 BLAKE2b hash output of their contents. That supplementary command is
209 not used often in practice, if ever.
215 % nncp-daemon [options] [-maxconn INT] [-bind ADDR]
218 Start listening TCP daemon, wait for incoming connections and run
219 @ref{Sync, synchronization protocol} with each of them. You can run
220 @ref{nncp-toss} utility in background to process inbound packets from
223 @option{-maxconn} option specifies how many simultaneous clients daemon
224 can handle. @option{-bind} option specifies @option{addr:port} it must
231 % nncp-file [options] [-chunked INT] SRC NODE:[DST]
234 Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies
235 destination file name in remote's @ref{CfgIncoming, incoming}
236 directory. If this file already exists there, then counter will be
239 This command queues file in @ref{Spool, spool} directory immediately
240 (through the temporary file of course) -- so pay attention that sending
241 2 GiB file will create 2 GiB outbound encrypted packet.
243 If @file{SRC} equals to @file{-}, then create an encrypted temporary
244 file and copy everything taken from stdin to it and use for outbound
245 packet creation. Pay attention that if you want to send 1 GiB of data
246 taken from stdin, then you have to have 2 GiB of disk space for that
247 temporary file and resulting encrypted packet. You can control where
248 temporary file will be stored using @env{TMPDIR} environment variable.
249 Encryption is performed with
250 @url{https://www.schneier.com/academic/twofish/, Twofish} algorithm, 256
251 bit random key, zero IV, in
252 @url{https://en.wikipedia.org/wiki/Counter_mode#Counter_.28CTR.29, CTR}
255 If @option{-chunked} is specified, then source file will be split
256 @ref{Chunked, on chunks}. @option{INT} is the desired chunk size in
257 KiBs. This mode is more CPU hungry. Pay attention that chunk is saved in
258 spool directory immediately and it is not deleted if any error occurs.
259 @option{-minsize} option is applied per each chunk.
261 If @ref{CfgNotify, notification} is enabled on the remote side for
262 file transmissions, then it will sent simple letter after successful
269 % nncp-freq [options] NODE:SRC [DST]
272 Send file request to @option{NODE}, asking it to send its @file{SRC}
273 file from @ref{CfgFreq, freq} directory to our node under @file{DST}
274 filename in our @ref{CfgIncoming, incoming} one. If @file{DST} is not
275 specified, then last element of @file{SRC} will be used.
277 If @ref{CfgNotify, notification} is enabled on the remote side for
278 file request, then it will sent simple letter after successful file
288 Parse @ref{Log, log} file and print out its records in human-readable form.
294 % nncp-mail [options] NODE USER ...
297 Send mail, that is read from stdin, to @option{NODE} and specified
298 @option{USER}s. Mail message will be compressed. After receiving, remote
299 side will execute specified @ref{CfgSendmail, sendmail} command with
300 @option{USER}s appended as a command line argument and feed decompressed
301 mail body to that command's stdin.
307 % nncp-pkt [options] < pkt
308 % nncp-pkt [options] [-decompress] -dump < pkt > payload
311 Low level packet parser. Normally it should not be used, but can help in
314 By default it will print packet's type, for example:
316 Packet type: encrypted
318 Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ
321 If you specify @option{-dump} option and provide an @ref{Encrypted,
322 encrypted} packet, then it will verify and decrypt it to stdout.
323 Encrypted packets contain @ref{Plain, plain} ones, that also can be fed
324 to @command{nncp-pkt}:
328 Payload type: transitional
329 Path: VHMTRWDOXPLK7BR55ICZ5N32ZJUMRKZEMFNGGCEAXV66GG43PEBQ
333 Path: stargrave@stargrave.org
336 And with the @option{-dump} option it will give you the actual payload
337 (the whole file, mail message, and so on). @option{-decompress} option
338 tries to zlib-decompress the data from plain packet (useful for mail
345 % nncp-reass [options] [-dryrun] [-keep] [-dump] [-stdout] FILE.nncp.meta
346 % nncp-reass [options] [-dryrun] [-keep] {-all | -node NODE}
349 Reassemble @ref{Chunked, chunked file} after @ref{nncp-toss, tossing}.
351 When called with @option{FILE} option, this command will reassemble only
352 it. When called with @option{-node} option, this command will try to
353 reassemble all @file{.nncp.meta} files found in @option{NODE}'s
354 @ref{CfgIncoming, incoming} directory. When called with @option{-all}
355 option, then cycle through all known nodes to do the same.
357 Reassembling process does the following:
360 @item Parses @ref{Chunked, @file{.nncp.meta}} file.
361 @item Checks existence and size of every @file{.nncp.chunkXXX}.
362 @item Verifies integrity of every chunk.
363 @item Concatenates all chunks, simultaneously removing them from filesystem.
366 That process reads the whole data twice. Be sure to have free disk
367 space for at least one chunk. Decrypted chunk files as a rule are saved
368 in pseudo-random order, so removing them during reassembly process will
369 likely lead to filesystem fragmentation. Reassembly process on
370 filesystems with deduplication capability should be rather lightweight.
372 If @option{-dryrun} option is specified, then only existence and
373 integrity checking are performed.
375 If @option{-keep} option is specified, then no
376 @file{.nncp.meta}/@file{.nncp.chunkXXX} files are deleted during
379 @option{-stdout} option outputs reassembled file to stdout, instead of
380 saving to temporary file with renaming after. This could be useful for
381 reassembling on separate filesystem to lower fragmentation effect,
382 and/or separate storage device for higher performance.
384 @option{-dump} option prints meta-file contents in human-friendly form.
385 It is useful mainly for debugging purposes. For example:
387 Original filename: testfile
388 File size: 3.8 MiB (3987795 bytes)
389 Chunk size: 1.0 MiB (1048576 bytes)
392 0: eac60d819edf40b8ecdacd0b9a5a8c62de2d15eef3c8ca719eafa0be9b894017
393 1: 013a07e659f2e353d0e4339c3375c96c7fffaa2fa00875635f440bbc4631052a
394 2: f4f883975a663f2252328707a30e71b2678f933b2f3103db8475b03293e4316e
395 3: 0e9e229501bf0ca42d4aa07393d19406d40b179f3922a3986ef12b41019b45a3
402 % nncp-rm [options] NODE PKT
405 Remove specified packet (Base32 name) in @option{NODE}'s queues. This
406 command is useful when you want to remove the packet that is failing to
413 % nncp-stat [options]
416 Print current @ref{Spool, spool} statistics about unsent and unprocessed
417 packets. For each node and each niceness level there will be printed how
418 many packets (with the total size) are in inbound (Rx) and outbound (Tx)
425 % nncp-toss [options] [-dryrun] [-cycle INT] [-seen]
428 Perform "tossing" operation on all inbound packets. This is the tool
429 that decrypts all packets and processes all payload packets in them:
430 copies files, sends mails, sends out file requests and relays transition
431 packets. It should be run after each online/offline exchange.
433 @option{-dryrun} option does not perform any writing and sending, just
434 tells what it will do.
436 @option{-cycle} option tells not to quit, but to repeat tossing every
437 @option{INT} seconds in an infinite loop. That can be useful when
438 running this command as a daemon.
440 @option{-seen} option creates empty @file{XXX.seen} file after
441 successful tossing of @file{XXX} packet. @ref{nncp-xfer} and
442 @ref{nncp-bundle} commands skip inbound packets that has been already
443 seen, processed and tossed. This is helpful to defeat duplicates.
449 % nncp-xfer [options] [-mkdir] [-keep] [-rx|-tx] DIR
452 Search for directory in @file{DIR} containing inbound packets for us and
453 move them to local @ref{Spool, spool} directory. Also search for known
454 neighbours directories and move locally queued outbound packets to them.
455 This command is used for offline packets transmission.
457 If @option{-mkdir} option is specified, then outbound neighbour(s)
458 directories will be created. This is useful for the first time usage,
459 when storage device does not have any directories tree.
461 If @option{-keep} option is specified, then keep copied files, do not
464 @option{-rx} option tells only to move inbound packets addressed to us.
465 @option{-tx} option tells exactly the opposite: move only outbound packets.
467 @ref{nncp-cfgmin} could be useful for creating stripped minimalistic
468 configuration file version without any private keys.
470 @file{DIR} directory has the following structure:
471 @file{RECIPIENT/SENDER/PACKET}, where @file{RECIPIENT} is Base32 encoded
472 destination node, @file{SENDER} is Base32 encoded sender node.