From: Sergey Matveev Date: Sat, 14 Dec 2019 18:33:14 +0000 (+0300) Subject: @example is more correct way to give examples X-Git-Tag: v5.2.0^2 X-Git-Url: http://www.git.cypherpunks.ru/?p=nncp.git;a=commitdiff_plain;h=fb0b3a18e2f73d4bf36a5aa3aa1e976b4dd284e9 @example is more correct way to give examples --- diff --git a/doc/bundles.texi b/doc/bundles.texi index 21b3104..7bbc85a 100644 --- a/doc/bundles.texi +++ b/doc/bundles.texi @@ -17,23 +17,23 @@ sequentially streamed for recording and digested back. @item They do not require intermediate storage before recording on either CD-ROM or tape drive. -@verbatim +@example $ nncp-bundle -tx SOMENODE | cdrecord -tao - # record directly to CD $ nncp-bundle -tx SOMENODE | dd of=/dev/sa0 bs=10240 # record directly to tape $ dd if=/dev/cd0 bs=2048 | nncp-bundle -rx # read directly from CD $ dd if=/dev/sa0 bs=10240 | nncp-bundle -rx # read directly from tape -@end verbatim +@end example @item They do not require filesystem existence to deal with, simplifying administration when operating in heterogeneous systems with varying filesystems. No @command{mount}/@command{umount}, @command{zpool import}/@command{zpool export} and struggling with file permissions. -@verbatim +@example $ nncp-bundle -tx SOMENODE | dd of=/dev/da0 bs=1M # record directly to # hard/flash drive $ dd if=/dev/da0 bs=1M | nncp-bundle -rx # read directly from drive -@end verbatim +@end example @item This is the fastest way to record outbound packets for offline transmission -- sequential write is always faster, when no diff --git a/doc/cfg.texi b/doc/cfg.texi index 6944451..1acfc33 100644 --- a/doc/cfg.texi +++ b/doc/cfg.texi @@ -148,12 +148,12 @@ arguments and the body fed to command's stdin. @verb{|echo hello world | nncp-exec OURNODE sendmail ARG0 ARG1 ARG2|} command, will execute: -@verbatim +@example NNCP_SELF=OURNODE \ NNCP_SENDER=REMOTE \ NNCP_NICE=64 \ /usr/sbin/sendmail -t ARG0 ARG1 ARG2 -@end verbatim +@end example feeding @verb{|hello world\n|} to that started @command{sendmail} process. @@ -235,9 +235,9 @@ 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 +@example $ 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 +@end example diff --git a/doc/cmds.texi b/doc/cmds.texi index 039c9e6..2606b6e 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -45,11 +45,11 @@ Nearly all commands have the following common options: @node nncp-bundle @section nncp-bundle -@verbatim +@example $ nncp-bundle [options] -tx [-delete] NODE [NODE ...] > ... $ nncp-bundle [options] -rx -delete [-dryrun] [NODE ...] < ... $ nncp-bundle [options] -rx [-check] [-dryrun] [NODE ...] < ... -@end verbatim +@end example With @option{-tx} option, this command creates @ref{Bundles, bundle} of @ref{Encrypted, encrypted packets} from the spool directory and writes @@ -80,10 +80,10 @@ with @option{-rx} and @option{-delete} options -- in that mode, stream packets integrity will be checked and they will be deleted from the spool if everything is good. So it is advisable to recheck your streams: -@verbatim +@example $ nncp-bundle -tx ALICE BOB WHATEVER | cdrecord -tao - $ dd if=/dev/cd0 bs=2048 | nncp-bundle -rx -delete -@end verbatim +@end example @option{-dryrun} option prevents any writes to the spool. This is useful when you need to see what packets will pass by and possibly check @@ -92,7 +92,7 @@ their integrity. @node nncp-call @section nncp-call -@verbatim +@example $ nncp-call [options] [-onlinedeadline INT] [-maxonlinetime INT] @@ -102,7 +102,7 @@ $ nncp-call [options] [-rxrate INT] [-txrate INT] NODE[:ADDR] [FORCEADDR] -@end verbatim +@end example Call (connect to) specified @option{NODE} and run @ref{Sync, synchronization} protocol with the @ref{nncp-daemon, daemon} on the @@ -141,9 +141,9 @@ notification. @node nncp-caller @section nncp-caller -@verbatim +@example $ nncp-caller [options] [NODE ...] -@end verbatim +@end example Croned daemon that calls remote nodes from time to time, according to their @ref{CfgCalls, @emph{calls}} configuration field. @@ -157,10 +157,10 @@ Look @ref{nncp-call} for more information. @node nncp-cfgenc @section nncp-cfgenc -@verbatim +@example $ nncp-cfgmin [options] [-s INT] [-t INT] [-p INT] cfg.hjson > cfg.hjson.eblob $ nncp-cfgmin [options] -d cfg.hjson.eblob > cfg.hjson -@end verbatim +@end example This command allows you to encrypt provided @file{cfg.hjson} file with the passphrase, producing @ref{EBlob, eblob}, to safely keep your @@ -185,21 +185,21 @@ if passphrase can not decrypt @file{eblob}. @option{-dump} options parses @file{eblob} and prints parameters used during its creation. For example: -@verbatim +@example $ nncp-cfgenc -dump /usr/local/etc/nncp.hjson.eblob Strengthening function: Balloon with BLAKE2b-256 Memory space cost: 1048576 bytes Number of rounds: 16 Number of parallel jobs: 2 Blob size: 2494 -@end verbatim +@end example @node nncp-cfgmin @section nncp-cfgmin -@verbatim +@example $ nncp-cfgmin [options] > stripped.hjson -@end verbatim +@end example Print out stripped configuration version: only path to @ref{Spool, spool}, path to log file, neighbours public keys are stayed. This is @@ -209,9 +209,9 @@ neighbours, without private keys involving. @node nncp-cfgnew @section nncp-cfgnew -@verbatim +@example $ nncp-cfgnew [options] [-nocomments] > new.hjson -@end verbatim +@end example Generate new node configuration: private keys, example configuration file and print it to stdout. You must use this command when you setup @@ -224,9 +224,9 @@ operating system. @node nncp-check @section nncp-check -@verbatim +@example $ nncp-check [options] -@end verbatim +@end example Perform @ref{Spool, spool} directory integrity check. Read all files that has Base32-encoded filenames and compare it with recalculated @@ -236,9 +236,9 @@ not used often in practice, if ever. @node nncp-daemon @section nncp-daemon -@verbatim +@example $ nncp-daemon [options] [-maxconn INT] [-bind ADDR] [-inetd] -@end verbatim +@end example Start listening TCP daemon, wait for incoming connections and run @ref{Sync, synchronization protocol} with each of them. You can run @@ -259,9 +259,9 @@ uucp stream tcp6 nowait nncpuser /usr/local/bin/nncp-daemon nncp-daemon -inetd @node nncp-exec @section nncp-exec -@verbatim +@example $ nncp-exec [options] NODE HANDLE [ARG0 ARG1 ...] -@end verbatim +@end example Send execution command to @option{NODE} for specified @option{HANDLE}. Body is read from stdin and compressed. After receiving, remote side @@ -281,13 +281,13 @@ exec: { then executing @verb{|echo My message | nncp-exec -replynice 123 REMOTE sendmail root@localhost|} will lead to execution of: -@verbatim +@example echo My message | NNCP_SELF=REMOTE \ NNCP_SENDER=OurNodeId \ NNCP_NICE=123 \ - /usr/sbin/sendmail -t root@localhost -@end verbatim + /usr/sbin/sendmail -t root@@localhost +@end example If @ref{CfgNotify, notification} is enabled on the remote side for exec handles, then it will sent simple letter after successful command @@ -296,9 +296,9 @@ execution with its output in message body. @node nncp-file @section nncp-file -@verbatim +@example $ nncp-file [options] [-chunked INT] SRC NODE:[DST] -@end verbatim +@end example Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies destination file name in remote's @ref{CfgIncoming, incoming} @@ -344,9 +344,9 @@ file receiving. @node nncp-freq @section nncp-freq -@verbatim +@example $ nncp-freq [options] NODE:SRC [DST] -@end verbatim +@end example Send file request to @option{NODE}, asking it to send its @file{SRC} file from @ref{CfgFreq, freq.path} directory to our node under @file{DST} @@ -360,45 +360,45 @@ queuing. @node nncp-log @section nncp-log -@verbatim +@example $ nncp-log [options] -@end verbatim +@end example Parse @ref{Log, log} file and print out its records in human-readable form. @node nncp-pkt @section nncp-pkt -@verbatim +@example $ nncp-pkt [options] < pkt $ nncp-pkt [options] [-decompress] -dump < pkt > payload $ nncp-pkt -overheads -@end verbatim +@end example Low level packet parser. Normally it should not be used, but can help in debugging. By default it will print packet's type, for example: -@verbatim +@example Packet type: encrypted Niceness: 64 Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ -@end verbatim +@end example If you specify @option{-dump} option and provide an @ref{Encrypted, encrypted} packet, then it will verify and decrypt it to stdout. Encrypted packets contain @ref{Plain, plain} ones, that also can be fed to @command{nncp-pkt}: -@verbatim +@example Packet type: plain Payload type: transitional Path: VHMTRWDOXPLK7BR55ICZ5N32ZJUMRKZEMFNGGCEAXV66GG43PEBQ Packet type: plain Payload type: mail -Path: stargrave@stargrave.org -@end verbatim +Path: stargrave@@stargrave.org +@end example And with the @option{-dump} option it will give you the actual payload (the whole file, mail message, and so on). @option{-decompress} option @@ -410,10 +410,10 @@ packets). @node nncp-reass @section nncp-reass -@verbatim +@example $ nncp-reass [options] [-dryrun] [-keep] [-dump] [-stdout] FILE.nncp.meta -$ nncp-reass [options] [-dryrun] [-keep] {-all | -node NODE} -@end verbatim +$ nncp-reass [options] [-dryrun] [-keep] @{-all | -node NODE@} +@end example Reassemble @ref{Chunked, chunked file} after @ref{nncp-toss, tossing}. @@ -452,7 +452,7 @@ and/or separate storage device for higher performance. @option{-dump} option prints meta-file contents in human-friendly form. It is useful mainly for debugging purposes. For example: -@verbatim +@example Original filename: testfile File size: 3.8 MiB (3987795 bytes) Chunk size: 1.0 MiB (1048576 bytes) @@ -462,21 +462,21 @@ Checksums: 1: 013a07e659f2e353d0e4339c3375c96c7fffaa2fa00875635f440bbc4631052a 2: f4f883975a663f2252328707a30e71b2678f933b2f3103db8475b03293e4316e 3: 0e9e229501bf0ca42d4aa07393d19406d40b179f3922a3986ef12b41019b45a3 -@end verbatim +@end example Do not forget about @ref{ChunkedZFS, possible} ZFS deduplication issues. @node nncp-rm @section nncp-rm -@verbatim +@example $ nncp-rm [options] -tmp $ nncp-rm [options] -lock $ nncp-rm [options] -node NODE -part $ nncp-rm [options] -node NODE -seen $ nncp-rm [options] -node NODE [-rx] [-tx] $ nncp-rm [options] -node NODE -pkt PKT -@end verbatim +@end example This command is aimed to delete various files from your spool directory: @@ -499,9 +499,9 @@ ones. If @option{-seen} option is specified, then delete only @node nncp-stat @section nncp-stat -@verbatim +@example $ nncp-stat [options] [-node NODE] -@end verbatim +@end example Print current @ref{Spool, spool} statistics about unsent and unprocessed packets. For each node (unless @option{-node} specified) and each @@ -511,7 +511,7 @@ size) are in inbound (Rx) and outbound (Tx) queues. @node nncp-toss @section nncp-toss -@verbatim +@example $ nncp-toss [options] [-node NODE] [-dryrun] @@ -521,7 +521,7 @@ $ nncp-toss [options] [-nofreq] [-noexec] [-notrns] -@end verbatim +@end example Perform "tossing" operation on all inbound packets. This is the tool that decrypts all packets and processes all payload packets in them: @@ -547,9 +547,9 @@ options allow to disable any kind of packet types processing. @node nncp-xfer @section nncp-xfer -@verbatim +@example $ nncp-xfer [options] [-node NODE] [-mkdir] [-keep] [-rx|-tx] DIR -@end verbatim +@end example Search for directory in @file{DIR} containing inbound packets for us and move them to local @ref{Spool, spool} directory. Also search for known diff --git a/doc/index.texi b/doc/index.texi index a83ea31..56480cf 100644 --- a/doc/index.texi +++ b/doc/index.texi @@ -2,6 +2,8 @@ @documentencoding UTF-8 @settitle NNCP +@set VERSION 5.2.0 + @copying This manual is for NNCP (Node to Node copy) -- collection of utilities simplifying secure store-and-forward files and mail exchanging. diff --git a/doc/integration.texi b/doc/integration.texi index 8240e2f..a8a8b9e 100644 --- a/doc/integration.texi +++ b/doc/integration.texi @@ -23,13 +23,13 @@ want to freq from. Because files can be updated there. It is useful to run cron-ed job on it to create files listing you can freq and search for files in it: -@verbatim +@example 0 4 * * * cd /storage ; tmp=`mktemp` ; \ tree -f -h -N --du --timefmt \%Y-\%m-\%d | zstdmt -19 > $tmp && chmod 644 $tmp && mv $tmp TREE.txt.zst ; \ tree -J -f --timefmt \%Y-\%m-\%d | zstdmt -19 > $tmp && chmod 644 $tmp && mv $tmp TREE.json.zst -@end verbatim +@end example @node Postfix @section Integration with Postfix @@ -51,11 +51,11 @@ the Postfix @command{sendmail} command. @item Define a @command{pipe(8)} based mail delivery transport for delivery via NNCP: -@verbatim +@example /usr/local/etc/postfix/master.cf: nncp unix - n n - - pipe flags=F user=nncp argv=nncp-exec -quiet $nexthop sendmail $recipient -@end verbatim +@end example This runs the @command{nncp-exec} command to place outgoing mail into the NNCP queue after replacing @var{$nexthop} by the the receiving NNCP @@ -67,11 +67,11 @@ shell meta characters in command-line parameters. @item Specify that mail for @emph{example.com}, should be delivered via NNCP, to a host named @emph{nncp-host}: -@verbatim +@example /usr/local/etc/postfix/transport: example.com nncp:nncp-host .example.com nncp:nncp-host -@end verbatim +@end example See the @command{transport(5)} manual page for more details. @@ -80,18 +80,18 @@ whenever you change the @file{transport} file. @item Enable @file{transport} table lookups: -@verbatim +@example /usr/local/etc/postfix/main.cf: transport_maps = hash:$config_directory/transport -@end verbatim +@end example @item Add @emph{example.com} to the list of domains that your site is willing to relay mail for. -@verbatim +@example /usr/local/etc/postfix/main.cf: relay_domains = example.com ...other relay domains... -@end verbatim +@end example See the @option{relay_domains} configuration parameter description for details. @@ -114,27 +114,27 @@ the Postfix @command{sendmail} command. @item Specify that all remote mail must be sent via the @command{nncp} mail transport to your NNCP gateway host, say, @emph{nncp-gateway}: -@verbatim +@example /usr/local/etc/postfix/main.cf: relayhost = nncp-gateway default_transport = nncp -@end verbatim +@end example Postfix 2.0 and later also allows the following more succinct form: -@verbatim +@example /usr/local/etc/postfix/main.cf: default_transport = nncp:nncp-gateway -@end verbatim +@end example @item Define a @command{pipe(8)} based message delivery transport for mail delivery via NNCP: -@verbatim +@example /usr/local/etc/postfix/master.cf: nncp unix - n n - - pipe flags=F user=nncp argv=nncp-exec -quiet $nexthop sendmail $recipient -@end verbatim +@end example This runs the @command{nncp-exec} command to place outgoing mail into the NNCP queue. It substitutes the hostname (@emph{nncp-gateway}, or @@ -159,33 +159,40 @@ program supports ETags and won't pollute the channel if remote server supports them too. After installing @command{rss2email}, create configuration file: -@verbatim -$ r2e new rss-robot@address.com -@end verbatim + +@example +$ r2e new rss-robot@@address.com +@end example + and add feeds you want to retrieve: -@verbatim + +@example $ r2e add https://git.cypherpunks.ru/cgit.cgi/nncp.git/atom/?h=master -@end verbatim +@end example + and run the process: -@verbatim + +@example $ r2e run -@end verbatim +@end example @node WARCs @section Integration with Web pages Simple HTML web page can be downloaded very easily for sending and viewing it offline after: -@verbatim + +@example $ wget http://www.example.com/page.html -@end verbatim +@end example But most web pages contain links to images, CSS and JavaScript files, required for complete rendering. @url{https://www.gnu.org/software/wget/, GNU Wget} supports that documents parsing and understanding page dependencies. You can download the whole page with dependencies the following way: -@verbatim + +@example $ wget \ --page-requisites \ --convert-links \ @@ -195,19 +202,22 @@ $ wget \ --random-wait \ --execute robots=off \ http://www.example.com/page.html -@end verbatim +@end example + that will create @file{www.example.com} directory with all files necessary to view @file{page.html} web page. You can create single file compressed tarball with that directory and send it to remote node: -@verbatim + +@example $ tar cf - www.example.com | zstd | nncp-file - remote.node:www.example.com-page.tar.zst -@end verbatim +@end example But there are multi-paged articles, there are the whole interesting sites you want to get in a single package. You can mirror the whole web site by utilizing @command{wget}'s recursive feature: -@verbatim + +@example $ wget \ --recursive \ --timestamping \ @@ -216,20 +226,22 @@ $ wget \ --no-parent \ [...] http://www.example.com/ -@end verbatim +@end example There is a standard for creating @url{https://en.wikipedia.org/wiki/Web_ARChive, Web ARChives}: @strong{WARC}. Fortunately again, @command{wget} supports it as an output format. -@verbatim + +@example $ wget \ --warc-file www.example_com-$(date '+%Y%M%d%H%m%S') \ --no-warc-compression \ --no-warc-keep-log \ [...] http://www.example.com/ -@end verbatim +@end example + That command will create uncompressed @file{www.example_com-XXX.warc} web archive. By default, WARCs are compressed using @url{https://en.wikipedia.org/wiki/Gzip, gzip}, but, in example above, @@ -241,12 +253,13 @@ There are plenty of software acting like HTTP proxy for your browser, allowing to view that WARC files. However you can extract files from that archive using @url{https://pypi.python.org/pypi/Warcat, warcat} utility, producing usual directory hierarchy: -@verbatim + +@example $ python3 -m warcat extract \ www.example_com-XXX.warc \ --output-dir www.example.com-XXX \ --progress -@end verbatim +@end example @node BitTorrent @section BitTorrent and huge files @@ -267,12 +280,14 @@ connections. You can queue you files after they are completely downloaded. @file{aria2-downloaded.sh} contents: + @verbatiminclude aria2-downloaded.sh Also you can prepare @url{http://aria2.github.io/manual/en/html/aria2c.html#files, input file} with the jobs you want to download: -@verbatim + +@example $ cat jobs http://www.nncpgo.org/download/nncp-0.11.tar.xz out=nncp.txz @@ -281,7 +296,8 @@ http://www.nncpgo.org/download/nncp-0.11.tar.xz.sig $ aria2c \ --on-download-complete aria2-downloaded.sh \ --input-file jobs -@end verbatim +@end example + and all that downloaded (@file{nncp.txz}, @file{nncp.txz.sig}) files will be sent to @file{remote.node} when finished. @@ -305,15 +321,17 @@ exec: { @end verbatim @file{warcer.sh} contents: + @verbatiminclude warcer.sh @file{wgeter.sh} contents: + @verbatiminclude wgeter.sh Now you can queue that node to send you some website's page, file or BitTorrents: -@verbatim +@example $ echo http://www.nncpgo.org/Postfix.html | nncp-exec remote.node warcer postfix-whole-page $ echo http://www.nncpgo.org/Postfix.html | @@ -322,7 +340,7 @@ $ echo \ http://www.nncpgo.org/download/nncp-0.11.tar.xz http://www.nncpgo.org/download/nncp-0.11.tar.xz.sig | nncp-exec remote.node aria2c -@end verbatim +@end example @node Git @section Integration with Git @@ -333,32 +351,37 @@ necessary tools for store-and-forward networking. everything you need. Use it to create bundles containing all required blobs/trees/commits and tags: -@verbatim + +@example $ git bundle create repo-initial.bundle master --tags --branches $ git tag -f last-bundle $ nncp-file repo-initial.bundle remote.node:repo-$(date % '+%Y%M%d%H%m%S').bundle -@end verbatim +@end example Do usual working with the Git: commit, add, branch, checkout, etc. When you decide to queue your changes for sending, create diff-ed bundle and transfer them: -@verbatim + +@example $ git bundle create repo-$(date '+%Y%M%d%H%m%S').bundle last-bundle..master or maybe $ git bundle create repo-$(date '+%Y%M%d').bundle --since=10.days master -@end verbatim +@end example Received bundle on remote machine acts like usual remote: -@verbatim + +@example $ git clone -b master repo-XXX.bundle -@end verbatim +@end example + overwrite @file{repo.bundle} file with newer bundles you retrieve and fetch all required branches and commits: -@verbatim + +@example $ git pull # assuming that origin remote points to repo.bundle $ git fetch repo.bundle master:localRef $ git ls-remote repo.bundle -@end verbatim +@end example Bundles are also useful when cloning huge repositories (like Linux has). Git's native protocol does not support any kind of interrupted download @@ -369,7 +392,9 @@ bundle, you can add an ordinary @file{git://} remote and fetch the difference. Also you can find the following exec-handler useful: + @verbatiminclude git-bundler.sh + And it allows you to request for bundles like that: @code{echo some-old-commit..master | nncp-exec REMOTE bundler REPONAME}. @@ -383,8 +408,9 @@ many of them are supported, including @emph{Dailymotion}, @emph{Vimeo} and @emph{YouTube}. When you multimedia becomes an ordinary file, you can transfer it easily. -@verbatim + +@example $ youtube-dl \ - --exec 'nncp-file {} remote.node:' \ + --exec 'nncp-file @{@} remote.node:' \ 'https://www.youtube.com/watch?list=PLd2Cw8x5CytxPAEBwzilrhQUHt_UN10FJ' -@end verbatim +@end example diff --git a/doc/integrity.texi b/doc/integrity.texi index 9ffcc0d..1752e9d 100644 --- a/doc/integrity.texi +++ b/doc/integrity.texi @@ -19,10 +19,10 @@ uid NNCP releases @itemize @item -@verbatim +@example $ gpg --auto-key-locate dane --locate-keys releases at nncpgo dot org $ gpg --auto-key-locate wkd --locate-keys releases at nncpgo dot org -@end verbatim +@end example @item @verbatiminclude .well-known/openpgpkey/hu/i4cdqgcarfjdjnba6y4jnf498asg8c6p.asc diff --git a/doc/sources.texi b/doc/sources.texi index 2ded27c..1cc1ea1 100644 --- a/doc/sources.texi +++ b/doc/sources.texi @@ -6,11 +6,11 @@ be buggy. It does not contain compiled documentation and dependent libraries source code. Because of that, it is recommended for porters to use @ref{Tarballs, tarballs} instead. -@verbatim +@example $ git clone git://git.cypherpunks.ru/nncp.git $ cd nncp $ git checkout develop -@end verbatim +@end example Also there is mirror of dependent libraries for safety if their native repositories will be unavailable (they are seldom updated): diff --git a/doc/sp.texi b/doc/sp.texi index 239b87f..d6be2d9 100644 --- a/doc/sp.texi +++ b/doc/sp.texi @@ -54,6 +54,7 @@ just an unsigned integer telling what body structure follows. Actually @emph{HALT} packet does not have any body, only the header with the type. It is also used in the first payload for padding to the maximum size. + @verbatim +------+ | HALT | @@ -62,11 +63,13 @@ just an unsigned integer telling what body structure follows. @item INFO Information about the file we have for transmission. + @verbatim +------+--------------------+ | INFO | NICE | SIZE | HASH | +------+--------------------+ @end verbatim + @multitable @columnfractions 0.2 0.3 0.5 @headitem @tab XDR type @tab Value @item Niceness @tab @@ -83,11 +86,13 @@ just an unsigned integer telling what body structure follows. @item FREQ File transmission request. Ask remote side to queue the file for transmission. + @verbatim +------+---------------+ | FREQ | HASH | OFFSET | +------+---------------+ @end verbatim + @multitable @columnfractions 0.2 0.3 0.5 @headitem @tab XDR type @tab Value @item Hash @tab @@ -100,11 +105,13 @@ just an unsigned integer telling what body structure follows. @item FILE Chunk of file. + @verbatim +------+-------------------------+ | FILE | HASH | OFFSET | PAYLOAD | +------+-------------------------+ @end verbatim + @multitable @columnfractions 0.2 0.3 0.5 @headitem @tab XDR type @tab Value @item Hash @tab @@ -120,11 +127,13 @@ just an unsigned integer telling what body structure follows. @item DONE Signal remote side that we have successfully downloaded the file. + @verbatim +------+------+ | DONE | HASH | +------+------+ @end verbatim + @multitable @columnfractions 0.2 0.3 0.5 @headitem @tab XDR type @tab Value @item Hash @tab diff --git a/doc/spool.texi b/doc/spool.texi index c5c516d..98532ae 100644 --- a/doc/spool.texi +++ b/doc/spool.texi @@ -5,7 +5,7 @@ Spool directory holds @ref{Encrypted, encrypted packets} received from remote nodes and queued for sending to them. It has the following example structure: -@verbatim +@example spool/tmp/ spool/2WHB...OABQ/rx.lock spool/2WHB...OABQ/rx/5ZIB...UMKW.part @@ -17,7 +17,7 @@ spool/BYRR...CG6Q/tx/AQUT...DGNT.seen spool/BYRR...CG6Q/tx/NSYY...ZUU6 spool/BYRR...CG6Q/tx/VCSR...3VXX.seen spool/BYRR...CG6Q/tx/ZI5U...5RRQ -@end verbatim +@end example Except for @file{tmp}, all other directories are Base32-encoded node identifiers (@file{2WHB...OABQ}, @file{BYRR...CG6Q} in our example). diff --git a/doc/usecases.ru.texi b/doc/usecases.ru.texi index 677d2ac..9e7e178 100644 --- a/doc/usecases.ru.texi +++ b/doc/usecases.ru.texi @@ -79,10 +79,10 @@ IMAP4, как правило, нет). У вас легковесный, сжа Команды: -@verbatim +@example $ nncp-file file_i_want_to_send bob: $ nncp-file another_file bob:movie.avi -@end verbatim +@end example добавят в очередь отправки два файла для узла @emph{bob}. Выстрелил-и-забыл! Теперь это работа демона (или offline передачи) @@ -105,12 +105,12 @@ NNCP поддерживает @ref{Niceness, приоритезацию траф раньше или позднее остальных. Почти все команды имеют соответствующую опцию: -@verbatim +@example $ nncp-file -nice FLASH myfile node:dst $ nncp-xfer -nice PRIORITY /mnt/shared $ nncp-call -nice NORMAL bob [...] -@end verbatim +@end example Огромные файлы могут быть разбиты на маленькие @ref{Chunked, части}, давая возможность передачи, по сути, любых объёмов используя накопители @@ -118,10 +118,10 @@ $ nncp-call -nice NORMAL bob Вы также можете использовать CD-ROM и ленточные накопители: -@verbatim +@example $ nncp-bundle -tx bob | cdrecord -tao - $ nncp-bundle -tx bob | dd of=/dev/sa0 bs=10240 -@end verbatim +@end example @node UsecaseNoLinkRU @subsection Экстремальные наземные окружающие условия, нет связи @@ -135,9 +135,9 @@ $ nncp-bundle -tx bob | dd of=/dev/sa0 bs=10240 устройство (SD гораздо предпочтительнее!) хранения, подмонтируйте и запустите @ref{nncp-xfer}: -@verbatim +@example $ nncp-xfer -node bob /media/usbstick -@end verbatim +@end example чтобы скопировать все исходящие пакеты относящиеся к @emph{bob}. Используйте @option{-mkdir} опцию чтобы создать все необходимые @@ -148,16 +148,16 @@ $ nncp-xfer -node bob /media/usbstick @emph{bob} и к @emph{alice}, то тогда просто не указывайте @option{-node} опцию, чтобы скопировать все доступные исходящие пакеты. -@verbatim +@example $ nncp-xfer /media/usbstick -@end verbatim +@end example Размонтируйте и передайте накопитель Бобу и Алисе. Когда они вставят накопитель в свои компьютеры, то выполнят точно такую же команду: -@verbatim +@example $ nncp-xfer /media/usbstick -@end verbatim +@end example чтобы найти все пакеты относящиеся к их узлу и локально скопируют для дальнейшей обработки. @command{nncp-xfer} это единственная команда @@ -175,10 +175,10 @@ $ nncp-xfer /media/usbstick отсылать их. Они -- всего-лишь последовательность @ref{Encrypted, зашифрованных пакетов}, которые вы можете принять. -@verbatim +@example $ nncp-bundle -tx alice bob eve ... | команда для отправки широковещательной рассылки $ команда для приёма широковещательной рассылки | nncp-bundle -rx -@end verbatim +@end example Встроенная возможность определять дубляжи пакетов позволит вам переотправлять широковещательные рассылки время от времени, повышая @@ -243,15 +243,17 @@ $ команда для приёма широковещательной расс отослать полезную нагрузку сразу же в самом первом пакете) безопасный транспорт с свойством совершенной прямой секретности. -@verbatim -$ nncp-daemon -bind [::]:5400 -@end verbatim +@example +$ nncp-daemon -bind "[::]":5400 +@end example + запустит TCP демон, который будет слушать входящие соединения на всех интерфейсах. -@verbatim +@example $ nncp-call bob -@end verbatim +@end example + попытается подключиться к известному TCP-адресу узла @emph{bob} (взятого из конфигурационного файла), послать все связанные с ним исходящие пакеты и получить от него. Все прерванные передачи будут автоматически diff --git a/doc/usecases.texi b/doc/usecases.texi index 113089d..e118da4 100644 --- a/doc/usecases.texi +++ b/doc/usecases.texi @@ -77,10 +77,10 @@ daemon}. The command: -@verbatim +@example $ nncp-file file_i_want_to_send bob: $ nncp-file another_file bob:movie.avi -@end verbatim +@end example will queue two files for sending to @emph{bob} node. Fire and forget! Now this is daemon's job (or offline transfer) to send this files part @@ -100,12 +100,12 @@ NNCP allows traffic @ref{Niceness, prioritizing}: each packet has niceness level, that will guarantee that it will be processed earlier or later than the other ones. Nearly all commands has corresponding option: -@verbatim +@example $ nncp-file -nice FLASH myfile node:dst $ nncp-xfer -nice PRIORITY /mnt/shared $ nncp-call -nice NORMAL bob [...] -@end verbatim +@end example Huge files could be split on smaller @ref{Chunked, chunks}, giving possibility to transfer virtually any volumes using small capacity @@ -113,10 +113,10 @@ storages. You can also use CD-ROM and tape drives: -@verbatim +@example $ nncp-bundle -tx bob | cdrecord -tao - $ nncp-bundle -tx bob | dd of=/dev/sa0 bs=10240 -@end verbatim +@end example @node UsecaseNoLink @section Extreme terrestrial environments, no link @@ -128,9 +128,9 @@ media for transferring packets to other nodes. Assume that you send two files to @emph{bob} node. Insert USB storage device (SD is preferable!), mount it and run @ref{nncp-xfer}: -@verbatim +@example $ nncp-xfer -node bob /media/usbstick -@end verbatim +@end example to copy all outbound packets related to @emph{bob}. Use @option{-mkdir} option to create related directory on USB/SD storage if they are missing @@ -140,16 +140,16 @@ If you use single storage device to transfer data both to @emph{bob} and @emph{alice}, then just omit @option{-node} option to copy all available outgoing packets. -@verbatim +@example $ nncp-xfer /media/usbstick -@end verbatim +@end example Unmount it and transfer storage to Bob and Alice. When they will insert it in their computers, they will use exactly the same command: -@verbatim +@example $ nncp-xfer /media/usbstick -@end verbatim +@end example to find all packets related to their node and copy them locally for further processing. @command{nncp-xfer} is the only command used with @@ -165,10 +165,10 @@ example, satellite's broadcasting signal. You are not able to use online You can use @ref{Bundles, bundles} and stream them above. They are just a sequence of @ref{Encrypted, encrypted packets} you can catch on. -@verbatim +@example $ nncp-bundle -tx alice bob eve ... | command to send broadcast $ command to receive broadcast | nncp-bundle -rx -@end verbatim +@end example With built-in packet duplicates detection ability, you can retransmit your broadcasts from time to time, to increase chances the recipient @@ -229,15 +229,17 @@ authenticate peers and provide effective (both participants send payload in the very first packet) secure transport with forward secrecy property. -@verbatim -$ nncp-daemon -bind [::]:5400 -@end verbatim +@example +$ nncp-daemon -bind "[::]":5400 +@end example + will start TCP daemon listening on all interfaces for incoming connections. -@verbatim +@example $ nncp-call bob -@end verbatim +@end example + will try to connect to @emph{bob}'s node known TCP addresses (taken from configuration file) and send all related outbound packets and retrieve those the Bob has. All interrupted transfers will be automatically