Import initial strongswan 2.7.0 version into SVN.

1 files changed, 267 insertions, 0 deletions

diff --git a/programs/manual/manual.8 b/programs/manual/manual.8
new file mode 100644
index 000000000..a439544da
--- /dev/null
+++ b/programs/manual/manual.8
@@ -0,0 +1,267 @@
+.TH IPSEC_MANUAL 8 "17 July 2001"
+.\" RCSID $Id: manual.8,v 1.1 2004/03/15 20:35:28 as Exp $
+.SH NAME
+ipsec manual \- take manually-keyed IPsec connections up and down
+.SH SYNOPSIS
+.B ipsec
+.B manual
+[
+.B \-\-show
+] [
+.B \-\-showonly
+] [
+.B \-\-other
+]
+.br
+\ \ \ [
+.B \-\-iam
+.RB address "@" interface
+] [
+.B \-\-config
+configfile
+]
+.br
+\ \ \ operation connection
+.sp 0.5
+.B ipsec
+.B manual
+[
+.I options
+]
+.B \-\-union
+operation part ...
+.SH DESCRIPTION
+.I Manual
+manipulates manually-keyed FreeS/WAN IPsec connections,
+setting them up and shutting them down,
+based on the information in the IPsec configuration file.
+In the normal usage,
+.I connection
+is the name of a connection specification in the configuration file;
+.I operation
+is
+.BR \-\-up ,
+.BR \-\-down ,
+.BR \-\-route ,
+or
+.BR \-\-unroute .
+.I Manual
+generates setup (\c
+.BR \-\-route
+or
+.BR \-\-up )
+or
+teardown (\c
+.BR \-\-down
+or
+.BR \-\-unroute )
+commands for the connection and feeds them to a shell for execution.
+.PP
+The
+.B \-\-up
+operation brings the specified connection up, including establishing a
+suitable route for it if necessary.
+.PP
+The
+.B \-\-route
+operation just establishes the route for a connection.
+Unless and until an
+.B \-\-up
+operation is done, packets routed by that route will simply be discarded.
+.PP
+The
+.B \-\-down
+operation tears the specified connection down,
+.I except
+that it leaves the route in place.
+Unless and until an
+.B \-\-unroute
+operation is done, packets routed by that route will simply be discarded.
+This permits establishing another connection to the same destination
+without any ``window'' in which packets can pass without encryption.
+.PP
+The
+.B \-\-unroute
+operation (and only the
+.B \-\-unroute
+operation) deletes any route established for a connection.
+.PP
+In the
+.B \-\-union
+usage, each
+.I part
+is the name of a partial connection specification in the configuration file,
+and the union of all the partial specifications is the
+connection specification used.
+The effect is as if the contents of the partial specifications were
+concatenated together;
+restrictions on duplicate parameters, etc., do apply to the result.
+(The same effect can now be had, more gracefully, using the
+.B also
+parameter in connection descriptions;
+see
+.IR ipsec.conf (5)
+for details.)
+.PP
+The
+.B \-\-show
+option turns on the
+.B \-x
+option of the shell used to execute the commands,
+so each command is shown as it is executed.
+.PP
+The
+.B \-\-showonly
+option causes
+.I manual
+to show the commands it would run, on standard output,
+and not run them.
+.PP
+The
+.B \-\-other
+option causes
+.I manual
+to pretend it is the other end of the connection.
+This is probably not useful except in combination with
+.BR \-\-showonly .
+.PP
+The
+.B \-\-iam
+option causes
+.I manual
+to believe it is running on the host with the specified IP
+.IR address ,
+and that it should use the specified
+.I interface
+(normally it determines all this automatically,
+based on what IPsec interfaces are up and how they are configured).
+.PP
+The
+.B \-\-config
+option specifies a non-standard location for the FreeS/WAN IPsec
+configuration file (default
+.IR /etc/ipsec.conf ).
+.PP
+See
+.IR ipsec.conf (5)
+for details of the configuration file.
+Apart from the basic parameters which specify the endpoints and routing
+of a connection (\fBleft\fR
+and
+.BR right ,
+plus possibly
+.BR leftsubnet ,
+.BR leftnexthop ,
+.BR leftfirewall ,
+their
+.B right
+equivalents,
+and perhaps
+.BR type ),
+a non-\fBpassthrough\fR
+.I manual
+connection needs an
+.B spi
+or
+.B spibase
+parameter and some parameters specifying encryption, authentication, or
+both, most simply
+.BR esp ,
+.BR espenckey ,
+and
+.BR espauthkey .
+Moderately-secure keys can be obtained from
+.IR ipsec_ranbits (8).
+For production use of manually-keyed connections,
+it is strongly recommended that the keys be kept in a separate file
+(with permissions
+.BR rw\-\-\-\-\-\-\- )
+using the
+.B include
+and
+.B also
+facilities of the configuration file (see
+.IR ipsec.conf (5)).
+.PP
+If an
+.B spi
+parameter is given,
+.I manual
+uses that value as the SPI number for all the SAs
+(which are in separate number spaces anyway).
+If an
+.B spibase
+parameter is given instead,
+.I manual
+assigns SPI values by altering the bottom digit
+of that value;
+SAs going from left to right get even digits starting at 0,
+SAs going from right to left get odd digits starting at 1.
+Either way, it is suggested that manually-keyed connections use
+three-digit SPIs with the first digit non-zero,
+i.e. in the range
+.B 0x100
+through
+.BR 0xfff ;
+FreeS/WAN reserves those for manual keying and will not
+attempt to use them for automatic keying (unless requested to,
+presumably by a non-FreeS/WAN other end).
+.SH FILES
+.ta \w'/var/run/ipsec.nexthop'u+4n
+/etc/ipsec.conf	default IPsec configuration file
+.br
+/var/run/ipsec.info	\fB%defaultroute\fR information
+.SH SEE ALSO
+ipsec(8), ipsec.conf(5), ipsec_spi(8), ipsec_eroute(8), ipsec_spigrp(8),
+route(8)
+.SH HISTORY
+Written for the FreeS/WAN project
+<http://www.freeswan.org/>
+by Henry Spencer.
+.SH BUGS
+It's not nearly as generous about the syntax of subnets,
+addresses, etc. as the usual FreeS/WAN user interfaces.
+Four-component dotted-decimal must be used for all addresses.
+It
+.I is
+smart enough to translate bit-count netmasks to dotted-decimal form.
+.PP
+If the connection specification for a connection is changed between an
+.B \-\-up
+and the ensuing
+.BR \-\-down ,
+chaos may ensue.
+.PP
+The
+.B \-\-up
+operation is not smart enough to notice whether the connection is already up.
+.PP
+.I Manual
+is not smart enough to reject insecure combinations of algorithms,
+e.g. encryption with no authentication at all.
+.PP
+Any non-IPsec route to the other end which is replaced by the
+.B \-\-up
+or
+.B \-\-route
+operation will not be re-established by
+.BR \-\-unroute .
+Whether this is a feature or a bug depends on your viewpoint.
+.PP
+The optional parameters which
+override the automatic
+.BR spibase -based
+SPI assignment are a messy area of the code and bugs are likely.
+.PP
+``Road warrior'' handling,
+and other special forms of setup which
+require negotiation between the two security gateways,
+inherently cannot be done with
+.IR manual .
+.PP
+.I Manual
+generally lags behind
+.I auto
+in support of various features,
+even when implementation \fIwould\fR be possible.
+For example, currently it does not do IPComp content compression.