@node Configuration
@unnumbered Configuration file
-Example YAML configuration file:
+Example @url{https://hjson.org/, Hjson} configuration file:
@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
+ exchprv: 65PUY...MPZ3Q
signpub: 2NMVC...CMH5Q
+ signprv: 555JD...RGD6Y
+ noiseprv: D62XU...NKYPA
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.
+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
-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.
-@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,
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
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
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.
-@item freqchunked
+@item freq.chunked
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.
-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
-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
-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
-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