FreeBSD Manual Pages

home | help

IPSEC_PLUTO(8) Executable programs IPSEC_PLUTO(8)

NAME
ipsec_pluto, ipsec_whack, pluto - ipsec whack : IPsec IKE keying daemon and
control interface

SYNOPSIS
ipsec pluto [--help] [--version] [--leak-detective] [--efence-protect]
[--config filename] [--vendorid VID] [--nofork] [--stderrlog] [--log-
file filename] [--log-no-time] [--log-no-append] [--log-no-ip]
[--log-no-audit] [--use-netkey] [--use-bsdkame] [--uniqueids] [--vir-
tual-private network_list] [--keep-alive delay_sec] [--force-busy]
[--crl-strict] [--crlcheckinterval] [--interface interfacename]
[--listen ipaddr] [--ikeport portnumber] [--natikeport portnumber]
[--rundir path] [--secretsfile secrets-file] [--nhelpers number]
[--seedbits numbits] [--ipsecdir dirname] [--nssdir dirname]
[--coredir dirname] [--statsbin filename] [--secctx-attr-type number]

ipsec whack [--help] [--version]

ipsec whack --name connection-name [[--ipv4] | [--ipv6]] [[--tunnelipv4] |
[--tunnelipv6]]
[--id identity] [--host ip-address] [--cert friendly_name] [--ck-
aid CKAID] [--ca distinguished name] [--groups access control groups]
[--sendcert yes | forced | always | ifasked | no | never]
[--sendca none | issuer | all] [--certtype number] [--ikeport port-
number] [--nexthop ip-address] [[--client subnet]] [--clientproto-
port protocol/port] [--srcip ip-address] [--xauthserver] [--xauth-
client] [--modecfgserver] [--modecfgclient] [--modecfgdns ip-ad-
dress, ip-address, ...] [--modecfgdomains DNS-domain, DNS-do-
main, ...] [--modecfgbanner login-banner] [--dnskeyondemand] [--up-
down updown]
--to
[--id identity] [--host ip-address] [--cert friendly_name] [--ck-
aid CKAID] [--ca distinguished name] [--groups access control groups]
[--sendcert yes | always | ifasked | no | never] [--certtype number]
[--ikeport port-number] [--nexthop ip-address] [--client subnet]
[--clientprotoport protocol/port] [--srcip ip-address] [--xauth-
server] [--xauthclient] [--modecfgserver] [--modecfgclient] [--mod-
ecfgdns ip-address, ip-address, ...] [--modecfgdomains DNS-do-
main, DNS-domain, ...] [--dnskeyondemand] [--updown updown]

ipsec whack --keyid id [--addkey] [--pubkeyrsa key] [--rundir path] [--ctl-
socket path/file] [--label string]

ipsec whack --listen | --unlisten [--rundir path] [--ctlsocket path/file]
[--label string]

ipsec whack --ddos-auto | --ddos-busy | --ddos-unlimited [--rundir path]
[--ctlsocket path/file]

ipsec whack --route | --unroute --name connection-name [--rundir path]
[--ctlsocket path/file] [--label string]

ipsec whack --initiate | [--remote-host ip-address] | --terminate |
--rekey-ike | --rekey-ipsec --name connection-name [--xau-
thuser user] [--xauthpass pass] [--asynchronous] [--rundir path]
[--ctlsocket path/file] [--label string]

ipsec whack --global-redirect yes|no|auto

ipsec whack --global-redirect-to ip-address(es)

ipsec whack [--name connection-name] --redirect-to ip-address(es)

ipsec whack [[--tunnelipv4] | [--tunnelipv6]] --oppohere ip-address --op-
pothere ip-address --opposport port --oppodport port --oppoproto pro-
tocol

ipsec whack --crash [ipaddress]

ipsec whack --name connection-name --delete [--ctlbase path] [--la-
bel string]

ipsec whack --deletestate state-number [--rundir path] [--ctl-
socket path/file] [--label string]

ipsec whack --deleteuser --name username [--rundir path] [--ctl-
socket path/file] [--label string]

ipsec whack [--name connection-name] {--debug help | none | base | cpu-us-
age | class} | {--no-debug class} | {--impair help | none | behav-
iour} | {--no-impair behaviour}

ipsec whack [--utc] [--listall] [--listpubkeys] [--listcerts] [--listcac-
erts] [--listcrls]

ipsec whack [--utc] [--rereadsecrets] [--fetchcrls] [--rereadall]

ipsec whack --ddns

ipsec whack --listevents

ipsec whack --purgeocsp

ipsec whack --status --trafficstatus --shuntstatus --addresspoolstatus
--processstatus [--rundir path] [--ctlsocket path/file] [--la-
bel string]

ipsec whack --globalstats --clearstats [--rundir path] [--ctl-
socket path/file] [--label string]

ipsec whack [--ike-socket-bufsize bufsize] [--ike-socket-errqueue-toggle]
[--rundir path] [--ctlsocket path/file] [--label string]

ipsec whack --shutdown [--rundir path] [--ctlsocket path/file] [--la-
bel string] [--leave-state]

DESCRIPTION
pluto is an IKE ("IPsec Key Exchange") daemon. whack is an auxiliary pro-
gram to allow requests to be made to a running pluto.

pluto is used to automatically build shared "security associations" on a
system that has IPsec, the secure IP protocol. In other words, pluto can
eliminate much of the work of manual keying. The actual secure transmission
of packets is the responsibility of other parts of the system - the kernel.
Pluto can talk to various kernel implementations, such as the Linux XFRM
and BSD KAME IPsec stacks. ipsec_auto(8) provides a more convenient inter-
face to pluto and whack.

IKE's Job
A Security Association (SA) is an agreement between two network nodes on
how to process certain traffic between them. This processing involves en-
capsulation, authentication, encryption, or compression.

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.

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.

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.

IKE deals with two kinds of Security Associations. The first part of a ne-
gotiation 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.

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. Currently,
Main Mode and Aggressive Mode are implemented.

