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