<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<!-- lifted from troff+man by doclifter -->
<refentry id="pluto8">
<refentryinfo>
  <author><firstname>Paul</firstname><surname>Wouters</surname><authorblurb><para>placeholder to suppress warning</para> </authorblurb></author>
</refentryinfo>
  <refmeta>
    <refentrytitle>IPSEC_PLUTO</refentrytitle>

    <manvolnum>8</manvolnum>

    <refmiscinfo class="date">29 June 2014</refmiscinfo>
<refmiscinfo class="source">libreswan</refmiscinfo>
<refmiscinfo class="manual">Executable programs</refmiscinfo>
  </refmeta>

  <refnamediv id="name">
    <refname>ipsec pluto</refname>
    <refname>ipsec whack</refname>
    <refname>pluto</refname>

    <refpurpose>ipsec whack : IPsec IKE keying daemon and control interface</refpurpose>
  </refnamediv>

  <!-- body begins here -->

  <refsynopsisdiv id="synopsis">
    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>pluto</replaceable></arg>
      <arg choice="opt">--help</arg>
      <arg choice="opt">--version</arg>
      <arg choice="opt">--leak-detective</arg>
      <arg choice="opt">--efence-protect</arg>
      <arg choice="opt">--config <replaceable>filename</replaceable></arg>
      <arg choice="opt">--vendorid <replaceable>VID</replaceable></arg>
      <arg choice="opt">--nofork</arg>
      <arg choice="opt">--stderrlog</arg>
      <arg choice="opt">--logfile <replaceable>filename</replaceable></arg>
      <arg choice="opt">--log-no-time</arg>
      <arg choice="opt">--log-no-append</arg>
      <arg choice="opt">--log-no-ip</arg>
      <arg choice="opt">--log-no-audit</arg>
      <arg choice="opt">--use-netkey</arg>
      <arg choice="opt">--use-bsdkame</arg>
      <arg choice="opt">--uniqueids</arg>
      <arg choice="opt">--virtual-private <replaceable>network_list</replaceable></arg>
      <arg choice="opt">--keep-alive <replaceable>delay_sec</replaceable></arg>
      <arg choice="opt">--force-busy</arg>
      <arg choice="opt">--crl-strict</arg>
      <arg choice="opt">--crlcheckinterval</arg>
      <arg choice="opt">--interface <replaceable>interfacename</replaceable></arg>
      <arg choice="opt">--listen <replaceable>ipaddr</replaceable></arg>
      <arg choice="opt">--ikeport <replaceable>portnumber</replaceable></arg>
      <arg choice="opt">--natikeport <replaceable>portnumber</replaceable></arg>
      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--secretsfile <replaceable>secrets-file</replaceable></arg>
      <arg choice="opt">--nhelpers <replaceable>number</replaceable></arg>
      <arg choice="opt">--seedbits <replaceable>numbits</replaceable></arg>
      <arg choice="opt">--ipsecdir <replaceable>dirname</replaceable></arg>
      <arg choice="opt">--nssdir <replaceable>dirname</replaceable></arg>
      <arg choice="opt">--coredir <replaceable>dirname</replaceable></arg>
      <arg choice="opt">--statsbin <replaceable>filename</replaceable></arg>
      <arg choice="opt">--secctx-attr-type <replaceable>number</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="opt">--help</arg>

      <arg choice="opt">--version</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--name
      <replaceable>connection-name</replaceable></arg>

      <group choice="opt">
        <arg choice="opt">--ipv4</arg>

        <arg choice="opt">--ipv6</arg>
      </group>

      <group choice="opt">
        <arg choice="opt">--tunnelipv4</arg>

        <arg choice="opt">--tunnelipv6</arg>
      </group>

      <sbr />

      <arg choice="opt">--id <replaceable>identity</replaceable></arg>

      <arg choice="opt">--host <replaceable>ip-address</replaceable></arg>

      <arg choice="opt">--cert <replaceable>friendly_name</replaceable></arg>

      <arg choice="opt">--ckaid <replaceable>CKAID</replaceable></arg>

      <arg choice="opt">--ca <replaceable>distinguished
      name</replaceable></arg>

      <arg choice="opt">--groups <replaceable>access control
      groups</replaceable></arg>

      <arg choice="opt">--sendcert <group choice="plain">
          <arg choice="plain">yes</arg>

          <arg choice="plain">forced</arg>

          <arg choice="plain">always</arg>

          <arg choice="plain">ifasked</arg>

          <arg choice="plain">no</arg>

          <arg choice="plain">never</arg>
        </group></arg>

      <arg choice="opt">--sendca <group choice="plain">
          <arg choice="plain">none</arg>

          <arg choice="plain">issuer</arg>

          <arg choice="plain">all</arg>
        </group></arg>

      <arg choice="opt">--certtype <replaceable>number</replaceable></arg>

      <arg choice="opt">--ikeport <replaceable>portnumber</replaceable></arg>

      <arg choice="opt">--nexthop <replaceable>ip-address</replaceable></arg>

      <group choice="opt">
        <arg choice="opt">--client <replaceable>subnet</replaceable></arg>
      </group>

      <arg choice="opt">--clientprotoport
      <replaceable>protocol</replaceable>/<replaceable>port</replaceable></arg>

      <arg choice="opt">--srcip <replaceable>ip-address</replaceable></arg>

      <arg choice="opt">--xauthserver</arg>

      <arg choice="opt">--xauthclient</arg>

      <arg choice="opt">--modecfgserver</arg>

      <arg choice="opt">--modecfgclient</arg>

      <arg choice="opt">--modecfgdns <replaceable>ip-address, ip-address, ...</replaceable></arg>

      <arg choice="opt">--modecfgdomains <replaceable>DNS-domain, DNS-domain, ...</replaceable></arg>
      <arg choice="opt">--modecfgbanner <replaceable>login-banner</replaceable></arg>

      <arg choice="opt">--dnskeyondemand</arg>

      <arg choice="opt">--updown <replaceable>updown</replaceable></arg>

      <sbr />

      <arg choice="plain">--to</arg>

      <sbr />

      <arg choice="opt">--id <replaceable>identity</replaceable></arg>

      <arg choice="opt">--host <replaceable>ip-address</replaceable></arg>

      <arg choice="opt">--cert <replaceable>friendly_name</replaceable></arg>

      <arg choice="opt">--ckaid <replaceable>CKAID</replaceable></arg>

      <arg choice="opt">--ca <replaceable>distinguished
      name</replaceable></arg>

      <arg choice="opt">--groups <replaceable>access control
      groups</replaceable></arg>

      <arg choice="opt">--sendcert <group choice="plain">
          <arg choice="plain">yes</arg>

          <arg choice="plain">always</arg>

          <arg choice="plain">ifasked</arg>

          <arg choice="plain">no</arg>

          <arg choice="plain">never</arg>
        </group></arg>

      <arg choice="opt">--certtype <replaceable>number</replaceable></arg>

      <arg choice="opt">--ikeport <replaceable>port-number</replaceable></arg>

      <arg choice="opt">--nexthop <replaceable>ip-address</replaceable></arg>

      <arg choice="opt">--client <replaceable>subnet</replaceable></arg>

      <arg choice="opt">--clientprotoport
      <replaceable>protocol</replaceable>/<replaceable>port</replaceable></arg>

      <arg choice="opt">--srcip <replaceable>ip-address</replaceable></arg>

      <arg choice="opt">--xauthserver</arg>

      <arg choice="opt">--xauthclient</arg>

      <arg choice="opt">--modecfgserver</arg>

      <arg choice="opt">--modecfgclient</arg>

      <arg choice="opt">--modecfgdns <replaceable>ip-address, ip-address, ...</replaceable></arg>

      <arg choice="opt">--modecfgdomains <replaceable>DNS-domain, DNS-domain, ...</replaceable></arg>

      <arg choice="opt">--dnskeyondemand</arg>

      <arg choice="opt">--updown <replaceable>updown</replaceable></arg>

      <sbr />

      <sbr />

      <arg choice="opt">--tunnel</arg>

      <arg choice="opt">--psk</arg>

      <arg choice="opt">--rsasig</arg>

      <arg choice="opt">--encrypt</arg>

      <arg choice="opt">--authenticate</arg>

      <arg choice="opt">--compress</arg>

      <arg choice="opt">--pfs</arg>

      <arg choice="opt">--pfsgroup <group choice="plain">
          <arg choice="opt">modp1024</arg>

          <arg choice="opt">modp1536</arg>

          <arg choice="opt">modp2048</arg>

          <arg choice="opt">modp3072</arg>

          <arg choice="opt">modp4096</arg>

          <arg choice="opt">modp6144</arg>

          <arg choice="opt">modp8192</arg>

          <arg choice="opt">dh22</arg>

          <arg choice="opt">dh23</arg>

          <arg choice="opt">dh24</arg>
        </group></arg>

      <arg choice="opt">--ikelifetime <replaceable>seconds</replaceable></arg>

      <arg choice="opt">--ipseclifetime
      <replaceable>seconds</replaceable></arg>

      <arg choice="opt">--rekeymargin <replaceable>seconds</replaceable></arg>

      <arg choice="opt">--rekeyfuzz
      <replaceable>percentage</replaceable></arg>

      <arg choice="opt">--keyingtries <replaceable>count</replaceable></arg>

      <arg choice="opt">--esp <replaceable>esp-algos</replaceable></arg>

      <arg choice="opt">--dontrekey</arg>

      <arg choice="opt">--aggrmode</arg>

      <arg choice="opt">--modecfgpull</arg>

      <arg choice="opt">--metric <replaceable>metric</replaceable></arg>

      <arg choice="opt">--nflog-group <replaceable>nflognum</replaceable></arg>

      <arg choice="opt">--conn-mark <replaceable>mark/mask</replaceable></arg>

      <group choice="opt">
        <arg choice="opt">--dpddelay <replaceable>seconds</replaceable></arg>

        <arg choice="opt">--dpdtimeout
        <replaceable>seconds</replaceable></arg>
      </group>

      <arg choice="opt">--dpdaction <group choice="plain">
          <arg choice="opt">clear</arg>

          <arg choice="opt">hold</arg>

          <arg choice="opt">restart</arg>
        </group></arg>

      <arg choice="opt">--forceencaps</arg>
      <arg choice="opt">--no-keep-alive</arg>

      <arg choice="opt"><group choice="plain">
          <arg choice="opt">--initiateontraffic</arg>

          <arg choice="opt">--pass</arg>

          <arg choice="opt">--drop</arg>

          <arg choice="opt">--reject</arg>
        </group></arg>

      <arg choice="opt"><group choice="plain">
          <arg choice="opt">--failnone</arg>

          <arg choice="opt">--failpass</arg>

          <arg choice="opt">--faildrop</arg>

          <arg choice="opt">--failreject</arg>
        </group></arg>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--keyid <replaceable>id</replaceable></arg>

      <arg choice="opt">--addkey</arg>

      <arg choice="opt">--pubkeyrsa <replaceable>key</replaceable></arg>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <group choice="plain">
        <arg choice="plain">--listen</arg>
        <arg choice="plain">--unlisten</arg>
      </group>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <group choice="plain">
        <arg choice="plain">--ddos-auto</arg>
        <arg choice="plain">--ddos-busy</arg>
        <arg choice="plain">--ddos-unlimited</arg>
      </group>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <group choice="plain">
        <arg choice="plain">--route</arg>

        <arg choice="plain">--unroute</arg>
      </group>

      <arg choice="plain">--name
      <replaceable>connection-name</replaceable></arg>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <group choice="plain">
        <arg choice="plain">--initiate</arg>
          <arg choice="opt">--remote-host <replaceable>ip-address</replaceable></arg>

        <arg choice="plain">--terminate</arg>
        <arg choice="plain">--rekey-ike</arg>
        <arg choice="plain">--rekey-ipsec</arg>
      </group>

      <arg choice="plain">--name
      <replaceable>connection-name</replaceable></arg>

      <arg choice="opt">--xauthuser <replaceable>user</replaceable></arg>

      <arg choice="opt">--xauthpass <replaceable>pass</replaceable></arg>

      <arg choice="opt">--asynchronous</arg>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--global-redirect
      <replaceable>yes|no|auto</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--global-redirect-to
      <replaceable>ip-address(es)</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="opt">
	--name
	<replaceable>connection-name</replaceable>
      </arg>

      <arg choice="plain">--redirect-to
      <replaceable>ip-address(es)</replaceable></arg>

    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <group choice="opt">
        <arg choice="opt">--tunnelipv4</arg>

        <arg choice="opt">--tunnelipv6</arg>
      </group>

      <arg choice="plain">--oppohere
      <replaceable>ip-address</replaceable></arg>

      <arg choice="plain">--oppothere
      <replaceable>ip-address</replaceable></arg>

      <arg choice="plain">--opposport
      <replaceable>port</replaceable></arg>

      <arg choice="plain">--oppodport
      <replaceable>port</replaceable></arg>

      <arg choice="plain">--oppoproto
      <replaceable>protocol</replaceable></arg>

    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--crash</arg>

      <arg choice="opt">ipaddress</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--name
      <replaceable>connection-name</replaceable></arg>

      <arg choice="plain">--delete</arg>

      <arg choice="opt">--ctlbase <replaceable>path</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--deletestate
      <replaceable>state-number</replaceable></arg>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--deleteuser</arg>
      <arg choice="plain">--name
      <replaceable>username</replaceable></arg>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="opt">
	--name
	<replaceable>connection-name</replaceable>
      </arg>

      <group choice="plain">
	<arg choice="req">
	  --debug
	  <group choice="plain">
	    <arg choice="plain">help</arg>
	    <arg choice="plain">none</arg>
	    <arg choice="plain">base</arg>
	    <arg choice="plain">cpu-usage</arg>
	    <arg choice="plain"><replaceable>class</replaceable></arg>
	  </group>
	</arg>
	<arg choice="req">
	  --no-debug <replaceable>class</replaceable>
	</arg>
	<arg choice="req">
	  --impair
	  <group choice="plain">
	    <arg choice="plain">help</arg>
	    <arg choice="plain">none</arg>
	    <!-- <arg choice="plain">list|show?</arg> -->
	    <arg choice="plain"><replaceable>behaviour</replaceable></arg>
	  </group>
	</arg>
	<arg choice="req">
	  --no-impair <replaceable>behaviour</replaceable>
	</arg>
      </group>

    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="opt">--utc</arg>

      <arg choice="opt">--listall</arg>

      <arg choice="opt">--listpubkeys</arg>

      <arg choice="opt">--listcerts</arg>

      <arg choice="opt">--listcacerts</arg>

      <arg choice="opt">--listcrls</arg>

    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="opt">--utc</arg>

      <arg choice="opt">--rereadsecrets</arg>
      <arg choice="opt">--fetchcrls</arg>
      <arg choice="opt">--rereadall</arg>

    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--ddns</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--listevents</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--purgeocsp</arg>
    </cmdsynopsis>


    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--status</arg>
      <arg choice="plain">--trafficstatus</arg>
      <arg choice="plain">--shuntstatus</arg>
      <arg choice="plain">--addresspoolstatus</arg>
      <arg choice="plain">--processstatus</arg>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--globalstats</arg>
      <arg choice="plain">--clearstats</arg>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="opt">--ike-socket-bufsize <replaceable>bufsize</replaceable></arg>
      <arg choice="opt">--ike-socket-errqueue-toggle</arg>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>

      <arg choice="opt">--label <replaceable>string</replaceable></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>ipsec</command>

      <arg choice="plain"><replaceable>whack</replaceable></arg>

      <arg choice="plain">--shutdown</arg>

      <arg choice="opt">--rundir <replaceable>path</replaceable></arg>
      <arg choice="opt">--ctlsocket <replaceable>path/file</replaceable></arg>
      <arg choice="opt">--label <replaceable>string</replaceable></arg>
      <arg choice="opt">--leave-state</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="description">
    <title>DESCRIPTION</title>

    <para><emphasis remap="B">pluto</emphasis> is an IKE ("IPsec Key
    Exchange") daemon. <emphasis remap="B">whack</emphasis> is an auxiliary
    program to allow requests to be made to a running <emphasis
    remap="B">pluto</emphasis>.</para>

    <para><emphasis remap="B">pluto</emphasis> is used to automatically build
    shared "security associations" on a system that has IPsec, the secure IP
    protocol. In other words, <emphasis remap="B">pluto</emphasis> can
    eliminate much of the work of manual keying. The actual secure
    transmission of packets is the responsibility of other parts of the system
    - the kernel. Pluto can talk to various kernel implementations, such as the Linux
    <emphasis remap="B">XFRM</emphasis> and BSD <emphasis remap="B">KAME</emphasis>
    IPsec stacks. <citerefentry>
        <refentrytitle>ipsec_auto</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry> provides a more convenient interface to <emphasis
    remap="B">pluto</emphasis> and <emphasis
    remap="B">whack</emphasis>.</para>

    <refsect2 id="ikes_job">
      <title>IKE's Job</title>

      <para>A <emphasis remap="I">Security Association</emphasis> (<emphasis
      remap="I">SA</emphasis>) is an agreement between two network nodes on
      how to process certain traffic between them. This processing involves
      encapsulation, authentication, encryption, or compression.</para>

      <para>IKE can be deployed on a network node to negotiate Security
      Associations 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.</para>

      <para>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 each
      direction.</para>

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

      <para>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.</para>

      <para>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.
      Currently, Main Mode and Aggressive Mode are implemented.</para>

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

      <para>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 the draft standards.</para>

      <para>IKE negotiation can be initiated by any instance with any other.
      If both can find an agreeable set of characteristics for a Security
      Association, and both recognize each others authenticity, they can set
      up a Security Association. The standards do not specify what causes an
      IKE instance to initiate a negotiation.</para>

      <para>In summary, an IKE instance is prepared to automate the management
      of Security Associations in an IPsec environment, but a number of issues
      are considered policy and are left in the system administrator's
      hands.</para>
    </refsect2>

    <refsect2 id="pluto">
      <title>Pluto</title>

      <para><emphasis remap="B">pluto</emphasis> 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 <emphasis remap="B">XFRM</emphasis> IPsec
      stack, or a FreeBSD/NetBSD/Mac OSX system running the <emphasis
      remap="B">KAME</emphasis> IPsec stack.</para>

      <para><emphasis remap="B">pluto</emphasis> implements a large subset of
      IKEv1 and IKEv2.</para>

      <para>The policy for acceptable characteristics for Security
      Associations is mostly hardwired into the code of <emphasis
      remap="B">pluto</emphasis> (spdb.c). Eventually this will be moved into
      a security policy database with reasonable expressive power and more
      convenience.</para>

      <para><emphasis remap="B">pluto</emphasis> uses shared secrets or RSA
      signatures to authenticate peers with whom it is negotiating. These RSA
      signatures can come from DNS(SEC), a configuration file, or from X.509
      and CA certificates.</para>

      <para><emphasis remap="B">pluto</emphasis> initiates negotiation of a
      Security Association when it is manually prodded: the program <emphasis
      remap="B">whack</emphasis> is run to trigger this. It will also initiate
      a negotiation when IPsec traps an outbound packet for Opportunistic Encryption.</para>

      <para><emphasis remap="B">pluto</emphasis> implements ISAKMP SAs itself.
      After it has negotiated the characteristics of an IPsec SA, it directs
      the <emphasis remap="B">kernel</emphasis> to implement it. If necessary,
      it also invokes a script to adjust any firewall and issue <citerefentry>
          <refentrytitle>route</refentrytitle>

          <manvolnum>8</manvolnum>
        </citerefentry> commands to direct IP packets.</para>

      <para>When <emphasis remap="B">pluto</emphasis> shuts down, it closes
      all Security Associations.</para>
    </refsect2>

    <refsect2 id="before_running_pluto">
      <title>Before Running Pluto</title>

      <para><emphasis remap="B">pluto</emphasis> runs as a daemon with userid
      root. Before running it, a few things must be set up.</para>

      <para><emphasis remap="B">pluto</emphasis> requires a working IPsec
      stack.</para>

      <para><emphasis remap="B">pluto</emphasis> 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 <option>--interface</option> option can be used to limit
      the interfaces considered). It does this only when <emphasis
      remap="B">whack</emphasis> tells it to --listen, so the interfaces must
      be configured by then. The <option>--listen</option> can be used to limit listening on
      only 1 IP address of a certain interface. <citerefentry>
          <refentrytitle>ifconfig</refentrytitle>

          <manvolnum>8</manvolnum>
        </citerefentry> or <citerefentry>
          <refentrytitle>ip</refentrytitle>

          <manvolnum>8</manvolnum>
        </citerefentry> with the <option>-a</option> flag will show the name
      and status of each network interface.</para>

      <para><emphasis remap="B">pluto</emphasis> requires a database of
      preshared secrets and RSA private keys. This is described in the
      <citerefentry>
          <refentrytitle>ipsec.secrets</refentrytitle>

          <manvolnum>5</manvolnum>
        </citerefentry>. <emphasis remap="B">pluto</emphasis> is told of RSA
      public keys via <emphasis remap="B">whack</emphasis> commands. If the
      connection is Opportunistic, and no RSA public key is known, <emphasis
      remap="B">pluto</emphasis> will attempt to fetch RSA keys using the
      Domain Name System.</para>
    </refsect2>

    <refsect2 id="setting_up_netkey_for_pluto">
      <title>Setting up <emphasis remap="B">XFRM</emphasis> for <emphasis
      remap="B">pluto</emphasis></title>

      <para>No special requirements are necessary to use XFRM - it ships
      with all modern versions of Linux 2.4 and later.
      </para>
    </refsect2>

    <refsect2 id="ipsecsecrets_file">
      <title>ipsec.secrets file</title>

      <para>A <emphasis remap="B">pluto</emphasis> daemon and another IKE
      daemon (for example, another instance of <emphasis
      remap="B">pluto</emphasis>) must convince each other that they are who
      they are supposed to be before any negotiation can succeed. This
      authentication is accomplished by using either secrets that have been
      shared beforehand (manually) or by using RSA signatures. There are other
      techniques, but they have not been implemented in <emphasis
      remap="B">pluto</emphasis>.</para>

      <para>The file <filename>@IPSEC_SECRETS_FILE@</filename> is used
      to keep preshared secret keys and XAUTH passwords. RSA private
      keys, X.509 certificates, CRLs, OCSP and smartcards are handled
      via NSS. For debugging, there is an argument to the <emphasis
      remap="B">pluto</emphasis> command to use a different file. This
      file is described in
      <citerefentry><refentrytitle>ipsec.secrets</refentrytitle>

          <manvolnum>5</manvolnum>
        </citerefentry>.</para>
    </refsect2>

    <refsect2 id="running_pluto">
      <title>Running Pluto</title>

      <para>To fire up the daemon, just type <emphasis
      remap="B">pluto</emphasis> (be sure to be running as the superuser). The
      default IKE port number is 500, the UDP port assigned by IANA for IKE
      Daemons. <emphasis remap="B">pluto</emphasis> must be run by the
      superuser to be able to use the UDP 500 port. If pluto is told to enable
      NAT-Traversal, then UDP port 4500 is also taken by pluto to listen
      on.</para>

      <para>
	Pluto supports different IPstacks on different operating
	systems.  This can be configured using one of the options
	<option>--use-netkey</option> (Linux),
	<option>--use-bsdkame</option> (BSD).  On startup, pluto might
	also read the <option>protostack=</option> option to select
	the IPsec stack to use if <option>--config
	/etc/ipsec.conf</option> is given as argument to pluto.  If
	both <option>--use-XXX</option> and <option>--config
	/etc/ipsec.conf</option> are specified, the last command line
	argument specified takes precedence.
      </para>

      <para>Pluto supports RFC 3947 NAT-Traversal. The allowed range behind the NAT routers is submitted using the
      <option>--virtual-private</option> option. See <citerefentry>
          <refentrytitle>ipsec.conf</refentrytitle>

          <manvolnum>5</manvolnum>
        </citerefentry> for the syntax. The option
      <option>--force-keepalive</option> forces the sending of the <emphasis
      remap="I">keep-alive packets</emphasis>, which are send to prevent the
      NAT router from closing its port when there is not enough traffic on the
      IPsec connection. The <option>--keep-alive</option> sets the delay (in
      seconds) of these keep-alive packets. The newer NAT-T standards support
      <emphasis remap="I">port floating</emphasis>, and Libreswan enables this
      per default.</para>

      <para>Pluto supports the use of X.509 certificates and sends certificates
      when needed. Pluto uses NSS for all X.509 related data, including CAcerts,
      certs, CRLs and private keys. The <emphasis remap="I">Certificate Revocation Lists</emphasis>
      can also be retrieved from an URL. The option <option>--crlcheckinterval</option>
      sets the time between checking for CRL expiration and issuing new fetch commands.
      The first attempt to update a CRL is started at <emphasis
      remap="I">2*crlcheckinterval</emphasis> before the next update time.
      Pluto logs a warning if no valid CRL was loaded or obtained for a
      connection. If <option>--crl-strict</option> is given, the
      connection will be rejected until a valid CRL has been loaded.
      </para>

      <para>Pluto can also use helper children to off-load cryptographic
      operations. This behavior can be fine tuned using the
      <option>--nhelpers</option>. Pluto will start <emphasis
      remap="I">(n-1)</emphasis> of them, where <emphasis
      remap="I">n</emphasis> is the number of CPU's you have (including
      hypherthreaded CPU's). A value of <emphasis remap="I">0</emphasis>
      forces pluto to do all operations in the main process. A value of
      <emphasis remap="I">-1</emphasis> tells pluto to perform the above
      calculation. Any other value forces the number to that amount.</para>

      <para>Pluto uses the NSS crypto library as its random source. Some
      government Three Letter Agency requires that pluto reads 440 bits
      from /dev/random and feed this into the NSS RNG before drawing
      random from the NSS library, despite the NSS library itself
      already seeding its internal state. As this process can block
      pluto for an extended time, the default is to not perform this
      redundant seeding. The <emphasis remap="B">--seedbits</emphasis>
      option can be used to specify the number of bits that will be
      pulled from /dev/random and seeded into the NSS RNG.  This can
      also be accomplished by specifying seedbits in the "config setup"
      section of ipsec.conf. This option should not be used by most people.</para>

      <para><emphasis remap="B">pluto</emphasis> attempts to create a lockfile
      with the name <filename>/var/run/pluto/pluto.pid</filename>. If the
      lockfile cannot be created, <emphasis remap="B">pluto</emphasis> exits -
      this prevents multiple <emphasis remap="B">pluto</emphasis>s from
      competing Any "leftover" lockfile must be removed before <emphasis
      remap="B">pluto</emphasis> will run. <emphasis
      remap="B">pluto</emphasis> writes its PID into this file so that scripts
      can find it. This lock will not function properly if it is on an NFS
      volume (but sharing locks on multiple machines doesn't make sense
      anyway).</para>

      <para><emphasis remap="B">pluto</emphasis> then forks and the parent
      exits. This is the conventional "daemon fork". It can make debugging
      awkward, so there is an option to suppress this fork. In certain
      configurations, pluto might also launch helper programs to assist with
      DNS queries or to offload cryptographic operations.</para>

      <para>All logging, including diagnostics, is sent to <citerefentry>
          <refentrytitle>syslog</refentrytitle>

          <manvolnum>3</manvolnum>
        </citerefentry> with facility=authpriv; it decides where to put these
      messages (possibly in /var/log/secure or /var/log/auth.log). Since this too can make
      debugging awkward, the option <option>--stderrlog</option> is used to
      steer logging to stderr.  </para>

      <para>Alternatively, <option>--logfile</option> can be used to send all logging
      information to a specific file.</para>

      <para>Once <emphasis remap="B">pluto</emphasis> is started, it waits for
      requests from <emphasis remap="B">whack</emphasis>.</para>
    </refsect2>

    <refsect2 id="plutos_internal_state">
      <title>Pluto's Internal State</title>

      <para>To understand how to use <emphasis remap="B">pluto</emphasis>, it
      is helpful to understand a little about its internal state. Furthermore,
      the terminology is needed to decipher some of the diagnostic
      messages.</para>

      <para>Pluto supports <emphasis remap="B">food groups</emphasis> for Opportunistic
      IPsec. The policies for these are located in /etc/ipsec.d/policies, or another
      directory as specified by <option>--ipsecdir</option>.</para>

      <para>Pluto supports X.509 Certificates. All certificate handling is done using
      the NSS library and all certificate material is stored in an NSS database in
      @IPSEC_NSSDIR@ or another directory as specified by <option>--nssdir</option>.</para>

      <para>Pluto may core dump. It will normally do so into the current
      working directory. You can specify the --coredir option for pluto, or
      specify the dumpdir= option in ipsec.conf.</para>

      <para>If you are investigating a potential memory leak in pluto,
      start pluto with the --leak-detective option.  Before the leak
      causes the system or pluto to die, shut down pluto in the regular
      way. pluto will display a list of leaks it has detected.  </para>

      <para>
	If you are investigating a potential use-after-free or
	double-free in pluto, first build pluto with USE_EFENCE=true
	and then start pluto with --efence-protect.  See
	<citerefentry> <refentrytitle>efence</refentrytitle>
	<manvolnum>2</manvolnum> </citerefentry> and EF_PROTECT_BELOW
	and EF_PROTECT_FREE.
      </para>

      <para>The <emphasis remap="I">(potential) connection</emphasis> database
      describes attributes of a connection. These include the IP addresses of
      the hosts and client subnets and the security characteristics desired.
      <emphasis remap="B">pluto</emphasis> requires this information (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.</para>

      <para>During the IKE exchange to build an SA, the information about the
      negotiation is represented in a <emphasis remap="I">state
      object</emphasis>. 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 logged
      messages.</para>

      <para>Each state object corresponds to a connection and can be thought
      of as an instantiation of that connection. At any particular time, there
      may be any number of state objects corresponding to a particular
      connection. Often there is one representing an ISAKMP SA and another
      representing an IPsec SA.</para>

      <para><emphasis remap="B">XFRM</emphasis> requires no special
      routing.</para>

      <para>Each connection may be routed, and must be while it has an IPsec
      SA. The connection specifies the characteristics of the route: the
      interface on this machine, the "gateway" (the nexthop), and the peer's
      client subnet. Two connections may not be simultaneously routed if they
      are for the same peer's client subnet but use different interfaces or
      gateways (<emphasis remap="B">pluto</emphasis>'s logic does not reflect
      any advanced routing capabilities).</para>

      <para>When <emphasis remap="B">pluto</emphasis> needs to install a route
      for a connection, it must make sure that no conflicting route is in use.
      If another connection has a conflicting 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.</para>

      <para>There is an exception. If <emphasis remap="B">pluto</emphasis>, 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).</para>

      <para>When <emphasis remap="B">pluto</emphasis> needs to install an
      eroute for an IPsec SA (for a state object), first the state object's
      connection must be routed (if this cannot be done, the eroute and SA
      will not be installed). If a conflicting eroute is already in place for
      another connection, the eroute and SA will not be installed (but note
      that the routing exception mentioned above may have already deleted
      potentially conflicting SAs). If another IPsec SA for the same
      connection already has an eroute, all its outgoing traffic is taken over
      by the new eroute. The incoming traffic will still be processed. This
      characteristic is exploited during rekeying.</para>
    </refsect2>

    <refsect2 id="using_whack">
      <title>Using whack</title>

      <para><emphasis remap="B">whack</emphasis> is used to command a running
      <emphasis remap="B">pluto</emphasis>. <emphasis
      remap="B">whack</emphasis> uses a UNIX domain socket to speak to
      <emphasis remap="B">pluto</emphasis> (by default,
      <filename>/var/pluto.ctl</filename>).</para>

      <para><emphasis remap="B">whack</emphasis> has an intricate argument
      syntax. This syntax allows many different functions to be specified. The
      help form shows the usage or version information. The connection form
      gives <emphasis remap="B">pluto</emphasis> a description of a potential
      connection. The public key form informs <emphasis
      remap="B">pluto</emphasis> of the RSA public key for a potential peer.
      The delete form deletes a connection description and all SAs
      corresponding to it. The listen form tells <emphasis
      remap="B">pluto</emphasis> to start or stop listening on the public
      interfaces for IKE requests from peers. The route form tells <emphasis
      remap="B">pluto</emphasis> to set up routing for a connection; the
      unroute form undoes this. The initiate form tells <emphasis
      remap="B">pluto</emphasis> to negotiate an SA corresponding to a
      connection. The terminate form tells <emphasis
      remap="B">pluto</emphasis> to remove all SAs corresponding to a
      connection, including those being negotiated. The status form displays
      the <emphasis remap="B">pluto</emphasis>'s internal state. The debug
      form tells <emphasis remap="B">pluto</emphasis> to change the selection
      of debugging output "on the fly". The shutdown form tells <emphasis
      remap="B">pluto</emphasis> to shut down, deleting all SAs.</para>

      <para>The crash option asks pluto to consider a particularly target IP
      to have crashed, and to attempt to restart all connections with that IP
      address as a gateway. In general, you should use Dead Peer Detection to
      detect this kind of situation automatically, but this is not always
      possible.</para>

      <para>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.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--ctlsocket</option>&nbsp;<emphasis
          remap="I">path/file</emphasis></term>

          <listitem>
            <para><emphasis remap="I">file</emphasis> is used as the UNIX
            domain socket for talking to <emphasis remap="B">pluto</emphasis>.
            Use either this option or <emphasis remap="B">--rundir</emphasis>,
            but not both.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--rundir</option>&nbsp;<emphasis
          remap="I">path</emphasis></term>

          <listitem>
            <para><emphasis remap="I">path</emphasis> where the UNIX domain
            socket for talking to the <emphasis remap="B">pluto</emphasis>, the
            <emphasis remap="B">pluto.pid</emphasis> file and the
            <emphasis remap="B">pluto.lock</emphasis> files are found.
            Use either this option or <emphasis remap="B">--ctlsocket</emphasis>,
            but not both.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--label</option>&nbsp;<emphasis
          remap="I">string</emphasis></term>

          <listitem>
            <para>adds the string to all error messages generated by <emphasis
            remap="B">whack</emphasis>.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The help form of <emphasis remap="B">whack</emphasis> is
      self-explanatory.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--help</option></term>

          <listitem>
            <para>display the usage message.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--version</option></term>

          <listitem>
            <para>display the version of <emphasis
            remap="B">whack</emphasis>.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The connection form describes a potential connection to <emphasis
      remap="B">pluto</emphasis>. <emphasis remap="B">pluto</emphasis> needs
      to know what connections can and should be negotiated. When <emphasis
      remap="B">pluto</emphasis> is the initiator, it needs to know what to
      propose. When <emphasis remap="B">pluto</emphasis> is the responder, it
      needs to know enough to decide whether is is willing to set up the
      proposed connection.</para>

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

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--name</option>&nbsp;<emphasis
          remap="I">connection-name</emphasis></term>

          <listitem>
            <para>sets the name of the connection</para>
          </listitem>
        </varlistentry>
      </variablelist>

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

      <para>&nbsp;&nbsp;&nbsp;client_subnet&lt;--&gt;host:ikeport&lt;--&gt;nexthop&lt;---</para>

      <para>A similar trick is used in the flags. The same flag names are used
      for both ends. Those before the <option>--to</option> flag describe the
      left side and those afterwards describe the right side. When <emphasis
      remap="B">pluto</emphasis> 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.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--id</option>&nbsp;<emphasis
          remap="I">id</emphasis></term>

          <listitem>
            <para>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
            Domain Name itself (prefixed by "@" to signify that it should not
            be resolved), or as user@FQDN, or an X.509 DN.
            <emphasis remap="B">Pluto</emphasis> 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
            <option>--host</option>.</para>

            <!--  The identity is transmitted in the IKE protocol, and is what is authenticated. -->
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--host</option>&nbsp;<emphasis
          remap="I">ip-address</emphasis></term>

          <term><option>--host</option>&nbsp;<emphasis
          remap="B">%any</emphasis></term>

          <term><option>--host</option>&nbsp;<emphasis
          remap="B">%opportunistic</emphasis></term>

          <listitem>
            <para>the IP address of the end (generally the public interface).
            If <emphasis remap="B">pluto</emphasis> 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
            <emphasis remap="B">%any</emphasis> (currently, the obsolete
            notation <literal>0.0.0.0</literal> is also accepted for this). If
            <emphasis remap="B">pluto</emphasis> is to opportunistically
            initiate the connection, use <emphasis
            remap="B">%opportunistic</emphasis></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--cert</option>&nbsp;<emphasis
          remap="I">friendly_name</emphasis></term>

          <listitem>
            <para>The friendly_name (or nickname) of the X.509 certificate that was used
            when imported the certificate into the NSS database.
            See <citerefentry>
                <refentrytitle>ipsec.conf</refentrytitle>

                <manvolnum>5</manvolnum>
              </citerefentry> on how to extract this from the PKCS#12
            file.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ckaid</option>&nbsp;<emphasis
          remap="I">CKAID</emphasis></term>

          <listitem>
            <para>The hex CKAID of the X.509 certificate.
            Certificates are stored in the NSS database.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ca</option>&nbsp;<emphasis remap="I">distinguished
          name</emphasis></term>

          <listitem>
            <para>the X.509 Certificate Authority's Distinguished Name (DN)
            used as trust anchor for this connection. This is the CA
            certificate that signed the host certificate, as well as the
            certificate of the incoming client.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--groups</option>&nbsp;<emphasis remap="I">access
          control groups</emphasis></term>

          <listitem>
            <para>the access control groups used.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--sendcert</option>&nbsp;<emphasis
          remap="I">yes|forced|always|ifasked|no|never</emphasis></term>

          <listitem>
            <para>Whether or not to send our X.509 certificate credentials.
            This could potentially give an attacker too much information about
            which identities are allowed to connect to this host. The default
            is to use <emphasis remap="B">ifasked</emphasis> when we are a
            Responder, and to use <emphasis remap="B">yes</emphasis> (which is
            the same as <emphasis remap="B">forced</emphasis> and <emphasis
            remap="B">always</emphasis> if we are an Initiator. The values
            <emphasis remap="B">no</emphasis> and <emphasis
            remap="B">never</emphasis> are equivalent. NOTE: "forced" does not
            seem to be actually implemented - do not use it.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--sendca</option>&nbsp;<emphasis
          remap="I">none|issuer|all</emphasis></term>

          <listitem>
	  <para>How much of our available X.509 trust chain to send with the
	  end certificate, excluding any root CAs. Specifying <emphasis remap="B"
	  >issuer</emphasis> sends just the issuing intermediate CA, while
	  <emphasis remap="B"> all</emphasis> will send the entire chain of
	  intermediate CAs.<emphasis remap="B">none</emphasis> will not send
	  any CA certs. The default is <emphasis remap="B">none</emphasis> which
	  maintains the current libreswan behavior.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--certtype</option>&nbsp;<emphasis
          remap="I">number</emphasis></term>

          <listitem>
            <para>The X.509 certificate type number.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ikeport</option>&nbsp;<emphasis
          remap="I">port-number</emphasis></term>

          <listitem>
            <para>the UDP port that IKE listens to on that host. The default
            is 500. (<emphasis remap="B">pluto</emphasis> on this machine uses
            the port specified by its own command line argument, so this only
            affects where <emphasis remap="B">pluto</emphasis> sends
            messages.)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--nexthop</option>&nbsp;<emphasis
          remap="I">ip-address</emphasis></term>

          <listitem>
            <para>where to route packets for the peer's client (presumably for
            the peer too, but it will not be used for this). When <emphasis
            remap="B">pluto</emphasis> installs an IPsec SA, it issues a route
            command. It uses the nexthop as the gateway. The default is the
            peer's IP address (this can be explicitly written as <emphasis
            remap="B">%direct</emphasis>; the obsolete notation
            <literal>0.0.0.0</literal> is accepted). This option is necessary
            if <emphasis remap="B">pluto</emphasis>'s host's interface used
            for sending packets to the peer is neither point-to-point nor
            directly connected to the peer.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--client</option>&nbsp;<emphasis
          remap="I">subnet</emphasis></term>

          <listitem>
            <para>the subnet for which the IPsec traffic will be destined. If
            not specified, the host will be the client. The subnet can be
            specified in any of the forms supported by <citerefentry>
                <refentrytitle>ipsec_atosubnet</refentrytitle>

                <manvolnum>3</manvolnum>
              </citerefentry>. The general form is <emphasis
            remap="I">address</emphasis>/<emphasis remap="I">mask</emphasis>.
            The <emphasis remap="I">address</emphasis> can be either a domain
            name or four decimal numbers (specifying octets) separated by
            dots. The most convenient form of the <emphasis
            remap="I">mask</emphasis> is a decimal integer, specifying the
            number of leading one bits in the mask. So, for example,
            10.0.0.0/8 would specify the class A network "Net 10".</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--clientprotoport</option>&nbsp;<emphasis
          remap="I">protocol/port</emphasis></term>

          <listitem>
            <para>specify the Port Selectors (filters) to be used on this
            connection. The general form is <emphasis
            remap="I">protocol</emphasis>/<emphasis remap="I">port</emphasis>.
            This is most commonly used to limit the connection to L2TP traffic
            only by specifying a value of <emphasis
            remap="I">17/1701</emphasis> for UDP (protocol 17) and port 1701.
            The notation <emphasis remap="I">17/%any</emphasis> can be used to
            allow all UDP traffic and is needed for L2TP connections with
            Windows XP machines before Service Pack 2.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--srcip</option>&nbsp;<emphasis
          remap="I">ip-address</emphasis></term>

          <listitem>
            <para>the IP address for this host to use when transmitting a
            packet to the remote IPsec gateway itself. This option is used to
            make the gateway itself use its internal IP, which is part of the
            <option>--client subnet</option>. Otherwise it will use its
            nearest IP address, which is its public IP address, which is not
            part of the subnet-subnet IPsec tunnel, and would therefore not get
            encrypted.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--xauthserver</option></term>

          <listitem>
            <para>this end is an xauthserver. It will lookup the xauth user
            name and password and verify this before allowing the connection
            to get established.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--xauthclient</option></term>

          <listitem>
            <para>this end is an xauthclient. To bring this connection up with
            the <option>--initiate</option> also requires the client to
            specify <option>--xauthuser username</option> and
            <option>--xauthpass password </option></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--xauthuser</option></term>

          <listitem>
            <para>The username for the xauth authentication.This option is
            normally passed along by <citerefentry>
                <refentrytitle>ipsec_auto</refentrytitle>

                <manvolnum>8</manvolnum>
              </citerefentry> when an xauth connection is started using
            <emphasis remap="I">ipsec auto --up conn</emphasis></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--xauthpass</option></term>

          <listitem>
            <para>The password for the xauth authentication. This option is
            normally passed along by <citerefentry>
                <refentrytitle>ipsec_auto</refentrytitle>

                <manvolnum>8</manvolnum>
              </citerefentry> when an xauth connection is started using
            <emphasis remap="I">ipsec auto --up conn</emphasis></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--modecfgserver</option></term>

          <listitem>
            <para>this end is an Mode Config server</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--modecfgclient</option></term>

          <listitem>
            <para>this end is an Mode Config client</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--modecfgdns</option></term>

          <listitem>
            <para>A comma separated list of DNS server IP's to pass along to connecting clients</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--modecfgdomains</option></term>

          <listitem>
            <para>A comma separated list of internal DNS domains to pass along to connecting clients</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dnskeyondemand</option></term>

          <listitem>
            <para>specifies that when an RSA public key is needed to
            authenticate this host, and it isn't already known, fetch it from
            DNS.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--updown</option>&nbsp;<emphasis
          remap="I">updown</emphasis></term>

          <listitem>
            <para>specifies an external shell command to be run whenever
            <emphasis remap="B">pluto</emphasis> 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 <emphasis remap="I">ipsec _updown</emphasis>. Pluto
            passes a dozen environment variables to the script about the
            connection involved.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--to</option></term>

          <listitem>
            <para>separates the specification of the left and right ends of
            the connection. Pluto tries to decide whether it is <emphasis
            remap="I">left</emphasis> or <emphasis remap="I">right</emphasis>
            based on the information provided on both sides of this
            option.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The potential connection description also specifies
      characteristics of rekeying and security.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--psk</option></term>

          <listitem>
            <para>Propose and allow preshared secret authentication for IKE
            peers. This authentication requires that each side use the same
            secret. May be combined with <option>--rsasig</option>; at least
            one must be specified.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--rsasig</option></term>

          <listitem>
            <para>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 <option>--psk</option>; at least one must be
            specified.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--encrypt</option></term>

          <listitem>
            <para>All proposed or accepted IPsec SAs will include non-null
            ESP. The actual choices of transforms are wired into <emphasis
            remap="B">pluto</emphasis>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--authenticate</option></term>

          <listitem>
            <para>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 <emphasis remap="B">pluto</emphasis>.
            Note that this has nothing to do with IKE authentication.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--compress</option></term>

          <listitem>
            <para>All proposed IPsec SAs will include IPCOMP (compression). </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--tunnel</option></term>

          <listitem>
            <para>the IPsec SA should use tunneling. Implicit if the SA is for
            clients. Must only be used with <option>--authenticate</option> or
            <option>--encrypt</option>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ipv4</option></term>

          <listitem>
            <para>The host addresses will be interpreted as IPv4 addresses.
            This is the default. Note that for a connection, all host
            addresses must be of the same Address Family (IPv4 and IPv6 use
            different Address Families).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ipv6</option></term>

          <listitem>
            <para>The host addresses (including nexthop) will be interpreted
            as IPv6 addresses. Note that for a connection, all host addresses
            must be of the same Address Family (IPv4 and IPv6 use different
            Address Families).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--tunnelipv4</option></term>

          <listitem>
            <para>The client addresses will be interpreted as IPv4 addresses.
            The default is to match what the host will be. This does not imply
            <option>--tunnel</option> so the flag can be safely used when no
            tunnel is actually specified. Note that for a connection, all
            tunnel addresses must be of the same Address Family.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--tunnelipv6</option></term>

          <listitem>
            <para>The client addresses will be interpreted as IPv6 addresses.
            The default is to match what the host will be. This does not imply
            <option>--tunnel</option> so the flag can be safely used when no
            tunnel is actually specified. Note that for a connection, all
            tunnel addresses must be of the same Address Family.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--pfs</option></term>

          <listitem>
            <para>There should be Perfect Forward Secrecy - new keying
            material will be generated for each IPsec SA when running Quick Mode in IKEv1
            or Create Child in IKEv2. Without this option, the SAKMP SA keying material is
            used instead.  <emphasis remap="B">pluto</emphasis> will propose the same group
            that was used with the original IKE SA. </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--pfsgroup</option>&nbsp;<emphasis
          remap="I">modp-group</emphasis></term>

          <listitem>
            <para>Sets the Diffie-Hellman group used. Currently the following
            values are supported: <emphasis remap="B">modp1024</emphasis>
            (DHgroup 2), <emphasis remap="B">modp1536</emphasis> (DHgroup 5),
            <emphasis remap="B">modp2048</emphasis> (DHgroup 14), <emphasis
            remap="B">modp3072</emphasis> (DHgroup 15), <emphasis
            remap="B">modp4096</emphasis> (DHgroup 16), <emphasis
            remap="B">modp6144</emphasis> (DHgroup 17), and <emphasis
            remap="B">modp8192</emphasis> (DHgroup 18). It is possible to
            support the weak and broken <emphasis remap="B">modp768</emphasis>
            (DHgroup 1), but this requires a manual recompile and is strongly
            discouraged.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--esp</option>&nbsp;<emphasis
          remap="I">esp-algos</emphasis></term>

          <listitem>
            <para>ESP encryption/authentication algorithm to be used for the
            connection (phase2 aka IPsec SA). The options must be suitable as
            a value of <citerefentry>
                <refentrytitle>ipsec_spi</refentrytitle>

                <manvolnum>8</manvolnum>
              </citerefentry>. See <citerefentry>
                <refentrytitle>ipsec.conf</refentrytitle>

                <manvolnum>5</manvolnum>
              </citerefentry> for a detailed description of the algorithm
            format.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--aggrmode</option></term>

          <listitem>
            <para>This tunnel is using aggressive mode ISAKMP negotiation. The
            default is main mode. Aggressive mode is less secure than main
            mode as it reveals your identity to an eavesdropper, but is needed
            to support road warriors using PSK keys or to interoperate with
            other buggy implementations insisting on using aggressive
            mode.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--modecfgpull</option></term>

          <listitem>
            <para>Pull the Mode Config network information from the
            peer.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dpddelay</option>&nbsp;<emphasis
          remap="I">seconds</emphasis></term>

          <listitem>
            <para>Set the delay (in seconds) between Dead Peer Detection (RFC
            3706) keepalives (R_U_THERE, R_U_THERE_ACK) that are sent for this
            connection (default 30 seconds).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--timeout</option>&nbsp;<emphasis
          remap="I">seconds</emphasis></term>

          <listitem>
            <para>Set the length of time (in seconds) we will idle without
            hearing either an R_U_THERE poll from our peer, or an
            R_U_THERE_ACK reply. After this period has elapsed with no
            response and no traffic, we will declare the peer dead, and remove
            the SA (default 120 seconds).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dpdaction</option>&nbsp;<emphasis
          remap="I">action</emphasis></term>

          <listitem>
            <para>When a DPD enabled peer is declared dead, what action should
            be taken. <emphasis remap="B">hold</emphasis>(default) means the
            eroute will be put into <emphasis remap="I">%hold</emphasis>
            status, while <emphasis remap="B">clear</emphasis>means the eroute
            and SA with both be cleared. Clear is really only useful on the
            server of a Road Warrior config. The action <emphasis
            remap="B">restart</emphasis> is used on tunnels that need to be
            permanently up, and have static IP addresses. The action <emphasis
            remap="B">restart_by_peer</emphasis>has been obsoleted and its
            functionality has been moved into the restart action.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--forceencaps</option></term>

          <listitem>
            <para>In some cases, for example when ESP packets are filtered or
            when a broken IPsec peer does not properly recognise NAT, it can
            be useful to force RFC-3948 encapsulation using this option. It
            causes pluto lie and tell the remote peer that RFC-3948
            encapsulation (ESP in UDP port 4500 packets) is required.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>If none of the <option>--encrypt</option>,
      <option>--authenticate</option>, <option>--compress</option>, or
      <option>--pfs</option> 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 specified.</para>

      <para>Apart from initiating directly using the
      <option>--initiate</option> option, a tunnel can be loaded with a
      different policy</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--initiateontraffic</option></term>

          <listitem>
            <para>Only initiate the connection when we have traffic to send
            over the connection</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--pass</option></term>

          <listitem>
            <para>Allow <emphasis remap="B">unencrypted</emphasis> traffic to
            flow until the tunnel is initiated.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--drop</option></term>

          <listitem>
            <para>Drop unencrypted traffic silently.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--reject</option></term>

          <listitem>
            <para>Drop unencrypted traffic silently, but send an ICMP message
            notifying the other end.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>These options need to be documented</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--failnone</option></term>

          <listitem>
            <para>to be documented</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--failpass</option></term>

          <listitem>
            <para>to be documented</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--faildrop</option></term>

          <listitem>
            <para>to be documented</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--failreject</option></term>

          <listitem>
            <para>to be documented</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para><emphasis remap="B">pluto</emphasis> supports various X.509
      Certificate related options.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--utc</option></term>

          <listitem>
            <para>display all times in UTC.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--listall</option></term>

          <listitem>
            <para>lists all of the X.509 information known to pluto.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--listpubkeys</option></term>

          <listitem>
            <para>list all the public keys that have been successfully
            loaded.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--listcerts</option></term>

          <listitem>
            <para>list all the X.509 certificates that are currently
            loaded.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--checkpubkeys</option></term>

          <listitem>
            <para>list all the loaded X.509 certificates that are about to
            expire or have expired.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--listcacerts</option></term>

          <listitem>
            <para>list all the Certificate Authority X.509 certificates that are currently
            loaded.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--listcrls</option></term>

          <listitem>
            <para>list all the loaded <emphasis remap="I">Certificate
            Revocation Lists</emphasis> (CRLs)</para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>The corresponding options <option>--rereadsecrets</option>,
      <option>--rereadall</option>,
      and <option>--rereadcrls</option> options reread this information from their
      respective sources, and purge all the online obtained information. The
      option <option>--listevents</option> lists all pending events, and the
      <option>--ddns</option> triggers the Dynamic DNS update event that is normally
      scheduled to run once every minute.
      </para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--ikelifetime</option>&nbsp;<emphasis
          remap="I">seconds</emphasis></term>

          <listitem>
            <para>how long <emphasis remap="B">pluto</emphasis> will propose
            that an ISAKMP SA be allowed to live. The default is 3600 (one
            hour) and the maximum is 86400 (1 day). This option will not
            affect what is accepted. <emphasis remap="B">pluto</emphasis> will
            reject proposals that exceed the maximum.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ipseclifetime</option>&nbsp;<emphasis
          remap="I">seconds</emphasis></term>

          <listitem>
            <para>how long <emphasis remap="B">pluto</emphasis> 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. <emphasis remap="B">pluto</emphasis> will
            reject proposals that exceed the maximum.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--rekeymargin</option>&nbsp;<emphasis
          remap="I">seconds</emphasis></term>

          <listitem>
            <para>how long before an SA's expiration should <emphasis
            remap="B">pluto</emphasis> try to negotiate a replacement SA. This
            will only happen if <emphasis remap="B">pluto</emphasis> was the
            initiator. The default is 540 (nine minutes).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--rekeyfuzz</option>&nbsp;<emphasis
          remap="I">percentage</emphasis></term>

          <listitem>
            <para>maximum size of random component to add to rekeymargin,
            expressed as a percentage of rekeymargin. <emphasis
            remap="B">pluto</emphasis> will select a delay 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.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--keyingtries</option>&nbsp;<emphasis
          remap="I">count</emphasis></term>

          <listitem>
            <para>how many times <emphasis remap="B">pluto</emphasis> should
            try to negotiate an SA, either for the first time or for rekeying.
            The default value of 0 means to keep trying forever. </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--dontrekey</option></term>

          <listitem>
            <para>A misnomer. Only rekey a connection if 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
            automatic way for a connection to terminate. It may be useful with
            Road Warrior or Opportunistic connections. <!-- .br --> Since SA
            lifetime negotiation is take-it-or-leave it, a Responder normally
            uses the shorter of the negotiated or the configured lifetime.
            This only works because if the lifetime is shorter than
            negotiated, the Responder will rekey in time so that everything
            works. This interacts badly with <option>--dontrekey</option>. In
            this case, the Responder will end up rekeying to rectify a
            shortfall in an IPsec SA lifetime; for an ISAKMP SA, the Responder
            will accept the negotiated lifetime.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--delete</option></term>

          <listitem>
            <para>when used in the connection form, it causes any previous
            connection with this name to be deleted before this one is added.
            Unlike a normal delete, no diagnostic is produced if there was no
            previous connection to delete. Any routing in place for the
            connection is undone.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--delete</option></term>

          <term><option>--name</option>&nbsp;<emphasis
          remap="I">connection-name</emphasis></term>

          <listitem>
            <para>The delete form deletes a named connection description and
            any SAs established or negotiations initiated using this
            connection. Any routing in place for the connection is
            undone.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--deletestate</option>&nbsp;<emphasis
          remap="I">state-number</emphasis></term>

          <listitem>
            <para>The deletestate form deletes the state object with the
            specified serial number. This is useful for selectively deleting
            instances of connections.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The route form of the <emphasis remap="B">whack</emphasis> command
      tells <emphasis remap="B">pluto</emphasis> to set up routing for a
      connection. Although like a traditional route, it uses an ipsec device
      as a virtual interface. Once routing is set up, no packets will be sent
      "in the clear" to the peer's client specified in the connection. A TRAP
      shunt eroute will be installed; if outbound traffic is caught, Pluto
      will initiate the connection. An explicit <emphasis
      remap="B">whack</emphasis> route is not always needed: if it hasn't been
      done when an IPsec SA is being installed, one will be automatically
      attempted.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--route</option></term>

          <term><option>--name</option>&nbsp;<emphasis
          remap="I">connection-name</emphasis></term>

          <listitem>
            <para>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 there is, it
            must not be being used by an IPsec SA. Otherwise the attempt will
            fail.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--unroute</option></term>

          <term><option>--name</option>&nbsp;<emphasis
          remap="I">connection-name</emphasis></term>

          <listitem>
            <para>The unroute form of the <emphasis remap="B">whack</emphasis>
            command tells <emphasis remap="B">pluto</emphasis> to undo a
            routing. <emphasis remap="B">pluto</emphasis> will refuse if an
            IPsec SA is using the connection. If another connection is sharing
            the same routing, it will be left in place. Without a routing,
            packets will be sent without encryption or authentication.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The initiate form tells <emphasis remap="B">pluto</emphasis> to
      initiate a negotiation with another <emphasis remap="B">pluto</emphasis>
      (or other IKE daemon) according to the named connection. Initiation
      requires a route that <option>--route</option> would provide; if none is
      in place at the time an IPsec SA is being installed, <emphasis
      remap="B">pluto</emphasis> attempts to set one up.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--initiate</option></term>

          <term><option>--name</option>&nbsp;<emphasis
          remap="I">connection-name</emphasis></term>

          <term><option>--asynchronous</option></term>

          <listitem>
            <para>The initiate form of the <emphasis
            remap="B">whack</emphasis> command will relay back from <emphasis
            remap="B">pluto</emphasis> status information via the UNIX domain
            socket (unless --asynchronous is specified). The status
            information is meant to look a bit like that from <emphasis
            remap="B">FTP</emphasis>. Currently <emphasis
            remap="B">whack</emphasis> simply copies this to stderr. When the
            request is finished (eg. the SAs are established or <emphasis
            remap="B">pluto</emphasis> gives up), <emphasis
            remap="B">pluto</emphasis> closes the channel, causing <emphasis
            remap="B">whack</emphasis> to terminate.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>
	The opportunistic initiate form is mainly used for
	debugging.
      </para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--tunnelipv4</option></term>

          <term><option>--tunnelipv6</option></term>

          <term>
	    <option>--oppohere</option>&nbsp;
	    <emphasis remap="I">ip-address</emphasis>
	  </term>

          <term>
	    <option>--oppothere</option>&nbsp;
	    <emphasis remap="I">ip-address</emphasis>
	  </term>

          <term>
	    <option>--opposport</option>&nbsp;
	    <emphasis remap="I">port</emphasis>
	  </term>

          <term>
	    <option>--oppodport</option>&nbsp;
	    <emphasis remap="I">port</emphasis>
	  </term>

          <term>
	    <option>--oppoproto</option>&nbsp;
	    <emphasis remap="I">protocol</emphasis>
	  </term>

          <listitem>
            <para>
	      This will cause <emphasis remap="B">pluto</emphasis> to
	      attempt to opportunistically initiate a connection from
	      here to the there, even if a previous attempt had been
	      made. The whack log will show the progress of this
	      attempt.
	    </para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>Rekeying a connection</para>

      <variablelist remap="tp">
        <varlistentry>
          <term><option>--rekey-ipsec</option></term>

          <term><option>--name</option>&nbsp;<emphasis
          remap="i">connection-name</emphasis></term>

          <listitem>
            <para>the rekey-ipsec form tells <emphasis
            remap="b">pluto</emphasis> to rekey the IPsec SA (child SA) of
            the specified connection. It does not affect the IKE SA (parent SA)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--rekey-ike</option></term>

          <term><option>--name</option>&nbsp;<emphasis
          remap="i">connection-name</emphasis></term>

          <listitem>
            <para>the rekey-ike form tells <emphasis
            remap="b">pluto</emphasis> to rekey the IKE SA (parent SA) of
            the specified connection. It does not affect the IPsec SAs (child SAs)</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>Ending a connection</para>

      <variablelist remap="tp">
        <varlistentry>
          <term><option>--terminate</option></term>

          <term><option>--name</option>&nbsp;<emphasis
          remap="i">connection-name</emphasis></term>

          <listitem>
            <para>the terminate form tells <emphasis
            remap="b">pluto</emphasis> to delete any SAs that use the
            specified connection and to stop any negotiations in process. it
            does not prevent new negotiations from starting (the delete form
            has this effect).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--crash</option>&nbsp;<emphasis
          remap="i">ip-address</emphasis></term>

          <listitem>
            <para>If the remote peer has crashed, and therefore did not notify
            us, we keep sending encrypted traffic, and rejecting all plaintext
            (non-IKE) traffic from that remote peer. The
            <option>--crash</option> brings our end down as well for all the
            known connections to the specified <emphasis
            remap="i">ip-address</emphasis></para>
          </listitem>
        </varlistentry>
      </variablelist>

      <variablelist remap="tp">
        <varlistentry>
          <term><emphasis remap="i">ip-address</emphasis></term>

          <listitem>
            <para>If the remote peer has crashed, and therefore did not notify
            us, we keep sending encrypted traffic, and rejecting all plaintext
            (non-IKE) traffic from that remote peer. The
            <option>--crash</option> brings our end down as well for all the
            known connections to the specified <emphasis
            remap="i">ip-address</emphasis></para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>Redirecting clients can be done using IKEv2 redirect mechanism.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--global-redirect</option>&nbsp;<emphasis
          remap="i">yes|no|auto</emphasis></term>

          <listitem>
            <para>The --global-redirect option controls whether <emphasis
            remap="b">pluto</emphasis> will instruct remote peers to redirect
            IKE/IPsec SA's during IKE_SA_INIT. Valid options are <emphasis
            remap="b">no</emphasis>, <emphasis remap="b">yes</emphasis> and
            <emphasis remap="b">auto</emphasis>, where auto means remote peers
            will be redirected if DDoS mode is active.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--global-redirect-to</option>&nbsp;<emphasis
          remap="i">ip-address(es)</emphasis></term>

          <listitem>
            <para>The destination, or a list of destinations, where the peers will
            be redirected.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--name</option>&nbsp;<emphasis
          remap="i">connection_name</emphasis></term>

          <term><option>--redirect-to</option>&nbsp;<emphasis
          remap="i">ip-address(es)</emphasis></term>

          <listitem>
            <para>The destination, or a list of destinations, where the peers will
            be redirected.
            Specifying the connection name is optional. If not specified
            the mechanism will redirect all currently active peers.
            If specified, only the peers from connection <emphasis
            remap="i">connection_name</emphasis> will be redirected.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The public key for informs <emphasis remap="B">pluto</emphasis> of
      the RSA public key for a potential peer. Private keys must be kept
      secret, so they are kept in <citerefentry>
          <refentrytitle>ipsec.secrets</refentrytitle>

          <manvolnum>5</manvolnum>
        </citerefentry>.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--keyid&nbsp;</option><replaceable>id</replaceable></term>

          <listitem>
            <para>specififies the identity of the peer for which a public key
            should be used. Its form is identical to the identity in the
            connection. If no public key is specified, <emphasis
            remap="B">pluto</emphasis> attempts to find KEY records from DNS
            for the id (if a FQDN) or through reverse lookup (if an IP
            address). Note that there several interesting ways in which this
            is not secure.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--addkey</option></term>

          <listitem>
            <para>specifies that the new key is added to the collection;
            otherwise the new key replaces any old ones.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--pubkeyrsa&nbsp;</option><replaceable>key</replaceable></term>

          <listitem>
            <para>specifies the value of the RSA public key. It is a sequence
            of bytes as described in RFC 2537 "RSA/MD5 KEYs and SIGs in the
            Domain Name System (DNS)". It is denoted in a way suitable for
            <citerefentry>
                <refentrytitle>ipsec_ttodata</refentrytitle>

                <manvolnum>3</manvolnum>
              </citerefentry>. For example, a base 64 numeral starts with
            0s.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The listen form tells <emphasis remap="B">pluto</emphasis> to
      start listening for IKE requests on its public interfaces. To avoid race
      conditions, it is normal to load the appropriate connections into
      <emphasis remap="B">pluto</emphasis> before allowing it to listen. If
      <emphasis remap="B">pluto</emphasis> isn't listening, it is pointless to
      initiate negotiations, so it will refuse requests to do so. Whenever the
      listen form is used, <emphasis remap="B">pluto</emphasis> 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 <emphasis
      remap="B">pluto</emphasis> to read the <emphasis
      remap="I">ipsec.secrets</emphasis> file. So listen may useful more than
      once.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--listen</option></term>

          <listitem>
            <para>start listening for IKE traffic on public interfaces.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--unlisten</option></term>

          <listitem>
            <para>stop listening for IKE traffic on public interfaces.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The --ddos-auto, --ddos-busy and --ddos-unlimited options
      tells <emphasis remap="B">pluto</emphasis> to update the DDoS
      protection state. Normally, these measures are automatically
      activated or deactivated based on the number of states inside
      pluto. The busy and unlimited option tells pluto to activate or
      deactivate the DDoS protection mode manually.  One of these DDoS
      protection methods is to activate IKEv2 DCOOKIEs to defend against
      spoofed IKE packets.
      </para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--ddos-busy</option></term>

          <listitem>
            <para>place pluto into busy mode and activate anti-DDoS measures.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ddos-unlimited</option></term>

          <listitem>
            <para>pull pluto out of busy mode and deactivate anti-DDoS measures.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ddos-auto</option></term>
          <listitem>
            <para>activate the built-in detection mechanism for the anti-DDoS measures.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The status form will display information about the internal state
      of <emphasis remap="B">pluto</emphasis>: information about each
      potential connection, about each state object, and about each shunt that
      <emphasis remap="B">pluto</emphasis> is managing without an associated
      connection.</para>

      <para>Statistics can be seen using <emphasis remap="B">ipsec whack --globalstats</emphasis>
      and reset using <emphasis remap="B">ipsec whack --clearstats</emphasis>.
      This can be used with the munin software to monitor VPN services.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--status</option></term>

          <listitem>
            <para></para>

            <!-- FIXME: blank list item -->
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The trafficstatus form will display the xauth username, add_time and the total in and
      out bytes of the IPsec SA's.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--trafficstatus</option></term>

          <listitem>
            <para></para>

            <!-- FIXME: blank list item -->
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The shutdown form is the proper way to shut down <emphasis
      remap="B">pluto</emphasis>. It will tear down the SAs on this machine
      that <emphasis remap="B">pluto</emphasis> has negotiated. If the
      <emphasis remap="B">--leave-state</emphasis> option is given, it does not
      delete any connections, and leaves the kernel state in the kernel. Note that
      the init system used might clean up the kernel state regardless.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--shutdown</option></term>

          <listitem>
            <para></para>

            <!-- FIXME: blank list item -->
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

    <refsect2 id="examples">
      <title>Examples</title>

      <para>It would be normal to start <emphasis remap="B">pluto</emphasis>
      in one of the system initialization scripts. It needs to be run by the
      superuser. Generally, no arguments are needed. To run in manually, the
      superuser can simply type</para>

      <para>&nbsp;&nbsp;&nbsp;ipsec pluto</para>

      <para>The command will immediately return, but a <emphasis
      remap="B">pluto</emphasis> process will be left running, waiting for
      requests from <emphasis remap="B">whack</emphasis> or a peer.</para>

      <para>Using <emphasis remap="B">whack</emphasis>, several potential
      connections would be described:</para>

      <!-- .na -->

      <para>&nbsp;&nbsp;&nbsp;ipsec whack --name&nbsp;silly
      --host&nbsp;127.0.0.1 --to --host&nbsp;127.0.0.2 --ikelifetime&nbsp;900
      --ipseclifetime&nbsp;800 --keyingtries&nbsp;3</para>

      <!-- .ad -->

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

      <!-- .na -->

      <para>&nbsp;&nbsp;&nbsp;ipsec whack --name&nbsp;conn_name
      --host&nbsp;10.0.0.1 --client&nbsp;10.0.1.0/24 --to --host&nbsp;10.0.0.2
      --client&nbsp;10.0.2.0/24 --encrypt</para>

      <!-- .ad -->

      <para>This is something that must be done on both sides. If the other
      side is <emphasis remap="B">pluto</emphasis>, the same <emphasis
      remap="B">whack</emphasis> command could be used on it (the command
      syntax is designed to not distinguish which end is ours).</para>

      <para>Now that the connections are specified, <emphasis
      remap="B">pluto</emphasis> is ready to handle requests and replies via
      the public interfaces. We must tell it to discover those interfaces and
      start accepting messages from peers:</para>

      <para>&nbsp;&nbsp;&nbsp;ipsec whack --listen</para>

      <para>If we don't immediately wish to bring up a secure connection
      between the two clients, we might wish to prevent insecure traffic. The
      routing form asks <emphasis remap="B">pluto</emphasis> to cause the
      packets sent from our client to the peer's client to be routed through
      the ipsec0 device; if there is no SA, they will be discarded:</para>

      <para>&nbsp;&nbsp;&nbsp;ipsec whack --route conn_name</para>

      <para>Finally, we are ready to get <emphasis remap="B">pluto</emphasis>
      to initiate negotiation for an IPsec SA (and implicitly, an ISAKMP
      SA):</para>

      <para>&nbsp;&nbsp;&nbsp;ipsec whack
      --initiate&nbsp;--name&nbsp;conn_name</para>

      <para>A small log of interesting events will appear on standard output
      (other logging is sent to syslog).</para>

      <para><emphasis remap="B">whack</emphasis> can also be used to terminate
      <emphasis remap="B">pluto</emphasis> cleanly, tearing down all SAs that
      it has negotiated.</para>

      <para>&nbsp;&nbsp;&nbsp;ipsec whack --shutdown</para>

      <para>Notification of any IPSEC SA deletion, but not ISAKMP SA deletion
      is sent to the peer. Unfortunately, such Notification is not reliable.
      Furthermore, <emphasis remap="B">pluto</emphasis> itself ignores
      Notifications.</para>
    </refsect2>

    <refsect2 id="xauth">
      <title>XAUTH</title>

      <para>If <emphasis remap="B">pluto</emphasis> needs additional
      authentication, such as defined by the XAUTH specifications, then it may
      ask <emphasis remap="B">whack</emphasis> to prompt the operator for
      username or passwords. Typically, these will be entered interactively. A
      GUI that wraps around <emphasis remap="B">whack</emphasis> may look for
      the 041 (username) or 040 (password) prompts, and display them to the
      user.</para>

      <para>For testing purposes, the options
      <option>--xauthuser&nbsp;</option><replaceable>user</replaceable>
      <option>--xauthpass&nbsp;</option><replaceable>pass</replaceable> may be
      be given prior to the <option>--initiate&nbsp;</option> to provide
      responses to the username and password prompts.</para>
    </refsect2>

    <refsect2 id="the_updown_command">
      <title>The updown command</title>

      <para>Whenever <emphasis remap="B">pluto</emphasis> brings a connection
      up or down, it invokes the updown command. This command is specified
      using the <option>--updown</option> option. This allows for customized
      control over routing and firewall manipulation.</para>

      <para>The updown is invoked for five different operations. Each of these
      operations can be for our client subnet or for our host itself.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><emphasis remap="B">prepare-host</emphasis> or <emphasis
          remap="B">prepare-client</emphasis></term>

          <listitem>
            <para>is run before bringing up a new connection if no other
            connection with the same clients is up. Generally, this is useful
            for deleting a route that might have been set up before <emphasis
            remap="B">pluto</emphasis> was run or perhaps by some agent not
            known to <emphasis remap="B">pluto</emphasis>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">route-host</emphasis> or <emphasis
          remap="B">route-client</emphasis></term>

          <listitem>
            <para>is run when bringing up a connection for a new peer client
            subnet (even if <emphasis remap="B">prepare-host</emphasis> or
            <emphasis remap="B">prepare-client</emphasis> was run). The
            command 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.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">unroute-host</emphasis> or <emphasis
          remap="B">unroute-client</emphasis></term>

          <listitem>
            <para>is run when bringing down the last connection for a
            particular peer client subnet. It should undo what the <emphasis
            remap="B">route-host</emphasis> or <emphasis
            remap="B">route-client</emphasis> did.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">up-host</emphasis> or <emphasis
          remap="B">up-client</emphasis></term>

          <listitem>
            <para>is run when bringing up a tunnel eroute with a pair of
            client subnets that does not already have a tunnel eroute. This
            command should install firewall rules as appropriate. It is
            generally a good idea to allow IKE messages (UDP port 500) travel
            between the hosts.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">down-host</emphasis> or <emphasis
          remap="B">down-client</emphasis></term>

          <listitem>
            <para>is run when bringing down the eroute for a pair of client
            subnets. This command should delete firewall rules as appropriate.
            Note that there may remain some inbound IPsec SAs with these
            client subnets.</para>
          </listitem>
        </varlistentry>
      </variablelist>

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

      <variablelist remap="TP">
        <varlistentry>
          <term><emphasis remap="B">PLUTO_VERSION</emphasis></term>

          <listitem>
            <para>indicates what version of this interface is being used. This
            document describes version 1.1. This is upwardly compatible with
            version 1.0.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_VERB</emphasis></term>

          <listitem>
            <para>specifies the name of the operation to be performed
            (<emphasis remap="B">prepare-host</emphasis>,r <emphasis
            remap="B">prepare-client</emphasis>, <emphasis
            remap="B">up-host</emphasis>, <emphasis
            remap="B">up-client</emphasis>, <emphasis
            remap="B">down-host</emphasis>, or <emphasis
            remap="B">down-client</emphasis>). If the address family for
            security gateway to security gateway communications is IPv6, then
            a suffix of -v6 is added to the verb.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_CONNECTION</emphasis></term>

          <listitem>
            <para>is the name of the connection for which we are
            routing.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_NEXT_HOP</emphasis></term>

          <listitem>
            <para>is the next hop to which packets bound for the peer must be
            sent.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_INTERFACE</emphasis></term>

          <listitem>
            <para>is the name of the ipsec interface to be used.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_ME</emphasis></term>

          <listitem>
            <para>is the IP address of our host.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_MY_CLIENT</emphasis></term>

          <listitem>
            <para>is the IP address / count of our client subnet. If the
            client is just the host, this will be the host's own IP address /
            max (where max is 32 for IPv4 and 128 for IPv6).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_MY_CLIENT_NET</emphasis></term>

          <listitem>
            <para>is the IP address of our client net. If the client is just
            the host, this will be the host's own IP address.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_MY_CLIENT_MASK</emphasis></term>

          <listitem>
            <para>is the mask for our client net. If the client is just the
            host, this will be 255.255.255.255.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_PEER</emphasis></term>

          <listitem>
            <para>is the IP address of our peer.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_PEER_CLIENT</emphasis></term>

          <listitem>
            <para>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).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_PEER_CLIENT_NET</emphasis></term>

          <listitem>
            <para>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.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_PEER_CLIENT_MASK</emphasis></term>

          <listitem>
            <para>is the mask for the peer's client net. If the client is just
            the peer, this will be 255.255.255.255.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_MY_PROTOCOL</emphasis></term>

          <listitem>
            <para>lists the protocols allowed over this IPsec SA.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_PEER_PROTOCOL</emphasis></term>

          <listitem>
            <para>lists the protocols the peer allows over this IPsec
            SA.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_MY_PORT</emphasis></term>

          <listitem>
            <para>lists the ports allowed over this IPsec SA.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_PEER_PORT</emphasis></term>

          <listitem>
            <para>lists the ports the peer allows over this IPsec SA.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_MY_ID</emphasis></term>

          <listitem>
            <para>lists our id.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_PEER_ID</emphasis></term>

          <listitem>
            <para>Dlists our peer's id.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><emphasis remap="B">PLUTO_PEER_CA</emphasis></term>

          <listitem>
            <para>lists the peer's CA.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>All output sent by the script to stderr or stdout is logged. The
      script should return an exit status of 0 if and only if it
      succeeds.</para>

      <para><emphasis remap="B">Pluto</emphasis> waits for the script to
      finish and will not do any other processing while it is waiting. The
      script may assume that <emphasis remap="B">pluto</emphasis> will not
      change anything while the script runs. The script should avoid doing
      anything that takes much time and it should not issue any command that
      requires processing by <emphasis remap="B">pluto</emphasis>. Either of
      these activities could be performed by a background subprocess of the
      script.</para>
    </refsect2>

    <refsect2 id="rekeying">
      <title>Rekeying</title>

      <para>When an SA that was initiated by <emphasis
      remap="B">pluto</emphasis> has only a bit of lifetime left, <emphasis
      remap="B">pluto</emphasis> 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 than the rekeymargin plus a random
      percentage, between 0 and rekeyfuzz, of the rekeymargin.</para>

      <para>Similarly, when an SA that was initiated by the peer has only a
      bit of lifetime left, <emphasis remap="B">pluto</emphasis> will try to
      initiate the creation of a replacement. 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 responder for the old SA will be the
      initiator for the replacement. The former initiator might also initiate
      rekeying, so there may be redundant SAs created. To avoid these
      complications, make sure that rekeymargin is generous.</para>

      <para>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 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 the former initiator is
      initiating). These may be stricter than those of the connection.</para>

      <para><emphasis remap="B">pluto</emphasis> will not rekey an SA if that
      SA is not the most recent of its type (IPsec or ISAKMP) for its
      potential connection. This avoids creating redundant SAs.</para>

      <para>The random component in the rekeying time (rekeyfuzz) is intended
      to make certain pathological patterns of rekeying unstable. If both
      sides decide to rekey at the same time, twice as many SAs as necessary
      are created. This could become a stable pattern without the
      randomness.</para>

      <para>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, entropy for random numbers).
      The rekeyfuzz can be used to stagger the rekeying times.</para>

      <para>Once a new set of SAs has been negotiated, <emphasis
      remap="B">pluto</emphasis> will never send traffic on a superseded one.
      Traffic will be accepted on an old SA until it expires.</para>
    </refsect2>

    <refsect2 id="selecting_a_connection_when_responding_r">
      <title>Selecting a Connection When Responding: Road Warrior
      Support</title>

      <para>When <emphasis remap="B">pluto</emphasis> 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 which case one of them is arbitrarily chosen. (The ISAKMP SA proposal
      contained in the message could be taken into account, but it is
      not.)</para>

      <para>The ISAKMP SA is negotiated before the parties pass further
      identifying information, so all ISAKMP SA characteristics specified in
      the connection description should be the same for every connection with
      the same two host IP addresses. At the moment, the only characteristic
      that might differ is authentication method.</para>

      <para>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.</para>

      <para>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 <emphasis remap="B">%any</emphasis> as the
      other. If it cannot find one, it refuses to negotiate. If it does find
      one, it creates a temporary connection that is a duplicate except with
      the <emphasis remap="B">%any</emphasis> replaced by the source IP
      address from the packet; if there was no identity specified for the
      peer, the new IP address will be used.</para>

      <para>When <emphasis remap="B">pluto</emphasis> is using one of these
      temporary connections and needs to find the preshared secret or RSA
      private key in <emphasis remap="I">ipsec.secrets</emphasis>, and the
      connection specified no identity for the peer, <emphasis
      remap="B">%any</emphasis> 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 this table.</para>

      <para>Part way into the Phase 1 (Main Mode) negotiation using one of
      these temporary connection descriptions, <emphasis
      remap="B">pluto</emphasis> will receive an Identity Payload. At this
      point, <emphasis remap="B">pluto</emphasis> checks for a more
      appropriate connection, one with an identity for the peer that matches
      the payload and would use the same keys as so far used for
      authentication. If it finds one, it will switch to using this better
      connection (or a temporary one derived from this, if it has <emphasis
      remap="B">%any</emphasis> for the peer's IP address). It may even turn
      out that no connection matches the newly discovered identity, including
      the current connection; if so, <emphasis remap="B">pluto</emphasis>
      terminates negotiation.</para>

      <para>Unfortunately, if 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 systems
      connecting to a host. RSA Signature authentication does not require
      that the responder knows how to select the initiator's public key until
      after the initiator's Identity Payload is decoded (using the responder's
      private key, so that must be preselected).</para>

      <para>When <emphasis remap="B">pluto</emphasis> 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 the temporary connection description. If so, it will look for a
      connection with matching subnets, its own host address, a peer address
      of <emphasis remap="B">%any</emphasis> 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,
      <emphasis remap="B">pluto</emphasis> terminates negotiation.</para>

      <para>Be sure to specify an appropriate nexthop for the responder to
      send a message to the initiator: <emphasis remap="B">pluto</emphasis>
      has no way of guessing it (if forwarding isn't required, use an explicit
      <emphasis remap="B">%direct</emphasis> as the nexthop and the IP address
      of the initiator will be filled in; the obsolete notation
      <literal>0.0.0.0</literal> is still accepted).</para>

      <para><emphasis remap="B">pluto</emphasis> has no special provision for
      the initiator side. The current (possibly dynamic) IP address and
      nexthop must be used in defining connections. These must be properly
      configured each time the initiator's IP address changes. <emphasis
      remap="B">pluto</emphasis> has no mechanism to do this
      automatically.</para>

      <para>Although we call this Road Warrior Support, it could also be used
      to support encrypted connections with anonymous initiators. The
      responder'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.</para>

      <para>If any Road Warrior connections are supported, <emphasis
      remap="B">pluto</emphasis> cannot reject an exchange initiated by an
      unknown host 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 connection 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.</para>

      <para>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 <option>--keyingtries</option> to 1 in the
      connection on the non-mobile side to prevent it trying to rekey the
      connection. Unfortunately, there is no mechanism to unroute the
      connection automatically.</para>
    </refsect2>

    <refsect2 id="debugging">
      <title>Debugging</title>

      <para><emphasis remap="B">pluto</emphasis> accepts several optional
      arguments, useful mostly for debugging. Except for
      <option>--interface</option>, each should appear at most once.</para>

      <variablelist remap="TP">
        <varlistentry>
          <term><option>--interface</option>
          <replaceable>interfacename</replaceable></term>

          <listitem>
            <para>specifies that the named real public network interface
            should be considered. The interface name specified should not be
            <command>ipsec</command><emphasis remap="I">N</emphasis>. 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.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ikeport</option>
          <replaceable>port-number</replaceable></term>

          <listitem>
            <para>changes the UDP port that <emphasis
            remap="B">pluto</emphasis> will use (default, specified by IANA:
            500)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ctlbase</option>
          <replaceable>path</replaceable></term>

          <listitem>
            <para>basename for control files. <emphasis
            remap="I">path</emphasis>.ctl is the socket through which
            <emphasis remap="B">whack</emphasis> communicates with <emphasis
            remap="B">pluto</emphasis>. <emphasis
            remap="I">path</emphasis>.pid is the lockfile to prevent multiple
            <emphasis remap="B">pluto</emphasis> instances. The default is
            <filename>/var/run/pluto/pluto</filename>).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--secretsfile</option>
          <replaceable>file</replaceable></term>

          <listitem>
            <para>specifies the file for authentication secrets (default:
            <filename>@IPSEC_SECRETS_FILE@</filename>). This name is subject to
            "globbing" as in <citerefentry>
                <refentrytitle>sh</refentrytitle>

                <manvolnum>1</manvolnum>
              </citerefentry>, so every file with a matching name is
            processed. Quoting is generally needed to prevent the shell from
            doing the globbing.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--nofork</option></term>

          <listitem>
            <para>disable "daemon fork" (default is to fork). In addition,
            after the lock file and control socket are created, print the line
            "Pluto initialized" to standard out.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--uniqueids</option></term>

          <listitem>
            <para>if this option has been selected, whenever a new ISAKMP SA
            is established, any connection with the same Peer ID but a
            different 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.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--force-busy</option></term>

          <listitem>
            <para>if this option has been selected, pluto will be forced
            to be "busy". In this state, which happens when there is a
            Denial of Service attack, will force pluto to use cookies
            before accepting new incoming IKE packets. Cookies are send
            and required in ikev1 Aggressive Mode and in ikev2.
            This option is mostly used for testing purposes, but can
            be selected by paranoid administrators as well.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--stderrlog</option></term>

          <listitem>
            <para>log goes to standard out {default is to use <citerefentry>
                <refentrytitle>syslogd</refentrytitle>

                <manvolnum>8</manvolnum>
              </citerefentry>)</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>
	<emphasis remap="B">pluto</emphasis> is willing to produce a
	prodigious amount of debugging information.  There are several
	classes of debugging output, and <emphasis
	remap="B">pluto</emphasis> may be directed to produce a
	selection of them.  All lines of debugging output are prefixed
	with "|&nbsp;" to distinguish them from normal diagnostic
	messages.
      </para>

      <para>
	When <emphasis remap="B">pluto</emphasis> is invoked, it may
	be given arguments to specify which debug classes to output.
	The current options are:
      </para>

      <variablelist remap="TP">

        <varlistentry>
          <term><option>--debug help</option> (whack only)</term>
          <listitem>
            <para>
	      list the debugging classes recognised by <emphasis
	      remap="B">pluto</emphasis>
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--debug none</option></term>
          <listitem>
            <para>disable logging for all debugging classes</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--debug base</option></term>
          <listitem>
            <para>
	      enable debug-logging
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--debug cpu-usage</option></term>
          <listitem>
            <para>
	      enable cpu-usage logging
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--debug <replaceable>class</replaceable></option></term>
          <term><option>--no-debug <replaceable>class</replaceable></option></term>
          <term><option>--debug no-<replaceable>class</replaceable></option></term>
          <listitem>
            <para>
	      enable (disable) logging of the specified debugging
	      <replaceable>class</replaceable> (<option>--debug
	      help</option> lists debugging classes supported by this
	      version of <emphasis remap="B">pluto</emphasis>)
	    </para>
          </listitem>
        </varlistentry>

      </variablelist>

      <para>
	The debug form of the <emphasis remap="B">whack</emphasis>
	command will change the selection in a running <emphasis
	remap="B">pluto</emphasis>. If a connection name is specified,
	the flags are added whenever <emphasis
	remap="B">pluto</emphasis> has identified that it is dealing
	with that connection.  Unfortunately, this is often part way
	into the operation being observed.
      </para>

      <para>
	For example, to start <emphasis remap="B">pluto</emphasis>
	with both <emphasis>base</emphasis> and
	<emphasis>cpu-usage</emphasis> debug-logging enabled:
      </para>

      <programlisting>
	pluto --debug base --debug cpu-usage
      </programlisting>

      <para>
	To later change this <emphasis remap="B">pluto</emphasis> to
	disable <emphasis>base</emphasis> debug-logging use either:
      </para>

      <programlisting>
	whack --no-debug base
      </programlisting>
      <para>
	or:
      </para>
      <programlisting>
	whack --debug none --debug cpu-usage
      </programlisting>

    </refsect2>

    <refsect2 id="impairing">
      <title>Impairing</title>

      <para>
	<emphasis remap="B">pluto</emphasis> and <emphasis
	remap="B">whack</emphasis> accept several optional arguments
	that alter (impair) correct behaviour.
      </para>
      <para>
	These options are solely intended for use by developers when
	testing <emphasis remap="B">pluto</emphasis>.
      </para>

      <variablelist remap="TP">

        <varlistentry>
          <term><option>--impair help</option> (whack only)</term>
          <listitem>
            <para>
	      list all the behaviours that can be altered (impaired)
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--impair list</option> (whack only)</term>
          <listitem>
            <para>
	      list all the behaviours that are currently altered (impaired)
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--impair none</option></term>
          <listitem>
            <para>
	      disable all altered (impaired) behaviours
	    </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--impair <replaceable>behaviour</replaceable></option></term>
          <term><option>--impair <replaceable>behaviour</replaceable>:<replaceable>how</replaceable></option></term>
          <term><option>--no-impair <replaceable>behaviour</replaceable></option></term>
          <listitem>
            <para>
	      alter (impair) <emphasis remap="B">pluto</emphasis>
	      inducing the (possibly erroneous)
	      <replaceable>behaviour</replaceable>
	    </para>
          </listitem>
        </varlistentry>

      </variablelist>

    </refsect2>

    <refsect2 id="plutos_behaviour_when_things_go_wrong">
      <title>Pluto's Behaviour When Things Go Wrong</title>

      <para>When <emphasis remap="B">pluto</emphasis> doesn't understand or
      accept a message, it just ignores the message. It is not yet capable of
      communicating the problem to the other IKE daemon (in the future it
      might use Notifications to accomplish this in many cases). It does log a
      diagnostic.</para>

      <para>When <emphasis remap="B">pluto</emphasis> gets 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.</para>

      <para>When pluto gets a message that it has already seen, there are many
      cases when it notices and discards it. This too is appropriate for
      UDP.</para>

      <para>Combine these three rules, and you can explain many apparently
      mysterious behaviours. In a <emphasis remap="B">pluto</emphasis> log,
      retrying isn't usually the interesting event. The critical thing is
      either earlier (<emphasis remap="B">pluto</emphasis> got a message that
      it didn't like and so ignored, so it was still awaiting an acceptable
      message and got impatient) or on the other system (<emphasis
      remap="B">pluto</emphasis> didn't send a reply because it wasn't happy
      with the previous message).</para>
    </refsect2>

    <refsect2 id="notes">
      <title>Notes</title>

      <para>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. <emphasis
      remap="B">Pluto</emphasis> also avoids choosing an SPI in the range
      0x100 to 0xFFF, leaving these SPIs free for manual keying. Remember that
      the peer, if not <emphasis remap="B">pluto</emphasis>, may well chose
      SPIs in this range.</para>
    </refsect2>

    <refsect2 id="policies">
      <title>Policies</title>

      <para>This catalogue of policies may be of use when trying to configure
      <emphasis remap="B">Pluto</emphasis> and another IKE implementation to
      interoperate.</para>

      <para>In Phase 1, only Main Mode is supported. We are not sure that
      Aggressive Mode is secure. For one thing, it does not support identity
      protection. It may allow more severe Denial Of Service attacks.</para>

      <para>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.</para>

      <para>No Informational Payloads are supported. These are optional, but
      useful. It is of concern that these payloads are not authenticated in
      Phase 1, nor in those Phase 2 messages authenticated with
      HASH(3).</para>

      <variablelist remap="IP">
        <varlistentry>
          <term>•</term>

          <listitem>
            <para>Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) are
            supported. Group MODP768 (1) is not supported because it is too
            weak.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>Host authentication can be done by RSA Signatures or
            Pre-Shared Secrets.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>3DES CBC (Cypher Block Chaining mode) is the only encryption
            supported, both for ISAKMP SAs and IPSEC SAs.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>MD5 and SHA1 hashing are supported for packet authentication
            in both kinds of SAs.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>The ESP, AH, or AH plus ESP are supported. If, and only if,
            AH and ESP are combined, the ESP need not have its own
            authentication component. The selection is controlled by the
            --encrypt and --authenticate flags.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>Each of these may be combined with IPCOMP Deflate
            compression, but only if the potential connection specifies
            compression.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>The IPSEC SAs may be tunnel or transport mode, where
            appropriate. The --tunnel flag controls this when <emphasis
            remap="B">pluto</emphasis> is initiating.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>When responding to an ISAKMP SA proposal, the maximum
            acceptable lifetime is eight hours. The default is one hour. There
            is no minimum. The --ikelifetime flag controls this when <emphasis
            remap="B">pluto</emphasis> is initiating.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>When responding to an IPSEC SA proposal, the maximum
            acceptable lifetime is one day. The default is eight hours. There
            is no minimum. The --ipseclifetime flag controls this when
            <emphasis remap="B">pluto</emphasis> is initiating.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>•</term>

          <listitem>
            <para>PFS is acceptable, and will be proposed if the --pfs flag
            was specified. The DH group proposed will be the same as
            negotiated for Phase 1.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>

  <refsect1 id="signals">
    <title>SIGNALS</title>

    <para><emphasis remap="B">Pluto</emphasis> responds to
    <constant>SIGHUP</constant> by issuing a suggestion that ``<emphasis
    remap="B">whack</emphasis> --listen'' might have been intended.</para>

    <para><emphasis remap="B">Pluto</emphasis> exits when it receives
    <constant>SIGTERM</constant>.</para>
  </refsect1>

  <refsect1 id="exit_status">
    <title>EXIT STATUS</title>

    <para><emphasis remap="B">pluto</emphasis> normally forks a daemon
    process, so the exit status is normally a very preliminary result.</para>

    <variablelist remap="TP">
      <varlistentry>
        <term>0</term>

        <listitem>
          <para>means that all is OK so far.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>1</term>

        <listitem>
          <para>means that something was wrong.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>10</term>

        <listitem>
          <para>means that the lock file already exists.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>If <emphasis remap="B">whack</emphasis> detects a problem, it will
    return an exit status of 1. If it received progress messages from
    <emphasis remap="B">pluto</emphasis>, it returns as status the value of
    the numeric prefix from the last such message that was not a message sent
    to syslog or a comment (but the prefix for success is treated as 0).
    Otherwise, the exit status is 0.</para>
  </refsect1>

  <refsect1 id="files">
    <title>FILES</title>

    <para><filename>/var/run/pluto/pluto.pid</filename> <!-- .br -->
    <filename>/var/run/pluto/pluto.ctl</filename> <!-- .br -->
    <filename>@IPSEC_SECRETS_FILE@</filename> <!-- .br -->
    <filename>/dev/urandom</filename></para>
  </refsect1>

  <refsect1 id="environment">
    <title>ENVIRONMENT</title>

    <para>pluto does not use any environment variables</para>
  </refsect1>

  <refsect1 id="see_also">
    <title>SEE ALSO</title>

    <para>The rest of the Libreswan distribution, in particular <citerefentry>
        <refentrytitle>ipsec</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry>.</para>

    <para><citerefentry>
        <refentrytitle>ipsec_auto</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry> is designed to make using <emphasis
    remap="B">pluto</emphasis> more pleasant. Use it!</para>

    <para><citerefentry>
        <refentrytitle>ipsec.secrets</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry> describes the format of the secrets file.</para>

    <para><citerefentry>
        <refentrytitle>ipsec_atoaddr</refentrytitle>

        <manvolnum>3</manvolnum>
      </citerefentry>, part of the Libreswan distribution, describes the forms
    that IP addresses may take. <citerefentry>
        <refentrytitle>ipsec_atosubnet</refentrytitle>

        <manvolnum>3</manvolnum>
      </citerefentry>, part of the Libreswan distribution, describes the forms
    that subnet specifications.</para>

    <para>For more information on IPsec, the mailing list, and the relevant
    documents, see:</para>

    <para><emphasis remap="I"><ulink
    url="https://datatracker.ietf.org/wg/ipsecme/charter/">https://datatracker.ietf.org/wg/ipsecme/charter/</ulink></emphasis></para>

    <para>At the time of writing, the latest IETF IKE RFC is:</para>

    <para>RFC 7296 Internet Key Exchange Protocol Version 2 (IKEv2)</para>

    <para>The Libreswan web site &lt;https://libreswan.org&gt; and the mailing
    lists described there.</para>

    <para>The Libreswan wiki &lt;https://libreswan.org/wiki&gt; and the mailing
    lists described there.</para>

    <para>The Libreswan list of implemented RFCs &lt;https://libreswan.org/wiki/Implemented_Standards&gt;</para>
  </refsect1>

  <refsect1 id="history">
    <title>HISTORY</title>

    <para>This code is released under the GPL terms. See the accompanying
    files CHANGES COPYING and CREDITS.* for more details.</para>

    <para>Detailed history (including FreeS/WAN and Openswan) can be found in the docs/ directory.</para>

  </refsect1>

  <refsect1 id="bugs">
    <title>BUGS</title>

    <para>Please see
    &lt;<ulink url="https://bugs.libreswan.org">https://bugs.libreswan.org</ulink>&gt;
    for a list of currently known bugs and missing features.</para>

    <para>Bugs should be reported to the &lt;swan-dev@lists.libreswan.org&gt;
    mailing list.</para>
  </refsect1>
</refentry>