uml_netjig.8

openswan

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.
.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/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