doc/cmds.texi

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