pluto.8

This a good VPN source

.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\-\-aggrmode\fP
This tunnel is using aggressive mode ISAKMP negotiation. The default is
main mode. Aggressive mode is less secure than main mode as it reveals
your identity to an eavesdropper, but is needed to support road warriors
using PSK keys or to interoperate with other buggy implementations insisting
on using aggressive mode.
.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 KLIPS 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 3600 (one hour) and the maximum is 86400 (1 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 28800 (eight 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\-\-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