Any negotiation under the protection of an ISAKMP SA, including the negoti-
ation of IPsec SAs, is part of Phase 2. The exchange type that we use to
negotiate an IPsec SA is called Quick Mode.

IKE instances must be able to authenticate each other as part of their ne-
gotiation of an ISAKMP SA. This can be done by several mechanisms described
in the draft standards.

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 As-
sociation. The standards do not specify what causes an IKE instance to ini-
tiate a negotiation.

In summary, an IKE instance is prepared to automate the management of Secu-
rity Associations in an IPsec environment, but a number of issues are con-
sidered policy and are left in the system administrator's hands.

Pluto
pluto is an implementation of IKE. It runs as a daemon on a network node.
Currently, this network node must be a Linux system running the XFRM IPsec
stack, or a FreeBSD/NetBSD/Mac OSX system running the KAME IPsec stack.

pluto implements a large subset of IKEv1 and IKEv2.

The policy for acceptable characteristics for Security Associations is
mostly hardwired into the code of pluto (spdb.c). Eventually this will be
moved into a security policy database with reasonable expressive power and
more convenience.

pluto uses shared secrets or RSA signatures to authenticate peers with whom
it is negotiating. These RSA signatures can come from DNS(SEC), a configu-
ration file, or from X.509 and CA certificates.

pluto initiates negotiation of a Security Association when it is manually
prodded: the program whack is run to trigger this. It will also initiate a
negotiation when IPsec traps an outbound packet for Opportunistic Encryp-
tion.

pluto implements ISAKMP SAs itself. After it has negotiated the character-
istics of an IPsec SA, it directs the kernel to implement it. If necessary,
it also invokes a script to adjust any firewall and issue route(8) commands
to direct IP packets.

When pluto shuts down, it closes all Security Associations.

Before Running Pluto
pluto runs as a daemon with userid root. Before running it, a few things
must be set up.

pluto requires a working IPsec stack.

pluto supports multiple public networks (that is, networks that are consid-
ered insecure and thus need to have their traffic encrypted or authenti-
cated). It discovers the public interfaces to use by looking at all inter-
faces that are configured (the --interface option can be used to limit the
interfaces considered). It does this only when whack tells it to --listen,
so the interfaces must be configured by then. The --listen can be used to
limit listening on only 1 IP address of a certain interface. ifconfig(8)
or ip(8) with the -a flag will show the name and status of each network in-
terface.

pluto requires a database of preshared secrets and RSA private keys. This
is described in the ipsec.secrets(5). pluto is told of RSA public keys via
whack commands. If the connection is Opportunistic, and no RSA public key
is known, pluto will attempt to fetch RSA keys using the Domain Name Sys-
tem.

Setting up XFRM for pluto
No special requirements are necessary to use XFRM - it ships with all mod-
ern versions of Linux 2.4 and later.

ipsec.secrets file
A pluto daemon and another IKE daemon (for example, another instance of
pluto) 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 us-
ing RSA signatures. There are other techniques, but they have not been im-
plemented in pluto.

The file /usr/local/etc/ipsec.secrets is used to keep preshared secret keys
and XAUTH passwords. RSA private keys, X.509 certificates, CRLs, OCSP and
smartcards are handled via NSS. For debugging, there is an argument to the
pluto command to use a different file. This file is described in ipsec.se-
crets(5).

Running Pluto
To fire up the daemon, just type pluto (be sure to be running as the supe-
ruser). The default IKE port number is 500, the UDP port assigned by IANA
for IKE Daemons. pluto must be run by the superuser to be able to use the
UDP 500 port. If pluto is told to enable NAT-Traversal, then UDP port 4500
is also taken by pluto to listen on.

Pluto supports different IPstacks on different operating systems. This can
be configured using one of the options --use-netkey (Linux), --use-bsdkame
(BSD). On startup, pluto might also read the protostack= option to select
the IPsec stack to use if --config /etc/ipsec.conf is given as argument to
pluto. If both --use-XXX and --config /etc/ipsec.conf are specified, the
last command line argument specified takes precedence.

Pluto supports RFC 3947 NAT-Traversal. The allowed range behind the NAT
routers is submitted using the --virtual-private option. See ipsec.conf(5)
for the syntax. The option --force-keepalive forces the sending of the
keep-alive packets, which are send to prevent the NAT router from closing
its port when there is not enough traffic on the IPsec connection. The
--keep-alive sets the delay (in seconds) of these keep-alive packets. The
newer NAT-T standards support port floating, and Libreswan enables this per
default.

Pluto supports the use of X.509 certificates and sends certificates when
needed. Pluto uses NSS for all X.509 related data, including CAcerts,
certs, CRLs and private keys. The Certificate Revocation Lists can also be
retrieved from an URL. The option --crlcheckinterval sets the time between
checking for CRL expiration and issuing new fetch commands. The first at-
tempt to update a CRL is started at 2*crlcheckinterval before the next up-
date time. Pluto logs a warning if no valid CRL was loaded or obtained for
a connection. If --crl-strict is given, the connection will be rejected un-
til a valid CRL has been loaded.

Pluto can also use helper children to off-load cryptographic operations.
This behavior can be fine tuned using the --nhelpers. Pluto will start
(n-1) of them, where n is the number of CPU's you have (including hy-
pherthreaded CPU's). A value of 0 forces pluto to do all operations in the
main process. A value of -1 tells pluto to perform the above calculation.
Any other value forces the number to that amount.

Pluto uses the NSS crypto library as its random source. Some government
Three Letter Agency requires that pluto reads 440 bits from /dev/random and
feed this into the NSS RNG before drawing random from the NSS library, de-
spite the NSS library itself already seeding its internal state. As this
process can block pluto for an extended time, the default is to not perform
this redundant seeding. The --seedbits option can be used to specify the
number of bits that will be pulled from /dev/random and seeded into the NSS
RNG. This can also be accomplished by specifying seedbits in the "config
setup" section of ipsec.conf. This option should not be used by most peo-
ple.

pluto attempts to create a lockfile with the name /var/run/pluto/pluto.pid.
If the lockfile cannot be created, pluto exits - this prevents multiple
plutos from competing Any "leftover" lockfile must be removed before pluto
will run. pluto 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).

pluto 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. In certain configurations, pluto might also launch helper pro-
grams to assist with DNS queries or to offload cryptographic operations.

All logging, including diagnostics, is sent to syslog(3) with facility=au-
thpriv; it decides where to put these messages (possibly in /var/log/secure
or /var/log/auth.log). Since this too can make debugging awkward, the op-
tion --stderrlog is used to steer logging to stderr.

Alternatively, --logfile can be used to send all logging information to a
specific file.

Once pluto is started, it waits for requests from whack.

Pluto's Internal State
To understand how to use pluto, it is helpful to understand a little about
its internal state. Furthermore, the terminology is needed to decipher some
of the diagnostic messages.

Pluto supports food groups for Opportunistic IPsec. The policies for these
are located in /etc/ipsec.d/policies, or another directory as specified by
--ipsecdir.

Pluto supports X.509 Certificates. All certificate handling is done using
the NSS library and all certificate material is stored in an NSS database
in /usr/local/etc/ipsec.d or another directory as specified by --nssdir.

Pluto may core dump. It will normally do so into the current working direc-
tory. You can specify the --coredir option for pluto, or specify the
dumpdir= option in ipsec.conf.

If you are investigating a potential memory leak in pluto, start pluto with
the --leak-detective option. Before the leak causes the system or pluto to
die, shut down pluto in the regular way. pluto will display a list of leaks
it has detected.

If you are investigating a potential use-after-free or double-free in
pluto, first build pluto with USE_EFENCE=true and then start pluto with
--efence-protect. See efence(2) and EF_PROTECT_BELOW and EF_PROTECT_FREE.

The (potential) connection database describes attributes of a connection.
These include the IP addresses of the hosts and client subnets and the se-
curity characteristics desired. pluto 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.

During the IKE exchange to build an SA, the information about the negotia-
tion is represented in a state object. 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 se-
rial number and this is used to refer to the state objects in logged mes-
sages.

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.

XFRM requires no special routing.

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 (pluto's
logic does not reflect any advanced routing capabilities).

When pluto needs to install a route for a connection, it must make sure
that no conflicting route is in use. If another connection has a conflict-
ing 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.

There is an exception. If pluto, 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).

When pluto 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 al-
ready in place for another connection, the eroute and SA will not be in-
stalled (but note that the routing exception mentioned above may have al-
ready 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.

Using whack
whack is used to command a running pluto. whack uses a UNIX domain socket
to speak to pluto (by default, /var/pluto.ctl).

whack has an intricate argument syntax. This syntax allows many different
functions to be specified. The help form shows the usage or version infor-
mation. The connection form gives pluto a description of a potential con-
nection. The public key form informs pluto of the RSA public key for a po-
tential peer. The delete form deletes a connection description and all SAs
corresponding to it. The listen form tells pluto to start or stop listening
on the public interfaces for IKE requests from peers. The route form tells
pluto to set up routing for a connection; the unroute form undoes this. The
initiate form tells pluto to negotiate an SA corresponding to a connection.
The terminate form tells pluto to remove all SAs corresponding to a connec-
tion, including those being negotiated. The status form displays the
pluto's internal state. The debug form tells pluto to change the selection
of debugging output "on the fly". The shutdown form tells pluto to shut
down, deleting all SAs.

The crash option asks pluto to consider a particularly target IP to have
crashed, and to attempt to restart all connections with that IP address as
a gateway. In general, you should use Dead Peer Detection to detect this
kind of situation automatically, but this is not always possible.

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.

--ctlsocket path/file
file is used as the UNIX domain socket for talking to pluto. Use either
this option or --rundir, but not both.

--rundir path
path where the UNIX domain socket for talking to the pluto, the
pluto.pid file and the pluto.lock files are found. Use either this op-
tion or --ctlsocket, but not both.

--label string
adds the string to all error messages generated by whack.

The help form of whack is self-explanatory.

--help
display the usage message.

--version
display the version of whack.

The connection form describes a potential connection to pluto. pluto needs
to know what connections can and should be negotiated. When pluto is the
initiator, it needs to know what to propose. When pluto is the responder,
it needs to know enough to decide whether is is willing to set up the pro-
posed connection.

The description of a potential connection can specify a large number of de-
tails. 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.

--name connection-name
sets the name of the connection

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 --to flag describe the left side and those after-
wards describe the right side. When pluto 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.

--id id
the identity of the end. Currently, this can be an IP address (speci-
fied as dotted quad or as a Fully Qualified Domain Name, which will be
resolved immediately) or as a Fully Qualified Domain Name itself (pre-
fixed by "@" to signify that it should not be resolved), or as
user@FQDN, or an X.509 DN. Pluto 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 --host.

--host ip-address, --host %any, --host %opportunistic
the IP address of the end (generally the public interface). If pluto 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 %any (currently, the obsolete notation 0.0.0.0 is also accepted for
this). If pluto is to opportunistically initiate the connection, use
%opportunistic

--cert friendly_name
The friendly_name (or nickname) of the X.509 certificate that was used
when imported the certificate into the NSS database. See ipsec.conf(5)
on how to extract this from the PKCS#12 file.

--ckaid CKAID
The hex CKAID of the X.509 certificate. Certificates are stored in the
NSS database.

--ca distinguished name
the X.509 Certificate Authority's Distinguished Name (DN) used as trust
anchor for this connection. This is the CA certificate that signed the
host certificate, as well as the certificate of the incoming client.

--groups access control groups
the access control groups used.

--sendcert yes|forced|always|ifasked|no|never
Whether or not to send our X.509 certificate credentials. This could
potentially give an attacker too much information about which identi-
ties are allowed to connect to this host. The default is to use ifasked
when we are a Responder, and to use yes (which is the same as forced
and always if we are an Initiator. The values no and never are equiva-
lent. NOTE: "forced" does not seem to be actually implemented - do not
use it.

--sendca none|issuer|all
How much of our available X.509 trust chain to send with the end cer-
tificate, excluding any root CAs. Specifying issuer sends just the is-
suing intermediate CA, while
all will send the entire chain of intermediate CAs.none will not send
any CA certs. The default is none which maintains the current libreswan
behavior.

--certtype number
The X.509 certificate type number.

--ikeport port-number
the UDP port that IKE listens to on that host. The default is 500.
(pluto on this machine uses the port specified by its own command line
argument, so this only affects where pluto sends messages.)

--nexthop ip-address
where to route packets for the peer's client (presumably for the peer
too, but it will not be used for this). When pluto 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
%direct; the obsolete notation 0.0.0.0 is accepted). This option is
necessary if pluto's host's interface used for sending packets to the
peer is neither point-to-point nor directly connected to the peer.

