1IPSEC_PLUTO(8)                Executable programs               IPSEC_PLUTO(8)
2
3
4

NAME

6       ipsec_pluto, ipsec_whack, pluto - ipsec whack : IPsec IKE keying daemon
7       and control interface
8

SYNOPSIS

10       ipsec pluto [--help] [--version] [--leak-detective] [--efence-protect]
11             [--config filename] [--vendorid VID] [--nofork] [--stderrlog]
12             [--logfile filename] [--log-no-time] [--log-no-append]
13             [--log-no-ip] [--log-no-audit] [--use-netkey] [--use-bsdkame]
14             [--uniqueids] [--virtual-private network_list]
15             [--keep-alive delay_sec] [--force-busy] [--crl-strict]
16             [--crlcheckinterval] [--interface interfacename]
17             [--listen ipaddr] [--ikeport portnumber]
18             [--natikeport portnumber] [--rundir path]
19             [--secretsfile secrets-file] [--nhelpers number]
20             [--seedbits numbits] [--ipsecdir dirname] [--nssdir dirname]
21             [--coredir dirname] [--statsbin filename]
22             [--secctx-attr-type number]
23
24       ipsec whack [--help] [--version]
25
26       ipsec whack --name connection-name [[--ipv4] | [--ipv6]]
27             [[--tunnelipv4] | [--tunnelipv6]]
28             [--id identity] [--host ip-address] [--cert friendly_name]
29             [--ckaid CKAID] [--ca distinguished name]
30             [--groups access control groups]
31             [--sendcert yes | forced | always | ifasked | no | never]
32             [--sendca none | issuer | all] [--certtype number]
33             [--ikeport portnumber] [--nexthop ip-address] [[--client subnet]]
34             [--clientprotoport protocol/port] [--srcip ip-address]
35             [--xauthserver] [--xauthclient] [--modecfgserver]
36             [--modecfgclient] [--modecfgdns ip-address, ip-address, ...]
37             [--modecfgdomains DNS-domain, DNS-domain, ...]
38             [--modecfgbanner login-banner] [--dnskeyondemand]
39             [--updown updown]
40             --to
41             [--id identity] [--host ip-address] [--cert friendly_name]
42             [--ckaid CKAID] [--ca distinguished name]
43             [--groups access control groups]
44             [--sendcert yes | always | ifasked | no | never]
45             [--certtype number] [--ikeport port-number]
46             [--nexthop ip-address] [--client subnet]
47             [--clientprotoport protocol/port] [--srcip ip-address]
48             [--xauthserver] [--xauthclient] [--modecfgserver]
49             [--modecfgclient] [--modecfgdns ip-address, ip-address, ...]
50             [--modecfgdomains DNS-domain, DNS-domain, ...] [--dnskeyondemand]
51             [--updown updown]
52
53             [--tunnel] [--psk] [--rsasig] [--encrypt] [--authenticate]
54             [--compress] [--pfs]
55             [--pfsgroup [modp1024] | [modp1536] | [modp2048] | [modp3072] | [modp4096] | [modp6144] | [modp8192] | [dh22] | [dh23] | [dh24]]
56             [--ikelifetime seconds] [--ipseclifetime seconds]
57             [--rekeymargin seconds] [--rekeyfuzz percentage]
58             [--keyingtries count] [--esp esp-algos] [--dontrekey]
59             [--aggrmode] [--modecfgpull] [--metric metric]
60             [--nflog-group nflognum] [--conn-mark mark/mask]
61             [[--dpddelay seconds] | [--dpdtimeout seconds]]
62             [--dpdaction [clear] | [hold] | [restart]] [--forceencaps]
63             [--no-keep-alive]
64             [[--initiateontraffic] | [--pass] | [--drop] | [--reject]]
65             [[--failnone] | [--failpass] | [--faildrop] | [--failreject]]
66             [--rundir path] [--ctlsocket path/file] [--label string]
67
68       ipsec whack --keyid id [--addkey] [--pubkeyrsa key] [--rundir path]
69             [--ctlsocket path/file] [--label string]
70
71       ipsec whack --listen | --unlisten  [--rundir path]
72             [--ctlsocket path/file] [--label string]
73
74       ipsec whack --ddos-auto | --ddos-busy | --ddos-unlimited
75             [--rundir path] [--ctlsocket path/file]
76
77       ipsec whack --route | --unroute  --name connection-name [--rundir path]
78             [--ctlsocket path/file] [--label string]
79
80       ipsec whack --initiate | [--remote-host ip-address] | --terminate |
81             --rekey-ike | --rekey-ipsec  --name connection-name
82             [--xauthuser user] [--xauthpass pass] [--asynchronous]
83             [--rundir path] [--ctlsocket path/file] [--label string]
84
85       ipsec whack --global-redirect yes|no|auto
86
87       ipsec whack --global-redirect-to ip-address(es)
88
89       ipsec whack [--name connection-name] --redirect-to ip-address(es)
90
91       ipsec whack [[--tunnelipv4] | [--tunnelipv6]] --oppohere ip-address
92             --oppothere ip-address --opposport port --oppodport port
93             --oppoproto protocol
94
95       ipsec whack --crash [ipaddress]
96
97       ipsec whack --name connection-name --delete [--ctlbase path]
98             [--label string]
99
100       ipsec whack --deletestate state-number [--rundir path]
101             [--ctlsocket path/file] [--label string]
102
103       ipsec whack --deleteuser --name username [--rundir path]
104             [--ctlsocket path/file] [--label string]
105
106       ipsec whack [--name connection-name]
107             {--debug help | none | base | cpu-usage | class} |
108             {--no-debug class} | {--impair help | none | behaviour} |
109             {--no-impair behaviour}
110
111       ipsec whack [--utc] [--listall] [--listpubkeys] [--listcerts]
112             [--listcacerts] [--listcrls]
113
114       ipsec whack [--utc] [--rereadsecrets] [--fetchcrls] [--rereadall]
115
116       ipsec whack --ddns
117
118       ipsec whack --listevents
119
120       ipsec whack --purgeocsp
121
122       ipsec whack --status --trafficstatus --shuntstatus --addresspoolstatus
123             --processstatus [--rundir path] [--ctlsocket path/file]
124             [--label string]
125
126       ipsec whack --globalstats --clearstats [--rundir path]
127             [--ctlsocket path/file] [--label string]
128
129       ipsec whack [--ike-socket-bufsize bufsize]
130             [--ike-socket-errqueue-toggle] [--rundir path]
131             [--ctlsocket path/file] [--label string]
132
133       ipsec whack --shutdown [--rundir path] [--ctlsocket path/file]
134             [--label string] [--leave-state]
135

DESCRIPTION

