X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fcfg.texi;h=3e0b882b0582f7c16792b9ed057e18d1b4c46d07;hb=4c17993ce76c6f1883e6854d826eafd4c33c1594;hp=46cbfae5d853395a1c79b6b5246e7a4961bb824f;hpb=5b401cc06b0a9a29f0201c20ead311fb2bff7446;p=nncp.git diff --git a/doc/cfg.texi b/doc/cfg.texi index 46cbfae..3e0b882 100644 --- a/doc/cfg.texi +++ b/doc/cfg.texi @@ -1,68 +1,121 @@ @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 - 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 - 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{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, @@ -74,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 @@ -83,11 +136,27 @@ node has the following fields: 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 @@ -95,38 +164,57 @@ 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 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 @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 -that 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