MTH

[nncp.git] / doc / cmds.texi

diff --git a/doc/cmds.texi b/doc/cmds.texi
index c4c6d01f6de38728823a29473b875336320871ab..665b57629d394f9926f95d1b04f79deabf3c6cb8 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,8 @@ $ nncp-call [options]
     [-pkts PKT,PKT,...]
     [-rxrate INT]
     [-txrate INT]
     [-pkts PKT,PKT,...]
     [-rxrate INT]
     [-txrate INT]

+    [-autotoss*]
+    [-nock]

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


@@ -113,15 +115,17 @@ transfer.
 
 If @option{-rx} option is specified then only inbound packets
 transmission is performed. If @option{-tx} option is specified, then
 
 If @option{-rx} option is specified then only inbound packets
 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,
-@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.
+only outbound transmission is performed.

 
 

-You can specify what packets your want to download, by specifying
-@option{-pkts} option with comma-separated list of packets identifiers.
+@option{-onlinedeadline} overrides @ref{CfgOnlineDeadline, @emph{onlinedeadline}}.
+@option{-maxonlinetime} overrides @ref{CfgMaxOnlineTime, @emph{maxonlinetime}}.
+@option{-rxrate}/@option{-txrate} override @ref{CfgXxRate, rxrate/txrate}.
+Read @ref{CfgNoCK, more} about @option{-nock} option.
+
+@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.

 
 Each @option{NODE} can contain several uniquely identified
 @option{ADDR}esses in @ref{CfgAddrs, configuration} file. If you do
 
 Each @option{NODE} can contain several uniquely identified
 @option{ADDR}esses in @ref{CfgAddrs, configuration} file. If you do


@@ -138,6 +142,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 +160,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 +222,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


@@ -225,19 +233,34 @@ operating system.
 @section nncp-check
 
 @example
 @section nncp-check
 
 @example

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

 @end example
 
 Perform @ref{Spool, spool} directory integrity check. Read all files
 that has Base32-encoded filenames and compare it with recalculated
 @end example
 
 Perform @ref{Spool, spool} directory integrity check. Read all files
 that has Base32-encoded filenames and compare it with recalculated

-BLAKE2b hash output of their contents. That supplementary command is
-not used often in practice, if ever.
+@ref{MTH} hash output of their contents.
+
+The most useful mode of operation is with @option{-nock} option, that
+checks integrity of @file{.nock} files, renaming them to ordinary
+(verified) encrypted packets.
+
+@node nncp-cronexpr
+@section nncp-cronexpr
+
+@example
+$ nncp-cronexpr -num 12 "*/1 * * * * SAT,SUN 2021"
+@end example
+
+Check validity of specified @ref{CronExpr, cron expression} and print 12
+next time entities.

 
 @node nncp-daemon
 @section nncp-daemon
 
 @example
 
 @node nncp-daemon
 @section nncp-daemon
 
 @example

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

 @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,25 +273,41 @@ 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} 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.
+
+Read @ref{CfgNoCK, more} about @option{-nock} option.
+
+@option{-mcd-once} option sends @ref{MCD} announcements once and quits.
+Could be useful with inetd-based setup, where daemons are not running.
+

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


@@ -295,6 +334,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
 


@@ -311,16 +353,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}
 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.
+algorithms. Data is divided on 128 KiB blocks. Each block is encrypted
+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}


@@ -359,6 +404,24 @@ If @ref{CfgNotify, notification} is enabled on the remote side for
 file request, then it will sent simple letter after successful file
 queuing.
 
 file request, then it will sent simple letter after successful file
 queuing.
 

+@node nncp-hash
+@section nncp-hash
+
+@example
+$ nncp-log [-file ...] [-seek X] [-debug] [-progress]
+@end example
+
+Calculate @ref{MTH} hash of either stdin, or @option{-file} if
+specified.
+
+You can optionally force seeking the file first, reading only part of
+the file, and then prepending unread portion of data, with the
+@option{-seek} option. It is intended only for testing and debugging of
+MTH hasher capabilities.
+
+@option{-debug} option shows all intermediate MTH hashes.
+And @option{-progress} will show progress bar.
+

 @node nncp-log
 @section nncp-log
 
 @node nncp-log
 @section nncp-log
 


@@ -366,7 +429,8 @@ queuing.
 $ nncp-log [options]
 @end example
 
 $ nncp-log [options]
 @end example
 

-Parse @ref{Log, log} file and print out its records in human-readable form.
+Parse @ref{Log, log} file and print out its records in short
+human-readable form.

 
 @node nncp-pkt
 @section nncp-pkt
 
 @node nncp-pkt
 @section nncp-pkt


@@ -388,7 +452,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}:
 


@@ -447,10 +511,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:


@@ -476,6 +540,7 @@ $ nncp-rm [options] -tmp
 $ nncp-rm [options] -lock
 $ nncp-rm [options] -node NODE -part
 $ nncp-rm [options] -node NODE -seen
 $ nncp-rm [options] -lock
 $ nncp-rm [options] -node NODE -part
 $ nncp-rm [options] -node NODE -seen

+$ nncp-rm [options] -node NODE -nock

 $ nncp-rm [options] -node NODE [-rx] [-tx]
 $ nncp-rm [options] -node NODE -pkt PKT
 @end example
 $ nncp-rm [options] -node NODE [-rx] [-tx]
 $ nncp-rm [options] -node NODE -pkt PKT
 @end example


@@ -483,32 +548,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
 @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.
+(maybe both of them), then delete all packets from that given queues.
+@option{-part} option deletes @file{.part}ly downloaded files.
+@option{-seen} option deletes @file{.seen} files. @option{-nock} option
+deletes non-checksummed (non-verified) @file{.nock} 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