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