doc/cfg.texi

   1 @node Configuration
   2 @unnumbered Configuration file
   3
   4 Example @url{https://hjson.org/, Hjson} configuration file:
   5
   6 @verbatim
   7 {
   8   spool: /var/spool/nncp
   9   log: /var/spool/nncp/log
  10   umask: "022"
  11   noprogress: true
  12   nohdr: true
  13
  14   mcd-listen: ["em0", "igb1"]
  15   mcd-send: {em0: 60, igb1: 5}
  16
  17   notify: {
  18     file: {
  19       from: nncp@localhost
  20       to: user+file@example.com
  21     }
  22     freq: {
  23       from: nncp@localhost
  24       to: user+freq@example.com
  25     }
  26     exec: {
  27       "*.warcer": {
  28         from: nncp@localhost
  29         to: user+warcer@example.com
  30       }
  31       "eve.warcer": {
  32         from: nncp@localhost
  33         to: user+warcer-overriden@example.com
  34       }
  35     }
  36   }
  37
  38   self: {
  39     id: TIJQL...2NGIA
  40     exchpub: CYVGQ...PSEWQ
  41     exchprv: 65PUY...MPZ3Q
  42     signpub: 2NMVC...CMH5Q
  43     signprv: 555JD...RGD6Y
  44     noiseprv: D62XU...NKYPA
  45     noisepub: KIBKK...ESM7Q
  46   }
  47
  48   neigh: {
  49     self: {
  50       id: TIJQL...2NGIA
  51       exchpub: CYVGQ...PSEWQ
  52       signpub: 2NMVC...CMH5Q
  53       noisepub: KIBKK...ESM7Q
  54       exec: {sendmail: ["/usr/sbin/sendmail"]}
  55     }
  56     alice: {
  57       id: "XJZBK...65IJQ"
  58       exchpub: MJACJ...FAI6A
  59       signpub: T4AFC...N2FRQ
  60       noisepub: UBM5K...VI42A
  61       exec: {flag: ["/usr/bin/touch", "-t"]}
  62       incoming: "/home/alice/incoming"
  63       onlinedeadline: 1800
  64       maxonlinetime: 3600
  65       addrs: {
  66         lan: "[fe80::1234%igb0]:5400"
  67         internet: alice.com:3389
  68         proxied: "|ssh remote.host nncp-daemon -inetd"
  69       }
  70       calls: [
  71         {
  72           cron: "*/2 * * * *"
  73         },
  74       ]
  75     }
  76     bob: {
  77       id: 2IZNP...UYGYA
  78       exchpub: WFLMZ...B7NHA
  79       signpub: GTGXG...IE3OA
  80       exec: {
  81         sendmail: ["/usr/sbin/sendmail"]
  82         warcer: ["/path/to/warcer.sh"]
  83         wgeter: ["/path/to/wgeter.sh"]
  84       }
  85       freq: {
  86         path: "/home/bob/pub"
  87         chunked: 1024
  88         minsize: 2048
  89       }
  90       via: ["alice"]
  91       rxrate: 10
  92       txrate: 20
  93     }
  94   }
  95 }
  96 @end verbatim
  97
  98 @strong{spool} field contains an absolute path to @ref{Spool, spool}
  99 directory. @strong{log} field contains an absolute path to @ref{Log,
 100 log} file.
 101
 102 Non-empty optional @strong{umask} will force all invoked commands to
 103 override their umask to specified octal mask. Useful for using with
 104 @ref{Shared spool, shared spool directories}.
 105
 106 Enabled @strong{noprogress} option disabled progress showing for many
 107 commands by default. You can always force its showing with
 108 @option{-progress} command line option anyway.
 109
 110 @anchor{CfgNoHdr}
 111 @strong{nohdr} option disables @ref{HdrFile, .hdr} files usage.
 112
 113 @anchor{CfgMCDListen}
 114 @strong{mcd-listen} specifies list of network interfaces
 115 @ref{nncp-caller} will listen for incoming @ref{MCD} announcements.
 116
 117 @anchor{CfgMCDSend}
 118 @strong{mcd-send} specifies list of network interfaces, and intervals in
 119 seconds, where @ref{nncp-daemon} will send @ref{MCD} announcements.
 120
 121 @anchor{CfgNotify}
 122 @strong{notify} section contains notification settings for successfully
 123 tossed file, freq and exec packets. Corresponding @strong{from} and
 124 @strong{to} fields will be substituted in notification email message.
 125 @code{neigh.self.exec.sendmail} will be used as a local mailer. You can
 126 omit either of those two @code{from}/@code{to} sections to omit
 127 corresponding notifications, or the whole section at once.
 128
 129 @code{notify.exec} section is a mapping of exec handles and
 130 corresponding @code{from}/@code{to} sections. Each handle has either
 131 @code{NODE.HANDLE} or @code{*.HANDLE} syntax. You can override
 132 notification options for some node with the first type of name.
 133 Handle command's output will be included in notification messages.
 134
 135 @strong{self} section contains our node's private keypairs.
 136 @strong{exch*} and @strong{sign*} are used during @ref{Encrypted,
 137 encrypted} packet creation. @strong{noise*} are used during @ref{Sync,
 138 synchronization protocol} working in @ref{nncp-call}/@ref{nncp-daemon}.
 139
 140 @strong{neigh} section contains all known neighbours information. It
 141 always has @strong{self} neighbour that is copy of our node's public
 142 data (public keys). It is useful for copy-paste sharing with your
 143 friends. Each section's key is a human-readable name of the neighbour.
 144
 145 Except for @code{id}, @code{exchpub} and @code{signpub} each neighbour
 146 node has the following fields:
 147
 148 @table @strong
 149
 150 @item noisepub
 151 If present, then node can be online called using @ref{Sync,
 152 synchronization protocol}. Contains authentication public key.
 153
 154 @anchor{CfgExec}
 155 @item exec
 156 Dictionary consisting of handles and corresponding command line
 157 arguments. In example above there are @command{sendmail} handles,
 158 @command{warcer}, @command{wgeter} and @command{flag} one. Remote node
 159 can queue some handle execution with providing additional command line
 160 arguments and the body fed to command's @code{stdin}.
 161
 162 @verb{|sendmail: ["/usr/sbin/sendmail", "-t"]|} handle, when called by
 163 @verb{|echo hello world | nncp-exec OURNODE sendmail ARG0 ARG1 ARG2|}
 164 command, will execute:
 165
 166 @example
 167 NNCP_SELF=OURNODE \
 168 NNCP_SENDER=REMOTE \
 169 NNCP_NICE=64 \
 170 /usr/sbin/sendmail -t ARG0 ARG1 ARG2
 171 @end example
 172
 173 feeding @verb{|hello world\n|} to that started @command{sendmail}
 174 process.
 175
 176 @anchor{CfgIncoming}
 177 @item incoming
 178 Full path to directory where all file uploads will be saved. May be
 179 omitted to forbid file uploading on that node.
 180
 181 @anchor{CfgFreq}
 182 @item freq.path
 183 Full path to directory from where file requests will queue files for
 184 transmission. May be omitted to forbid freqing from that node.
 185
 186 @item freq.chunked
 187 If set, then enable @ref{Chunked, chunked} file transmission during
 188 freqing. This is the desired chunk size in KiBs.
 189
 190 @item freq.minsize
 191 If set, then apply @ref{OptMinSize, -minsize} option during file
 192 transmission.
 193
 194 @anchor{CfgVia}
 195 @item via
 196 An array of node identifiers that will be used as a relay to that node.
 197 For example @verb{|["foo","bar"]|} means that packet can reach current
 198 node by transitioning through @code{foo} and then @code{bar} nodes. May
 199 be omitted if direct connection exists and no relaying is required.
 200
 201 @anchor{CfgAddrs}
 202 @item addrs
 203 Dictionary containing known network addresses of the node. Each key is
 204 human-readable name of the address. For direct TCP connections use
 205 @verb{|host:port|} format, pointing to @ref{nncp-daemon}'s listening
 206 instance. Also you can pipe connection through the external command
 207 using @verb{#|some command#} format. @code{/bin/sh -c "some command"}
 208 will start and its @code{stdin}/@code{stdout} used as a connection. May
 209 be omitted if either no direct connection exists, or @ref{nncp-call} is
 210 used with forced address specifying.
 211
 212 @anchor{CfgXxRate}
 213 @item rxrate/txrate
 214 If greater than zero, then at most *rate packets per second will be
 215 sent/received after the handshake. It could be used as crude bandwidth
 216 traffic shaper: each packet has at most 64 KiB payload size. Could be
 217 omitted at all -- no rate limits.
 218
 219 @anchor{CfgOnlineDeadline}
 220 @item onlinedeadline
 221 Online connection deadline of nodes inactivity in seconds. It is the
 222 time connection considered dead after not receiving/sending any packets
 223 (except for PINGs) and connection must be terminated. By default it is
 224 set to 10 seconds. This can be set to rather high values to keep
 225 connection alive (to reduce handshake overhead and delays), wait for
 226 appearing packets ready to send and notifying remote side about their
 227 appearance.
 228
 229 @anchor{CfgMaxOnlineTime}
 230 @item maxonlinetime
 231 If greater than zero, then it is maximal time of single connection.
 232 Forcefully disconnect if it is exceeded.
 233
 234 @anchor{CfgCalls}
 235 @item calls
 236 List of @ref{Call, call configuration}s. Can be omitted if
 237 @ref{nncp-caller} won't be used to call that node.
 238
 239 @end table