X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fcfg.texi;h=3e0b882b0582f7c16792b9ed057e18d1b4c46d07;hb=4c17993ce76c6f1883e6854d826eafd4c33c1594;hp=410bee884e2ef7305ccbff340a3846ab09f43471;hpb=40e961bf30dce2ecd1b4517190c6f2040df08de7;p=nncp.git diff --git a/doc/cfg.texi b/doc/cfg.texi index 410bee8..3e0b882 100644 --- a/doc/cfg.texi +++ b/doc/cfg.texi @@ -1,78 +1,122 @@ @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 + + 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 - 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 - 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: /home/bob/pub - freqchunked: 1024 - freqminsize: 2048 - via: [alice] - rxrate: 10 - txrate: 20 + } + + 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 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/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. +@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, @@ -83,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. -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 @@ -98,19 +142,21 @@ 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 stdin. +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: -@verbatim -echo hello world | - NNCP_SELF=OURNODE \ - NNCP_SENDER=REMOTE \ - NNCP_NICE=64 \ - /usr/sbin/sendmail -t ARG0 ARG1 ARG2 -@end verbatim +@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 @@ -118,32 +164,35 @@ 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. -@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 @@ -154,18 +203,18 @@ 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