X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fcmds.texi;h=c2107bed94fe2f1157925104767b5899de82b86d;hb=0139e8deda4112d2c3dcd52e0ad72162e54caa03;hp=ce0855a972db3c43334c86f44e7422a0f864de53;hpb=07a0344ed56852bf0570117e504c50e4152a3697;p=nncp.git diff --git a/doc/cmds.texi b/doc/cmds.texi index ce0855a..c2107be 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -17,12 +17,13 @@ Nearly all commands have the following common options: will be 4 KiB (containing file itself and some junk). @item -nice Set desired outgoing packet @ref{Niceness, niceness level}. - 1-255 values are allowed. -@item -node - Process only single specified node. +@item -replynice + Set desired reply packet @ref{Niceness, niceness level}. Only freq + and exec packets look at that niceness level. @item -via Override @ref{CfgVia, via} configuration option for destination node. Specified nodes must be separated with comma: @verb{|NODE1,NODE2|}. + With @verb{|-via -|} you can disable relaying at all. @item -spool Override path to spool directory. May be specified by @env{NNCPSPOOL} environment variable. @@ -43,9 +44,9 @@ Nearly all commands have the following common options: @section nncp-bundle @verbatim -% nncp-bundle [options] -tx [-delete] NODE [NODE ...] > ... -% nncp-bundle [options] -rx -delete [-dryrun] [NODE ...] < ... -% nncp-bundle [options] -rx [-check] [-dryrun] [NODE ...] < ... +$ nncp-bundle [options] -tx [-delete] NODE [NODE ...] > ... +$ nncp-bundle [options] -rx -delete [-dryrun] [NODE ...] < ... +$ nncp-bundle [options] -rx [-check] [-dryrun] [NODE ...] < ... @end verbatim With @option{-tx} option, this command creates @ref{Bundles, bundle} of @@ -78,11 +79,11 @@ 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 -% nncp-bundle -tx ALICE BOB WHATEVER | cdrecord -tao - -% dd if=/dev/cd0 bs=2048 | nncp-bundle -rx -delete +$ nncp-bundle -tx ALICE BOB WHATEVER | cdrecord -tao - +$ dd if=/dev/cd0 bs=2048 | nncp-bundle -rx -delete @end verbatim -@option{-dryrun} option prevents any writing to the spool. This is +@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 their integrity. @@ -90,8 +91,15 @@ their integrity. @section nncp-call @verbatim -% nncp-call [options] [-onlinedeadline INT] [-maxonlinetime INT] [-rx|-tx] - NODE[:ADDR] [FORCEADDR] +$ nncp-call [options] + [-onlinedeadline INT] + [-maxonlinetime INT] + [-rx|-tx] + [-list] + [-pkts PKT,PKT,...] + [-rxrate INT] + [-txrate INT] + NODE[:ADDR] [FORCEADDR] @end verbatim Call (connect to) specified @option{NODE} and run @ref{Sync, @@ -106,13 +114,18 @@ 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}}. +@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. + +You can specify what packets your want to download, by specifying +@option{-pkts} option with comma-separated list of packets identifiers. @node nncp-caller @section nncp-caller @verbatim -% nncp-caller [options] [NODE ...] +$ nncp-caller [options] [NODE ...] @end verbatim Croned daemon that calls remote nodes from time to time, according to @@ -143,11 +156,11 @@ notification. @section nncp-cfgenc @verbatim -% nncp-cfgmin [options] [-s INT] [-t INT] [-p INT] cfg.yaml > cfg.yaml.eblob -% nncp-cfgmin [options] -d cfg.yaml.eblob > cfg.yaml +$ 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 -This command allows you to encrypt provided @file{cfg.yaml} file with +This command allows you to encrypt provided @file{cfg.hjson} file with the passphrase, producing @ref{EBlob, eblob}, to safely keep your configuration file with private keys. This utility was written for users who do not want (or can not) to use either @url{https://gnupg.org/, @@ -171,7 +184,7 @@ if passphrase can not decrypt @file{eblob}. @option{-dump} options parses @file{eblob} and prints parameters used during its creation. For example: @verbatim -% nncp-cfgenc -dump /usr/local/etc/nncp.yaml.eblob +$ nncp-cfgenc -dump /usr/local/etc/nncp.hjson.eblob Strengthening function: Balloon with BLAKE2b-256 Memory space cost: 1048576 bytes Number of rounds: 16 @@ -183,7 +196,7 @@ Blob size: 2494 @section nncp-cfgmin @verbatim -% nncp-cfgmin [options] > stripped.yaml +$ nncp-cfgmin [options] > stripped.hjson @end verbatim Print out stripped configuration version: only path to @ref{Spool, @@ -195,12 +208,13 @@ neighbours, without private keys involving. @section nncp-cfgnew @verbatim -% nncp-cfgnew [options] > new.yaml +$ nncp-cfgnew [options] [-nocomments] > new.hjson @end verbatim 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. +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 operating system. @@ -209,7 +223,7 @@ operating system. @section nncp-check @verbatim -% nncp-check [options] +$ nncp-check [options] @end verbatim Perform @ref{Spool, spool} directory integrity check. Read all files @@ -221,7 +235,7 @@ not used often in practice, if ever. @section nncp-daemon @verbatim -% nncp-daemon [options] [-maxconn INT] [-bind ADDR] +$ nncp-daemon [options] [-maxconn INT] [-bind ADDR] [-inetd] @end verbatim Start listening TCP daemon, wait for incoming connections and run @@ -233,11 +247,52 @@ time to time. 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: + +@verbatim +uucp stream tcp6 nowait nncpuser /usr/local/bin/nncp-daemon nncp-daemon -inetd +@end verbatim + +@node nncp-exec +@section nncp-exec + +@verbatim +$ nncp-exec [options] NODE HANDLE [ARG0 ARG1 ...] +@end verbatim + +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. + +For example, if remote side has following configuration file for your +node: + +@verbatim +exec: { + sendmail: [/usr/sbin/sendmail, "-t"] + appender: ["/bin/sh", "-c", "cat >> /append"] +} +@end verbatim + +then executing @verb{|echo My message | nncp-exec -replynice 123 REMOTE +sendmail root@localhost|} will lead to execution of: + +@verbatim +echo My message | + NNCP_SELF=REMOTE \ + NNCP_SENDER=OurNodeId \ + NNCP_NICE=123 \ + /usr/sbin/sendmail -t root@localhost +@end verbatim + + @node nncp-file @section nncp-file @verbatim -% nncp-file [options] [-chunked INT] SRC NODE:[DST] +$ nncp-file [options] [-chunked INT] SRC NODE:[DST] @end verbatim Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies @@ -252,12 +307,13 @@ This command queues file in @ref{Spool, spool} directory immediately If @file{SRC} equals to @file{-}, then create an encrypted temporary file and copy everything taken from 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 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 variable. -Encryption is performed with @url{https://cr.yp.to/chacha.html, -ChaCha20} algorithm. Data is splitted on 128 KiB blocks. Each block is -encrypted with increasing nonce counter. +taken from 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 +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. If @option{-chunked} is specified, then source file will be split @ref{Chunked, on chunks}. @option{INT} is the desired chunk size in @@ -274,7 +330,7 @@ file receiving. @section nncp-freq @verbatim -% nncp-freq [options] NODE:SRC [DST] +$ nncp-freq [options] NODE:SRC [DST] @end verbatim Send file request to @option{NODE}, asking it to send its @file{SRC} @@ -290,30 +346,18 @@ queuing. @section nncp-log @verbatim -% nncp-log [options] +$ nncp-log [options] @end verbatim Parse @ref{Log, log} file and print out its records in human-readable form. -@node nncp-mail -@section nncp-mail - -@verbatim -% nncp-mail [options] NODE USER ... -@end verbatim - -Send mail, that is read from stdin, to @option{NODE} and specified -@option{USER}s. Mail message will be compressed. After receiving, remote -side will execute specified @ref{CfgSendmail, sendmail} command with -@option{USER}s appended as a command line argument and feed decompressed -mail body to that command's stdin. - @node nncp-pkt @section nncp-pkt @verbatim -% nncp-pkt [options] < pkt -% nncp-pkt [options] [-decompress] -dump < pkt > payload +$ nncp-pkt [options] < pkt +$ nncp-pkt [options] [-decompress] -dump < pkt > payload +$ nncp-pkt -overheads @end verbatim Low level packet parser. Normally it should not be used, but can help in @@ -346,12 +390,14 @@ And with the @option{-dump} option it will give you the actual payload tries to zlib-decompress the data from plain packet (useful for mail packets). +@option{-overheads} options print encrypted, plain and size header overheads. + @node nncp-reass @section nncp-reass @verbatim -% nncp-reass [options] [-dryrun] [-keep] [-dump] [-stdout] FILE.nncp.meta -% nncp-reass [options] [-dryrun] [-keep] {-all | -node NODE} +$ nncp-reass [options] [-dryrun] [-keep] [-dump] [-stdout] FILE.nncp.meta +$ nncp-reass [options] [-dryrun] [-keep] {-all | -node NODE} @end verbatim Reassemble @ref{Chunked, chunked file} after @ref{nncp-toss, tossing}. @@ -409,12 +455,12 @@ Checksums: @section nncp-rm @verbatim -% 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 [-rx] [-tx] -% nncp-rm [options] -node NODE -pkt PKT +$ 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 [-rx] [-tx] +$ nncp-rm [options] -node NODE -pkt PKT @end verbatim This command is aimed to delete various files from your spool directory: @@ -439,19 +485,27 @@ ones. If @option{-seen} option is specified, then delete only @section nncp-stat @verbatim -% nncp-stat [options] +$ nncp-stat [options] [-node NODE] @end verbatim Print current @ref{Spool, spool} statistics about unsent and unprocessed -packets. For each node and each niceness level there will be printed how -many packets (with the total size) are in inbound (Rx) and outbound (Tx) -queues. +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. @node nncp-toss @section nncp-toss @verbatim -% nncp-toss [options] [-dryrun] [-cycle INT] [-seen] +$ nncp-toss [options] + [-node NODE] + [-dryrun] + [-cycle INT] + [-seen] + [-nofile] + [-nofreq] + [-noexec] + [-notrns] @end verbatim Perform "tossing" operation on all inbound packets. This is the tool @@ -467,15 +521,19 @@ tells what it will do. running this command as a daemon. @option{-seen} option creates empty @file{XXX.seen} file after -successful tossing of @file{XXX} packet. @ref{nncp-xfer} and -@ref{nncp-bundle} commands skip inbound packets that has been already -seen, processed and tossed. This is helpful to defeat duplicates. +successful tossing of @file{XXX} packet. @ref{nncp-xfer}, +@ref{nncp-bundle}, @ref{nncp-daemon} and @ref{nncp-call} commands skip +inbound packets that has been already seen, processed and tossed. This +is helpful to prevent duplicates. + +@option{-nofile}, @option{-nofreq}, @option{-noexec}, @option{-notrns} +options allow to disable any kind of packet types processing. @node nncp-xfer @section nncp-xfer @verbatim -% nncp-xfer [options] [-mkdir] [-keep] [-rx|-tx] DIR +$ nncp-xfer [options] [-node NODE] [-mkdir] [-keep] [-rx|-tx] DIR @end verbatim Search for directory in @file{DIR} containing inbound packets for us and