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