137       pluto is an IKE ("IPsec Key Exchange") daemon.  whack is an auxiliary
138       program to allow requests to be made to a running pluto.
139
140       pluto is used to automatically build shared "security associations" on
141       a system that has IPsec, the secure IP protocol. In other words, pluto
142       can eliminate much of the work of manual keying. The actual secure
143       transmission of packets is the responsibility of other parts of the
144       system - the kernel. Pluto can talk to various kernel implementations,
145       such as the Linux XFRM and BSD KAME IPsec stacks.  ipsec_auto(8)
146       provides a more convenient interface to pluto and whack.
147
148   IKE's Job
149       A Security Association (SA) is an agreement between two network nodes
150       on how to process certain traffic between them. This processing
151       involves encapsulation, authentication, encryption, or compression.
152
153       IKE can be deployed on a network node to negotiate Security
154       Associations for that node. These IKE implementations can only
155       negotiate with other IKE implementations, so IKE must be on each node
156       that is to be an endpoint of an IKE-negotiated Security Association. No
157       other nodes need to be running IKE.
158
159       An IKE instance (i.e. an IKE implementation on a particular network
160       node) communicates with another IKE instance using UDP IP packets, so
161       there must be a route between the nodes in each direction.
162
163       The negotiation of Security Associations requires a number of choices
164       that involve tradeoffs between security, convenience, trust, and
165       efficiency. These are policy issues and are normally specified to the
166       IKE instance by the system administrator.
167
168       IKE deals with two kinds of Security Associations. The first part of a
169       negotiation between IKE instances is to build an ISAKMP SA. An ISAKMP
170       SA is used to protect communication between the two IKEs. IPsec SAs can
171       then be built by the IKEs - these are used to carry protected IP
172       traffic between the systems.
173
174       The negotiation of the ISAKMP SA is known as Phase 1. In theory, Phase
175       1 can be accomplished by a couple of different exchange types.
176       Currently, Main Mode and Aggressive Mode are implemented.
177
178       Any negotiation under the protection of an ISAKMP SA, including the
179       negotiation of IPsec SAs, is part of Phase 2. The exchange type that we
180       use to negotiate an IPsec SA is called Quick Mode.
181
182       IKE instances must be able to authenticate each other as part of their
183       negotiation of an ISAKMP SA. This can be done by several mechanisms
184       described in the draft standards.
185
186       IKE negotiation can be initiated by any instance with any other. If
187       both can find an agreeable set of characteristics for a Security
188       Association, and both recognize each others authenticity, they can set
189       up a Security Association. The standards do not specify what causes an
190       IKE instance to initiate a negotiation.
191
192       In summary, an IKE instance is prepared to automate the management of
193       Security Associations in an IPsec environment, but a number of issues
194       are considered policy and are left in the system administrator's hands.
195
196   Pluto
197       pluto is an implementation of IKE. It runs as a daemon on a network
198       node. Currently, this network node must be a Linux system running the
199       XFRM IPsec stack, or a FreeBSD/NetBSD/Mac OSX system running the KAME
200       IPsec stack.
201
202       pluto implements a large subset of IKEv1 and IKEv2.
203
204       The policy for acceptable characteristics for Security Associations is
205       mostly hardwired into the code of pluto (spdb.c). Eventually this will
206       be moved into a security policy database with reasonable expressive
207       power and more convenience.
208
209       pluto uses shared secrets or RSA signatures to authenticate peers with
210       whom it is negotiating. These RSA signatures can come from DNS(SEC), a
211       configuration file, or from X.509 and CA certificates.
212
213       pluto initiates negotiation of a Security Association when it is
214       manually prodded: the program whack is run to trigger this. It will
215       also initiate a negotiation when IPsec traps an outbound packet for
216       Opportunistic Encryption.
217
218       pluto implements ISAKMP SAs itself. After it has negotiated the
219       characteristics of an IPsec SA, it directs the kernel to implement it.
220       If necessary, it also invokes a script to adjust any firewall and issue
221       route(8) commands to direct IP packets.
222
223       When pluto shuts down, it closes all Security Associations.
224
225   Before Running Pluto
226       pluto runs as a daemon with userid root. Before running it, a few
227       things must be set up.
228
229       pluto requires a working IPsec stack.
230
231       pluto supports multiple public networks (that is, networks that are
232       considered insecure and thus need to have their traffic encrypted or
233       authenticated). It discovers the public interfaces to use by looking at
234       all interfaces that are configured (the --interface option can be used
235       to limit the interfaces considered). It does this only when whack tells
236       it to --listen, so the interfaces must be configured by then. The
237       --listen can be used to limit listening on only 1 IP address of a
238       certain interface.  ifconfig(8) or ip(8) with the -a flag will show the
239       name and status of each network interface.
240
241       pluto requires a database of preshared secrets and RSA private keys.
242       This is described in the ipsec.secrets(5).  pluto is told of RSA public
243       keys via whack commands. If the connection is Opportunistic, and no RSA
244       public key is known, pluto will attempt to fetch RSA keys using the
245       Domain Name System.
246
247   Setting up XFRM for pluto
248       No special requirements are necessary to use XFRM - it ships with all
249       modern versions of Linux 2.4 and later.
250
251   ipsec.secrets file
252       A pluto daemon and another IKE daemon (for example, another instance of
253       pluto) must convince each other that they are who they are supposed to
254       be before any negotiation can succeed. This authentication is
255       accomplished by using either secrets that have been shared beforehand
256       (manually) or by using RSA signatures. There are other techniques, but
257       they have not been implemented in pluto.
258
259       The file /etc/ipsec.secrets is used to keep preshared secret keys and
260       XAUTH passwords. RSA private keys, X.509 certificates, CRLs, OCSP and
261       smartcards are handled via NSS. For debugging, there is an argument to
262       the pluto command to use a different file. This file is described in
263       ipsec.secrets(5).
264
265   Running Pluto
266       To fire up the daemon, just type pluto (be sure to be running as the
267       superuser). The default IKE port number is 500, the UDP port assigned
268       by IANA for IKE Daemons.  pluto must be run by the superuser to be able
269       to use the UDP 500 port. If pluto is told to enable NAT-Traversal, then
270       UDP port 4500 is also taken by pluto to listen on.
271
272       Pluto supports different IPstacks on different operating systems. This
273       can be configured using one of the options --use-netkey (Linux),
274       --use-bsdkame (BSD). On startup, pluto might also read the protostack=
275       option to select the IPsec stack to use if --config /etc/ipsec.conf is
276       given as argument to pluto. If both --use-XXX and --config
277       /etc/ipsec.conf are specified, the last command line argument specified
278       takes precedence.
279
280       Pluto supports RFC 3947 NAT-Traversal. The allowed range behind the NAT
281       routers is submitted using the --virtual-private option. See
282       ipsec.conf(5) for the syntax. The option --force-keepalive forces the
283       sending of the keep-alive packets, which are send to prevent the NAT
284       router from closing its port when there is not enough traffic on the
285       IPsec connection. The --keep-alive sets the delay (in seconds) of these
286       keep-alive packets. The newer NAT-T standards support port floating,
287       and Libreswan enables this per default.
288
289       Pluto supports the use of X.509 certificates and sends certificates
290       when needed. Pluto uses NSS for all X.509 related data, including
291       CAcerts, certs, CRLs and private keys. The Certificate Revocation Lists
292       can also be retrieved from an URL. The option --crlcheckinterval sets
293       the time between checking for CRL expiration and issuing new fetch
294       commands. The first attempt to update a CRL is started at
295       2*crlcheckinterval before the next update time. Pluto logs a warning if
296       no valid CRL was loaded or obtained for a connection. If --crl-strict
297       is given, the connection will be rejected until a valid CRL has been
298       loaded.
299
300       Pluto can also use helper children to off-load cryptographic
301       operations. This behavior can be fine tuned using the --nhelpers. Pluto
302       will start (n-1) of them, where n is the number of CPU's you have
303       (including hypherthreaded CPU's). A value of 0 forces pluto to do all
304       operations in the main process. A value of -1 tells pluto to perform
305       the above calculation. Any other value forces the number to that
306       amount.
307
308       Pluto uses the NSS crypto library as its random source. Some government
309       Three Letter Agency requires that pluto reads 440 bits from /dev/random
310       and feed this into the NSS RNG before drawing random from the NSS
311       library, despite the NSS library itself already seeding its internal
312       state. As this process can block pluto for an extended time, the
313       default is to not perform this redundant seeding. The --seedbits option
314       can be used to specify the number of bits that will be pulled from
315       /dev/random and seeded into the NSS RNG. This can also be accomplished
316       by specifying seedbits in the "config setup" section of ipsec.conf.
317       This option should not be used by most people.
318
319       pluto attempts to create a lockfile with the name
320       /var/run/pluto/pluto.pid. If the lockfile cannot be created, pluto
321       exits - this prevents multiple plutos from competing Any "leftover"
322       lockfile must be removed before pluto will run.  pluto writes its PID
323       into this file so that scripts can find it. This lock will not function
324       properly if it is on an NFS volume (but sharing locks on multiple
325       machines doesn't make sense anyway).
326
327       pluto then forks and the parent exits. This is the conventional "daemon
328       fork". It can make debugging awkward, so there is an option to suppress
329       this fork. In certain configurations, pluto might also launch helper
330       programs to assist with DNS queries or to offload cryptographic
331       operations.
332
333       All logging, including diagnostics, is sent to syslog(3) with
334       facility=authpriv; it decides where to put these messages (possibly in
335       /var/log/secure or /var/log/auth.log). Since this too can make
336       debugging awkward, the option --stderrlog is used to steer logging to
337       stderr.
338
339       Alternatively, --logfile can be used to send all logging information to
340       a specific file.
341
342       Once pluto is started, it waits for requests from whack.
343
344   Pluto's Internal State
345       To understand how to use pluto, it is helpful to understand a little
346       about its internal state. Furthermore, the terminology is needed to
347       decipher some of the diagnostic messages.
348
349       Pluto supports food groups for Opportunistic IPsec. The policies for
350       these are located in /etc/ipsec.d/policies, or another directory as
351       specified by --ipsecdir.
352
353       Pluto supports X.509 Certificates. All certificate handling is done
354       using the NSS library and all certificate material is stored in an NSS
355       database in /var/lib/ipsec/nss or another directory as specified by
356       --nssdir.
357
358       Pluto may core dump. It will normally do so into the current working
359       directory. You can specify the --coredir option for pluto, or specify
360       the dumpdir= option in ipsec.conf.
361
362       If you are investigating a potential memory leak in pluto, start pluto
363       with the --leak-detective option. Before the leak causes the system or
364       pluto to die, shut down pluto in the regular way. pluto will display a
365       list of leaks it has detected.
366
367       If you are investigating a potential use-after-free or double-free in
368       pluto, first build pluto with USE_EFENCE=true and then start pluto with
369       --efence-protect. See efence(2) and EF_PROTECT_BELOW and
370       EF_PROTECT_FREE.
371
372       The (potential) connection database describes attributes of a
373       connection. These include the IP addresses of the hosts and client
374       subnets and the security characteristics desired.  pluto requires this
375       information (simply called a connection) before it can respond to a
376       request to build an SA. Each connection is given a name when it is
377       created, and all references are made using this name.
378
379       During the IKE exchange to build an SA, the information about the
380       negotiation is represented in a state object. Each state object
381       reflects how far the negotiation has reached. Once the negotiation is
382       complete and the SA established, the state object remains to represent
383       the SA. When the SA is terminated, the state object is discarded. Each
384       State object is given a serial number and this is used to refer to the
385       state objects in logged messages.
386
387       Each state object corresponds to a connection and can be thought of as
388       an instantiation of that connection. At any particular time, there may
389       be any number of state objects corresponding to a particular
390       connection. Often there is one representing an ISAKMP SA and another
391       representing an IPsec SA.
392
393       XFRM requires no special routing.
394
395       Each connection may be routed, and must be while it has an IPsec SA.
396       The connection specifies the characteristics of the route: the
397       interface on this machine, the "gateway" (the nexthop), and the peer's
398       client subnet. Two connections may not be simultaneously routed if they
399       are for the same peer's client subnet but use different interfaces or
400       gateways (pluto's logic does not reflect any advanced routing
401       capabilities).
402
403       When pluto needs to install a route for a connection, it must make sure
404       that no conflicting route is in use. If another connection has a
405       conflicting route, that route will be taken down, as long as there is
406       no IPsec SA instantiating that connection. If there is such an IPsec
407       SA, the attempt to install a route will fail.
408
409       There is an exception. If pluto, as Responder, needs to install a route
410       to a fixed client subnet for a connection, and there is already a
411       conflicting route, then the SAs using the route are deleted to make
412       room for the new SAs. The rationale is that the new connection is
413       probably more current. The need for this usually is a product of Road
414       Warrior connections (these are explained later; they cannot be used to
415       initiate).
416
417       When pluto needs to install an eroute for an IPsec SA (for a state
418       object), first the state object's connection must be routed (if this
419       cannot be done, the eroute and SA will not be installed). If a
420       conflicting eroute is already in place for another connection, the
421       eroute and SA will not be installed (but note that the routing
422       exception mentioned above may have already deleted potentially
423       conflicting SAs). If another IPsec SA for the same connection already
424       has an eroute, all its outgoing traffic is taken over by the new
425       eroute. The incoming traffic will still be processed. This
426       characteristic is exploited during rekeying.
427
428   Using whack
429       whack is used to command a running pluto.  whack uses a UNIX domain
430       socket to speak to pluto (by default, /var/pluto.ctl).
431
432       whack has an intricate argument syntax. This syntax allows many
433       different functions to be specified. The help form shows the usage or
434       version information. The connection form gives pluto a description of a
435       potential connection. The public key form informs pluto of the RSA
436       public key for a potential peer. The delete form deletes a connection
437       description and all SAs corresponding to it. The listen form tells
438       pluto to start or stop listening on the public interfaces for IKE
439       requests from peers. The route form tells pluto to set up routing for a
440       connection; the unroute form undoes this. The initiate form tells pluto
441       to negotiate an SA corresponding to a connection. The terminate form
442       tells pluto to remove all SAs corresponding to a connection, including
443       those being negotiated. The status form displays the pluto's internal
444       state. The debug form tells pluto to change the selection of debugging
445       output "on the fly". The shutdown form tells pluto to shut down,
446       deleting all SAs.
447
448       The crash option asks pluto to consider a particularly target IP to
449       have crashed, and to attempt to restart all connections with that IP
450       address as a gateway. In general, you should use Dead Peer Detection to
451       detect this kind of situation automatically, but this is not always
452       possible.
453
454       Most options are specific to one of the forms, and will be described
455       with that form. There are three options that apply to all forms.
456
457       --ctlsocket path/file
458           file is used as the UNIX domain socket for talking to pluto. Use
459           either this option or --rundir, but not both.
460
461       --rundir path
462           path where the UNIX domain socket for talking to the pluto, the
463           pluto.pid file and the pluto.lock files are found. Use either this
464           option or --ctlsocket, but not both.
465
466       --label string
467           adds the string to all error messages generated by whack.
468
469       The help form of whack is self-explanatory.
470
471       --help
472           display the usage message.
473
474       --version
475           display the version of whack.
476
477       The connection form describes a potential connection to pluto.  pluto
478       needs to know what connections can and should be negotiated. When pluto
479       is the initiator, it needs to know what to propose. When pluto is the
480       responder, it needs to know enough to decide whether is is willing to
481       set up the proposed connection.
482
483       The description of a potential connection can specify a large number of
484       details. Each connection has a unique name. This name will appear in a
485       updown shell command, so it should not contain punctuation that would
486       make the command ill-formed.
487
488       --name connection-name
489           sets the name of the connection
490
491       The topology of a connection is symmetric, so to save space here is
492       half a picture:
493
494          client_subnet<-->host:ikeport<-->nexthop<---
495
496       A similar trick is used in the flags. The same flag names are used for
497       both ends. Those before the --to flag describe the left side and those
498       afterwards describe the right side. When pluto attempts to use the
499       connection, it decides whether it is the left side or the right side of
500       the connection, based on the IP numbers of its interfaces.
501
502       --id id
503           the identity of the end. Currently, this can be an IP address
504           (specified as dotted quad or as a Fully Qualified Domain Name,
505           which will be resolved immediately) or as a Fully Qualified Domain
506           Name itself (prefixed by "@" to signify that it should not be
507           resolved), or as user@FQDN, or an X.509 DN.  Pluto only
508           authenticates the identity, and does not use it for addressing, so,
509           for example, an IP address need not be the one to which packets are
510           to be sent. If the option is absent, the identity defaults to the
511           IP address specified by --host.
512
513       --host ip-address, --host %any, --host %opportunistic
514           the IP address of the end (generally the public interface). If
515           pluto is to act as a responder for IKE negotiations initiated from
516           unknown IP addresses (the "Road Warrior" case), the IP address
517           should be specified as %any (currently, the obsolete notation
518           0.0.0.0 is also accepted for this). If pluto is to
519           opportunistically initiate the connection, use %opportunistic
520
521       --cert friendly_name
522           The friendly_name (or nickname) of the X.509 certificate that was
523           used when imported the certificate into the NSS database. See
524           ipsec.conf(5) on how to extract this from the PKCS#12 file.
525
526       --ckaid CKAID
527           The hex CKAID of the X.509 certificate. Certificates are stored in
528           the NSS database.
529
530       --ca distinguished name
531           the X.509 Certificate Authority's Distinguished Name (DN) used as
532           trust anchor for this connection. This is the CA certificate that
533           signed the host certificate, as well as the certificate of the
534           incoming client.
535
536       --groups access control groups
537           the access control groups used.
538
539       --sendcert yes|forced|always|ifasked|no|never
540           Whether or not to send our X.509 certificate credentials. This
541           could potentially give an attacker too much information about which
542           identities are allowed to connect to this host. The default is to
543           use ifasked when we are a Responder, and to use yes (which is the
544           same as forced and always if we are an Initiator. The values no and
545           never are equivalent. NOTE: "forced" does not seem to be actually
546           implemented - do not use it.
547
548       --sendca none|issuer|all
549           How much of our available X.509 trust chain to send with the end
550           certificate, excluding any root CAs. Specifying issuer sends just
551           the issuing intermediate CA, while
552            all will send the entire chain of intermediate CAs.none will not
553           send any CA certs. The default is none which maintains the current
554           libreswan behavior.
555
556       --certtype number
557           The X.509 certificate type number.
558
559       --ikeport port-number
560           the UDP port that IKE listens to on that host. The default is 500.
561           (pluto on this machine uses the port specified by its own command
562           line argument, so this only affects where pluto sends messages.)
563
564       --nexthop ip-address
565           where to route packets for the peer's client (presumably for the
566           peer too, but it will not be used for this). When pluto installs an
567           IPsec SA, it issues a route command. It uses the nexthop as the
568           gateway. The default is the peer's IP address (this can be
569           explicitly written as %direct; the obsolete notation 0.0.0.0 is
570           accepted). This option is necessary if pluto's host's interface
571           used for sending packets to the peer is neither point-to-point nor
572           directly connected to the peer.
573
574       --client subnet
575           the subnet for which the IPsec traffic will be destined. If not
576           specified, the host will be the client. The subnet can be specified
577           in any of the forms supported by ipsec_atosubnet(3). The general
578           form is address/mask. The address can be either a domain name or
579           four decimal numbers (specifying octets) separated by dots. The
580           most convenient form of the mask is a decimal integer, specifying
581           the number of leading one bits in the mask. So, for example,
582           10.0.0.0/8 would specify the class A network "Net 10".
583
584       --clientprotoport protocol/port
585           specify the Port Selectors (filters) to be used on this connection.
586           The general form is protocol/port. This is most commonly used to
587           limit the connection to L2TP traffic only by specifying a value of
588           17/1701 for UDP (protocol 17) and port 1701. The notation 17/%any
589           can be used to allow all UDP traffic and is needed for L2TP
590           connections with Windows XP machines before Service Pack 2.
591
592       --srcip ip-address
593           the IP address for this host to use when transmitting a packet to
594           the remote IPsec gateway itself. This option is used to make the
595           gateway itself use its internal IP, which is part of the --client
596           subnet. Otherwise it will use its nearest IP address, which is its
597           public IP address, which is not part of the subnet-subnet IPsec
598           tunnel, and would therefore not get encrypted.
599
600       --xauthserver
601           this end is an xauthserver. It will lookup the xauth user name and
602           password and verify this before allowing the connection to get
603           established.
604
605       --xauthclient
606           this end is an xauthclient. To bring this connection up with the
607           --initiate also requires the client to specify --xauthuser username
608           and --xauthpass password
609
610       --xauthuser
611           The username for the xauth authentication.This option is normally
612           passed along by ipsec_auto(8) when an xauth connection is started
613           using ipsec auto --up conn
614
615       --xauthpass
616           The password for the xauth authentication. This option is normally
617           passed along by ipsec_auto(8) when an xauth connection is started
618           using ipsec auto --up conn
619
620       --modecfgserver
621           this end is an Mode Config server
622
623       --modecfgclient
624           this end is an Mode Config client
625
626       --modecfgdns
627           A comma separated list of DNS server IP's to pass along to
628           connecting clients
629
630       --modecfgdomains
631           A comma separated list of internal DNS domains to pass along to
632           connecting clients
633
634       --dnskeyondemand
635           specifies that when an RSA public key is needed to authenticate
636           this host, and it isn't already known, fetch it from DNS.
637
638       --updown updown
639           specifies an external shell command to be run whenever pluto brings
640           up or down a connection. The script is used to build a shell
641           command, so it may contain positional parameters, but ought not to
642           have punctuation that would cause the resulting command to be
643           ill-formed. The default is ipsec _updown. Pluto passes a dozen
644           environment variables to the script about the connection involved.
645
646       --to
647           separates the specification of the left and right ends of the
648           connection. Pluto tries to decide whether it is left or right based
649           on the information provided on both sides of this option.
650
651       The potential connection description also specifies characteristics of
652       rekeying and security.
653
654       --psk
655           Propose and allow preshared secret authentication for IKE peers.
656           This authentication requires that each side use the same secret.
657           May be combined with --rsasig; at least one must be specified.
658
659       --rsasig
660           Propose and allow RSA signatures for authentication of IKE peers.
661           This authentication requires that each side have have a private key
662           of its own and know the public key of its peer. May be combined
663           with --psk; at least one must be specified.
664
665       --encrypt
666           All proposed or accepted IPsec SAs will include non-null ESP. The
667           actual choices of transforms are wired into pluto.
668
669       --authenticate
670           All proposed IPsec SAs will include AH. All accepted IPsec SAs will
671           include AH or ESP with authentication. The actual choices of
672           transforms are wired into pluto. Note that this has nothing to do
673           with IKE authentication.
674
675       --compress
676           All proposed IPsec SAs will include IPCOMP (compression).
677
678       --tunnel
679           the IPsec SA should use tunneling. Implicit if the SA is for
680           clients. Must only be used with --authenticate or --encrypt.
681
682       --ipv4
683           The host addresses will be interpreted as IPv4 addresses. This is
684           the default. Note that for a connection, all host addresses must be
685           of the same Address Family (IPv4 and IPv6 use different Address
686           Families).
687
688       --ipv6
689           The host addresses (including nexthop) will be interpreted as IPv6
690           addresses. Note that for a connection, all host addresses must be
691           of the same Address Family (IPv4 and IPv6 use different Address
692           Families).
693
694       --tunnelipv4
695           The client addresses will be interpreted as IPv4 addresses. The
696           default is to match what the host will be. This does not imply
697           --tunnel so the flag can be safely used when no tunnel is actually
698           specified. Note that for a connection, all tunnel addresses must be
699           of the same Address Family.
700
701       --tunnelipv6
702           The client addresses will be interpreted as IPv6 addresses. The
703           default is to match what the host will be. This does not imply
704           --tunnel so the flag can be safely used when no tunnel is actually
705           specified. Note that for a connection, all tunnel addresses must be
706           of the same Address Family.
707
708       --pfs
709           There should be Perfect Forward Secrecy - new keying material will
710           be generated for each IPsec SA when running Quick Mode in IKEv1 or
711           Create Child in IKEv2. Without this option, the SAKMP SA keying
712           material is used instead.  pluto will propose the same group that
713           was used with the original IKE SA.
714
715       --pfsgroup modp-group
716           Sets the Diffie-Hellman group used. Currently the following values
717           are supported: modp1024 (DHgroup 2), modp1536 (DHgroup 5), modp2048
718           (DHgroup 14), modp3072 (DHgroup 15), modp4096 (DHgroup 16),
719           modp6144 (DHgroup 17), and modp8192 (DHgroup 18). It is possible to
720           support the weak and broken modp768 (DHgroup 1), but this requires
721           a manual recompile and is strongly discouraged.
722
723       --esp esp-algos
724           ESP encryption/authentication algorithm to be used for the
725           connection (phase2 aka IPsec SA). The options must be suitable as a
726           value of ipsec_spi(8). See ipsec.conf(5) for a detailed description
727           of the algorithm format.
728
729       --aggrmode
730           This tunnel is using aggressive mode ISAKMP negotiation. The
731           default is main mode. Aggressive mode is less secure than main mode
732           as it reveals your identity to an eavesdropper, but is needed to
733           support road warriors using PSK keys or to interoperate with other
734           buggy implementations insisting on using aggressive mode.
735
736       --modecfgpull
737           Pull the Mode Config network information from the peer.
738
739       --dpddelay seconds
740           Set the delay (in seconds) between Dead Peer Detection (RFC 3706)
741           keepalives (R_U_THERE, R_U_THERE_ACK) that are sent for this
742           connection (default 30 seconds).
743
744       --timeout seconds
745           Set the length of time (in seconds) we will idle without hearing
746           either an R_U_THERE poll from our peer, or an R_U_THERE_ACK reply.
747           After this period has elapsed with no response and no traffic, we
748           will declare the peer dead, and remove the SA (default 120
749           seconds).
750
751       --dpdaction action
752           When a DPD enabled peer is declared dead, what action should be
753           taken.  hold(default) means the eroute will be put into %hold
754           status, while clearmeans the eroute and SA with both be cleared.
755           Clear is really only useful on the server of a Road Warrior config.
756           The action restart is used on tunnels that need to be permanently
757           up, and have static IP addresses. The action restart_by_peerhas
758           been obsoleted and its functionality has been moved into the
759           restart action.
760
761       --forceencaps
762           In some cases, for example when ESP packets are filtered or when a
763           broken IPsec peer does not properly recognise NAT, it can be useful
764           to force RFC-3948 encapsulation using this option. It causes pluto
765           lie and tell the remote peer that RFC-3948 encapsulation (ESP in
766           UDP port 4500 packets) is required.
767
768       If none of the --encrypt, --authenticate, --compress, or --pfs flags is
769       given, the initiating the connection will only build an ISAKMP SA. For
770       such a connection, client subnets have no meaning and must not be
771       specified.
772
773       Apart from initiating directly using the --initiate option, a tunnel
774       can be loaded with a different policy
775
776       --initiateontraffic
777           Only initiate the connection when we have traffic to send over the
778           connection
779
780       --pass
781           Allow unencrypted traffic to flow until the tunnel is initiated.
782
783       --drop
784           Drop unencrypted traffic silently.
785
786       --reject
787           Drop unencrypted traffic silently, but send an ICMP message
788           notifying the other end.
789
790       These options need to be documented
791
792       --failnone
793           to be documented
794
795       --failpass
796           to be documented
797
798       --faildrop
799           to be documented
800
801       --failreject
802           to be documented
803
804       pluto supports various X.509 Certificate related options.
805
806       --utc
807           display all times in UTC.
808
809       --listall
810           lists all of the X.509 information known to pluto.
811
812       --listpubkeys
813           list all the public keys that have been successfully loaded.
814
815       --listcerts
816           list all the X.509 certificates that are currently loaded.
817
818       --checkpubkeys
819           list all the loaded X.509 certificates that are about to expire or
820           have expired.
821
822       --listcacerts
823           list all the Certificate Authority X.509 certificates that are
824           currently loaded.
825
826       --listcrls
827           list all the loaded Certificate Revocation Lists (CRLs)
828
829       The corresponding options --rereadsecrets, --rereadall, and
830       --rereadcrls options reread this information from their respective
831       sources, and purge all the online obtained information. The option
832       --listevents lists all pending events, and the --ddns triggers the
833       Dynamic DNS update event that is normally scheduled to run once every
834       minute.
835
836       --ikelifetime seconds
837           how long pluto will propose that an ISAKMP SA be allowed to live.
838           The default is 3600 (one hour) and the maximum is 86400 (1 day).
839           This option will not affect what is accepted.  pluto will reject
840           proposals that exceed the maximum.
841
842       --ipseclifetime seconds
843           how long pluto will propose that an IPsec SA be allowed to live.
844           The default is 28800 (eight hours) and the maximum is 86400 (one
845           day). This option will not affect what is accepted.  pluto will
846           reject proposals that exceed the maximum.
847
848       --rekeymargin seconds
849           how long before an SA's expiration should pluto try to negotiate a
850           replacement SA. This will only happen if pluto was the initiator.
851           The default is 540 (nine minutes).
852
853       --rekeyfuzz percentage
854           maximum size of random component to add to rekeymargin, expressed
855           as a percentage of rekeymargin.  pluto will select a delay
856           uniformly distributed within this range. By default, the percentage
857           will be 100. If greater determinism is desired, specify 0. It may
858           be appropriate for the percentage to be much larger than 100.
859
860       --keyingtries count
861           how many times pluto should try to negotiate an SA, either for the
862           first time or for rekeying. The default value of 0 means to keep
863           trying forever.
864
865       --dontrekey
866           A misnomer. Only rekey a connection if we were the Initiator and
867           there was recent traffic on the existing connection. This applies
868           to Phase 1 and Phase 2. This is currently the only automatic way
869           for a connection to terminate. It may be useful with Road Warrior
870           or Opportunistic connections.  Since SA lifetime negotiation is
871           take-it-or-leave it, a Responder normally uses the shorter of the
872           negotiated or the configured lifetime. This only works because if
873           the lifetime is shorter than negotiated, the Responder will rekey
874           in time so that everything works. This interacts badly with
875           --dontrekey. In this case, the Responder will end up rekeying to
876           rectify a shortfall in an IPsec SA lifetime; for an ISAKMP SA, the
877           Responder will accept the negotiated lifetime.
878
879       --delete
880           when used in the connection form, it causes any previous connection
881           with this name to be deleted before this one is added. Unlike a
882           normal delete, no diagnostic is produced if there was no previous
883           connection to delete. Any routing in place for the connection is
884           undone.
885
886       --delete, --name connection-name
887           The delete form deletes a named connection description and any SAs
888           established or negotiations initiated using this connection. Any
889           routing in place for the connection is undone.
890
891       --deletestate state-number
892           The deletestate form deletes the state object with the specified
893           serial number. This is useful for selectively deleting instances of
894           connections.
895
896       The route form of the whack command tells pluto to set up routing for a
897       connection. Although like a traditional route, it uses an ipsec device
898       as a virtual interface. Once routing is set up, no packets will be sent
899       "in the clear" to the peer's client specified in the connection. A TRAP
900       shunt eroute will be installed; if outbound traffic is caught, Pluto
901       will initiate the connection. An explicit whack route is not always
902       needed: if it hasn't been done when an IPsec SA is being installed, one
903       will be automatically attempted.
904
905       --route, --name connection-name
906           When a routing is attempted for a connection, there must not
907           already be a routing for a different connection with the same
908           subnet but different interface or destination, or if there is, it
909           must not be being used by an IPsec SA. Otherwise the attempt will
910           fail.
911
912       --unroute, --name connection-name
913           The unroute form of the whack command tells pluto to undo a
914           routing.  pluto will refuse if an IPsec SA is using the connection.
915           If another connection is sharing the same routing, it will be left
916           in place. Without a routing, packets will be sent without
917           encryption or authentication.
918
919       The initiate form tells pluto to initiate a negotiation with another
920       pluto (or other IKE daemon) according to the named connection.
921       Initiation requires a route that --route would provide; if none is in
922       place at the time an IPsec SA is being installed, pluto attempts to set
923       one up.
924
925       --initiate, --name connection-name, --asynchronous
926           The initiate form of the whack command will relay back from pluto
927           status information via the UNIX domain socket (unless
928           --asynchronous is specified). The status information is meant to
929           look a bit like that from FTP. Currently whack simply copies this
930           to stderr. When the request is finished (eg. the SAs are
931           established or pluto gives up), pluto closes the channel, causing
932           whack to terminate.
933
934       The opportunistic initiate form is mainly used for debugging.
935
936       --tunnelipv4, --tunnelipv6, --oppohere  ip-address, --oppothere
937       ip-address, --opposport  port, --oppodport  port, --oppoproto  protocol
938           This will cause pluto to attempt to opportunistically initiate a
939           connection from here to the there, even if a previous attempt had
940           been made. The whack log will show the progress of this attempt.
941
942       Rekeying a connection
943
944       --rekey-ipsec, --name connection-name
945           the rekey-ipsec form tells pluto to rekey the IPsec SA (child SA)
946           of the specified connection. It does not affect the IKE SA (parent
947           SA)
948
949       --rekey-ike, --name connection-name
950           the rekey-ike form tells pluto to rekey the IKE SA (parent SA) of
951           the specified connection. It does not affect the IPsec SAs (child
952           SAs)
953
954       Ending a connection
955
956       --terminate, --name connection-name
957           the terminate form tells pluto to delete any SAs that use the
958           specified connection and to stop any negotiations in process. it
959           does not prevent new negotiations from starting (the delete form
960           has this effect).
961
962       --crash ip-address
963           If the remote peer has crashed, and therefore did not notify us, we
964           keep sending encrypted traffic, and rejecting all plaintext
965           (non-IKE) traffic from that remote peer. The --crash brings our end
966           down as well for all the known connections to the specified
967           ip-address
968
969       ip-address
970           If the remote peer has crashed, and therefore did not notify us, we
971           keep sending encrypted traffic, and rejecting all plaintext
972           (non-IKE) traffic from that remote peer. The --crash brings our end
973           down as well for all the known connections to the specified
974           ip-address
975
976       Redirecting clients can be done using IKEv2 redirect mechanism.
977
978       --global-redirect yes|no|auto
979           The --global-redirect option controls whether pluto will instruct
980           remote peers to redirect IKE/IPsec SA's during IKE_SA_INIT. Valid
981           options are no, yes and auto, where auto means remote peers will be
982           redirected if DDoS mode is active.
983
984       --global-redirect-to ip-address(es)
985           The destination, or a list of destinations, where the peers will be
986           redirected.
987
988       --name connection_name, --redirect-to ip-address(es)
989           The destination, or a list of destinations, where the peers will be
990           redirected. Specifying the connection name is optional. If not
991           specified the mechanism will redirect all currently active peers.
992           If specified, only the peers from connection connection_name will
993           be redirected.
994
995       The public key for informs pluto of the RSA public key for a potential
996       peer. Private keys must be kept secret, so they are kept in
997       ipsec.secrets(5).
998
999       --keyid id
1000           specififies the identity of the peer for which a public key should
1001           be used. Its form is identical to the identity in the connection.
1002           If no public key is specified, pluto attempts to find KEY records
1003           from DNS for the id (if a FQDN) or through reverse lookup (if an IP
1004           address). Note that there several interesting ways in which this is
1005           not secure.
1006
1007       --addkey
1008           specifies that the new key is added to the collection; otherwise
1009           the new key replaces any old ones.
1010
1011       --pubkeyrsa key
1012           specifies the value of the RSA public key. It is a sequence of
1013           bytes as described in RFC 2537 "RSA/MD5 KEYs and SIGs in the Domain
1014           Name System (DNS)". It is denoted in a way suitable for
1015           ipsec_ttodata(3). For example, a base 64 numeral starts with 0s.
1016
1017       The listen form tells pluto to start listening for IKE requests on its
1018       public interfaces. To avoid race conditions, it is normal to load the
1019       appropriate connections into pluto before allowing it to listen. If
1020       pluto isn't listening, it is pointless to initiate negotiations, so it
1021       will refuse requests to do so. Whenever the listen form is used, pluto
1022       looks for public interfaces and will notice when new ones have been
1023       added and when old ones have been removed. This is also the trigger for
1024       pluto to read the ipsec.secrets file. So listen may useful more than
1025       once.
1026
1027       --listen
1028           start listening for IKE traffic on public interfaces.
1029
1030       --unlisten
1031           stop listening for IKE traffic on public interfaces.
1032
1033       The --ddos-auto, --ddos-busy and --ddos-unlimited options tells pluto
1034       to update the DDoS protection state. Normally, these measures are
1035       automatically activated or deactivated based on the number of states
1036       inside pluto. The busy and unlimited option tells pluto to activate or
1037       deactivate the DDoS protection mode manually. One of these DDoS
1038       protection methods is to activate IKEv2 DCOOKIEs to defend against
1039       spoofed IKE packets.
1040
1041       --ddos-busy
1042           place pluto into busy mode and activate anti-DDoS measures.
1043
1044       --ddos-unlimited
1045           pull pluto out of busy mode and deactivate anti-DDoS measures.
1046
1047       --ddos-auto
1048           activate the built-in detection mechanism for the anti-DDoS
1049           measures.
1050
1051       The status form will display information about the internal state of
1052       pluto: information about each potential connection, about each state
1053       object, and about each shunt that pluto is managing without an
1054       associated connection.
1055
1056       Statistics can be seen using ipsec whack --globalstats and reset using
1057       ipsec whack --clearstats. This can be used with the munin software to
1058       monitor VPN services.
1059
1060       --status
1061
1062       The trafficstatus form will display the xauth username, add_time and
1063       the total in and out bytes of the IPsec SA's.
1064
1065       --trafficstatus
1066
1067       The shutdown form is the proper way to shut down pluto. It will tear
1068       down the SAs on this machine that pluto has negotiated. If the
1069       --leave-state option is given, it does not delete any connections, and
1070       leaves the kernel state in the kernel. Note that the init system used
1071       might clean up the kernel state regardless.
1072
1073       --shutdown
1074
1075   Examples
1076       It would be normal to start pluto in one of the system initialization
1077       scripts. It needs to be run by the superuser. Generally, no arguments
1078       are needed. To run in manually, the superuser can simply type
1079
1080          ipsec pluto
1081
1082       The command will immediately return, but a pluto process will be left
1083       running, waiting for requests from whack or a peer.
1084
1085       Using whack, several potential connections would be described:
1086
1087          ipsec whack --name silly --host 127.0.0.1 --to --host 127.0.0.2
1088       --ikelifetime 900 --ipseclifetime 800 --keyingtries 3
1089
1090       Since this silly connection description specifies neither encryption,
1091       authentication, nor tunneling, it could only be used to establish an
1092       ISAKMP SA.
1093
1094          ipsec whack --name conn_name --host 10.0.0.1 --client 10.0.1.0/24
1095       --to --host 10.0.0.2 --client 10.0.2.0/24 --encrypt
1096
1097       This is something that must be done on both sides. If the other side is
1098       pluto, the same whack command could be used on it (the command syntax
1099       is designed to not distinguish which end is ours).
1100
1101       Now that the connections are specified, pluto is ready to handle
1102       requests and replies via the public interfaces. We must tell it to
1103       discover those interfaces and start accepting messages from peers:
1104
1105          ipsec whack --listen
1106
1107       If we don't immediately wish to bring up a secure connection between
1108       the two clients, we might wish to prevent insecure traffic. The routing
1109       form asks pluto to cause the packets sent from our client to the peer's
1110       client to be routed through the ipsec0 device; if there is no SA, they
1111       will be discarded:
1112
1113          ipsec whack --route conn_name
1114
1115       Finally, we are ready to get pluto to initiate negotiation for an IPsec
1116       SA (and implicitly, an ISAKMP SA):
1117
1118          ipsec whack --initiate --name conn_name
1119
1120       A small log of interesting events will appear on standard output (other
1121       logging is sent to syslog).
1122
1123       whack can also be used to terminate pluto cleanly, tearing down all SAs
1124       that it has negotiated.
1125
1126          ipsec whack --shutdown
1127
1128       Notification of any IPSEC SA deletion, but not ISAKMP SA deletion is
1129       sent to the peer. Unfortunately, such Notification is not reliable.
1130       Furthermore, pluto itself ignores Notifications.
1131
1132   XAUTH
1133       If pluto needs additional authentication, such as defined by the XAUTH
1134       specifications, then it may ask whack to prompt the operator for
1135       username or passwords. Typically, these will be entered interactively.
1136       A GUI that wraps around whack may look for the 041 (username) or 040
1137       (password) prompts, and display them to the user.
1138
1139       For testing purposes, the options --xauthuser user --xauthpass pass may
1140       be be given prior to the --initiate  to provide responses to the
1141       username and password prompts.
1142
1143   The updown command
1144       Whenever pluto brings a connection up or down, it invokes the updown
1145       command. This command is specified using the --updown option. This
1146       allows for customized control over routing and firewall manipulation.
1147
1148       The updown is invoked for five different operations. Each of these
1149       operations can be for our client subnet or for our host itself.
1150
1151       prepare-host or prepare-client
1152           is run before bringing up a new connection if no other connection
1153           with the same clients is up. Generally, this is useful for deleting
1154           a route that might have been set up before pluto was run or perhaps
1155           by some agent not known to pluto.
1156
1157       route-host or route-client
1158           is run when bringing up a connection for a new peer client subnet
1159           (even if prepare-host or prepare-client was run). The command
1160           should install a suitable route. Routing decisions are based only
1161           on the destination (peer's client) subnet address, unlike eroutes
1162           which discriminate based on source too.
1163
1164       unroute-host or unroute-client
1165           is run when bringing down the last connection for a particular peer
1166           client subnet. It should undo what the route-host or route-client
1167           did.
1168
1169       up-host or up-client
1170           is run when bringing up a tunnel eroute with a pair of client
1171           subnets that does not already have a tunnel eroute. This command
1172           should install firewall rules as appropriate. It is generally a
1173           good idea to allow IKE messages (UDP port 500) travel between the
1174           hosts.
1175
1176       down-host or down-client
1177           is run when bringing down the eroute for a pair of client subnets.
1178           This command should delete firewall rules as appropriate. Note that
1179           there may remain some inbound IPsec SAs with these client subnets.
1180
1181       The script is passed a large number of environment variables to specify
1182       what needs to be done.
1183
1184       PLUTO_VERSION
1185           indicates what version of this interface is being used. This
1186           document describes version 1.1. This is upwardly compatible with
1187           version 1.0.
1188
1189       PLUTO_VERB
1190           specifies the name of the operation to be performed (prepare-host,r
1191           prepare-client, up-host, up-client, down-host, or down-client). If
1192           the address family for security gateway to security gateway
1193           communications is IPv6, then a suffix of -v6 is added to the verb.
1194
1195       PLUTO_CONNECTION
1196           is the name of the connection for which we are routing.
1197
1198       PLUTO_NEXT_HOP
1199           is the next hop to which packets bound for the peer must be sent.
1200
1201       PLUTO_INTERFACE
1202           is the name of the ipsec interface to be used.
1203
1204       PLUTO_ME
1205           is the IP address of our host.
1206
1207       PLUTO_MY_CLIENT
1208           is the IP address / count of our client subnet. If the client is
1209           just the host, this will be the host's own IP address / max (where
1210           max is 32 for IPv4 and 128 for IPv6).
1211
1212       PLUTO_MY_CLIENT_NET
1213           is the IP address of our client net. If the client is just the
1214           host, this will be the host's own IP address.
1215
1216       PLUTO_MY_CLIENT_MASK
1217           is the mask for our client net. If the client is just the host,
1218           this will be 255.255.255.255.
1219
1220       PLUTO_PEER
1221           is the IP address of our peer.
1222
1223       PLUTO_PEER_CLIENT
1224           is the IP address / count of the peer's client subnet. If the
1225           client is just the peer, this will be the peer's own IP address /
1226           max (where max is 32 for IPv4 and 128 for IPv6).
1227
1228       PLUTO_PEER_CLIENT_NET
1229           is the IP address of the peer's client net. If the client is just
1230           the peer, this will be the peer's own IP address.
1231
1232       PLUTO_PEER_CLIENT_MASK
1233           is the mask for the peer's client net. If the client is just the
1234           peer, this will be 255.255.255.255.
1235
1236       PLUTO_MY_PROTOCOL
1237           lists the protocols allowed over this IPsec SA.
1238
1239       PLUTO_PEER_PROTOCOL
1240           lists the protocols the peer allows over this IPsec SA.
1241
1242       PLUTO_MY_PORT
1243           lists the ports allowed over this IPsec SA.
1244
1245       PLUTO_PEER_PORT
1246           lists the ports the peer allows over this IPsec SA.
1247
1248       PLUTO_MY_ID
1249           lists our id.
1250
1251       PLUTO_PEER_ID
1252           Dlists our peer's id.
1253
1254       PLUTO_PEER_CA
1255           lists the peer's CA.
1256
1257       All output sent by the script to stderr or stdout is logged. The script
1258       should return an exit status of 0 if and only if it succeeds.
1259
1260       Pluto waits for the script to finish and will not do any other
1261       processing while it is waiting. The script may assume that pluto will
1262       not change anything while the script runs. The script should avoid
1263       doing anything that takes much time and it should not issue any command
1264       that requires processing by pluto. Either of these activities could be
1265       performed by a background subprocess of the script.
1266
1267   Rekeying
1268       When an SA that was initiated by pluto has only a bit of lifetime left,
1269       pluto will initiate the creation of a new SA. This applies to ISAKMP
1270       and IPsec SAs. The rekeying will be initiated when the SA's remaining
1271       lifetime is less than the rekeymargin plus a random percentage, between
1272       0 and rekeyfuzz, of the rekeymargin.
1273
1274       Similarly, when an SA that was initiated by the peer has only a bit of
1275       lifetime left, pluto will try to initiate the creation of a
1276       replacement. To give preference to the initiator, this rekeying will
1277       only be initiated when the SA's remaining lifetime is half of
1278       rekeymargin. If rekeying is done by the responder, the roles will be
1279       reversed: the responder for the old SA will be the initiator for the
1280       replacement. The former initiator might also initiate rekeying, so
1281       there may be redundant SAs created. To avoid these complications, make
1282       sure that rekeymargin is generous.
1283
1284       One risk of having the former responder initiate is that perhaps none
1285       of its proposals is acceptable to the former initiator (they have not
1286       been used in a successful negotiation). To reduce the chances of this
1287       happening, and to prevent loss of security, the policy settings are
1288       taken from the old SA (this is the case even if the former initiator is
1289       initiating). These may be stricter than those of the connection.
1290
1291       pluto will not rekey an SA if that SA is not the most recent of its
1292       type (IPsec or ISAKMP) for its potential connection. This avoids
1293       creating redundant SAs.
1294
1295       The random component in the rekeying time (rekeyfuzz) is intended to
1296       make certain pathological patterns of rekeying unstable. If both sides
1297       decide to rekey at the same time, twice as many SAs as necessary are
1298       created. This could become a stable pattern without the randomness.
1299
1300       Another more important case occurs when a security gateway has SAs with
1301       many other security gateways. Each of these connections might need to
1302       be rekeyed at the same time. This would cause a high peek requirement
1303       for resources (network bandwidth, CPU time, entropy for random
1304       numbers). The rekeyfuzz can be used to stagger the rekeying times.
1305
1306       Once a new set of SAs has been negotiated, pluto will never send
1307       traffic on a superseded one. Traffic will be accepted on an old SA
1308       until it expires.
1309
1310   Selecting a Connection When Responding: Road Warrior Support
1311       When pluto receives an initial Main Mode message, it needs to decide
1312       which connection this message is for. It picks based solely on the
1313       source and destination IP addresses of the message. There might be
1314       several connections with suitable IP addresses, in which case one of
1315       them is arbitrarily chosen. (The ISAKMP SA proposal contained in the
1316       message could be taken into account, but it is not.)
1317
1318       The ISAKMP SA is negotiated before the parties pass further identifying
1319       information, so all ISAKMP SA characteristics specified in the
1320       connection description should be the same for every connection with the
1321       same two host IP addresses. At the moment, the only characteristic that
1322       might differ is authentication method.
1323
1324       Up to this point, all configuring has presumed that the IP addresses
1325       are known to all parties ahead of time. This will not work when either
1326       end is mobile (or assigned a dynamic IP address for other reasons). We
1327       call this situation "Road Warrior". It is fairly tricky and has some
1328       important limitations, most of which are features of the IKE protocol.
1329
1330       Only the initiator may be mobile: the initiator may have an IP number
1331       unknown to the responder. When the responder doesn't recognize the IP
1332       address on the first Main Mode packet, it looks for a connection with
1333       itself as one end and %any as the other. If it cannot find one, it
1334       refuses to negotiate. If it does find one, it creates a temporary
1335       connection that is a duplicate except with the %any replaced by the
1336       source IP address from the packet; if there was no identity specified
1337       for the peer, the new IP address will be used.
1338
1339       When pluto is using one of these temporary connections and needs to
1340       find the preshared secret or RSA private key in ipsec.secrets, and the
1341       connection specified no identity for the peer, %any is used as its
1342       identity. After all, the real IP address was apparently unknown to the
1343       configuration, so it is unreasonable to require that it be used in this
1344       table.
1345
1346       Part way into the Phase 1 (Main Mode) negotiation using one of these
1347       temporary connection descriptions, pluto will receive an Identity
1348       Payload. At this point, pluto checks for a more appropriate connection,
1349       one with an identity for the peer that matches the payload and would
1350       use the same keys as so far used for authentication. If it finds one,
1351       it will switch to using this better connection (or a temporary one
1352       derived from this, if it has %any for the peer's IP address). It may
1353       even turn out that no connection matches the newly discovered identity,
1354       including the current connection; if so, pluto terminates negotiation.
1355
1356       Unfortunately, if preshared secret authentication is being used, the
1357       Identity Payload is encrypted using this secret, so the secret must be
1358       selected by the responder without knowing this payload. This limits
1359       there to being at most one preshared secret for all Road Warrior
1360       systems connecting to a host. RSA Signature authentication does not
1361       require that the responder knows how to select the initiator's public
1362       key until after the initiator's Identity Payload is decoded (using the
1363       responder's private key, so that must be preselected).
1364
1365       When pluto is responding to a Quick Mode negotiation via one of these
1366       temporary connection descriptions, it may well find that the subnets
1367       specified by the initiator don't match those in the temporary
1368       connection description. If so, it will look for a connection with
1369       matching subnets, its own host address, a peer address of %any and
1370       matching identities. If it finds one, a new temporary connection is
1371       derived from this one and used for the Quick Mode negotiation of IPsec
1372       SAs. If it does not find one, pluto terminates negotiation.
1373
1374       Be sure to specify an appropriate nexthop for the responder to send a
1375       message to the initiator: pluto has no way of guessing it (if
1376       forwarding isn't required, use an explicit %direct as the nexthop and
1377       the IP address of the initiator will be filled in; the obsolete
1378       notation 0.0.0.0 is still accepted).
1379
1380       pluto has no special provision for the initiator side. The current
1381       (possibly dynamic) IP address and nexthop must be used in defining
1382       connections. These must be properly configured each time the
1383       initiator's IP address changes.  pluto has no mechanism to do this
1384       automatically.
1385
1386       Although we call this Road Warrior Support, it could also be used to
1387       support encrypted connections with anonymous initiators. The
1388       responder's organization could announce the preshared secret that would
1389       be used with unrecognized initiators and let anyone connect. Of course
1390       the initiator's identity would not be authenticated.
1391
1392       If any Road Warrior connections are supported, pluto cannot reject an
1393       exchange initiated by an unknown host until it has determined that the
1394       secret is not shared or the signature is invalid. This must await the
1395       third Main Mode message from the initiator. If no Road Warrior
1396       connection is supported, the first message from an unknown source would
1397       be rejected. This has implications for ease of debugging configurations
1398       and for denial of service attacks.
1399
1400       Although a Road Warrior connection must be initiated by the mobile
1401       side, the other side can and will rekey using the temporary connection
1402       it has created. If the Road Warrior wishes to be able to disconnect, it
1403       is probably wise to set --keyingtries to 1 in the connection on the
1404       non-mobile side to prevent it trying to rekey the connection.
1405       Unfortunately, there is no mechanism to unroute the connection
1406       automatically.
1407
1408   Debugging
1409       pluto accepts several optional arguments, useful mostly for debugging.
1410       Except for --interface, each should appear at most once.
1411
1412       --interface interfacename
1413           specifies that the named real public network interface should be
1414           considered. The interface name specified should not be ipsecN. If
1415           the option doesn't appear, all interfaces are considered. To
1416           specify several interfaces, use the option once for each. One use
1417           of this option is to specify which interface should be used when
1418           two or more share the same IP address.
1419
1420       --ikeport port-number
1421           changes the UDP port that pluto will use (default, specified by
1422           IANA: 500)
1423
1424       --ctlbase path
1425           basename for control files.  path.ctl is the socket through which
1426           whack communicates with pluto.  path.pid is the lockfile to prevent
1427           multiple pluto instances. The default is /var/run/pluto/pluto).
1428
1429       --secretsfile file
1430           specifies the file for authentication secrets (default:
1431           /etc/ipsec.secrets). This name is subject to "globbing" as in
1432           sh(1), so every file with a matching name is processed. Quoting is
1433           generally needed to prevent the shell from doing the globbing.
1434
1435       --nofork
1436           disable "daemon fork" (default is to fork). In addition, after the
1437           lock file and control socket are created, print the line "Pluto
1438           initialized" to standard out.
1439
1440       --uniqueids
1441           if this option has been selected, whenever a new ISAKMP SA is
1442           established, any connection with the same Peer ID but a different
1443           Peer IP address is unoriented (causing all its SAs to be deleted).
1444           This helps clean up dangling SAs when a connection is lost and then
1445           regained at another IP address.
1446
1447       --force-busy
1448           if this option has been selected, pluto will be forced to be
1449           "busy". In this state, which happens when there is a Denial of
1450           Service attack, will force pluto to use cookies before accepting
1451           new incoming IKE packets. Cookies are send and required in ikev1
1452           Aggressive Mode and in ikev2. This option is mostly used for
1453           testing purposes, but can be selected by paranoid administrators as
1454           well.
1455
1456       --stderrlog
1457           log goes to standard out {default is to use syslogd(8))
1458
1459       pluto is willing to produce a prodigious amount of debugging
1460       information. There are several classes of debugging output, and pluto
1461       may be directed to produce a selection of them. All lines of debugging
1462       output are prefixed with "| " to distinguish them from normal
1463       diagnostic messages.
1464
1465       When pluto is invoked, it may be given arguments to specify which debug
1466       classes to output. The current options are:
1467
1468       --debug help (whack only)
1469           list the debugging classes recognised by pluto
1470
1471       --debug none
1472           disable logging for all debugging classes
1473
1474       --debug base
1475           enable debug-logging
1476
1477       --debug cpu-usage
1478           enable cpu-usage logging
1479
1480       --debug class, --no-debug class, --debug no-class
1481           enable (disable) logging of the specified debugging class (--debug
1482           help lists debugging classes supported by this version of pluto)
1483
1484       The debug form of the whack command will change the selection in a
1485       running pluto. If a connection name is specified, the flags are added
1486       whenever pluto has identified that it is dealing with that connection.
1487       Unfortunately, this is often part way into the operation being
1488       observed.
1489
1490       For example, to start pluto with both base and cpu-usage debug-logging
1491       enabled:
1492
1493                pluto --debug base --debug cpu-usage
1494
1495
1496       To later change this pluto to disable base debug-logging use either:
1497
1498                whack --no-debug base
1499
1500
1501       or:
1502
1503                whack --debug none --debug cpu-usage
1504
1505
1506   Impairing
1507       pluto and whack accept several optional arguments that alter (impair)
1508       correct behaviour.
1509
1510       These options are solely intended for use by developers when testing
1511       pluto.
1512
1513       --impair help (whack only)
1514           list all the behaviours that can be altered (impaired)
1515
1516       --impair list (whack only)
1517           list all the behaviours that are currently altered (impaired)
1518
1519       --impair none
1520           disable all altered (impaired) behaviours
1521
1522       --impair behaviour, --impair behaviour:how, --no-impair behaviour
1523           alter (impair) pluto inducing the (possibly erroneous) behaviour
1524
1525   Pluto's Behaviour When Things Go Wrong
1526       When pluto doesn't understand or accept a message, it just ignores the
1527       message. It is not yet capable of communicating the problem to the
1528       other IKE daemon (in the future it might use Notifications to
1529       accomplish this in many cases). It does log a diagnostic.
1530
1531       When pluto gets no response from a message, it resends the same message
1532       (a message will be sent at most three times). This is appropriate: UDP
1533       is unreliable.
1534
1535       When pluto gets a message that it has already seen, there are many
1536       cases when it notices and discards it. This too is appropriate for UDP.
1537
1538       Combine these three rules, and you can explain many apparently
1539       mysterious behaviours. In a pluto log, retrying isn't usually the
1540       interesting event. The critical thing is either earlier (pluto got a
1541       message that it didn't like and so ignored, so it was still awaiting an
1542       acceptable message and got impatient) or on the other system (pluto
1543       didn't send a reply because it wasn't happy with the previous message).
1544
1545   Notes
1546       Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the
1547       SA. The IKE protocol lets the destination of the SA choose the SPI. The
1548       range 0 to 0xFF is reserved for IANA.  Pluto also avoids choosing an
1549       SPI in the range 0x100 to 0xFFF, leaving these SPIs free for manual
1550       keying. Remember that the peer, if not pluto, may well chose SPIs in
1551       this range.
1552
1553   Policies
1554       This catalogue of policies may be of use when trying to configure Pluto
1555       and another IKE implementation to interoperate.
1556
1557       In Phase 1, only Main Mode is supported. We are not sure that
1558       Aggressive Mode is secure. For one thing, it does not support identity
1559       protection. It may allow more severe Denial Of Service attacks.
1560
1561       No Informational Exchanges are supported. These are optional and since
1562       their delivery is not assured, they must not matter. It is the case
1563       that some IKE implementations won't interoperate without Informational
1564       Exchanges, but we feel they are broken.
1565
1566       No Informational Payloads are supported. These are optional, but
1567       useful. It is of concern that these payloads are not authenticated in
1568       Phase 1, nor in those Phase 2 messages authenticated with HASH(3).
1569
1570       ·
1571           Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) are
1572           supported. Group MODP768 (1) is not supported because it is too
1573           weak.
1574
1575       ·
1576           Host authentication can be done by RSA Signatures or Pre-Shared
1577           Secrets.
1578
1579       ·
1580           3DES CBC (Cypher Block Chaining mode) is the only encryption
1581           supported, both for ISAKMP SAs and IPSEC SAs.
1582
1583       ·
1584           MD5 and SHA1 hashing are supported for packet authentication in
1585           both kinds of SAs.
1586
1587       ·
1588           The ESP, AH, or AH plus ESP are supported. If, and only if, AH and
1589           ESP are combined, the ESP need not have its own authentication
1590           component. The selection is controlled by the --encrypt and
1591           --authenticate flags.
1592
1593       ·
1594           Each of these may be combined with IPCOMP Deflate compression, but
1595           only if the potential connection specifies compression.
1596
1597       ·
1598           The IPSEC SAs may be tunnel or transport mode, where appropriate.
1599           The --tunnel flag controls this when pluto is initiating.
1600
1601       ·
1602           When responding to an ISAKMP SA proposal, the maximum acceptable
1603           lifetime is eight hours. The default is one hour. There is no
1604           minimum. The --ikelifetime flag controls this when pluto is
1605           initiating.
1606
1607       ·
1608           When responding to an IPSEC SA proposal, the maximum acceptable
1609           lifetime is one day. The default is eight hours. There is no
1610           minimum. The --ipseclifetime flag controls this when pluto is
1611           initiating.
1612
1613       ·
1614           PFS is acceptable, and will be proposed if the --pfs flag was
1615           specified. The DH group proposed will be the same as negotiated for
1616           Phase 1.
1617

SIGNALS

1619       Pluto responds to SIGHUP by issuing a suggestion that ``whack
1620       --listen'' might have been intended.
1621
1622       Pluto exits when it receives SIGTERM.
1623

EXIT STATUS

1625       pluto normally forks a daemon process, so the exit status is normally a
1626       very preliminary result.
1627
1628       0
1629           means that all is OK so far.
1630
1631       1
1632           means that something was wrong.
1633
1634       10
1635           means that the lock file already exists.
1636
1637       If whack detects a problem, it will return an exit status of 1. If it
1638       received progress messages from pluto, it returns as status the value
1639       of the numeric prefix from the last such message that was not a message
1640       sent to syslog or a comment (but the prefix for success is treated as
1641       0). Otherwise, the exit status is 0.
1642

FILES

1644       /var/run/pluto/pluto.pid
1645
1646       /var/run/pluto/pluto.ctl
1647
1648       /etc/ipsec.secrets
1649
1650       /dev/urandom
1651

ENVIRONMENT

1653       pluto does not use any environment variables
1654

SEE ALSO

1656       The rest of the Libreswan distribution, in particular ipsec(8).
1657
1658       ipsec_auto(8) is designed to make using pluto more pleasant. Use it!
1659
1660       ipsec.secrets(5) describes the format of the secrets file.
1661
1662       ipsec_atoaddr(3), part of the Libreswan distribution, describes the
1663       forms that IP addresses may take.  ipsec_atosubnet(3), part of the
1664       Libreswan distribution, describes the forms that subnet specifications.
1665
1666       For more information on IPsec, the mailing list, and the relevant
1667       documents, see:
1668
1669       https://datatracker.ietf.org/wg/ipsecme/charter/
1670
1671       At the time of writing, the latest IETF IKE RFC is:
1672
1673       RFC 7296 Internet Key Exchange Protocol Version 2 (IKEv2)
1674
1675       The Libreswan web site <https://libreswan.org> and the mailing lists
1676       described there.
1677
1678       The Libreswan wiki <https://libreswan.org/wiki> and the mailing lists
1679       described there.
1680
1681       The Libreswan list of implemented RFCs
1682       <https://libreswan.org/wiki/Implemented_Standards>
1683

HISTORY

1685       This code is released under the GPL terms. See the accompanying files
1686       CHANGES COPYING and CREDITS.* for more details.
1687
1688       Detailed history (including FreeS/WAN and Openswan) can be found in the
1689       docs/ directory.
1690

BUGS

1692       Please see <https://bugs.libreswan.org> for a list of currently known
1693       bugs and missing features.
1694
1695       Bugs should be reported to the <swan-dev@lists.libreswan.org> mailing
1696       list.
1697

AUTHOR

1699       Paul Wouters
1700           placeholder to suppress warning
1701
1702
1703
1704libreswan                         02/21/2021                    IPSEC_PLUTO(8)
Impressum