--client subnet
the subnet for which the IPsec traffic will be destined. If not speci-
fied, the host will be the client. The subnet can be specified in any
of the forms supported by ipsec_atosubnet(3). The general form is ad-
dress/mask. The address can be either a domain name or four decimal
numbers (specifying octets) separated by dots. The most convenient form
of the mask 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".

--clientprotoport protocol/port
specify the Port Selectors (filters) to be used on this connection. The
general form is protocol/port. This is most commonly used to limit the
connection to L2TP traffic only by specifying a value of 17/1701 for
UDP (protocol 17) and port 1701. The notation 17/%any can be used to
allow all UDP traffic and is needed for L2TP connections with Windows
XP machines before Service Pack 2.

--srcip ip-address
the IP address for this host to use when transmitting a packet to the
remote IPsec gateway itself. This option is used to make the gateway
itself use its internal IP, which is part of the --client subnet. Oth-
erwise it will use its nearest IP address, which is its public IP ad-
dress, which is not part of the subnet-subnet IPsec tunnel, and would
therefore not get encrypted.

--xauthserver
this end is an xauthserver. It will lookup the xauth user name and
password and verify this before allowing the connection to get estab-
lished.

--xauthclient
this end is an xauthclient. To bring this connection up with the --ini-
tiate also requires the client to specify --xauthuser username and
--xauthpass password

--xauthuser
The username for the xauth authentication.This option is normally
passed along by ipsec_auto(8) when an xauth connection is started using
ipsec auto --up conn

--xauthpass
The password for the xauth authentication. This option is normally
passed along by ipsec_auto(8) when an xauth connection is started using
ipsec auto --up conn

--modecfgserver
this end is an Mode Config server

--modecfgclient
this end is an Mode Config client

--modecfgdns
A comma separated list of DNS server IP's to pass along to connecting
clients

--modecfgdomains
A comma separated list of internal DNS domains to pass along to con-
necting clients

--dnskeyondemand
specifies that when an RSA public key is needed to authenticate this
host, and it isn't already known, fetch it from DNS.

--updown updown
specifies an external shell command to be run whenever pluto 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
ipsec _updown. Pluto passes a dozen environment variables to the script
about the connection involved.

--to
separates the specification of the left and right ends of the connec-
tion. Pluto tries to decide whether it is left or right based on the
information provided on both sides of this option.

The potential connection description also specifies characteristics of
rekeying and security.

--psk
Propose and allow preshared secret authentication for IKE peers. This
authentication requires that each side use the same secret. May be com-
bined with --rsasig; at least one must be specified.

--rsasig
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 --psk; at
least one must be specified.

--encrypt
All proposed or accepted IPsec SAs will include non-null ESP. The ac-
tual choices of transforms are wired into pluto.

--authenticate
All proposed IPsec SAs will include AH. All accepted IPsec SAs will in-
clude AH or ESP with authentication. The actual choices of transforms
are wired into pluto. Note that this has nothing to do with IKE authen-
tication.

--compress
All proposed IPsec SAs will include IPCOMP (compression).

--tunnel
the IPsec SA should use tunneling. Implicit if the SA is for clients.
Must only be used with --authenticate or --encrypt.

--ipv4
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).

--ipv6
The host addresses (including nexthop) will be interpreted as IPv6 ad-
dresses. Note that for a connection, all host addresses must be of the
same Address Family (IPv4 and IPv6 use different Address Families).

--tunnelipv4
The client addresses will be interpreted as IPv4 addresses. The default
is to match what the host will be. This does not imply --tunnel 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 Fam-
ily.

--tunnelipv6
The client addresses will be interpreted as IPv6 addresses. The default
is to match what the host will be. This does not imply --tunnel 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 Fam-
ily.

--pfs
There should be Perfect Forward Secrecy - new keying material will be
generated for each IPsec SA when running Quick Mode in IKEv1 or Create
Child in IKEv2. Without this option, the SAKMP SA keying material is
used instead. pluto will propose the same group that was used with the
original IKE SA.

--pfsgroup modp-group
Sets the Diffie-Hellman group used. Currently the following values are
supported: modp1024 (DHgroup 2), modp1536 (DHgroup 5), modp2048
(DHgroup 14), modp3072 (DHgroup 15), modp4096 (DHgroup 16), modp6144
(DHgroup 17), and modp8192 (DHgroup 18). It is possible to support the
weak and broken modp768 (DHgroup 1), but this requires a manual recom-
pile and is strongly discouraged.

--esp esp-algos
ESP encryption/authentication algorithm to be used for the connection
(phase2 aka IPsec SA). The options must be suitable as a value of
ipsec_spi(8). See ipsec.conf(5) for a detailed description of the algo-
rithm format.

--aggrmode
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 war-
riors using PSK keys or to interoperate with other buggy implementa-
tions insisting on using aggressive mode.

--modecfgpull
Pull the Mode Config network information from the peer.

