]> Cypherpunks.ru repositories - nncp.git/blobdiff - doc/cmds.texi
Encrypted configuration file
[nncp.git] / doc / cmds.texi
index 70586a7aa8d731acf46d58ec09fd9da8ee0352e8..039fc2d1a079383f45339a777e46a113a7a42661 100644 (file)
@@ -5,14 +5,16 @@ Nearly all commands have the following common options:
 
 @table @option
 @item -cfg
 
 @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
 @item -debug
     Print debug messages. Normally this option should not be used.
 @item -minsize
-    Minimal required resulting packet size. 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).
+    @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 @ref{Niceness, niceness level}.
     1-255 values are allowed.
 @item -nice
     Set desired outgoing packet @ref{Niceness, niceness level}.
     1-255 values are allowed.
@@ -81,6 +83,72 @@ 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.
 
+@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
 
 @node nncp-check
 @section nncp-check
 
@@ -90,7 +158,7 @@ notification.
 
 Perform @ref{Spool, spool} directory integrity check. Read all files
 that has Base32-encoded filenames and compare it with recalculated
 
 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 is
+BLAKE2b hash output of their contents. That supplementary command is
 not used often in practice, if ever.
 
 @node nncp-daemon
 not used often in practice, if ever.
 
 @node nncp-daemon
@@ -113,7 +181,7 @@ bind to and listen.
 @section nncp-file
 
 @verbatim
 @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
 @end verbatim
 
 Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies
@@ -129,7 +197,19 @@ 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
 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.
+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
 
 If @ref{CfgNotify, notification} is enabled on the remote side for
 file transmissions, then it will sent simple letter after successful
@@ -172,32 +252,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.
 
 @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
 
 @node nncp-pkt
 @section nncp-pkt
 
@@ -236,6 +290,74 @@ 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).
 
 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
 
 @node nncp-stat
 @section nncp-stat
 
@@ -271,7 +393,7 @@ running this command as a daemon.
 @section nncp-xfer
 
 @verbatim
 @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
 @end verbatim
 
 Search for directory in @file{DIR} containing inbound packets for us and
@@ -279,7 +401,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.
 
 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.
 
 directories will be created. This is useful for the first time usage,
 when storage device does not have any directories tree.
 
@@ -289,20 +411,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.
 
 @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:
 @file{RECIPIENT/SENDER/PACKET}, where @file{RECIPIENT} is Base32 encoded
 destination node, @file{SENDER} is Base32 encoded sender node.
 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.
-
-@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.