[Swan-dev] Comments/Suggestions for Libreswan Documentation

[Bill Atwood]

Applicable to version 4.12 tarball

In README.md

1. For Debian/Ubuntu, the list of packages required includes "xmlto", 
which installs 95 packages, requiring 726 MB.  Is it really necessary to 
install all of these?  It seems unlikely to me that Libreswan needs a 
complete TeX system, for example.  It seems possible (from other 
reading) that this requirement is only necessary if the man pages are 
being built.  However, attempting to do "make base" when xmlto has not 
been installed results in an error message.  Is there a way to satisfy 
the needs of a base-only install, without installing all of xmlto?  If 
this is so, a note to this effect, or a revised makefile and 
instructions, would be useful.

2. Under the heading "Building for DEB based systems", the first line 
starts "The packaging/Debian directly is used".  The word "directly" 
should be "directory".  (Note that this error was reported previously 
(on 2023-08-06), and the README.md file on the GitHub site has been 
fixed, but this fix appears not to have propagated to the 4.12 tarball.)

3. Under the heading "Compiling the userland and IKE daemon manually in 
/usr/local", the first line is "make programs", which returns an error 
message:
     "make: *** No rule to make target 'programs'.  Stop."

(Note: the INSTALL file in the same directory suggests "make all".)

In man ipsec.conf(5)

4. In the section "CONN PARAMETERS: GENERAL", under the parameter 
"left", it explicitly says that "IPv4 and IPv6 IP addresses are 
supported".  However, I can find no IPv6 addresses in *any* of the examples.

5. Under the parameter "left", it says, " The value can also contain the 
interface name, which will then later be used to obtain the IP address 
from to fill in.  For example %ppp0."  For IPv6, which address will be 
used?  An IPv6 interface will typically have several valid addresses.

6. More importantly, if the user needs to specify an IPv6 Link-Local 
(LL) address, the interface name MUST also be given, because IPv6 LL 
addresses are unique only on a single medium, and it is not possible to 
tell which interface to use from the IPv6 address itself.  (A typical 
IPv6 LL address would be specified as fe80::xxxx:xxxx:xxxx:xxxx%eno1. 
This is going to conflict with the present semantics for %eno1.)

7. Under the parameter "leftsubnet" (and others later on), it says "any 
form acceptable to ipsec_ttosubnet(3)".  However, when I do "man 
ipsec_ttosubnet", on a system where the "man" pages have been installed, 
I am told that there is " No manual entry for ipsec_ttosubnet".