Replace YAML with Hjson

[nncp.git] / doc / cmds.texi

diff --git a/doc/cmds.texi b/doc/cmds.texi
index e7090afff73fe4d0d7be71d68bd4937d9602872d..c2107bed94fe2f1157925104767b5899de82b86d 100644 (file)
--- a/doc/cmds.texi
+++ b/doc/cmds.texi
@@ -17,16 +17,13 @@ Nearly all commands have the following common options:
     will be 4 KiB (containing file itself and some junk).
 @item -nice
     Set desired outgoing packet @ref{Niceness, niceness level}.
     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 -replynice
     Set desired reply packet @ref{Niceness, niceness level}. Only freq
 @item -replynice
     Set desired reply packet @ref{Niceness, niceness level}. Only freq

-    and exec packets look at that niceness level. 1-255 values are
-    allowed.
-@item -node
-    Process only single specified node.
+    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|}.
 @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 -spool
     Override path to spool directory. May be specified by
     @env{NNCPSPOOL} environment variable.


@@ -47,9 +44,9 @@ Nearly all commands have the following common options:
 @section nncp-bundle
 
 @verbatim
 @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 ...] < ...
+$ 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
 @end verbatim
 
 With @option{-tx} option, this command creates @ref{Bundles, bundle} of


@@ -82,11 +79,11 @@ 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
 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
+$ nncp-bundle -tx ALICE BOB WHATEVER | cdrecord -tao -
+$ dd if=/dev/cd0 bs=2048 | nncp-bundle -rx -delete

 @end verbatim
 
 @end verbatim
 

-@option{-dryrun} option prevents any writing to the spool. This is
+@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.
 
 useful when you need to see what packets will pass by and possibly check
 their integrity.
 


@@ -94,8 +91,15 @@ their integrity.
 @section nncp-call
 
 @verbatim
 @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,
 @end verbatim
 
 Call (connect to) specified @option{NODE} and run @ref{Sync,


@@ -110,13 +114,18 @@ 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,
 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.

 
 @node nncp-caller
 @section nncp-caller
 
 @verbatim
 
 @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
 @end verbatim
 
 Croned daemon that calls remote nodes from time to time, according to


@@ -147,11 +156,11 @@ notification.
 @section nncp-cfgenc
 
 @verbatim
 @section nncp-cfgenc
 
 @verbatim

-% nncp-cfgmin [options] [-s INT] [-t INT] [-p INT] cfg.yaml > cfg.yaml.eblob
-% nncp-cfgmin [options] -d cfg.yaml.eblob > cfg.yaml
+$ 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
 
 @end verbatim
 

-This command allows you to encrypt provided @file{cfg.yaml} file with
+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/,
 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/,


@@ -175,7 +184,7 @@ if passphrase can not decrypt @file{eblob}.
 @option{-dump} options parses @file{eblob} and prints parameters used
 during its creation. For example:
 @verbatim
 @option{-dump} options parses @file{eblob} and prints parameters used
 during its creation. For example:
 @verbatim

-% nncp-cfgenc -dump /usr/local/etc/nncp.yaml.eblob
+$ nncp-cfgenc -dump /usr/local/etc/nncp.hjson.eblob

 Strengthening function: Balloon with BLAKE2b-256
 Memory space cost: 1048576 bytes
 Number of rounds: 16
 Strengthening function: Balloon with BLAKE2b-256
 Memory space cost: 1048576 bytes
 Number of rounds: 16


@@ -187,7 +196,7 @@ Blob size: 2494
 @section nncp-cfgmin
 
 @verbatim
 @section nncp-cfgmin
 
 @verbatim

-% nncp-cfgmin [options] > stripped.yaml
+$ nncp-cfgmin [options] > stripped.hjson

 @end verbatim
 
 Print out stripped configuration version: only path to @ref{Spool,
 @end verbatim
 
 Print out stripped configuration version: only path to @ref{Spool,


@@ -199,12 +208,13 @@ neighbours, without private keys involving.
 @section nncp-cfgnew
 
 @verbatim
 @section nncp-cfgnew
 
 @verbatim

-% nncp-cfgnew [options] > new.yaml
+$ 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
 @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.
+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.
 
 Pay attention that private keys generation consumes an entropy from your
 operating system.


@@ -213,7 +223,7 @@ operating system.
 @section nncp-check
 
 @verbatim
 @section nncp-check
 
 @verbatim

-% nncp-check [options]
+$ nncp-check [options]

 @end verbatim
 
 Perform @ref{Spool, spool} directory integrity check. Read all files
 @end verbatim
 
 Perform @ref{Spool, spool} directory integrity check. Read all files


@@ -225,7 +235,7 @@ not used often in practice, if ever.
 @section nncp-daemon
 
 @verbatim
 @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
 @end verbatim
 
 Start listening TCP daemon, wait for incoming connections and run


@@ -237,11 +247,18 @@ time to time.
 can handle. @option{-bind} option specifies @option{addr:port} it must
 bind to and listen.
 
 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
 @node nncp-exec
 @section nncp-exec
 
 @verbatim

-% nncp-exec [options] NODE HANDLE [ARG0 ARG1 ...]
+$ nncp-exec [options] NODE HANDLE [ARG0 ARG1 ...]

 @end verbatim
 
 Send execution command to @option{NODE} for specified @option{HANDLE}.
 @end verbatim
 
 Send execution command to @option{NODE} for specified @option{HANDLE}.


@@ -253,13 +270,14 @@ For example, if remote side has following configuration file for your
 node:
 
 @verbatim
 node:
 
 @verbatim

-exec:
+exec: {

   sendmail: [/usr/sbin/sendmail, "-t"]
   appender: ["/bin/sh", "-c", "cat >> /append"]
   sendmail: [/usr/sbin/sendmail, "-t"]
   appender: ["/bin/sh", "-c", "cat >> /append"]

+}

 @end verbatim
 
 then executing @verb{|echo My message | nncp-exec -replynice 123 REMOTE
 @end verbatim
 
 then executing @verb{|echo My message | nncp-exec -replynice 123 REMOTE

-sendmail root@localhost|} will lead to executing of:
+sendmail root@localhost|} will lead to execution of:

 
 @verbatim
 echo My message |
 
 @verbatim
 echo My message |


@@ -274,7 +292,7 @@ echo My message |
 @section nncp-file
 
 @verbatim
 @section nncp-file
 
 @verbatim

-% nncp-file [options] [-chunked INT] SRC NODE:[DST]
+$ nncp-file [options] [-chunked INT] SRC NODE:[DST]

 @end verbatim
 
 Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies
 @end verbatim
 
 Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies


@@ -289,12 +307,13 @@ This command queues file in @ref{Spool, spool} directory immediately
 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
 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 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 with @url{https://cr.yp.to/chacha.html,
-ChaCha20} algorithm. Data is splitted on 128 KiB blocks. Each block is
-encrypted with increasing nonce counter.
+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 @option{-chunked} is specified, then source file will be split
 @ref{Chunked, on chunks}. @option{INT} is the desired chunk size in
 
 If @option{-chunked} is specified, then source file will be split
 @ref{Chunked, on chunks}. @option{INT} is the desired chunk size in


@@ -311,7 +330,7 @@ file receiving.
 @section nncp-freq
 
 @verbatim
 @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}
 @end verbatim
 
 Send file request to @option{NODE}, asking it to send its @file{SRC}


@@ -327,7 +346,7 @@ queuing.
 @section nncp-log
 
 @verbatim
 @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.
 @end verbatim
 
 Parse @ref{Log, log} file and print out its records in human-readable form.


@@ -336,8 +355,9 @@ Parse @ref{Log, log} file and print out its records in human-readable form.
 @section nncp-pkt
 
 @verbatim
 @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
 @end verbatim
 
 Low level packet parser. Normally it should not be used, but can help in


@@ -370,12 +390,14 @@ And with the @option{-dump} option it will give you the actual payload
 tries to zlib-decompress the data from plain packet (useful for mail
 packets).
 
 tries to zlib-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
 @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}
+$ 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}.
 @end verbatim
 
 Reassemble @ref{Chunked, chunked file} after @ref{nncp-toss, tossing}.


@@ -433,12 +455,12 @@ Checksums:
 @section nncp-rm
 
 @verbatim
 @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
+$ 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:
 @end verbatim
 
 This command is aimed to delete various files from your spool directory:


@@ -463,25 +485,26 @@ ones. If @option{-seen} option is specified, then delete only
 @section nncp-stat
 
 @verbatim
 @section nncp-stat
 
 @verbatim

-% nncp-stat [options]
+$ nncp-stat [options] [-node NODE]

 @end verbatim
 
 Print current @ref{Spool, spool} statistics about unsent and unprocessed
 @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
 
 @node nncp-toss
 @section nncp-toss
 
 @verbatim

-% nncp-toss [options]
+$ nncp-toss [options]
+    [-node NODE]

     [-dryrun]
     [-cycle INT]
     [-seen]
     [-nofile]
     [-nofreq]
     [-dryrun]
     [-cycle INT]
     [-seen]
     [-nofile]
     [-nofreq]

-    [-nomail]
+    [-noexec]

     [-notrns]
 @end verbatim
 
     [-notrns]
 @end verbatim
 


@@ -498,18 +521,19 @@ tells what it will do.
 running this command as a daemon.
 
 @option{-seen} option creates empty @file{XXX.seen} file after
 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} and
-@ref{nncp-bundle} commands skip inbound packets that has been already
-seen, processed and tossed. This is helpful to defeat duplicates.
+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{-nomail}, @option{-notrns}
+@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
 options allow to disable any kind of packet types processing.
 
 @node nncp-xfer
 @section nncp-xfer
 
 @verbatim

-% nncp-xfer [options] [-mkdir] [-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
 @end verbatim
 
 Search for directory in @file{DIR} containing inbound packets for us and