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