X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fcfg.texi;h=3e0b882b0582f7c16792b9ed057e18d1b4c46d07;hb=4c17993ce76c6f1883e6854d826eafd4c33c1594;hp=3f114c52bbc520719402139a3586db81d021847e;hpb=b5e7652459c88eddb78ce31d9abec2e9c76cdd51;p=nncp.git

diff --git a/doc/cfg.texi b/doc/cfg.texi
index 3f114c5..3e0b882 100644
--- a/doc/cfg.texi
+++ b/doc/cfg.texi
@@ -1,4 +1,224 @@
 @node Configuration
 @unnumbered Configuration file
 
-TODO.
+Example @url{https://hjson.org/, Hjson} configuration file:
+
+@verbatim
+{
+  spool: /var/spool/nncp
+  log: /var/spool/nncp/log
+  umask: "022"
+  noprogress: true
+
+  notify: {
+    file: {
+      from: nncp@localhost
+      to: user+file@example.com
+    }
+    freq: {
+      from: nncp@localhost
+      to: user+freq@example.com
+    }
+    exec: {
+      "*.warcer": {
+        from: nncp@localhost
+        to: user+warcer@example.com
+      }
+      "eve.warcer": {
+        from: nncp@localhost
+        to: user+warcer-overriden@example.com
+      }
+    }
+  }
+
+  self: {
+    id: TIJQL...2NGIA
+    exchpub: CYVGQ...PSEWQ
+    exchprv: 65PUY...MPZ3Q
+    signpub: 2NMVC...CMH5Q
+    signprv: 555JD...RGD6Y
+    noiseprv: D62XU...NKYPA
+    noisepub: KIBKK...ESM7Q
+  }
+
+  neigh: {
+    self: {
+      id: TIJQL...2NGIA
+      exchpub: CYVGQ...PSEWQ
+      signpub: 2NMVC...CMH5Q
+      noisepub: KIBKK...ESM7Q
+      exec: {sendmail: ["/usr/sbin/sendmail"]}
+    }
+    alice: {
+      id: "XJZBK...65IJQ"
+      exchpub: MJACJ...FAI6A
+      signpub: T4AFC...N2FRQ
+      noisepub: UBM5K...VI42A
+      exec: {flag: ["/usr/bin/touch", "-t"]}
+      incoming: "/home/alice/incoming"
+      onlinedeadline: 1800
+      maxonlinetime: 3600
+      addrs: {
+        lan: "[fe80::1234%igb0]:5400"
+        internet: alice.com:3389
+        proxied: "|ssh remote.host nncp-daemon -inetd"
+      }
+      calls: [
+        {
+          cron: "*/2 * * * *"
+        },
+      ]
+    }
+    bob: {
+      id: 2IZNP...UYGYA
+      exchpub: WFLMZ...B7NHA
+      signpub: GTGXG...IE3OA
+      exec: {
+        sendmail: ["/usr/sbin/sendmail"]
+        warcer: ["/path/to/warcer.sh"]
+        wgeter: ["/path/to/wgeter.sh"]
+      }
+      freq: {
+        path: "/home/bob/pub"
+        chunked: 1024
+        minsize: 2048
+      }
+      via: ["alice"]
+      rxrate: 10
+      txrate: 20
+    }
+  }
+}
+@end verbatim
+
+@strong{spool} field contains an absolute path to @ref{Spool, spool}
+directory. @strong{log} field contains an absolute path to @ref{Log,
+log} file.
+
+Non-empty optional @strong{umask} will force all invoked commands to
+override their umask to specified octal mask. Useful for using with
+@ref{Shared spool, shared spool directories}.
+
+Enabled @strong{noprogress} option disabled progress showing for many
+commands by default. You can always force its showing with
+@option{-progress} command line option anyway.
+
+@anchor{CfgNotify}
+@strong{notify} section contains notification settings for successfully
+tossed file, freq and exec packets. Corresponding @strong{from} and
+@strong{to} fields will be substituted in notification email message.
+@code{neigh.self.exec.sendmail} will be used as a local mailer. You can
+omit either of those two @code{from}/@code{to} sections to omit
+corresponding notifications, or the whole section at once.
+
+@code{notify.exec} section is a mapping of exec handles and
+corresponding @code{from}/@code{to} sections. Each handle has either
+@code{NODE.HANDLE} or @code{*.HANDLE} syntax. You can override
+notification options for some node with the first type of name.
+Handle command's output will be included in notification messages.
+
+@strong{self} section contains our node's private keypairs.
+@strong{exch*} and @strong{sign*} are used during @ref{Encrypted,
+encrypted} packet creation. @strong{noise*} are used during @ref{Sync,
+synchronization protocol} working in @ref{nncp-call}/@ref{nncp-daemon}.
+
+@strong{neigh} section contains all known neighbours information. It
+always has @strong{self} neighbour that is copy of our node's public
+data (public keys). It is useful for copy-paste sharing with your
+friends. Each section's key is a human-readable name of the neighbour.
+
+Except for @code{id}, @code{exchpub} and @code{signpub} each neighbour
+node has the following fields:
+
+@table @strong
+
+@item noisepub
+If present, then node can be online called using @ref{Sync,
+synchronization protocol}. Contains authentication public key.
+
+@anchor{CfgExec}
+@item exec
+Dictionary consisting of handles and corresponding command line
+arguments. In example above there are @command{sendmail} handles,
+@command{warcer}, @command{wgeter} and @command{flag} one. Remote node
+can queue some handle execution with providing additional command line
+arguments and the body fed to command's @code{stdin}.
+
+@verb{|sendmail: ["/usr/sbin/sendmail", "-t"]|} handle, when called by
+@verb{|echo hello world | nncp-exec OURNODE sendmail ARG0 ARG1 ARG2|}
+command, will execute:
+
+@example
+NNCP_SELF=OURNODE \
+NNCP_SENDER=REMOTE \
+NNCP_NICE=64 \
+/usr/sbin/sendmail -t ARG0 ARG1 ARG2
+@end example
+
+feeding @verb{|hello world\n|} to that started @command{sendmail}
+process.
+
+@anchor{CfgIncoming}
+@item incoming
+Full path to directory where all file uploads will be saved. May be
+omitted to forbid file uploading on that node.
+
+@anchor{CfgFreq}
+@item freq.path
+Full path to directory from where file requests will queue files for
+transmission. May be omitted to forbid freqing from that node.
+
+@item freq.chunked
+If set, then enable @ref{Chunked, chunked} file transmission during
+freqing. This is the desired chunk size in KiBs.
+
+@item freq.minsize
+If set, then apply @ref{OptMinSize, -minsize} option during file
+transmission.
+
+@anchor{CfgVia}
+@item via
+An array of node identifiers that will be used as a relay to that node.
+For example @verb{|["foo","bar"]|} means that packet can reach current
+node by transitioning through @code{foo} and then @code{bar} nodes. May
+be omitted if direct connection exists and no relaying is required.
+
+@anchor{CfgAddrs}
+@item addrs
+Dictionary containing known network addresses of the node. Each key is
+human-readable name of the address. For direct TCP connections use
+@verb{|host:port|} format, pointing to @ref{nncp-daemon}'s listening
+instance. Also you can pipe connection through the external command
+using @verb{#|some command#} format. @code{/bin/sh -c "some command"}
+will start and its @code{stdin}/@code{stdout} used as a connection. May
+be omitted if either no direct connection exists, or @ref{nncp-call} is
+used with forced address specifying.
+
+@anchor{CfgXxRate}
+@item rxrate/txrate
+If greater than zero, then at most *rate packets per second will be
+sent/received after the handshake. It could be used as crude bandwidth
+traffic shaper: each packet has at most 64 KiB payload size. Could be
+omitted at all -- no rate limits.
+
+@anchor{CfgOnlineDeadline}
+@item onlinedeadline
+Online connection deadline of nodes inactivity in seconds. It is the
+time connection considered dead after not receiving/sending any packets
+(except for PINGs) and connection must be terminated. By default it is
+set to 10 seconds. This can be set to rather high values to keep
+connection alive (to reduce handshake overhead and delays), wait for
+appearing packets ready to send and notifying remote side about their
+appearance.
+
+@anchor{CfgMaxOnlineTime}
+@item maxonlinetime
+If greater than zero, then it is maximal time of single connection.
+Forcefully disconnect if it is exceeded.
+
+@anchor{CfgCalls}
+@item calls
+List of @ref{Call, call configuration}s. Can be omitted if
+@ref{nncp-caller} won't be used to call that node.
+
+@end table