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       }
  50       calls: [
  51         {
  52           cron: "*/2 * * * *"
  53         },
  54       ]
  55     }
  56     bob: {
  57       id: 2IZNP...UYGYA
  58       exchpub: WFLMZ...B7NHA
  59       signpub: GTGXG...IE3OA
  60       exec: {
  61         sendmail: ["/usr/sbin/sendmail"]
  62         warcer: ["/path/to/warcer.sh"]
  63         wgeter: ["/path/to/wgeter.sh"]
  64       }
  65       freq: "/home/bob/pub"
  66       freqchunked: 1024
  67       freqminsize: 2048
  68       via: ["alice"]
  69       rxrate: 10
  70       txrate: 20
  71     }
  72   }
  73 }
  74 @end verbatim
  75
  76 @strong{spool} field contains an absolute path to @ref{Spool, spool}
  77 directory. @strong{log} field contains an absolute path to @ref{Log,
  78 log} file.
  79
  80 @anchor{CfgNotify}
  81 @strong{notify} section contains notification settings for successfully
  82 tossed file and freq packets. Corresponding @strong{from} and
  83 @strong{to} fields will be substituted in notification email message.
  84 @emph{neigh/self/exec/sendmail} will be used as a local mailer. You can
  85 omit either of those two @emph{from}/@emph{to} sections to omit
  86 corresponding notifications, or the whole section at once.
  87
  88 @strong{self} section contains our node's private keypairs.
  89 @strong{exch*} and @strong{sign*} are used during @ref{Encrypted,
  90 encrypted} packet creation. @strong{noise*} are used during @ref{Sync,
  91 synchronization protocol} working in @ref{nncp-call}/@ref{nncp-daemon}.
  92
  93 @strong{neigh} section contains all known neighbours information. It
  94 always has @strong{self} neighbour that is copy of our node's public
  95 data (public keys). It is useful for copy-paste sharing with your
  96 friends. Each section's key is a human-readable name of the neighbour.
  97
  98 Except for @emph{id}, @emph{exchpub} and @emph{signpub} each neighbour
  99 node has the following fields:
 100
 101 @table @strong
 102
 103 @item noisepub
 104 If present, then node can be online called using @ref{Sync,
 105 synchronization protocol}. Contains authentication public key.
 106
 107 @anchor{CfgExec}
 108 @item exec
 109 Dictionary consisting of handles and corresponding command line
 110 arguments. In example above there are @command{sendmail} handles,
 111 @command{warcer}, @command{wgeter} and @command{flag} one. Remote node
 112 can queue some handle execution with providing additional command line
 113 arguments and the body fed to command's stdin.
 114
 115 @verb{|sendmail: ["/usr/sbin/sendmail", "-t"]|} handle, when called by
 116 @verb{|echo hello world | nncp-exec OURNODE sendmail ARG0 ARG1 ARG2|}
 117 command, will execute:
 118
 119 @verbatim
 120 echo hello world |
 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 @anchor{CfgIncoming}
 128 @item incoming
 129 Full path to directory where all file uploads will be saved. May be
 130 omitted to forbid file uploading on that node.
 131
 132 @anchor{CfgFreq}
 133 @item freq
 134 Full path to directory from where file requests will queue files for
 135 transmission. May be omitted to forbid freqing from that node.
 136
 137 @item freqchunked
 138 If set, then enable @ref{Chunked, chunked} file transmission during
 139 freqing. This is the desired chunk size in KiBs.
 140
 141 @item freqminsize
 142 If set, then apply @ref{OptMinSize, -minsize} option during file
 143 transmission.
 144
 145 @anchor{CfgVia}
 146 @item via
 147 An array of node identifiers that will be used as a relay to that node.
 148 For example @verb{|[foo,bar]|} means that packet can reach current node
 149 by transitioning through @emph{foo} and then @emph{bar} nodes. May be
 150 omitted if direct connection exists and no relaying is required.
 151
 152 @anchor{CfgAddrs}
 153 @item addrs
 154 Dictionary containing known network addresses of the node. Each key is
 155 human-readable name of the link/address. Values are @verb{|addr:port|}
 156 pairs pointing to @ref{nncp-daemon}'s listening instance. May be omitted
 157 if either no direct connection exists, or @ref{nncp-call} is used with
 158 forced address specifying.
 159
 160 @anchor{CfgXxRate}
 161 @item rxrate/txrate
 162 If greater than zero, then at most *rate packets per second will be
 163 sent/received after the handshake. It could be used as crude bandwidth
 164 traffic shaper: each packet has at most 64 KiB payload size. Could be
 165 omitted at all -- no rate limits.
 166
 167 @anchor{CfgOnlineDeadline}
 168 @item onlinedeadline
 169 Online connection deadline of node inactivity in seconds. It is the time
 170 connection considered dead after not receiving/sending any packets and
 171 node must disconnect. By default it is set to 10 seconds -- that means
 172 disconnecting after 10 seconds when no packets received and transmitted.
 173 This can be set to rather high values to keep connection alive (to
 174 reduce handshake overhead and delays), wait for appearing packets ready
 175 to send and notifying remote side about their appearance.
 176
 177 @anchor{CfgMaxOnlineTime}
 178 @item maxonlinetime
 179 If greater than zero, then it is maximal amount of time connect could be
 180 alive. Forcefully disconnect if it is exceeded.
 181
 182 @anchor{CfgCalls}
 183 @item calls
 184 List of @ref{Call, call configuration}s. Can be omitted if
 185 @ref{nncp-caller} won't be used to call that node.
 186
 187 @end table