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 echo hello world |
 122     NNCP_SELF=OURNODE \
 123     NNCP_SENDER=REMOTE \
 124     NNCP_NICE=64 \
 125     /usr/sbin/sendmail -t ARG0 ARG1 ARG2
 126 @end verbatim
 127
 128 @anchor{CfgIncoming}
 129 @item incoming
 130 Full path to directory where all file uploads will be saved. May be
 131 omitted to forbid file uploading on that node.
 132
 133 @anchor{CfgFreq}
 134 @item freq
 135 Full path to directory from where file requests will queue files for
 136 transmission. May be omitted to forbid freqing from that node.
 137
 138 @item freqchunked
 139 If set, then enable @ref{Chunked, chunked} file transmission during
 140 freqing. This is the desired chunk size in KiBs.
 141
 142 @item freqminsize
 143 If set, then apply @ref{OptMinSize, -minsize} option during file
 144 transmission.
 145
 146 @anchor{CfgVia}
 147 @item via
 148 An array of node identifiers that will be used as a relay to that node.
 149 For example @verb{|[foo,bar]|} means that packet can reach current node
 150 by transitioning through @emph{foo} and then @emph{bar} nodes. May be
 151 omitted if direct connection exists and no relaying is required.
 152
 153 @anchor{CfgAddrs}
 154 @item addrs
 155 Dictionary containing known network addresses of the node. Each key is
 156 human-readable name of the address. For direct TCP connections use
 157 @verb{|host:port|} format, pointing to @ref{nncp-daemon}'s listening
 158 instance. Also you can pipe connection through the external command
 159 using @verb{#|some command#} format. @code{/bin/sh -c "some command"}
 160 will start and its stdin/stdout used as a connection. May be omitted if
 161 either no direct connection exists, or @ref{nncp-call} is used with
 162 forced address specifying.
 163
 164 @anchor{CfgXxRate}
 165 @item rxrate/txrate
 166 If greater than zero, then at most *rate packets per second will be
 167 sent/received after the handshake. It could be used as crude bandwidth
 168 traffic shaper: each packet has at most 64 KiB payload size. Could be
 169 omitted at all -- no rate limits.
 170
 171 @anchor{CfgOnlineDeadline}
 172 @item onlinedeadline
 173 Online connection deadline of node inactivity in seconds. It is the time
 174 connection considered dead after not receiving/sending any packets and
 175 node must disconnect. By default it is set to 10 seconds -- that means
 176 disconnecting after 10 seconds when no packets received and transmitted.
 177 This can be set to rather high values to keep connection alive (to
 178 reduce handshake overhead and delays), wait for appearing packets ready
 179 to send and notifying remote side about their appearance.
 180
 181 @anchor{CfgMaxOnlineTime}
 182 @item maxonlinetime
 183 If greater than zero, then it is maximal amount of time connect could be
 184 alive. Forcefully disconnect if it is exceeded.
 185
 186 @anchor{CfgCalls}
 187 @item calls
 188 List of @ref{Call, call configuration}s. Can be omitted if
 189 @ref{nncp-caller} won't be used to call that node.
 190
 191 @end table