--dpddelay seconds
Set the delay (in seconds) between Dead Peer Detection (RFC 3706)
keepalives (R_U_THERE, R_U_THERE_ACK) that are sent for this connection
(default 30 seconds).

--timeout seconds
Set the length of time (in seconds) we will idle without hearing either
an R_U_THERE poll from our peer, or an R_U_THERE_ACK reply. After this
period has elapsed with no response and no traffic, we will declare the
peer dead, and remove the SA (default 120 seconds).

--dpdaction action
When a DPD enabled peer is declared dead, what action should be taken.
hold(default) means the eroute will be put into %hold status, while
clearmeans the eroute and SA with both be cleared. Clear is really only
useful on the server of a Road Warrior config. The action restart is
used on tunnels that need to be permanently up, and have static IP ad-
dresses. The action restart_by_peerhas been obsoleted and its function-
ality has been moved into the restart action.

--forceencaps
In some cases, for example when ESP packets are filtered or when a bro-
ken IPsec peer does not properly recognise NAT, it can be useful to
force RFC-3948 encapsulation using this option. It causes pluto lie and
tell the remote peer that RFC-3948 encapsulation (ESP in UDP port 4500
packets) is required.

If none of the --encrypt, --authenticate, --compress, or --pfs 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.

Apart from initiating directly using the --initiate option, a tunnel can be
loaded with a different policy

--initiateontraffic
Only initiate the connection when we have traffic to send over the con-
nection

--pass
Allow unencrypted traffic to flow until the tunnel is initiated.

--drop
Drop unencrypted traffic silently.

--reject
Drop unencrypted traffic silently, but send an ICMP message notifying
the other end.

These options need to be documented

--failnone
to be documented

--failpass
to be documented

--faildrop
to be documented

--failreject
to be documented

pluto supports various X.509 Certificate related options.

--utc
display all times in UTC.

--listall
lists all of the X.509 information known to pluto.

--listpubkeys
list all the public keys that have been successfully loaded.

--listcerts
list all the X.509 certificates that are currently loaded.

--checkpubkeys
list all the loaded X.509 certificates that are about to expire or have
expired.

--listcacerts
list all the Certificate Authority X.509 certificates that are cur-
rently loaded.

--listcrls
list all the loaded Certificate Revocation Lists (CRLs)

The corresponding options --rereadsecrets, --rereadall, and --rereadcrls
options reread this information from their respective sources, and purge
all the online obtained information. The option --listevents lists all
pending events, and the --ddns triggers the Dynamic DNS update event that
is normally scheduled to run once every minute.

--ikelifetime seconds
how long pluto will propose that an ISAKMP SA be allowed to live. The
default is 3600 (one hour) and the maximum is 86400 (1 day). This op-
tion will not affect what is accepted. pluto will reject proposals
that exceed the maximum.

--ipseclifetime seconds
how long pluto 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. pluto will reject proposals
that exceed the maximum.

--rekeymargin seconds
how long before an SA's expiration should pluto try to negotiate a re-
placement SA. This will only happen if pluto was the initiator. The de-
fault is 540 (nine minutes).

--rekeyfuzz percentage
maximum size of random component to add to rekeymargin, expressed as a
percentage of rekeymargin. pluto will select a delay uniformly dis-
tributed 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.

--keyingtries count
how many times pluto should try to negotiate an SA, either for the
first time or for rekeying. The default value of 0 means to keep trying
forever.

--dontrekey
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 con-
nections. Since SA lifetime negotiation is take-it-or-leave it, a Re-
sponder normally uses the shorter of the negotiated or the configured
lifetime. This only works because if the lifetime is shorter than nego-
tiated, the Responder will rekey in time so that everything works. This
interacts badly with --dontrekey. 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.

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

--delete, --name connection-name
The delete form deletes a named connection description and any SAs es-
tablished or negotiations initiated using this connection. Any routing
in place for the connection is undone.

--deletestate state-number
The deletestate form deletes the state object with the specified serial
number. This is useful for selectively deleting instances of connec-
tions.

The route form of the whack command tells pluto 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 er-
oute will be installed; if outbound traffic is caught, Pluto will initiate
the connection. An explicit whack route is not always needed: if it hasn't
been done when an IPsec SA is being installed, one will be automatically
attempted.

--route, --name connection-name
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.

--unroute, --name connection-name
The unroute form of the whack command tells pluto to undo a routing.
pluto will refuse if an IPsec SA is using the connection. If another
connection is sharing the same routing, it will be left in place. With-
out a routing, packets will be sent without encryption or authentica-
tion.

The initiate form tells pluto to initiate a negotiation with another pluto
(or other IKE daemon) according to the named connection. Initiation re-
quires a route that --route would provide; if none is in place at the time
an IPsec SA is being installed, pluto attempts to set one up.

--initiate, --name connection-name, --asynchronous
The initiate form of the whack command will relay back from pluto sta-
tus information via the UNIX domain socket (unless --asynchronous is
specified). The status information is meant to look a bit like that
from FTP. Currently whack simply copies this to stderr. When the re-
quest is finished (eg. the SAs are established or pluto gives up),
pluto closes the channel, causing whack to terminate.

The opportunistic initiate form is mainly used for debugging.

--tunnelipv4, --tunnelipv6, --oppohere ip-address, --oppothere ip-ad-
dress, --opposport port, --oppodport port, --oppoproto protocol
This will cause pluto to attempt to opportunistically initiate a con-
nection from here to the there, even if a previous attempt had been
made. The whack log will show the progress of this attempt.

Rekeying a connection

--rekey-ipsec, --name connection-name
the rekey-ipsec form tells pluto to rekey the IPsec SA (child SA) of
the specified connection. It does not affect the IKE SA (parent SA)

--rekey-ike, --name connection-name
the rekey-ike form tells pluto to rekey the IKE SA (parent SA) of the
specified connection. It does not affect the IPsec SAs (child SAs)

Ending a connection

