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] [--ctlbase path]
19 [--secretsfile secrets-file] [--adns pathname]
20 [--nhelpers number] [--seedbits numbits] [--perpeerlog]
21 [--perpeerlogbase dirname] [--ipsecdir dirname]
22 [--coredir dirname] [--statsbin filename]
23 [--secctx-attr-type number]
24 ipsec whack [--help] [--version]
26 ipsec whack [--debug-none] [--debug-all] [--debug-raw] [--debug-crypt]
28 [--debug-parsing] [--debug-emitting] [--debug-control]
29 [--debug-lifecycle] [--debug-kernel] [--debug-pfkey]
30 [--debug-nat-t] [--debug-dpd] [--debug-dns] [--debug-oppo]
31 [--debug-oppoinfo] [--debug-whackwatch] [--debug-private]
32 [--debug-x509]
33 ipsec whack --name connection-name [[--ipv4] | [--ipv6]]
35 [[--tunnelipv4] | [--tunnelipv6]]
36 [--id identity] [--host ip-address] [--cert path]
37 [--ca distinguished name] [--groups access control groups]
38 [--sendcert yes | forced | always | ifasked | no | never]
39 [--sendca none | issuer | all] [--certtype number]
40 [--ikeport portnumber] [--nexthop ip-address] [[--client subnet]
41 | [--clientwithin subnet]] [--clientprotoport protocol/port]
42 [--srcip ip-address] [--xauthserver] [--xauthclient]
43 [--modecfgserver] [--modecfgclient] [--modecfgdns1 ip-address]
44 [--modecfgdns2 ip-address] [--modecfgdomain DNS-domain]
45 [--modecfgbanner login-banner] [--dnskeyondemand]
46 [--updown updown]
47 --to
48 [--id identity] [--host ip-address] [--cert path]
49 [--ca distinguished name] [--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] [--modecfgdns1 ip-address]
56 [--modecfgdns2 ip-address] [--modecfgdomain DNS-domain]
57 [--dnskeyondemand] [--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] [[--dpddelay seconds] |
67 [--dpdtimeout seconds]]
68 [--dpdaction [clear] | [hold] | [restart]] [--forceencaps]
69 [--no-keep-alive]
70 [[--initiateontraffic] | [--pass] | [--drop] | [--reject]]
71 [[--failnone] | [--failpass] | [--faildrop] | [--failreject]]
72 [--ctlbase path] [--label string]
73 ipsec whack --keyid id [--addkey] [--pubkeyrsa key] [--ctlbase path]
75 [--label string]
76 ipsec whack --myid id
78 ipsec whack --listen | --unlisten [--ctlbase path] [--label string]
80 ipsec whack --busy | --relax [--ctlbase path]
82 ipsec whack --route | --unroute --name connection-name
84 [--ctlbase path] [--label string]
85 ipsec whack --initiate | --terminate --name connection-name
87 [--xauthuser user] [--xauthpass pass] [--asynchronous]
88 [--ctlbase path] [--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 [--ctlbase path]
103 [--label string]
104 ipsec whack --deleteuser --name username [--ctlbase path]
106 [--label string]
107 ipsec whack [--name connection-name] [--debug-none] [--debug-all]
109 [--debug-raw] [--debug-crypt] [--debug-parsing]
110 [--debug-emitting] [--debug-control] [--debug-controlmore]
111 [--debug-lifecycle] [--debug-klips] [--debug-pfkey] [--debug-dns]
112 [--debug-dpd] [--debug-natt] [--debug-oppo] [--debug-oppoinfo]
113 [--debug-whackwatch] [--debug-private] [--impair-bust-mi2]
114 [--impair-bust-mr2] [--impair-sa-fail] [--impair-die-oninfo]
115 [--impair-jacob-two-two] [--impair-major-version-bump]
116 [--impair-minor-version-bump] [--impair-retransmits]
117 [--impair-send-bogus-isakmp-flag] [--impair-send-ikev2-ke]
118 [--impair-send-key-size-check] [--impair-send-no-delete]
119 ipsec whack [--utc] [--listall] [--listpubkeys] [--listcerts]
121 [--listcacerts] [--listcrls]
122 ipsec whack [--utc] [--rereadsecrets] [--rereadcrls] [--rereadall]
124 ipsec whack --listevents
126 ipsec whack --purgeocsp
128 ipsec whack --status [--ctlbase path] [--label string]
130 ipsec whack --trafficstatus --shuntstatus [--ctlbase path]
132 [--label string]
133 ipsec whack --shutdown [--ctlbase path] [--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 which 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 it certificate
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. At startup, pluto loads all the X.509 related
328 files from the directories /etc/ipsec.d/certs, /etc/ipsec.d/cacerts,
329 /etc/ipsec.d/aacerts, /etc/ipsec.d/private and /etc/ipsec.d/crls. The
330 Certificate Revocation Lists can also be retrieved from an URL. The
331 option --crlcheckinterval sets the time between checking for CRL
332 expiration and issuing new fetch commands. The first attempt to update
333 a CRL is started at 2*crlcheckinterval before the next update time.
334 Pluto logs a warning if no valid CRL was loaded or obtained for a
335 connection. If --strictcrlpolicy is given, the connection will be
336 rejected until a valid CRL has been loaded.
337 Pluto can also use helper children to off-load cryptographic
339 operations. This behavior can be fine tuned using the --nhelpers. Pluto
340 will start (n-1) of them, where n is the number of CPU’s you have
341 (including hypherthreaded CPU’s). A value of 0 forces pluto to do all
342 operations in the main process. A value of -1 tells pluto to perform
343 the above calculation. Any other value forces the number to that
344 amount.
345 Pluto uses the NSS crypto library as its random source. Some government
347 Three Letter Agency requires that pluto reads 440 bits from /dev/random
348 and feed this into the NSS RNG before drawing random from the NSS
349 library, despite the NSS library itself already seeding its internal
350 state. As this process can block pluto for an extended time, the
351 default is to not perform this redundant seeding. The --seedbits option
352 can be used to specify the number of bits that will be pulled from
353 /dev/random and seeded into the NSS RNG. This can also be accomplished
354 by specifying seedbits in the "config setup" section of ipsec.conf.
355 This option should not be used by most people.
356 pluto attempts to create a lockfile with the name
358 /var/run/pluto/pluto.pid. If the lockfile cannot be created, pluto
359 exits - this prevents multiple plutos from competing Any “leftover”
360 lockfile must be removed before pluto will run. pluto writes its PID
361 into this file so that scripts can find it. This lock will not function
362 properly if it is on an NFS volume (but sharing locks on multiple
363 machines doesn´t make sense anyway).
364 pluto then forks and the parent exits. This is the conventional “daemon
366 fork”. It can make debugging awkward, so there is an option to suppress
367 this fork. In certain configurations, pluto might also launch helper
368 programs to assist with DNS queries or to offload cryptographic
369 operations.
370 All logging, including diagnostics, is sent to syslog(3) with
372 facility=authpriv; it decides where to put these messages (possibly in
373 /var/log/secure or /var/log/auth.log). Since this too can make
374 debugging awkward, the option --stderrlog is used to steer logging to
375 stderr.
376 Alternatively, --logfile can be used to send all logging information to
378 a specific file.
379 If the --perpeerlog option is given, then pluto will open a log file
381 per connection. By default, this is in /var/log/pluto/peer, in a
382 subdirectory formed by turning all dot (.) [IPv4} or colon (:) [IPv6]
383 into slashes (/).
384 The base directory can be changed with the --perpeerlogbase.
386 Once pluto is started, it waits for requests from whack.
388 Pluto´s Internal State
390 To understand how to use pluto, it is helpful to understand a little
391 about its internal state. Furthermore, the terminology is needed to
392 decipher some of the diagnostic messages.
393 Pluto supports food groups, and X.509 certificates. These are located
395 in /etc/ipsec.d, or another directory as specified by --ipsecdir.
396 Pluto may core dump. It will normally do so into the current working
398 directory. You can specify the --coredir option for pluto, or specify
399 the dumpdir= option in ipsec.conf.
400 If you are investigating a potential memory leak in pluto, start pluto
402 with the --leak-detective option. Before the leak causes the system or
403 pluto to die, shut down pluto in the regular way. pluto will display a
404 list of leaks it has detected.
405 The (potential) connection database describes attributes of a
407 connection. These include the IP addresses of the hosts and client
408 subnets and the security characteristics desired. pluto requires this
409 information (simply called a connection) before it can respond to a
410 request to build an SA. Each connection is given a name when it is
411 created, and all references are made using this name.
412 During the IKE exchange to build an SA, the information about the
414 negotiation is represented in a state object. Each state object
415 reflects how far the negotiation has reached. Once the negotiation is
416 complete and the SA established, the state object remains to represent
417 the SA. When the SA is terminated, the state object is discarded. Each
418 State object is given a serial number and this is used to refer to the
419 state objects in logged messages.
420 Each state object corresponds to a connection and can be thought of as
422 an instantiation of that connection. At any particular time, there may
423 be any number of state objects corresponding to a particular
424 connection. Often there is one representing an ISAKMP SA and another
425 representing an IPsec SA.
426 KLIPS hooks into the routing code in a LINUX kernel. Traffic to be
428 processed by an IPsec SA must be directed through KLIPS by routing
429 commands. Furthermore, the processing to be done is specified by ipsec
430 eroute(8) commands. pluto takes the responsibility of managing both of
431 these special kinds of routes.
432 NETKEY requires no special routing.
434 Each connection may be routed, and must be while it has an IPsec SA.
436 The connection specifies the characteristics of the route: the
437 interface on this machine, the “gateway” (the nexthop), and the peer´s
438 client subnet. Two connections may not be simultaneously routed if they
439 are for the same peer´s client subnet but use different interfaces or
440 gateways (pluto´s logic does not reflect any advanced routing
441 capabilities).
442 On KLIPS, each eroute is associated with the state object for an IPsec
444 SA because it has the particular characteristics of the SA. Two eroutes
445 conflict if they specify the identical local and remote clients (unlike
446 for routes, the local clients are taken into account).
447 When pluto needs to install a route for a connection, it must make sure
449 that no conflicting route is in use. If another connection has a
450 conflicting route, that route will be taken down, as long as there is
451 no IPsec SA instantiating that connection. If there is such an IPsec
452 SA, the attempt to install a route will fail.
453 There is an exception. If pluto, as Responder, needs to install a route
455 to a fixed client subnet for a connection, and there is already a
456 conflicting route, then the SAs using the route are deleted to make
457 room for the new SAs. The rationale is that the new connection is
458 probably more current. The need for this usually is a product of Road
459 Warrior connections (these are explained later; they cannot be used to
460 initiate).
461 When pluto needs to install an eroute for an IPsec SA (for a state
463 object), first the state object´s connection must be routed (if this
464 cannot be done, the eroute and SA will not be installed). If a
465 conflicting eroute is already in place for another connection, the
466 eroute and SA will not be installed (but note that the routing
467 exception mentioned above may have already deleted potentially
468 conflicting SAs). If another IPsec SA for the same connection already
469 has an eroute, all its outgoing traffic is taken over by the new
470 eroute. The incoming traffic will still be processed. This
471 characteristic is exploited during rekeying.
472 All of these routing characteristics are expected change when KLIPS and
474 NETKEY merge into a single new stack.
475 Using whack
477 whack is used to command a running pluto. whack uses a UNIX domain
478 socket to speak to pluto (by default, /var/pluto.ctl).
479 whack has an intricate argument syntax. This syntax allows many
481 different functions to be specified. The help form shows the usage or
482 version information. The connection form gives pluto a description of a
483 potential connection. The public key form informs pluto of the RSA
484 public key for a potential peer. The delete form deletes a connection
485 description and all SAs corresponding to it. The listen form tells
486 pluto to start or stop listening on the public interfaces for IKE
487 requests from peers. The route form tells pluto to set up routing for a
488 connection; the unroute form undoes this. The initiate form tells pluto
489 to negotiate an SA corresponding to a connection. The terminate form
490 tells pluto to remove all SAs corresponding to a connection, including
491 those being negotiated. The status form displays the pluto´s internal
492 state. The debug form tells pluto to change the selection of debugging
493 output “on the fly”. The shutdown form tells pluto to shut down,
494 deleting all SAs.
495 The crash option asks pluto to consider a particularly target IP to
497 have crashed, and to attempt to restart all connections with that IP
498 address as a gateway. In general, you should use Dead Peer Detection to
499 detect this kind of situation automatically, but this is not always
500 possible.
501 Most options are specific to one of the forms, and will be described
503 with that form. There are three options that apply to all forms.
504 --ctlbase path
506 path.ctl is used as the UNIX domain socket for talking to pluto.
507 This option facilitates debugging.
508 --label string
510 adds the string to all error messages generated by whack.
511 The help form of whack is self-explanatory.
513 --help
515 display the usage message.
516 --version
518 display the version of whack.
519 The connection form describes a potential connection to pluto. pluto
521 needs to know what connections can and should be negotiated. When pluto
522 is the initiator, it needs to know what to propose. When pluto is the
523 responder, it needs to know enough to decide whether is is willing to
524 set up the proposed connection.
525 The description of a potential connection can specify a large number of
527 details. Each connection has a unique name. This name will appear in a
528 updown shell command, so it should not contain punctuation that would
529 make the command ill-formed.
530 --name connection-name
532 sets the name of the connection
533 The topology of a connection is symmetric, so to save space here is
535 half a picture:
536 client_subnet<-->host:ikeport<-->nexthop<---
538 A similar trick is used in the flags. The same flag names are used for
540 both ends. Those before the --to flag describe the left side and those
541 afterwards describe the right side. When pluto attempts to use the
542 connection, it decides whether it is the left side or the right side of
543 the connection, based on the IP numbers of its interfaces.
544 --id id
546 the identity of the end. Currently, this can be an IP address
547 (specified as dotted quad or as a Fully Qualified Domain Name,
548 which will be resolved immediately) or as a Fully Qualified Domain
549 Name itself (prefixed by “@” to signify that it should not be
550 resolved), or as user@FQDN, or an X.509 DN, or as the magic value
551 %myid. Pluto only authenticates the identity, and does not use it
552 for addressing, so, for example, an IP address need not be the one
553 to which packets are to be sent. If the option is absent, the
554 identity defaults to the IP address specified by --host. %myid
555 allows the identity to be separately specified (by the pluto or
556 whack option --myid or by the ipsec.conf(5) config setup parameter
557 myid). Otherwise, pluto tries to guess what %myid should stand for:
558 the IP address of %defaultroute, if it is supported by a suitable
559 TXT record in the reverse domain for that IP address, or the
560 system´s hostname, if it is supported by a suitable TXT record in
561 its forward domain.
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 filename
572 The filename of the X.509 certificate. This must be the public key
573 certificate only, and cannot be the PKCS#12 certificate file. See
574 ipsec.conf(5) on how to extrac this from the PKCS#12 file.
575 --ca distinguished name
577 the X.509 Certificate Authority´s Distinguished Name (DN) used as
578 trust anchor for this connection. This is the CA certificate that
579 signed the host certificate, as well as the certificate of the
580 incoming client.
581 --groups access control groups
583 the access control groups used.
584 --sendcert yes|forced|always|ifasked|no|never
586 Whether or not to send our X.509 certificate credentials. This
587 could potentially give an attacker too much information about which
588 identities are allowed to connect to this host. The default is to
589 use ifasked when we are a Responder, and to use yes (which is the
590 same as forced and always if we are an Initiator. The values no and
591 never are equivalent. NOTE: "forced" does not seem to be actually
592 implemented - do not use it.
593 --sendca none|issuer|all
595 How much of our available X.509 trust chain to send with the end
596 certificate, excluding any root CAs. Specifying issuer sends just
597 the issuing intermediate CA, while
598 all will send the entire chain of intermediate CAs.none will not
599 send any CA certs. The default is none which maintains the current
600 libreswan behavior.
601 --certtype number
603 The X.509 certificate type number.
604 --ikeport port-number
606 the UDP port that IKE listens to on that host. The default is 500.
607 (pluto on this machine uses the port specified by its own command
608 line argument, so this only affects where pluto sends messages.)
609 --nexthop ip-address
611 where to route packets for the peer´s client (presumably for the
612 peer too, but it will not be used for this). When pluto installs an
613 IPsec SA, it issues a route command. It uses the nexthop as the
614 gateway. The default is the peer´s IP address (this can be
615 explicitly written as %direct; the obsolete notation 0.0.0.0 is
616 accepted). This option is necessary if pluto´s host´s interface
617 used for sending packets to the peer is neither point-to-point nor
618 directly connected to the peer.
619 --client subnet
621 the subnet for which the IPsec traffic will be destined. If not
622 specified, the host will be the client. The subnet can be specified
623 in any of the forms supported by ipsec_atosubnet(3). The general
624 form is address/mask. The address can be either a domain name or
625 four decimal numbers (specifying octets) separated by dots. The
626 most convenient form of the mask is a decimal integer, specifying
627 the number of leading one bits in the mask. So, for example,
628 10.0.0.0/8 would specify the class A network “Net 10”.
629 --clientwithin subnet
631 This option is obsolete and will be removed. Do not use this option
632 anymore.
633 --clientprotoport protocol/port
635 specify the Port Selectors (filters) to be used on this connection.
636 The general form is protocol/port. This is most commonly used to
637 limit the connection to L2TP traffic only by specifying a value of
638 17/1701 for UDP (protocol 17) and port 1701. The notation 17/%any
639 can be used to allow all UDP traffic and is needed for L2TP
640 connections with Windows XP machines before Service Pack 2.
641 --srcip ip-address
643 the IP address for this host to use when transmitting a packet to
644 the remote IPsec gateway itself. This option is used to make the
645 gateway itself use its internal IP, which is part of the --client
646 subnet. Otherwise it will use its nearest IP address, which is its
647 public IP address, which is not part of the subnet-subnet IPsec
648 tunnel, and would therefor not get encrypted.
649 --xauthserver
651 this end is an xauthserver. It will lookup the xauth user name and
652 password and verify this before allowing the connection to get
653 established.
654 --xauthclient
656 this end is an xauthclient. To bring this connection up with the
657 --initiate also requires the client to specify --xauthuser username
658 and --xauthpass password
659 --xauthuser
661 The username for the xauth authentication.This option is normally
662 passed along by ipsec_auto(8) when an xauth connection is started
663 using ipsec auto --up conn
664 --xauthpass
666 The password for the xauth authentication. This option is normally
667 passed along by ipsec_auto(8) when an xauth connection is started
668 using ipsec auto --up conn
669 --modecfgserver
671 this end is an Mode Config server
672 --modecfgclient
674 this end is an Mode Config client
675 --modecfgdns1
677 The IP address of the first DNS server to pass along to the
678 ModeConfig Client
679 --modecfgdns2
681 The IP address of the second DNS server to pass along to the
682 ModeConfig Client
683 --dnskeyondemand
685 specifies that when an RSA public key is needed to authenticate
686 this host, and it isn´t already known, fetch it from DNS.
687 --updown updown
689 specifies an external shell command to be run whenever pluto brings
690 up or down a connection. The script is used to build a shell
691 command, so it may contain positional parameters, but ought not to
692 have punctuation that would cause the resulting command to be
693 ill-formed. The default is ipsec _updown. Pluto passes a dozen
694 environment variables to the script about the connection involved.
695 --to
697 separates the specification of the left and right ends of the
698 connection. Pluto tries to decide whether it is left or right based
699 on the information provided on both sides of this option.
700 The potential connection description also specifies characteristics of
702 rekeying and security.
703 --psk
705 Propose and allow preshared secret authentication for IKE peers.
706 This authentication requires that each side use the same secret.
707 May be combined with --rsasig; at least one must be specified.
708 --rsasig
710 Propose and allow RSA signatures for authentication of IKE peers.
711 This authentication requires that each side have have a private key
712 of its own and know the public key of its peer. May be combined
713 with --psk; at least one must be specified.
714 --encrypt
716 All proposed or accepted IPsec SAs will include non-null ESP. The
717 actual choices of transforms are wired into pluto.
718 --authenticate
720 All proposed IPsec SAs will include AH. All accepted IPsec SAs will
721 include AH or ESP with authentication. The actual choices of
722 transforms are wired into pluto. Note that this has nothing to do
723 with IKE authentication.
724 --compress
726 All proposed IPsec SAs will include IPCOMP (compression). This will
727 be ignored if KLIPS is not configured with IPCOMP support.
728 --tunnel
730 the IPsec SA should use tunneling. Implicit if the SA is for
731 clients. Must only be used with --authenticate or --encrypt.
732 --ipv4
734 The host addresses will be interpreted as IPv4 addresses. This is
735 the default. Note that for a connection, all host addresses must be
736 of the same Address Family (IPv4 and IPv6 use different Address
737 Families).
738 --ipv6
740 The host addresses (including nexthop) will be interpreted as IPv6
741 addresses. Note that for a connection, all host addresses must be
742 of the same Address Family (IPv4 and IPv6 use different Address
743 Families).
744 --tunnelipv4
746 The client addresses will be interpreted as IPv4 addresses. The
747 default is to match what the host will be. This does not imply
748 --tunnel so the flag can be safely used when no tunnel is actually
749 specified. Note that for a connection, all tunnel addresses must be
750 of the same Address Family.
751 --tunnelipv6
753 The client addresses will be interpreted as IPv6 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 --pfs
760 There should be Perfect Forward Secrecy - new keying material will
761 be generated for each IPsec SA rather than being derived from the
762 ISAKMP SA keying material. Since the group to be used cannot be
763 negotiated (a dubious feature of the standard), pluto will propose
764 the same group that was used during Phase 1. We don´t implement a
765 stronger form of PFS which would require that the ISAKMP SA be
766 deleted after the IPSEC SA is negotiated.
767 --pfsgroup modp-group
769 Sets the Diffie-Hellman group used. Currently the following values
770 are supported: modp1024 (DHgroup 2), modp1536 (DHgroup 5), modp2048
771 (DHgroup 14), modp3072 (DHgroup 15), modp4096 (DHgroup 16),
772 modp6144 (DHgroup 17), and modp8192 (DHgroup 18). It is possible to
773 support the weak and broken modp768 (DHgroup 1), but this requires
774 a manual recompile and is strongly discouraged.
775 --disablearrivalcheck
777 If the connection is a tunnel, allow packets arriving through the
778 tunnel to have any source and destination addresses.
779 --esp esp-algos
781 ESP encryption/authentication algorithm to be used for the
782 connection (phase2 aka IPsec SA). The options must be suitable as a
783 value of ipsec_spi(8). See ipsec.conf(5) for a detailed description
784 of the algorithm format.
785 --aggrmode
787 This tunnel is using aggressive mode ISAKMP negotiation. The
788 default is main mode. Aggressive mode is less secure than main mode
789 as it reveals your identity to an eavesdropper, but is needed to
790 support road warriors using PSK keys or to interoperate with other
791 buggy implementations insisting on using aggressive mode.
792 --modecfgpull
794 Pull the Mode Config network information from the peer.
795 --dpddelay seconds
797 Set the delay (in seconds) between Dead Peer Detection (RFC 3706)
798 keepalives (R_U_THERE, R_U_THERE_ACK) that are sent for this
799 connection (default 30 seconds).
800 --timeout seconds
802 Set the length of time (in seconds) we will idle without hearing
803 either an R_U_THERE poll from our peer, or an R_U_THERE_ACK reply.
804 After this period has elapsed with no response and no traffic, we
805 will declare the peer dead, and remove the SA (default 120
806 seconds).
807 --dpdaction action
809 When a DPD enabled peer is declared dead, what action should be
810 taken. hold(default) means the eroute will be put into %hold
811 status, while clearmeans the eroute and SA with both be cleared.
812 Clear is really only useful on the server of a Road Warrior config.
813 The action restart is used on tunnels that need to be permanently
814 up, and have static IP addresses. The action restart_by_peerhas
815 been obsoleted and its functionality has been moved into the
816 restart action.
817 --forceencaps
819 In some cases, for example when ESP packets are filtered or when a
820 broken IPsec peer does not properly recognise NAT, it can be useful
821 to force RFC-3948 encapsulation using this option. It causes pluto
822 lie and tell the remote peer that RFC-3948 encapsulation (ESP in
823 UDP port 4500 packets) is required.
824 If none of the --encrypt, --authenticate, --compress, or --pfs flags is
826 given, the initiating the connection will only build an ISAKMP SA. For
827 such a connection, client subnets have no meaning and must not be
828 specified.
829 Apart from initiating directly using the --initiate option, a tunnel
831 can be loaded with a different policy
832 --initiateontraffic
834 Only initiate the connection when we have traffic to send over the
835 connection
836 --pass
838 Allow unencrypted traffic to flow until the tunnel is initiated.
839 --drop
841 Drop unencrypted traffic silently.
842 --reject
844 Drop unencrypted traffic silently, but send an ICMP message
845 notifying the other end.
846 These options need to be documented
848 --failnone
850 to be documented
851 --failpass
853 to be documented
854 --faildrop
856 to be documented
857 --failreject
859 to be documented
860 pluto supports various X.509 Certificate related options.
862 --utc
864 display all times in UTC.
865 --listall
867 lists all of the X.509 information known to pluto.
868 --listpubkeys
870 list all the public keys that have been successfully loaded.
871 --listcerts
873 list all the X.509 certificates that are currently loaded.
874 --checkpubkeys
876 list all the loaded X.509 certificates which are about to expire or
877 have been expired.
878 --listcacerts
880 list all the Certificate Authority X.509 certificates that are
881 currently loaded.
882 --listcrls
884 list all the loaded Certificate Revocation Lists (CRLs)
885 The corresponding options --rereadsecrets, --rereadall, and
887 --rereadcrls options reread this information from their respective
888 sources, and purge all the online obtained information. The option
889 --listevents lists all pending CRL fetch commands.
890 --ikelifetime seconds
892 how long pluto will propose that an ISAKMP SA be allowed to live.
893 The default is 3600 (one hour) and the maximum is 86400 (1 day).
894 This option will not affect what is accepted. pluto will reject
895 proposals that exceed the maximum.
896 --ipseclifetime seconds
898 how long pluto will propose that an IPsec SA be allowed to live.
899 The default is 28800 (eight hours) and the maximum is 86400 (one
900 day). This option will not affect what is accepted. pluto will
901 reject proposals that exceed the maximum.
902 --rekeymargin seconds
904 how long before an SA´s expiration should pluto try to negotiate a
905 replacement SA. This will only happen if pluto was the initiator.
906 The default is 540 (nine minutes).
907 --rekeyfuzz percentage
909 maximum size of random component to add to rekeymargin, expressed
910 as a percentage of rekeymargin. pluto will select a delay
911 uniformly distributed within this range. By default, the percentage
912 will be 100. If greater determinism is desired, specify 0. It may
913 be appropriate for the percentage to be much larger than 100.
914 --keyingtries count
916 how many times pluto should try to negotiate an SA, either for the
917 first time or for rekeying. A value of 0 is interpreted as a very
918 large number: never give up. The default is three.
919 --dontrekey
921 A misnomer. Only rekey a connection if we were the Initiator and
922 there was recent traffic on the existing connection. This applies
923 to Phase 1 and Phase 2. This is currently the only automatic way
924 for a connection to terminate. It may be useful with Road Warrior
925 or Opportunistic connections. Since SA lifetime negotiation is
926 take-it-or-leave it, a Responder normally uses the shorter of the
927 negotiated or the configured lifetime. This only works because if
928 the lifetime is shorter than negotiated, the Responder will rekey
929 in time so that everything works. This interacts badly with
930 --dontrekey. In this case, the Responder will end up rekeying to
931 rectify a shortfall in an IPsec SA lifetime; for an ISAKMP SA, the
932 Responder will accept the negotiated lifetime.
933 --delete
935 when used in the connection form, it causes any previous connection
936 with this name to be deleted before this one is added. Unlike a
937 normal delete, no diagnostic is produced if there was no previous
938 connection to delete. Any routing in place for the connection is
939 undone.
940 --delete, --name connection-name
942 The delete form deletes a named connection description and any SAs
943 established or negotiations initiated using this connection. Any
944 routing in place for the connection is undone.
945 --deletestate state-number
947 The deletestate form deletes the state object with the specified
948 serial number. This is useful for selectively deleting instances of
949 connections.
950 The route form of the whack command tells pluto to set up routing for a
952 connection. Although like a traditional route, it uses an ipsec device
953 as a virtual interface. Once routing is set up, no packets will be sent
954 “in the clear” to the peer´s client specified in the connection. A TRAP
955 shunt eroute will be installed; if outbound traffic is caught, Pluto
956 will initiate the connection. An explicit whack route is not always
957 needed: if it hasn´t been done when an IPsec SA is being installed, one
958 will be automatically attempted.
959 --route, --name connection-name
961 When a routing is attempted for a connection, there must not
962 already be a routing for a different connection with the same
963 subnet but different interface or destination, or if there is, it
964 must not be being used by an IPsec SA. Otherwise the attempt will
965 fail.
966 --unroute, --name connection-name
968 The unroute form of the whack command tells pluto to undo a
969 routing. pluto will refuse if an IPsec SA is using the connection.
970 If another connection is sharing the same routing, it will be left
971 in place. Without a routing, packets will be sent without
972 encryption or authentication.
973 The initiate form tells pluto to initiate a negotiation with another
975 pluto (or other IKE daemon) according to the named connection.
976 Initiation requires a route that --route would provide; if none is in
977 place at the time an IPsec SA is being installed, pluto attempts to set
978 one up.
979 --initiate, --name connection-name, --asynchronous
981 The initiate form of the whack command will relay back from pluto
982 status information via the UNIX domain socket (unless
983 --asynchronous is specified). The status information is meant to
984 look a bit like that from FTP. Currently whack simply copies this
985 to stderr. When the request is finished (eg. the SAs are
986 established or pluto gives up), pluto closes the channel, causing
987 whack to terminate.
988 The opportunistic initiate form is mainly used for debugging.
990 --tunnelipv4, --tunnelipv6, --oppohere ip-address,
992 --oppothere ip-address
993 This will cause pluto to attempt to opportunistically initiate a
994 connection from here to the there, even if a previous attempt had
995 been made. The whack log will show the progress of this attempt.
996 Ending an connection
998 --terminate, --name connection-name
1000 the terminate form tells pluto to delete any SAs that use the
1001 specified connection and to stop any negotiations in process. it
1002 does not prevent new negotiations from starting (the delete form
1003 has this effect).
1004 --crash ip-address
1006 If the remote peer has crashed, and therefor did not notify us, we
1007 keep sending encrypted traffic, and rejecting all plaintext
1008 (non-IKE) traffic from that remote peer. The --crash brings our end
1009 down as well for all the known connections to the specified
1010 ip-address
1011 --whackrecordfilename, --whackstoprecord
1013 this causes plutoto open the given filename for write, and record
1014 each of the messages received from whack or addconn. This continues
1015 until the whackstoprecord option is used. This option may not be
1016 combined with any other command. The start/stop commands are not
1017 recorded themselves. These files are usually used to create input
1018 files for unit tests, particularly for complex setups where
1019 policies may in fact overlap.
1020 The format of the file consists of a line starting with
1022 #!pluto-whack and the date that the file was started, as well as
1023 the hostname, and a linefeed. What follows are binary format
1024 records consisting of a 32-bit record length in bytes, (including
1025 the length record itself), a 64-bit timestamp, and then the literal
1026 contents of the whack message that was received. All integers are
1027 in host format. In order to unambigously determine the host order,
1028 the first record is an empty record that contains only the current
1029 WHACK_MAGIC value. This record is 16 bytes long.
1030 ip-address
1032 If the remote peer has crashed, and therefor did not notify us, we
1033 keep sending encrypted traffic, and rejecting all plaintext
1034 (non-IKE) traffic from that remote peer. The --crash brings our end
1035 down as well for all the known connections to the specified
1036 ip-address
1037 The public key for informs pluto of the RSA public key for a potential
1039 peer. Private keys must be kept secret, so they are kept in
1040 ipsec.secrets(5).
1041 --keyid id
1043 specififies the identity of the peer for which a public key should
1044 be used. Its form is identical to the identity in the connection.
1045 If no public key is specified, pluto attempts to find KEY records
1046 from DNS for the id (if a FQDN) or through reverse lookup (if an IP
1047 address). Note that there several interesting ways in which this is
1048 not secure.
1049 --addkey
1051 specifies that the new key is added to the collection; otherwise
1052 the new key replaces any old ones.
1053 --pubkeyrsa key
1055 specifies the value of the RSA public key. It is a sequence of
1056 bytes as described in RFC 2537 “RSA/MD5 KEYs and SIGs in the Domain
1057 Name System (DNS)”. It is denoted in a way suitable for
1058 ipsec_ttodata(3). For example, a base 64 numeral starts with 0s.
1059 The listen form tells pluto to start listening for IKE requests on its
1061 public interfaces. To avoid race conditions, it is normal to load the
1062 appropriate connections into pluto before allowing it to listen. If
1063 pluto isn´t listening, it is pointless to initiate negotiations, so it
1064 will refuse requests to do so. Whenever the listen form is used, pluto
1065 looks for public interfaces and will notice when new ones have been
1066 added and when old ones have been removed. This is also the trigger for
1067 pluto to read the ipsec.secrets file. So listen may useful more than
1068 once.
1069 --listen
1071 start listening for IKE traffic on public interfaces.
1072 --unlisten
1074 stop listening for IKE traffic on public interfaces.
1075 The busy and relax options tells pluto to explicitly activate or
1077 deactivate additional DDoS protection. Normally, these meassures are
1078 automatically activate or deactivate based on the number of states
1079 inside pluto. One of these DDoS protection methods is to active IKEv2
1080 DCOOKIEs to defend against spoofed IKE packets.
1081 --busy
1083 place pluto into busy mode and activate anti-DDoS measures.
1084 --relax
1086 pull pluto out of busy mode and deactivate anti-DDoS measures.
1087 The status form will display information about the internal state of
1089 pluto: information about each potential connection, about each state
1090 object, and about each shunt that pluto is managing without an
1091 associated connection.
1092 --status
1094 The trafficstatus form will display the xauth username, add_time and
1096 the total in and out bytes of the IPsec SA´s.
1097 --trafficstatus
1099 The shutdown form is the proper way to shut down pluto. It will tear
1101 down the SAs on this machine that pluto has negotiated. It does not
1102 inform its peers, so the SAs on their machines remain.
1103 --shutdown
1105 Examples
1107 It would be normal to start pluto in one of the system initialization
1108 scripts. It needs to be run by the superuser. Generally, no arguments
1109 are needed. To run in manually, the superuser can simply type
1110 ipsec pluto
1112 The command will immediately return, but a pluto process will be left
1114 running, waiting for requests from whack or a peer.
1115 Using whack, several potential connections would be described:
1117 ipsec whack --name silly --host 127.0.0.1 --to --host 127.0.0.2
1119 --ikelifetime 900 --ipseclifetime 800 --keyingtries 3
1120 Since this silly connection description specifies neither encryption,
1122 authentication, nor tunneling, it could only be used to establish an
1123 ISAKMP SA.
1124 ipsec whack --name conn_name --host 10.0.0.1 --client 10.0.1.0/24
1126 --to --host 10.0.0.2 --client 10.0.2.0/24 --encrypt
1127 This is something that must be done on both sides. If the other side is
1129 pluto, the same whack command could be used on it (the command syntax
1130 is designed to not distinguish which end is ours).
1131 Now that the connections are specified, pluto is ready to handle
1133 requests and replies via the public interfaces. We must tell it to
1134 discover those interfaces and start accepting messages from peers:
1135 ipsec whack --listen
1137 If we don´t immediately wish to bring up a secure connection between
1139 the two clients, we might wish to prevent insecure traffic. The routing
1140 form asks pluto to cause the packets sent from our client to the peer´s
1141 client to be routed through the ipsec0 device; if there is no SA, they
1142 will be discarded:
1143 ipsec whack --route conn_name
1145 Finally, we are ready to get pluto to initiate negotiation for an IPsec
1147 SA (and implicitly, an ISAKMP SA):
1148 ipsec whack --initiate --name conn_name
1150 A small log of interesting events will appear on standard output (other
1152 logging is sent to syslog).
1153 whack can also be used to terminate pluto cleanly, tearing down all SAs
1155 that it has negotiated.
1156 ipsec whack --shutdown
1158 Notification of any IPSEC SA deletion, but not ISAKMP SA deletion is
1160 sent to the peer. Unfortunately, such Notification is not reliable.
1161 Furthermore, pluto itself ignores Notifications.
1162 XAUTH
1164 If pluto needs additional authentication, such as defined by the XAUTH
1165 specifications, then it may ask whack to prompt the operator for
1166 username or passwords. Typically, these will be entered interactively.
1167 A GUI that wraps around whack may look for the 041 (username) or 040
1168 (password) prompts, and display them to the user.
1169 For testing purposes, the options --xauthuser user --xauthpass pass may
1171 be be given prior to the --initiate to provide responses to the
1172 username and password prompts.
1173 The updown command
1175 Whenever pluto brings a connection up or down, it invokes the updown
1176 command. This command is specified using the --updown option. This
1177 allows for customized control over routing and firewall manipulation.
1178 The updown is invoked for five different operations. Each of these
1180 operations can be for our client subnet or for our host itself.
1181 prepare-host or prepare-client
1183 is run before bringing up a new connection if no other connection
1184 with the same clients is up. Generally, this is useful for deleting
1185 a route that might have been set up before pluto was run or perhaps
1186 by some agent not known to pluto.
1187 route-host or route-client
1189 is run when bringing up a connection for a new peer client subnet
1190 (even if prepare-host or prepare-client was run). The command
1191 should install a suitable route. Routing decisions are based only
1192 on the destination (peer´s client) subnet address, unlike eroutes
1193 which discriminate based on source too.
1194 unroute-host or unroute-client
1196 is run when bringing down the last connection for a particular peer
1197 client subnet. It should undo what the route-host or route-client
1198 did.
1199 up-host or up-client
1201 is run when bringing up a tunnel eroute with a pair of client
1202 subnets that does not already have a tunnel eroute. This command
1203 should install firewall rules as appropriate. It is generally a
1204 good idea to allow IKE messages (UDP port 500) travel between the
1205 hosts.
1206 down-host or down-client
1208 is run when bringing down the eroute for a pair of client subnets.
1209 This command should delete firewall rules as appropriate. Note that
1210 there may remain some inbound IPsec SAs with these client subnets.
1211 The script is passed a large number of environment variables to specify
1213 what needs to be done.
1214 PLUTO_VERSION
1216 indicates what version of this interface is being used. This
1217 document describes version 1.1. This is upwardly compatible with
1218 version 1.0.
1219 PLUTO_VERB
1221 specifies the name of the operation to be performed (prepare-host,r
1222 prepare-client, up-host, up-client, down-host, or down-client). If
1223 the address family for security gateway to security gateway
1224 communications is IPv6, then a suffix of -v6 is added to the verb.
1225 PLUTO_CONNECTION
1227 is the name of the connection for which we are routing.
1228 PLUTO_NEXT_HOP
1230 is the next hop to which packets bound for the peer must be sent.
1231 PLUTO_INTERFACE
1233 is the name of the ipsec interface to be used.
1234 PLUTO_ME
1236 is the IP address of our host.
1237 PLUTO_MY_CLIENT
1239 is the IP address / count of our client subnet. If the client is
1240 just the host, this will be the host´s own IP address / max (where
1241 max is 32 for IPv4 and 128 for IPv6).
1242 PLUTO_MY_CLIENT_NET
1244 is the IP address of our client net. If the client is just the
1245 host, this will be the host´s own IP address.
1246 PLUTO_MY_CLIENT_MASK
1248 is the mask for our client net. If the client is just the host,
1249 this will be 255.255.255.255.
1250 PLUTO_PEER
1252 is the IP address of our peer.
1253 PLUTO_PEER_CLIENT
1255 is the IP address / count of the peer´s client subnet. If the
1256 client is just the peer, this will be the peer´s own IP address /
1257 max (where max is 32 for IPv4 and 128 for IPv6).
1258 PLUTO_PEER_CLIENT_NET
1260 is the IP address of the peer´s client net. If the client is just
1261 the peer, this will be the peer´s own IP address.
1262 PLUTO_PEER_CLIENT_MASK
1264 is the mask for the peer´s client net. If the client is just the
1265 peer, this will be 255.255.255.255.
1266 PLUTO_MY_PROTOCOL
1268 lists the protocols allowed over this IPsec SA.
1269 PLUTO_PEER_PROTOCOL
1271 lists the protocols the peer allows over this IPsec SA.
1272 PLUTO_MY_PORT
1274 lists the ports allowed over this IPsec SA.
1275 PLUTO_PEER_PORT
1277 lists the ports the peer allows over this IPsec SA.
1278 PLUTO_MY_ID
1280 lists our id.
1281 PLUTO_PEER_ID
1283 Dlists our peer´s id.
1284 PLUTO_PEER_CA
1286 lists the peer´s CA.
1287 All output sent by the script to stderr or stdout is logged. The script
1289 should return an exit status of 0 if and only if it succeeds.
1290 Pluto waits for the script to finish and will not do any other
1292 processing while it is waiting. The script may assume that pluto will
1293 not change anything while the script runs. The script should avoid
1294 doing anything that takes much time and it should not issue any command
1295 that requires processing by pluto. Either of these activities could be
1296 performed by a background subprocess of the script.
1297 Rekeying
1299 When an SA that was initiated by pluto has only a bit of lifetime left,
1300 pluto will initiate the creation of a new SA. This applies to ISAKMP
1301 and IPsec SAs. The rekeying will be initiated when the SA´s remaining
1302 lifetime is less than the rekeymargin plus a random percentage, between
1303 0 and rekeyfuzz, of the rekeymargin.
1304 Similarly, when an SA that was initiated by the peer has only a bit of
1306 lifetime left, pluto will try to initiate the creation of a
1307 replacement. To give preference to the initiator, this rekeying will
1308 only be initiated when the SA´s remaining lifetime is half of
1309 rekeymargin. If rekeying is done by the responder, the roles will be
1310 reversed: the responder for the old SA will be the initiator for the
1311 replacement. The former initiator might also initiate rekeying, so
1312 there may be redundant SAs created. To avoid these complications, make
1313 sure that rekeymargin is generous.
1314 One risk of having the former responder initiate is that perhaps none
1316 of its proposals is acceptable to the former initiator (they have not
1317 been used in a successful negotiation). To reduce the chances of this
1318 happening, and to prevent loss of security, the policy settings are
1319 taken from the old SA (this is the case even if the former initiator is
1320 initiating). These may be stricter than those of the connection.
1321 pluto will not rekey an SA if that SA is not the most recent of its
1323 type (IPsec or ISAKMP) for its potential connection. This avoids
1324 creating redundant SAs.
1325 The random component in the rekeying time (rekeyfuzz) is intended to
1327 make certain pathological patterns of rekeying unstable. If both sides
1328 decide to rekey at the same time, twice as many SAs as necessary are
1329 created. This could become a stable pattern without the randomness.
1330 Another more important case occurs when a security gateway has SAs with
1332 many other security gateways. Each of these connections might need to
1333 be rekeyed at the same time. This would cause a high peek requirement
1334 for resources (network bandwidth, CPU time, entropy for random
1335 numbers). The rekeyfuzz can be used to stagger the rekeying times.
1336 Once a new set of SAs has been negotiated, pluto will never send
1338 traffic on a superseded one. Traffic will be accepted on an old SA
1339 until it expires.
1340 Selecting a Connection When Responding: Road Warrior Support
1342 When pluto receives an initial Main Mode message, it needs to decide
1343 which connection this message is for. It picks based solely on the
1344 source and destination IP addresses of the message. There might be
1345 several connections with suitable IP addresses, in which case one of
1346 them is arbitrarily chosen. (The ISAKMP SA proposal contained in the
1347 message could be taken into account, but it is not.)
1348 The ISAKMP SA is negotiated before the parties pass further identifying
1350 information, so all ISAKMP SA characteristics specified in the
1351 connection description should be the same for every connection with the
1352 same two host IP addresses. At the moment, the only characteristic that
1353 might differ is authentication method.
1354 Up to this point, all configuring has presumed that the IP addresses
1356 are known to all parties ahead of time. This will not work when either
1357 end is mobile (or assigned a dynamic IP address for other reasons). We
1358 call this situation “Road Warrior”. It is fairly tricky and has some
1359 important limitations, most of which are features of the IKE protocol.
1360 Only the initiator may be mobile: the initiator may have an IP number
1362 unknown to the responder. When the responder doesn´t recognize the IP
1363 address on the first Main Mode packet, it looks for a connection with
1364 itself as one end and %any as the other. If it cannot find one, it
1365 refuses to negotiate. If it does find one, it creates a temporary
1366 connection that is a duplicate except with the %any replaced by the
1367 source IP address from the packet; if there was no identity specified
1368 for the peer, the new IP address will be used.
1369 When pluto is using one of these temporary connections and needs to
1371 find the preshared secret or RSA private key in ipsec.secrets, and and
1372 the connection specified no identity for the peer, %any is used as its
1373 identity. After all, the real IP address was apparently unknown to the
1374 configuration, so it is unreasonable to require that it be used in this
1375 table.
1376 Part way into the Phase 1 (Main Mode) negotiation using one of these
1378 temporary connection descriptions, pluto will be receive an Identity
1379 Payload. At this point, pluto checks for a more appropriate connection,
1380 one with an identity for the peer that matches the payload but which
1381 would use the same keys so-far used for authentication. If it finds
1382 one, it will switch to using this better connection (or a temporary
1383 derived from this, if it has %any for the peer´s IP address). It may
1384 even turn out that no connection matches the newly discovered identity,
1385 including the current connection; if so, pluto terminates negotiation.
1386 Unfortunately, if preshared secret authentication is being used, the
1388 Identity Payload is encrypted using this secret, so the secret must be
1389 selected by the responder without knowing this payload. This limits
1390 there to being at most one preshared secret for all Road Warrior
1391 systems connecting to a host. RSA Signature authentications does not
1392 require that the responder know how to select the initiator´s public
1393 key until after the initiator´s Identity Payload is decoded (using the
1394 responder´s private key, so that must be preselected).
1395 When pluto is responding to a Quick Mode negotiation via one of these
1397 temporary connection descriptions, it may well find that the subnets
1398 specified by the initiator don´t match those in the temporary
1399 connection description. If so, it will look for a connection with
1400 matching subnets, its own host address, a peer address of %any and
1401 matching identities. If it finds one, a new temporary connection is
1402 derived from this one and used for the Quick Mode negotiation of IPsec
1403 SAs. If it does not find one, pluto terminates negotiation.
1404 Be sure to specify an appropriate nexthop for the responder to send a
1406 message to the initiator: pluto has no way of guessing it (if
1407 forwarding isn´t required, use an explicit %direct as the nexthop and
1408 the IP address of the initiator will be filled in; the obsolete
1409 notation 0.0.0.0 is still accepted).
1410 pluto has no special provision for the initiator side. The current
1412 (possibly dynamic) IP address and nexthop must be used in defining
1413 connections. These must be properly configured each time the
1414 initiator´s IP address changes. pluto has no mechanism to do this
1415 automatically.
1416 Although we call this Road Warrior Support, it could also be used to
1418 support encrypted connections with anonymous initiators. The
1419 responder´s organization could announce the preshared secret that would
1420 be used with unrecognized initiators and let anyone connect. Of course
1421 the initiator´s identity would not be authenticated.
1422 If any Road Warrior connections are supported, pluto cannot reject an
1424 exchange initiated by an unknown host until it has determined that the
1425 secret is not shared or the signature is invalid. This must await the
1426 third Main Mode message from the initiator. If no Road Warrior
1427 connection is supported, the first message from an unknown source would
1428 be rejected. This has implications for ease of debugging configurations
1429 and for denial of service attacks.
1430 Although a Road Warrior connection must be initiated by the mobile
1432 side, the other side can and will rekey using the temporary connection
1433 it has created. If the Road Warrior wishes to be able to disconnect, it
1434 is probably wise to set --keyingtries to 1 in the connection on the
1435 non-mobile side to prevent it trying to rekey the connection.
1436 Unfortunately, there is no mechanism to unroute the connection
1437 automatically.
1438 Debugging
1440 pluto accepts several optional arguments, useful mostly for debugging.
1441 Except for --interface, each should appear at most once.
1442 --interface interfacename
1444 specifies that the named real public network interface should be
1445 considered. The interface name specified should not be ipsecN. If
1446 the option doesn´t appear, all interfaces are considered. To
1447 specify several interfaces, use the option once for each. One use
1448 of this option is to specify which interface should be used when
1449 two or more share the same IP address.
1450 --ikeport port-number
1452 changes the UDP port that pluto will use (default, specified by
1453 IANA: 500)
1454 --ctlbase path
1456 basename for control files. path.ctl is the socket through which
1457 whack communicates with pluto. path.pid is the lockfile to prevent
1458 multiple pluto instances. The default is /var/run/pluto/pluto).
1459 --secretsfile file
1461 specifies the file for authentication secrets (default:
1462 /etc/ipsec.secrets). This name is subject to “globbing” as in
1463 sh(1), so every file with a matching name is processed. Quoting is
1464 generally needed to prevent the shell from doing the globbing.
1465 --adns path to adns
1467 specifies where to find pluto´s helper program for asynchronous DNS
1468 lookup. pluto can be built to use _pluto_adns. By default, pluto
1469 will look for the program in $IPSEC_DIR (if that environment
1470 variable is defined) or, failing that, in the same directory as
1471 pluto.
1472 --nofork
1474 disable “daemon fork” (default is to fork). In addition, after the
1475 lock file and control socket are created, print the line “Pluto
1476 initialized” to standard out.
1477 --uniqueids
1479 if this option has been selected, whenever a new ISAKMP SA is
1480 established, any connection with the same Peer ID but a different
1481 Peer IP address is unoriented (causing all its SAs to be deleted).
1482 This helps clean up dangling SAs when a connection is lost and then
1483 regained at another IP address.
1484 --force-busy
1486 if this option has been selected, pluto will be forced to be
1487 "busy". In this state, which happens when there is a Denial of
1488 Service attack, will force pluto to use cookies before accepting
1489 new incoming IKE packets. Cookies are send and required in ikev1
1490 Aggressive Mode and in ikev2. This option is mostly used for
1491 testing purposes, but can be selected by paranoid administrators as
1492 well.
1493 --stderrlog
1495 log goes to standard out {default is to use syslogd(8))
1496 For example
1498 pluto --secretsfile ipsec.secrets --ctlbase pluto.base --ikeport 8500
1500 --nofork --use-nostack --stderrlog
1501 lets one test pluto without using the superuser account.
1503 pluto is willing to produce a prodigious amount of debugging
1505 information. There are several classes of debugging output, and pluto
1506 may be directed to produce a selection of them. All lines of debugging
1507 output are prefixed with “| ” to distinguish them from error messages.
1508 When pluto is invoked, it may be given arguments to specify which
1510 classes to output. The current options are:
1511 --debug-none
1513 disable all debugging
1514 --debug-all
1516 enable all debugging
1517 --debug-raw
1519 show the raw bytes of messages
1520 --debug-crypt
1522 show the encryption and decryption of messages
1523 --debug-parsing
1525 show the structure of input messages
1526 --debug-emitting
1528 show the structure of output messages
1529 --debug-control
1531 show pluto´s decision making
1532 --debug-controlmore
1534 show even more detailed pluto decision making
1535 --debug-lifecycle
1537 [this option is temporary] log more detail of lifecycle of SAs
1538 --debug-klips
1540 show pluto´s interaction with KLIPS
1541 --debug-pfkey
1543 show pluto´s PFKEYinterface communication
1544 --debug-dns
1546 show pluto´s interaction with DNS for KEY and TXT records
1547 --debug-dpd
1549 show pluto´s Dead Peer Detection handling
1550 --debug-natt
1552 show pluto´s NAT Traversal handling
1553 --debug-oppo
1555 show why pluto didn´t find a suitable DNS TXT record to authorize
1556 opportunistic initiation
1557 --debug-oppoinfo
1559 log when connections are initiated due to acquires from the kernel.
1560 This is often useful to know, but can be extremely chatty on a busy
1561 system.
1562 --debug-whackwatch
1564 if set, causes pluto not to release the whack --initiate channel
1565 until the SA is completely up. This will cause the requestor to
1566 possibly wait forever while pluto unsuccessfully negotiates. Used
1567 often in test cases.
1568 --debug-private
1570 allow debugging output with private keys.
1571 The debug form of the whack command will change the selection in a
1573 running pluto. If a connection name is specified, the flags are added
1574 whenever pluto has identified that it is dealing with that connection.
1575 Unfortunately, this is often part way into the operation being
1576 observed.
1577 For example, to start a pluto with a display of the structure of input
1579 and output:
1580 pluto --debug-emitting --debug-parsing
1582 To later change this pluto to only display raw bytes:
1584 whack --debug-raw
1586 Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA
1588 is established. This allows future IPsec SA´s to be negotiated
1589 directly. If one of the IKEs is restarted, the other may try to use the
1590 ISAKMP SA but the new IKE won´t know about it. This can lead to much
1591 confusion. pluto is not yet smart enough to get out of such a mess.
1592 Pluto´s Behaviour When Things Go Wrong
1594 When pluto doesn´t understand or accept a message, it just ignores the
1595 message. It is not yet capable of communicating the problem to the
1596 other IKE daemon (in the future it might use Notifications to
1597 accomplish this in many cases). It does log a diagnostic.
1598 When pluto gets no response from a message, it resends the same message
1600 (a message will be sent at most three times). This is appropriate: UDP
1601 is unreliable.
1602 When pluto gets a message that it has already seen, there are many
1604 cases when it notices and discards it. This too is appropriate for UDP.
1605 Combine these three rules, and you can explain many apparently
1607 mysterious behaviours. In a pluto log, retrying isn´t usually the
1608 interesting event. The critical thing is either earlier (pluto got a
1609 message which it didn´t like and so ignored, so it was still awaiting
1610 an acceptable message and got impatient) or on the other system (pluto
1611 didn´t send a reply because it wasn´t happy with the previous message).
1612 Notes
1614 If pluto is compiled without -DKLIPS, it negotiates Security
1615 Associations but never ask the kernel to put them in place and never
1616 makes routing changes. This allows pluto to be tested on systems
1617 without KLIPS, but makes it rather useless.
1618 Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the
1620 SA. The IKE protocol lets the destination of the SA choose the SPI. The
1621 range 0 to 0xFF is reserved for IANA. Pluto also avoids choosing an
1622 SPI in the range 0x100 to 0xFFF, leaving these SPIs free for manual
1623 keying. Remember that the peer, if not pluto, may well chose SPIs in
1624 this range.
1625 Policies
1627 This catalogue of policies may be of use when trying to configure Pluto
1628 and another IKE implementation to interoperate.
1629 In Phase 1, only Main Mode is supported. We are not sure that
1631 Aggressive Mode is secure. For one thing, it does not support identity
1632 protection. It may allow more severe Denial Of Service attacks.
1633 No Informational Exchanges are supported. These are optional and since
1635 their delivery is not assured, they must not matter. It is the case
1636 that some IKE implementations won´t interoperate without Informational
1637 Exchanges, but we feel they are broken.
1638 No Informational Payloads are supported. These are optional, but
1640 useful. It is of concern that these payloads are not authenticated in
1641 Phase 1, nor in those Phase 2 messages authenticated with HASH(3).
1642 ·
1644 Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) are
1645 supported. Group MODP768 (1) is not supported because it is too
1646 weak.
1647 ·
1649 Host authentication can be done by RSA Signatures or Pre-Shared
1650 Secrets.
1651 ·
1653 3DES CBC (Cypher Block Chaining mode) is the only encryption
1654 supported, both for ISAKMP SAs and IPSEC SAs.
1655 ·
1657 MD5 and SHA1 hashing are supported for packet authentication in
1658 both kinds of SAs.
1659 ·
1661 The ESP, AH, or AH plus ESP are supported. If, and only if, AH and
1662 ESP are combined, the ESP need not have its own authentication
1663 component. The selection is controlled by the --encrypt and
1664 --authenticate flags.
1665 ·
1667 Each of these may be combined with IPCOMP Deflate compression, but
1668 only if the potential connection specifies compression and only if
1669 KLIPS is configured with IPCOMP support.
1670 ·
1672 The IPSEC SAs may be tunnel or transport mode, where appropriate.
1673 The --tunnel flag controls this when pluto is initiating.
1674 ·
1676 When responding to an ISAKMP SA proposal, the maximum acceptable
1677 lifetime is eight hours. The default is one hour. There is no
1678 minimum. The --ikelifetime flag controls this when pluto is
1679 initiating.
1680 ·
1682 When responding to an IPSEC SA proposal, the maximum acceptable
1683 lifetime is one day. The default is eight hours. There is no
1684 minimum. The --ipseclifetime flag controls this when pluto is
1685 initiating.
1686 ·
1688 PFS is acceptable, and will be proposed if the --pfs flag was
1689 specified. The DH group proposed will be the same as negotiated for
1690 Phase 1.
1691
1693 Pluto responds to SIGHUP by issuing a suggestion that ``whack
1694 --listen´´ might have been intended.
1695 Pluto exits when it receives SIGTERM.
1697
1699 pluto normally forks a daemon process, so the exit status is normally a
1700 very preliminary result.
1701 0
1703 means that all is OK so far.
1704 1
1706 means that something was wrong.
1707 10
1709 means that the lock file already exists.
1710 If whack detects a problem, it will return an exit status of 1. If it
1712 received progress messages from pluto, it returns as status the value
1713 of the numeric prefix from the last such message that was not a message
1714 sent to syslog or a comment (but the prefix for success is treated as
1715 0). Otherwise, the exit status is 0.
1716
1718 /var/run/pluto/pluto.pid
1719 /var/run/pluto/pluto.ctl
1721 /etc/ipsec.secrets
1723 /dev/urandom
1725
1727 IPSEC_EXECDIR
1728 IPSECmyid
1730 PLUTO_CORE_DIR
1732
1734 The rest of the Libreswan distribution, in particular ipsec(8).
1735 ipsec_auto(8) is designed to make using pluto more pleasant. Use it!
1737 ipsec.secrets(5) describes the format of the secrets file.
1739 ipsec_atoaddr(3), part of the Libreswan distribution, describes the
1741 forms that IP addresses may take. ipsec_atosubnet(3), part of the
1742 Libreswan distribution, describes the forms that subnet specifications.
1743 For more information on IPsec, the mailing list, and the relevant
1745 documents, see:
1746 https://datatracker.ietf.org/wg/ipsecme/charter/
1748 At the time of writing, the most relevant IETF RFCs are:
1750 RFC5996 Internet Key Exchange Protocol Version 2 (IKEv2)
1752 The Libreswan web site <https://libreswan.org> and the mailing lists
1754 described there.
1755
1757 This code is released under the GPL terms. See the accompanying files
1758 COPYING and CREDITS.* for more details.
1759 This software was originally written for the FreeS/WAN project
1761 <http://www.freeswan.org>, founded by John Gilmore and managed by Hugh
1762 Daniel. It was written by Angelos D. Keromytis
1763 (angelos@dsl.cis.upenn.edu), in May/June 1997, in Athens, Greece.
1764 Thanks go to John Ioannidis for his help.
1765 FreeS/WAN´s Pluto was developed/maintained from 2000-2004 by D. Hugh
1767 Redelmeier (hugh@mimosa.com), in Canada. The regulations of Greece and
1768 Canada allow the code to be freely redistributable.
1769 Richard Guy Briggs <rgb@conscoop.ottawa.on.ca> was the main resource on
1771 KLIPS development
1772 IKE version 2 was initially written by Michael Richardson, Antony
1774 Antony and Paul Wouters. It has since been extended by Avesh Agarwal,
1775 D. Hugh Redelmeier, Matt Rogers, Antony Antony and Paul Wouters.
1776 From 2003 onwards, the code was developed and maintained by The
1778 Openswan Project by developers worldwide and distributed from The
1779 Netherland and Finland. Due to a lawsuit by Xelerance over the
1780 trademark, the project was forced to rename itself and the code to The
1781 Libreswan Project in 2012.
1782 See further: the CHANGES/CREDITS files in the main directory and the
1784 doc/ directory.
1785
1787 Please see <https://bugs.libreswan.org> for a list of currently known
1788 bugs and missing features.
1789 Bugs should be reported to the <swan-dev@lists.libreswan.org> mailing
1791 list.
1792
1794 Paul Wouters
1795 placeholder to suppress warning
1796libreswan 10/04/2017 IPSEC_PLUTO(8)