Seth Woolley's Man Viewer

pluto(8) - ipsec pluto, ipsec whack - control interface for IPSEC keying daemon - man 8 pluto

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

IPSEC_PLUTO(8)                                                  IPSEC_PLUTO(8)



NAME
       ipsec(5,8) pluto - IPsec IKE keying daemon
       ipsec(5,8) whack - control interface for IPSEC keying daemon

SYNOPSIS
       ipsec(5,8) pluto [--help] [--version] [--optionsfrom filename] [--nofork]
              [--stderrlog] [--noklips] [--uniqueids] [--interface
              interfacename] [--ikeport portnumber] [--ctlbase path]
              [--secretsfile secrets-file] [--adns pathname] [--lwdnsq
              pathname] [--perpeerlog] [--perpeerlogbase dirname]
              [--debug-none] [--debug-all] [--debug-raw] [--debug-crypt]
              [--debug-parsing] [--debug-emitting] [--debug-control]
              [--debug-lifecycle] [--debug-klips] [--debug-dns] [--debug-oppo]
              [--debug-private]

       ipsec(5,8) whack [--help] [--version]

       ipsec(5,8) whack --name connection-name
              [--id id] [--host ip-address] [--ikeport port-number]
              [--nexthop ip-address] [--client subnet] [--dnskeyondemand]
              [--updown updown]
              --to
              [--id id] [--host ip-address] [--ikeport port-number]
              [--nexthop ip-address] [--client subnet] [--dnskeyondemand]
              [--updown updown]
              [--psk] [--rsasig] [--encrypt] [--authenticate] [--compress]
              [--tunnel] [--pfs] [--disablearrivalcheck] [--ipv4] [--ipv6]
              [--tunnelipv4] [--tunnelipv6] [--ikelifetime seconds]
              [--ipseclifetime seconds] [--rekeymargin seconds]
              [--rekeyfuzz percentage] [--keyingtries count] [--dontrekey]
              [--delete] [--ctlbase path] [--optionsfrom filename]
              [--label string(3,n)]

       ipsec(5,8) whack --keyid id [--addkey] [--pubkeyrsa key] [--ctlbase path]
              [--optionsfrom filename] [--label string(3,n)]

       ipsec(5,8) whack --myid id

       ipsec(5,8) whack --listen|--unlisten [--ctlbase path]
              [--optionsfrom filename] [--label string(3,n)]

       ipsec(5,8) whack --route|--unroute --name connection-name [--ctlbase path]
              [--optionsfrom filename] [--label string(3,n)]

       ipsec(5,8) whack --initiate|--terminate --name connection-name
              [--asynchronous] [--ctlbase path] [--optionsfrom filename]
              [--label string(3,n)]

       ipsec(5,8) whack [--tunnelipv4] [--tunnelipv6] --oppohere ip-address
              --oppothere ip-address

       ipsec(5,8) whack --delete --name connection-name [--ctlbase path]
              [--optionsfrom filename] [--label string(3,n)]

       ipsec(5,8) whack --deletestate state-number [--ctlbase path]
              [--optionsfrom filename] [--label string(3,n)]

       ipsec(5,8) whack [--name connection-name] [--debug-none] [--debug-all]
              [--debug-raw] [--debug-crypt] [--debug-parsing]
              [--debug-emitting] [--debug-control] [--debug-lifecycle]
              [--debug-klips] [--debug-dns] [--debug-oppo] [--debug-private]
              [--ctlbase path] [--optionsfrom filename] [--label string(3,n)]

       ipsec(5,8) whack --status [--ctlbase path] [--optionsfrom filename]
              [--label string(3,n)]

       ipsec(5,8) whack --shutdown [--ctlbase path] [--optionsfrom filename]
              [--label string(3,n)]

DESCRIPTION
       pluto is an IKE (``IPsec Key Exchange'') daemon.  whack is an auxiliary
       program to allow requests to be made to a running pluto.

       pluto is used to automatically build shared  ``security  associations''
       on  a  system  that has IPsec, the secure IP protocol.  In other words,
       pluto can eliminate much of the work of manual keying.  The actual  se-
       cure  transmission  of  packets is the responsibility of other parts of
       the  system  (see  KLIPS,  the  companion  implementation  of   IPsec).
       ipsec_auto(8)  provides a more convenient interface to pluto and whack.

   IKE's Job
       A Security Association (SA) is an agreement between two  network  nodes
       on  how  to  process certain traffic between them.  This processing in-
       volves encapsulation, authentication, encryption, or compression.

       IKE can be deployed on a network node to  negotiate  Security  Associa-
       tions for that node.  These IKE implementations can only negotiate with
       other IKE implementations, so IKE must be on each node that is to be an
       endpoint  of  an  IKE-negotiated  Security Association.  No other nodes
       need to be running IKE.

       An IKE instance (i.e. an IKE implementation  on  a  particular  network
       node)  communicates  with another IKE instance using UDP IP packets, so
       there must be a route between the nodes in(1,8) each direction.

       The negotiation of Security Associations requires a number  of  choices
       that  involve tradeoffs between security, convenience, trust, and effi-
       ciency.  These are policy issues and are normally specified to the  IKE
       instance by the system administrator.

       IKE deals with two kinds of Security Associations.  The first part of a
       negotiation between IKE instances is to build an ISAKMP SA.  An  ISAKMP
       SA  is  used  to protect communication between the two IKEs.  IPsec SAs
       can then be built by the IKEs - these are used to  carry  protected  IP
       traffic between the systems.

       The negotiation of the ISAKMP SA is known as Phase 1.  In theory, Phase
       1 can be accomplished by a couple of different exchange types,  but  we
       only  implement  one  called  Main  Mode (we don't implement Aggressive
       Mode).

       Any negotiation under the protection of an ISAKMP SA, including the ne-
       gotiation  of IPsec SAs, is part of Phase 2.  The exchange type that we
       use to negotiate an IPsec SA is called Quick Mode.

       IKE instances must be able to authenticate each other as part of  their
       negotiation  of  an  ISAKMP SA.  This can be done by several mechanisms
       described in(1,8) the draft standards.

       IKE negotiation can be initiated by any instance with  any  other.   If
       both  can find an agreeable set(7,n,1 builtins) of characteristics for a Security Asso-
       ciation, and both recognize each others authenticity, they can set(7,n,1 builtins) up a
       Security  Association.  The standards do not specify what causes an IKE
       instance to initiate a negotiation.

       In summary, an IKE instance is prepared to automate the  management  of
       Security  Associations  in(1,8) an IPsec environment, but a number of issues
       are considered policy and are left in(1,8) the system administrator's hands.

   Pluto
       pluto  is  an  implementation of IKE.  It runs as a daemon on a network
       node.  Currently, this network node must be a LINUX system running  the
       KLIPS implementation of IPsec.

       pluto only implements a subset of IKE.  This is enough for it to inter-
       operate with other instances of pluto, and many other  IKE  implementa-
       tions.  We are working on implementing more of IKE.

       The  policy for acceptable characteristics for Security Associations is
       mostly hardwired into the code of pluto (spdb.c).  Eventually this will
       be  moved  into  a  security policy database with reasonable expressive
       power and more convenience.

       pluto uses shared secrets or RSA signatures to authenticate peers  with
       whom it is negotiating.

       pluto  initiates negotiation of a Security Association when it is manu-
       ally prodded: the program whack is run to trigger this.  It  will  also
       initiate  a  negotiation when KLIPS traps an outbound packet for Oppor-
       tunistic Encryption.

       pluto implements ISAKMP SAs itself.  After it has negotiated the  char-
       acteristics  of an IPsec SA, it directs KLIPS to implement it.  It also
       invokes a script to adjust any firewall and issue route(8) commands  to
       direct IP packets through KLIPS.

       When pluto shuts down, it closes all Security Associations.

   Before Running Pluto
       pluto  runs  as  a  daemon  with userid root.  Before running it, a few
       things must be set(7,n,1 builtins) up.

       pluto requires KLIPS, the FreeS/WAN implementation of  IPsec.   All  of
       the components of KLIPS and pluto should be installed.

       pluto  supports  multiple  public  networks (that is, networks that are
       considered insecure and thus need to have their  traffic  encrypted  or
       authenticated).   It  discovers the public interfaces to use by looking
       at all interfaces that are configured (the --interface  option  can  be
       used to limit the interfaces considered).  It does this only when whack
       tells it to --listen, so the interfaces must  be  configured  by  then.
       Each  interface  with a name of the form ipsec(5,8)[0-9] is taken as a KLIPS
       virtual(5,8) public interface.  Another network interface with the  same  IP
       address  (there  should be only one) is taken as the corresponding real
       public interface.  ifconfig(8) with the -a flag will show the name  and
       status of each network interface.

       pluto  requires  a  database of preshared secrets and RSA private keys.
       This is described in(1,8) the ipsec.secrets(5).  pluto is told of RSA public
       keys  via  whack  commands.  If the connection is Opportunistic, and no
       RSA public key is known, pluto will attempt to fetch RSA keys using the
       Domain Name System.

   Setting up KLIPS for pluto
       The  most  basic  network topology that pluto supports has two security
       gateways negotiating on behalf of client subnets.  The diagram of RGB's
       testbed is a good example (see klips/doc/rgb_setup.txt).

       The  file(1,n)  INSTALL  in(1,8) the base directory of this distribution explains
       how to start setting up the whole system, including KLIPS.

       Make sure that the security gateways have routes to each  other.   This
       is  usually  covered  by  the  default  route,  but may require issuing
       route(8) commands.  The route must go through a particular IP interface
       (we  will  assume  it is eth0, but it need not be).  The interface that
       connects the security gateway to its client must be a different one.

       It is necessary to issue a ipsec_tncfg(8) command on each gateway.  The
       required command is:

          ipsec(5,8) tncfg(5,8) --attach --virtual ipsec0 --physical eth0

       A  command  to set(7,n,1 builtins) up the ipsec0 virtual(5,8) interface will also need to be
       run.  It will have the same parameters as the command used  to  set(7,n,1 builtins)  up
       the  physical  interface  to  which  it  has  just been connected using
       ipsec_tncfg(8).

   ipsec.secrets file(1,n)
       A pluto daemon and another IKE daemon (for example, another instance of
       pluto)  must convince each other that they are who they are supposed to
       be before any negotiation can succeed.  This authentication  is  accom-
       plished by using either secrets that have been shared beforehand (manu-
       ally) or by using RSA signatures.  There are other techniques, but they
       have not been implemented in(1,8) pluto.

       The  file(1,n)  /etc/ipsec.secrets is used to keep preshared secret keys and
       RSA private keys for authentication with other IKE daemons.  For debug-
       ging,  there  is  an  argument  to the pluto command to use a different
       file.  This file(1,n) is described in(1,8) ipsec.secrets(5).

   Running Pluto
       To fire up the daemon, just type pluto (be sure to be  running  as  the
       superuser).   The default IKE port number is 500, the UDP port assigned
       by IANA for IKE Daemons.  pluto must be run by the superuser to be able
       to use the UDP 500 port.

       pluto  attempts  to create a lockfile with the name /var/run/pluto.pid.
       If the lockfile cannot be created, pluto exits - this prevents multiple
       plutos from competing  Any ``leftover'' lockfile must be removed before
       pluto will run.  pluto writes its pid into this file(1,n)  so  that  scripts
       can  find  it.  This lock will not function properly if(3,n) it is on an NFS
       volume (but sharing locks on multiple machines doesn't make sense  any-
       way).

       pluto then forks and the parent exits.  This is the conventional ``dae-
       mon fork''.  It can make debugging awkward, so there is  an  option  to
       suppress this fork.

       All  logging,  including diagnostics, is sent to syslog(2,3,5,3 Sys::Syslog)(3) with facili-
       ty=authpriv; it decides  where  to  put  these  messages  (possibly  in(1,8)
       /var/log/secure).   Since this too can make debugging awkward, there is
       an option to steer logging to stderr.

       If the --perpeerlog option is given, then pluto will open(2,3,n)  a  log  file(1,n)
       per connection. By default, this is in(1,8) /var/log/pluto/peer, in(1,8) a subdi-
       rectory formed by turning all dot (.) [IPv4} or colon (:)  [IPv6]  into
       slashes (/).

       The base directory can be changed with the --perpeerlogbase.

       Once pluto is started, it waits for requests from whack.

   Pluto's Internal State
       To  understand  how  to use pluto, it is helpful to understand a little
       about its internal state.  Furthermore, the terminology  is  needed  to
       decipher some of the diagnostic messages.

       The  (potential)  connection database describes attributes of a connec-
       tion.  These include the IP addresses of the hosts and  client  subnets
       and the security characteristics desired.  pluto requires this informa-
       tion (simply called a connection) before it can respond to a request to
       build  an  SA.  Each connection is given a name when it is created, and
       all references are made using this name.

       During the IKE exchange to build an SA, the information about the nego-
       tiation  is  represented in(1,8) a state object.  Each state object reflects
       how far the negotiation has reached.  Once the negotiation is  complete
       and  the  SA established, the state object remains to represent the SA.
       When the SA is terminated, the state object is discarded.   Each  State
       object  is given a serial number and this is used to refer to the state
       objects in(1,8) logged messages.

       Each state object corresponds to a connection and can be thought of  as
       an instantiation of that connection.  At any particular time(1,2,n), there may
       be any number of state objects corresponding to  a  particular  connec-
       tion.   Often there is one representing an ISAKMP SA and another repre-
       senting an IPsec SA.

       KLIPS hooks into the routing code in(1,8) a LINUX  kernel.   Traffic  to  be
       processed by an IPsec SA must be directed through KLIPS by routing com-
       mands.  Furthermore, the processing to be done is  specified  by  ipsec(5,8)
       eroute(5,8)(8) commands.  pluto takes the responsibility of managing both of
       these special kinds of routes.

       Each connection may be routed, and must be while it has  an  IPsec  SA.
       The  connection  specifies the characteristics of the route: the inter-
       face on this machine, the ``gateway'' (the  nexthop),  and  the  peer's
       client  subnet.   Two  connections  may not be simultaneously routed if(3,n)
       they are for the same peer's client subnet but use different interfaces
       or  gateways (pluto's logic does not reflect any advanced routing capa-
       bilities).

       Each eroute(5,8) is associated with the state object for an IPsec SA because
       it  has the particular characteristics of the SA.  Two eroutes conflict
       if(3,n) they specify the identical local  and  remote  clients  (unlike  for
       routes, the local clients are taken into account).

       When pluto needs to install a route for a connection, it must make sure
       that no conflicting route is in(1,8) use.  If another connection has a  con-
       flicting  route,  that route will be taken down, as long as there is no
       IPsec SA instantiating that connection.  If there is such an IPsec  SA,
       the attempt to install a route will fail.

       There  is  an  exception.   If  pluto, as Responder, needs to install a
       route to a fixed client subnet for a connection, and there is already a
       conflicting  route,  then  the  SAs using the route are deleted to make
       room for the new SAs.  The rationale is  that  the  new  connection  is
       probably  more current.  The need for this usually is a product of Road
       Warrior connections (these are explained later; they cannot be used  to
       initiate).

       When  pluto needs to install an eroute(5,8) for an IPsec SA (for a state ob-
       ject), first the state object's connection must be routed (if(3,n) this can-
       not  be done, the eroute(5,8) and SA will not be installed).  If a conflict-
       ing eroute(5,8) is already in(1,8) place for another connection, the  eroute(5,8)  and
       SA will not be installed (but note that the routing exception mentioned
       above may have already deleted potentially conflicting SAs).  If anoth-
       er IPsec SA for the same connection already has an eroute(5,8), all its out-
       going traffic is taken over by the new eroute.   The  incoming  traffic
       will  still  be  processed.   This  characteristic  is exploited during
       rekeying.

       All of these routing characteristics are expected change when KLIPS  is
       modified to use the firewall hooks in(1,8) the LINUX 2.4.x kernel.

   Using Whack
       whack  is  used  to  command a running pluto.  whack uses a UNIX domain
       socket(2,7,n) to speak to pluto (by default, /var/pluto.ctl).

       whack has an intricate argument syntax.  This syntax allows  many  dif-
       ferent  functions  to  be  specified.  The help form shows the usage or
       version(1,3,5) information.  The connection form gives pluto a description  of
       a  potential  connection.  The public key form informs pluto of the RSA
       public key for a potential peer.  The delete form deletes a  connection
       description  and  all  SAs  corresponding to it.  The listen(1,2,7) form tells
       pluto to start or stop listening on the public interfaces for  IKE  re-
       quests  from peers.  The route form tells pluto to set(7,n,1 builtins) up routing for a
       connection; the unroute form undoes this.  The initiate form tells plu-
       to  to  negotiate  an  SA corresponding to a connection.  The terminate
       form tells pluto to remove all SAs corresponding to a  connection,  in-
       cluding  those  being negotiated.  The status form displays the pluto's
       internal state.  The debug form tells pluto to change the selection  of
       debugging output ``on the fly''.  The shutdown(2,8) form tells pluto to shut
       down, deleting all SAs.

       Most options are specific to one of the forms, and  will  be  described
       with that form.  There are three options that apply to all forms.

       --ctlbase path
              path.ctl is used as the UNIX domain socket(2,7,n) for talking to pluto.
              This option facilitates debugging.

       --optionsfrom filename
              adds the contents of the file(1,n) to the argument list.

       --label string(3,n)
              adds the string(3,n) to all error(8,n) messages generated by whack.

       The help form of whack is self-explanatory.

       --help display the usage message.

       --version
              display the version(1,3,5) of whack.

       The connection form describes a potential connection to  pluto.   pluto
       needs to know what connections can and should be negotiated.  When plu-
       to is the initiator, it needs to know what to propose.  When  pluto  is
       the  responder, it needs to know enough to decide whether is is willing
       to set(7,n,1 builtins) up the proposed connection.

       The description of a potential connection can specify a large number of
       details.   Each connection has a unique name.  This name will appear in(1,8)
       a updown shell command, so it should not contain punctuation that would
       make the command ill-formed.

       --name connection-name

       The  topology  of  a  connection is symmetric, so to save space here is
       half a picture:

          client_subnet<-->host:ikeport<-->nexthop<---

       A similar trick is used in(1,8) the flags.  The same flag names are used for
       both ends.  Those before the --to flag describe the left side and those
       afterwards describe the right side.  When pluto  attempts  to  use  the
       connection, it decides whether it is the left side or the right side of
       the connection, based on the IP numbers of its interfaces.

       --id id
              the identity of the end.  Currently, this can be an  IP  address
              (specified  as  dotted quad or as a Fully Qualified Domain Name,
              which will be resolved immediately) or as a Fully Qualified  Do-
              main  Name  itself  (prefixed by ``@'' to signify that it should
              not be resolved), or as user@FQDN, or as the magic(4,5) value  %myid.
              Pluto  only  authenticates the identity, and does not use it for
              addressing, so, for example, an IP address need not be  the  one
              to  which  packets are to be sent.  If the option is absent, the
              identity defaults to the IP address specified by --host.   %myid
              allows  the identity to be separately specified (by the pluto or
              whack option --myid or by the ipsec.conf(5) config(1,5) setup(2,8) parame-
              ter  myid).   Otherwise,  pluto tries to guess what %myid should
              stand for: the IP address of %defaultroute, if(3,n) it  is  supported
              by  a  suitable TXT record in(1,8) the reverse domain for that IP ad-
              dress, or the system's hostname, if(3,n) it is supported by  a  suit-
              able TXT record in(1,8) its forward domain.

       --host ip-address

       --host %any

       --host %opportunistic
              the  IP address of the end (generally the public interface).  If
              pluto is to act as a responder for  IKE  negotiations  initiated
              from  unknown  IP  addresses (the ``Road Warrior'' case), the IP
              address should be specified as %any (currently, the obsolete no-
              tation  0.0.0.0  is also accepted for this).  If pluto is to op-
              portunistically initiate the connection, use %opportunistic

       --ikeport port-number
              the UDP port that IKE listens to on that host.  The  default  is
              500.   (pluto on this machine uses the port specified by its own
              command line argument, so this only affects  where  pluto  sends
              messages.)

       --nexthop ip-address
              where to route packets for the peer's client (presumably for the
              peer too, but it will not be used for  this).   When  pluto  in-
              stalls an IPsec SA, it issues a route command.  It uses the nex-
              thop as the gateway.  The default is the peer's IP address (this
              can  be  explicitly  written  as  %direct; the obsolete notation
              0.0.0.0 is accepted).   This  option  is  necessary  if(3,n)  pluto's
              host(1,5)'s interface used for sending packets to the peer is neither
              point-to-point nor directly connected to the peer.

       --client subnet
              the subnet for which the IPsec traffic will be destined.  If not
              specified, the host(1,5) will be the client.  The subnet can be spec-
              ified in(1,8) any of the forms supported by ipsec_atosubnet(3).   The
              general  form  is address/mask.  The address can be either a do-
              main name or four decimal numbers (specifying octets)  separated
              by  dots.  The most convenient form of the mask is a decimal in-
              teger, specifying the number of leading one bits  in(1,8)  the  mask.
              So,  for  example,  10.0.0.0/8 would specify the class A network
              ``Net 10''.

       --dnskeyondemand]
              specifies that when an RSA public key is needed to  authenticate
              this host(1,5), and it isn't already known, fetch it from DNS.

       --updown updown
              specifies  an  external  shell  command to be run whenever pluto
              brings up or down a connection.  The script is used to  build  a
              shell  command,  so  it  may  contain positional parameters, but
              ought not to have punctuation that  would  cause  the  resulting
              command to be ill-formed.  The default is ipsec(5,8) _updown.

       --to   separates  the  specification  of the left and right ends of the
              connection.

       The potential connection description also specifies characteristics  of
       rekeying and security.

       --psk  Propose and allow preshared secret authentication for IKE peers.
              This authentication requires that each side use the same secret.
              May be combined with --rsasig; at least one must be specified.

       --rsasig
              Propose  and  allow  RSA  signatures  for  authentication of IKE
              peers.  This authentication requires that each side have have  a
              private key of its own and know the public key of its peer.  May
              be combined with --psk; at least one must be specified.

       --encrypt
              All proposed or accepted IPsec SAs will  include  non-null  ESP.
              The actual choices of transforms are wired into pluto.

       --authenticate
              All  proposed IPsec SAs will include AH.  All accepted IPsec SAs
              will include AH or ESP with authentication.  The actual  choices
              of  transforms are wired into pluto.  Note that this has nothing
              to do with IKE authentication.

       --compress
              All proposed IPsec SAs will include IPCOMP (compression).   This
              will  be ignored if(3,n) KLIPS is not configured with IPCOMP support.

       --tunnel
              the IPsec SA should use tunneling.  Implicit if(3,n) the  SA  is  for
              clients.  Must only be used with --authenticate or --encrypt.

       --ipv4 The  host(1,5) addresses will be interpreted as IPv4 addresses.  This
              is the default.  Note that for a connection, all host(1,5)  addresses
              must  be of the same Address Family (IPv4 and IPv6 use different
              Address Families).

       --ipv6 The host(1,5) addresses (including nexthop) will  be  interpreted  as
              IPv6  addresses.  Note that for a connection, all host(1,5) addresses
              must be of the same Address Family (IPv4 and IPv6 use  different
              Address Families).

       --tunnelipv4
              The client addresses will be interpreted as IPv4 addresses.  The
              default is to match what the host(1,5) will be.  This does not  imply
              --tunnel  so the flag can be safely used when no tunnel is actu-
              ally specified.  Note that for a connection, all tunnel address-
              es must be of the same Address Family.

       --tunnelipv6
              The client addresses will be interpreted as IPv6 addresses.  The
              default is to match what the host(1,5) will be.  This does not  imply
              --tunnel  so the flag can be safely used when no tunnel is actu-
              ally specified.  Note that for a connection, all tunnel address-
              es must be of the same Address Family.

       --pfs  There  should  be  Perfect Forward Secrecy - new keying material
              will be generated for each IPsec SA rather  than  being  derived
              from  the ISAKMP SA keying material.  Since the group to be used
              cannot be negotiated (a dubious feature of the standard),  pluto
              will  propose  the  same group that was used during Phase 1.  We
              don't implement a stronger form of PFS which would require  that
              the ISAKMP SA be deleted after the IPSEC SA is negotiated.

       --disablearrivalcheck
              If  the  connection  is a tunnel, allow packets arriving through
              the tunnel to have any source and destination addresses.

       If none of the --encrypt, --authenticate, --compress, or --pfs flags is
       given, the initiating the connection will only build an ISAKMP SA.  For
       such a connection, client subnets have no meaning and must not be spec-
       ified.

       More  work  is needed to allow for flexible policies.  Currently policy
       is hardwired in(1,8) the source file(1,n) spdb.c.  The ISAKMP SAs may use  Oakley
       groups  MODP1024  and MODP1536; 3DES encryption; SHA1-96 and MD5-96 au-
       thentication.  The IPsec SAs may use 3DES and  MD5-96  or  SHA1-96  for
       ESP,  or  just  MD5-96 or SHA1-96 for AH.  IPCOMP Compression is always
       Deflate.

       --ikelifetime seconds
              how long pluto will propose that an  ISAKMP  SA  be  allowed  to
              live.   The  default is 3600 (one hour) and the maximum is 28800
              (8 hours).  This option will not affect what is accepted.  pluto
              will reject proposals that exceed the maximum.

       --ipseclifetime seconds
              how long pluto will propose that an IPsec SA be allowed to live.
              The default is 28800 (eight hours) and the maximum is 86400 (one
              day).  This option will not affect what is accepted.  pluto will
              reject proposals that exceed the maximum.

       --rekeymargin seconds
              how long before an SA's expiration should pluto try to negotiate
              a  replacement  SA.  This will only happen if(3,n) pluto was the ini-
              tiator.  The default is 540 (nine minutes).

       --rekeyfuzz percentage
              maximum size of random(3,4,6) component  to  add  to  rekeymargin,  ex-
              pressed as a percentage of rekeymargin.  pluto will select(2,7,2 select_tut) a de-
              lay uniformly distributed within this range.   By  default,  the
              percentage  will  be  100.   If  greater determinism is desired,
              specify 0.  It may be appropriate for the percentage to be  much
              larger than 100.

       --keyingtries count
              how  many  times pluto should try to negotiate an SA, either for
              the first time(1,2,n) or for rekeying.  A value of 0 is interpreted  as
              a very large number: never give up.  The default is three.

       --dontrekey
              A  misnomer.   Only  rekey a connection if(3,n) we were the Initiator
              and there was recent traffic on the existing  connection.   This
              applies  to Phase 1 and Phase 2.  This is currently the only au-
              tomatic way for a connection to terminate.   It  may  be  useful
              with Road Warrior or Opportunistic connections.
              Since  SA lifetime negotiation is take-it-or-leave it, a Respon-
              der normally uses the shorter of the negotiated or  the  config-
              ured  lifetime.   This  only  works  because  if(3,n) the lifetime is
              shorter than negotiated, the Responder will  rekey  in(1,8)  time(1,2,n)  so
              that  everything  works.  This interacts badly with --dontrekey.
              In this case, the Responder will end up rekeying  to  rectify  a
              shortfall in(1,8) an IPsec SA lifetime; for an ISAKMP SA, the Respon-
              der will accept(2,8) the negotiated lifetime.

       --delete
              when used in(1,8) the connection form, it causes any previous connec-
              tion with this name to be deleted before this one is added.  Un-
              like a normal delete, no diagnostic is produced if(3,n) there was  no
              previous  connection  to  delete.   Any routing in(1,8) place for the
              connection is undone.

       The delete form deletes a named(5,8) connection description and any SAs  es-
       tablished or negotiations initiated using this connection.  Any routing
       in(1,8) place for the connection is undone.

       --delete

       --name connection-name

       The deletestate form deletes the state object with the specified serial
       number.   This  is useful for selectively deleting instances of connec-
       tions.

       --deletestate state-number

       The route form of the whack command tells pluto to set(7,n,1 builtins) up routing for a
       connection.  Although like a traditional route, it uses an ipsec(5,8) device
       as a virtual(5,8) interface.  Once routing is set(7,n,1 builtins) up,  no  packets  will  be
       sent ``in(1,8) the clear(1,3x,3x clrtobot)'' to the peer's client specified in(1,8) the connection.
       A TRAP shunt eroute(5,8) will be installed; if(3,n) outbound traffic  is  caught,
       Pluto will initiate the connection.  An explicit whack route is not al-
       ways needed: if(3,n) it hasn't been done when  an  IPsec  SA  is  being  in-
       stalled, one will be automatically attempted.

       When a routing is attempted for a connection, there must not already be
       a routing for a different connection with the same subnet but different
       interface  or destination, or if(3,n) there is, it must not be being used by
       an IPsec SA.  Otherwise the attempt will fail.

       --route

       --name connection-name

       The unroute form of the whack command tells pluto to  undo  a  routing.
       pluto  will  refuse if(3,n) an IPsec SA is using the connection.  If another
       connection is sharing the same routing,  it  will  be  left  in(1,8)  place.
       Without a routing, packets will be sent without encryption or authenti-
       cation.

       --unroute

       --name connection-name

       The initiate form tells pluto to initiate a  negotiation  with  another
       pluto (or other IKE daemon) according to the named(5,8) connection.  Initia-
       tion requires a route that --route would provide; if(3,n) none is  in(1,8)  place
       at  the  time(1,2,n) an IPsec SA is being installed, pluto attempts to set(7,n,1 builtins) one
       up.

       --initiate

       --name connection-name

       --asynchronous

       The initiate form of the whack command will relay back from pluto  sta-
       tus  information  via  the UNIX domain socket(2,7,n) (unless --asynchronous is
       specified).  The status information is meant to look(1,8,3 Search::Dict) a  bit  like  that
       from  FTP.  Currently whack simply copies this to stderr.  When the re-
       quest is finished (eg. the SAs are established or pluto gives up), plu-
       to closes the channel, causing whack to terminate.

       The opportunistic initiate form is mainly used for debugging.

       --tunnelipv4

       --tunnelipv6

       --oppohere ip-address

       --oppothere ip-address

       This  will  cause pluto to attempt to opportunistically initiate a con-
       nection from here to the there, even if(3,n) a  previous  attempt  had  been
       made.  The whack log will show the progress of this attempt.

       The terminate form tells pluto to delete any SAs that use the specified
       connection and to stop any negotiations in(1,8) process.  It does  not  pre-
       vent  new negotiations from starting (the delete form has this effect).

       --terminate

       --name connection-name

       The public key for informs pluto of the RSA public key for a  potential
       peer.   Private keys must be kept secret, so they are kept in(1,8) ipsec.se-
       crets(5).

       --keyid id
              specififies the identity of the peer  for  which  a  public  key
              should  be  used.   Its form is identical to the identity in(1,8) the
              connection.  If no public key is specified,  pluto  attempts  to
              find  KEY records from DNS for the id (if(3,n) a FQDN) or through re-
              verse lookup (if(3,n) an IP address).  Note that there several inter-
              esting ways in(1,8) which this is not secure.

       --addkey
              specifies that the new key is added to the collection; otherwise
              the new key replaces any old ones.

       --pubkeyrsa key
              specifies the value of the RSA public key.  It is a sequence  of
              bytes  as  described  in(1,8) RFC 2537 ``RSA/MD5 KEYs and SIGs in(1,8) the
              Domain Name System (DNS)''.  It is denoted in(1,8) a way suitable for
              ipsec_ttodata(3).   For  example,  a base 64 numeral starts with
              0s.

       The listen(1,2,7) form tells pluto to start listening for IKE requests on  its
       public  interfaces.  To avoid race conditions, it is normal to load(7,n) the
       appropriate connections into pluto before allowing it  to  listen.   If
       pluto  isn't listening, it is pointless to initiate negotiations, so it
       will refuse requests to do so.  Whenever the listen(1,2,7) form is used, pluto
       looks  for  public  interfaces  and will notice when new ones have been
       added and when old ones have been removed.  This is  also  the  trigger
       for  pluto  to  read(2,n,1 builtins) the ipsec.secrets file.  So listen(1,2,7) may useful more
       than once.

       --listen
              start listening for IKE traffic on public interfaces.

       --unlisten
              stop listening for IKE traffic on public interfaces.

       The status form will display information about the  internal  state  of
       pluto:  information  about  each potential connection, about each state
       object, and about each shunt that pluto is managing without an  associ-
       ated connection.

       --status

       The  shutdown(2,8)  form is the proper way to shut down pluto.  It will tear
       down the SAs on this machine that pluto has negotiated.   It  does  not
       inform its peers, so the SAs on their machines remain.

       --shutdown

   Examples
       It  would  be normal to start pluto in(1,8) one of the system initialization
       scripts.  It needs to be run by the superuser.  Generally, no arguments
       are needed.  To run in(1,8) manually, the superuser can simply type

          ipsec(5,8) pluto

       The  command  will immediately return, but a pluto process will be left
       running, waiting for requests from whack or a peer.

       Using whack, several potential connections would be described:

          ipsec(5,8) whack --name silly --host 127.0.0.1 --to --host 127.0.0.2
              --ikelifetime 900 --ipseclifetime 800 --keyingtries 3

       Since  this  silly connection description specifies neither encryption,
       authentication, nor tunneling, it could only be used  to  establish  an
       ISAKMP SA.

          ipsec(5,8) whack --name secret --host 10.0.0.1 --client 10.0.1.0/24 --to
              --host 10.0.0.2 --client 10.0.2.0/24 --encrypt

       This is something that must be done on both sides.  If the  other  side
       is  pluto, the same whack command could be used on it (the command syn-
       tax is designed to not distinguish which end is ours).

       Now that the connections are specified, pluto is ready  to  handle  re-
       quests  and replies via the public interfaces.  We must tell it to dis-
       cover(1,3,5) those interfaces and start accepting messages from peers:

          ipsec(5,8) whack --listen

       If we don't immediately wish to bring up a  secure  connection  between
       the  two clients, we might wish to prevent insecure traffic.  The rout-
       ing form asks pluto to cause the packets sent from our  client  to  the
       peer's  client  to  be routed through the ipsec0 device; if(3,n) there is no
       SA, they will be discarded:

          ipsec(5,8) whack --route secret

       Finally, we are ready to get pluto to initiate negotiation for an IPsec
       SA (and implicitly, an ISAKMP SA):

          ipsec(5,8) whack --initiate --name secret

       A small log of interesting events will appear on standard output (other
       logging is sent to syslog(2,3,5,3 Sys::Syslog)).

       whack can also be used to terminate pluto cleanly, tearing down all SAs
       that it has negotiated.

          ipsec(5,8) whack --shutdown

       Notification  of  any  IPSEC SA deletion, but not ISAKMP SA deletion is
       sent to the peer.  Unfortunately, such Notification  is  not  reliable.
       Furthermore, pluto itself ignores Notifications.

   The updown command
       Whenever  pluto  brings  a connection up or down, it invokes the updown
       command.  This command is specified using the  --updown  option.   This
       allows for customized control over routing and firewall manipulation.

       The updown is invoked for five different operations.  Each of these op-
       erations can be for our client subnet or for our host(1,5) itself.

       prepare-host or prepare-client
              is run before bringing up a new connection if(3,n) no  other  connec-
              tion with the same clients is up.  Generally, this is useful for
              deleting a route that might have been set(7,n,1 builtins) up  before  pluto  was
              run or perhaps by some agent not known to pluto.

       route-host or route-client
              is  run when bringing up a connection for a new peer client sub-
              net (even if(3,n) prepare-host or prepare-client was run).  The  com-
              mand  should  install  a  suitable route.  Routing decisions are
              based only on the destination (peer's  client)  subnet  address,
              unlike eroutes which discriminate based on source too.

       unroute-host or unroute-client
              is  run  when bringing down the last connection for a particular
              peer client subnet.  It  should  undo  what  the  route-host  or
              route-client did.

       up-host or up-client
              is  run  when  bringing up a tunnel eroute(5,8) with a pair of client
              subnets that does not already have a tunnel eroute.   This  com-
              mand should install firewall rules as appropriate.  It is gener-
              ally a good idea to allow IKE messages (UDP port 500) travel be-
              tween the hosts.

       down-host or down-client
              is  run  when bringing down the eroute(5,8) for a pair of client sub-
              nets.  This command should delete firewall rules as appropriate.
              Note  that  there  may  remain some inbound IPsec SAs with these
              client subnets.

       The script is passed a large number of environment variables to specify
       what needs to be done.

       PLUTO_VERSION
              indicates  what  version(1,3,5)  of this interface is being used.  This
              document describes version(1,3,5) 1.1.   This  is  upwardly  compatible
              with version(1,3,5) 1.0.

       PLUTO_VERB
              specifies  the  name  of the operation to be performed (prepare-
              host(1,5),r prepare-client, up-host, up-client, down-host,  or  down-
              client).  If the address family for security gateway to security
              gateway communications is IPv6, then a suffix of -v6 is added to
              the verb.

       PLUTO_CONNECTION
              is the name of the connection for which we are routing.

       PLUTO_NEXT_HOP
              is  the  next  hop  to  which packets bound for the peer must be
              sent.

       PLUTO_INTERFACE
              is the name of the ipsec(5,8) interface to be used.

       PLUTO_ME
              is the IP address of our host.

       PLUTO_MY_CLIENT
              is the IP address / count of our client subnet.  If  the  client
              is  just  the host(1,5), this will be the host(1,5)'s own IP address / max
              (where max is 32 for IPv4 and 128 for IPv6).

       PLUTO_MY_CLIENT_NET
              is the IP address of our client net.  If the client is just  the
              host(1,5), this will be the host(1,5)'s own IP address.

       PLUTO_MY_CLIENT_MASK
              is the mask for our client net.  If the client is just the host(1,5),
              this will be 255.255.255.255.

       PLUTO_PEER
              is the IP address of our peer.

       PLUTO_PEER_CLIENT
              is the IP address / count of the peer's client subnet.   If  the
              client  is just the peer, this will be the peer's own IP address
              / max (where max is 32 for IPv4 and 128 for IPv6).

       PLUTO_PEER_CLIENT_NET
              is the IP address of the peer's client net.  If  the  client  is
              just the peer, this will be the peer's own IP address.

       PLUTO_PEER_CLIENT_MASK
              is  the  mask  for the peer's client net.  If the client is just
              the peer, this will be 255.255.255.255.

       All output sent by the script to  stderr  or  stdout  is  logged.   The
       script should return an exit(3,n,1 builtins) status of 0 if(3,n) and only if(3,n) it succeeds.

       Pluto waits for the script to finish and will not do any other process-
       ing while it is waiting.  The script may assume  that  pluto  will  not
       change  anything  while the script runs.  The script should avoid doing
       anything that takes much time(1,2,n) and it should not issue any command  that
       requires processing by pluto.  Either of these activities could be per-
       formed by a background subprocess of the script.

   Rekeying
       When an SA that was initiated by pluto has only a bit of lifetime left,
       pluto  will  initiate the creation of a new SA.  This applies to ISAKMP
       and IPsec SAs.  The rekeying will be initiated when the SA's  remaining
       lifetime is less(1,3) than the rekeymargin plus a random(3,4,6) percentage, between
       0 and rekeyfuzz, of the rekeymargin.

       Similarly, when an SA that was initiated by the peer has only a bit  of
       lifetime  left,  pluto  will try to initiate the creation of a replace-
       ment.  To give preference to the initiator, this rekeying will only  be
       initiated  when the SA's remaining lifetime is half of rekeymargin.  If
       rekeying is done by the responder, the roles will be reversed: the  re-
       sponder  for the old SA will be the initiator for the replacement.  The
       former initiator might also initiate rekeying, so there may  be  redun-
       dant  SAs created.  To avoid these complications, make sure that rekey-
       margin is generous.

       One risk of having the former responder initiate is that  perhaps  none
       of  its  proposals is acceptable to the former initiator (they have not
       been used in(1,8) a successful negotiation).  To reduce the chances of  this
       happening,  and  to  prevent  loss of security, the policy settings are
       taken from the old SA (this is the case even if(3,n) the former initiator is
       initiating).  These may be stricter than those of the connection.

       pluto  will  not  rekey  an SA if(3,n) that SA is not the most recent of its
       type (IPsec or ISAKMP) for its potential connection.  This avoids  cre-
       ating redundant SAs.

       The  random(3,4,6)  component  in(1,8) the rekeying time(1,2,n) (rekeyfuzz) is intended to
       make certain pathological patterns of rekeying unstable.  If both sides
       decide  to  rekey  at the same time(1,2,n), twice as many SAs as necessary are
       created.  This could become a stable pattern without the randomness.

       Another more important case occurs when a security gateway has SAs with
       many  other security gateways.  Each of these connections might need to
       be rekeyed at the same time.  This would cause a high peek  requirement
       for  resources  (network  bandwidth,  CPU time(1,2,n), entropy for random(3,4,6) num-
       bers).  The rekeyfuzz can be used to stagger the rekeying times.

       Once a new set(7,n,1 builtins) of SAs has been negotiated, pluto will never send(2,n)  traf-
       fic  on  a superseded one.  Traffic will be accepted on an old SA until
       it expires.

   Selecting a Connection When Responding: Road Warrior Support
       When pluto receives an initial Main Mode message, it  needs  to  decide
       which  connection  this  message  is for.  It picks based solely on the
       source and destination IP addresses of the  message.   There  might  be
       several  connections  with  suitable IP addresses, in(1,8) which case one of
       them is arbitrarily chosen.  (The ISAKMP SA proposal contained  in(1,8)  the
       message could be taken into account, but it is not.)

       The ISAKMP SA is negotiated before the parties pass further identifying
       information, so all ISAKMP SA characteristics specified in(1,8) the  connec-
       tion  description should be the same for every connection with the same
       two host(1,5) IP addresses.  At the moment,  the  only  characteristic  that
       might differ is authentication method.

       Up  to  this  point, all configuring has presumed that the IP addresses
       are known to all parties ahead of time.  This will not work when either
       end is mobile (or assigned a dynamic IP address for other reasons).  We
       call this situation ``Road Warrior''.  It is fairly tricky and has some
       important  limitations, most of which are features of the IKE protocol.

       Only the initiator may be mobile: the initiator may have an  IP  number
       unknown  to the responder.  When the responder doesn't recognize the IP
       address on the first Main Mode packet, it looks for a  connection  with
       itself as one end and %any as the other.  If it cannot find one, it re-
       fuses to negotiate.  If it does find one, it creates a  temporary  con-
       nection that is a duplicate except with the %any replaced by the source
       IP address from the packet; if(3,n) there was no identity specified for  the
       peer, the new IP address will be used.

       When  pluto  is  using  one of these temporary connections and needs to
       find the preshared secret or RSA private key in(1,8) ipsec.secrets, and  and
       the  connection specified no identity for the peer, %any is used as its
       identity.  After all, the real IP address was apparently unknown to the
       configuration, so it is unreasonable to require that it be used in(1,8) this
       table.

       Part way into the Phase 1 (Main Mode) negotiation using  one  of  these
       temporary  connection  descriptions,  pluto will be receive an Identity
       Payload.  At this point, pluto checks for a  more  appropriate  connec-
       tion,  one  with  an identity for the peer that matches the payload but
       which would use the same keys so-far used for  authentication.   If  it
       finds  one, it will switch(1,n) to using this better connection (or a tempo-
       rary derived from this, if(3,n) it has %any for the peer's IP address).   It
       may even turn out that no connection matches the newly discovered iden-
       tity, including the current connection; if(3,n) so, pluto terminates negoti-
       ation.

       Unfortunately,  if(3,n)  preshared  secret authentication is being used, the
       Identity Payload is encrypted using this secret, so the secret must  be
       selected  by  the  responder without knowing this payload.  This limits
       there to being at most one preshared secret for all Road  Warrior  sys-
       tems  connecting to a host.  RSA Signature authentications does not re-
       quire that the responder know how to select(2,7,2 select_tut) the initiator's public  key
       until  after the initiator's Identity Payload is decoded (using the re-
       sponder's private key, so that must be preselected).

       When pluto is responding to a Quick Mode negotiation via one  of  these
       temporary  connection  descriptions,  it may well find that the subnets
       specified by the initiator don't match those in(1,8) the  temporary  connec-
       tion  description.   If so, it will look(1,8,3 Search::Dict) for a connection with matching
       subnets, its own host(1,5) address, a peer  address  of  %any  and  matching
       identities.   If  it  finds  one, a new temporary connection is derived
       from this one and used for the Quick Mode negotiation of IPsec SAs.  If
       it does not find one, pluto terminates negotiation.

       Be  sure  to specify an appropriate nexthop for the responder to send(2,n) a
       message to the initiator: pluto has no way of guessing it (if(3,n)  forward-
       ing  isn't  required, use an explicit %direct as the nexthop and the IP
       address of the initiator will  be  filled  in(1,8);  the  obsolete  notation
       0.0.0.0 is still accepted).

       pluto  has  no  special  provision for the initiator side.  The current
       (possibly dynamic) IP address and nexthop must be used in(1,8) defining con-
       nections.   These must be properly configured each time(1,2,n) the initiator's
       IP address changes.  pluto has no mechanism to do this automatically.

       Although we call this Road Warrior Support, it could also  be  used  to
       support  encrypted  connections with anonymous initiators.  The respon-
       der's organization could announce the preshared secret  that  would  be
       used  with  unrecognized  initiators and let anyone connect.  Of course
       the initiator's identity would not be authenticated.

       If any Road Warrior connections are supported, pluto cannot  reject  an
       exchange  initiated by an unknown host(1,5) until it has determined that the
       secret is not shared or the signature is invalid.  This must await  the
       third Main Mode message from the initiator.  If no Road Warrior connec-
       tion is supported, the first message from an unknown  source  would  be
       rejected.   This  has implications for ease of debugging configurations
       and for denial of service attacks.

       Although a Road Warrior connection must  be  initiated  by  the  mobile
       side,  the other side can and will rekey using the temporary connection
       it has created.  If the Road Warrior wishes to be able  to  disconnect,
       it  is probably wise to set(7,n,1 builtins) --keyingtries to 1 in(1,8) the connection on the
       non-mobile side to prevent it trying to rekey the connection.  Unfortu-
       nately,  there is no mechanism to unroute the connection automatically.

   Debugging
       pluto accepts several optional arguments, useful mostly for  debugging.
       Except for --interface, each should appear at most once.

       --interface interfacename
              specifies that the named(5,8) real public network interface should be
              considered.  The interface name specified should not be  ipsec(5,8)N.
              If the option doesn't appear, all interfaces are considered.  To
              specify several interfaces, use the option once for  each.   One
              use  of this option is to specify which interface should be used
              when two or more share the same IP address.

       --ikeport port-number
              changes the UDP port that pluto will use (default, specified  by
              IANA: 500)

       --ctlbase path
              basename(1,3,3 File::Basename)  for  control  files.   path.ctl  is the socket(2,7,n) through
              which whack communicates with pluto.  path.pid is  the  lockfile
              to   prevent   multiple   pluto   instances.    The  default  is
              /var/run/pluto).

       --secretsfile file(1,n)
              specifies  the  file(1,n)  for   authentication   secrets   (default:
              /etc/ipsec.secrets).  This name is subject to ``globbing'' as in(1,8)
              sh(1), so every file(1,n) with a matching name is processed.  Quoting
              is  generally  needed  to prevent the shell from doing the glob-
              bing.

       --adns pathname

       --lwdnsq pathname
              specifies where to find pluto's helper program for  asynchronous
              DNS  lookup.   pluto  can be built to use one of two helper pro-
              grams: _pluto_adns or lwdnsq.  You  must  use  the  program  for
              which it was built.  By default, pluto will look(1,8,3 Search::Dict) for the program
              in(1,8) $IPSEC_DIR (if(3,n) that  environment  variable  is  defined)  or,
              failing that, in(1,8) the same directory as pluto.

       --nofork
              disable  ``daemon fork'' (default is to fork).  In addition, af-
              ter the lock file(1,n) and control socket(2,7,n) are created, print the line
              ``Pluto initialized'' to standard out.

       --noklips
              don't actually implement negotiated IPsec SAs

       --uniqueids
              if(3,n)  this  option  has been selected, whenever a new ISAKMP SA is
              established, any connection with the same Peer ID but a  differ-
              ent  Peer  IP  address  is unoriented (causing all its SAs to be
              deleted).  This helps clean up dangling SAs when a connection is
              lost and then regained at another IP address.

       --stderrlog
              log goes to standard out {default is to use syslogd(8))

       For example

       pluto  --secretsfile ipsec.secrets  --ctlbase pluto.base --ikeport 8500
       --nofork --noklips --stderrlog

       lets one test pluto without using the superuser account.

       pluto  is  willing to produce a prodigious amount of debugging informa-
       tion.  To do so, it must be compiled with -DDEBUG.  There  are  several
       classes of debugging output, and pluto may be directed to produce a se-
       lection of them.  All lines  of  debugging  output  are  prefixed  with
       ``| '' to distinguish them from error(8,n) messages.

       When  pluto  is  invoked,  it  may  be given arguments to specify which
       classes to output.  The current options are:

       --debug-raw
              show the raw(3x,7,8,3x cbreak) bytes of messages

       --debug-crypt
              show the encryption and decryption of messages

       --debug-parsing
              show the structure of input messages

       --debug-emitting
              show the structure of output messages

       --debug-control
              show pluto's decision making

       --debug-lifecycle
              [this option is temporary] log more detail of lifecycle of SAs

       --debug-klips
              show pluto's interaction with KLIPS

       --debug-dns
              show pluto's interaction with DNS for KEY and TXT records

       --debug-oppo
              show why pluto didn't find a suitable DNS TXT record  to  autho-
              rize opportunistic initiation

       --debug-all
              all of the above

       --debug-private
              allow debugging output with private keys.

       --debug-none
              none of the above

       The debug form of the whack command will change the selection in(1,8) a run-
       ning pluto.  If a connection name is specified,  the  flags  are  added
       whenever  pluto has identified that it is dealing with that connection.
       Unfortunately, this is often part way  into  the  operation  being  ob-
       served.

       For  example, to start a pluto with a display of the structure of input
       and output:

              pluto --debug-emitting --debug-parsing

       To later change this pluto to only display raw(3x,7,8,3x cbreak) bytes:

              whack --debug-raw

       For testing, SSH's IKE test page is quite useful:

              http://isakmp-test.ssh.fi/

       Hint: ISAKMP SAs are often kept alive by IKEs even after the  IPsec  SA
       is established.  This allows future IPsec SA's to be negotiated direct-
       ly.  If one of the IKEs is restarted, the other  may  try  to  use  the
       ISAKMP  SA  but the new IKE won't know about it.  This can lead to much
       confusion.  pluto is not yet smart enough to get out of such a mess.

   Pluto's Behaviour When Things Go Wrong
       When pluto doesn't understand or accept(2,8) a message, it just ignores  the
       message.   It  is  not  yet capable of communicating the problem to the
       other IKE daemon (in(1,8) the future it might use  Notifications  to  accom-
       plish this in(1,8) many cases).  It does log a diagnostic.

       When pluto gets(3,n) no response from a message, it resends the same message
       (a message will be sent at most three times).  This is appropriate: UDP
       is unreliable.

       When pluto gets(3,n) a message that it has already seen, there are many cas-
       es when it notices and discards it.  This too is appropriate for UDP.

       Combine these three rules, and you can explain many apparently mysteri-
       ous behaviours.  In a pluto log, retrying isn't usually the interesting
       event.  The critical thing is either earlier (pluto got a message which
       it  didn't  like and so ignored, so it was still awaiting an acceptable
       message and got impatient) or on the other system (pluto didn't send(2,n)  a
       reply because it wasn't happy with the previous message).

   Notes
       If  pluto  is compiled without -DKLIPS, it negotiates Security Associa-
       tions but never ask the kernel to put them in(1,8)  place  and  never  makes
       routing  changes.   This  allows  pluto to be tested on systems without
       KLIPS, but makes it rather useless.

       Each IPsec SA is assigned an SPI, a 32-bit number used to refer to  the
       SA.   The  IKE  protocol lets the destination of the SA choose the SPI.
       The range 0 to 0xFF is reserved for IANA.  Pluto also  avoids  choosing
       an  SPI in(1,8) the range 0x100 to 0xFFF, leaving these SPIs free for manual
       keying.  Remember that the peer, if(3,n) not pluto, may well chose  SPIs  in(1,8)
       this range.

   Policies
       This catalogue of policies may be of use when trying to configure Pluto
       and another IKE implementation to interoperate.

       In Phase 1, only Main Mode is supported.  We are not sure that  Aggres-
       sive  Mode is secure.  For one thing, it does not support identity pro-
       tection.  It may allow more severe Denial Of Service attacks.

       No Informational Exchanges are supported.  These are optional and since
       their  delivery  is  not assured, they must not matter.  It is the case
       that some IKE implementations won't interoperate without  Informational
       Exchanges, but we feel they are broken.

       No  Informational Payloads are supported.  These are optional, but use-
       ful.  It is of concern that these payloads  are  not  authenticated  in(1,8)
       Phase 1, nor in(1,8) those Phase 2 messages authenticated with HASH(3).

        Diffie  Hellman Groups MODP 1024 and MODP 1536 (2 and 5) are support-
         ed.  Group MODP768 (1) is not supported because it is too weak.

        Host authetication can be done by RSA Signatures  or  Pre-Shared  Se-
         crets.

        3DES CBC (Cypher Block Chaining mode) is the only encryption support-
         ed, both for ISAKMP SAs and IPSEC SAs.

        MD5 and SHA1 hashing are supported for packet authentication in(1,8)  both
         kinds of SAs.

        The  ESP,  AH, or AH plus ESP are supported.  If, and only if(3,n), AH and
         ESP are combined, the ESP need not have its own authentication compo-
         nent.   The  selection is controlled by the --encrypt and --authenti-
         cate flags.

        Each of these may be combined with IPCOMP  Deflate  compression,  but
         only  if(3,n)  the  potential connection specifies compression and only if(3,n)
         KLIPS is configured with IPCOMP support.

        The IPSEC SAs may be tunnel or  transport  mode,  where  appropriate.
         The --tunnel flag controls this when pluto is initiating.

        When  responding  to  an  ISAKMP  SA proposal, the maximum acceptable
         lifetime is eight hours.  The default is one hour.  There is no mini-
         mum.   The --ikelifetime flag controls this when pluto is initiating.

        When responding to an IPSEC SA proposal, the maximum acceptable life-
         time(1,2,n)  is  one day.  The default is eight hours.  There is no minimum.
         The --ipseclifetime flag controls this when pluto is initiating.

        PFS is acceptable, and will be proposed if(3,n) the --pfs flag was  speci-
         fied.  The DH group proposed will be the same as negotiated for Phase
         1.

SIGNALS
       Pluto responds to SIGHUP by issuing a suggestion  that  ``whack  --lis-
       ten'' might have been intended.

       Pluto exits when it recieves SIGTERM.

EXIT STATUS
       pluto normally forks a daemon process, so the exit(3,n,1 builtins) status is normally a
       very preliminary result.

       0      means that all is OK so far.

       1      means that something was wrong.

       10     means that the lock file(1,n) already exists.

       If whack detects a problem, it will return an exit(3,n,1 builtins) status of 1.  If  it
       received  progress  messages from pluto, it returns as status the value
       of the numeric prefix from the last such message that was not a message
       sent  to  syslog(2,3,5,3 Sys::Syslog) or a comment (but the prefix for success is treated as
       0).  Otherwise, the exit(3,n,1 builtins) status is 0.

FILES
       /var/run/pluto.pid
       /var/run/pluto.ctl
       /etc/ipsec.secrets
       $IPSEC_LIBDIR/_pluto_adns
       $IPSEC_EXECDIR/lwdnsq
       /dev/urandom

ENVIRONMENT
       IPSEC_LIBDIR
       IPSEC_EXECDIR
       IPSECmyid

SEE ALSO
       The rest of the FreeS/WAN distribution, in(1,8) particular ipsec(5,8)(8).

       ipsec_auto(8) is designed to make using pluto more pleasant.  Use it!

       ipsec.secrets(5) describes the format of the secrets file.

       ipsec_atoaddr(3), part of the  FreeS/WAN  distribution,  describes  the
       forms  that  IP  addresses  may  take.  ipsec_atosubnet(3), part of the
       FreeS/WAN distribution, describes the forms that subnet specifications.

       For more information on IPsec, the mailing list, and the relevant docu-
       ments, see:

              http://www.ietf.cnri.reston.va.us/html.charters/ipsec-
              charter.html

       At the time(1,2,n) of writing, the most relevant IETF RFCs are:

              RFC2409 The Internet Key Exchange (IKE)

              RFC2408  Internet Security Association and Key Management Proto-
              col (ISAKMP)

              RFC2407 The Internet IP Security Domain  of  Interpretation  for
              ISAKMP

       The  FreeS/WAN  web site <htp://www.freeswan.org> and the mailing lists
       described there.

HISTORY
       This code is released under the GPL terms.  See the  accompanying  file(1,n)
       COPYING-2.0  for  more details.  The GPL does NOT apply to those pieces
       of code written by others which are included in(1,8) this distribution,  ex-
       cept as noted by the individual authors.

       This   software  was  originally  written  for  the  FreeS/WAN  project
       <http://www.freeswan.org>    by    Angelos    D.    Keromytis    (ange-
       los@dsl.cis.upenn.edu), in(1,8) May/June 1997, in(1,8) Athens, Greece.  Thanks go
       to John Ioannidis for his help.

       It is currently (2000) being developed and maintained by  D.  Hugh  Re-
       delmeier  (hugh@mimosa.com),  in(1,8) Canada.  The regulations of Greece and
       Canada allow us to make the code freely redistributable.

       Kai Martius (admin@imib.med.tu-dresden.de) contributed the initial ver-
       sion(1,3,5) of the code supporting PFS.

       Richard   Guy   Briggs   <rgb@conscoop.ottawa.on.ca>  and  Peter  Onion
       <ponion@srd.bt.co.uk> added the PFKEY2 support.

       We gratefully acknowledge that we use  parts  of  Eric  Young's  libdes
       package; see ../libdes/COPYRIGHT.

BUGS
       pluto  is  a work-in-progress.  It currently has many limitations.  For
       example, it ignores notification messages that it receives, and it gen-
       erates only Delete Notifications and those only for IPSEC SAs.

       pluto  does not support the Commit Flag.  The Commit Flag is a bad fea-
       ture of the IKE protocol.  It isn't protected -- neither encrypted  nor
       authenticated.   A  man(1,5,7) in(1,8) the middle could turn it on, leading to DoS.
       We just ignore it, with a warning.  This  should  let  us  interoperate
       with implementations that insist on it, with minor damage.

       pluto  does not check that the SA returned by the Responder is actually
       one that was proposed.  It only checks that the SA is acceptable.   The
       difference is not large, but can show up in(1,8) attributes such as SA life-
       time.

       There is no good way for a connection to be  automatically  terminated.
       This  is a problem for Road Warrior and Opportunistic connections.  The
       --dontrekey option does prevent the SAs from being rekeyed  on  expiry.
       Additonally,  if(3,n)  a  Road Warrior connection has a client subnet with a
       fixed IP address, a negotiation with that subnet will cause  any  other
       connection  instantiations  with  that  same  subnet  to  be unoriented
       (deleted, in(1,8) effect).  See also the --uniqueids option for an extension
       of this.

       When  pluto  sends  a message to a peer that has disappeared, pluto re-
       ceives incomplete information from the kernel, so it logs the  unsatis-
       factory message ``some IKE message we sent has been rejected with ECON-
       NREFUSED (kernel supplied no details)''.   John  Denker  suggests  that
       this command is useful for tracking down the source of these problems:
            tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0
       Substitute your public interface for eth0 if(3,n) it is different.

       The  word ``authenticate'' is used for two different features.  We must
       authenticate each IKE peer to the other.  This is an important task  of
       Phase  1.  Each packet must be authenticated, both in(1,8) IKE and in(1,8) IPsec,
       and the method for IPsec is negotiated as an AH SA or part  of  an  ESP
       SA.   Unfortunately,  the  protocol has no mechanism for authenticating
       the Phase 2 identities.

       Bugs should be reported to the <users(1,5)@lists.freeswan.org> mailing list.
       Caution:  we  cannot  accept(2,8)  actual code from US residents, or even US
       citizens living outside the US, because that would bring FreeS/WAN  un-
       der  US  export  law.  Some other countries cause similar problems.  In
       general, we would prefer that you send(2,n) detailed problem reports  rather
       than  code:   we want FreeS/WAN to be unquestionably freely exportable,
       which means being very careful about where the code comes from, and for
       a  small bug fix, that is often more time-consuming than just reinvent-
       ing the fix ourselves.



                                 28 March 1999                  IPSEC_PLUTO(8)

References for this manual (incoming links)