--terminate, --name connection-name
the terminate form tells pluto 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).

--crash ip-address
If the remote peer has crashed, and therefore did not notify us, we
keep sending encrypted traffic, and rejecting all plaintext (non-IKE)
traffic from that remote peer. The --crash brings our end down as well
for all the known connections to the specified ip-address

ip-address
If the remote peer has crashed, and therefore did not notify us, we
keep sending encrypted traffic, and rejecting all plaintext (non-IKE)
traffic from that remote peer. The --crash brings our end down as well
for all the known connections to the specified ip-address

Redirecting clients can be done using IKEv2 redirect mechanism.

--global-redirect yes|no|auto
The --global-redirect option controls whether pluto will instruct re-
mote peers to redirect IKE/IPsec SA's during IKE_SA_INIT. Valid options
are no, yes and auto, where auto means remote peers will be redirected
if DDoS mode is active.

--global-redirect-to ip-address(es)
The destination, or a list of destinations, where the peers will be
redirected.

--name connection_name, --redirect-to ip-address(es)
The destination, or a list of destinations, where the peers will be
redirected. Specifying the connection name is optional. If not speci-
fied the mechanism will redirect all currently active peers. If speci-
fied, only the peers from connection connection_name will be redi-
rected.

The public key for informs pluto of the RSA public key for a potential
peer. Private keys must be kept secret, so they are kept in ipsec.se-
crets(5).

--keyid id
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, pluto 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.

--addkey
specifies that the new key is added to the collection; otherwise the
new key replaces any old ones.

--pubkeyrsa key
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 ipsec_ttodata(3). For exam-
ple, a base 64 numeral starts with 0s.

The listen form tells pluto to start listening for IKE requests on its pub-
lic interfaces. To avoid race conditions, it is normal to load the appro-
priate connections into pluto before allowing it to listen. If pluto isn't
listening, it is pointless to initiate negotiations, so it will refuse re-
quests to do so. Whenever the listen form is used, pluto 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 pluto to read the ipsec.se-
crets file. So listen may useful more than once.

--listen
start listening for IKE traffic on public interfaces.

--unlisten
stop listening for IKE traffic on public interfaces.

The --ddos-auto, --ddos-busy and --ddos-unlimited options tells pluto to
update the DDoS protection state. Normally, these measures are automati-
cally activated or deactivated based on the number of states inside pluto.
The busy and unlimited option tells pluto to activate or deactivate the
DDoS protection mode manually. One of these DDoS protection methods is to
activate IKEv2 DCOOKIEs to defend against spoofed IKE packets.

--ddos-busy
place pluto into busy mode and activate anti-DDoS measures.

--ddos-unlimited
pull pluto out of busy mode and deactivate anti-DDoS measures.

--ddos-auto
activate the built-in detection mechanism for the anti-DDoS measures.

The status form will display information about the internal state of pluto:
information about each potential connection, about each state object, and
about each shunt that pluto is managing without an associated connection.

Statistics can be seen using ipsec whack --globalstats and reset using
ipsec whack --clearstats. This can be used with the munin software to moni-
tor VPN services.

--status

The trafficstatus form will display the xauth username, add_time and the
total in and out bytes of the IPsec SA's.

--trafficstatus

The shutdown form is the proper way to shut down pluto. It will tear down
the SAs on this machine that pluto has negotiated. If the --leave-state op-
tion is given, it does not delete any connections, and leaves the kernel
state in the kernel. Note that the init system used might clean up the ker-
nel state regardless.

--shutdown

Examples
It would be normal to start pluto 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 pluto process will be left run-
ning, waiting for requests from whack or a peer.

Using whack, several potential connections would be described:

ipsec whack --name silly --host 127.0.0.1 --to --host 127.0.0.2 --ike-
lifetime 900 --ipseclifetime 800 --keyingtries 3

Since this silly connection description specifies neither encryption, au-
thentication, nor tunneling, it could only be used to establish an ISAKMP
SA.

ipsec whack --name conn_name --host 10.0.0.1 --client 10.0.1.0/24 --to
--host 10.0.0.2 --client 10.0.2.0/24 --encrypt

This is something that must be done on both sides. If the other side is
pluto, the same whack command could be used on it (the command syntax is
designed to not distinguish which end is ours).

Now that the connections are specified, pluto 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

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 pluto 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 conn_name

Finally, we are ready to get pluto to initiate negotiation for an IPsec SA
(and implicitly, an ISAKMP SA):

ipsec whack --initiate --name conn_name

A small log of interesting events will appear on standard output (other
logging is sent to syslog).

whack can also be used to terminate pluto 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,
pluto itself ignores Notifications.

XAUTH
If pluto needs additional authentication, such as defined by the XAUTH
specifications, then it may ask whack to prompt the operator for username
or passwords. Typically, these will be entered interactively. A GUI that
wraps around whack may look for the 041 (username) or 040 (password)
prompts, and display them to the user.

For testing purposes, the options --xauthuser user --xauthpass pass may be
be given prior to the --initiate to provide responses to the username and
password prompts.

The updown command
Whenever pluto brings a connection up or down, it invokes the updown com-
mand. This command is specified using the --updown option. This allows for
customized control over routing and firewall manipulation.

The updown is invoked for five different operations. Each of these opera-
tions can be for our client subnet or for our host itself.

prepare-host or prepare-client
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 pluto was run or perhaps by some
agent not known to pluto.

route-host or route-client
is run when bringing up a connection for a new peer client subnet (even
if prepare-host or prepare-client 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.

unroute-host or unroute-client
is run when bringing down the last connection for a particular peer
client subnet. It should undo what the route-host or route-client did.

up-host or up-client
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.

down-host or down-client
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.

The script is passed a large number of environment variables to specify
what needs to be done.

PLUTO_VERB
specifies the name of the operation to be performed (prepare-host,r
prepare-client, up-host, up-client, down-host, or down-client). If the
address family for security gateway to security gateway communications
is IPv6, then a suffix of -v6 is added to the verb.

PLUTO_CONNECTION
is the name of the connection for which we are routing.

PLUTO_NEXT_HOP
is the next hop to which packets bound for the peer must be sent.

PLUTO_INTERFACE
is the name of the ipsec interface to be used.

PLUTO_ME
is the IP address of our host.

PLUTO_MY_CLIENT
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).

