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