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