PLUTO_MY_CLIENT_NET
is the IP address of our client net. If the client is just the host,
this will be the host's own IP address.

PLUTO_MY_CLIENT_MASK
is the mask for our client net. If the client is just the host, this
will be 255.255.255.255.

PLUTO_PEER
is the IP address of our peer.

PLUTO_PEER_CLIENT
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).

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

PLUTO_PEER_CLIENT_MASK
is the mask for the peer's client net. If the client is just the peer,
this will be 255.255.255.255.

PLUTO_MY_PROTOCOL
lists the protocols allowed over this IPsec SA.

PLUTO_PEER_PROTOCOL
lists the protocols the peer allows over this IPsec SA.

PLUTO_MY_PORT
lists the ports allowed over this IPsec SA.

PLUTO_PEER_PORT
lists the ports the peer allows over this IPsec SA.

PLUTO_MY_ID
lists our id.

PLUTO_PEER_ID
Dlists our peer's id.

PLUTO_PEER_CA
lists the peer's CA.

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.

Pluto waits for the script to finish and will not do any other processing
while it is waiting. The script may assume that pluto will not change any-
thing while the script runs. The script should avoid doing anything that
takes much time and it should not issue any command that requires process-
ing by pluto. Either of these activities could be performed by a background
subprocess of the script.

Rekeying
When an SA that was initiated by pluto has only a bit of lifetime left,
pluto 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 rekey-
fuzz, of the rekeymargin.

Similarly, when an SA that was initiated by the peer has only a bit of
lifetime left, pluto 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.

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.

pluto 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 redun-
dant SAs.

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.

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 re-
sources (network bandwidth, CPU time, entropy for random numbers). The
rekeyfuzz can be used to stagger the rekeying times.

Once a new set of SAs has been negotiated, pluto will never send traffic on
a superseded one. Traffic will be accepted on an old SA until it expires.

Selecting a Connection When Responding: Road Warrior Support
When pluto 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 cho-
sen. (The ISAKMP SA proposal contained in the message could be taken into
account, but it is not.)

The ISAKMP SA is negotiated before the parties pass further identifying in-
formation, so all ISAKMP SA characteristics specified in the connection de-
scription should be the same for every connection with the same two host IP
addresses. At the moment, the only characteristic that might differ is au-
thentication method.

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 limi-
tations, most of which are features of the IKE protocol.

Only the initiator may be mobile: the initiator may have an IP number un-
known 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 %any 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 %any 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.

When pluto is using one of these temporary connections and needs to find
the preshared secret or RSA private key in ipsec.secrets, and the connec-
tion specified no identity for the peer, %any is used as its identity. Af-
ter all, the real IP address was apparently unknown to the configuration,
so it is unreasonable to require that it be used in this table.

Part way into the Phase 1 (Main Mode) negotiation using one of these tempo-
rary connection descriptions, pluto will receive an Identity Payload. At
this point, pluto checks for a more appropriate connection, one with an
identity for the peer that matches the payload and would use the same keys
as so far used for authentication. If it finds one, it will switch to using
this better connection (or a temporary one derived from this, if it has
%any 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, pluto terminates negotiation.

Unfortunately, if preshared secret authentication is being used, the Iden-
tity 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 authentication does not require that the responder
knows 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).

When pluto is responding to a Quick Mode negotiation via one of these tem-
porary 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 %any 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, pluto terminates
negotiation.

Be sure to specify an appropriate nexthop for the responder to send a mes-
sage to the initiator: pluto has no way of guessing it (if forwarding isn't
required, use an explicit %direct as the nexthop and the IP address of the
initiator will be filled in; the obsolete notation 0.0.0.0 is still ac-
cepted).

pluto has no special provision for the initiator side. The current (possi-
bly dynamic) IP address and nexthop must be used in defining connections.
These must be properly configured each time the initiator's IP address
changes. pluto has no mechanism to do this automatically.

Although we call this Road Warrior Support, it could also be used to sup-
port encrypted connections with anonymous initiators. The responder's orga-
nization could announce the preshared secret that would be used with unrec-
ognized initiators and let anyone connect. Of course the initiator's iden-
tity would not be authenticated.

If any Road Warrior connections are supported, pluto cannot reject an ex-
change 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 sup-
ported, the first message from an unknown source would be rejected. This
has implications for ease of debugging configurations and for denial of
service attacks.

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 proba-
bly wise to set --keyingtries 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.

Debugging
pluto accepts several optional arguments, useful mostly for debugging. Ex-
cept for --interface, each should appear at most once.

--interface interfacename
specifies that the named real public network interface should be con-
sidered. The interface name specified should not be ipsecN. If the op-
tion 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.

--ikeport port-number
changes the UDP port that pluto will use (default, specified by IANA:
500)

--ctlbase path
basename for control files. path.ctl is the socket through which whack
communicates with pluto. path.pid is the lockfile to prevent multiple
pluto instances. The default is /var/run/pluto/pluto).

--secretsfile file
specifies the file for authentication secrets (default: /usr/lo-
cal/etc/ipsec.secrets). This name is subject to "globbing" as in sh(1),
so every file with a matching name is processed. Quoting is generally
needed to prevent the shell from doing the globbing.

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

--uniqueids
if this option has been selected, whenever a new ISAKMP SA is estab-
lished, 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.

--force-busy
if this option has been selected, pluto will be forced to be "busy". In
this state, which happens when there is a Denial of Service attack,
will force pluto to use cookies before accepting new incoming IKE pack-
ets. Cookies are send and required in ikev1 Aggressive Mode and in
ikev2. This option is mostly used for testing purposes, but can be se-
lected by paranoid administrators as well.

