doc/cmds.texi

   1 @node Commands
   2 @unnumbered Commands
   3
   4 Nearly all commands have the following common options:
   5
   6 @table @option
   7 @item -cfg
   8     Path to configuration file. May be overrided by @env{NNCPCFG}
   9     environment variable.
  10 @item -debug
  11     Print debug messages. Normally this option should not be used.
  12 @item -minsize
  13     Minimal required resulting packet size. For example if you send 2
  14     KiB file and set @option{-minsize 4096}, then resulting packet will
  15     be 4 KiB (containing file itself and some junk).
  16 @item -nice
  17     Set desired outgoing packet @ref{Niceness, niceness level}.
  18     1-255 values are allowed.
  19 @item -node
  20     Process only single specified node.
  21 @item -quiet
  22     Print only errors, omit simple informational messages. In any case
  23     those messages are logged, so you can reread them using
  24     @ref{nncp-log} command.
  25 @item -version
  26     Print version information.
  27 @item -warranty
  28     Print warranty information (no warranty).
  29 @end table
  30
  31 @node nncp-call
  32 @section nncp-call
  33
  34 @verbatim
  35 % nncp-call [options] [-onlinedeadline INT] [-maxonlinetime INT] [-rx|-tx]
  36                       NODE[:ADDR] [FORCEADDR]
  37 @end verbatim
  38
  39 Call (connect to) specified @option{NODE} and run @ref{Sync,
  40 synchronization} protocol with the @ref{nncp-daemon, daemon} on the
  41 remote side. Normally this command could be run any time you wish to
  42 either check for incoming packets, or to send out queued ones.
  43 Synchronization protocol allows resuming and bidirectional packets
  44 transfer.
  45
  46 If @option{-rx} option is specified then only inbound packets
  47 transmission is performed. If @option{-tx} option is specified, then
  48 only outbound transmission is performed. @option{-onlinedeadline}
  49 overrides @ref{CfgOnlineDeadline, @emph{onlinedeadline}}.
  50 @option{-maxonlinetime} overrides @ref{CfgMaxOnlineTime,
  51 @emph{maxonlinetime}}.
  52
  53 @node nncp-caller
  54 @section nncp-caller
  55
  56 @verbatim
  57 % nncp-caller [options] [NODE ...]
  58 @end verbatim
  59
  60 Croned daemon that calls remote nodes from time to time, according to
  61 their @ref{CfgCalls, @emph{calls}} configuration field.
  62
  63 Optional number of @option{NODE}s tells to ignore other ones.
  64 Otherwise all nodes with specified @emph{calls} configuration
  65 field will be called.
  66
  67 @option{-onlinedeadline} overrides @ref{CfgOnlineDeadline,
  68 @emph{onlinedeadline}} configuration option.
  69
  70 Each @option{NODE} can contain several uniquely identified
  71 @option{ADDR}esses in @ref{CfgAddrs, configuration} file. If you do
  72 not specify the exact one, then all will be tried until the first
  73 success. Optionally you can force @option{FORCEADDR} address usage,
  74 instead of addresses taken from configuration file.
  75
  76 Pay attention that this command runs integrity check for each completely
  77 received packet in the background. This can be time consuming.
  78 Connection could be lost during that check and remote node won't be
  79 notified that file is done. But after successful integrity check that
  80 file is renamed from @file{.part} one and when you rerun
  81 @command{nncp-call} again, remote node will receive completion
  82 notification.
  83
  84 @node nncp-check
  85 @section nncp-check
  86
  87 @verbatim
  88 % nncp-check [options]
  89 @end verbatim
  90
  91 Perform @ref{Spool, spool} directory integrity check. Read all files
  92 that has Base32-encoded filenames and compare it with recalculated
  93 BLAKE2b hash output of their contents. This supplementary command is
  94 not used often in practice, if ever.
  95
  96 @node nncp-daemon
  97 @section nncp-daemon
  98
  99 @verbatim
 100 % nncp-daemon [options] [-maxconn INT] [-bind ADDR]
 101 @end verbatim
 102
 103 Start listening TCP daemon, wait for incoming connections and run
 104 @ref{Sync, synchronization protocol} with each of them. You can run
 105 @ref{nncp-toss} utility in background to process inbound packets from
 106 time to time.
 107
 108 @option{-maxconn} option specifies how many simultaneous clients daemon
 109 can handle. @option{-bind} option specifies @option{addr:port} it must
 110 bind to and listen.
 111
 112 @node nncp-file
 113 @section nncp-file
 114
 115 @verbatim
 116 % nncp-file [options] SRC NODE:[DST]
 117 @end verbatim
 118
 119 Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies
 120 destination file name in remote's @ref{CfgIncoming, incoming}
 121 directory. If this file already exists there, then counter will be
 122 appended to it.
 123
 124 This command queues file in @ref{Spool, spool} directory immediately
 125 (through the temporary file of course) -- so pay attention that sending
 126 2 GiB file will create 2 GiB outbound encrypted packet.
 127
 128 If @ref{CfgNotify, notification} is enabled on the remote side for
 129 file transmissions, then it will sent simple letter after successful
 130 file receiving.
 131
 132 @node nncp-freq
 133 @section nncp-freq
 134
 135 @verbatim
 136 % nncp-freq [options] NODE:SRC DST
 137 @end verbatim
 138
 139 Send file request to @option{NODE}, asking it to send its @file{SRC}
 140 file from @ref{CfgFreq, freq} directory to our node under @file{DST}
 141 filename in our @ref{CfgIncoming, incoming} one.
 142
 143 If @ref{CfgNotify, notification} is enabled on the remote side for
 144 file request, then it will sent simple letter after successful file
 145 queuing.
 146
 147 @node nncp-log
 148 @section nncp-log
 149
 150 @verbatim
 151 % nncp-log [options]
 152 @end verbatim
 153
 154 Parse @ref{Log, log} file and print out its records in human-readable form.
 155
 156 @node nncp-mail
 157 @section nncp-mail
 158
 159 @verbatim
 160 % nncp-mail [options] NODE USER ...
 161 @end verbatim
 162
 163 Send mail, that is read from stdin, to @option{NODE} and specified
 164 @option{USER}s. Mail message will be compressed. After receiving, remote
 165 side will execute specified @ref{CfgSendmail, sendmail} command with
 166 @option{USER}s appended as a command line argument and feed decompressed
 167 mail body to that command's stdin.
 168
 169 @node nncp-newnode
 170 @section nncp-newnode
 171
 172 @verbatim
 173 % nncp-newnode [options] > mynewnode.yaml
 174 @end verbatim
 175
 176 Generate new node: private keys, example configuration file and print it
 177 to stdout. You must use this command when you setup the new node.
 178
 179 Pay attention that private keys generation consumes an entropy from your
 180 operating system.
 181
 182 @node nncp-pkt
 183 @section nncp-pkt
 184
 185 @verbatim
 186 % nncp-pkt [options] < pkt
 187 % nncp-pkt [options] [-decompress] -dump < pkt > payload
 188 @end verbatim
 189
 190 Low level packet parser. Normally it should not be used, but can help in
 191 debugging.
 192
 193 By default it will print packet's type, for example:
 194 @verbatim
 195 Packet type: encrypted
 196 Niceness: 64
 197 Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ
 198 @end verbatim
 199
 200 If you specify @option{-dump} option and provide an @ref{Encrypted,
 201 encrypted} packet, then it will verify and decrypt it to stdout.
 202 Encrypted packets contain @ref{Plain, plain} ones, that also can be fed
 203 to @command{nncp-pkt}:
 204
 205 @verbatim
 206 Packet type: plain
 207 Payload type: transitional
 208 Path: VHMTRWDOXPLK7BR55ICZ5N32ZJUMRKZEMFNGGCEAXV66GG43PEBQ
 209
 210 Packet type: plain
 211 Payload type: mail
 212 Path: stargrave@stargrave.org
 213 @end verbatim
 214
 215 And with the @option{-dump} option it will give you the actual payload
 216 (the whole file, mail message, and so on). @option{-decompress} option
 217 tries to zlib-decompress the data from plain packet (useful for mail
 218 packets).
 219
 220 @node nncp-stat
 221 @section nncp-stat
 222
 223 @verbatim
 224 % nncp-stat [options]
 225 @end verbatim
 226
 227 Print current @ref{Spool, spool} statistics about unsent and unprocessed
 228 packets. For each node and each niceness level there will be printed how
 229 many packets (with the total size) are in inbound (Rx) and outbound (Tx)
 230 queues.
 231
 232 @node nncp-toss
 233 @section nncp-toss
 234
 235 @verbatim
 236 % nncp-toss [options] [-dryrun] [-cycle INT]
 237 @end verbatim
 238
 239 Perform "tossing" operation on all inbound packets. This is the tool
 240 that decrypts all packets and processes all payload packets in them:
 241 copies files, sends mails, sends out file requests and relays transition
 242 packets. It should be run after each online/offline exchange.
 243
 244 @option{-dryrun} option does not perform any writing and sending, just
 245 tells what it will do.
 246
 247 @option{-cycle} option tells not to quit, but to repeat tossing every
 248 @option{INT} seconds in an infinite loop. That can be useful when
 249 running this command as a daemon.
 250
 251 @node nncp-xfer
 252 @section nncp-xfer
 253
 254 @verbatim
 255 % nncp-xfer [options] [-force] [-keep] [-rx|-tx] DIR
 256 @end verbatim
 257
 258 Search for directory in @file{DIR} containing inbound packets for us and
 259 move them to local @ref{Spool, spool} directory. Also search for known
 260 neighbours directories and move locally queued outbound packets to them.
 261 This command is used for offline packets transmission.
 262
 263 If @option{-force} option is specified, then outbound neighbour(s)
 264 directories will be created. This is useful for the first time usage,
 265 when storage device does not have any directories tree.
 266
 267 If @option{-keep} option is specified, then keep copied files, do not
 268 remove them.
 269
 270 @option{-rx} option tells only to move inbound packets addressed to us.
 271 @option{-tx} option tells exactly the opposite: move only outbound packets.
 272
 273 @file{DIR} directory has the following structure:
 274 @file{RECIPIENT/SENDER/PACKET}, where @file{RECIPIENT} is Base32 encoded
 275 destination node, @file{SENDER} is Base32 encoded sender node.