Vendorizing

[nncp.git] / doc / cmds.texi

diff --git a/doc/cmds.texi b/doc/cmds.texi
index 575807af676e230feda3fd1de28c02383f9088d3..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


@@ -139,8 +139,8 @@ 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} options runs tosser on node's spool after call
-is finished. All @option{-autotoss-*} options is the same as in
+@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
 @ref{nncp-toss} command.
 
 @node nncp-caller


@@ -219,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


@@ -255,16 +255,17 @@ 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. Pay attention that because it uses stdin/stdout,
-it can not effectively work with IO timeouts and connection closing can
-propagate up to 5 minutes in practice. 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
 uucp   stream  tcp6    nowait  nncpuser        /usr/local/bin/nncp-daemon      nncp-daemon -quiet -inetd
 @end verbatim
 
 
 @verbatim
 uucp   stream  tcp6    nowait  nncpuser        /usr/local/bin/nncp-daemon      nncp-daemon -quiet -inetd
 @end verbatim
 

-@option{-autotoss} options runs tosser on node's spool after call
-is finished. All @option{-autotoss-*} options is the same as in
+@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
 @ref{nncp-toss} command.
 
 @node nncp-exec


@@ -275,11 +276,15 @@ $ 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 (either into memory, or into encrypted temporary
-file if @option{-use-tmp} is specified) and compressed (unless
+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*}
 @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 stdin.
+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:


@@ -325,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}


@@ -402,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}:
 


@@ -461,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: