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 [
<B>--interface
</B> <I>interfacename
</I>]
33 [--ikeport
<I>portnumber
</I>]
34 [--ctlbase
<I>path
</I>]
35 [--secretsfile
<I>secrets-file
</I>]
36 [--adns
<I>pathname
</I>]
37 [--lwdnsq
<I>pathname
</I>]
39 [--perpeerlogbase
<I>dirname
</I>]
60 --name
</B><I>connection-name
</I>
63 [--id
<I>id
</I>] [--host
<I>ip-address
</I>]
64 [--ikeport
<I>port-number
</I>]
65 [--nexthop
<I>ip-address
</I>]
66 [--client
<I>subnet
</I>]
68 [--updown
<I>updown
</I>]
75 [--host
<I>ip-address
</I>]
76 [--ikeport
<I>port-number
</I>]
77 [--nexthop
<I>ip-address
</I>]
78 [--client
<I>subnet
</I>]
80 [--updown
<I>updown
</I>]
90 [--disablearrivalcheck]
95 [--ikelifetime
<I>seconds
</I>]
96 [--ipseclifetime
<I>seconds
</I>]
97 [--rekeymargin
<I>seconds
</I>]
98 [--rekeyfuzz
<I>percentage
</I>]
99 [--keyingtries
<I>count
</I>]
102 [--ctlbase
<I>path
</I>]
103 [--optionsfrom
<I>filename
</I>]
104 [--label
<I>string
</I>]
108 --keyid
</B><I>id
</I>
110 [--pubkeyrsa
<I>key
</I>]
111 [--ctlbase
<I>path
</I>]
112 [--optionsfrom
<I>filename
</I>]
113 [--label
<I>string
</I>]
117 --myid
</B><I>id
</I>
122 [--ctlbase
</B><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 --initiate|--terminate
137 --name
</B><I>connection-name
</I>
139 [--ctlbase
<I>path
</I>]
140 [--optionsfrom
<I>filename
</I>]
141 [--label
<I>string
</I>]
147 --oppohere
</B><I>ip-address
</I>
148 --oppothere
<I>ip-address
</I>
153 --name
</B><I>connection-name
</I>
154 [--ctlbase
<I>path
</I>]
155 [--optionsfrom
<I>filename
</I>]
156 [--label
<I>string
</I>]
160 --deletestate
</B><I>state-number
</I>
161 [--ctlbase
<I>path
</I>]
162 [--optionsfrom
<I>filename
</I>]
163 [--label
<I>string
</I>]
167 [--name
</B><I>connection-name
</I>]
180 [--ctlbase
<I>path
</I>]
181 [--optionsfrom
<I>filename
</I>]
182 [--label
<I>string
</I>]
187 [--ctlbase
</B><I>path
</I>]
188 [--optionsfrom
<I>filename
</I>]
189 [--label
<I>string
</I>]
194 [--ctlbase
</B><I>path
</I>]
195 [--optionsfrom
<I>filename
</I>]
196 [--label
<I>string
</I>]
201 <A NAME=
"lbAD"> </A>
206 is an IKE (``IPsec Key Exchange'') daemon.
209 is an auxiliary program to allow requests to be made to a running
216 is used to automatically build shared ``security associations'' on a
217 system that has IPsec, the secure IP protocol.
221 can eliminate much of the work of manual keying.
223 secure transmission of packets is the responsibility of other parts of
227 the companion implementation of IPsec).
228 <I><A HREF=
"ipsec_auto.8.html">ipsec_auto
</A></I>(
8) provides a more convenient interface to
229 <B>pluto
</B> and
<B>whack
</B>.
230 <A NAME=
"lbAE"> </A>
235 A
<I>Security Association
</I> (
<I>SA
</I>) is an agreement between two network nodes on
236 how to process certain traffic between them. This processing involves
237 encapsulation, authentication, encryption, or compression.
240 IKE can be deployed on a network node to negotiate Security
241 Associations for that node. These IKE implementations can only
242 negotiate with other IKE implementations, so IKE must be on each node
243 that is to be an endpoint of an IKE-negotiated Security Association.
244 No other nodes need to be running IKE.
247 An IKE instance (i.e. an IKE implementation on a particular network
248 node) communicates with another IKE instance using UDP IP packets, so
249 there must be a route between the nodes in each direction.
252 The negotiation of Security Associations requires a number of choices
253 that involve tradeoffs between security, convenience, trust, and
254 efficiency. These are policy issues and are normally specified to the
255 IKE instance by the system administrator.
258 IKE deals with two kinds of Security Associations. The first part of
259 a negotiation between IKE instances is to build an ISAKMP SA. An
260 ISAKMP SA is used to protect communication between the two IKEs.
261 IPsec SAs can then be built by the IKEs - these are used to carry
262 protected IP traffic between the systems.
265 The negotiation of the ISAKMP SA is known as Phase
1. In theory,
266 Phase
1 can be accomplished by a couple of different exchange types,
267 but we only implement one called Main Mode (we don't implement
271 Any negotiation under the protection of an ISAKMP SA, including the
272 negotiation of IPsec SAs, is part of Phase
2. The exchange type
273 that we use to negotiate an IPsec SA is called Quick Mode.
276 IKE instances must be able to authenticate each other as part of their
277 negotiation of an ISAKMP SA. This can be done by several mechanisms
278 described in the draft standards.
281 IKE negotiation can be initiated by any instance with any other. If
282 both can find an agreeable set of characteristics for a Security
283 Association, and both recognize each others authenticity, they can set
284 up a Security Association. The standards do not specify what causes
285 an IKE instance to initiate a negotiation.
288 In summary, an IKE instance is prepared to automate the management of
289 Security Associations in an IPsec environment, but a number of issues
290 are considered policy and are left in the system administrator's hands.
291 <A NAME=
"lbAF"> </A>
296 <B>pluto
</B> is an implementation of IKE. It runs as a daemon on a network
297 node. Currently, this network node must be a LINUX system running the
298 <B>KLIPS
</B> implementation of IPsec.
301 <B>pluto
</B> only implements a subset of IKE. This is enough for it to
302 interoperate with other instances of
<B>pluto
</B>, and many other IKE
303 implementations. We are working on implementing more of IKE.
306 The policy for acceptable characteristics for Security Associations is
307 mostly hardwired into the code of
<B>pluto
</B> (spdb.c). Eventually
308 this will be moved into a security policy database with reasonable
309 expressive power and more convenience.
312 <B>pluto
</B> uses shared secrets or RSA signatures to authenticate
313 peers with whom it is negotiating.
316 <B>pluto
</B> initiates negotiation of a Security Association when it is
317 manually prodded: the program
<B>whack
</B> is run to trigger this.
318 It will also initiate a negotiation when
<B>KLIPS
</B> traps an outbound packet
319 for Opportunistic Encryption.
322 <B>pluto
</B> implements ISAKMP SAs itself. After it has negotiated the
323 characteristics of an IPsec SA, it directs
<B>KLIPS
</B> to implement it.
324 It also invokes a script to adjust any firewall and issue
<I><A HREF=
"route.8.html">route
</A></I>(
8)
325 commands to direct IP packets through
<B>KLIPS
</B>.
328 When
<B>pluto
</B> shuts down, it closes all Security Associations.
329 <A NAME=
"lbAG"> </A>
330 <H3>Before Running Pluto
</H3>
334 <B>pluto
</B> runs as a daemon with userid root. Before running it, a few
335 things must be set up.
338 <B>pluto
</B> requires
<B>KLIPS
</B>, the FreeS/WAN implementation of IPsec.
339 All of the components of
<B>KLIPS
</B> and
<B>pluto
</B> should be installed.
342 <B>pluto
</B> supports multiple public networks (that is, networks
343 that are considered insecure and thus need to have their traffic
344 encrypted or authenticated). It discovers the
345 public interfaces to use by looking at all interfaces that are
346 configured (the
<B>--interface
</B> option can be used to limit
347 the interfaces considered).
348 It does this only when
<B>whack
</B> tells it to --listen,
349 so the interfaces must be configured by then. Each interface with a name of the form
350 <B>ipsec
</B>[
<B>0</B>-
<B>9</B>] is taken as a
<B>KLIPS
</B> virtual public interface.
351 Another network interface with the same IP address (there should be only
352 one) is taken as the corresponding real public
353 interface.
<I><A HREF=
"ifconfig.8.html">ifconfig
</A></I>(
8) with the
<B>-a
</B> flag will show
354 the name and status of each network interface.
357 <B>pluto
</B> requires a database of preshared secrets and RSA private keys.
358 This is described in the
359 <I><A HREF=
"ipsec.secrets.5.html">ipsec.secrets
</A></I>(
5).
361 <B>pluto
</B> is told of RSA public keys via
<B>whack
</B> commands.
362 If the connection is Opportunistic, and no RSA public key is known,
363 <B>pluto
</B> will attempt to fetch RSA keys using the Domain Name System.
364 <A NAME=
"lbAH"> </A>
365 <H3>Setting up
<B>KLIPS
</B> for
<B>pluto
</B></H3>
369 The most basic network topology that
<B>pluto
</B> supports has two security
370 gateways negotiating on behalf of client subnets. The diagram of RGB's
371 testbed is a good example (see
<I>klips/doc/rgb_setup.txt
</I>).
374 The file
<I>INSTALL
</I> in the base directory of this distribution
375 explains how to start setting up the whole system, including
<B>KLIPS
</B>.
378 Make sure that the security gateways have routes to each other. This
379 is usually covered by the default route, but may require issuing
380 <I><A HREF=
"route.8.html">route
</A></I>(
8)
382 commands. The route must go through a particular IP
383 interface (we will assume it is
<I>eth0
</I>, but it need not be). The
384 interface that connects the security gateway to its client must be a
388 It is necessary to issue a
389 <I><A HREF=
"ipsec_tncfg.8.html">ipsec_tncfg
</A></I>(
8)
391 command on each gateway. The required command is:
393 ipsec tncfg --attach
--virtual
ipsec0 --physical
eth0
395 A command to set up the ipsec0 virtual interface will also need to be
396 run. It will have the same parameters as the command used to set up
397 the physical interface to which it has just been connected using
398 <I><A HREF=
"ipsec_tncfg.8.html">ipsec_tncfg
</A></I>(
8).
400 <A NAME=
"lbAI"> </A>
401 <H3>ipsec.secrets file
</H3>
405 A
<B>pluto
</B> daemon and another IKE daemon (for example, another instance
406 of
<B>pluto
</B>) must convince each other that they are who they are supposed
407 to be before any negotiation can succeed. This authentication is
408 accomplished by using either secrets that have been shared beforehand
409 (manually) or by using RSA signatures. There are other techniques,
410 but they have not been implemented in
<B>pluto
</B>.
413 The file
<I>/etc/ipsec.secrets
</I> is used to keep preshared secret keys
414 and RSA private keys for
415 authentication with other IKE daemons. For debugging, there is an
416 argument to the
<B>pluto
</B> command to use a different file.
417 This file is described in
418 <I><A HREF=
"ipsec.secrets.5.html">ipsec.secrets
</A></I>(
5).
420 <A NAME=
"lbAJ"> </A>
421 <H3>Running Pluto
</H3>
425 To fire up the daemon, just type
<B>pluto
</B> (be sure to be running as
427 The default IKE port number is
500, the UDP port assigned by IANA for IKE Daemons.
428 <B>pluto
</B> must be run by the superuser to be able to use the UDP
500 port.
431 <B>pluto
</B> attempts to create a lockfile with the name
432 <I>/var/run/pluto.pid
</I>. If the lockfile cannot be created,
433 <B>pluto
</B> exits - this prevents multiple
<B>pluto
</B>s from
434 competing Any ``leftover'' lockfile must be removed before
435 <B>pluto
</B> will run.
<B>pluto
</B> writes its pid into this file so
436 that scripts can find it. This lock will not function properly if it
437 is on an NFS volume (but sharing locks on multiple machines doesn't
441 <B>pluto
</B> then forks and the parent exits. This is the conventional
442 ``daemon fork''. It can make debugging awkward, so there is an option
443 to suppress this fork.
446 All logging, including diagnostics, is sent to
447 <I><A HREF=
"syslog.3.html">syslog
</A></I>(
3)
449 with facility=authpriv;
450 it decides where to put these messages (possibly in /var/log/secure).
451 Since this too can make debugging awkward, there is an option to
452 steer logging to stderr.
455 If the
<B>--perpeerlog
</B> option is given, then pluto will open
456 a log file per connection. By default, this is in /var/log/pluto/peer,
457 in a subdirectory formed by turning all dot (.) [IPv4} or colon (:)
458 [IPv6] into slashes (/).
461 The base directory can be changed with the
<B>--perpeerlogbase
</B>.
464 Once
<B>pluto
</B> is started, it waits for requests from
<B>whack
</B>.
465 <A NAME=
"lbAK"> </A>
466 <H3>Pluto's Internal State
</H3>
470 To understand how to use
<B>pluto
</B>, it is helpful to understand a little
471 about its internal state. Furthermore, the terminology is needed to decipher
472 some of the diagnostic messages.
475 The
<I>(potential) connection
</I> database describes attributes of a
476 connection. These include the IP addresses of the hosts and client
477 subnets and the security characteristics desired.
<B>pluto
</B>
478 requires this information (simply called a connection) before it can
479 respond to a request to build an SA. Each connection is given a name
480 when it is created, and all references are made using this name.
483 During the IKE exchange to build an SA, the information about the
484 negotiation is represented in a
<I>state object
</I>. Each state object
485 reflects how far the negotiation has reached. Once the negotiation is
486 complete and the SA established, the state object remains to represent
487 the SA. When the SA is terminated, the state object is discarded.
488 Each State object is given a serial number and this is used to refer
489 to the state objects in logged messages.
492 Each state object corresponds to a connection and can be thought of
493 as an instantiation of that connection.
494 At any particular time, there may be any number of state objects
495 corresponding to a particular connection.
496 Often there is one representing an ISAKMP SA and another representing
500 <B>KLIPS
</B> hooks into the routing code in a LINUX kernel.
501 Traffic to be processed by an IPsec SA must be directed through
502 <B>KLIPS
</B> by routing commands. Furthermore, the processing to be
503 done is specified by
<I>ipsec
<A HREF=
"eroute.8.html">eroute
</A>(
8)
</I> commands.
504 <B>pluto
</B> takes the responsibility of managing both of these special
508 Each connection may be routed, and must be while it has an IPsec SA.
509 The connection specifies the characteristics of the route: the
510 interface on this machine, the ``gateway'' (the nexthop),
511 and the peer's client subnet. Two
512 connections may not be simultaneously routed if they are for the same
513 peer's client subnet but use different interfaces or gateways
514 (
<B>pluto
</B>'s logic does not reflect any advanced routing capabilities).
517 Each eroute is associated with the state object for an IPsec SA
518 because it has the particular characteristics of the SA.
519 Two eroutes conflict if they specify the identical local
520 and remote clients (unlike for routes, the local clients are
524 When
<B>pluto
</B> needs to install a route for a connection,
525 it must make sure that no conflicting route is in use. If another
526 connection has a conflicting route, that route will be taken down, as long
527 as there is no IPsec SA instantiating that connection.
528 If there is such an IPsec SA, the attempt to install a route will fail.
531 There is an exception. If
<B>pluto
</B>, as Responder, needs to install
532 a route to a fixed client subnet for a connection, and there is
533 already a conflicting route, then the SAs using the route are deleted
534 to make room for the new SAs. The rationale is that the new
535 connection is probably more current. The need for this usually is a
536 product of Road Warrior connections (these are explained later; they
537 cannot be used to initiate).
540 When
<B>pluto
</B> needs to install an eroute for an IPsec SA (for a
541 state object), first the state object's connection must be routed (if
542 this cannot be done, the eroute and SA will not be installed).
543 If a conflicting eroute is already in place for another connection,
544 the eroute and SA will not be installed (but note that the routing
545 exception mentioned above may have already deleted potentially conflicting SAs).
547 SA for the same connection already has an eroute, all its outgoing traffic
548 is taken over by the new eroute. The incoming traffic will still be
549 processed. This characteristic is exploited during rekeying.
552 All of these routing characteristics are expected change when
553 <B>KLIPS
</B> is modified to use the firewall hooks in the LINUX
2.4.x
555 <A NAME=
"lbAL"> </A>
560 <B>whack
</B> is used to command a running
<B>pluto
</B>.
561 <B>whack
</B> uses a UNIX domain socket to speak to
<B>pluto
</B>
562 (by default,
<I>/var/pluto.ctl
</I>).
565 <B>whack
</B> has an intricate argument syntax.
566 This syntax allows many different functions to be specified.
567 The help form shows the usage or version information.
568 The connection form gives
<B>pluto
</B> a description of a potential connection.
569 The public key form informs
<B>pluto
</B> of the RSA public key for a potential peer.
570 The delete form deletes a connection description and all SAs corresponding
572 The listen form tells
<B>pluto
</B> to start or stop listening on the public interfaces
573 for IKE requests from peers.
574 The route form tells
<B>pluto
</B> to set up routing for a connection;
575 the unroute form undoes this.
576 The initiate form tells
<B>pluto
</B> to negotiate an SA corresponding to a connection.
577 The terminate form tells
<B>pluto
</B> to remove all SAs corresponding to a connection,
578 including those being negotiated.
579 The status form displays the
<B>pluto
</B>'s internal state.
580 The debug form tells
<B>pluto
</B> to change the selection of debugging output
581 ``on the fly''. The shutdown form tells
582 <B>pluto
</B> to shut down, deleting all SAs.
585 Most options are specific to one of the forms, and will be described
586 with that form. There are three options that apply to all forms.
588 <DT><B>--ctlbase
</B> <I>path
</I><DD>
589 <I>path
</I>.ctl is used as the UNIX domain socket for talking
591 This option facilitates debugging.
592 <DT><B>--optionsfrom
</B> <I>filename
</I><DD>
593 adds the contents of the file to the argument list.
594 <DT><B>--label
</B> <I>string
</I><DD>
595 adds the string to all error messages generated by
<B>whack
</B>.
599 The help form of
<B>whack
</B> is self-explanatory.
601 <DT><B>--help
</B><DD>
602 display the usage message.
603 <DT><B>--version
</B><DD>
604 display the version of
<B>whack
</B>.
608 The connection form describes a potential connection to
<B>pluto
</B>.
609 <B>pluto
</B> needs to know what connections can and should be negotiated.
610 When
<B>pluto
</B> is the initiator, it needs to know what to propose.
611 When
<B>pluto
</B> is the responder, it needs to know enough to decide whether
612 is is willing to set up the proposed connection.
615 The description of a potential connection can specify a large number
616 of details. Each connection has a unique name. This name will appear
617 in a updown shell command, so it should not contain punctuation
618 that would make the command ill-formed.
620 <DT><B>--name
</B> <I>connection-name
</I><DD>
625 a connection is symmetric, so to save space here is half a picture:
627 client_subnet
<--
>host:ikeport
<--
>nexthop
<---
629 A similar trick is used in the flags. The same flag names are used for
630 both ends. Those before the
<B>--to
</B> flag describe the left side
631 and those afterwards describe the right side. When
<B>pluto
</B> attempts
632 to use the connection, it decides whether it is the left side or the right
633 side of the connection, based on the IP numbers of its interfaces.
635 <DT><B>--id
</B> <I>id
</I><DD>
636 the identity of the end. Currently, this can be an IP address (specified
637 as dotted quad or as a Fully Qualified Domain Name, which will be resolved
638 immediately) or as a Fully Qualified Domain Name itself (prefixed by ``@''
639 to signify that it should not be resolved), or as
<A HREF=
"mailto:user@FQDN">user@FQDN
</A>, or as the
640 magic value
<B>%myid
</B>.
641 <B>Pluto
</B> only authenticates the identity, and does not use it for
642 addressing, so, for example, an IP address need not be the one to which
643 packets are to be sent. If the option is absent, the
644 identity defaults to the IP address specified by
<B>--host
</B>.
645 <B>%myid
</B> allows the identity to be separately specified (by the
<B>pluto
</B> or
<B>whack
</B> option
<B>--myid
</B>
646 or by the
<B><A HREF=
"ipsec.conf.5.html">ipsec.conf
</A></B>(
5)
<B>config setup
</B> parameter myid).
647 Otherwise,
<B>pluto
</B> tries to guess what
<B>%myid
</B> should stand for:
648 the IP address of
<B>%defaultroute
</B>, if it is supported by a suitable TXT record in the reverse domain for that IP address,
649 or the system's hostname, if it is supported by a suitable TXT record in its forward domain.
651 <DT><B>--host
</B> <I>ip-address
</I><DD>
652 <DT><B>--host
</B> <B>%any
</B><DD>
653 <DT><B>--host
</B> <B>%opportunistic
</B><DD>
654 the IP address of the end (generally the public interface).
655 If
<B>pluto
</B> is to act as a responder
656 for IKE negotiations initiated from unknown IP addresses (the
657 ``Road Warrior'' case), the
658 IP address should be specified as
<B>%any
</B> (currently,
659 the obsolete notation
<B>0.0.0.0</B> is also accepted for this).
660 If
<B>pluto
</B> is to opportunistically initiate the connection,
661 use
<B>%opportunistic
</B>
662 <DT><B>--ikeport
</B> <I>port-number
</I><DD>
663 the UDP port that IKE listens to on that host. The default is
500.
664 (
<B>pluto
</B> on this machine uses the port specified by its own command
665 line argument, so this only affects where
<B>pluto
</B> sends messages.)
666 <DT><B>--nexthop
</B> <I>ip-address
</I><DD>
667 where to route packets for the peer's client (presumably for the peer too,
668 but it will not be used for this).
669 When
<B>pluto
</B> installs an IPsec SA, it issues a route command.
670 It uses the nexthop as the gateway.
671 The default is the peer's IP address (this can be explicitly written as
672 <B>%direct
</B>; the obsolete notation
<B>0.0.0.0</B> is accepted).
673 This option is necessary if
<B>pluto
</B>'s host's interface used for sending
674 packets to the peer is neither point-to-point nor directly connected to the
676 <DT><B>--client
</B> <I>subnet
</I><DD>
677 the subnet for which the IPsec traffic will be destined. If not specified,
678 the host will be the client.
679 The subnet can be specified in any of the forms supported by
<I><A HREF=
"ipsec_atosubnet.3.html">ipsec_atosubnet
</A></I>(
3).
680 The general form is
<I>address
</I>/
<I>mask
</I>. The
<I>address
</I> can be either
681 a domain name or four decimal numbers (specifying octets) separated by dots.
682 The most convenient form of the
<I>mask
</I> is a decimal integer, specifying
683 the number of leading one bits in the mask. So, for example,
10.0.0.0/
8
684 would specify the class A network ``Net
10''.
685 <DT><B>--dnskeyondemand]
</B><DD>
686 specifies that when an RSA public key is needed to authenticate this
687 host, and it isn't already known, fetch it from DNS.
688 <DT><B>--updown
</B> <I>updown
</I><DD>
689 specifies an external shell command to be run whenever
<B>pluto
</B>
690 brings up or down a connection.
691 The script is used to build a shell command, so it may contain positional
692 parameters, but ought not to have punctuation that would cause the
693 resulting command to be ill-formed.
694 The default is
<I>ipsec _updown
</I>.
696 separates the specification of the left and right ends of the connection.
700 The potential connection description also specifies characteristics of
701 rekeying and security.
704 Propose and allow preshared secret authentication for IKE peers. This authentication
705 requires that each side use the same secret. May be combined with
<B>--rsasig
</B>;
706 at least one must be specified.
707 <DT><B>--rsasig
</B><DD>
708 Propose and allow RSA signatures for authentication of IKE peers. This authentication
709 requires that each side have have a private key of its own and know the
710 public key of its peer. May be combined with
<B>--psk
</B>;
711 at least one must be specified.
712 <DT><B>--encrypt
</B><DD>
713 All proposed or accepted IPsec SAs will include non-null ESP.
714 The actual choices of transforms are wired into
<B>pluto
</B>.
715 <DT><B>--authenticate
</B><DD>
716 All proposed IPsec SAs will include AH.
717 All accepted IPsec SAs will include AH or ESP with authentication.
718 The actual choices of transforms are wired into
<B>pluto
</B>.
719 Note that this has nothing to do with IKE authentication.
720 <DT><B>--compress
</B><DD>
721 All proposed IPsec SAs will include IPCOMP (compression).
722 This will be ignored if KLIPS is not configured with IPCOMP support.
723 <DT><B>--tunnel
</B><DD>
724 the IPsec SA should use tunneling. Implicit if the SA is for clients.
725 Must only be used with
<B>--authenticate
</B> or
<B>--encrypt
</B>.
726 <DT><B>--ipv4
</B><DD>
727 The host addresses will be interpreted as IPv4 addresses. This is the
728 default. Note that for a connection, all host addresses must be of
729 the same Address Family (IPv4 and IPv6 use different Address Families).
730 <DT><B>--ipv6
</B><DD>
731 The host addresses (including nexthop) will be interpreted as IPv6 addresses.
732 Note that for a connection, all host addresses must be of
733 the same Address Family (IPv4 and IPv6 use different Address Families).
734 <DT><B>--tunnelipv4
</B><DD>
735 The client addresses will be interpreted as IPv4 addresses. The default is
736 to match what the host will be. This does not imply
<B>--tunnel
</B> so the
737 flag can be safely used when no tunnel is actually specified.
738 Note that for a connection, all tunnel addresses must be of the same
740 <DT><B>--tunnelipv6
</B><DD>
741 The client addresses will be interpreted as IPv6 addresses. The default is
742 to match what the host will be. This does not imply
<B>--tunnel
</B> so the
743 flag can be safely used when no tunnel is actually specified.
744 Note that for a connection, all tunnel addresses must be of the same
747 There should be Perfect Forward Secrecy - new keying material will
748 be generated for each IPsec SA rather than being derived from the ISAKMP
750 Since the group to be used cannot be negotiated (a dubious feature of the
751 standard),
<B>pluto
</B> will propose the same group that was used during Phase
1.
752 We don't implement a stronger form of PFS which would require that the
753 ISAKMP SA be deleted after the IPSEC SA is negotiated.
754 <DT><B>--disablearrivalcheck
</B><DD>
755 If the connection is a tunnel, allow packets arriving through the tunnel
756 to have any source and destination addresses.
760 If none of the
<B>--encrypt
</B>,
<B>--authenticate
</B>,
<B>--compress
</B>,
761 or
<B>--pfs
</B> flags is given, the initiating the connection will
762 only build an ISAKMP SA. For such a connection, client subnets have
763 no meaning and must not be specified.
766 More work is needed to allow for flexible policies. Currently
767 policy is hardwired in the source file spdb.c. The ISAKMP SAs may use
768 Oakley groups MODP1024 and MODP1536;
3DES encryption; SHA1-
96
769 and MD5-
96 authentication. The IPsec SAs may use
3DES and
770 MD5-
96 or SHA1-
96 for ESP, or just MD5-
96 or SHA1-
96 for AH.
771 IPCOMP Compression is always Deflate.
773 <DT><B>--ikelifetime
</B> <I>seconds
</I><DD>
774 how long
<B>pluto
</B> will propose that an ISAKMP SA be allowed to live.
775 The default is
3600 (one hour) and the maximum is
28800 (
8 hours).
776 This option will not affect what is accepted.
777 <B>pluto
</B> will reject proposals that exceed the maximum.
778 <DT><B>--ipseclifetime
</B> <I>seconds
</I><DD>
779 how long
<B>pluto
</B> will propose that an IPsec SA be allowed to live.
780 The default is
28800 (eight hours) and the maximum is
86400 (one day).
781 This option will not affect what is accepted.
782 <B>pluto
</B> will reject proposals that exceed the maximum.
783 <DT><B>--rekeymargin
</B> <I>seconds
</I><DD>
784 how long before an SA's expiration should
<B>pluto
</B> try to negotiate
785 a replacement SA. This will only happen if
<B>pluto
</B> was the initiator.
786 The default is
540 (nine minutes).
787 <DT><B>--rekeyfuzz
</B> <I>percentage
</I><DD>
788 maximum size of random component to add to rekeymargin, expressed as
789 a percentage of rekeymargin.
<B>pluto
</B> will select a delay uniformly
790 distributed within this range. By default, the percentage will be
100.
791 If greater determinism is desired, specify
0. It may be appropriate
792 for the percentage to be much larger than
100.
793 <DT><B>--keyingtries
</B> <I>count
</I><DD>
794 how many times
<B>pluto
</B> should try to negotiate an SA,
795 either for the first time or for rekeying.
796 A value of
0 is interpreted as a very large number: never give up.
797 The default is three.
798 <DT><B>--dontrekey
</B><DD>
800 Only rekey a connection if we were the Initiator and there was recent
801 traffic on the existing connection.
802 This applies to Phase
1 and Phase
2.
803 This is currently the only automatic way for a connection to terminate.
804 It may be useful with Road Warrior or Opportunistic connections.
807 Since SA lifetime negotiation is take-it-or-leave it, a Responder
808 normally uses the shorter of the negotiated or the configured lifetime.
809 This only works because if the lifetime is shorter than negotiated,
810 the Responder will rekey in time so that everything works.
811 This interacts badly with
<B>--dontrekey
</B>. In this case,
812 the Responder will end up rekeying to rectify a shortfall in an IPsec SA
813 lifetime; for an ISAKMP SA, the Responder will accept the negotiated
815 <DT><B>--delete
</B><DD>
816 when used in the connection form, it causes any previous connection
817 with this name to be deleted before this one is added. Unlike a
818 normal delete, no diagnostic is produced if there was no previous
819 connection to delete. Any routing in place for the connection is undone.
823 The delete form deletes a named connection description and any
824 SAs established or negotiations initiated using this connection.
825 Any routing in place for the connection is undone.
827 <DT><B>--delete
</B><DD>
828 <DT><B>--name
</B> <I>connection-name
</I><DD>
832 The deletestate form deletes the state object with the specified serial number.
833 This is useful for selectively deleting instances of connections.
835 <DT><B>--deletestate
</B> <I>state-number
</I><DD>
839 The route form of the
<B>whack
</B> command tells
<B>pluto
</B> to set up
840 routing for a connection.
841 Although like a traditional route, it uses an ipsec device as a
843 Once routing is set up, no packets will be
844 sent ``in the clear'' to the peer's client specified in the connection.
845 A TRAP shunt eroute will be installed; if outbound traffic is caught,
846 Pluto will initiate the connection.
847 An explicit
<B>whack
</B> route is not always needed: if it hasn't been
848 done when an IPsec SA is being installed, one will be automatically attempted.
851 When a routing is attempted for a connection, there must not already
852 be a routing for a different connection with the same subnet but different
853 interface or destination, or if
854 there is, it must not be being used by an IPsec SA. Otherwise the
857 <DT><B>--route
</B><DD>
858 <DT><B>--name
</B> <I>connection-name
</I><DD>
862 The unroute form of the
<B>whack
</B> command tells
<B>pluto
</B> to undo
863 a routing.
<B>pluto
</B> will refuse if an IPsec SA is using the connection.
864 If another connection is sharing the same routing, it will be left in place.
865 Without a routing, packets will be sent without encryption or authentication.
867 <DT><B>--unroute
</B><DD>
868 <DT><B>--name
</B> <I>connection-name
</I><DD>
872 The initiate form tells
<B>pluto
</B> to initiate a negotiation with another
873 <B>pluto
</B> (or other IKE daemon) according to the named connection.
874 Initiation requires a route that
<B>--route
</B> would provide;
875 if none is in place at the time an IPsec SA is being installed,
876 <B>pluto
</B> attempts to set one up.
878 <DT><B>--initiate
</B><DD>
879 <DT><B>--name
</B> <I>connection-name
</I><DD>
880 <DT><B>--asynchronous
<DD>
884 The initiate form of the whack
</B> command will relay back from
885 <B>pluto
</B> status information via the UNIX domain socket (unless
886 --asynchronous is specified). The status information is meant to
887 look a bit like that from
<B>FTP
</B>. Currently
<B>whack
</B> simply
888 copies this to stderr. When the request is finished (eg. the SAs are
889 established or
<B>pluto
</B> gives up),
<B>pluto
</B> closes the channel,
890 causing
<B>whack
</B> to terminate.
893 The opportunistic initiate form is mainly used for debugging.
895 <DT><B>--tunnelipv4
</B><DD>
896 <DT><B>--tunnelipv6
</B><DD>
897 <DT><B>--oppohere
</B> <I>ip-address
</I><DD>
898 <DT><B>--oppothere
</B> <I>ip-address
</I><DD>
902 This will cause
<B>pluto
</B> to attempt to opportunistically initiate a
903 connection from here to the there, even if a previous attempt
905 The whack log will show the progress of this attempt.
908 The terminate form tells
<B>pluto
</B> to delete any SAs that use the specified
909 connection and to stop any negotiations in process.
910 It does not prevent new negotiations from starting (the delete form
913 <DT><B>--terminate
</B><DD>
914 <DT><B>--name
</B> <I>connection-name
</I><DD>
918 The public key for informs
<B>pluto
</B> of the RSA public key for a potential peer.
919 Private keys must be kept secret, so they are kept in
920 <I><A HREF=
"ipsec.secrets.5.html">ipsec.secrets
</A></I>(
5).
923 <DT><B>--keyid
</B><I>id
</I><DD>
924 specififies the identity of the peer for which a public key should be used.
925 Its form is identical to the identity in the connection.
926 If no public key is specified,
<B>pluto
</B> attempts to find KEY records
927 from DNS for the id (if a FQDN) or through reverse lookup (if an IP address).
928 Note that there several interesting ways in which this is not secure.
929 <DT><B>--addkey
</B><DD>
930 specifies that the new key is added to the collection; otherwise the
931 new key replaces any old ones.
932 <DT><B>--pubkeyrsa
</B><I>key
</I><DD>
933 specifies the value of the RSA public key. It is a sequence of bytes
934 as described in RFC
2537 ``RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)''.
935 It is denoted in a way suitable for
<I><A HREF=
"ipsec_ttodata.3.html">ipsec_ttodata
</A></I>(
3).
936 For example, a base
64 numeral starts with
0s.
940 The listen form tells
<B>pluto
</B> to start listening for IKE requests
941 on its public interfaces. To avoid race conditions, it is normal to
942 load the appropriate connections into
<B>pluto
</B> before allowing it
943 to listen. If
<B>pluto
</B> isn't listening, it is pointless to
944 initiate negotiations, so it will refuse requests to do so. Whenever
945 the listen form is used,
<B>pluto
</B> looks for public interfaces and
946 will notice when new ones have been added and when old ones have been
947 removed. This is also the trigger for
<B>pluto
</B> to read the
948 <I>ipsec.secrets
</I> file. So listen may useful more than once.
950 <DT><B>--listen
</B><DD>
951 start listening for IKE traffic on public interfaces.
952 <DT><B>--unlisten
</B><DD>
953 stop listening for IKE traffic on public interfaces.
957 The status form will display information about the internal state of
958 <B>pluto
</B>: information about each potential connection, about
959 each state object, and about each shunt that
<B>pluto
</B> is managing
960 without an associated connection.
962 <DT><B>--status
</B><DD>
966 The shutdown form is the proper way to shut down
<B>pluto
</B>.
967 It will tear down the SAs on this machine that
<B>pluto
</B> has negotiated.
968 It does not inform its peers, so the SAs on their machines remain.
970 <DT><B>--shutdown
</B><DD>
972 <A NAME=
"lbAM"> </A>
977 It would be normal to start
<B>pluto
</B> in one of the system initialization
978 scripts. It needs to be run by the superuser. Generally, no arguments are needed.
979 To run in manually, the superuser can simply type
981 ipsec pluto
983 The command will immediately return, but a
<B>pluto
</B> process will be left
984 running, waiting for requests from
<B>whack
</B> or a peer.
987 Using
<B>whack
</B>, several potential connections would be described:
991 ipsec whack --name
silly
992 --host
127.0.0.1 --to --host
127.0.0.2
993 --ikelifetime
900 --ipseclifetime
800 --keyingtries
3
998 <DD>Since this silly connection description specifies neither encryption,
999 authentication, nor tunneling, it could only be used to establish
1004 ipsec whack --name
secret --host
10.0.0.1 --client
10.0.1.0/
24
1005 --to --host
10.0.0.2 --client
10.0.2.0/
24
1011 <DD>This is something that must be done on both sides. If the other
1012 side is
<B>pluto
</B>, the same
<B>whack
</B> command could be used on it
1013 (the command syntax is designed to not distinguish which end is ours).
1016 Now that the connections are specified,
<B>pluto
</B> is ready to handle
1017 requests and replies via the public interfaces. We must tell it to discover
1018 those interfaces and start accepting messages from peers:
1020 ipsec whack --listen
1023 If we don't immediately wish to bring up a secure connection between
1024 the two clients, we might wish to prevent insecure traffic.
1025 The routing form asks
<B>pluto
</B> to cause the packets sent from
1026 our client to the peer's client to be routed through the ipsec0
1027 device; if there is no SA, they will be discarded:
1029 ipsec whack --route secret
1032 Finally, we are ready to get
<B>pluto
</B> to initiate negotiation
1033 for an IPsec SA (and implicitly, an ISAKMP SA):
1035 ipsec whack --initiate
--name
secret
1037 A small log of interesting events will appear on standard output
1038 (other logging is sent to syslog).
1041 <B>whack
</B> can also be used to terminate
<B>pluto
</B> cleanly, tearing down
1042 all SAs that it has negotiated.
1044 ipsec whack --shutdown
1046 Notification of any IPSEC SA deletion, but not ISAKMP SA deletion
1047 is sent to the peer. Unfortunately, such Notification is not reliable.
1048 Furthermore,
<B>pluto
</B> itself ignores Notifications.
1049 <A NAME=
"lbAN"> </A>
1050 <H3>The updown command
</H3>
1054 Whenever
<B>pluto
</B> brings a connection up or down, it invokes
1055 the updown command. This command is specified using the
<B>--updown
</B>
1056 option. This allows for customized control over routing and firewall manipulation.
1059 The updown is invoked for five different operations. Each of
1060 these operations can be for our client subnet or for our host itself.
1062 <DT><B>prepare-host
</B> or
<B>prepare-client
</B><DD>
1063 is run before bringing up a new connection if no other connection
1064 with the same clients is up. Generally, this is useful for deleting a
1065 route that might have been set up before
<B>pluto
</B> was run or
1066 perhaps by some agent not known to
<B>pluto
</B>.
1067 <DT><B>route-host
</B> or
<B>route-client
</B><DD>
1068 is run when bringing up a connection for a new peer client subnet
1069 (even if
<B>prepare-host
</B> or
<B>prepare-client
</B> was run). The
1070 command should install a suitable route. Routing decisions are based
1071 only on the destination (peer's client) subnet address, unlike eroutes
1072 which discriminate based on source too.
1073 <DT><B>unroute-host
</B> or
<B>unroute-client
</B><DD>
1074 is run when bringing down the last connection for a particular peer
1075 client subnet. It should undo what the
<B>route-host
</B> or
<B>route-client
</B>
1077 <DT><B>up-host
</B> or
<B>up-client
</B><DD>
1078 is run when bringing up a tunnel eroute with a pair of client subnets
1079 that does not already have a tunnel eroute.
1080 This command should install firewall rules as appropriate.
1081 It is generally a good idea to allow IKE messages (UDP port
500)
1082 travel between the hosts.
1083 <DT><B>down-host
</B> or
<B>down-client
</B><DD>
1084 is run when bringing down the eroute for a pair of client subnets.
1085 This command should delete firewall rules as appropriate. Note that
1086 there may remain some inbound IPsec SAs with these client subnets.
1090 The script is passed a large number of environment variables to specify
1091 what needs to be done.
1093 <DT><B>PLUTO_VERSION
</B><DD>
1094 indicates what version of this interface is being used. This document
1095 describes version
1.1. This is upwardly compatible with version
1.0.
1096 <DT><B>PLUTO_VERB
</B><DD>
1097 specifies the name of the operation to be performed
1098 (
<B>prepare-host
</B>,r
<B>prepare-client
</B>,
1099 <B>up-host
</B>,
<B>up-client
</B>,
1100 <B>down-host
</B>, or
<B>down-client
</B>). If the address family for
1101 security gateway to security gateway communications is IPv6, then
1102 a suffix of -v6 is added to the verb.
1103 <DT><B>PLUTO_CONNECTION
</B><DD>
1104 is the name of the connection for which we are routing.
1105 <DT><B>PLUTO_NEXT_HOP
</B><DD>
1106 is the next hop to which packets bound for the peer must be sent.
1107 <DT><B>PLUTO_INTERFACE
</B><DD>
1108 is the name of the ipsec interface to be used.
1109 <DT><B>PLUTO_ME
</B><DD>
1110 is the IP address of our host.
1111 <DT><B>PLUTO_MY_CLIENT
</B><DD>
1112 is the IP address / count of our client subnet.
1113 If the client is just the host, this will be the host's own IP address / max
1114 (where max is
32 for IPv4 and
128 for IPv6).
1115 <DT><B>PLUTO_MY_CLIENT_NET
</B><DD>
1116 is the IP address of our client net.
1117 If the client is just the host, this will be the host's own IP address.
1118 <DT><B>PLUTO_MY_CLIENT_MASK
</B><DD>
1119 is the mask for our client net.
1120 If the client is just the host, this will be
255.255.255.255.
1121 <DT><B>PLUTO_PEER
</B><DD>
1122 is the IP address of our peer.
1123 <DT><B>PLUTO_PEER_CLIENT
</B><DD>
1124 is the IP address / count of the peer's client subnet.
1125 If the client is just the peer, this will be the peer's own IP address / max
1126 (where max is
32 for IPv4 and
128 for IPv6).
1127 <DT><B>PLUTO_PEER_CLIENT_NET
</B><DD>
1128 is the IP address of the peer's client net.
1129 If the client is just the peer, this will be the peer's own IP address.
1130 <DT><B>PLUTO_PEER_CLIENT_MASK
</B><DD>
1131 is the mask for the peer's client net.
1132 If the client is just the peer, this will be
255.255.255.255.
1136 All output sent by the script to stderr or stdout is logged. The
1137 script should return an exit status of
0 if and only if it succeeds.
1140 <B>Pluto
</B> waits for the script to finish and will not do any other
1141 processing while it is waiting.
1142 The script may assume that
<B>pluto
</B> will not change anything
1143 while the script runs.
1144 The script should avoid doing anything that takes much time and it
1145 should not issue any command that requires processing by
<B>pluto
</B>.
1146 Either of these activities could be performed by a background
1147 subprocess of the script.
1148 <A NAME=
"lbAO"> </A>
1153 When an SA that was initiated by
<B>pluto
</B> has only a bit of
1155 <B>pluto
</B> will initiate the creation of a new SA. This applies to
1156 ISAKMP and IPsec SAs.
1157 The rekeying will be initiated when the SA's remaining lifetime is
1158 less than the rekeymargin plus a random percentage, between
0 and
1159 rekeyfuzz, of the rekeymargin.
1162 Similarly, when an SA that was initiated by the peer has only a bit of
1163 lifetime left,
<B>pluto
</B> will try to initiate the creation of a
1165 To give preference to the initiator, this rekeying will only be initiated
1166 when the SA's remaining lifetime is half of rekeymargin.
1167 If rekeying is done by the responder, the roles will be reversed: the
1168 responder for the old SA will be the initiator for the replacement.
1169 The former initiator might also initiate rekeying, so there may
1170 be redundant SAs created.
1171 To avoid these complications, make sure that rekeymargin is generous.
1174 One risk of having the former responder initiate is that perhaps
1175 none of its proposals is acceptable to the former initiator
1176 (they have not been used in a successful negotiation).
1177 To reduce the chances of this happening, and to prevent loss of security,
1178 the policy settings are taken from the old SA (this is the case even if
1179 the former initiator is initiating).
1180 These may be stricter than those of the connection.
1183 <B>pluto
</B> will not rekey an SA if that SA is not the most recent of its
1184 type (IPsec or ISAKMP) for its potential connection.
1185 This avoids creating redundant SAs.
1188 The random component in the rekeying time (rekeyfuzz) is intended to
1189 make certain pathological patterns of rekeying unstable. If both
1190 sides decide to rekey at the same time, twice as many SAs as necessary
1191 are created. This could become a stable pattern without the
1195 Another more important case occurs when a security gateway has SAs
1196 with many other security gateways. Each of these connections might
1197 need to be rekeyed at the same time. This would cause a high peek
1198 requirement for resources (network bandwidth, CPU time, entropy for
1199 random numbers). The rekeyfuzz can be used to stagger the rekeying
1203 Once a new set of SAs has been negotiated,
<B>pluto
</B> will never send
1204 traffic on a superseded one. Traffic will be accepted on an old SA
1206 <A NAME=
"lbAP"> </A>
1207 <H3>Selecting a Connection When Responding: Road Warrior Support
</H3>
1211 When
<B>pluto
</B> receives an initial Main Mode message, it needs to
1212 decide which connection this message is for. It picks based solely on
1213 the source and destination IP addresses of the message. There might
1214 be several connections with suitable IP addresses, in which case one
1215 of them is arbitrarily chosen. (The ISAKMP SA proposal contained in
1216 the message could be taken into account, but it is not.)
1219 The ISAKMP SA is negotiated before the parties pass further
1220 identifying information, so all ISAKMP SA characteristics specified in
1221 the connection description should be the same for every connection
1222 with the same two host IP addresses. At the moment, the only
1223 characteristic that might differ is authentication method.
1227 all configuring has presumed that the IP addresses
1228 are known to all parties ahead of time. This will not work
1229 when either end is mobile (or assigned a dynamic IP address for other
1230 reasons). We call this situation ``Road Warrior''. It is fairly tricky
1231 and has some important limitations, most of which are features of
1235 Only the initiator may be mobile:
1236 the initiator may have an IP number unknown to the responder. When
1237 the responder doesn't recognize the IP address on the first Main Mode
1238 packet, it looks for a connection with itself as one end and
<B>%any
</B>
1240 If it cannot find one, it refuses to negotiate. If it
1241 does find one, it creates a temporary connection that is a duplicate
1242 except with the
<B>%any
</B> replaced by the source IP address from the
1243 packet; if there was no identity specified for the peer, the new IP
1244 address will be used.
1247 When
<B>pluto
</B> is using one of these temporary connections and
1248 needs to find the preshared secret or RSA private key in
<I>ipsec.secrets
</I>,
1249 and and the connection specified no identity for the peer,
<B>%any
</B>
1250 is used as its identity. After all, the real IP address was apparently
1251 unknown to the configuration, so it is unreasonable to require that
1252 it be used in this table.
1255 Part way into the Phase
1 (Main Mode) negotiation using one of these
1256 temporary connection descriptions,
<B>pluto
</B> will be receive an
1257 Identity Payload. At this point,
<B>pluto
</B> checks for a more
1258 appropriate connection, one with an identity for the peer that matches
1259 the payload but which would use the same keys so-far used for
1260 authentication. If it finds one, it will switch to using this better
1261 connection (or a temporary derived from this, if it has
<B>%any
</B>
1262 for the peer's IP address). It may even turn out that no connection
1263 matches the newly discovered identity, including the current connection;
1264 if so,
<B>pluto
</B> terminates negotiation.
1267 Unfortunately, if preshared secret authentication is being used, the
1268 Identity Payload is encrypted using this secret, so the secret must be
1269 selected by the responder without knowing this payload. This
1270 limits there to being at most one preshared secret for all Road Warrior
1271 systems connecting to a host. RSA Signature authentications does not
1272 require that the responder know how to select the initiator's public key
1273 until after the initiator's Identity Payload is decoded (using the
1274 responder's private key, so that must be preselected).
1277 When
<B>pluto
</B> is responding to a Quick Mode negotiation via one of these
1278 temporary connection descriptions, it may well find that the subnets
1279 specified by the initiator don't match those in the temporary
1280 connection description. If so, it will look for a connection with
1281 matching subnets, its own host address, a peer address of
<B>%any
</B>
1282 and matching identities.
1283 If it finds one, a new temporary connection is derived from this one
1284 and used for the Quick Mode negotiation of IPsec SAs. If it does not
1285 find one,
<B>pluto
</B> terminates negotiation.
1288 Be sure to specify an appropriate nexthop for the responder
1289 to send a message to the initiator:
<B>pluto
</B> has no way of guessing
1290 it (if forwarding isn't required, use an explicit
<B>%direct
</B> as the nexthop
1291 and the IP address of the initiator will be filled in; the obsolete
1292 notation
<B>0.0.0.0</B> is still accepted).
1295 <B>pluto
</B> has no special provision for the initiator side. The current
1296 (possibly dynamic) IP address and nexthop must be used in defining
1297 connections. These must be
1298 properly configured each time the initiator's IP address changes.
1299 <B>pluto
</B> has no mechanism to do this automatically.
1302 Although we call this Road Warrior Support, it could also be used to
1303 support encrypted connections with anonymous initiators. The
1304 responder's organization could announce the preshared secret that would be used
1305 with unrecognized initiators and let anyone connect. Of course the initiator's
1306 identity would not be authenticated.
1309 If any Road Warrior connections are supported,
<B>pluto
</B> cannot
1310 reject an exchange initiated by an unknown host until it has
1311 determined that the secret is not shared or the signature is invalid.
1313 third Main Mode message from the initiator. If no Road Warrior
1314 connection is supported, the first message from an unknown source
1315 would be rejected. This has implications for ease of debugging
1316 configurations and for denial of service attacks.
1319 Although a Road Warrior connection must be initiated by the mobile
1320 side, the other side can and will rekey using the temporary connection
1321 it has created. If the Road Warrior wishes to be able to disconnect,
1322 it is probably wise to set
<B>--keyingtries
</B> to
1 in the
1323 connection on the non-mobile side to prevent it trying to rekey the
1324 connection. Unfortunately, there is no mechanism to unroute the
1325 connection automatically.
1326 <A NAME=
"lbAQ"> </A>
1331 <B>pluto
</B> accepts several optional arguments, useful mostly for debugging.
1332 Except for
<B>--interface
</B>, each should appear at most once.
1334 <DT><B>--interface
</B> <I>interfacename
</I><DD>
1335 specifies that the named real public network interface should be considered.
1336 The interface name specified should not be
<B>ipsec
</B><I>N
</I>.
1337 If the option doesn't appear, all interfaces are considered.
1338 To specify several interfaces, use the option once for each.
1339 One use of this option is to specify which interface should be used
1340 when two or more share the same IP address.
1341 <DT><B>--ikeport
</B> <I>port-number
</I><DD>
1342 changes the UDP port that
<B>pluto
</B> will use
1343 (default, specified by IANA:
500)
1344 <DT><B>--ctlbase
</B> <I>path
</I><DD>
1345 basename for control files.
1346 <I>path
</I>.ctl is the socket through which
<B>whack
</B> communicates with
1348 <I>path
</I>.pid is the lockfile to prevent multiple
<B>pluto
</B> instances.
1349 The default is
<I>/var/run/pluto
</I>).
1350 <DT><B>--secretsfile
</B> <I>file
</I><DD>
1351 specifies the file for authentication secrets
1352 (default:
<I>/etc/ipsec.secrets
</I>).
1353 This name is subject to ``globbing'' as in
<I><A HREF=
"sh.1.html">sh
</A></I>(
1),
1354 so every file with a matching name is processed.
1355 Quoting is generally needed to prevent the shell from doing the globbing.
1356 <DT><B>--adns
</B> <I>pathname
</I><DD>
1357 <DT><B>--lwdnsq
</B> <I>pathname
</I><DD>
1358 specifies where to find
<B>pluto
</B>'s helper program for asynchronous DNS lookup.
1359 <B>pluto
</B> can be built to use one of two helper programs:
<B>_pluto_adns
</B>
1360 or
<B>lwdnsq
</B>. You must use the program for which it was built.
1361 By default,
<B>pluto
</B> will look for the program in
1362 <B>$IPSEC_DIR
</B> (if that environment variable is defined) or, failing that,
1363 in the same directory as
<B>pluto
</B>.
1364 <DT><B>--nofork
</B><DD>
1365 disable ``daemon fork'' (default is to fork). In addition, after the
1366 lock file and control socket are created, print the line ``Pluto
1367 initialized'' to standard out.
1368 <DT><B>--noklips
</B><DD>
1369 don't actually implement negotiated IPsec SAs
1370 <DT><B>--uniqueids
</B><DD>
1371 if this option has been selected, whenever a new ISAKMP SA is
1372 established, any connection with the same Peer ID but a different
1373 Peer IP address is unoriented (causing all its SAs to be deleted).
1374 This helps clean up dangling SAs when a connection is lost and
1375 then regained at another IP address.
1376 <DT><B>--stderrlog
</B><DD>
1377 log goes to standard out {default is to use
<I><A HREF=
"syslogd.8.html">syslogd
</A></I>(
8))
1383 <DT>pluto --secretsfile
ipsec.secrets --ctlbase
pluto.base --ikeport
8500 --nofork --noklips --stderrlog
<DD>
1387 lets one test
<B>pluto
</B> without using the superuser account.
1390 <B>pluto
</B> is willing to produce a prodigious amount of debugging
1391 information. To do so, it must be compiled with -DDEBUG. There are
1392 several classes of debugging output, and
<B>pluto
</B> may be directed to
1393 produce a selection of them. All lines of
1394 debugging output are prefixed with ``|
'' to distinguish them from error
1398 When
<B>pluto
</B> is invoked, it may be given arguments to specify
1399 which classes to output. The current options are:
1401 <DT><B>--debug-raw
</B><DD>
1402 show the raw bytes of messages
1403 <DT><B>--debug-crypt
</B><DD>
1404 show the encryption and decryption of messages
1405 <DT><B>--debug-parsing
</B><DD>
1406 show the structure of input messages
1407 <DT><B>--debug-emitting
</B><DD>
1408 show the structure of output messages
1409 <DT><B>--debug-control
</B><DD>
1410 show
<B>pluto
</B>'s decision making
1411 <DT><B>--debug-lifecycle
</B><DD>
1412 [this option is temporary] log more detail of lifecycle of SAs
1413 <DT><B>--debug-klips
</B><DD>
1414 show
<B>pluto
</B>'s interaction with
<B>KLIPS
</B>
1415 <DT><B>--debug-dns
</B><DD>
1416 show
<B>pluto
</B>'s interaction with
<B>DNS
</B> for KEY and TXT records
1417 <DT><B>--debug-oppo
</B><DD>
1418 show why
<B>pluto
</B> didn't find a suitable DNS TXT record to authorize opportunistic initiation
1419 <DT><B>--debug-all
</B><DD>
1421 <DT><B>--debug-private
</B><DD>
1422 allow debugging output with private keys.
1423 <DT><B>--debug-none
</B><DD>
1428 The debug form of the
1429 <B>whack
</B> command will change the selection in a running
1431 If a connection name is specified, the flags are added whenever
1432 <B>pluto
</B> has identified that it is dealing with that connection.
1433 Unfortunately, this is often part way into the operation being observed.
1436 For example, to start a
<B>pluto
</B> with a display of the structure of input
1440 pluto --debug-emitting --debug-parsing
1444 To later change this
<B>pluto
</B> to only display raw bytes:
1451 For testing, SSH's IKE test page is quite useful:
1454 <I><A HREF=
"http://isakmp-test.ssh.fi/">http://isakmp-test.ssh.fi/
</A></I>
1458 Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA
1459 is established. This allows future IPsec SA's to be negotiated
1460 directly. If one of the IKEs is restarted, the other may try to use
1461 the ISAKMP SA but the new IKE won't know about it. This can lead to
1462 much confusion.
<B>pluto
</B> is not yet smart enough to get out of such a
1464 <A NAME=
"lbAR"> </A>
1465 <H3>Pluto's Behaviour When Things Go Wrong
</H3>
1469 When
<B>pluto
</B> doesn't understand or accept a message, it just
1470 ignores the message. It is not yet capable of communicating the
1471 problem to the other IKE daemon (in the future it might use
1472 Notifications to accomplish this in many cases). It does log a diagnostic.
1475 When
<B>pluto
</B> gets no response from a message, it resends the same
1476 message (a message will be sent at most three times). This is
1477 appropriate: UDP is unreliable.
1480 When pluto gets a message that it has already seen, there are many
1481 cases when it notices and discards it. This too is appropriate for UDP.
1484 Combine these three rules, and you can explain many apparently
1485 mysterious behaviours. In a
<B>pluto
</B> log, retrying isn't usually the
1486 interesting event. The critical thing is either earlier (
<B>pluto
</B>
1487 got a message which it didn't like and so ignored, so it was still
1488 awaiting an acceptable message and got impatient) or on the other
1489 system (
<B>pluto
</B> didn't send a reply because it wasn't happy with
1490 the previous message).
1491 <A NAME=
"lbAS"> </A>
1496 If
<B>pluto
</B> is compiled without -DKLIPS, it negotiates Security
1497 Associations but never ask the kernel to put them in place and never
1498 makes routing changes. This allows
<B>pluto
</B> to be tested on systems
1499 without
<B>KLIPS
</B>, but makes it rather useless.
1502 Each IPsec SA is assigned an SPI, a
32-bit number used to refer to the SA.
1503 The IKE protocol lets the destination of the SA choose the SPI.
1504 The range
0 to
0xFF is reserved for IANA.
1505 <B>Pluto
</B> also avoids choosing an SPI in the range
0x100 to
0xFFF,
1506 leaving these SPIs free for manual keying.
1507 Remember that the peer, if not
<B>pluto
</B>, may well chose
1509 <A NAME=
"lbAT"> </A>
1514 This catalogue of policies may be of use when trying to configure
1515 <B>Pluto
</B> and another IKE implementation to interoperate.
1518 In Phase
1, only Main Mode is supported. We are not sure that
1519 Aggressive Mode is secure. For one thing, it does not support
1520 identity protection. It may allow more severe Denial Of Service
1524 No Informational Exchanges are supported. These are optional and
1525 since their delivery is not assured, they must not matter.
1526 It is the case that some IKE implementations won't interoperate
1527 without Informational Exchanges, but we feel they are broken.
1530 No Informational Payloads are supported. These are optional, but
1531 useful. It is of concern that these payloads are not authenticated in
1532 Phase
1, nor in those Phase
2 messages authenticated with
<A HREF=
"HASH.3.html">HASH
</A>(
3).
1535 Diffie Hellman Groups MODP
1024 and MODP
1536 (
2 and
5)
1537 Group MODP768 (
1) is not supported because it is too weak.
1539 Host authetication can be done by RSA Signatures or Pre-Shared
1542 3DES CBC (Cypher Block Chaining mode) is the only encryption
1543 supported, both for ISAKMP SAs and IPSEC SAs.
1545 MD5 and SHA1 hashing are supported for packet authentication in both
1548 The ESP, AH, or AH plus ESP are supported. If, and only if, AH and
1549 ESP are combined, the ESP need not have its own authentication
1550 component. The selection is controlled by the --encrypt and
1551 --authenticate flags.
1553 Each of these may be combined with IPCOMP Deflate compression,
1554 but only if the potential connection specifies compression and only
1555 if KLIPS is configured with IPCOMP support.
1557 The IPSEC SAs may be tunnel or transport mode, where appropriate.
1558 The --tunnel flag controls this when
<B>pluto
</B> is initiating.
1560 When responding to an ISAKMP SA proposal, the maximum acceptable
1561 lifetime is eight hours. The default is one hour. There is no
1562 minimum. The --ikelifetime flag controls this when
<B>pluto
</B>
1565 When responding to an IPSEC SA proposal, the maximum acceptable
1566 lifetime is one day. The default is eight hours. There is no
1567 minimum. The --ipseclifetime flag controls this when
<B>pluto
</B>
1570 PFS is acceptable, and will be proposed if the --pfs flag was
1571 specified. The DH group proposed will be the same as negotiated for
1574 <A NAME=
"lbAU"> </A>
1579 <B>Pluto
</B> responds to
<B>SIGHUP
</B> by issuing a suggestion that ``
<B>whack
</B>
1580 --listen'' might have been intended.
1583 <B>Pluto
</B> exits when it recieves
<B>SIGTERM
</B>.
1584 <A NAME=
"lbAV"> </A>
1585 <H2>EXIT STATUS
</H2>
1589 <B>pluto
</B> normally forks a daemon process, so the exit status is
1590 normally a very preliminary result.
1593 means that all is OK so far.
1595 means that something was wrong.
1597 means that the lock file already exists.
1601 If
<B>whack
</B> detects a problem, it will return an exit status of
1.
1602 If it received progress messages from
<B>pluto
</B>, it returns as status
1603 the value of the numeric prefix from the last such message
1604 that was not a message sent to syslog or a comment
1605 (but the prefix for success is treated as
0).
1606 Otherwise, the exit status is
0.
1607 <A NAME=
"lbAW"> </A>
1610 <I>/var/run/pluto.pid
</I>
1613 <I>/var/run/pluto.ctl
</I>
1616 <I>/etc/ipsec.secrets
</I>
1619 <I>$IPSEC_LIBDIR/_pluto_adns
</I>
1622 <I>$IPSEC_EXECDIR/lwdnsq
</I>
1626 <A NAME=
"lbAX"> </A>
1627 <H2>ENVIRONMENT
</H2>
1632 <I>IPSEC_EXECDIR
</I>
1636 <A NAME=
"lbAY"> </A>
1641 The rest of the FreeS/WAN distribution, in particular
<I><A HREF=
"ipsec.8.html">ipsec
</A></I>(
8).
1644 <I><A HREF=
"ipsec_auto.8.html">ipsec_auto
</A></I>(
8) is designed to make using
<B>pluto
</B> more pleasant.
1648 <I><A HREF=
"ipsec.secrets.5.html">ipsec.secrets
</A></I>(
5)
1650 describes the format of the secrets file.
1653 <I><A HREF=
"ipsec_atoaddr.3.html">ipsec_atoaddr
</A></I>(
3), part of the FreeS/WAN distribution, describes the
1654 forms that IP addresses may take.
1655 <I><A HREF=
"ipsec_atosubnet.3.html">ipsec_atosubnet
</A></I>(
3), part of the FreeS/WAN distribution, describes the
1656 forms that subnet specifications.
1659 For more information on IPsec, the mailing list, and the relevant
1664 <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>
1669 At the time of writing, the most relevant IETF RFCs are:
1672 RFC2409 The Internet Key Exchange (IKE)
1674 RFC2408 Internet Security Association and Key Management Protocol (ISAKMP)
1676 RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP
1680 The FreeS/WAN web site
<<A HREF=
"htp://www.freeswan.org">htp://www.freeswan.org
</A>>
1681 and the mailing lists described there.
1682 <A NAME=
"lbAZ"> </A>
1685 This code is released under the GPL terms.
1686 See the accompanying file COPYING-
2.0 for more details.
1687 The GPL does NOT apply to those pieces of code written by others
1688 which are included in this distribution, except as noted by the
1692 This software was originally written
1693 for the FreeS/WAN project
1694 <<A HREF=
"http://www.freeswan.org">http://www.freeswan.org
</A>>
1695 by Angelos D. Keromytis
1696 (
<A HREF=
"mailto:angelos@dsl.cis.upenn.edu">angelos@dsl.cis.upenn.edu
</A>), in May/June
1997, in Athens, Greece.
1697 Thanks go to John Ioannidis for his help.
1700 It is currently (
2000)
1701 being developed and maintained by D. Hugh Redelmeier
1702 (
<A HREF=
"mailto:hugh@mimosa.com">hugh@mimosa.com
</A>), in Canada. The regulations of Greece and Canada
1703 allow us to make the code freely redistributable.
1706 Kai Martius (
<A HREF=
"mailto:admin@imib.med.tu-dresden.de">admin@imib.med.tu-dresden.de
</A>) contributed the initial
1707 version of the code supporting PFS.
1710 Richard Guy Briggs
<<A HREF=
"mailto:rgb@conscoop.ottawa.on.ca">rgb@conscoop.ottawa.on.ca
</A>> and Peter Onion
1711 <<A HREF=
"mailto:ponion@srd.bt.co.uk">ponion@srd.bt.co.uk
</A>> added the PFKEY2 support.
1714 We gratefully acknowledge that we use parts of Eric Young's
<I>libdes
</I>
1715 package; see
<I>../libdes/COPYRIGHT
</I>.
1716 <A NAME=
"lbBA"> </A>
1721 is a work-in-progress. It currently has many limitations.
1722 For example, it ignores notification messages that it receives, and
1723 it generates only Delete Notifications and those only for IPSEC SAs.
1726 <B>pluto
</B> does not support the Commit Flag.
1727 The Commit Flag is a bad feature of the IKE protocol.
1728 It isn't protected -- neither encrypted nor authenticated.
1729 A man in the middle could turn it on, leading to DoS.
1730 We just ignore it, with a warning.
1731 This should let us interoperate with
1732 implementations that insist on it, with minor damage.
1735 <B>pluto
</B> does not check that the SA returned by the Responder
1736 is actually one that was proposed. It only checks that the SA is
1737 acceptable. The difference is not large, but can show up in attributes
1738 such as SA lifetime.
1741 There is no good way for a connection to be automatically terminated.
1742 This is a problem for Road Warrior and Opportunistic connections.
1743 The
<B>--dontrekey
</B> option does prevent the SAs from
1744 being rekeyed on expiry.
1745 Additonally, if a Road Warrior connection has a client subnet with a fixed IP
1746 address, a negotiation with that subnet will cause any other
1747 connection instantiations with that same subnet to be unoriented
1748 (deleted, in effect).
1749 See also the --uniqueids option for an extension of this.
1752 When
<B>pluto
</B> sends a message to a peer that has disappeared,
1753 <B>pluto
</B> receives incomplete information from the kernel, so it
1754 logs the unsatisfactory message ``some IKE message we sent has been
1755 rejected with ECONNREFUSED (kernel supplied no details)''. John
1756 Denker suggests that this command is useful for tracking down the
1757 source of these problems:
1760 <TT> </TT>tcpdump -i eth0 icmp[
0] !=
8 and icmp[
0] !=
0<BR>
1763 Substitute your public interface for eth0 if it is different.
1766 The word ``authenticate'' is used for two different features. We must
1767 authenticate each IKE peer to the other. This is an important task of
1768 Phase
1. Each packet must be authenticated, both in IKE and in IPsec,
1769 and the method for IPsec is negotiated as an AH SA or part of an ESP SA.
1770 Unfortunately, the protocol has no mechanism for authenticating the Phase
2
1774 Bugs should be reported to the
<<A HREF=
"mailto:users@lists.freeswan.org">users@lists.freeswan.org
</A>> mailing list.
1775 Caution: we cannot accept
1776 actual code from US residents, or even US citizens living outside the
1777 US, because that would bring FreeS/WAN under US export law. Some
1778 other countries cause similar problems. In general, we would prefer
1779 that you send detailed problem reports rather than code: we want
1780 FreeS/WAN to be unquestionably freely exportable, which means being
1781 very careful about where the code comes from, and for a small bug fix,
1782 that is often more time-consuming than just reinventing the fix
1787 <A NAME=
"index"> </A><H2>Index
</H2>
1789 <DT><A HREF=
"#lbAB">NAME
</A><DD>
1790 <DT><A HREF=
"#lbAC">SYNOPSIS
</A><DD>
1791 <DT><A HREF=
"#lbAD">DESCRIPTION
</A><DD>
1793 <DT><A HREF=
"#lbAE">IKE's Job
</A><DD>
1794 <DT><A HREF=
"#lbAF">Pluto
</A><DD>
1795 <DT><A HREF=
"#lbAG">Before Running Pluto
</A><DD>
1796 <DT><A HREF=
"#lbAH">Setting up
<B>KLIPS
</B> for
<B>pluto
</B></A><DD>
1797 <DT><A HREF=
"#lbAI">ipsec.secrets file
</A><DD>
1798 <DT><A HREF=
"#lbAJ">Running Pluto
</A><DD>
1799 <DT><A HREF=
"#lbAK">Pluto's Internal State
</A><DD>
1800 <DT><A HREF=
"#lbAL">Using Whack
</A><DD>
1801 <DT><A HREF=
"#lbAM">Examples
</A><DD>
1802 <DT><A HREF=
"#lbAN">The updown command
</A><DD>
1803 <DT><A HREF=
"#lbAO">Rekeying
</A><DD>
1804 <DT><A HREF=
"#lbAP">Selecting a Connection When Responding: Road Warrior Support
</A><DD>
1805 <DT><A HREF=
"#lbAQ">Debugging
</A><DD>
1806 <DT><A HREF=
"#lbAR">Pluto's Behaviour When Things Go Wrong
</A><DD>
1807 <DT><A HREF=
"#lbAS">Notes
</A><DD>
1808 <DT><A HREF=
"#lbAT">Policies
</A><DD>
1810 <DT><A HREF=
"#lbAU">SIGNALS
</A><DD>
1811 <DT><A HREF=
"#lbAV">EXIT STATUS
</A><DD>
1812 <DT><A HREF=
"#lbAW">FILES
</A><DD>
1813 <DT><A HREF=
"#lbAX">ENVIRONMENT
</A><DD>
1814 <DT><A HREF=
"#lbAY">SEE ALSO
</A><DD>
1815 <DT><A HREF=
"#lbAZ">HISTORY
</A><DD>
1816 <DT><A HREF=
"#lbBA">BUGS
</A><DD>
1819 This document was created by
1820 <A HREF=
"http://localhost/cgi-bin/man/man2html">man2html
</A>,
1821 using the manual pages.
<BR>
1822 Time:
21:
40:
18 GMT, November
11,
2003
projects / thirdparty / strongswan.git / blob