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