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