1 Content-type: text/html
3 <HTML><HEAD><TITLE>Manpage of IPSEC_PLUTO</TITLE>
6 Section: Maintenance Commands (8)<BR>Updated: 28 March 1999<BR><A HREF="#index">Index</A>
7 <A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
9 <A NAME="lbAB"> </A>
12 ipsec pluto - IPsec IKE keying daemon
15 ipsec whack - control interface for IPSEC keying daemon
16 <A NAME="lbAC"> </A>
27 [--optionsfrom </B><I>filename</I>]
32 [--ikeport <I>portnumber</I>]
33 [--ctlbase <I>path</I>]
34 [--secretsfile <I>secrets-file</I>]
52 --name </B><I>connection-name</I>
55 [--id <I>id</I>] [--host <I>ip-address</I>]
56 [--ikeport <I>port-number</I>]
57 [--nexthop <I>ip-address</I>]
58 [--client <I>subnet</I>]
59 [--updown <I>updown</I>]
66 [--host <I>ip-address</I>]
67 [--ikeport <I>port-number</I>]
68 [--nexthop <I>ip-address</I>]
69 [--client <I>subnet</I>]
70 [--updown <I>updown</I>]
84 [--ikelifetime <I>seconds</I>]
85 [--ipseclifetime <I>seconds</I>]
86 [--rekeymargin <I>seconds</I>]
87 [--rekeyfuzz <I>percentage</I>]
88 [--keyingtries <I>count</I>]
90 [--ctlbase <I>path</I>]
91 [--optionsfrom <I>filename</I>]
92 [--label <I>string</I>]
96 --keyid </B><I>id</I>
97 [--pubkeyrsa <I>key</I>]
98 [--ctlbase <I>path</I>]
99 [--optionsfrom <I>filename</I>]
100 [--label <I>string</I>]
105 [--ctlbase </B><I>path</I>]
106 [--optionsfrom <I>filename</I>]
107 [--label <I>string</I>]
112 --name </B><I>connection-name</I>
113 [--ctlbase <I>path</I>]
114 [--optionsfrom <I>filename</I>]
115 [--label <I>string</I>]
119 --initiate|--terminate
120 --name </B><I>connection-name</I>
122 [--ctlbase <I>path</I>]
123 [--optionsfrom <I>filename</I>]
124 [--label <I>string</I>]
129 --name </B><I>connection-name</I>
130 [--ctlbase <I>path</I>]
131 [--optionsfrom <I>filename</I>]
132 [--label <I>string</I>]
136 [--name </B><I>connection-name</I>]
146 [--ctlbase <I>path</I>]
147 [--optionsfrom <I>filename</I>]
148 [--label <I>string</I>]
153 [--ctlbase </B><I>path</I>]
154 [--optionsfrom <I>filename</I>]
155 [--label <I>string</I>]
160 [--ctlbase </B><I>path</I>]
161 [--optionsfrom <I>filename</I>]
162 [--label <I>string</I>]
167 <A NAME="lbAD"> </A>
172 is an IKE (``IPsec Key Exchange'') daemon.
175 is an auxiliary program to allow requests to be made to a running
182 is used to automatically build shared ``security associations'' on a
183 system that has IPsec, the secure IP protocol.
187 can eliminate much of the work of manual keying.
189 secure transmission of packets is the responsibility of other parts of
193 the companion implementation of IPsec).
194 <I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8) provides a more convenient interface to
195 <B>pluto</B> and <B>whack</B>.
196 <A NAME="lbAE"> </A>
201 A <I>Security Association</I> (<I>SA</I>) is an agreement between two network nodes on
202 how to process certain traffic between them. This processing involves
203 encapsulation, authentication, encryption, or compression.
206 IKE can be deployed on a network node to negotiate Security
207 Associations for that node. These IKE implementations can only
208 negotiate with other IKE implementations, so IKE must be on each node
209 that is to be an endpoint of an IKE-negotiated Security Association.
210 No other nodes need to be running IKE.
213 An IKE instance (i.e. an IKE implementation on a particular network
214 node) communicates with another IKE instance using UDP IP packets, so
215 there must be a route between the nodes in each direction.
218 The negotiation of Security Associations requires a number of choices
219 that involve tradeoffs between security, convenience, trust, and
220 efficiency. These are policy issues and are normally specified to the
221 IKE instance by the system administrator.
224 IKE deals with two kinds of Security Associations. The first part of
225 a negotiation between IKE instances is to build an ISAKMP SA. An
226 ISAKMP SA is used to protect communication between the two IKEs.
227 IPsec SAs can then be built by the IKEs - these are used to carry
228 protected IP traffic between the systems.
231 The negotiation of the ISAKMP SA is known as Phase 1. In theory,
232 Phase 1 can be accomplished by a couple of different exchange types,
233 but we only implement one called Main Mode (we don't implement
237 Any negotiation under the protection of an ISAKMP SA, including the
238 negotiation of IPsec SAs, is part of Phase 2. The exchange type
239 that we use to negotiate an IPsec SA is called Quick Mode.
242 IKE instances must be able to authenticate each other as part of their
243 negotiation of an ISAKMP SA. This can be done by several mechanisms
244 described in the draft standards.
247 IKE negotiation can be initiated by any instance with any other. If
248 both can find an agreeable set of characteristics for a Security
249 Association, and both recognize each others authenticity, they can set
250 up a Security Association. The standards do not specify what causes
251 an IKE instance to initiate a negotiation.
254 In summary, an IKE instance is prepared to automate the management of
255 Security Associations in an IPsec environment, but a number of issues
256 are considered policy and are left in the system administrator's hands.
257 <A NAME="lbAF"> </A>
262 <B>pluto</B> is an implementation of IKE. It runs as a daemon on a network
263 node. Currently, this network node must be a LINUX system running the
264 <B>KLIPS</B> implementation of IPsec.
267 <B>pluto</B> only implements a subset of IKE. This is enough for it to
268 interoperate with other instances of <B>pluto</B>, and many other IKE
269 implementations. We are working on implementing more of IKE.
272 The policy for acceptable characteristics for Security Associations is
273 mostly hardwired into the code of <B>pluto</B> (spdb.c). Eventually
274 this will be moved into a security policy database with reasonable
275 expressive power and more convenience.
278 <B>pluto</B> uses shared secrets or RSA signatures to authenticate
279 peers with whom it is negotiating. In future other techniques will be
283 <B>pluto</B> initiates negotiation of a Security Association when it is
284 manually prodded: the program <B>whack</B> is run to trigger this.
285 Eventually, more convenient and useful mechanisms will be implemented.
288 <B>pluto</B> implements ISAKMP SAs itself. After it has negotiated the
289 characteristics of an IPsec SA, it directs <B>KLIPS</B> to implement it.
290 It also issues <I><A HREF="route.8.html">route</A></I>(8) commands to direct messages through <B>KLIPS</B>.
293 When <B>pluto</B> shuts down, it closes all Security Associations.
294 <A NAME="lbAG"> </A>
295 <H3>Before Running Pluto</H3>
299 <B>pluto</B> runs as a daemon with userid root. Before running it, a few
300 things must be set up.
303 <B>pluto</B> requires <B>KLIPS</B>, the FreeS/WAN implementation of IPsec.
304 All of the components of <B>KLIPS</B> and <B>pluto</B> should be installed.
307 <B>pluto</B> supports multiple public networks (that is, networks
308 that are considered insecure and thus need to have their traffic
309 encrypted or authenticated). It discovers the
310 public interfaces to use by looking at all interfaces that are
311 configured. It does this only when <B>whack</B> tells it to --listen,
312 so the interfaces must be configured by then. Each interface with a name of the form
313 <B>ipsec</B>[<B>0</B>-<B>9</B>] is taken as a <B>KLIPS</B> virtual public interface.
314 Another network interface with the same IP address (there should be only
315 one) is taken as the corresponding real public
316 interface. <I><A HREF="ifconfig.8.html">ifconfig</A></I>(8) with the <B>-a</B> flag will show
317 the name and status of each network interface.
320 <B>pluto</B> requires a database of preshared secrets and RSA private keys.
321 This is described in the
322 <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5).
324 <B>pluto</B> is told of RSA public keys via <B>whack</B> commands.
325 <A NAME="lbAH"> </A>
326 <H3>Setting up <B>KLIPS</B> for <B>pluto</B></H3>
330 The most basic network topology that <B>pluto</B> supports has two security
331 gateways negotiating on behalf of client subnets. The diagram of RGB's
332 testbed is a good example (see <I>klips/doc/rgb_setup.txt</I>).
335 The file <I>INSTALL</I> in the base directory of this distribution
336 explains how to start setting up the whole system, including <B>KLIPS</B>.
339 Make sure that the security gateways have routes to each other. This
340 is usually covered by the default route, but may require issuing
341 <I><A HREF="route.8.html">route</A></I>(8)
343 commands. The route must go through a particular ethernet
344 interface (we will assume it is <I>eth0</I>, but it need not be). The
345 interface that connects the security gateway to its client must be a
349 It is necessary to issue a
350 <I><A HREF="ipsec_tncfg.8.html">ipsec_tncfg</A></I>(8)
352 command on each gateway. The required command is:
354 ipsec tncfg --attach --virtual ipsec0 --physical eth0
356 A command to set up the ipsec0 virtual interface will also need to be
357 run. It will have the same parameters as the command used to set up
358 the physical interface to which it has just been connected using
359 <I><A HREF="ipsec_tncfg.8.html">ipsec_tncfg</A></I>(8).
361 <A NAME="lbAI"> </A>
362 <H3>ipsec.secrets file</H3>
366 A <B>pluto</B> daemon and another IKE daemon (for example, another instance
367 of <B>pluto</B>) must convince each other that they are who they are supposed
368 to be before any negotiation can succeed. This authentication is
369 accomplished by using either secrets that have been shared beforehand
370 (manually) or by using RSA signatures. There are other techniques,
371 but they have not been implemented in <B>pluto</B>.
374 The file <I>/etc/ipsec.secrets</I> is used to keep preshared secret keys
375 and RSA private keys for
376 authentication with other IKE daemons. For debugging, there is an
377 argument to the <B>pluto</B> command to use a different file.
378 This file is described in
379 <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5).
381 <A NAME="lbAJ"> </A>
382 <H3>Running Pluto</H3>
386 To fire up the daemon, just type <B>pluto</B> (be sure to be running as
388 The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons.
389 <B>pluto</B> must be run by the superuser to be able to use the UDP 500 port.
392 <B>pluto</B> attempts to create a lockfile with the name
393 <I>/var/run/pluto.pid</I>. If the lockfile cannot be created,
394 <B>pluto</B> exits - this prevents multiple <B>pluto</B>s from
395 competing Any ``leftover'' lockfile must be removed before
396 <B>pluto</B> will run. <B>pluto</B> writes its pid into this file so
397 that scripts can find it. This lock will not function properly if it
398 is on an NFS volume (but sharing locks on multiple machines doesn't
402 <B>pluto</B> then forks and the parent exits. This is the conventional
403 ``daemon fork''. It can make debugging awkward, so there is an option
404 to suppress this fork.
407 All logging, including diagnostics, is sent to
408 <I><A HREF="syslog.3.html">syslog</A></I>(3);
410 it decides where to put these messages (possibly in /var/log/secure).
411 Since this too can make debugging awkward, there is an option to
412 steer logging to stderr.
415 Once <B>pluto</B> is started, it waits for requests from <B>whack</B>.
416 <A NAME="lbAK"> </A>
417 <H3>Pluto's Internal State</H3>
421 To understand how to use <B>pluto</B>, it is helpful to understand a little
422 about its internal state. Furthermore, the terminology is needed to decipher
423 some of the diagnostic messages.
426 The <I>(potential) connection</I> database describes attributes of a
427 connection. These include the IP addresses of the hosts and client
428 subnets and the security characteristics desired. <B>pluto</B>
429 requires this information (simply called a connection) before it can
430 respond to a request to build an SA. Each connection is given a name
431 when it is created, and all references are made using this name.
434 During the IKE exchange to build an SA, the information about the
435 negotiation is represented in a <I>state object</I>. Each state object
436 reflects how far the negotiation has reached. Once the negotiation is
437 complete and the SA established, the state object remains to represent
438 the SA. When the SA is terminated, the state object is discarded.
439 Each State object is given a serial number and this is used to refer
440 to the state objects in logged messages.
443 Each state object corresponds to a connection and can be thought of
444 as an instantiation of that connection.
445 At any particular time, there may be any number of state objects
446 corresponding to a particular connection.
447 Often there is one representing an ISAKMP SA and another representing
451 <B>KLIPS</B> hooks into the routing code in a LINUX kernel.
452 Traffic to be processed by an IPsec SA must be directed through
453 <B>KLIPS</B> by routing commands. Furthermore, the processing to be
454 done is specified by <I>ipsec <A HREF="eroute.8.html">eroute</A>(8)</I> commands.
455 <B>pluto</B> takes the responsibility of managing both of these special
459 Each connection may be routed, and must be while it has an IPsec SA.
460 The connection specifies the characteristics of the route: the
461 interface on this machine, the ``gateway'' (the nexthop),
462 and the peer's client subnet. Two
463 connections may not be simultaneously routed if they are for the same
464 peer's client subnet but use different interfaces or gateways
465 (<B>pluto</B>'s logic does not reflect any advanced routing capabilities).
468 Each eroute is associated with the state object for an IPsec SA
469 because it has the particular characteristics of the SA.
470 Two eroutes conflict if they specify the identical local
471 and remote clients (unlike for routes, the local clients are
475 When <B>pluto</B> needs to install a route for a connection,
476 it must make sure that no conflicting route is in use. If another
477 connection has a conflicting route, that route will be taken down, as long
478 as there is no IPsec SA instantiating that connection.
479 If there is such an IPsec SA, the attempt to install a route will fail.
482 There is an exception. If <B>pluto</B>, as Responder, needs to install
483 a route to a fixed client subnet for a connection, and there is
484 already a conflicting route, then the SAs using the route are deleted
485 to make room for the new SAs. The rationale is that the new
486 connection is probably more current. The need for this usually is a
487 product of Road Warrior connections (these are explained later; they
488 cannot be used to initiate).
491 When <B>pluto</B> needs to install an eroute for an IPsec SA (for a
492 state object), first the state object's connection must be routed (if
493 this cannot be done, the eroute and SA will not be installed).
494 If a conflicting eroute is already in place for another connection,
495 the eroute and SA will not be installed (but note that the routing
496 exception mentioned above may have already deleted potentially conflicting SAs).
498 SA for the same connection already has an eroute, all its outgoing traffic
499 is taken over by the new eroute. The incoming traffic will still be
500 processed. This characteristic is exploited during rekeying.
503 All of these routing characteristics are expected change when
504 <B>KLIPS</B> is modified to use the firewall hooks in the LINUX 2.4.x
506 <A NAME="lbAL"> </A>
511 <B>whack</B> is used to command a running <B>pluto</B>.
512 <B>whack</B> uses a UNIX domain socket to speak to <B>pluto</B>
513 (by default, <I>/var/pluto.ctl</I>).
516 <B>whack</B> has an intricate argument syntax.
517 This syntax allows many different functions to be specified.
518 The help form shows the usage or version information.
519 The connection form gives <B>pluto</B> a description of a potential connection.
520 The public key form informs <B>pluto</B> of the RSA public key for a potential peer.
521 The delete form deletes a connection description and all SAs corresponding
523 The listen form tells <B>pluto</B> to start or stop listening on the public interfaces
524 for IKE requests from peers.
525 The route form tells <B>pluto</B> to set up routing for a connection;
526 the unroute form undoes this.
527 The initiate form tells <B>pluto</B> to negotiate an SA corresponding to a connection.
528 The terminate form tells <B>pluto</B> to remove all SAs corresponding to a connection,
529 including those being negotiated.
530 The status form displays the <B>pluto</B>'s internal state.
531 The debug form tells <B>pluto</B> to change the selection of debugging output
532 ``on the fly''. The shutdown form tells
533 <B>pluto</B> to shut down, deleting all SAs.
536 Most options are specific to one of the forms, and will be described
537 with that form. There are three options that apply to all forms.
539 <DT><B>--ctlbase</B> <I>path</I><DD>
540 <I>path</I>.ctl is used as the UNIX domain socket for talking
542 This option facilitates debugging.
543 <DT><B>--optionsfrom</B> <I>filename</I><DD>
544 adds the contents of the file to the argument list.
545 <DT><B>--label</B> <I>string</I><DD>
546 adds the string to all error messages generated by <B>whack</B>.
550 The help form of <B>whack</B> is self-explanatory.
552 <DT><B>--help</B><DD>
553 display the usage message.
554 <DT><B>--version</B><DD>
555 display the version of <B>whack</B>.
559 The connection form describes a potential connection to <B>pluto</B>.
560 <B>pluto</B> needs to know what connections can and should be negotiated.
561 When <B>pluto</B> is the initiator, it needs to know what to propose.
562 When <B>pluto</B> is the responder, it needs to know enough to decide whether
563 is is willing to set up the proposed connection.
566 The description of a potential connection can specify a large number
567 of details. Each connection has a unique name. This name will appear
568 in a updown shell command, so it should not contain punctuation
569 that would make the command ill-formed.
571 <DT><B>--name</B> <I>connection-name</I><DD>
576 circuit is symmetric, so to save space here is half a picture:
578 client_subnet<-->host:ikeport<-->nexthop<---
580 A similar trick is used in the flags. The same flag names are used for
581 both ends. Those before the <B>--to</B> flag describe the left side
582 and those afterwards describe the right side. When <B>pluto</B> attempts
583 to use the connection, it decides whether it is the left side or the right
584 side of the connection, based on the IP numbers of its interfaces.
586 <DT><B>--id</B> <I>id</I><DD>
587 the identity of the end. Currently, this can be an IP address (specified
588 as dotted quad or as a Fully Qualified Domain Name, which will be resolved
589 immediately) or as a Fully Qualified Domain Name itself (prefixed by ``@''
590 to signify that it should not be resolved), or as <A HREF="mailto:user@FQDN">user@FQDN</A>.
591 <B>pluto</B> only authenticates the identity, and does not use it for
592 addressing, so, for example, an IP address need not be the one to which
593 packets are to be sent. If the option is absent, the
594 identity defaults to the IP address specified by <B>--host</B>.
596 <DT><B>--host</B> <I>ip-address</I><DD>
597 <DT><B>--host</B> <B>%any</B><DD>
598 <DT><B>--host</B> <B>%opportunistic</B><DD>
599 the IP address of the end (generally the public interface).
600 If <B>pluto</B> is to act as a responder
601 for IKE negotiations initiated from unknown IP addresses (the
602 ``Road Warrior'' case), the
603 IP address should be specified as <B>%any</B> (currently,
604 the obsolete notation <B>0.0.0.0</B> is also accepted for this).
605 If <B>pluto</B> is to opportunistically initiate the connection,
606 use <B>%opportunistic</B>
607 <DT><B>--ikeport</B> <I>port-number</I><DD>
608 the UDP port that IKE listens to on that host. The default is 500.
609 (<B>pluto</B> on this machine uses the port specified by its own command
610 line argument, so this only affects where <B>pluto</B> sends messages.)
611 <DT><B>--nexthop</B> <I>ip-address</I><DD>
612 where to route packets for the peer's client (presumably for the peer too,
613 but it will not be used for this).
614 When <B>pluto</B> installs an IPsec SA, it issues a route command.
615 It uses the nexthop as the gateway.
616 The default is the peer's IP address (this can be explicitly written as
617 <B>%direct</B>; the obsolete notation <B>0.0.0.0</B> is accepted).
618 This option is necessary if <B>pluto</B>'s host's interface used for sending
619 packets to the peer is neither point-to-point nor directly connected to the
621 <DT><B>--client</B> <I>subnet</I><DD>
622 the subnet for which the IPsec traffic will be destined. If not specified,
623 the host will be the client.
624 The subnet can be specified in any of the forms supported by <I><A HREF="ipsec_atosubnet.3.html">ipsec_atosubnet</A></I>(3).
625 The general form is <I>address</I>/<I>mask</I>. The <I>address</I> can be either
626 a domain name or four decimal numbers (specifying octets) separated by dots.
627 The most convenient form of the <I>mask</I> is a decimal integer, specifying
628 the number of leading one bits in the mask. So, for example, 10.0.0.0/8
629 would specify the class A network ``Net 10''.
630 <DT><B>--updown</B> <I>updown</I><DD>
631 specifies an external shell command to be run whenever <B>pluto</B>
632 brings up or down a connection.
633 The script is used to build a shell command, so it may contain positional
634 parameters, but ought not to have punctuation that would cause the
635 resulting command to be ill-formed.
636 The default is <I>ipsec _updown</I>.
638 separates the specification of the left and right ends of the connection.
642 The potential connection description also specifies characteristics of
643 rekeying and security.
646 Propose and allow preshared secret authentication for IKE peers. This authentication
647 requires that each side use the same secret. May be combined with <B>--rsasig</B>.
648 <B>pluto</B> supported for a long time.
649 <DT><B>--rsasig</B><DD>
650 Propose and allow RSA signatures for authentication of IKE peers. This authentication
651 requires that each side have have a private key of its own and know the
652 public key of its peer. May be combined with <B>--psk</B>.
656 If neither <B>--rsasig</B> nor <B>--psk</B> is specified, the
657 initiator will default to proposing those for which it has the required
658 keying material. The responder defaults similarly, but does not know
659 the identity of the initiator (except for its IP address), so it is
660 willing to accept RSA Sig if it is proposed (PSK cannot use the Identity
661 payload, so the responder does know if it can handle PSK).
663 <DT><B>--encrypt</B><DD>
664 All proposed or accepted IPsec SAs will include non-null ESP.
665 The actual choices of transforms are wired into <B>pluto</B>.
666 <DT><B>--authenticate</B><DD>
667 All proposed IPsec SAs will include AH.
668 All accepted IPsec SAs will include AH or ESP with authentication.
669 The actual choices of transforms are wired into <B>pluto</B>.
670 Note that this has nothing to do with IKE authentication.
671 <DT><B>--compress</B><DD>
672 All proposed IPsec SAs will include IPCOMP (compression).
673 This will be ignored if KLIPS is not configured with IPCOMP support.
674 <DT><B>--tunnel</B><DD>
675 the IPsec SA should use tunneling. Implicit if the SA is for clients.
676 Must only be used with <B>--authenticate</B> or <B>--encrypt</B>.
677 <DT><B>--ipv4</B><DD>
678 The host addresses will be interpreted as IPv4 addresses. This is the
679 default. Note that for a connection, all host addresses must be of
680 the same Address Family (IPv4 and IPv6 use different Address Families).
681 <DT><B>--ipv6</B><DD>
682 The host addresses (including nexthop) will be interpreted as IPv6 addresses.
683 Note that for a connection, all host addresses must be of
684 the same Address Family (IPv4 and IPv6 use different Address Families).
685 <DT><B>--tunnelipv4</B><DD>
686 The client addresses will be interpreted as IPv4 addresses. The default is
687 to match what the host will be. This does not imply <B>--tunnel</B> so the
688 flag can be safely used when no tunnel is actually specified.
689 Note that for a connection, all tunnel addresses must be of the same
691 <DT><B>--tunnelipv6</B><DD>
692 The client addresses will be interpreted as IPv6 addresses. The default is
693 to match what the host will be. This does not imply <B>--tunnel</B> so the
694 flag can be safely used when no tunnel is actually specified.
695 Note that for a connection, all tunnel addresses must be of the same
698 There should be Perfect Forward Secrecy - new keying material will
699 be generated for each IPsec SA rather than being derived from the ISAKMP
701 Since the group to be used cannot be negotiated (a dubious feature of the
702 standard), <B>pluto</B> will propose the same group that was used during Phase 1.
703 We don't implement a stronger form of PFS which would require that the
704 ISAKMP SA be deleted after the IPSEC SA is negotiated.
708 If none of the <B>--encrypt</B>, <B>--authenticate</B>, <B>--compress</B>,
709 or <B>--pfs</B> flags is given, the initiating the connection will
710 only build an ISAKMP SA. For such a connection, client subnets have
711 no meaning and must not be specified.
714 More work is needed to allow for flexible policies. Currently
715 policy is hardwired in the source file spdb.c. The ISAKMP SAs may use
716 Oakley groups MODP1024 and MODP1536; 3DES encryption; SHA1-96
717 and MD5-96 authentication. The IPsec SAs may use 3DES and
718 MD5-96 or SHA1-96 for ESP, or just MD5-96 or SHA1-96 for AH.
719 IPCOMP Compression is always Deflate.
721 <DT><B>--ikelifetime</B> <I>seconds</I><DD>
722 how long <B>pluto</B> will propose that an ISAKMP SA be allowed to live.
723 The default is 3600 (one hour) and the maximum is 28800 (8 hours).
724 This option will not affect what is accepted.
725 <B>pluto</B> will reject proposals that exceed the maximum.
726 <DT><B>--ipseclifetime</B> <I>seconds</I><DD>
727 how long <B>pluto</B> will propose that an IPsec SA be allowed to live.
728 The default is 28800 (eight hours) and the maximum is 86400 (one day).
729 This option will not affect what is accepted.
730 <B>pluto</B> will reject proposals that exceed the maximum.
731 <DT><B>--rekeymargin</B> <I>seconds</I><DD>
732 how long before an SA's expiration should <B>pluto</B> try to negotiate
733 a replacement SA. This will only happen if <B>pluto</B> was the initiator.
734 The default is 540 (nine minutes).
735 <DT><B>--rekeyfuzz</B> <I>percentage</I><DD>
736 maximum size of random component to add to rekeymargin, expressed as
737 a percentage of rekeymargin. <B>pluto</B> will select a delay uniformly
738 distributed within this range. By default, the percentage will be 100.
739 If greater determinism is desired, specify 0. It may be appropriate
740 for the percentage to be much larger than 100.
741 <DT><B>--keyingtries</B> <I>count</I><DD>
742 how many times <B>pluto</B> should try to negotiate an SA,
743 either for the first time or for rekeying.
744 A value of 0 is interpreted as a very large number: never give up.
745 The default is three.
746 <DT><B>--delete</B><DD>
747 when used in the connection form, it causes any previous connection
748 with this name to be deleted before this one is added. Unlike a
749 normal delete, no diagnostic is produced if there was no previous
750 connection to delete. Any routing in place for the connection is undone.
754 The delete form deletes a named connection description and any
755 SAs established or negotiations initiated using this connection.
756 Any routing in place for the connection is undone.
758 <DT><B>--delete</B><DD>
759 <DT><B>--name</B> <I>connection-name</I><DD>
763 The route form of the <B>whack</B> command tells <B>pluto</B> to set up
764 routing for a connection.
765 Although like a traditional route, it uses an ipsec device as a
767 Once routing is set up, no packets will be
768 sent ``in the clear'' to the peer's client specified in the connection.
769 A TRAP shunt eroute will be installed; if outbound traffic is caught,
770 Pluto will initiate the connection.
771 An explicit <B>whack</B> route is not always needed: if it hasn't been
772 done when an IPsec SA is being installed, one will be automatically attempted.
775 When a routing is attempted for a connection, there must not already
776 be a routing for a different connection with the same subnet but different
777 interface or destination, or if
778 there is, it must not be being used by an IPsec SA. Otherwise the
781 <DT><B>--route</B><DD>
782 <DT><B>--name</B> <I>connection-name</I><DD>
786 The unroute form of the <B>whack</B> command tells <B>pluto</B> to undo
787 a routing. <B>pluto</B> will refuse if an IPsec SA is using the connection.
788 If another connection is sharing the same routing, it will be left in place.
789 Without a routing, packets will be sent without encryption or authentication.
791 <DT><B>--unroute</B><DD>
792 <DT><B>--name</B> <I>connection-name</I><DD>
796 The initiate form tells <B>pluto</B> to initiate a negotiation with another
797 <B>pluto</B> (or other IKE daemon) according to the named connection.
798 Initiation requires a route that <B>--route</B> would provide;
799 if none is in place at the time an IPsec SA is being installed,
800 <B>pluto</B> attempts to set one up.
802 <DT><B>--initiate</B><DD>
803 <DT><B>--name</B> <I>connection-name</I><DD>
804 <DT><B>--asynchronous<DD>
808 The initiate form of the whack</B> command will relay back from
809 <B>pluto</B> status information via the UNIX domain socket (unless
810 --asynchronous is specified). The status information is meant to
811 look a bit like that from <B>FTP</B>. Currently <B>whack</B> simply
812 copies this to stderr. When the request is finished (eg. the SAs are
813 established or <B>pluto</B> gives up), <B>pluto</B> closes the channel,
814 causing <B>whack</B> to terminate.
817 The terminate form tells <B>pluto</B> to delete any SAs that use the specified
818 connection and to stop any negotiations in process.
819 It does not prevent new negotiations from starting (the delete form
822 <DT><B>--terminate</B><DD>
823 <DT><B>--name</B> <I>connection-name</I><DD>
827 The public key for informs <B>pluto</B> of the RSA public key for a potential peer.
828 Private keys must be kept secret, so they are kept in
829 <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5).
832 <DT><B>--keyid </B><I>id</I><DD>
833 specififies the identity of the peer for which a public key should be used.
834 Its form is identical to the identity in the connection.
835 If no public key is specified, <B>pluto</B> attempts to find a KEY record
836 from DNS for the id (if a FQDN) or through reverse lookup (if an IP address).
837 Note that there several interesting ways in which this is not secure.
838 <DT><B>--pubkeyrsa </B><I>key</I><DD>
839 specifies the value of the RSA public key. It is a sequence of bytes
840 as described in RFC 2537 ``RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)''.
841 It is denoted in a way suitable for <I><A HREF="ipsec_atodata.3.html">ipsec_atodata</A></I>(3).
842 For example, a base 64 numeral starts with 0s.
846 The listen form tells <B>pluto</B> to start listening for IKE requests
847 on its public interfaces. To avoid race conditions, it is normal to
848 load the appropriate connections into <B>pluto</B> before allowing it
849 to listen. If <B>pluto</B> isn't listening, it is pointless to
850 initiate negotiations, so it will refuse requests to do so. Whenever
851 the listen form is used, <B>pluto</B> looks for public interfaces and
852 will notice when new ones have been added and when old ones have been
853 removed. This is also the trigger for <B>pluto</B> to read the
854 <I>ipsec.secrets</I> file. So listen may useful more than once.
856 <DT><B>--listen</B><DD>
857 start listening for IKE traffic on public interfaces.
858 <DT><B>--unlisten</B><DD>
859 stop listening for IKE traffic on public interfaces.
863 The status form will display information about the internal state of
864 <B>pluto</B>: information about each potential connection and about
867 <DT><B>--status</B><DD>
871 The shutdown form is the proper way to shut down <B>pluto</B>.
872 It will tear down the SAs on this machine that <B>pluto</B> has negotiated.
873 It does not inform its peers, so the SAs on their machines remain.
875 <DT><B>--shutdown</B><DD>
877 <A NAME="lbAM"> </A>
882 It would be normal to start <B>pluto</B> in one of the system initialization
883 scripts. It needs to be run by the superuser. Generally, no arguments are needed.
884 To run in manually, the superuser can simply type
886 ipsec pluto
888 The command will immediately return, but a <B>pluto</B> process will be left
889 running, waiting for requests from <B>whack</B> or a peer.
892 Using <B>whack</B>, several potential connections would be described:
896 ipsec whack --name silly
897 --host 127.0.0.1 --to --host 127.0.0.2
898 --ikelifetime 900 --ipseclifetime 800 --keyingtries 3
903 <DD>Since this silly connection description specifies neither encryption,
904 authentication, nor tunneling, it could only be used to establish
909 ipsec whack --name secret --host 10.0.0.1 --client 10.0.1.0/24
910 --to --host 10.0.0.2 --client 10.0.2.0/24
916 <DD>This is something that must be done on both sides. If the other
917 side is <B>pluto</B>, the same <B>whack</B> command could be used on it
918 (the command syntax is designed to not distinguish which end is ours).
921 Now that the connections are specified, <B>pluto</B> is ready to handle
922 requests and replies via the public interfaces. We must tell it to discover
923 those interfaces and start accepting messages from peers:
925 ipsec whack --listen
928 If we don't immediately wish to bring up a secure connection between
929 the two clients, we might wish to prevent insecure traffic.
930 The routing form asks <B>pluto</B> to cause the packets sent from
931 our client to the peer's client to be routed through the ipsec0
932 device; if there is no SA, they will be discarded:
934 ipsec whack --route secret
937 Finally, we are ready to get <B>pluto</B> to initiate negotiation
938 for an IPsec SA (and implicitly, an ISAKMP SA):
940 ipsec whack --initiate --name secret
942 A small log of interesting events will appear on standard output
943 (other logging is sent to syslog).
946 <B>whack</B> can also be used to terminate <B>pluto</B> cleanly, tearing down
947 all SAs that it has negotiated.
949 ipsec whack --shutdown
951 At this time, the tearing down is all local:
952 no notification is given to the peers.
953 <A NAME="lbAN"> </A>
954 <H3>The updown command</H3>
958 Whenever <B>pluto</B> brings a connection up or down, it invokes
959 the updown command. This command is specified using the <B>--updown</B>
960 option. This allows for customized control over routing and firewall manipulation.
963 The updown is invoked for five different operations. Each of
964 these operations can be for our client subnet or for our host itself.
966 <DT><B>prepare-host</B> or <B>prepare-client</B><DD>
967 is run before bringing up a new connection if no other connection
968 with the same clients is up. Generally, this is useful for deleting a
969 route that might have been set up before <B>pluto</B> was run or
970 perhaps by some agent not known to <B>pluto</B>.
971 <DT><B>route-host</B> or <B>route-client</B><DD>
972 is run when bringing up a connection for a new peer client subnet
973 (even if <B>prepare-host</B> or <B>prepare-client</B> was run). The
974 command should install a suitable route. Routing decisions are based
975 only on the destination (peer's client) subnet address, unlike eroutes
976 which discriminate based on source too.
977 <DT><B>unroute-host</B> or <B>unroute-client</B><DD>
978 is run when bringing down the last connection for a particular peer
979 client subnet. It should undo what the <B>route-host</B> or <B>route-client</B>
981 <DT><B>up-host</B> or <B>up-client</B><DD>
982 is run when bringing up an eroute with a new pair of client subnets
983 (technically: when an eroute is being added (not replaced)).
984 This command should install firewall rules as appropriate.
985 It is generally a good idea to allow IKE messages (UDP port 500)
986 travel between the hosts.
987 <DT><B>down-host</B> or <B>down-client</B><DD>
988 is run when bringing down the eroute for a pair of client subnets.
989 This command should delete firewall rules as appropriate. Note that
990 there may remain some inbound IPsec SAs with these client subnets.
994 The script is passed a large number of environment variables to specify
995 what needs to be done.
997 <DT><B>PLUTO_VERSION</B><DD>
998 indicates what version of this interface is being used. This document
999 describes version 1.1. This is upwardly compatible with version 1.0.
1000 <DT><B>PLUTO_VERB</B><DD>
1001 specifies the name of the operation to be performed
1002 (<B>prepare-host</B>,r <B>prepare-client</B>,
1003 <B>up-host</B>, <B>up-client</B>,
1004 <B>down-host</B>, or <B>down-client</B>). If the address family for
1005 security gateway to security gateway communications is IPv6, then
1006 a suffix of -v6 is added to the verb.
1007 <DT><B>PLUTO_CONNECTION</B><DD>
1008 is the name of the connection for which we are routing.
1009 <DT><B>PLUTO_NEXT_HOP</B><DD>
1010 is the next hop to which packets bound for the peer must be sent.
1011 <DT><B>PLUTO_INTERFACE</B><DD>
1012 is the name of the ipsec interface to be used.
1013 <DT><B>PLUTO_ME</B><DD>
1014 is the IP address of our host.
1015 <DT><B>PLUTO_MY_CLIENT</B><DD>
1016 is the IP address / count of our client subnet.
1017 If the client is just the host, this will be the host's own IP address / max
1018 (where max is 32 for IPv4 and 128 for IPv6).
1019 <DT><B>PLUTO_MY_CLIENT_NET</B><DD>
1020 is the IP address of our client net.
1021 If the client is just the host, this will be the host's own IP address.
1022 <DT><B>PLUTO_MY_CLIENT_MASK</B><DD>
1023 is the mask for our client net.
1024 If the client is just the host, this will be 255.255.255.255.
1025 <DT><B>PLUTO_PEER</B><DD>
1026 is the IP address of our peer.
1027 <DT><B>PLUTO_PEER_CLIENT</B><DD>
1028 is the IP address / count of the peer's client subnet.
1029 If the client is just the peer, this will be the peer's own IP address / max
1030 (where max is 32 for IPv4 and 128 for IPv6).
1031 <DT><B>PLUTO_PEER_CLIENT_NET</B><DD>
1032 is the IP address of the peer's client net.
1033 If the client is just the peer, this will be the peer's own IP address.
1034 <DT><B>PLUTO_PEER_CLIENT_MASK</B><DD>
1035 is the mask for the peer's client net.
1036 If the client is just the peer, this will be 255.255.255.255.
1040 All output sent by the script to stderr or stdout is logged. The
1041 script should return an exit status of 0 if and only if it succeeds.
1042 <A NAME="lbAO"> </A>
1047 When an SA that was initiated by <B>pluto</B> has only a bit of
1049 <B>pluto</B> will initiate the creation of a new SA. This applies to
1050 ISAKMP and IPsec SAs.
1051 The rekeying will be initiated when the SA's remaining lifetime is
1052 less than the rekeymargin plus a random percentage, between 0 and
1053 rekeyfuzz, of the rekeymargin.
1056 Similarly, when an SA that was initiated by the peer has only a bit of
1057 lifetime left, <B>pluto</B> will try to initiate the creation of a
1059 To give preference to the initiator, this rekeying will only be initiated
1060 when the SA's remaining lifetime is half of rekeymargin.
1061 If rekeying is done by the responder, the roles will be reversed: the
1062 responder for the old SA will be the initiator for the replacement.
1063 The former initiator might also initiate rekeying, so there may
1064 be redundant SAs created.
1065 To avoid these complications, make sure that rekeymargin is generous.
1068 One risk of having the former responder initiate is that perhaps
1069 none of its proposals is acceptable to the former initiator
1070 (they have not been used in a successful negotiation).
1071 To reduce the chances of this happening, and to prevent loss of security,
1072 the policy settings are taken from the old SA (this is the case even if
1073 the former initiator is initiating).
1074 These may be stricter than those of the connection.
1077 <B>pluto</B> will not rekey an SA if that SA is not the most recent of its
1078 type (IPsec or ISAKMP) for its potential connection.
1079 This avoids creating redundant SAs.
1082 The random component in the rekeying time (rekeyfuzz) is intended to
1083 make certain pathological patterns of rekeying unstable. If both
1084 sides decide to rekey at the same time, twice as many SAs as necessary
1085 are created. This could become a stable pattern without the
1089 Another more important case occurs when a security gateway has SAs
1090 with many other security gateways. Each of these connections might
1091 need to be rekeyed at the same time. This would cause a high peek
1092 requirement for resources (network bandwidth, CPU time, entropy for
1093 random numbers). The rekeyfuzz can be used to stagger the rekeying
1097 Once a new set of SAs has been negotiated, <B>pluto</B> will never send
1098 traffic on a superseded one. Traffic will be accepted on an old SA
1100 <A NAME="lbAP"> </A>
1101 <H3>Selecting a Connection When Responding: Road Warrior Support</H3>
1105 When <B>pluto</B> receives an initial Main Mode message, it needs to
1106 decide which connection this message is for. It picks based solely on
1107 the source and destination IP addresses of the message. There might
1108 be several connections with suitable IP addresses, in which case one
1109 of them is arbitrarily chosen. (The ISAKMP SA proposal contained in
1110 the message could be taken into account, but it is not.)
1113 The ISAKMP SA is negotiated before the parties pass further
1114 identifying information, so all ISAKMP SA characteristics specified in
1115 the connection description should be the same for every connection
1116 with the same two host IP addresses. At the moment, the only
1117 characteristic that might differ is authentication method.
1121 all configuring has presumed that the IP addresses
1122 are known to all parties ahead of time. This will not work
1123 when either end is mobile (or assigned a dynamic IP address for other
1124 reasons). We call this situation ``Road Warrior''. It is fairly tricky
1125 and has some important limitations, most of which are features of
1129 Only the initiator may be mobile:
1130 the initiator may have an IP number unknown to the responder. When
1131 the responder doesn't recognize the IP address on the first Main Mode
1132 packet, it looks for a connection with itself as one end and <B>%any</B>
1134 If it cannot find one, it refuses to negotiate. If it
1135 does find one, it creates a temporary connection that is a duplicate
1136 except with the <B>%any</B> replaced by the source IP address from the
1137 packet; if there was no identity specified for the peer, the new IP
1138 address will be used.
1141 When <B>pluto</B> is using one of these temporary connections and
1142 needs to find the preshared secret or RSA private key in <I>ipsec.secrets</I>,
1143 and and the connection specified no identity for the peer, <B>%any</B>
1144 is used as its identity. After all, the real IP address was apparently
1145 unknown to the configuration, so it is unreasonable to require that
1146 it be used in this table.
1149 Part way into the Phase 1 (Main Mode) negotiation using one of these
1150 temporary connection descriptions, <B>pluto</B> will be receive an
1151 Identity Payload. At this point, <B>pluto</B> checks for a more
1152 appropriate connection, one with an identity for the peer that matches
1153 the payload but which would use the same keys so-far used for
1154 authentication. If it finds one, it will switch to using this better
1155 connection (or a temporary derived from this, if it has <B>%any</B>
1156 for the peer's IP address). It may even turn out that no connection
1157 matches the newly discovered identity, including the current connection;
1158 if so, <B>pluto</B> terminates negotiation.
1161 Unfortunately, if preshared secret authentication is being used, the
1162 Identity Payload is encrypted using this secret, so the secret must be
1163 selected by the responder without knowing this payload. This
1164 limits there to being at most one preshared secret for all Road Warrior
1165 systems connecting to a host. RSA Signature authentications does not
1166 require that the responder know how to select the initiator's public key
1167 until after the initiator's Identity Payload is decoded (using the
1168 responder's private key, so that must be preselected).
1171 When <B>pluto</B> is responding to a Quick Mode negotiation via one of these
1172 temporary connection descriptions, it may well find that the subnets
1173 specified by the initiator don't match those in the temporary
1174 connection description. If so, it will look for a connection with
1175 matching subnets, its own host address, a peer address of <B>%any</B>
1176 and matching identities.
1177 If it finds one, a new temporary connection is derived from this one
1178 and used for the Quick Mode negotiation of IPsec SAs. If it does not
1179 find one, <B>pluto</B> terminates negotiation.
1182 Be sure to specify an appropriate nexthop for the responder
1183 to send a message to the initiator: <B>pluto</B> has no way of guessing
1184 it (if forwarding isn't required, use an explicit <B>%direct</B> as the nexthop
1185 and the IP address of the initiator will be filled in; the obsolete
1186 notation <B>0.0.0.0</B> is still accepted).
1189 <B>pluto</B> has no special provision for the initiator side. The current
1190 (possibly dynamic) IP address and nexthop must be used in defining
1191 connections. These must be
1192 properly configured each time the initiator's IP address changes.
1193 <B>pluto</B> has no mechanism to do this automatically.
1196 Although we call this Road Warrior Support, it could also be used to
1197 support encrypted connections with anonymous initiators. The
1198 responder's organization could announce the preshared secret that would be used
1199 with unrecognized initiators and let anyone connect. Of course the initiator's
1200 identity would not be authenticated.
1203 If any Road Warrior connections are supported, <B>pluto</B> cannot
1204 reject an exchange initiated by an unknown host until it has
1205 determined that the secret is not shared or the signature is invalid.
1207 third Main Mode message from the initiator. If no Road Warrior
1208 connection is supported, the first message from an unknown source
1209 would be rejected. This has implications for ease of debugging
1210 configurations and for denial of service attacks.
1213 Although a Road Warrior connection must be initiated by the mobile
1214 side, the other side can and will rekey using the temporary connection
1215 it has created. If the Road Warrior wishes to be able to disconnect,
1216 it is probably wise to set <B>--keyingtries</B> to 1 in the
1217 connection on the non-mobile side to prevent it trying to rekey the
1218 connection. Unfortunately, there is no mechanism to unroute the
1219 connection automatically.
1220 <A NAME="lbAQ"> </A>
1225 <B>pluto</B> accepts several optional arguments, useful mostly for debugging.
1227 <DT><B>--ikeport</B> <I>port-number</I><DD>
1228 changes the UDP port that <B>pluto</B> will use
1229 (default, specified by IANA: 500)
1230 <DT><B>--ctlbase</B> <I>path</I><DD>
1231 basename for control files.
1232 <I>path</I>.ctl is the socket through which <B>whack</B> communicates with
1234 <I>path</I>.pid is the lockfile to prevent multiple pluto instances.
1235 The default is <I>/var/run/pluto</I>).
1236 <DT><B>--secretsfile</B> <I>file</I><DD>
1237 specifies the file for authentication secrets
1238 (default: <I>/etc/ipsec.secrets</I>).
1239 This name is subject to ``globbing'' as in <I><A HREF="sh.1.html">sh</A></I>(1),
1240 so every file with a matching name is processed.
1241 Quoting is generally needed to prevent the shell from doing the globbing.
1242 <DT><B>--nofork</B><DD>
1243 disable ``daemon fork'' (default is to fork). In addition, after the
1244 lock file and control socket are created, print the line ``Pluto
1245 initialized'' to standard out.
1246 <DT><B>--noklips</B><DD>
1247 don't actually implement negotiated IPsec SAs
1248 <DT><B>--uniqueids</B><DD>
1249 if this option has been selected, whenever a new ISAKMP SA is
1250 established, any connection with the same Peer ID but a different
1251 Peer IP address is unoriented (causing all its SAs to be deleted).
1252 This helps clean up dangling SAs when a connection is lost and
1253 then regained at another IP address.
1254 <DT><B>--stderrlog</B><DD>
1255 log goes to standard out {default is to use <I><A HREF="syslogd.8.html">syslogd</A></I>(8))
1261 <DT>pluto --secretsfile ipsec.secrets --ctlbase pluto.base --ikeport 8500 --nofork --noklips --stderrlog<DD>
1265 lets one test <B>pluto</B> without using the superuser account.
1268 <B>pluto</B> is willing to produce a prodigious amount of debugging
1269 information. To do so, it must be compiled with -DDEBUG. There are
1270 several classes of debugging output, and <B>pluto</B> may be directed to
1271 produce a selection of them. All lines of
1272 debugging output are prefixed with ``| '' to distinguish them from error
1276 When <B>pluto</B> is invoked, it may be given arguments to specify
1277 which classes to output. The current options are:
1279 <DT><B>--debug-raw</B><DD>
1280 show the raw bytes of messages
1281 <DT><B>--debug-crypt</B><DD>
1282 show the encryption and decryption of messages
1283 <DT><B>--debug-parsing</B><DD>
1284 show the structure of input messages
1285 <DT><B>--debug-emitting</B><DD>
1286 show the structure of output messages
1287 <DT><B>--debug-control</B><DD>
1288 show <B>pluto</B>'s decision making
1289 <DT><B>--debug-klips</B><DD>
1290 show <B>pluto</B>'s interaction with <B>KLIPS</B>
1291 <DT><B>--debug-all</B><DD>
1293 <DT><B>--debug-private</B><DD>
1294 allow debugging output with private keys.
1295 <DT><B>--debug-none</B><DD>
1300 The debug form of the
1301 <B>whack</B> command will change the selection in a running
1303 If a connection name is specified, the flags are added whenever
1304 <B>pluto</B> has identified that it is dealing with that connection.
1305 Unfortunately, this is often part way into the operation being observed.
1308 For example, to start a <B>pluto</B> with a display of the structure of input
1312 pluto --debug-emitting --debug-parsing
1316 To later change this <B>pluto</B> to only display raw bytes:
1323 For testing, SSH's IKE test page is quite useful:
1326 <I><A HREF="http://isakmp-test.ssh.fi/">http://isakmp-test.ssh.fi/</A></I>
1330 Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA
1331 is established. This allows future IPsec SA's to be negotiated
1332 directly. If one of the IKEs is restarted, the other may try to use
1333 the ISAKMP SA but the new IKE won't know about it. This can lead to
1334 much confusion. <B>pluto</B> is not yet smart enough to get out of such a
1336 <A NAME="lbAR"> </A>
1337 <H3>Pluto's Behaviour When Things Go Wrong</H3>
1341 When <B>pluto</B> doesn't understand or accept a message, it just
1342 ignores the message. It is not yet capable of communicating the
1343 problem to the other IKE daemon (in the future it will use
1344 Notifications to accomplish this in many cases). It does log a diagnostic.
1347 When <B>pluto</B> gets no response from a message, it resends the same
1348 message (a message will be sent at most three times). This is
1349 appropriate: UDP is unreliable.
1352 When pluto gets a message that it has already seen, there are many
1353 cases when it notices and discards it. This too is appropriate for UDP.
1356 Combine these three rules, and you can explain many apparently
1357 mysterious behaviours. In a <B>pluto</B> log, retrying isn't usually the
1358 interesting event. The critical thing is either earlier (<B>pluto</B>
1359 got a message which it didn't like and so ignored, so it was still
1360 awaiting an acceptable message and got impatient) or on the other
1361 system (<B>pluto</B> didn't send a reply because it wasn't happy with
1362 the previous message).
1363 <A NAME="lbAS"> </A>
1368 If <B>pluto</B> is compiled without -DKLIPS, it negotiates Security
1369 Associations but never ask the kernel to put them in place and never
1370 makes routing changes. This allows <B>pluto</B> to be tested on systems
1371 without <B>KLIPS</B>, but makes it rather useless.
1374 Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the SA.
1375 The IKE protocol lets the destination of the SA choose the SPI.
1376 The range 0 to 0xFF is reserved for IANA.
1377 <B>Pluto</B> also avoids choosing an SPI in the range 0x100 to 0xFFF,
1378 leaving these SPIs free for manual keying.
1379 Remember that the peer, if not <B>pluto</B>, may well chose
1381 <A NAME="lbAT"> </A>
1386 This catalogue of policies may be of use when trying to configure
1387 <B>Pluto</B> and another IKE implementation to interoperate.
1390 In Phase 1, only Main Mode is supported. We are not sure that
1391 Aggressive Mode is secure. For one thing, it does not support
1392 identity protection. It may allow more severe Denial Of Service
1396 No Informational Exchanges are supported. These are optional and
1397 since their delivery is not assured, they must not matter.
1398 It is the case that some IKE implementations won't interoperate
1399 without Informational Exchanges, but we feel they are broken.
1402 No Informational Payloads are supported. These are optional, but
1403 useful. It is of concern that these payloads are not authenticated in
1404 Phase 1, nor in those Phase 2 messages authenticated with <A HREF="HASH.3.html">HASH</A>(3).
1407 Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5)
1409 Group MODP768 (1) is not supported because it is too weak.
1411 Host authetication can be done by RSA Signatures or Pre-Shared
1414 3DES CBC (Cypher Block Chaining mode) is the only encryption
1415 supported, both for ISAKMP SAs and IPSEC SAs.
1417 MD5 and SHA1 hashing are supported for packet authentication in both
1420 The ESP, AH, or AH plus ESP are supported. If, and only if, AH and
1421 ESP are combined, the ESP need not have its own authentication
1422 component. The selection is controlled by the --encrypt and
1423 --authenticate flags.
1425 Each of these may be combined with IPCOMP Deflate compression,
1426 but only if the potential connection specifies compression and only
1427 if KLIPS is configured with IPCOMP support.
1429 The IPSEC SAs may be tunnel or transport mode, where appropriate.
1430 The --tunnel flag controls this when <B>pluto</B> is initiating.
1432 When responding to an ISAKMP SA proposal, the maximum acceptable
1433 lifetime is eight hours. The default is one hour. There is no
1434 minimum. The --ikelifetime flag controls this when <B>pluto</B>
1437 When responding to an IPSEC SA proposal, the maximum acceptable
1438 lifetime is one day. The default is eight hours. There is no
1439 minimum. The --ipseclifetime flag controls this when <B>pluto</B>
1442 PFS is acceptable, and will be proposed if the --pfs flag was
1443 specified. The DH group proposed will be the same as negotiated for
1446 <A NAME="lbAU"> </A>
1451 <B>Pluto</B> responds to <B>SIGHUP</B> by issuing a suggestion that ``<B>whack</B>
1452 --listen'' might have been intended.
1455 <B>Pluto</B> exits when it recieves <B>SIGTERM</B>.
1456 <A NAME="lbAV"> </A>
1457 <H2>EXIT STATUS</H2>
1461 <B>pluto</B> normally forks a daemon process, so the exit status is
1462 normally a very preliminary result.
1465 means that all is OK so far.
1467 means that something was wrong.
1469 means that the lock file already exists.
1473 If <B>whack</B> detects a problem, it will return an exit status of 1.
1474 If it received progress messages from <B>pluto</B>, it returns as status
1475 the value of the numeric prefix from the last such message
1476 that was not a message sent to syslog or a comment
1477 (but the prefix for success is treated as 0).
1478 Otherwise, the exit status is 0.
1479 <A NAME="lbAW"> </A>
1482 <I>/var/run/pluto.pid</I>
1485 <I>/var/run/pluto.ctl</I>
1488 <I>/etc/ipsec.secrets</I>
1492 <A NAME="lbAX"> </A>
1497 The rest of the FreeS/WAN distribution, in particular <I><A HREF="ipsec.8.html">ipsec</A></I>(8).
1500 <I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8) is designed to make using <B>pluto</B> more pleasant.
1504 <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5)
1506 describes the format of the secrets file.
1509 <I><A HREF="ipsec_atoaddr.3.html">ipsec_atoaddr</A></I>(3), part of the FreeS/WAN distribution, describes the
1510 forms that IP addresses may take.
1511 <I><A HREF="ipsec_atosubnet.3.html">ipsec_atosubnet</A></I>(3), part of the FreeS/WAN distribution, describes the
1512 forms that subnet specifications.
1515 For more information on IPsec, the mailing list, and the relevant
1520 <I><A HREF="http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html">http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html</A></I>
1525 At the time of writing, the most relevant IETF RFCs are:
1528 RFC2409 The Internet Key Exchange (IKE)
1530 RFC2408 Internet Security Association and Key Management Protocol (ISAKMP)
1532 RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP
1536 The <A HREF="mailto:linux-ipsec@clinet.fi">linux-ipsec@clinet.fi</A> mailing list.
1537 <A NAME="lbAY"> </A>
1540 This code is released under the GPL terms.
1541 See the accompanying file COPYING-2.0 for more details.
1542 The GPL does NOT apply to those pieces of code written by others
1543 which are included in this distribution, except as noted by the
1547 This software was originally written
1548 for the FreeS/WAN project
1549 <<A HREF="http://www.xs4all.nl/~freeswan/">http://www.xs4all.nl/~freeswan/</A>>
1550 by Angelos D. Keromytis
1551 (<A HREF="mailto:angelos@dsl.cis.upenn.edu">angelos@dsl.cis.upenn.edu</A>), in May/June 1997, in Athens, Greece.
1552 Thanks go to John Ioannidis for his help.
1555 It is currently (2000)
1556 being developed and maintained by D. Hugh Redelmeier
1557 (<A HREF="mailto:hugh@mimosa.com">hugh@mimosa.com</A>), in Canada. The regulations of Greece and Canada
1558 allow us to make the code freely redistributable.
1561 Kai Martius (<A HREF="mailto:admin@imib.med.tu-dresden.de">admin@imib.med.tu-dresden.de</A>) contributed the initial
1562 version of the code supporting PFS.
1565 Richard Guy Briggs <<A HREF="mailto:rgb@conscoop.ottawa.on.ca">rgb@conscoop.ottawa.on.ca</A>> and Peter Onion
1566 <<A HREF="mailto:ponion@srd.bt.co.uk">ponion@srd.bt.co.uk</A>> added the PFKEY2 support.
1569 We gratefully acknowledge that we use parts of Eric Young's <I>libdes</I>
1570 package; see <I>../libdes/COPYRIGHT</I>.
1571 <A NAME="lbAZ"> </A>
1576 is a work-in-progress. It currently has many limitations.
1577 For example, it ignores notification messages that it receives, and
1581 <B>pluto</B> does not check that the SA returned by the Responder
1582 is actually one that was proposed. It only checks that the SA is
1583 acceptable. The difference is not large, but can show up in attributes
1584 such as SA lifetime.
1587 There is no provision for unrouting a Road Warrior connection that has
1588 expired. In fact, there is no good way for a Road Warrior to indicate
1589 that the connection should be torn down. The expiry of SAs is the
1590 closest approximation.
1591 If, however, a Road Warrior has a client subnet with a fixed IP
1592 address, a negotiation with that subnet will cause any other
1593 connection instantiations with that same subnet to be unoriented
1594 (deleted, in effect).
1595 See also the --uniqueids option.
1598 When <B>pluto</B> sends a message to a peer that has disappeared,
1599 <B>pluto</B> receives incomplete information from the kernel, so it
1600 logs the unsatisfactory message ``some IKE message we sent has been
1601 rejected with ECONNREFUSED (kernel supplied no details)''. John
1602 Denker suggests that this command is useful for tracking down the
1603 source of these problems:
1606 <TT> </TT>tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0<BR>
1609 Substitute your public interface for eth0 if it is different.
1612 Sometimes (rarely) <B>pluto</B> hangs trying to receive an IKE message
1613 that isn't there. While this is happening, it responds to nothing
1614 else. We haven't yet located the cause of the problem and even
1615 suspect a kernel bug. Sending SIGHUP to <B>pluto</B> should wake it
1616 up. Any assistance nailing this bug would be welcome.
1619 The word ``authenticate'' is used for two different features. We must
1620 authenticate each IKE peer to the other. This is an important task of
1621 Phase 1. Each packet must be authenticated, both in IKE and in IPsec,
1622 and the method for IPsec is negotiated as an AH SA or part of an ESP SA.
1623 Unfortunately, the protocol has no mechanism for authenticating the Phase 2
1627 Bugs should be reported to the <A HREF="mailto:linux-ipsec@clinet.fi">linux-ipsec@clinet.fi</A> mailing list.
1628 Caution: we cannot accept
1629 actual code from US residents, or even US citizens living outside the
1630 US, because that would bring FreeS/WAN under US export law. Some
1631 other countries cause similar problems. In general, we would prefer
1632 that you send detailed problem reports rather than code: we want
1633 FreeS/WAN to be unquestionably freely exportable, which means being
1634 very careful about where the code comes from, and for a small bug fix,
1635 that is often more time-consuming than just reinventing the fix
1640 <A NAME="index"> </A><H2>Index</H2>
1642 <DT><A HREF="#lbAB">NAME</A><DD>
1643 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
1644 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
1646 <DT><A HREF="#lbAE">IKE's Job</A><DD>
1647 <DT><A HREF="#lbAF">Pluto</A><DD>
1648 <DT><A HREF="#lbAG">Before Running Pluto</A><DD>
1649 <DT><A HREF="#lbAH">Setting up <B>KLIPS</B> for <B>pluto</B></A><DD>
1650 <DT><A HREF="#lbAI">ipsec.secrets file</A><DD>
1651 <DT><A HREF="#lbAJ">Running Pluto</A><DD>
1652 <DT><A HREF="#lbAK">Pluto's Internal State</A><DD>
1653 <DT><A HREF="#lbAL">Using Whack</A><DD>
1654 <DT><A HREF="#lbAM">Examples</A><DD>
1655 <DT><A HREF="#lbAN">The updown command</A><DD>
1656 <DT><A HREF="#lbAO">Rekeying</A><DD>
1657 <DT><A HREF="#lbAP">Selecting a Connection When Responding: Road Warrior Support</A><DD>
1658 <DT><A HREF="#lbAQ">Debugging</A><DD>
1659 <DT><A HREF="#lbAR">Pluto's Behaviour When Things Go Wrong</A><DD>
1660 <DT><A HREF="#lbAS">Notes</A><DD>
1661 <DT><A HREF="#lbAT">Policies</A><DD>
1663 <DT><A HREF="#lbAU">SIGNALS</A><DD>
1664 <DT><A HREF="#lbAV">EXIT STATUS</A><DD>
1665 <DT><A HREF="#lbAW">FILES</A><DD>
1666 <DT><A HREF="#lbAX">SEE ALSO</A><DD>
1667 <DT><A HREF="#lbAY">HISTORY</A><DD>
1668 <DT><A HREF="#lbAZ">BUGS</A><DD>
1671 This document was created by
1672 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
1673 using the manual pages.<BR>
1674 Time: 05:09:34 GMT, June 19, 2001
OSDN Git Service
