Imported Upstream version 5.0.1

1 files changed, 0 insertions, 1594 deletions

diff --git a/src/pluto/pluto.8 b/src/pluto/pluto.8
deleted file mode 100644
index ed6f78050..000000000
--- a/src/pluto/pluto.8
+++ /dev/null
@@ -1,1594 +0,0 @@
-.TH IPSEC_PLUTO 8 "28 March 1999"
-.SH NAME
-pluto \- IPsec IKE keying daemon and control interface
-.PP
-whack \- control interface for IKE keying daemon
-.SH SYNOPSIS
-.na
-.nh
-.HP
-.ft B
-ipsec pluto
-[\-\-help]
-[\-\-version]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-nofork]
-[\-\-stderrlog]
-[\-\-uniqueids]
-[\fB\-\-interface\fP \fIinterfacename\fP]
-[\-\-ikeport\ \c
-\fIportnumber\fP]
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-secretsfile\ \c
-\fIsecrets\(hyfile\fP]
-[\-\-adns \fIpathname\fP]
-[\-\-lwdnsq \fIpathname\fP]
-[\-\-perpeerlog]
-[\-\-perpeerlogbase\ \c
-\fIdirname\fP]
-[\-\-debug\(hynone]
-[\-\-debug\(hyall]
-[\-\-debug\(hyraw]
-[\-\-debug\(hycrypt]
-[\-\-debug\(hyparsing]
-[\-\-debug\(hyemitting]
-[\-\-debug\(hycontrol]
-[\-\-debug\(hylifecycle]
-[\-\-debug\(hykernel]
-[\-\-debug\(hydns]
-[\-\-debug\(hyoppo]
-[\-\-debug\(hyprivate]
-.HP
-.ft B
-ipsec whack
-[\-\-help]
-[\-\-version]
-.HP
-.ft B
-ipsec whack
-\-\-name\ \c
-\fIconnection-name\fP
-.br
-[\-\-id\ \c
-\fIid\fP] \c
-[\-\-host\ \c
-\fIip\(hyaddress\fP]
-[\-\-ikeport\ \c
-\fIport\(hynumber\fP]
-[\-\-nexthop\ \c
-\fIip\(hyaddress\fP]
-[\-\-client\ \c
-\fIsubnet\fP]
-[\-\-dnskeyondemand]
-[\-\-updown\ \c
-\fIupdown\fP]
-.br
-\-\-to
-.br
-[\-\-id\ \c
-\fIid\fP]
-[\-\-host\ \c
-\fIip\(hyaddress\fP]
-[\-\-ikeport\ \c
-\fIport\(hynumber\fP]
-[\-\-nexthop\ \c
-\fIip\(hyaddress\fP]
-[\-\-client\ \c
-\fIsubnet\fP]
-[\-\-dnskeyondemand]
-[\-\-updown\ \c
-\fIupdown\fP]
-.br
-[\-\-psk]
-[\-\-rsasig]
-[\-\-encrypt]
-[\-\-authenticate]
-[\-\-compress]
-[\-\-tunnel]
-[\-\-pfs]
-[\-\-disablearrivalcheck]
-[\-\-ipv4]
-[\-\-ipv6]
-[\-\-tunnelipv4]
-[\-\-tunnelipv6]
-[\-\-ikelifetime\ \c
-\fIseconds\fP]
-[\-\-ipseclifetime\ \c
-\fIseconds\fP]
-[\-\-rekeymargin\ \c
-\fIseconds\fP]
-[\-\-rekeyfuzz\ \c
-\fIpercentage\fP]
-[\-\-keyingtries\ \c
-\fIcount\fP]
-[\-\-dontrekey]
-[\-\-delete]
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-label\ \c
-\fIstring\fP]
-.HP
-.ft B
-ipsec whack
-\-\-keyid\ \c
-\fIid\fP
-[\-\-addkey]
-[\-\-pubkeyrsa\ \c
-\fIkey\fP]
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-label\ \c
-\fIstring\fP]
-.HP
-.ft B
-ipsec whack
-\-\-myid\ \c
-\fIid\fP
-.HP
-.ft B
-ipsec whack
-\-\-listen|\-\-unlisten
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-label\ \c
-\fIstring\fP]
-.HP
-.ft B
-ipsec whack
-\-\-route|\-\-unroute
-\-\-name\ \c
-\fIconnection-name\fP
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-label\ \c
-\fIstring\fP]
-.HP
-.ft B
-ipsec whack
-\-\-initiate|\-\-terminate
-\-\-name\ \c
-\fIconnection-name\fP
-[\-\-asynchronous]
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-label\ \c
-\fIstring\fP]
-.HP
-.ft B
-ipsec whack
-[\-\-tunnelipv4]
-[\-\-tunnelipv6]
-\-\-oppohere \fIip\(hyaddress\fP
-\-\-oppothere \fIip\(hyaddress\fP
-.HP
-.ft B
-ipsec whack
-\-\-delete
-\-\-name\ \c
-\fIconnection-name\fP
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-label\ \c
-\fIstring\fP]
-.HP
-.ft B
-ipsec whack
-\-\-deletestate\ \c
-\fIstate-number\fP
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-label\ \c
-\fIstring\fP]
-.HP
-.ft B
-ipsec whack
-[\-\-name\ \c
-\fIconnection-name\fP]
-[\-\-debug\(hynone]
-[\-\-debug\(hyall]
-[\-\-debug\(hyraw]
-[\-\-debug\(hycrypt]
-[\-\-debug\(hyparsing]
-[\-\-debug\(hyemitting]
-[\-\-debug\(hycontrol]
-[\-\-debug\(hylifecycle]
-[\-\-debug\(hykernel]
-[\-\-debug\(hydns]
-[\-\-debug\(hyoppo]
-[\-\-debug\(hyprivate]
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-label\ \c
-\fIstring\fP]
-.HP
-.ft B
-ipsec whack
-\-\-status
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-label\ \c
-\fIstring\fP]
-.HP
-.ft B
-ipsec whack
-\-\-shutdown
-[\-\-ctlbase\ \c
-\fIpath\fP]
-[\-\-optionsfrom\ \c
-\fIfilename\fP]
-[\-\-label\ \c
-\fIstring\fP]
-.ft R
-.hy
-.ad
-.SH DESCRIPTION
-.BR pluto
-is an IKE (``IPsec Key Exchange'') daemon.
-.BR whack
-is an auxiliary program to allow requests to be made to a running
-.BR pluto .
-.LP
-.BR pluto
-is used to automatically build shared ``security associations'' on a
-system that has IPsec, the secure IP protocol.
-In other words,
-.BR pluto
-can eliminate much of the work of manual keying.
-The actual
-secure transmission of packets is the responsibility of the Linux kernel.
-\fIipsec_auto\fP(8) provides a more convenient interface to
-\fBpluto\fP and \fBwhack\fP.
-.SS IKE's Job
-.LP
-A \fISecurity Association\fP (\fISA\fP) is an agreement between two network nodes on
-how to process certain traffic between them.  This processing involves
-encapsulation, authentication, encryption, or compression.
-.LP
-IKE can be deployed on a network node to negotiate Security
-Associations for that node.  These IKE implementations can only
-negotiate with other IKE implementations, so IKE must be on each node
-that is to be an endpoint of an IKE-negotiated Security Association.
-No other nodes need to be running IKE.
-.LP
-An IKE instance (i.e. an IKE implementation on a particular network
-node) communicates with another IKE instance using UDP IP packets, so
-there must be a route between the nodes in each direction.
-.LP
-The negotiation of Security Associations requires a number of choices
-that involve tradeoffs between security, convenience, trust, and
-efficiency.  These are policy issues and are normally specified to the
-IKE instance by the system administrator.
-.LP
-IKE deals with two kinds of Security Associations.  The first part of
-a negotiation between IKE instances is to build an ISAKMP SA.  An
-ISAKMP SA is used to protect communication between the two IKEs.
-IPsec SAs can then be built by the IKEs \- these are used to carry
-protected IP traffic between the systems.
-.LP
-The negotiation of the ISAKMP SA is known as Phase 1.  In theory,
-Phase 1 can be accomplished by a couple of different exchange types,
-but we only implement one called Main Mode (we don't implement
-Aggressive Mode).
-.LP
-Any negotiation under the protection of an ISAKMP SA, including the
-negotiation of IPsec SAs, is part of Phase 2.  The exchange type
-that we use to negotiate an IPsec SA is called Quick Mode.
-.LP
-IKE instances must be able to authenticate each other as part of their
-negotiation of an ISAKMP SA.  This can be done by several mechanisms
-described in the draft standards.
-.LP
-IKE negotiation can be initiated by any instance with any other.  If
-both can find an agreeable set of characteristics for a Security
-Association, and both recognize each others authenticity, they can set
-up a Security Association.  The standards do not specify what causes
-an IKE instance to initiate a negotiation.
-.LP
-In summary, an IKE instance is prepared to automate the management of
-Security Associations in an IPsec environment, but a number of issues
-are considered policy and are left in the system administrator's hands.
-.SS Pluto
-.LP
-\fBpluto\fP is an implementation of IKE.  It runs as a daemon on a network
-node.  Currently, this network node must be a Linux 2.6 system running the
-native \fBNETKEY\fP IPsec stack.
-.LP
-\fBpluto\fP only implements a subset of IKE.  This is enough for it to
-interoperate with other instances of \fBpluto\fP, and many other IKE
-implementations.  We are working on implementing more of IKE.
-.LP
-The policy for acceptable characteristics for Security Associations is
-mostly hardwired into the code of \fBpluto\fP (spdb.c).  Eventually
-this will be moved into a security policy database with reasonable
-expressive power and more convenience.
-.LP
-\fBpluto\fP uses shared secrets or RSA signatures to authenticate
-peers with whom it is negotiating.
-.LP
-\fBpluto\fP initiates negotiation of a Security Association when it is
-manually prodded: the program \fBwhack\fP is run to trigger this.
-It will also initiate a negotiation when the Linux kernel traps an outbound
-packet for Opportunistic Encryption.
-.LP
-\fBpluto\fP implements ISAKMP SAs itself.  After it has negotiated the
-characteristics of an IPsec SA, it directs the Linux kernel to implement it.
-It also invokes a script to adjust any firewall and issue \fIroute\fP(8)
-commands.
-.LP
-When \fBpluto\fP shuts down, it closes all Security Associations.
-.SS Before Running Pluto
-.LP
-\fBpluto\fP runs as a daemon with userid root.  Before running it, a few
-things must be set up.
-.LP
-\fBpluto\fP requires a Linux 2.6 kernel with the modules for the native IPsec
-stack enabled.
-.LP
-\fBpluto\fP supports multiple public networks (that is, networks
-that are considered insecure and thus need to have their traffic
-encrypted or authenticated).  It discovers the
-public interfaces to use by looking at all interfaces that are
-configured (the \fB\-\-interface\fP option can be used to limit
-the interfaces considered).
-It does this only when \fBwhack\fP tells it to \-\-listen,
-so the interfaces must be configured by then.
-\fIifconfig\fP(8) with the \fB\-a\fP flag will show
-the name and status of each network interface.
-.LP
-\fBpluto\fP requires a database of preshared secrets and RSA private keys.
-This is described in the
-.IR ipsec.secrets (5).
-\fBpluto\fP is told of RSA public keys via \fBwhack\fP commands.
-If the connection is Opportunistic, and no RSA public key is known,
-\fBpluto\fP will attempt to fetch RSA keys using the Domain Name System.
-.SS ipsec.secrets file
-.LP
-A \fBpluto\fP daemon and another IKE daemon (for example, another instance
-of \fBpluto\fP) must convince each other that they are who they are supposed
-to be before any negotiation can succeed.  This authentication is
-accomplished by using either secrets that have been shared beforehand
-(manually) or by using RSA signatures.  There are other techniques,
-but they have not been implemented in \fBpluto\fP.
-.LP
-The file \fI/etc/ipsec.secrets\fP is used to keep preshared secret keys
-and RSA private keys for
-authentication with other IKE daemons.  For debugging, there is an
-argument to the \fBpluto\fP command to use a different file.
-This file is described in
-.IR ipsec.secrets (5).
-.SS Running Pluto
-.LP
-To fire up the daemon, just type \fBpluto\fP (be sure to be running as
-the superuser).
-The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons.
-\fBpluto\fP must be run by the superuser to be able to use the UDP 500 port.
-.LP
-\fBpluto\fP attempts to create a lockfile with the name
-\fI/var/run/pluto.pid\fP.  If the lockfile cannot be created,
-\fBpluto\fP exits \- this prevents multiple \fBpluto\fPs from
-competing  Any ``leftover'' lockfile must be removed before
-\fBpluto\fP will run.  \fBpluto\fP writes its pid into this file so
-that scripts can find it.  This lock will not function properly if it
-is on an NFS volume (but sharing locks on multiple machines doesn't
-make sense anyway).
-.LP
-\fBpluto\fP then forks and the parent exits.  This is the conventional
-``daemon fork''.  It can make debugging awkward, so there is an option
-to suppress this fork.
-.LP
-All logging, including diagnostics, is sent to
-.IR syslog (3)
-with facility=authpriv;
-it decides where to put these messages (possibly in /var/log/secure).
-Since this too can make debugging awkward, there is an option to
-steer logging to stderr.
-.LP
-If the \fB\-\-perpeerlog\fP option is given, then pluto will open
-a log file per connection. By default, this is in /var/log/pluto/peer,
-in a subdirectory formed by turning all dot (.) [IPv4} or colon (:)
-[IPv6] into slashes (/).
-.LP
-The base directory can be changed with the \fB\-\-perpeerlogbase\fP.
-.LP
-Once \fBpluto\fP is started, it waits for requests from \fBwhack\fP.
-.SS Pluto's Internal State
-.LP
-To understand how to use \fBpluto\fP, it is helpful to understand a little
-about its internal state.  Furthermore, the terminology is needed to decipher
-some of the diagnostic messages.
-.LP
-The \fI(potential) connection\fP database describes attributes of a
-connection.  These include the IP addresses of the hosts and client
-subnets and the security characteristics desired.  \fBpluto\fP
-requires this information (simply called a connection) before it can
-respond to a request to build an SA.  Each connection is given a name
-when it is created, and all references are made using this name.
-.LP
-During the IKE exchange to build an SA, the information about the
-negotiation is represented in a \fIstate object\fP.  Each state object
-reflects how far the negotiation has reached.  Once the negotiation is
-complete and the SA established, the state object remains to represent
-the SA.  When the SA is terminated, the state object is discarded.
-Each State object is given a serial number and this is used to refer
-to the state objects in logged messages.
-.LP
-Each state object corresponds to a connection and can be thought of
-as an instantiation of that connection.
-At any particular time, there may be any number of state objects
-corresponding to a particular connection.
-Often there is one representing an ISAKMP SA and another representing
-an IPsec SA.
-.LP
-Each connection may be routed, and must be while it has an IPsec SA.
-The connection specifies the characteristics of the route: the
-interface on this machine, the ``gateway'' (the nexthop),
-and the peer's client subnet.  Two
-connections may not be simultaneously routed if they are for the same
-peer's client subnet but use different interfaces or gateways
-(\fBpluto\fP's logic does not reflect any advanced routing capabilities).
-.LP
-Each eroute is associated with the state object for an IPsec SA
-because it has the particular characteristics of the SA.
-Two eroutes conflict if they specify the identical local
-and remote clients (unlike for routes, the local clients are
-taken into account).
-.LP
-When \fBpluto\fP needs to install a route for a connection,
-it must make sure that no conflicting route is in use.  If another
-connection has a conflicting route, that route will be taken down, as long
-as there is no IPsec SA instantiating that connection.
-If there is such an IPsec SA, the attempt to install a route will fail.
-.LP
-There is an exception.  If \fBpluto\fP, as Responder, needs to install
-a route to a fixed client subnet for a connection, and there is
-already a conflicting route, then the SAs using the route are deleted
-to make room for the new SAs.  The rationale is that the new
-connection is probably more current.  The need for this usually is a
-product of Road Warrior connections (these are explained later; they
-cannot be used to initiate).
-.LP
-When \fBpluto\fP needs to install an eroute for an IPsec SA (for a
-state object), first the state object's connection must be routed (if
-this cannot be done, the eroute and SA will not be installed).
-If a conflicting eroute is already in place for another connection,
-the eroute and SA will not be installed (but note that the routing
-exception mentioned above may have already deleted potentially conflicting SAs).
-If another IPsec
-SA for the same connection already has an eroute, all its outgoing traffic
-is taken over by the new eroute.  The incoming traffic will still be
-processed.  This characteristic is exploited during rekeying.
-.LP
-Some of these routing characteristics are specific to \fBKLIPS\fP, the FreeS/WAN
-implementation of IPsec and are not relevant when running pluto on the native
-Linux 2.6 IPsec stack.
-.SS Using Whack
-.LP
-\fBwhack\fP is used to command a running \fBpluto\fP.
-\fBwhack\fP uses a UNIX domain socket to speak to \fBpluto\fP
-(by default, \fI/var/pluto.ctl\fP).
-.LP
-\fBwhack\fP has an intricate argument syntax.
-This syntax allows many different functions to be specified.
-The help form shows the usage or version information.
-The connection form gives \fBpluto\fP a description of a potential connection.
-The public key form informs \fBpluto\fP of the RSA public key for a potential peer.
-The delete form deletes a connection description and all SAs corresponding
-to it.
-The listen form tells \fBpluto\fP to start or stop listening on the public interfaces
-for IKE requests from peers.
-The route form tells \fBpluto\fP to set up routing for a connection;
-the unroute form undoes this.
-The initiate form tells \fBpluto\fP to negotiate an SA corresponding to a connection.
-The terminate form tells \fBpluto\fP to remove all SAs corresponding to a connection,
-including those being negotiated.
-The status form displays the \fBpluto\fP's internal state.
-The debug form tells \fBpluto\fP to change the selection of debugging output
-``on the fly''.  The shutdown form tells
-\fBpluto\fP to shut down, deleting all SAs.
-.LP
-Most options are specific to one of the forms, and will be described
-with that form.  There are three options that apply to all forms.
-.TP
-\fB\-\-ctlbase\fP\ \fIpath\fP
-\fIpath\fP.ctl is used as the UNIX domain socket for talking
-to \fBpluto\fP.
-This option facilitates debugging.
-.TP
-\fB\-\-optionsfrom\fP\ \fIfilename\fP
-adds the contents of the file to the argument list.
-.TP
-\fB\-\-label\fP\ \fIstring\fP
-adds the string to all error messages generated by \fBwhack\fP.
-.LP
-The help form of \fBwhack\fP is self-explanatory.
-.TP
-\fB\-\-help\fP
-display the usage message.
-.TP
-\fB\-\-version\fP
-display the version of \fBwhack\fP.
-.LP
-The connection form describes a potential connection to \fBpluto\fP.
-\fBpluto\fP needs to know what connections can and should be negotiated.
-When \fBpluto\fP is the initiator, it needs to know what to propose.
-When \fBpluto\fP is the responder, it needs to know enough to decide whether
-is is willing to set up the proposed connection.
-.LP
-The description of a potential connection can specify a large number
-of details.  Each connection has a unique name.  This name will appear
-in a updown shell command, so it should not contain punctuation
-that would make the command ill-formed.
-.TP
-\fB\-\-name\fP\ \fIconnection-name\fP
-.LP
-The topology of
-a connection is symmetric, so to save space here is half a picture:
-
-\ \ \ client_subnet<\-\->host:ikeport<\-\->nexthop<\-\-\-
-
-A similar trick is used in the flags.  The same flag names are used for
-both ends.  Those before the \fB\-\-to\fP flag describe the left side
-and those afterwards describe the right side.  When \fBpluto\fP attempts
-to use the connection, it decides whether it is the left side or the right
-side of the connection, based on the IP numbers of its interfaces.
-.TP
-\fB\-\-id\fP\ \fIid\fP
-the identity of the end.  Currently, this can be an IP address (specified
-as dotted quad or as a Fully Qualified Domain Name, which will be resolved
-immediately) or as a Fully Qualified Domain Name itself (prefixed by ``@''
-to signify that it should not be resolved), or as user@FQDN, or as the
-magic value \fB%myid\fP.
-\fBPluto\fP only authenticates the identity, and does not use it for
-addressing, so, for example, an IP address need not be the one to which
-packets are to be sent.  If the option is absent, the
-identity defaults to the IP address specified by \fB\-\-host\fP.
-\fB%myid\fP allows the identity to be separately specified (by the \fBpluto\fP or \fBwhack\fP option \fB\-\-myid\fP
-or by the \fBipsec.conf\fP(5) \fBconfig setup\fP parameter \fPmyid\fP).
-Otherwise, \fBpluto\fP tries to guess what \fB%myid\fP should stand for:
-the IP address of \fB%defaultroute\fP, if it is supported by a suitable TXT record in the reverse domain for that IP address,
-or the system's hostname, if it is supported by a suitable TXT record in its forward domain.
-.\" The identity is transmitted in the IKE protocol, and is what is authenticated.
-.TP
-\fB\-\-host\fP\ \fIip\(hyaddress\fP
-.TP
-\fB\-\-host\fP\ \fB%any\fP
-.TP
-\fB\-\-host\fP\ \fB%opportunistic\fP
-the IP address of the end (generally the public interface).
-If \fBpluto\fP is to act as a responder
-for IKE negotiations initiated from unknown IP addresses (the
-``Road Warrior'' case), the
-IP address should be specified as \fB%any\fP (currently,
-the obsolete notation \fB0.0.0.0\fP is also accepted for this).
-If \fBpluto\fP is to opportunistically initiate the connection,
-use \fB%opportunistic\fP
-.TP
-\fB\-\-ikeport\fP\ \fIport\(hynumber\fP
-the UDP port that IKE listens to on that host.  The default is 500.
-(\fBpluto\fP on this machine uses the port specified by its own command
-line argument, so this only affects where \fBpluto\fP sends messages.)
-.TP
-\fB\-\-nexthop\fP\ \fIip\(hyaddress\fP
-where to route packets for the peer's client (presumably for the peer too,
-but it will not be used for this).
-When \fBpluto\fP installs an IPsec SA, it issues a route command.
-It uses the nexthop as the gateway.
-The default is the peer's IP address (this can be explicitly written as
-\fB%direct\fP; the obsolete notation \fB0.0.0.0\fP is accepted).
-This option is necessary if \fBpluto\fP's host's interface used for sending
-packets to the peer is neither point-to-point nor directly connected to the
-peer.
-.TP
-\fB\-\-client\fP\ \fIsubnet\fP
-the subnet for which the IPsec traffic will be destined.  If not specified,
-the host will be the client.
-The subnet can be specified in any of the forms supported by \fIipsec_atosubnet\fP(3).
-The general form is \fIaddress\fP/\fImask\fP.  The \fIaddress\fP can be either
-a domain name or four decimal numbers (specifying octets) separated by dots.
-The most convenient form of the \fImask\fP is a decimal integer, specifying
-the number of leading one bits in the mask.  So, for example, 10.0.0.0/8
-would specify the class A network ``Net 10''.
-.TP
-\fB\-\-dnskeyondemand]\fP
-specifies that when an RSA public key is needed to authenticate this
-host, and it isn't already known, fetch it from DNS.
-.TP
-\fB\-\-updown\fP\ \fIupdown\fP
-specifies an external shell command to be run whenever \fBpluto\fP
-brings up or down a connection.
-The script is used to build a shell command, so it may contain positional
-parameters, but ought not to have punctuation that would cause the
-resulting command to be ill-formed.
-The default is \fIipsec _updown\fP.
-.TP
-\fB\-\-to\fP
-separates the specification of the left and right ends of the connection.
-.LP
-The potential connection description also specifies characteristics of
-rekeying and security.
-.TP
-\fB\-\-psk\fP
-Propose and allow preshared secret authentication for IKE peers.  This authentication
-requires that each side use the same secret.  May be combined with \fB\-\-rsasig\fP;
-at least one must be specified.
-.TP
-\fB\-\-rsasig\fP
-Propose and allow RSA signatures for authentication of IKE peers.  This authentication
-requires that each side have have a private key of its own and know the
-public key of its peer.  May be combined with \fB\-\-psk\fP;
-at least one must be specified.
-.TP
-\fB\-\-encrypt\fP
-All proposed or accepted IPsec SAs will include non-null ESP.
-The actual choices of transforms are wired into \fBpluto\fP.
-.TP
-\fB\-\-authenticate\fP
-All proposed IPsec SAs will include AH.
-All accepted IPsec SAs will include AH or ESP with authentication.
-The actual choices of transforms are wired into \fBpluto\fP.
-Note that this has nothing to do with IKE authentication.
-.TP
-\fB\-\-compress\fP
-All proposed IPsec SAs will include IPCOMP (compression).
-This will be ignored if the kernel is not configured with IPCOMP support.
-.TP
-\fB\-\-tunnel\fP
-the IPsec SA should use tunneling.  Implicit if the SA is for clients.
-Must only be used with \fB\-\-authenticate\fP or \fB\-\-encrypt\fP.
-.TP
-\fB\-\-ipv4\fP
-The host addresses will be interpreted as IPv4 addresses.  This is the
-default.  Note that for a connection, all host addresses must be of
-the same Address Family (IPv4 and IPv6 use different Address Families).
-.TP
-\fB\-\-ipv6\fP
-The host addresses (including nexthop) will be interpreted as IPv6 addresses.
-Note that for a connection, all host addresses must be of
-the same Address Family (IPv4 and IPv6 use different Address Families).
-.TP
-\fB\-\-tunnelipv4\fP
-The client addresses will be interpreted as IPv4 addresses.  The default is
-to match what the host will be.  This does not imply \fB\-\-tunnel\fP so the
-flag can be safely used when no tunnel is actually specified.
-Note that for a connection, all tunnel addresses must be of the same
-Address Family.
-.TP
-\fB\-\-tunnelipv6\fP
-The client addresses will be interpreted as IPv6 addresses.  The default is
-to match what the host will be.  This does not imply \fB\-\-tunnel\fP so the
-flag can be safely used when no tunnel is actually specified.
-Note that for a connection, all tunnel addresses must be of the same
-Address Family.
-.TP
-\fB\-\-pfs\fP
-There should be Perfect Forward Secrecy \- new keying material will
-be generated for each IPsec SA rather than being derived from the ISAKMP
-SA keying material.
-Since the group to be used cannot be negotiated (a dubious feature of the
-standard), \fBpluto\fP will propose the same group that was used during Phase 1.
-We don't implement a stronger form of PFS which would require that the
-ISAKMP SA be deleted after the IPSEC SA is negotiated.
-.TP
-\fB\-\-disablearrivalcheck\fP
-If the connection is a tunnel, allow packets arriving through the tunnel
-to have any source and destination addresses.
-.LP
-If none of the \fB\-\-encrypt\fP, \fB\-\-authenticate\fP, \fB\-\-compress\fP,
-or \fB\-\-pfs\fP flags is given, the initiating the connection will
-only build an ISAKMP SA.  For such a connection, client subnets have
-no meaning and must not be specified.
-.LP
-More work is needed to allow for flexible policies.  Currently
-policy is hardwired in the source file spdb.c.  The ISAKMP SAs may use
-Oakley groups MODP1024 and MODP1536; 3DES encryption; SHA1-96
-and MD5-96 authentication.  The IPsec SAs may use 3DES and
-MD5-96 or SHA1-96 for ESP, or just MD5-96 or SHA1-96 for AH.
-IPCOMP Compression is always Deflate.
-.TP
-\fB\-\-ikelifetime\fP\ \fIseconds\fP
-how long \fBpluto\fP will propose that an ISAKMP SA be allowed to live.
-The default is 10800 (three hours) and the maximum is 86400 (one day).
-This option will not affect what is accepted.
-\fBpluto\fP will reject proposals that exceed the maximum.
-.TP
-\fB\-\-ipseclifetime\fP\ \fIseconds\fP
-how long \fBpluto\fP will propose that an IPsec SA be allowed to live.
-The default is 3600 (one hour) and the maximum is 86400 (one day).
-This option will not affect what is accepted.
-\fBpluto\fP will reject proposals that exceed the maximum.
-.TP
-\fB\-\-rekeymargin\fP\ \fIseconds\fP
-how long before an SA's expiration should \fBpluto\fP try to negotiate
-a replacement SA.  This will only happen if \fBpluto\fP was the initiator.
-The default is 540 (nine minutes).
-.TP
-\fB\-\-rekeyfuzz\fP\ \fIpercentage\fP
-maximum size of random component to add to rekeymargin, expressed as
-a percentage of rekeymargin.  \fBpluto\fP will select a delay uniformly
-distributed within this range.  By default, the percentage will be 100.
-If greater determinism is desired, specify 0.  It may be appropriate
-for the percentage to be much larger than 100.
-.TP
-\fB\-\-keyingtries\fP\ \fIcount\fP
-how many times \fBpluto\fP should try to negotiate an SA,
-either for the first time or for rekeying.
-A value of 0 is interpreted as a very large number: never give up.
-The default is three.
-.TP
-\fB\-\-dontrekey\fP
-A misnomer.
-Only rekey a connection if we were the Initiator and there was recent
-traffic on the existing connection.
-This applies to Phase 1 and Phase 2.
-This is currently the only automatic way for a connection to terminate.
-It may be useful with Road Warrior or Opportunistic connections.
-.br
-Since SA lifetime negotiation is take-it-or-leave it, a Responder
-normally uses the shorter of the negotiated or the configured lifetime.
-This only works because if the lifetime is shorter than negotiated,
-the Responder will rekey in time so that everything works.
-This interacts badly with \fB\-\-dontrekey\fP.  In this case,
-the Responder will end up rekeying to rectify a shortfall in an IPsec SA
-lifetime; for an ISAKMP SA, the Responder will accept the negotiated
-lifetime.
-.TP
-\fB\-\-delete\fP
-when used in the connection form, it causes any previous connection
-with this name to be deleted before this one is added.  Unlike a
-normal delete, no diagnostic is produced if there was no previous
-connection to delete.  Any routing in place for the connection is undone.
-.LP
-The delete form deletes a named connection description and any
-SAs established or negotiations initiated using this connection.
-Any routing in place for the connection is undone.
-.TP
-\fB\-\-delete\fP
-.TP
-\fB\-\-name\fP\ \fIconnection-name\fP
-.LP
-The deletestate form deletes the state object with the specified serial number.
-This is useful for selectively deleting instances of connections.
-.TP
-\fB\-\-deletestate\fP\ \fIstate-number\fP
-.LP
-The route form of the \fBwhack\fP command tells \fBpluto\fP to set up
-routing for a connection.
-Although like a traditional route, it uses an ipsec device as a
-virtual interface.
-Once routing is set up, no packets will be
-sent ``in the clear'' to the peer's client specified in the connection.
-A TRAP shunt eroute will be installed; if outbound traffic is caught,
-Pluto will initiate the connection.
-An explicit \fBwhack\fP route is not always needed: if it hasn't been
-done when an IPsec SA is being installed, one will be automatically attempted.
-.LP
-When a routing is attempted for a connection, there must not already
-be a routing for a different connection with the same subnet but different
-interface or destination, or if
-there is, it must not be being used by an IPsec SA.  Otherwise the
-attempt will fail.
-.TP
-\fB\-\-route\fP
-.TP
-\fB\-\-name\fP\ \fIconnection-name\fP
-.LP
-The unroute form of the \fBwhack\fP command tells \fBpluto\fP to undo
-a routing.  \fBpluto\fP will refuse if an IPsec SA is using the connection.
-If another connection is sharing the same routing, it will be left in place.
-Without a routing, packets will be sent without encryption or authentication.
-.TP
-\fB\-\-unroute\fP
-.TP
-\fB\-\-name\fP\ \fIconnection-name\fP
-.LP
-The initiate form tells \fBpluto\fP to initiate a negotiation with another
-\fBpluto\fP (or other IKE daemon) according to the named connection.
-Initiation requires a route that \fB\-\-route\fP would provide;
-if none is in place at the time an IPsec SA is being installed,
-\fBpluto\fP attempts to set one up.
-.TP
-\fB\-\-initiate\fP
-.TP
-\fB\-\-name\fP\ \fIconnection-name\fP
-.TP
-\fB\-\-asynchronous
-.LP
-The initiate form of the \fBwhack\fP command will relay back from
-\fBpluto\fP status information via the UNIX domain socket (unless
-\-\-asynchronous is specified).  The status information is meant to
-look a bit like that from \fBFTP\fP.  Currently \fBwhack\fP simply
-copies this to stderr.  When the request is finished (eg. the SAs are
-established or \fBpluto\fP gives up), \fBpluto\fP closes the channel,
-causing \fBwhack\fP to terminate.
-.LP
-The opportunistic initiate form is mainly used for debugging.
-.TP
-\fB\-\-tunnelipv4\fP
-.TP
-\fB\-\-tunnelipv6\fP
-.TP
-\fB\-\-oppohere\fP\ \fIip-address\fP
-.TP
-\fB\-\-oppothere\fP\ \fIip-address\fP
-.LP
-This will cause \fBpluto\fP to attempt to opportunistically initiate a
-connection from here to the there, even if a previous attempt
-had been made.
-The whack log will show the progress of this attempt.
-.LP
-The terminate form tells \fBpluto\fP to delete any SAs that use the specified
-connection and to stop any negotiations in process.
-It does not prevent new negotiations from starting (the delete form
-has this effect).
-.TP
-\fB\-\-terminate\fP
-.TP
-\fB\-\-name\fP\ \fIconnection-name\fP
-.LP
-The public key for informs \fBpluto\fP of the RSA public key for a potential peer.
-Private keys must be kept secret, so they are kept in
-.IR ipsec.secrets (5).
-.TP
-\fB\-\-keyid\ \fP\fIid\fP
-specififies the identity of the peer for which a public key should be used.
-Its form is identical to the identity in the connection.
-If no public key is specified, \fBpluto\fP attempts to find KEY records
-from DNS for the id (if a FQDN) or through reverse lookup (if an IP address).
-Note that there several interesting ways in which this is not secure.
-.TP
-\fB\-\-addkey\fP
-specifies that the new key is added to the collection; otherwise the
-new key replaces any old ones.
-.TP
-\fB\-\-pubkeyrsa\ \fP\fIkey\fP
-specifies the value of the RSA public key.  It is a sequence of bytes
-as described in RFC 2537 ``RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)''.
-It is denoted in a way suitable for \fIipsec_ttodata\fP(3).
-For example, a base 64 numeral starts with 0s.
-.LP
-The listen form tells \fBpluto\fP to start listening for IKE requests
-on its public interfaces.  To avoid race conditions, it is normal to
-load the appropriate connections into \fBpluto\fP before allowing it
-to listen.  If \fBpluto\fP isn't listening, it is pointless to
-initiate negotiations, so it will refuse requests to do so.  Whenever
-the listen form is used, \fBpluto\fP looks for public interfaces and
-will notice when new ones have been added and when old ones have been
-removed.  This is also the trigger for \fBpluto\fP to read the
-\fIipsec.secrets\fP file.  So listen may useful more than once.
-.TP
-\fB\-\-listen\fP
-start listening for IKE traffic on public interfaces.
-.TP
-\fB\-\-unlisten\fP
-stop listening for IKE traffic on public interfaces.
-.LP
-The status form will display information about the internal state of
-\fBpluto\fP: information about each potential connection, about
-each state object, and about each shunt that \fBpluto\fP is managing
-without an associated connection.
-.TP
-\fB\-\-status\fP
-.LP
-The shutdown form is the proper way to shut down \fBpluto\fP.
-It will tear down the SAs on this machine that \fBpluto\fP has negotiated.
-It does not inform its peers, so the SAs on their machines remain.
-.TP
-\fB\-\-shutdown\fP
-.SS Examples
-.LP
-It would be normal to start \fBpluto\fP in one of the system initialization
-scripts.  It needs to be run by the superuser.  Generally, no arguments are needed.
-To run in manually, the superuser can simply type
-
-\ \ \ ipsec pluto
-
-The command will immediately return, but a \fBpluto\fP process will be left
-running, waiting for requests from \fBwhack\fP or a peer.
-.LP
-Using \fBwhack\fP, several potential connections would be described:
-.HP
-.na
-\ \ \ ipsec whack \-\-name\ silly
-\-\-host\ 127.0.0.1 \-\-to \-\-host\ 127.0.0.2
-\-\-ikelifetime\ 900 \-\-ipseclifetime\ 800 \-\-keyingtries\ 3
-.ad
-.LP
-Since this silly connection description specifies neither encryption,
-authentication, nor tunneling, it could only be used to establish
-an ISAKMP SA.
-.HP
-.na
-\ \ \ ipsec whack \-\-name\ secret \-\-host\ 10.0.0.1 \-\-client\ 10.0.1.0/24
-\-\-to \-\-host\ 10.0.0.2 \-\-client\ 10.0.2.0/24
-\-\-encrypt
-.ad
-.LP
-This is something that must be done on both sides.  If the other
-side is \fBpluto\fP, the same \fBwhack\fP command could be used on it
-(the command syntax is designed to not distinguish which end is ours).
-.LP
-Now that the connections are specified, \fBpluto\fP is ready to handle
-requests and replies via the public interfaces.  We must tell it to discover
-those interfaces and start accepting messages from peers:
-
-\ \ \ ipsec whack \-\-listen
-.LP
-If we don't immediately wish to bring up a secure connection between
-the two clients, we might wish to prevent insecure traffic.
-The routing form asks \fBpluto\fP to cause the packets sent from
-our client to the peer's client to be routed through the ipsec0
-device; if there is no SA, they will be discarded:
-
-\ \ \ ipsec whack \-\-route secret
-.LP
-Finally, we are ready to get \fBpluto\fP to initiate negotiation
-for an IPsec SA (and implicitly, an ISAKMP SA):
-
-\ \ \ ipsec whack \-\-initiate\ \-\-name\ secret
-
-A small log of interesting events will appear on standard output
-(other logging is sent to syslog).
-.LP
-\fBwhack\fP can also be used to terminate \fBpluto\fP cleanly, tearing down
-all SAs that it has negotiated.
-
-\ \ \ ipsec whack \-\-shutdown
-
-Notification of any IPSEC SA deletion, but not ISAKMP SA deletion
-is sent to the peer.  Unfortunately, such Notification is not reliable.
-Furthermore, \fBpluto\fP itself ignores Notifications.
-.SS The updown command
-.LP
-Whenever \fBpluto\fP brings a connection up or down, it invokes
-the updown command.  This command is specified using the \fB\-\-updown\fP
-option.  This allows for customized control over routing and firewall manipulation.
-.LP
-The updown is invoked for five different operations.  Each of
-these operations can be for our client subnet or for our host itself.
-.TP
-\fBprepare-host\fP or \fBprepare-client\fP
-is run before bringing up a new connection if no other connection
-with the same clients is up.  Generally, this is useful for deleting a
-route that might have been set up before \fBpluto\fP was run or
-perhaps by some agent not known to \fBpluto\fP.
-.TP
-\fBroute-host\fP or \fBroute-client\fP
-is run when bringing up a connection for a new peer client subnet
-(even if \fBprepare-host\fP or \fBprepare-client\fP was run).  The
-command should install a suitable route.  Routing decisions are based
-only on the destination (peer's client) subnet address, unlike eroutes
-which discriminate based on source too.
-.TP
-\fBunroute-host\fP or \fBunroute-client\fP
-is run when bringing down the last connection for a particular peer
-client subnet.  It should undo what the \fBroute-host\fP or \fBroute-client\fP
-did.
-.TP
-\fBup-host\fP or \fBup-client\fP
-is run when bringing up a tunnel eroute with a pair of client subnets
-that does not already have a tunnel eroute.
-This command should install firewall rules as appropriate.
-It is generally a good idea to allow IKE messages (UDP port 500)
-travel between the hosts.
-.TP
-\fBdown-host\fP or \fBdown-client\fP
-is run when bringing down the eroute for a pair of client subnets.
-This command should delete firewall rules as appropriate.  Note that
-there may remain some inbound IPsec SAs with these client subnets.
-.LP
-The script is passed a large number of environment variables to specify
-what needs to be done.
-.TP
-\fBPLUTO_VERSION\fP
-indicates what version of this interface is being used.  This document
-describes version 1.1.  This is upwardly compatible with version 1.0.
-.TP
-\fBPLUTO_VERB\fP
-specifies the name of the operation to be performed
-(\fBprepare-host\fP,r \fBprepare-client\fP,
-\fBup-host\fP, \fBup-client\fP,
-\fBdown-host\fP, or \fBdown-client\fP).  If the address family for
-security gateway to security gateway communications is IPv6, then
-a suffix of \-v6 is added to the verb.
-.TP
-\fBPLUTO_CONNECTION\fP
-is the name of the connection for which we are routing.
-.TP
-\fBPLUTO_NEXT_HOP\fP
-is the next hop to which packets bound for the peer must be sent.
-.TP
-\fBPLUTO_INTERFACE\fP
-is the name of the ipsec interface to be used.
-.TP
-\fBPLUTO_ME\fP
-is the IP address of our host.
-.TP
-\fBPLUTO_MY_CLIENT\fP
-is the IP address / count of our client subnet.
-If the client is just the host, this will be the host's own IP address / max
-(where max is 32 for IPv4 and 128 for IPv6).
-.TP
-\fBPLUTO_MY_CLIENT_NET\fP
-is the IP address of our client net.
-If the client is just the host, this will be the host's own IP address.
-.TP
-\fBPLUTO_MY_CLIENT_MASK\fP
-is the mask for our client net.
-If the client is just the host, this will be 255.255.255.255.
-.TP
-\fBPLUTO_PEER\fP
-is the IP address of our peer.
-.TP
-\fBPLUTO_PEER_CLIENT\fP
-is the IP address / count of the peer's client subnet.
-If the client is just the peer, this will be the peer's own IP address / max
-(where max is 32 for IPv4 and 128 for IPv6).
-.TP
-\fBPLUTO_PEER_CLIENT_NET\fP
-is the IP address of the peer's client net.
-If the client is just the peer, this will be the peer's own IP address.
-.TP
-\fBPLUTO_PEER_CLIENT_MASK\fP
-is the mask for the peer's client net.
-If the client is just the peer, this will be 255.255.255.255.
-.LP
-All output sent by the script to stderr or stdout is logged.  The
-script should return an exit status of 0 if and only if it succeeds.
-.LP
-\fBPluto\fP waits for the script to finish and will not do any other
-processing while it is waiting.
-The script may assume that \fBpluto\fP will not change anything
-while the script runs.
-The script should avoid doing anything that takes much time and it
-should not issue any command that requires processing by \fBpluto\fP.
-Either of these activities could be performed by a background
-subprocess of the script.
-.SS Rekeying
-.LP
-When an SA that was initiated by \fBpluto\fP has only a bit of
-lifetime left,
-\fBpluto\fP will initiate the creation of a new SA.  This applies to
-ISAKMP and IPsec SAs.
-The rekeying will be initiated when the SA's remaining lifetime is
-less than the rekeymargin plus a random percentage, between 0 and
-rekeyfuzz, of the rekeymargin.
-.LP
-Similarly, when an SA that was initiated by the peer has only a bit of
-lifetime left, \fBpluto\fP will try to initiate the creation of a
-replacement.
-To give preference to the initiator, this rekeying will only be initiated
-when the SA's remaining lifetime is half of rekeymargin.
-If rekeying is done by the responder, the roles will be reversed: the
-responder for the old SA will be the initiator for the replacement.
-The former initiator might also initiate rekeying, so there may
-be redundant SAs created.
-To avoid these complications, make sure that rekeymargin is generous.
-.LP
-One risk of having the former responder initiate is that perhaps
-none of its proposals is acceptable to the former initiator
-(they have not been used in a successful negotiation).
-To reduce the chances of this happening, and to prevent loss of security,
-the policy settings are taken from the old SA (this is the case even if
-the former initiator is initiating).
-These may be stricter than those of the connection.
-.LP
-\fBpluto\fP will not rekey an SA if that SA is not the most recent of its
-type (IPsec or ISAKMP) for its potential connection.
-This avoids creating redundant SAs.
-.LP
-The random component in the rekeying time (rekeyfuzz) is intended to
-make certain pathological patterns of rekeying unstable.  If both
-sides decide to rekey at the same time, twice as many SAs as necessary
-are created.  This could become a stable pattern without the
-randomness.
-.LP
-Another more important case occurs when a security gateway has SAs
-with many other security gateways.  Each of these connections might
-need to be rekeyed at the same time.  This would cause a high peek
-requirement for resources (network bandwidth, CPU time, entropy for
-random numbers).  The rekeyfuzz can be used to stagger the rekeying
-times.
-.LP
-Once a new set of SAs has been negotiated, \fBpluto\fP will never send
-traffic on a superseded one.  Traffic will be accepted on an old SA
-until it expires.
-.SS Selecting a Connection When Responding: Road Warrior Support
-.LP
-When \fBpluto\fP receives an initial Main Mode message, it needs to
-decide which connection this message is for.  It picks based solely on
-the source and destination IP addresses of the message.  There might
-be several connections with suitable IP addresses, in which case one
-of them is arbitrarily chosen.  (The ISAKMP SA proposal contained in
-the message could be taken into account, but it is not.)
-.LP
-The ISAKMP SA is negotiated before the parties pass further
-identifying information, so all ISAKMP SA characteristics specified in
-the connection description should be the same for every connection
-with the same two host IP addresses.  At the moment, the only
-characteristic that might differ is authentication method.
-.LP
-Up to this point,
-all configuring has presumed that the IP addresses
-are known to all parties ahead of time.  This will not work
-when either end is mobile (or assigned a dynamic IP address for other
-reasons).  We call this situation ``Road Warrior''.  It is fairly tricky
-and has some important limitations, most of which are features of
-the IKE protocol.
-.LP
-Only the initiator may be mobile:
-the initiator may have an IP number unknown to the responder.  When
-the responder doesn't recognize the IP address on the first Main Mode
-packet, it looks for a connection with itself as one end and \fB%any\fP
-as the other.
-If it cannot find one, it refuses to negotiate.  If it
-does find one, it creates a temporary connection that is a duplicate
-except with the \fB%any\fP replaced by the source IP address from the
-packet; if there was no identity specified for the peer, the new IP
-address will be used.
-.LP
-When \fBpluto\fP is using one of these temporary connections and
-needs to find the preshared secret or RSA private key in \fIipsec.secrets\fP,
-and and the connection specified no identity for the peer, \fB%any\fP
-is used as its identity.  After all, the real IP address was apparently
-unknown to the configuration, so it is unreasonable to require that
-it be used in this table.
-.LP
-Part way into the Phase 1 (Main Mode) negotiation using one of these
-temporary connection descriptions, \fBpluto\fP will be receive an
-Identity Payload.  At this point, \fBpluto\fP checks for a more
-appropriate connection, one with an identity for the peer that matches
-the payload but which would use the same keys so-far used for
-authentication.  If it finds one, it will switch to using this better
-connection (or a temporary derived from this, if it has \fB%any\fP
-for the peer's IP address).  It may even turn out that no connection
-matches the newly discovered identity, including the current connection;
-if so, \fBpluto\fP terminates negotiation.
-.LP
-Unfortunately, if preshared secret authentication is being used, the
-Identity Payload is encrypted using this secret, so the secret must be
-selected by the responder without knowing this payload.  This
-limits there to being at most one preshared secret for all Road Warrior
-systems connecting to a host.  RSA Signature authentications does not
-require that the responder know how to select the initiator's public key
-until after the initiator's Identity Payload is decoded (using the
-responder's private key, so that must be preselected).
-.LP
-When \fBpluto\fP is responding to a Quick Mode negotiation via one of these
-temporary connection descriptions, it may well find that the subnets
-specified by the initiator don't match those in the temporary
-connection description.  If so, it will look for a connection with
-matching subnets, its own host address, a peer address of \fB%any\fP
-and matching identities.
-If it finds one, a new temporary connection is derived from this one
-and used for the Quick Mode negotiation of IPsec SAs.  If it does not
-find one, \fBpluto\fP terminates negotiation.
-.LP
-Be sure to specify an appropriate nexthop for the responder
-to send a message to the initiator: \fBpluto\fP has no way of guessing
-it (if forwarding isn't required, use an explicit \fB%direct\fP as the nexthop
-and the IP address of the initiator will be filled in; the obsolete
-notation \fB0.0.0.0\fP is still accepted).
-.LP
-\fBpluto\fP has no special provision for the initiator side.  The current
-(possibly dynamic) IP address and nexthop must be used in defining
-connections.  These must be
-properly configured each time the initiator's IP address changes.
-\fBpluto\fP has no mechanism to do this automatically.
-.LP
-Although we call this Road Warrior Support, it could also be used to
-support encrypted connections with anonymous initiators.  The
-responder's organization could announce the preshared secret that would be used
-with unrecognized initiators and let anyone connect.  Of course the initiator's
-identity would not be authenticated.
-.LP
-If any Road Warrior connections are supported, \fBpluto\fP cannot
-reject an exchange initiated by an unknown host until it has
-determined that the secret is not shared or the signature is invalid.
-This must await the
-third Main Mode message from the initiator.  If no Road Warrior
-connection is supported, the first message from an unknown source
-would be rejected.  This has implications for ease of debugging
-configurations and for denial of service attacks.
-.LP
-Although a Road Warrior connection must be initiated by the mobile
-side, the other side can and will rekey using the temporary connection
-it has created.  If the Road Warrior wishes to be able to disconnect,
-it is probably wise to set \fB\-\-keyingtries\fP to 1 in the
-connection on the non-mobile side to prevent it trying to rekey the
-connection.  Unfortunately, there is no mechanism to unroute the
-connection automatically.
-.SS Debugging
-.LP
-\fBpluto\fP accepts several optional arguments, useful mostly for debugging.
-Except for \fB\-\-interface\fP, each should appear at most once.
-.TP
-\fB\-\-interface\fP \fIinterfacename\fP
-specifies that the named real public network interface should be considered.
-The interface name specified should not be \fBipsec\fP\fIN\fP.
-If the option doesn't appear, all interfaces are considered.
-To specify several interfaces, use the option once for each.
-One use of this option is to specify which interface should be used
-when two or more share the same IP address.
-.TP
-\fB\-\-ikeport\fP \fIport-number\fP
-changes the UDP port that \fBpluto\fP will use
-(default, specified by IANA: 500)
-.TP
-\fB\-\-ctlbase\fP \fIpath\fP
-basename for control files.
-\fIpath\fP.ctl is the socket through which \fBwhack\fP communicates with
-\fBpluto\fP.
-\fIpath\fP.pid is the lockfile to prevent multiple \fBpluto\fP instances.
-The default is \fI/var/run/pluto\fP).
-.TP
-\fB\-\-secretsfile\fP \fIfile\fP
-specifies the file for authentication secrets
-(default: \fI/etc/ipsec.secrets\fP).
-This name is subject to ``globbing'' as in \fIsh\fP(1),
-so every file with a matching name is processed.
-Quoting is generally needed to prevent the shell from doing the globbing.
-.TP
-\fB\-\-adns\fP \fIpathname\fP
-.TP
-\fB\-\-lwdnsq\fP \fIpathname\fP
-specifies where to find \fBpluto\fP's helper program for asynchronous DNS lookup.
-\fBpluto\fP can be built to use one of two helper programs: \fB_pluto_adns\fP
-or \fBlwdnsq\fP.  You must use the program for which it was built.
-By default, \fBpluto\fP will look for the program in
-\fB$IPSEC_DIR\fP (if that environment variable is defined) or, failing that,
-in the same directory as \fBpluto\fP.
-.TP
-\fB\-\-nofork\fP
-disable ``daemon fork'' (default is to fork).  In addition, after the
-lock file and control socket are created, print the line ``Pluto
-initialized'' to standard out.
-.TP
-\fB\-\-uniqueids\fP
-if this option has been selected, whenever a new ISAKMP SA is
-established, any connection with the same Peer ID but a different
-Peer IP address is unoriented (causing all its SAs to be deleted).
-This helps clean up dangling SAs when a connection is lost and
-then regained at another IP address.
-.TP
-\fB\-\-stderrlog\fP
-log goes to standard out {default is to use \fIsyslogd\fP(8))
-.LP
-\fBpluto\fP is willing to produce a prodigious amount of debugging
-information.  To do so, it must be compiled with \-DDEBUG.  There are
-several classes of debugging output, and \fBpluto\fP may be directed to
-produce a selection of them.  All lines of
-debugging output are prefixed with ``|\ '' to distinguish them from error
-messages.
-.LP
-When \fBpluto\fP is invoked, it may be given arguments to specify
-which classes to output.  The current options are:
-.TP
-\fB\-\-debug-raw\fP
-show the raw bytes of messages
-.TP
-\fB\-\-debug-crypt\fP
-show the encryption and decryption of messages
-.TP
-\fB\-\-debug-parsing\fP
-show the structure of input messages
-.TP
-\fB\-\-debug-emitting\fP
-show the structure of output messages
-.TP
-\fB\-\-debug-control\fP
-show \fBpluto\fP's decision making
-.TP
-\fB\-\-debug-lifecycle\fP
-[this option is temporary] log more detail of lifecycle of SAs
-.TP
-\fB\-\-debug-kernel\fP
-show \fBpluto\fP's interaction with the kernel
-.TP
-\fB\-\-debug-dns\fP
-show \fBpluto\fP's interaction with \fBDNS\fP for KEY and TXT records
-.TP
-\fB\-\-debug-oppo\fP
-show why \fBpluto\fP didn't find a suitable DNS TXT record to authorize opportunistic initiation
-.TP
-\fB\-\-debug-all\fP
-all of the above
-.TP
-\fB\-\-debug-private\fP
-allow debugging output with private keys.
-.TP
-\fB\-\-debug-none\fP
-none of the above
-.LP
-The debug form of the
-\fBwhack\fP command will change the selection in a running
-\fBpluto\fP.
-If a connection name is specified, the flags are added whenever
-\fBpluto\fP has identified that it is dealing with that connection.
-Unfortunately, this is often part way into the operation being observed.
-.LP
-For example, to start a \fBpluto\fP with a display of the structure of input
-and output:
-.IP
-pluto \-\-debug-emitting \-\-debug-parsing
-.LP
-To later change this \fBpluto\fP to only display raw bytes:
-.IP
-whack \-\-debug-raw
-.LP
-For testing, SSH's IKE test page is quite useful:
-.IP
-\fIhttp://isakmp-test.ssh.fi/\fP
-.LP
-Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA
-is established.  This allows future IPsec SA's to be negotiated
-directly.  If one of the IKEs is restarted, the other may try to use
-the ISAKMP SA but the new IKE won't know about it.  This can lead to
-much confusion.  \fBpluto\fP is not yet smart enough to get out of such a
-mess.
-.SS Pluto's Behaviour When Things Go Wrong
-.LP
-When \fBpluto\fP doesn't understand or accept a message, it just
-ignores the message.  It is not yet capable of communicating the
-problem to the other IKE daemon (in the future it might use
-Notifications to accomplish this in many cases).  It does log a diagnostic.
-.LP
-When \fBpluto\fP gets no response from a message, it resends the same
-message (a message will be sent at most three times).  This is
-appropriate: UDP is unreliable.
-.LP
-When pluto gets a message that it has already seen, there are many
-cases when it notices and discards it.  This too is appropriate for UDP.
-.LP
-Combine these three rules, and you can explain many apparently
-mysterious behaviours.  In a \fBpluto\fP log, retrying isn't usually the
-interesting event.  The critical thing is either earlier (\fBpluto\fP
-got a message which it didn't like and so ignored, so it was still
-awaiting an acceptable message and got impatient) or on the other
-system (\fBpluto\fP didn't send a reply because it wasn't happy with
-the previous message).
-.SS Notes
-.LP
-Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the SA.
-The IKE protocol lets the destination of the SA choose the SPI.
-The range 0 to 0xFF is reserved for IANA.
-\fBPluto\fP also avoids choosing an SPI in the range 0x100 to 0xFFF,
-leaving these SPIs free for manual keying.
-Remember that the peer, if not \fBpluto\fP, may well chose
-SPIs in this range.
-.SS Policies
-.LP
-This catalogue of policies may be of use when trying to configure
-\fBPluto\fP and another IKE implementation to interoperate.
-.LP
-In Phase 1, only Main Mode is supported.  We are not sure that
-Aggressive Mode is secure.  For one thing, it does not support
-identity protection.  It may allow more severe Denial Of Service
-attacks.
-.LP
-No Informational Exchanges are supported.  These are optional and
-since their delivery is not assured, they must not matter.
-It is the case that some IKE implementations won't interoperate
-without Informational Exchanges, but we feel they are broken.
-.LP
-No Informational Payloads are supported.  These are optional, but
-useful.  It is of concern that these payloads are not authenticated in
-Phase 1, nor in those Phase 2 messages authenticated with HASH(3).
-.IP \(bu \w'\(bu\ 'u
-Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5)
-are supported.
-Group MODP768 (1) is not supported because it is too weak.
-.IP \(bu
-Host authetication can be done by RSA Signatures or Pre-Shared
-Secrets.
-.IP \(bu
-3DES CBC (Cypher Block Chaining mode) is the only encryption
-supported, both for ISAKMP SAs and IPSEC SAs.
-.IP \(bu
-MD5 and SHA1 hashing are supported for packet authentication in both
-kinds of SAs.
-.IP \(bu
-The ESP, AH, or AH plus ESP are supported.  If, and only if, AH and
-ESP are combined, the ESP need not have its own authentication
-component.  The selection is controlled by the \-\-encrypt and
-\-\-authenticate flags.
-.IP \(bu
-Each of these may be combined with IPCOMP Deflate compression,
-but only if the potential connection specifies compression and only
-if the kernel is configured with IPCOMP support.
-.IP \(bu
-The IPSEC SAs may be tunnel or transport mode, where appropriate.
-The \-\-tunnel flag controls this when \fBpluto\fP is initiating.
-.IP \(bu
-When responding to an ISAKMP SA proposal, the maximum acceptable
-lifetime is eight hours.  The default is one hour.  There is no
-minimum.  The \-\-ikelifetime flag controls this when \fBpluto\fP
-is initiating.
-.IP \(bu
-When responding to an IPSEC SA proposal, the maximum acceptable
-lifetime is one day.  The default is eight hours.  There is no
-minimum.  The \-\-ipseclifetime flag controls this when \fBpluto\fP
-is initiating.
-.IP \(bu
-PFS is acceptable, and will be proposed if the \-\-pfs flag was
-specified.  The DH group proposed will be the same as negotiated for
-Phase 1.
-.SH SIGNALS
-.LP
-\fBPluto\fP responds to \fBSIGHUP\fP by issuing a suggestion that ``\fBwhack\fP
-\-\-listen'' might have been intended.
-.LP
-\fBPluto\fP exits when it receives \fBSIGTERM\fP.
-.SH EXIT STATUS
-.LP
-\fBpluto\fP normally forks a daemon process, so the exit status is
-normally a very preliminary result.
-.TP
-0
-means that all is OK so far.
-.TP
-1
-means that something was wrong.
-.TP
-10
-means that the lock file already exists.
-.LP
-If \fBwhack\fP detects a problem, it will return an exit status of 1.
-If it received progress messages from \fBpluto\fP, it returns as status
-the value of the numeric prefix from the last such message
-that was not a message sent to syslog or a comment
-(but the prefix for success is treated as 0).
-Otherwise, the exit status is 0.
-.SH FILES
-\fI/var/run/pluto.pid\fP
-.br
-\fI/var/run/pluto.ctl\fP
-.br
-\fI/etc/ipsec.secrets\fP
-.br
-\fI$IPSEC_LIBDIR/_pluto_adns\fP
-.br
-\fI$IPSEC_EXECDIR/lwdnsq\fP
-.br
-\fI/dev/urandom\fP
-.SH ENVIRONMENT
-\fIIPSEC_LIBDIR\fP
-.br
-\fIIPSEC_EXECDIR\fP
-.br
-\fIIPSECmyid\fP
-.SH SEE ALSO
-.LP
-The rest of the FreeS/WAN distribution, in particular \fIipsec\fP(8).
-.LP
-\fIipsec_auto\fP(8) is designed to make using \fBpluto\fP more pleasant.
-Use it!
-.LP
-.IR ipsec.secrets (5)
-describes the format of the secrets file.
-.LP
-\fIipsec_atoaddr\fP(3), part of the FreeS/WAN distribution, describes the
-forms that IP addresses may take.
-\fIipsec_atosubnet\fP(3), part of the FreeS/WAN distribution, describes the
-forms that subnet specifications.
-.LP
-For more information on IPsec, the mailing list, and the relevant
-documents, see:
-.IP
-.nh
-\fIhttp://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html\fP
-.hy
-.LP
-At the time of writing, the most relevant IETF RFCs are:
-.IP
-RFC2409 The Internet Key Exchange (IKE)
-.IP
-RFC2408 Internet Security Association and Key Management Protocol (ISAKMP)
-.IP
-RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP
-.LP
-The FreeS/WAN web site <htp://www.freeswan.org>
-and the mailing lists described there.
-.SH HISTORY
-This code is released under the GPL terms.
-See the accompanying file COPYING-2.0 for more details.
-The GPL does NOT apply to those pieces of code written by others
-which are included in this distribution, except as noted by the
-individual authors.
-.LP
-This software was originally written
-for the FreeS/WAN project
-<http://www.freeswan.org>
-by Angelos D. Keromytis
-(angelos@dsl.cis.upenn.edu), in May/June 1997, in Athens, Greece.
-Thanks go to John Ioannidis for his help.
-.LP
-It is currently (2000)
-being developed and maintained by D. Hugh Redelmeier
-(hugh@mimosa.com), in Canada.  The regulations of Greece and Canada
-allow us to make the code freely redistributable.
-.LP
-Kai Martius (admin@imib.med.tu-dresden.de) contributed the initial
-version of the code supporting PFS.
-.LP
-Richard Guy Briggs <rgb@conscoop.ottawa.on.ca> and Peter Onion
-<ponion@srd.bt.co.uk> added the PFKEY2 support.
-.LP
-We gratefully acknowledge that we use parts of Eric Young's \fIlibdes\fP
-package; see \fI../libdes/COPYRIGHT\fP.
-.SH BUGS
-.BR pluto
-is a work-in-progress.  It currently has many limitations.
-For example, it ignores notification messages that it receives, and
-it generates only Delete Notifications and those only for IPSEC SAs.
-.LP
-\fBpluto\fP does not support the Commit Flag.
-The Commit Flag is a bad feature of the IKE protocol.
-It isn't protected -- neither encrypted nor authenticated.
-A man in the middle could turn it on, leading to DoS.
-We just ignore it, with a warning.
-This should let us interoperate with
-implementations that insist on it, with minor damage.
-.LP
-\fBpluto\fP does not check that the SA returned by the Responder
-is actually one that was proposed.  It only checks that the SA is
-acceptable.  The difference is not large, but can show up in attributes
-such as SA lifetime.
-.LP
-There is no good way for a connection to be automatically terminated.
-This is a problem for Road Warrior and Opportunistic connections.
-The \fB\-\-dontrekey\fP option does prevent the SAs from
-being rekeyed on expiry.
-Additionally, if a Road Warrior connection has a client subnet with a fixed IP
-address, a negotiation with that subnet will cause any other
-connection instantiations with that same subnet to be unoriented
-(deleted, in effect).
-See also the \-\-uniqueids option for an extension of this.
-.LP
-When \fBpluto\fP sends a message to a peer that has disappeared,
-\fBpluto\fP receives incomplete information from the kernel, so it
-logs the unsatisfactory message ``some IKE message we sent has been
-rejected with ECONNREFUSED (kernel supplied no details)''.  John
-Denker suggests that this command is useful for tracking down the
-source of these problems:
-.br
-	tcpdump \-i eth0 icmp[0] != 8 and icmp[0] != 0
-.br
-Substitute your public interface for eth0 if it is different.
-.LP
-The word ``authenticate'' is used for two different features.  We must
-authenticate each IKE peer to the other.  This is an important task of
-Phase 1.  Each packet must be authenticated, both in IKE and in IPsec,
-and the method for IPsec is negotiated as an AH SA or part of an ESP SA.
-Unfortunately, the protocol has no mechanism for authenticating the Phase 2
-identities.
-.LP
-Bugs should be reported to the <users@lists.freeswan.org> mailing list.
-Caution: we cannot accept
-actual code from US residents, or even US citizens living outside the
-US, because that would bring FreeS/WAN under US export law.  Some
-other countries cause similar problems.  In general, we would prefer
-that you send detailed problem reports rather than code:  we want
-FreeS/WAN to be unquestionably freely exportable, which means being
-very careful about where the code comes from, and for a small bug fix,
-that is often more time-consuming than just reinventing the fix
-ourselves.