X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fcmds.texi;h=665b57629d394f9926f95d1b04f79deabf3c6cb8;hb=0ca5764d9eeff210ebf50d6c2e03fa6cbd173b99;hp=039c9e685ebcd18c2832c106d7c7ff40b12f4477;hpb=1d2ce674b042d07fd9b37a46578c8b62bb0345b7;p=nncp.git diff --git a/doc/cmds.texi b/doc/cmds.texi index 039c9e6..665b576 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -45,18 +45,18 @@ Nearly all commands have the following common options: @node nncp-bundle @section nncp-bundle -@verbatim +@example $ nncp-bundle [options] -tx [-delete] NODE [NODE ...] > ... $ nncp-bundle [options] -rx -delete [-dryrun] [NODE ...] < ... $ nncp-bundle [options] -rx [-check] [-dryrun] [NODE ...] < ... -@end verbatim +@end example 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,17 +73,17 @@ 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 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 +@example $ nncp-bundle -tx ALICE BOB WHATEVER | cdrecord -tao - $ dd if=/dev/cd0 bs=2048 | nncp-bundle -rx -delete -@end verbatim +@end example @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 @@ -92,7 +92,7 @@ their integrity. @node nncp-call @section nncp-call -@verbatim +@example $ nncp-call [options] [-onlinedeadline INT] [-maxonlinetime INT] @@ -101,8 +101,10 @@ $ nncp-call [options] [-pkts PKT,PKT,...] [-rxrate INT] [-txrate INT] + [-autotoss*] + [-nock] NODE[:ADDR] [FORCEADDR] -@end verbatim +@end example Call (connect to) specified @option{NODE} and run @ref{Sync, synchronization} protocol with the @ref{nncp-daemon, daemon} on the @@ -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 -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. + +@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. -You can specify what packets your want to download, by specifying -@option{-pkts} option with comma-separated list of packets identifiers. +@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 @@ -138,12 +142,16 @@ file is renamed from @file{.part} one and when you rerun @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 -@verbatim +@example $ nncp-caller [options] [NODE ...] -@end verbatim +@end example Croned daemon that calls remote nodes from time to time, according to their @ref{CfgCalls, @emph{calls}} configuration field. @@ -152,15 +160,15 @@ Optional number of @option{NODE}s tells to ignore other ones. 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 -@verbatim -$ 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 +@example +$ 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 the passphrase, producing @ref{EBlob, eblob}, to safely keep your @@ -185,21 +193,21 @@ if passphrase can not decrypt @file{eblob}. @option{-dump} options parses @file{eblob} and prints parameters used during its creation. For example: -@verbatim +@example $ nncp-cfgenc -dump /usr/local/etc/nncp.hjson.eblob Strengthening function: Balloon with BLAKE2b-256 Memory space cost: 1048576 bytes Number of rounds: 16 Number of parallel jobs: 2 Blob size: 2494 -@end verbatim +@end example @node nncp-cfgmin @section nncp-cfgmin -@verbatim +@example $ nncp-cfgmin [options] > stripped.hjson -@end verbatim +@end example Print out stripped configuration version: only path to @ref{Spool, spool}, path to log file, neighbours public keys are stayed. This is @@ -209,13 +217,13 @@ neighbours, without private keys involving. @node nncp-cfgnew @section nncp-cfgnew -@verbatim +@example $ nncp-cfgnew [options] [-nocomments] > new.hjson -@end verbatim +@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 @@ -224,21 +232,36 @@ operating system. @node nncp-check @section nncp-check -@verbatim -$ nncp-check [options] -@end verbatim +@example +$ 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 -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 -@verbatim -$ nncp-daemon [options] [-maxconn INT] [-bind ADDR] [-inetd] -@end verbatim +@example +$ nncp-daemon [options] + [-maxconn INT] [-bind ADDR] [-inetd] + [-autotoss*] [-nock] [-mcd-once] +@end example Start listening TCP daemon, wait for incoming connections and run @ref{Sync, synchronization protocol} with each of them. You can run @@ -250,23 +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 -@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 -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 +@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 -@verbatim -$ nncp-exec [options] NODE HANDLE [ARG0 ARG1 ...] -@end verbatim +@example +$ 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 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: @@ -281,24 +322,27 @@ exec: { then executing @verb{|echo My message | nncp-exec -replynice 123 REMOTE sendmail root@localhost|} will lead to execution of: -@verbatim +@example echo My message | NNCP_SELF=REMOTE \ NNCP_SENDER=OurNodeId \ NNCP_NICE=123 \ - /usr/sbin/sendmail -t root@localhost -@end verbatim + /usr/sbin/sendmail -t root@@localhost +@end example 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. +@strong{Pay attention} that packet generated with this command won't be +be chunked. + @node nncp-file @section nncp-file -@verbatim +@example $ nncp-file [options] [-chunked INT] SRC NODE:[DST] -@end verbatim +@end example Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies destination file name in remote's @ref{CfgIncoming, incoming} @@ -309,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. +@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. +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} @@ -344,9 +391,9 @@ file receiving. @node nncp-freq @section nncp-freq -@verbatim +@example $ nncp-freq [options] NODE:SRC [DST] -@end verbatim +@end example Send file request to @option{NODE}, asking it to send its @file{SRC} file from @ref{CfgFreq, freq.path} directory to our node under @file{DST} @@ -357,48 +404,67 @@ If @ref{CfgNotify, notification} is enabled on the remote side for 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 -@verbatim +@example $ nncp-log [options] -@end verbatim +@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 -@verbatim +@example $ nncp-pkt [options] < pkt $ nncp-pkt [options] [-decompress] -dump < pkt > payload $ nncp-pkt -overheads -@end verbatim +@end example Low level packet parser. Normally it should not be used, but can help in debugging. By default it will print packet's type, for example: -@verbatim +@example Packet type: encrypted Niceness: 64 Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ -@end verbatim +@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}: -@verbatim +@example Packet type: plain Payload type: transitional Path: VHMTRWDOXPLK7BR55ICZ5N32ZJUMRKZEMFNGGCEAXV66GG43PEBQ Packet type: plain Payload type: mail -Path: stargrave@stargrave.org -@end verbatim +Path: stargrave@@stargrave.org +@end example And with the @option{-dump} option it will give you the actual payload (the whole file, mail message, and so on). @option{-decompress} option @@ -410,10 +476,10 @@ packets). @node nncp-reass @section nncp-reass -@verbatim +@example $ nncp-reass [options] [-dryrun] [-keep] [-dump] [-stdout] FILE.nncp.meta -$ nncp-reass [options] [-dryrun] [-keep] {-all | -node NODE} -@end verbatim +$ nncp-reass [options] [-dryrun] [-keep] @{-all | -node NODE@} +@end example Reassemble @ref{Chunked, chunked file} after @ref{nncp-toss, tossing}. @@ -445,14 +511,14 @@ 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: -@verbatim +@example Original filename: testfile File size: 3.8 MiB (3987795 bytes) Chunk size: 1.0 MiB (1048576 bytes) @@ -462,56 +528,69 @@ Checksums: 1: 013a07e659f2e353d0e4339c3375c96c7fffaa2fa00875635f440bbc4631052a 2: f4f883975a663f2252328707a30e71b2678f933b2f3103db8475b03293e4316e 3: 0e9e229501bf0ca42d4aa07393d19406d40b179f3922a3986ef12b41019b45a3 -@end verbatim +@end example Do not forget about @ref{ChunkedZFS, possible} ZFS deduplication issues. @node nncp-rm @section nncp-rm -@verbatim +@example $ 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 -nock $ nncp-rm [options] -node NODE [-rx] [-tx] $ nncp-rm [options] -node NODE -pkt PKT -@end verbatim +@end example 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{-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 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 -@verbatim -$ nncp-stat [options] [-node NODE] -@end verbatim +@example +$ 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 -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 -@verbatim +@example $ nncp-toss [options] [-node NODE] [-dryrun] @@ -521,7 +600,7 @@ $ nncp-toss [options] [-nofreq] [-noexec] [-notrns] -@end verbatim +@end example Perform "tossing" operation on all inbound packets. This is the tool that decrypts all packets and processes all payload packets in them: @@ -547,9 +626,9 @@ options allow to disable any kind of packet types processing. @node nncp-xfer @section nncp-xfer -@verbatim +@example $ nncp-xfer [options] [-node NODE] [-mkdir] [-keep] [-rx|-tx] DIR -@end verbatim +@end example Search for directory in @file{DIR} containing inbound packets for us and move them to local @ref{Spool, spool} directory. Also search for known