doc/cfg.texi

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