Operations progress

[nncp.git] / doc / cfg.texi

diff --git a/doc/cfg.texi b/doc/cfg.texi
index 2004073c98245043e085194be51f211399b17d1f..694445130ae11eeb75b7ea30ec297797a49b2229 100644 (file)
--- a/doc/cfg.texi
+++ b/doc/cfg.texi
@@ -7,6 +7,9 @@ Example @url{https://hjson.org/, Hjson} configuration file:
 {
   spool: /var/spool/nncp
   log: /var/spool/nncp/log
 {
   spool: /var/spool/nncp
   log: /var/spool/nncp/log

+  umask: "022"
+  noprogress: true
+

   notify: {
     file: {
       from: nncp@localhost
   notify: {
     file: {
       from: nncp@localhost


@@ -16,7 +19,18 @@ Example @url{https://hjson.org/, Hjson} configuration file:
       from: nncp@localhost
       to: user+freq@example.com
     }
       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
   self: {
     id: TIJQL...2NGIA
     exchpub: CYVGQ...PSEWQ


@@ -26,6 +40,7 @@ Example @url{https://hjson.org/, Hjson} configuration file:
     noiseprv: D62XU...NKYPA
     noisepub: KIBKK...ESM7Q
   }
     noiseprv: D62XU...NKYPA
     noisepub: KIBKK...ESM7Q
   }

+

   neigh: {
     self: {
       id: TIJQL...2NGIA
   neigh: {
     self: {
       id: TIJQL...2NGIA


@@ -46,6 +61,7 @@ Example @url{https://hjson.org/, Hjson} configuration file:
       addrs: {
         lan: "[fe80::1234%igb0]:5400"
         internet: alice.com:3389
       addrs: {
         lan: "[fe80::1234%igb0]:5400"
         internet: alice.com:3389

+        proxied: "|ssh remote.host nncp-daemon -inetd"

       }
       calls: [
         {
       }
       calls: [
         {


@@ -62,9 +78,11 @@ Example @url{https://hjson.org/, Hjson} configuration file:
         warcer: ["/path/to/warcer.sh"]
         wgeter: ["/path/to/wgeter.sh"]
       }
         warcer: ["/path/to/warcer.sh"]
         wgeter: ["/path/to/wgeter.sh"]
       }

-      freq: "/home/bob/pub"
-      freqchunked: 1024
-      freqminsize: 2048
+      freq: {
+        path: "/home/bob/pub"
+        chunked: 1024
+        minsize: 2048
+      }

       via: ["alice"]
       rxrate: 10
       txrate: 20
       via: ["alice"]
       rxrate: 10
       txrate: 20


@@ -77,14 +95,28 @@ Example @url{https://hjson.org/, Hjson} configuration file:
 directory. @strong{log} field contains an absolute path to @ref{Log,
 log} file.
 
 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
 @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/exec/sendmail} will be used as a local mailer. You can
-omit either of those two @emph{from}/@emph{to} sections to omit
+@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.
 
 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,
 @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,


@@ -95,7 +127,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


@@ -117,44 +149,49 @@ arguments and the body fed to command's stdin.
 command, will execute:
 
 @verbatim
 command, will execute:
 
 @verbatim

-echo hello world |
-    NNCP_SELF=OURNODE \
-    NNCP_SENDER=REMOTE \
-    NNCP_NICE=64 \
-    /usr/sbin/sendmail -t ARG0 ARG1 ARG2
+NNCP_SELF=OURNODE \
+NNCP_SENDER=REMOTE \
+NNCP_NICE=64 \
+/usr/sbin/sendmail -t ARG0 ARG1 ARG2

 @end verbatim
 
 @end verbatim
 

+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}
 @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
+@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.
 
 @anchor{CfgVia}
 @item via
 An array of node identifiers that will be used as a relay to that node.
 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 @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
+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 stdin/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}
 forced address specifying.
 
 @anchor{CfgXxRate}


@@ -185,3 +222,22 @@ List of @ref{Call, call configuration}s. Can be omitted if
 @ref{nncp-caller} won't be used to call that node.
 
 @end table
 @ref{nncp-caller} won't be used to call that node.
 
 @end table

+
+@menu
+* Shared spool directory: Shared spool.
+@end menu
+
+@node Shared spool
+@section Shared spool directory
+
+If you want to share single spool directory with multiple grouped Unix
+users, then you can @command{setgid} it and assure that umask is group
+friendly. For convenience you can set @option{umask} globally for
+invoked NNCP commands in the configuration file. For example:
+
+@verbatim
+$ chgrp nncp /usr/local/etc/nncp.hjson /var/spool/nncp
+$ chmod g+r /usr/local/etc/nncp.hjson
+$ chmod g+rwxs /var/spool/nncp
+$ echo 'umask: "007"' >> /usr/local/etc/nncp.hjson
+@end verbatim