--stderrlog
log goes to standard out {default is to use syslogd(8))

pluto is willing to produce a prodigious amount of debugging information.
There are several classes of debugging output, and pluto may be directed to
produce a selection of them. All lines of debugging output are prefixed
with "| " to distinguish them from normal diagnostic messages.

When pluto is invoked, it may be given arguments to specify which debug
classes to output. The current options are:

--debug help (whack only)
list the debugging classes recognised by pluto

--debug none
disable logging for all debugging classes

--debug base
enable debug-logging

--debug cpu-usage
enable cpu-usage logging

--debug class, --no-debug class, --debug no-class
enable (disable) logging of the specified debugging class (--debug help
lists debugging classes supported by this version of pluto)

The debug form of the whack command will change the selection in a running
pluto. If a connection name is specified, the flags are added whenever
pluto has identified that it is dealing with that connection. Unfortu-
nately, this is often part way into the operation being observed.

For example, to start pluto with both base and cpu-usage debug-logging en-
abled:

pluto --debug base --debug cpu-usage

To later change this pluto to disable base debug-logging use either:

whack --no-debug base

or:

whack --debug none --debug cpu-usage

Impairing
pluto and whack accept several optional arguments that alter (impair) cor-
rect behaviour.

These options are solely intended for use by developers when testing pluto.

--impair help (whack only)
list all the behaviours that can be altered (impaired)

--impair list (whack only)
list all the behaviours that are currently altered (impaired)

--impair none
disable all altered (impaired) behaviours

--impair behaviour, --impair behaviour:how, --no-impair behaviour
alter (impair) pluto inducing the (possibly erroneous) behaviour

Pluto's Behaviour When Things Go Wrong
When pluto doesn't understand or accept a message, it just ignores the mes-
sage. 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.

When pluto 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 un-
reliable.

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.

Combine these three rules, and you can explain many apparently mysterious
behaviours. In a pluto log, retrying isn't usually the interesting event.
The critical thing is either earlier (pluto got a message that it didn't
like and so ignored, so it was still awaiting an acceptable message and got
impatient) or on the other system (pluto didn't send a reply because it
wasn't happy with the previous message).

Notes
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. Pluto also avoids choosing an SPI in the
range 0x100 to 0xFFF, leaving these SPIs free for manual keying. Remember
that the peer, if not pluto, may well chose SPIs in this range.

Policies
This catalogue of policies may be of use when trying to configure Pluto and
another IKE implementation to interoperate.

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.

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 Ex-
changes, but we feel they are broken.

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

*
Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) are supported.
Group MODP768 (1) is not supported because it is too weak.

*
Host authentication can be done by RSA Signatures or Pre-Shared Se-
crets.

*
3DES CBC (Cypher Block Chaining mode) is the only encryption supported,
both for ISAKMP SAs and IPSEC SAs.

*
MD5 and SHA1 hashing are supported for packet authentication in both
kinds of SAs.

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

*
Each of these may be combined with IPCOMP Deflate compression, but only
if the potential connection specifies compression.

*
The IPSEC SAs may be tunnel or transport mode, where appropriate. The
--tunnel flag controls this when pluto is initiating.

*
When responding to an ISAKMP SA proposal, the maximum acceptable life-
time is eight hours. The default is one hour. There is no minimum. The
--ikelifetime flag controls this when pluto is initiating.

*
When responding to an IPSEC SA proposal, the maximum acceptable life-
time is one day. The default is eight hours. There is no minimum. The
--ipseclifetime flag controls this when pluto is initiating.

*
PFS is acceptable, and will be proposed if the --pfs flag was speci-
fied. The DH group proposed will be the same as negotiated for Phase 1.

SIGNALS
Pluto responds to SIGHUP by issuing a suggestion that ``whack --listen''
might have been intended.

Pluto exits when it receives SIGTERM.

EXIT STATUS
pluto normally forks a daemon process, so the exit status is normally a
very preliminary result.

0
means that all is OK so far.

1
means that something was wrong.

10
means that the lock file already exists.

If whack detects a problem, it will return an exit status of 1. If it re-
ceived progress messages from pluto, 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). Other-
wise, the exit status is 0.

FILES
/var/run/pluto/pluto.pid

/var/run/pluto/pluto.ctl

/usr/local/etc/ipsec.secrets

/dev/urandom

ENVIRONMENT
pluto does not use any environment variables

SEE ALSO
The rest of the Libreswan distribution, in particular ipsec(8).

ipsec_auto(8) is designed to make using pluto more pleasant. Use it!

ipsec.secrets(5) describes the format of the secrets file.

ipsec_atoaddr(3), part of the Libreswan distribution, describes the forms
that IP addresses may take. ipsec_atosubnet(3), part of the Libreswan dis-
tribution, describes the forms that subnet specifications.

For more information on IPsec, the mailing list, and the relevant docu-
ments, see:

https://datatracker.ietf.org/wg/ipsecme/charter/

At the time of writing, the latest IETF IKE RFC is:

RFC 7296 Internet Key Exchange Protocol Version 2 (IKEv2)

The Libreswan web site <https://libreswan.org> and the mailing lists de-
scribed there.

The Libreswan wiki <https://libreswan.org/wiki> and the mailing lists de-
scribed there.

The Libreswan list of implemented RFCs <https://libreswan.org/wiki/Imple-
mented_Standards>

HISTORY
This code is released under the GPL terms. See the accompanying files
CHANGES COPYING and CREDITS.* for more details.

Detailed history (including FreeS/WAN and Openswan) can be found in the
docs/ directory.

BUGS
Please see <https://bugs.libreswan.org> for a list of currently known bugs
and missing features.

Bugs should be reported to the <swan-dev@lists.libreswan.org> mailing list.

AUTHOR
Paul Wouters
placeholder to suppress warning

libreswan 08/01/2026 IPSEC_PLUTO(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ipsec_pluto&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages