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