Fix Texinfo warning about nodes with the dots

[nncp.git] / doc / cfg.texi

diff --git a/doc/cfg.texi b/doc/cfg.texi
index 1a37f10e5678410c3d7523ae311567a62c856e94..30341f888dc160c555939530541d5609f1b11a4f 100644 (file)
--- a/doc/cfg.texi
+++ b/doc/cfg.texi
@@ -1,70 +1,136 @@
 @node Configuration
 @unnumbered Configuration file
 
 @node Configuration
 @unnumbered Configuration file
 

-Example YAML configuration file:
+Example @url{https://hjson.org/, Hjson} configuration file:

 
 @verbatim
 
 @verbatim

-spool: /var/spool/nncp
-log: /var/spool/nncp/log
-notify:
-  file:
-    from: nncp@localhost
-    to: user+file@example.com
-  freq:
-    from: nncp@localhost
-    to: user+freq@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:
+{
+  spool: /var/spool/nncp
+  log: /var/spool/nncp/log
+  umask: "022"
+  noprogress: true
+  nohdr: true
+
+  mcd-listen: ["em0", "igb1"]
+  mcd-send: {em0: 60, igb1: 5}
+
+  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
     id: TIJQL...2NGIA
     exchpub: CYVGQ...PSEWQ

+    exchprv: 65PUY...MPZ3Q

     signpub: 2NMVC...CMH5Q
     signpub: 2NMVC...CMH5Q

+    signprv: 555JD...RGD6Y
+    noiseprv: D62XU...NKYPA

     noisepub: KIBKK...ESM7Q
     noisepub: KIBKK...ESM7Q

-    sendmail: [/usr/sbin/sendmail]
-  alice:
-    id: XJZBK...65IJQ
-    exchpub: MJACJ...FAI6A
-    signpub: T4AFC...N2FRQ
-    noisepub: UBM5K...VI42A
-    sendmail: ["/bin/sh", "-c", "false"]
-    incoming: /home/alice/incoming
-    onlinedeadline: 1800
-    maxonlinetime: 3600
-    addrs:
-      lan: "[fe80::1234%igb0]:5400"
-      internet: alice.com:3389
-    calls:
-      -
-        cron: "*/2 * * * *"
-  bob:
-    id: 2IZNP...UYGYA
-    exchpub: WFLMZ...B7NHA
-    signpub: GTGXG...IE3OA
-    sendmail: [/usr/sbin/sendmail]
-    freq: /home/bob/pub
-    freqchunked: 1024
-    freqminsize: 2048
-    via: [alice]
+  }
+
+  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.
 
 @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{CfgNoHdr}
+@strong{nohdr} option disables @ref{HdrFile, .hdr} files usage.
+
+@anchor{CfgMCDListen}
+@strong{mcd-listen} specifies list of network interfaces
+@ref{nncp-caller} will listen for incoming @ref{MCD} announcements.
+
+@anchor{CfgMCDSend}
+@strong{mcd-send} specifies list of network interfaces, and intervals in
+seconds, where @ref{nncp-daemon} will send @ref{MCD} announcements.
+

 @anchor{CfgNotify}
 @strong{notify} section contains notification settings for successfully
 @anchor{CfgNotify}
 @strong{notify} section contains notification settings for successfully

-tossed file and freq packets. Corresponding @strong{from} and
+tossed file, freq and exec packets. Corresponding @strong{from} and

 @strong{to} fields will be substituted in notification email message.
 @strong{to} fields will be substituted in notification email message.

-@emph{neigh/self/sendmail} will be used as a local mailer. You can omit
-either of those two @emph{from}/@emph{to} sections to omit corresponding
-notifications, or the whole section at once.
+@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,
 
 @strong{self} section contains our node's private keypairs.
 @strong{exch*} and @strong{sign*} are used during @ref{Encrypted,


@@ -76,7 +142,7 @@ 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.
 
 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 @emph{id}, @emph{exchpub} and @emph{signpub} each neighbour
+Except for @code{id}, @code{exchpub} and @code{signpub} each neighbour

 node has the following fields:
 
 @table @strong
 node has the following fields:
 
 @table @strong


@@ -85,11 +151,27 @@ node has the following fields:
 If present, then node can be online called using @ref{Sync,
 synchronization protocol}. Contains authentication public key.
 
 If present, then node can be online called using @ref{Sync,
 synchronization protocol}. Contains authentication public key.
 

-@anchor{CfgSendmail}
-@item sendmail
-An array containing path to executable and its command line arguments
-that is called for mail sending. If it is empty, then no mail processing
-will be performed from that node.
+@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
 
 @anchor{CfgIncoming}
 @item incoming


@@ -97,46 +179,57 @@ Full path to directory where all file uploads will be saved. May be
 omitted to forbid file uploading on that node.
 
 @anchor{CfgFreq}
 omitted to forbid file uploading on that node.
 
 @anchor{CfgFreq}

-@item freq
+@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.
 
 Full path to directory from where file requests will queue files for
 transmission. May be omitted to forbid freqing from that node.
 

-@item freqchunked
+@item freq.chunked

 If set, then enable @ref{Chunked, chunked} file transmission during
 freqing. This is the desired chunk size in KiBs.
 
 If set, then enable @ref{Chunked, chunked} file transmission during
 freqing. This is the desired chunk size in KiBs.
 

-@item freqminsize
+@item freq.minsize

 If set, then apply @ref{OptMinSize, -minsize} option during file
 transmission.
 
 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.
 @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 @emph{foo} and then @emph{bar} nodes. May be
-omitted if direct connection exists and no relaying is required.
+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
 
 @anchor{CfgAddrs}
 @item addrs
 Dictionary containing known network addresses of the node. Each key is

-human-readable name of the link/address. Values are @verb{|addr:port|}
-pairs pointing to @ref{nncp-daemon}'s listening instance. May be omitted
-if either no direct connection exists, or @ref{nncp-call} is used with
-forced address specifying.
+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
 
 @anchor{CfgOnlineDeadline}
 @item onlinedeadline

-Online connection deadline of node inactivity in seconds. It is the time
-connection considered dead after not receiving/sending any packets and
-node must disconnect. By default it is set to 10 seconds -- that means
-disconnecting after 10 seconds when no packets received and transmitted.
-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.
+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
 
 @anchor{CfgMaxOnlineTime}
 @item maxonlinetime

-If greater than zero, then it is maximal amount of time connect could be
-alive. Forcefully disconnect if it is exceeded.
+If greater than zero, then it is maximal time of single connection.
+Forcefully disconnect if it is exceeded.

 
 @anchor{CfgCalls}
 @item calls
 
 @anchor{CfgCalls}
 @item calls