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