From 8e0dde30602de63fd1229049d15cb8f62ffd8288 Mon Sep 17 00:00:00 2001 From: Sergey Matveev Date: Tue, 17 Jan 2017 11:03:46 +0300 Subject: [PATCH] Various documentation fixes --- doc/cfg.texi | 2 +- doc/cmds.texi | 24 +++++++-------- doc/news.texi | 8 ++--- doc/pkt.texi | 11 +++---- doc/postfix.texi | 2 +- doc/sp.texi | 4 +-- doc/usecases.texi | 77 ++++++++++++++++++++++++----------------------- doc/workflow.texi | 8 ++--- 8 files changed, 68 insertions(+), 68 deletions(-) diff --git a/doc/cfg.texi b/doc/cfg.texi index 3160d73..46cbfae 100644 --- a/doc/cfg.texi +++ b/doc/cfg.texi @@ -59,7 +59,7 @@ log} file. @anchor{CfgNotify} @strong{notify} section contains notification settings for successfully tossed file and freq packets. Corresponding @strong{from} and -@strong{to} fields will substituted in notification email message. +@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. diff --git a/doc/cmds.texi b/doc/cmds.texi index 9097044..4c1873f 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -14,10 +14,8 @@ Nearly all commands have the following common options: KiB file and set @option{-minsize 4096}, then resulting packet will be 4 KiB (containing file itself and some junk). @item -nice - Set desired outgoing packet niceness level. 1-255 values are - allowed. Higher value means lower priority. In some commands that - means processing of packets that have equal or lower nice value. - That is used for controlling network QoS. + Set desired outgoing packet @ref{Niceness, niceness level}. + 1-255 values are allowed. @item -node Process only single specified node. @item -quiet @@ -62,8 +60,8 @@ overrides @ref{CfgOnlineDeadline, @emph{onlinedeadline}}. Croned daemon that calls remote nodes from time to time, according to their @ref{CfgCalls, @emph{calls}} configuration field. -Optional number of @option{NODE}s tells to call only them, ignoring the -other. Otherwise all nodes with specified @emph{calls} configuration +Optional number of @option{NODE}s tells to ignore other ones. +Otherwise all nodes with specified @emph{calls} configuration field will be called. @option{-onlinedeadline} overrides @ref{CfgOnlineDeadline, @@ -75,12 +73,13 @@ not specify the exact one, then all will be tried until the first success. Optionally you can force @option{FORCEADDR} address usage, instead of addresses taken from configuration file. -Pay attention that this command run integrity check for each completely -received packet in the background. This can be time consuming and -connection could be lost during that check time and remote node won't be +Pay attention that this command runs integrity check for each completely +received packet in the background. This can be time consuming. +Connection could be lost during that check and remote node won't be notified that file is done. But after successful integrity check that -file will be renamed from @file{.part} one and when you rerun -@command{nncp-call} again, remote node will receive completion at once. +file is renamed from @file{.part} one and when you rerun +@command{nncp-call} again, remote node will receive completion +notification. @node nncp-check @section nncp-check @@ -91,7 +90,7 @@ file will be renamed from @file{.part} one and when you rerun Perform @ref{Spool, spool} directory integrity check. Read all files that has Base32-encoded filenames and compare it with recalculated -BLAKE2b hash output of their contents. This supplementary command are +BLAKE2b hash output of their contents. This supplementary command is not used often in practice, if ever. @node nncp-daemon @@ -196,7 +195,6 @@ By default it will print packet's type, for example: Packet type: encrypted Niceness: 64 Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ -Payload size: 4.0 MiB (4162852 bytes) @end verbatim If you specify @option{-dump} option and provide an @ref{Encrypted, diff --git a/doc/news.texi b/doc/news.texi index d72250f..ce921bb 100644 --- a/doc/news.texi +++ b/doc/news.texi @@ -4,19 +4,19 @@ @node Release 0.2 @section Release 0.2 @itemize -@item @strong{Incompatible} packet format change (magic number is +@item @strong{Incompatible} packet's format change (magic number is changed too): size field is encrypted and is not send in plaintext anymore. @item @option{-minsize} option gives ability to automatically pad outgoing packets to specified minimal size. @item @ref{nncp-daemon} and @ref{nncp-call}/@ref{nncp-caller} always -checks new @emph{tx} packet appearance in the background while -connected. Remote side is notified immediately about them. +check new @emph{tx} packets appearance in the background while +connected. Remote side is immediately notified. @item @option{-onlinedeadline} option gives ability to configure timeout of inactivity of online connection, when it could be disconnected. It could be used to keep connection alive for a long time. @item @option{-maxonlinetime} option gives ability to set maximal -allowable online connection alive time. +allowable online connection aliveness time. @item @ref{nncp-caller} command appeared: cron-ed TCP daemon caller. @item @ref{nncp-pkt} command can decompress the data. @end itemize diff --git a/doc/pkt.texi b/doc/pkt.texi index 35700c1..ef6bc0a 100644 --- a/doc/pkt.texi +++ b/doc/pkt.texi @@ -29,20 +29,20 @@ drive. @headitem @tab XDR type @tab Value @item Magic number @tab 8-byte, fixed length opaque data @tab - @verb{|NNCPP0x00x00x01|} + @verb{|N N C P P 0x00 0x00 0x01|} @item Payload type @tab unsigned integer @tab 0 (file), 1 (freq), 2 (mail), 3 (transition) @item Path length @tab unsigned integer @tab - actual length of following field's payload + actual length of @emph{path} field's payload @item Path @tab 255 byte, fixed length opaque data @tab @itemize @item UTF-8 encoded destination path for file transfer @item UTF-8 encoded source path for file request @item UTF-8 encoded, space separated, email recipients list - @item Node id the transition packet must be relayed on + @item Node's id the transition packet must be relayed on @end itemize @end multitable @@ -69,7 +69,7 @@ storages and that are synchronized between TCP daemons. Each encrypted packet has the following header: @verbatim - +--------------- HEADER ----------+ +-------- ENCRYPTED --------+ + +------------ HEADER -------------+ +-------- ENCRYPTED --------+ / \ / \ +-------------------------------------+------------+----...-----------+------+ | MAGIC | NICE | SENDER | EPUB | SIGN | SIZE | MAC | CIPHERTEXT | MAC | JUNK | @@ -84,7 +84,7 @@ Each encrypted packet has the following header: @headitem @tab XDR type @tab Value @item Magic number @tab 8-byte, fixed length opaque data @tab - @verb{|NNCPE0x00x00x01|} + @verb{|N N C P E 0x00 0x00 0x01|} @item Niceness @tab unsigned integer @tab 1-255, packet @ref{Niceness, niceness} level @@ -123,7 +123,6 @@ After the headers comes an encrypted payload size and MAC of that size. @headitem @tab XDR type @tab Value @item Size @tab unsigned hyper integer @tab - @verb{|NNCPE0x00x00x01|} Payload size. @end multitable diff --git a/doc/postfix.texi b/doc/postfix.texi index c62033b..95ed9bb 100644 --- a/doc/postfix.texi +++ b/doc/postfix.texi @@ -2,7 +2,7 @@ @unnumbered Integration with Postfix This section is taken from @url{http://www.postfix.org/nncp_README.html, -Postfix and nncp} manual and just replaces nncp-related calls with NNCP +Postfix and UUCP} manual and just replaces UUCP-related calls with NNCP ones. @strong{Setting up a Postfix Internet to NNCP gateway} diff --git a/doc/sp.texi b/doc/sp.texi index 282a1b9..dca38c3 100644 --- a/doc/sp.texi +++ b/doc/sp.texi @@ -27,7 +27,7 @@ are sent inside XDR envelope: @headitem @tab XDR type @tab Value @item Magic number @tab 8-byte, fixed length opaque data @tab - @verb{|NNCPS0x00x00x01|} + @verb{|N N C P S 0x00 0x00 0x01|} @item Payload @tab variable length opaque data @tab Noise packet itself @@ -36,7 +36,7 @@ are sent inside XDR envelope: Peers static keys are specified as @ref{Configuration, @emph{noisepub}} configuration entry. -Payload inside Noise packets has maximum size of @emph{65 KiB - 256 B = +Payload inside Noise packets has maximum size of @emph{64 KiB - 256 B = 65280 B}. It is sent immediately in the first message by each side. The very first payload (that is carried inside handshake messages) is always padded to the maximum size with @emph{HALT} packets (read below), for diff --git a/doc/usecases.texi b/doc/usecases.texi index 1b61890..8067a93 100644 --- a/doc/usecases.texi +++ b/doc/usecases.texi @@ -29,14 +29,14 @@ Another possibility is to use POP3/IMAP4 servers, but this is too overcomplicated and bloated for the simple task. Not an option. KISS! Just tell both of your Postfixes (on the server and notebook) to drop -email as a mail via NNCP to specified node. This is done similarly as -with UUCP and as written in +email as a mail via NNCP (@ref{nncp-mail}) to specified node. This is +done similarly as with UUCP and as written in @url{http://www.postfix.org/UUCP_README.html, Postfix documentation}. Look @ref{Postfix, here} for further information. All mail will be stored in NNCP @ref{Spool, spool}, that after exchanging and tossing -will call local @command{sendmail} command to deliver them just that was -happened on the same machine. +will call local @command{sendmail} command to deliver them just like +that happened on the same machine. @node UsecaseUnreliable @section Unreliable/expensive communication link @@ -44,14 +44,15 @@ happened on the same machine. Assume that you have got slow modem/radio/cellular link that frequently disconnects and causes TCP timeouts. Not all HTTP servers support file download continuation. SMTP does not support resuming at all and heavy -messages is a problem to retrieve. Moreover, each disconnect leads to -the same data retransmission again, that can be expensive to afford. +messages is problematic to retrieve. Moreover, each disconnect leads to +the same data retransmission again, that can not be afforded sometimes. -Just send your mail and files through NNCP. You can use either offline -delivery methods -- read about them in the next section, or you can use -included NNCP TCP daemon. +Just send your @ref{nncp-mail, mail} and @ref{nncp-file, files} through +NNCP. You can use either offline delivery methods -- read about them in +the next section, or you can use included NNCP @ref{nncp-daemon, TCP +daemon}. -The command below: +The command: @verbatim % nncp-file file_i_want_to_send bob: @@ -91,7 +92,7 @@ choice. Just send files as shown in previous section, but use removable media for transferring packets to other nodes. Assume that you send two files to @emph{bob} node. Insert USB storage -device, mount it and run: +device, mount it and run @ref{nncp-xfer}: @verbatim % nncp-xfer -node bob /media/usbstick @@ -118,8 +119,8 @@ it in their computers, they will use exactly the same command: @end verbatim to find all packets related to their node and copy them locally for -further processing. @ref{nncp-xfer} is the only command used with -removable devices. +further processing. nncp-xfer is the only command used with removable +devices. @node UsecaseF2F @section Private, isolated MitM-resistant networks @@ -144,10 +145,11 @@ Friend-to-friend networks, darknets can mitigate risks related to fake and forged nodes. However they are harder to support and require more time to be done right. -NNCP's TCP daemon uses @url{http://noiseprotocol.org/, Noise-IK} -protocol to mutually authenticate peers and provide effective (both -participants send payload in the very first packet) secure transport -with forward secrecy property. +NNCP's @ref{nncp-daemon, TCP daemon} uses +@url{http://noiseprotocol.org/, Noise-IK} protocol to mutually +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 @@ -190,10 +192,11 @@ neigh: via: [bob] @end verbatim -That configuration file tells that we have got two known neighbours: -@emph{bob} and @emph{bob-airgap}. @emph{bob} can be reached via online -connection using @emph{lan} address. @emph{bob-airgap} can be reached by -sending intermediate relay packet through the @emph{bob}. +That @ref{Configuration, configuration file} tells that we have got two +known neighbours: @emph{bob} and @emph{bob-airgap}. @emph{bob} can be +reached via online connection using @emph{lan} address. +@emph{bob-airgap} can be reached by sending intermediate relay packet +through the @emph{bob}. Any command like @command{nncp-file myfile bob-airgap:} will automatically create an encapsulated packet: one for the destination @@ -211,15 +214,14 @@ This is some kind of bad link too. Some governments tend to forbid entertainment content delivering and popular social networks access (that are already bloated with advertisements, locally executed proprietary JavaScript code (for spying on user activities, collect data -on them), shamelessly exploiting of very basic interhuman need of -communication). +on them), shamelessly exploiting the very basic human need of communication). This is their natural wish. But nobody forces you to obey huge corporations like Apple, Google or Microsoft. It is your choice to -create isolated friend-to-friend network with piles of harmless content -and private messaging. Only predators silently watch for their victims -in mammals world -- it harms your health being watched and feeling that -you are the victim that has already done something wrong. +create an isolated friend-to-friend network with piles of harmless +content and private messaging. Only predators silently watch for their +victims in mammals world -- it harms your health being watched and +feeling that you are the victim that has already done something wrong. @node UsecaseSpy @section Reconnaissance, spying, intelligence, covert agents @@ -235,17 +237,18 @@ Short lived short range networks like Bluetooth and WiFi can also be pretty fast, allowing to quickly fire chunks of queued packets. Very important property is that compromising of those dead drops and -storages must not be fatal and even dangerous. Packets sent through the -network and exchanged via those devices are end-to-end @ref{Encrypted, -encrypted} (but unfortunately lacking forward secrecy). No filenames, -mail recipients are seen. +storages must be neither fatal nor even dangerous. Packets sent through +the network and exchanged via those devices are end-to-end +@ref{Encrypted, encrypted} (but unfortunately lacking forward secrecy). +No filenames, mail recipients are seen. All communications are done with so-called @ref{Spool, spool} area: directory containing only those unprocessed encrypted packets. After packet transfer you still can not read any of them: you have to run -another stage: tossing, that involves your private cryptographic keys. -So even if your loose your computer, storage devices and so on -- it is -not so bad, because you are not carrying private keys with it, you do -not "toss" those packets immediately on the same device. Tossing -(reading those encrypted packets and extracting transferred files and -mail messages) could and should be done on a separate computer. +another stage: @ref{nncp-toss, tossing}, that involves your private +cryptographic keys. So even if your loose your computer, storage devices +and so on -- it is not so bad, because you are not carrying private keys +with it (don't you?), you do not "toss" those packets immediately on the +same device. Tossing (reading those encrypted packets and extracting +transferred files and mail messages) could and should be done on a +separate computer. diff --git a/doc/workflow.texi b/doc/workflow.texi index ea77a3d..7803a78 100644 --- a/doc/workflow.texi +++ b/doc/workflow.texi @@ -2,7 +2,7 @@ @unnumbered Workflow NNCP consists of several utilities. As a rule you will have the -following workflow with them. +following workflow: @enumerate @item Run @ref{nncp-newnode} on each node to create an initial @@ -13,8 +13,8 @@ neighbours. Add their keys to your configuration file and do any other required configuration about their reachability, permissions of file or freq transmission. @item Use @ref{nncp-file}, @ref{nncp-freq}, @ref{nncp-mail} -(@ref{Postfix, look how} Postfix SMTP server could be configured for its -usage) commands to queue file, freq and mail transmissions. Repeat as +(@ref{Postfix, look how} Postfix SMTP server could be configured) +commands to queue file, freq and mail transmissions. Repeat as many times any time as you wish. @item Depending on connection methods, either: @itemize @@ -23,7 +23,7 @@ many times any time as you wish. @item run either @ref{nncp-call} or @ref{nncp-caller} to initiate connection to required nodes from time to time @item use @ref{nncp-xfer} with removable storage devices for copying - packets for/from other nodes + packets to/from other nodes @end itemize @item After successful packet exchanging (or just simply from time to time), run @ref{nncp-toss} for tossing (decrypting and processing) all -- 2.44.0