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