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