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 [--debug all] [--debug none] [--debug list] [--debug class]
26             [--debug no-class] [--debug-all (obsolete)]
27             [--debug-none (obsolete)] [--impair list] [--impair none]
28             [--impair behaviour] [--impair no-behaviour]
29
30       ipsec whack --name connection-name [[--ipv4] | [--ipv6]]
31             [[--tunnelipv4] | [--tunnelipv6]]
32             [--id identity] [--host ip-address] [--cert friendly_name]
33             [--ckaid CKAID] [--ca distinguished name]
34             [--groups access control groups]
35             [--sendcert yes | forced | always | ifasked | no | never]
36             [--sendca none | issuer | all] [--certtype number]
37             [--ikeport portnumber] [--nexthop ip-address] [[--client subnet]
38             | [--clientwithin subnet]] [--clientprotoport protocol/port]
39             [--srcip ip-address] [--xauthserver] [--xauthclient]
40             [--modecfgserver] [--modecfgclient]
41             [--modecfgdns ip-address, ip-address, ...]
42             [--modecfgdomains DNS-domain, DNS-domain, ...]
43             [--modecfgbanner login-banner] [--dnskeyondemand]
44             [--updown updown]
45             --to
46             [--id identity] [--host ip-address] [--cert friendly_name]
47             [--ckaid CKAID] [--ca distinguished name]
48             [--groups access control groups]
49             [--sendcert yes | always | ifasked | no | never]
50             [--certtype number] [--ikeport port-number]
51             [--nexthop ip-address] [--client subnet] [--clientwithin subnet]
52             [--clientprotoport protocol/port] [--srcip ip-address]
53             [--xauthserver] [--xauthclient] [--modecfgserver]
54             [--modecfgclient] [--modecfgdns ip-address, ip-address, ...]
55             [--modecfgdomains DNS-domain, DNS-domain, ...] [--dnskeyondemand]
56             [--updown updown]
57
58             [--tunnel] [--psk] [--rsasig] [--encrypt] [--authenticate]
59             [--compress] [--pfs]
60             [--pfsgroup [modp1024] | [modp1536] | [modp2048] | [modp3072] | [modp4096] | [modp6144] | [modp8192] | [dh22] | [dh23] | [dh24]]
61             [--disablearrivalcheck] [--ikelifetime seconds]
62             [--ipseclifetime seconds] [--rekeymargin seconds]
63             [--rekeyfuzz percentage] [--keyingtries count] [--esp esp-algos]
64             [--dontrekey] [--aggrmode] [--modecfgpull] [--metric metric]
65             [--nflog-group nflognum] [--conn-mark mark/mask]
66             [[--dpddelay seconds] | [--dpdtimeout seconds]]
67             [--dpdaction [clear] | [hold] | [restart]] [--forceencaps]
68             [--no-keep-alive]
69             [[--initiateontraffic] | [--pass] | [--drop] | [--reject]]
70             [[--failnone] | [--failpass] | [--faildrop] | [--failreject]]
71             [--rundir path] [--ctlsocket path/file] [--label string]
72
73       ipsec whack --keyid id [--addkey] [--pubkeyrsa key] [--rundir path]
74             [--ctlsocket path/file] [--label string]
75
76       ipsec whack --listen | --unlisten  [--rundir path]
77             [--ctlsocket path/file] [--label string]
78
79       ipsec whack --busy | --relax  [--rundir path] [--ctlsocket path/file]
80
81       ipsec whack --route | --unroute  --name connection-name [--rundir path]
82             [--ctlsocket path/file] [--label string]
83
84       ipsec whack --initiate | [--remote-host ip-address] | --terminate
85             --name connection-name [--xauthuser user] [--xauthpass pass]
86             [--asynchronous] [--rundir path] [--ctlsocket path/file]
87             [--label string]
88
89       ipsec whack [[--tunnelipv4] | [--tunnelipv6]] --oppohere ip-address
90             --oppothere ip-address
91
92       ipsec whack --crash [ipaddress]
93
94       ipsec whack --whackrecord [filename]
95
96       ipsec whack --whackstoprecord
97
98       ipsec whack --name connection-name --delete [--ctlbase path]
99             [--label string]
100
101       ipsec whack --deletestate state-number [--rundir path]
102             [--ctlsocket path/file] [--label string]
103
104       ipsec whack --deleteuser --name username [--rundir path]
105             [--ctlsocket path/file] [--label string]
106
107       ipsec whack [--name connection-name] [--debug all] [--debug none]
108             [--debug list] [--debug class] [--debug no-class]
109             [--debug-all (obsolete)] [--debug-none (obsolete)]
110             [--impair list] [--impair none] [--impair behaviour]
111             [--impair no-behaviour]
112
113       ipsec whack [--utc] [--listall] [--listpubkeys] [--listcerts]
114             [--listcacerts] [--listcrls]
115
116       ipsec whack [--utc] [--rereadsecrets] [--fetchcrls] [--rereadall]
117
118       ipsec whack --listevents
119
120       ipsec whack --purgeocsp
121
122       ipsec whack --status [--rundir path] [--ctlsocket path/file]
123             [--label string]
124
125       ipsec whack --trafficstatus --shuntstatus [--rundir path]
126             [--ctlsocket path/file] [--label string]
127
128       ipsec whack [--ike-socket-bufsize bufsize]
129             [--ike-socket-errqueue-toggle] [--rundir path]
130             [--ctlsocket path/file] [--label string]
131
132       ipsec whack --shutdown [--rundir path] [--ctlsocket path/file]
133             [--label string]
134

DESCRIPTION

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

SIGNALS

1669       Pluto responds to SIGHUP by issuing a suggestion that ``whack
1670       --listen'' might have been intended.
1671
1672       Pluto exits when it receives SIGTERM.
1673

EXIT STATUS

1675       pluto normally forks a daemon process, so the exit status is normally a
1676       very preliminary result.
1677
1678       0
1679           means that all is OK so far.
1680
1681       1
1682           means that something was wrong.
1683
1684       10
1685           means that the lock file already exists.
1686
1687       If whack detects a problem, it will return an exit status of 1. If it
1688       received progress messages from pluto, it returns as status the value
1689       of the numeric prefix from the last such message that was not a message
1690       sent to syslog or a comment (but the prefix for success is treated as
1691       0). Otherwise, the exit status is 0.
1692

FILES

1694       /var/run/pluto/pluto.pid
1695
1696       /var/run/pluto/pluto.ctl
1697
1698       /etc/ipsec.secrets
1699
1700       /dev/urandom
1701

ENVIRONMENT

1703       pluto does not use any environment variables
1704

SEE ALSO

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

HISTORY

1735       This code is released under the GPL terms. See the accompanying files
1736       CHANGES COPYING and CREDITS.* for more details.
1737
1738       Detailed history (including FreeS/WAN and Openswan) can be found in the
1739       docs/ directory.
1740

BUGS

1742       Please see <https://bugs.libreswan.org> for a list of currently known
1743       bugs and missing features.
1744
1745       Bugs should be reported to the <swan-dev@lists.libreswan.org> mailing
1746       list.
1747

AUTHOR

1749       Paul Wouters
1750           placeholder to suppress warning
1751
1752
1753
1754libreswan                         05/14/2019                    IPSEC_PLUTO(8)
Impressum