pluto.8

This a good VPN source

\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 \fBKLIPS\fP 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 \fBKLIPS\fP to implement it.
It also invokes a script to adjust any firewall and issue \fIroute\fP(8)
commands to direct IP packets through \fBKLIPS\fP.
.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 \fBKLIPS\fP, the Openswan implementation of IPsec.
All of the components of \fBKLIPS\fP and \fBpluto\fP should be installed.
.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.  Each interface with a name of the form
\fBipsec\fP[\fB0\fP-\fB9\fP] is taken as a \fBKLIPS\fP virtual public interface.
Another network interface with the same IP address (there should be only
one) is taken as the corresponding real public
interface.  \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 Setting up \fBKLIPS\fP for \fBpluto\fP
.LP
The most basic network topology that \fBpluto\fP supports has two security
gateways negotiating on behalf of client subnets.  The diagram of RGB's
testbed is a good example (see \fIklips/doc/rgb_setup.txt\fP).
.LP
The file \fIINSTALL\fP in the base directory of this distribution
explains how to start setting up the whole system, including \fBKLIPS\fP.
.LP
Make sure that the security gateways have routes to each other.  This
is usually covered by the default route, but may require issuing
.IR route (8)
commands.  The route must go through a particular IP
interface (we will assume it is \fIeth0\fP, but it need not be).  The
interface that connects the security gateway to its client must be a
different one.
.LP
It is necessary to issue a
.IR ipsec_tncfg (8)
command on each gateway.  The required command is:

\ \ \ ipsec tncfg \-\-attach\ \-\-virtual\ ipsec0 \-\-physical\ eth0

A command to set up the ipsec0 virtual interface will also need to be
run.  It will have the same parameters as the command used to set up
the physical interface to which it has just been connected using
.IR ipsec_tncfg (8).
.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
Pluto supports \fBfood groups\fP, and certificates. These are located in
/etc/ipsec.d, or another directory as specified by \fB\-\-ipsecdir\fP.
.LP
Pluto may core dump. It will normally do so into the current working
directory. The standard scripts have an option dumpdir=, which can set the
current directory to determine where the core dump will go. In some cases, it
may be more convenient to specify it on the command line using --coredir.
A third method is to set the environment variable PLUTO_CORE_DIR. The command
line argument takes precedence over the environment variable.
.LP
At times it may be desireable to turn off all timed events in \fBpluto\fP,
this can be done with \fB\-\-noretransmits\fP.
.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
\fBKLIPS\fP hooks into the routing code in a LINUX kernel.
Traffic to be processed by an IPsec SA must be directed through
\fBKLIPS\fP by routing commands.  Furthermore, the processing to be
done is specified by \fIipsec eroute(8)\fP commands.
\fBpluto\fP takes the responsibility of managing both of these special
kinds of routes.
.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
All of these routing characteristics are expected change when
\fBKLIPS\fP is modified to use the firewall hooks in the LINUX 2.4.x
kernel.
.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''.