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