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