X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fcmds.texi;h=ae7bd52824db6b5346220341612a1bfa223719ee;hb=d182e82482b61ac3b0e9e0005ca7a018acf899f1;hp=575807af676e230feda3fd1de28c02383f9088d3;hpb=1aebea616a9218d0bc8b4fffa10aa2f49c8d071b;p=nncp.git diff --git a/doc/cmds.texi b/doc/cmds.texi index 575807a..ae7bd52 100644 --- 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 -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} @@ -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 -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 @@ -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. -@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 @@ -219,8 +219,8 @@ $ nncp-cfgnew [options] [-nocomments] > new.hjson @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 @@ -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 -@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 -@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 @@ -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}. -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*} -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: @@ -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. +@anchor{StdinTmpFile} 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 -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 -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 -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} @@ -402,7 +410,7 @@ Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ @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}: @@ -461,10 +469,10 @@ If @option{-keep} option is specified, then no @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: