Vendorizing

[nncp.git] / doc / cmds.texi

diff --git a/doc/cmds.texi b/doc/cmds.texi
index 2606b6ee12bd9e59c67726eb57a93c1ec5c0999a..ae7bd52824db6b5346220341612a1bfa223719ee 100644 (file)
--- a/doc/cmds.texi
+++ b/doc/cmds.texi
@@ -53,10 +53,10 @@ $ nncp-bundle [options] -rx [-check] [-dryrun] [NODE ...] < ...
 
 With @option{-tx} option, this command creates @ref{Bundles, bundle} of
 @ref{Encrypted, encrypted packets} from the spool directory and writes
 
 With @option{-tx} option, this command creates @ref{Bundles, bundle} of
 @ref{Encrypted, encrypted packets} from the spool directory and writes

-it to stdout.
+it to @code{stdout}.

 
 

-With @option{-rx} option, this command takes bundle from stdin and
-copies all found packets for our node to the spool directory. Pay
+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}
 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}


@@ -73,7 +73,7 @@ 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
 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.
+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
 
 But you can verify produced stream after, by digesting it by yourself
 with @option{-rx} and @option{-delete} options -- in that mode, stream


@@ -101,6 +101,7 @@ $ nncp-call [options]
     [-pkts PKT,PKT,...]
     [-rxrate INT]
     [-txrate INT]
     [-pkts PKT,PKT,...]
     [-rxrate INT]
     [-txrate INT]

+    [-autotoss*]

     NODE[:ADDR] [FORCEADDR]
 @end example
 
     NODE[:ADDR] [FORCEADDR]
 @end example
 


@@ -138,6 +139,10 @@ file is renamed from @file{.part} one and when you rerun
 @command{nncp-call} again, remote node will receive completion
 notification.
 
 @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
 
 @node nncp-caller
 @section nncp-caller
 


@@ -152,14 +157,14 @@ Optional number of @option{NODE}s tells to ignore other ones.
 Otherwise all nodes with specified @emph{calls} configuration
 field will be called.
 
 Otherwise all nodes with specified @emph{calls} configuration
 field will be called.
 

-Look @ref{nncp-call} for more information.
+Look at @ref{nncp-call} for more information.

 
 @node nncp-cfgenc
 @section nncp-cfgenc
 
 @example
 
 @node nncp-cfgenc
 @section nncp-cfgenc
 
 @example

-$ nncp-cfgmin [options] [-s INT] [-t INT] [-p INT] cfg.hjson > cfg.hjson.eblob
-$ nncp-cfgmin [options] -d cfg.hjson.eblob > cfg.hjson
+$ 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
 @end example
 
 This command allows you to encrypt provided @file{cfg.hjson} file with


@@ -214,8 +219,8 @@ $ nncp-cfgnew [options] [-nocomments] > new.hjson
 @end example
 
 Generate new node configuration: private keys, example configuration
 @end example
 
 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
+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
 without descriptive huge comments -- useful for advanced users.
 
 Pay attention that private keys generation consumes an entropy from your


@@ -237,7 +242,7 @@ not used often in practice, if ever.
 @section nncp-daemon
 
 @example
 @section nncp-daemon
 
 @example

-$ nncp-daemon [options] [-maxconn INT] [-bind ADDR] [-inetd]
+$ nncp-daemon [options] [-maxconn INT] [-bind ADDR] [-inetd] [-autotoss*]

 @end example
 
 Start listening TCP daemon, wait for incoming connections and run
 @end example
 
 Start listening TCP daemon, wait for incoming connections and run


@@ -250,23 +255,36 @@ 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
 bind to and listen.
 
 It could be run as @command{inetd} service, by specifying

-@option{-inetd} option. Example inetd-entry:
+@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
 
 @verbatim

-uucp   stream  tcp6    nowait  nncpuser        /usr/local/bin/nncp-daemon      nncp-daemon -inetd
+uucp   stream  tcp6    nowait  nncpuser        /usr/local/bin/nncp-daemon      nncp-daemon -quiet -inetd

 @end verbatim
 
 @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.
+

 @node nncp-exec
 @section nncp-exec
 
 @example
 @node nncp-exec
 @section nncp-exec
 
 @example

-$ nncp-exec [options] NODE HANDLE [ARG0 ARG1 ...]
+$ nncp-exec [options] [-use-tmp] [-nocompress] NODE HANDLE [ARG0 ARG1 ...]

 @end example
 
 Send execution command to @option{NODE} for specified @option{HANDLE}.
 @end example
 
 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.
+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:
 
 For example, if remote side has following configuration file for your
 node:


@@ -293,6 +311,9 @@ 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.
 
 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
 
 @node nncp-file
 @section nncp-file
 


@@ -309,16 +330,19 @@ 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.
 
 (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
 If @file{SRC} equals to @file{-}, then create an encrypted temporary

-file and copy everything taken from stdin to it and use for outbound
+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
 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
+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
 for that temporary file and resulting encrypted packet. You can control

-where temporary file will be stored using @env{TMPDIR} environment
+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 splitted on 128 KiB blocks. Each block is encrypted
 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.
+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}
 
 If @file{SRC} points to directory, then
 @url{https://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13_01, pax archive}


@@ -386,7 +410,7 @@ Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ
 @end example
 
 If you specify @option{-dump} option and provide an @ref{Encrypted,
 @end example
 
 If you specify @option{-dump} option and provide an @ref{Encrypted,

-encrypted} packet, then it will verify and decrypt it to stdout.
+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}:
 
 Encrypted packets contain @ref{Plain, plain} ones, that also can be fed
 to @command{nncp-pkt}:
 


@@ -445,10 +469,10 @@ If @option{-keep} option is specified, then no
 @file{.nncp.meta}/@file{.nncp.chunkXXX} files are deleted during
 reassembly process.
 
 @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{-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:
 
 @option{-dump} option prints meta-file contents in human-friendly form.
 It is useful mainly for debugging purposes. For example:


@@ -481,32 +505,44 @@ $ nncp-rm [options] -node NODE -pkt PKT
 This command is aimed to delete various files from your spool directory:
 
 @itemize
 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{-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{-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 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.
 @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.

+
+@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
 @end itemize
 
 @node nncp-stat
 @section nncp-stat
 
 @example

-$ nncp-stat [options] [-node NODE]
+$ 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
 @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.
+size) are in inbound (Rx) and outbound (Tx) queues. @option{-pkt} option
+show information about each packet.

 
 @node nncp-toss
 @section nncp-toss
 
 @node nncp-toss
 @section nncp-toss