X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fcmds.texi;h=f1a029aabb6fa6b246e19d2afc9da563a2ecc5c8;hb=6d771479c630cc44a3873ded16ce24f75aadf0fe;hp=2426e33414a61e9bc85f4f6a0f7d7c99ef71950a;hpb=048ebed8b9a42ec907c6b6073d07905126319b2e;p=nncp.git diff --git a/doc/cmds.texi b/doc/cmds.texi index 2426e33..f1a029a 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -5,15 +5,16 @@ Nearly all commands have the following common options: @table @option @item -cfg - Path to configuration file. May be overrided by @env{NNCPCFG} - environment variable. + Path to configuration file. May be overridden by @env{NNCPCFG} + environment variable. If file file is an encrypted @ref{EBlob, + eblob}, then ask for passphrase to decrypt it first. @item -debug Print debug messages. Normally this option should not be used. @item -minsize @anchor{OptMinSize} - Minimal required resulting packet size, in bytes. For example if you - send 2 KiB file and set @option{-minsize 4096}, then resulting - packet will be 4 KiB (containing file itself and some junk). + 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 @ref{Niceness, niceness level}. 1-255 values are allowed. @@ -29,6 +30,49 @@ Nearly all commands have the following common options: Print warranty information (no warranty). @end table +@node nncp-bundle +@section nncp-bundle + +@verbatim +% nncp-bundle [options] -tx [-delete] NODE [NODE ...] > ... +% nncp-bundle [options] -rx -delete [NODE ...] < ... +% nncp-bundle [options] -rx [-check] [NODE ...] < ... +@end verbatim + +With @option{-tx} option, this command creates @ref{Bundles, bundle} of +@ref{Encrypted, encrypted packets} from the spool directory and writes +it to stdout. + +With @option{-rx} option, this command takes bundle from 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} +received packets at the place, it is advised to run @ref{nncp-check} +utility for packets integrity verification, or use @option{-check} +option to enable on the fly integrity check. + +You can specify multiple @option{NODE} arguments, telling for what nodes +you want to create the stream, or take it from. If no nodes are +specified for @option{-rx} mode, then all packets aimed at us will be +processed. + +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. + +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 +% nncp-bundle -tx ALICE BOB WHATEVER | cdrecord -tao - +% dd if=/dev/cd0 bs=2048 | nncp-bundle -rx -delete +@end verbatim + @node nncp-call @section nncp-call @@ -82,6 +126,72 @@ file is renamed from @file{.part} one and when you rerun @command{nncp-call} again, remote node will receive completion notification. +@node nncp-cfgenc +@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 +@end verbatim + +This command allows you to encrypt provided @file{cfg.yaml} 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/, +GnuPG} or similar tools. That @file{eblob} file can be used directly in +@option{-cfg} option of nearly all commands. + +@option{-s}, @option{-t}, @option{-p} are used to tune @file{eblob}'s +password strengthening function. Space memory cost (@option{-s}), +specified in number of BLAKE2b-256 blocks (32 bytes), tells how many +memory must be used for hashing -- bigger values are better, but slower. +Time cost (@option{-t}) tells how many rounds/iterations must be +performed -- bigger is better, but slower. Number of parallel jobs +(@option{-p}) tells how many computation processes will be run: this is +the same as running that number of independent hashers and then joining +their result together. + +When invoked for encryption, passphrase is entered manually twice. When +invoked for decryption (@option{-d} option), it is asked once and exits +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 +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 + +@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 @@ -132,6 +242,11 @@ 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 @@ -147,12 +262,13 @@ 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} file from @ref{CfgFreq, freq} directory to our node under @file{DST} -filename in our @ref{CfgIncoming, incoming} one. +filename in our @ref{CfgIncoming, incoming} one. If @file{DST} is not +specified, then last element of @file{SRC} will be used. If @ref{CfgNotify, notification} is enabled on the remote side for file request, then it will sent simple letter after successful file @@ -180,32 +296,6 @@ 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-mincfg -@section nncp-mincfg - -@verbatim -% nncp-mincfg [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-newcfg -@section nncp-newcfg - -@verbatim -% nncp-newcfg [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-pkt @section nncp-pkt @@ -347,7 +437,7 @@ running this command as a daemon. @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 @@ -355,7 +445,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. @@ -365,7 +455,7 @@ 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-mincfg} could be useful for creating stripped minimalistic +@ref{nncp-cfgmin} could be useful for creating stripped minimalistic configuration file version without any private keys. @file{DIR} directory has the following structure: