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] [--config filename]
11             [--vendorid VID] [--nofork] [--stderrlog]
12             [----plutostderrlogtime] [--logfile filename] [--use-klips]
13             [--use-mast] [--use-netkey] [--use-nostack] [--uniqueids]
14             [--virtual-private network_list] [--keep-alive delay_sec]
15             [--force-busy] [--strictcrlpolicy] [--crlcheckinterval]
16             [--interface interfacename] [--listen ipaddr]
17             [--ikeport portnumber] [--natikeport portnumber] [--rundir path]
18             [--secretsfile secrets-file] [--nhelpers number]
19             [--seedbits numbits] [--perpeerlog] [--perpeerlogbase dirname]
20             [--ipsecdir dirname] [--nssdir dirname] [--coredir dirname]
21             [--statsbin filename] [--secctx-attr-type number]
22
23       ipsec whack [--help] [--version]
24
25       ipsec whack --name connection-name [[--ipv4] | [--ipv6]]
26             [[--tunnelipv4] | [--tunnelipv6]]
27             [--id identity] [--host ip-address] [--cert friendly_name]
28             [--ckaid CKAID] [--ca distinguished name]
29             [--groups access control groups]
30             [--sendcert yes | forced | always | ifasked | no | never]
31             [--sendca none | issuer | all] [--certtype number]
32             [--ikeport portnumber] [--nexthop ip-address] [[--client subnet]
33             | [--clientwithin subnet]] [--clientprotoport protocol/port]
34             [--srcip ip-address] [--xauthserver] [--xauthclient]
35             [--modecfgserver] [--modecfgclient]
36             [--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] [--clientwithin 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             [--disablearrivalcheck] [--ikelifetime seconds]
57             [--ipseclifetime seconds] [--rekeymargin seconds]
58             [--rekeyfuzz percentage] [--keyingtries count] [--esp esp-algos]
59             [--dontrekey] [--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 --busy | --relax  [--rundir path] [--ctlsocket path/file]
75
76       ipsec whack --route | --unroute  --name connection-name [--rundir path]
77             [--ctlsocket path/file] [--label string]
78
79       ipsec whack --initiate | [--remote-host ip-address] | --terminate
80             --name connection-name [--xauthuser user] [--xauthpass pass]
81             [--asynchronous] [--rundir path] [--ctlsocket path/file]
82             [--label string]
83
84       ipsec whack [[--tunnelipv4] | [--tunnelipv6]] --oppohere ip-address
85             --oppothere ip-address
86
87       ipsec whack --crash [ipaddress]
88
89       ipsec whack --whackrecord [filename]
90
91       ipsec whack --whackstoprecord
92
93       ipsec whack --name connection-name --delete [--ctlbase path]
94             [--label string]
95
96       ipsec whack --deletestate state-number [--rundir path]
97             [--ctlsocket path/file] [--label string]
98
99       ipsec whack --deleteuser --name username [--rundir path]
100             [--ctlsocket path/file] [--label string]
101
102       ipsec whack [--name connection-name]
103             {--debug help | none | base | cpu-usage | class} |
104             {--no-debug class} | {--impair help | none | behaviour} |
105             {--no-impair behaviour}
106
107       ipsec whack [--utc] [--listall] [--listpubkeys] [--listcerts]
108             [--listcacerts] [--listcrls]
109
110       ipsec whack [--utc] [--rereadsecrets] [--fetchcrls] [--rereadall]
111
112       ipsec whack --listevents
113
114       ipsec whack --purgeocsp
115
116       ipsec whack --status [--rundir path] [--ctlsocket path/file]
117             [--label string]
118
119       ipsec whack --trafficstatus --shuntstatus [--rundir path]
120             [--ctlsocket path/file] [--label string]
121
122       ipsec whack [--ike-socket-bufsize bufsize]
123             [--ike-socket-errqueue-toggle] [--rundir path]
124             [--ctlsocket path/file] [--label string]
125
126       ipsec whack --shutdown [--rundir path] [--ctlsocket path/file]
127             [--label string]
128

DESCRIPTION

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

SIGNALS

1659       Pluto responds to SIGHUP by issuing a suggestion that ``whack
1660       --listen'' might have been intended.
1661
1662       Pluto exits when it receives SIGTERM.
1663

EXIT STATUS

1665       pluto normally forks a daemon process, so the exit status is normally a
1666       very preliminary result.
1667
1668       0
1669           means that all is OK so far.
1670
1671       1
1672           means that something was wrong.
1673
1674       10
1675           means that the lock file already exists.
1676
1677       If whack detects a problem, it will return an exit status of 1. If it
1678       received progress messages from pluto, it returns as status the value
1679       of the numeric prefix from the last such message that was not a message
1680       sent to syslog or a comment (but the prefix for success is treated as
1681       0). Otherwise, the exit status is 0.
1682

FILES

1684       /var/run/pluto/pluto.pid
1685
1686       /var/run/pluto/pluto.ctl
1687
1688       /etc/ipsec.secrets
1689
1690       /dev/urandom
1691

ENVIRONMENT

1693       pluto does not use any environment variables
1694

SEE ALSO

1696       The rest of the Libreswan distribution, in particular ipsec(8).
1697
1698       ipsec_auto(8) is designed to make using pluto more pleasant. Use it!
1699
1700       ipsec.secrets(5) describes the format of the secrets file.
1701
1702       ipsec_atoaddr(3), part of the Libreswan distribution, describes the
1703       forms that IP addresses may take.  ipsec_atosubnet(3), part of the
1704       Libreswan distribution, describes the forms that subnet specifications.
1705
1706       For more information on IPsec, the mailing list, and the relevant
1707       documents, see:
1708
1709       https://datatracker.ietf.org/wg/ipsecme/charter/
1710
1711       At the time of writing, the latest IETF IKE RFC is:
1712
1713       RFC 7296 Internet Key Exchange Protocol Version 2 (IKEv2)
1714
1715       The Libreswan web site <https://libreswan.org> and the mailing lists
1716       described there.
1717
1718       The Libreswan wiki <https://libreswan.org/wiki> and the mailing lists
1719       described there.
1720
1721       The Libreswan list of implemented RFCs
1722       <https://libreswan.org/wiki/Implemented_Standards>
1723

HISTORY

1725       This code is released under the GPL terms. See the accompanying files
1726       CHANGES COPYING and CREDITS.* for more details.
1727
1728       Detailed history (including FreeS/WAN and Openswan) can be found in the
1729       docs/ directory.
1730

BUGS

1732       Please see <https://bugs.libreswan.org> for a list of currently known
1733       bugs and missing features.
1734
1735       Bugs should be reported to the <swan-dev@lists.libreswan.org> mailing
1736       list.
1737

AUTHOR

1739       Paul Wouters
1740           placeholder to suppress warning
1741
1742
1743
1744libreswan                         06/10/2019                    IPSEC_PLUTO(8)
Impressum