X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fcmds.texi;h=dc4b4efc09262714d297ad04d6798ef61098edb9;hb=f194c5efbc8fdf7698e4ec608643720a40bcfa9d;hp=e3c1fd2b1d78039fdb3ef7095ec006dde5229470;hpb=c6fc64da2b9ab1be9cc809b0d455d35998cde45a;p=nncp.git diff --git a/doc/cmds.texi b/doc/cmds.texi index e3c1fd2..dc4b4ef 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -9,11 +9,14 @@ Nearly all commands have the following common options: environment variable. @item -debug Print debug messages. Normally this option should not be used. +@item -minsize + @anchor{OptMinSize} + Minimal required resulting packet size, in KiBs. For example if you + send 2 KiB file and set @option{-minsize 4}, then resulting packet + will be 4 KiB (containing file itself and some junk). @item -nice - Set desired outgoing packet niceness level. 1-255 values are - allowed. Higher value means lower priority. In some commands that - means processing of packets that have equal or lower nice value. - That is used for controlling network QoS. + Set desired outgoing packet @ref{Niceness, niceness level}. + 1-255 values are allowed. @item -node Process only single specified node. @item -quiet @@ -30,7 +33,8 @@ Nearly all commands have the following common options: @section nncp-call @verbatim -% nncp-call [options] [-rx|-tx] NODE[:ADDR] [FORCEADDR] +% nncp-call [options] [-onlinedeadline INT] [-maxonlinetime INT] [-rx|-tx] + NODE[:ADDR] [FORCEADDR] @end verbatim Call (connect to) specified @option{NODE} and run @ref{Sync, @@ -40,22 +44,69 @@ either check for incoming packets, or to send out queued ones. Synchronization protocol allows resuming and bidirectional packets 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. +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}}. + +@node nncp-caller +@section nncp-caller + +@verbatim +% nncp-caller [options] [NODE ...] +@end verbatim + +Croned daemon that calls remote nodes from time to time, according to +their @ref{CfgCalls, @emph{calls}} configuration field. + +Optional number of @option{NODE}s tells to ignore other ones. +Otherwise all nodes with specified @emph{calls} configuration +field will be called. + +@option{-onlinedeadline} overrides @ref{CfgOnlineDeadline, +@emph{onlinedeadline}} configuration option. Each @option{NODE} can contain several uniquely identified -@option{ADDR}esses in @ref{Configuration, configuration} file. If you do +@option{ADDR}esses in @ref{CfgAddrs, configuration} file. If you do not specify the exact one, then all will be tried until the first success. Optionally you can force @option{FORCEADDR} address usage, instead of addresses taken from configuration file. -Pay attention that this command run integrity check for each completely -received packet in the background. This can be time consuming and -connection could be lost during that check time and remote node won't be +Pay attention that this command runs integrity check for each completely +received packet in the background. This can be time consuming. +Connection could be lost during that check and remote node won't be notified that file is done. But after successful integrity check that -file will be renamed from @file{.part} one and when you rerun -@command{nncp-call} again, remote node will receive completion at once. +file is renamed from @file{.part} one and when you rerun +@command{nncp-call} again, remote node will receive completion +notification. + +@node nncp-cfgmin +@section nncp-cfgmin + +@verbatim +% nncp-cfgmin [options] > stripped.yaml +@end verbatim + +Print out stripped configuration version: only path to @ref{Spool, +spool}, path to log file, neighbours public keys are stayed. This is +useful mainly for usage with @ref{nncp-xfer} that has to know only +neighbours, without private keys involving. + +@node nncp-cfgnew +@section nncp-cfgnew + +@verbatim +% nncp-cfgnew [options] > new.yaml +@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. + +Pay attention that private keys generation consumes an entropy from your +operating system. @node nncp-check @section nncp-check @@ -66,7 +117,7 @@ file will be renamed from @file{.part} one and when you rerun 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. This supplementary command are +BLAKE2b hash output of their contents. That supplementary command is not used often in practice, if ever. @node nncp-daemon @@ -89,11 +140,11 @@ bind to and listen. @section nncp-file @verbatim -% nncp-file [options] SRC NODE:[DST] +% nncp-file [options] [-chunked INT] SRC NODE:[DST] @end verbatim Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies -destination file name in remote's @ref{Configuration, incoming} +destination file name in remote's @ref{CfgIncoming, incoming} directory. If this file already exists there, then counter will be appended to it. @@ -101,7 +152,25 @@ 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. -If @ref{Configuration, notification} is enabled on the remote side for +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://www.schneier.com/academic/twofish/, Twofish} algorithm, 256 +bit random key, zero IV, in +@url{https://en.wikipedia.org/wiki/Counter_mode#Counter_.28CTR.29, CTR} +mode. + +If @option{-chunked} is specified, then source file will be split +@ref{Chunked, on chunks}. @option{INT} is the desired chunk size in +KiBs. This mode is more CPU hungry. Pay attention that chunk is saved in +spool directory immediately and it is not deleted if any error occurs. +@option{-minsize} option is applied per each chunk. + +If @ref{CfgNotify, notification} is enabled on the remote side for file transmissions, then it will sent simple letter after successful file receiving. @@ -113,10 +182,10 @@ file receiving. @end verbatim Send file request to @option{NODE}, asking it to send its @file{SRC} -file from @ref{Configuration, freq} directory to our node under -@file{DST} filename in our @ref{Configuration, incoming} one. +file from @ref{CfgFreq, freq} directory to our node under @file{DST} +filename in our @ref{CfgIncoming, incoming} one. -If @ref{Configuration, notification} is enabled on the remote side for +If @ref{CfgNotify, notification} is enabled on the remote side for file request, then it will sent simple letter after successful file queuing. @@ -138,29 +207,16 @@ Parse @ref{Log, log} file and print out its records in human-readable form. 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{Configuration, sendmail} command with +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-newnode -@section nncp-newnode - -@verbatim -% nncp-newnode [options] > mynewnode.yaml -@end verbatim - -Generate new node: private keys, example configuration file and print it -to stdout. You must use this command when you setup the new node. - -Pay attention that private keys generation consumes an entropy from your -operating system. - @node nncp-pkt @section nncp-pkt @verbatim % nncp-pkt [options] < pkt -% nncp-pkt [options] -dump < pkt > payload +% nncp-pkt [options] [-decompress] -dump < pkt > payload @end verbatim Low level packet parser. Normally it should not be used, but can help in @@ -171,7 +227,6 @@ By default it will print packet's type, for example: Packet type: encrypted Niceness: 64 Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ -Payload size: 4.0 MiB (4162852 bytes) @end verbatim If you specify @option{-dump} option and provide an @ref{Encrypted, @@ -190,7 +245,77 @@ Path: stargrave@stargrave.org @end verbatim And with the @option{-dump} option it will give you the actual payload -(the whole file, mail message, and so on). +(the whole file, mail message, and so on). @option{-decompress} option +tries to zlib-decompress the data from plain packet (useful for mail +packets). + +@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} +@end verbatim + +Reassemble @ref{Chunked, chunked file} after @ref{nncp-toss, tossing}. + +When called with @option{FILE} option, this command will reassemble only +it. When called with @option{-node} option, this command will try to +reassemble all @file{.nncp.meta} files found in @option{NODE}'s +@ref{CfgIncoming, incoming} directory. When called with @option{-all} +option, then cycle through all known nodes to do the same. + +Reassembling process does the following: + +@enumerate +@item Parses @ref{Chunked, @file{.nncp.meta}} file. +@item Checks existence and size of every @file{.nncp.chunkXXX}. +@item Verifies integrity of every chunk. +@item Concatenates all chunks, simultaneously removing them from filesystem. +@end enumerate + +That process reads the whole data twice. Be sure to have free disk +space for at least one chunk. Decrypted chunk files as a rule are saved +in pseudo-random order, so removing them during reassembly process will +likely lead to filesystem fragmentation. Reassembly process on +filesystems with deduplication capability should be rather lightweight. + +If @option{-dryrun} option is specified, then only existence and +integrity checking are performed. + +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{-dump} option prints meta-file contents in human-friendly form. +It is useful mainly for debugging purposes. For example: +@verbatim +Original filename: testfile +File size: 3.8 MiB (3987795 bytes) +Chunk size: 1.0 MiB (1048576 bytes) +Number of chunks: 4 +Checksums: + 0: eac60d819edf40b8ecdacd0b9a5a8c62de2d15eef3c8ca719eafa0be9b894017 + 1: 013a07e659f2e353d0e4339c3375c96c7fffaa2fa00875635f440bbc4631052a + 2: f4f883975a663f2252328707a30e71b2678f933b2f3103db8475b03293e4316e + 3: 0e9e229501bf0ca42d4aa07393d19406d40b179f3922a3986ef12b41019b45a3 +@end verbatim + +@node nncp-rm +@section nncp-rm + +@verbatim +% nncp-rm [options] NODE PKT +@end verbatim + +Remove specified packet (Base32 name) in @option{NODE}'s queues. This +command is useful when you want to remove the packet that is failing to +be processed. @node nncp-stat @section nncp-stat @@ -208,7 +333,7 @@ queues. @section nncp-toss @verbatim -% nncp-toss [options] [-dryrun] +% nncp-toss [options] [-dryrun] [-cycle INT] @end verbatim Perform "tossing" operation on all inbound packets. This is the tool @@ -219,11 +344,15 @@ packets. It should be run after each online/offline exchange. @option{-dryrun} option does not perform any writing and sending, just tells what it will do. +@option{-cycle} option tells not to quit, but to repeat tossing every +@option{INT} seconds in an infinite loop. That can be useful when +running this command as a daemon. + @node nncp-xfer @section nncp-xfer @verbatim -% nncp-xfer [options] [-force] [-keep] [-rx|-tx] DIR +% nncp-xfer [options] [-mkdir] [-keep] [-rx|-tx] DIR @end verbatim Search for directory in @file{DIR} containing inbound packets for us and @@ -231,7 +360,7 @@ move them to local @ref{Spool, spool} directory. Also search for known neighbours directories and move locally queued outbound packets to them. This command is used for offline packets transmission. -If @option{-force} option is specified, then outbound neighbour(s) +If @option{-mkdir} option is specified, then outbound neighbour(s) directories will be created. This is useful for the first time usage, when storage device does not have any directories tree. @@ -241,6 +370,9 @@ remove them. @option{-rx} option tells only to move inbound packets addressed to us. @option{-tx} option tells exactly the opposite: move only outbound packets. +@ref{nncp-cfgmin} could be useful for creating stripped minimalistic +configuration file version without any private keys. + @file{DIR} directory has the following structure: @file{RECIPIENT/SENDER/PACKET}, where @file{RECIPIENT} is Base32 encoded destination node, @file{SENDER} is Base32 encoded sender node.