From 08cf538a8efb309817a37f39dfccc9fc2f90ebb9 Mon Sep 17 00:00:00 2001
From: Sergey Matveev <stargrave@stargrave.org>
Date: Tue, 27 Jul 2021 15:27:31 +0300
Subject: [PATCH] PPP example

---
 doc/integration/index.texi |  2 +
 doc/integration/ppp.texi   | 78 ++++++++++++++++++++++++++++++++++++++
 doc/nncp.info.do           |  5 ++-
 3 files changed, 83 insertions(+), 2 deletions(-)
 create mode 100644 doc/integration/ppp.texi

diff --git a/doc/integration/index.texi b/doc/integration/index.texi
index f95e9fe..315868b 100644
--- a/doc/integration/index.texi
+++ b/doc/integration/index.texi
@@ -14,6 +14,7 @@ making them store-and-forward friendly.
 * Downloading service: DownloadService
 * Git::
 * Multimedia streaming: Multimedia
+* Serial connection: PPP
 @end menu
 
 @include integration/freqindex.texi
@@ -25,3 +26,4 @@ making them store-and-forward friendly.
 @include integration/download.texi
 @include integration/git.texi
 @include integration/multimedia.texi
+@include integration/ppp.texi
diff --git a/doc/integration/ppp.texi b/doc/integration/ppp.texi
new file mode 100644
index 0000000..d5076c7
--- /dev/null
+++ b/doc/integration/ppp.texi
@@ -0,0 +1,78 @@
+@node PPP
+@section Serial connection
+
+It is not trivial to run online @command{nncp-daemon},
+@command{nncp-call} and @command{nncp-caller} commands over the serial
+link, because it is link without built-in error detection. For efficient
+usage you have to use some kind of window-sliding error correction
+protocol, like Kermit, ZMODEM, UUCP's g-protocol and similar well known
+ones.
+
+However TCP is already satisfying and existing protocol for the same
+purposes. So it would be more easier to bring up the IP interconnection
+and use TCP over it. Most distributions already have
+@url{https://en.wikipedia.org/wiki/Point-to-point_protocol, PPP}
+protocol out-of-box.
+
+Ordinary man page for @command{ppp} in FreeBSD is enough for being able
+to setup it:
+
+@itemize
+
+@item Enable PPP-aware default terminal to run @command{ppplogin} script:
+
+@example
+/etc/gettytab:
+    default:pp=/usr/local/bin/ppplogin:...
+@end example
+
+@example
+/usr/local/bin/ppplogin:
+    #!/bin/sh
+    exec /usr/sbin/ppp -direct incoming
+@end example
+
+@item Enable listening on necessary UART:
+
+@example
+/etc/ttys:
+    ttyU0 "/usr/libexec/getty 3wire.115200" vt100 on
+@end example
+
+@item
+Create @code{incoming} PPP profile, allowing authenticated @code{ppp}
+user to log in:
+
+@example
+/etc/ppp/ppp.conf:
+    incoming:
+        allow ppp
+        disable deflate pred1 mppe protocomp vjcomp ipcp dns
+        enable lqr # null-modem cables might not have carrier detection
+/etc/ppp/ppp.secret:
+    ppp	PASSWORD
+@end example
+
+@item
+Configure PPP client to access that server:
+
+@example
+/etc/ppp/ppp.conf:
+    outgoing:
+        set device /dev/cuaU0
+        set speed 115200
+        set dial
+        set login
+        set authname ppp
+        set authkey PASSWORD
+        disable deflate pred1 mppe protocomp vjcomp ipcp dns
+        enable lqr
+@end example
+
+@end itemize
+
+That configuration does not negotiate any kind of IPv4 addresses,
+routing or DNS servers. Also all compression is turned off, because
+NNCP's traffic is encrypted and uncompressible. Only IPV6CP will
+negotiate IPv6 link-local addresses, on which you can run @ref{MCD,
+multicast discovered} daemons for simplicity.
diff --git a/doc/nncp.info.do b/doc/nncp.info.do
index e336238..0780f63 100644
--- a/doc/nncp.info.do
+++ b/doc/nncp.info.do
@@ -4,9 +4,10 @@ redo-ifchange \
     *.texi \
     cfg/*.texi \
     cmd/*.texi \
+    integration/*.texi \
+    pedro.txt \
     pkt/*.texi \
-    sp.plantuml.txt \
-    pedro.txt
+    sp.plantuml.txt
 . ../config
 ${MAKEINFO:-makeinfo} \
     -D "VERSION `cat ../VERSION`" \
-- 
2.44.0