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