<?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>
<refentryinfo>
  <author><firstname>Paul</firstname><surname>Wouters</surname><authorblurb><para>placeholder to suppress warning</para> </authorblurb></author>
</refentryinfo>
<refmeta>
<refentrytitle>IPSEC_AUTO</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class='date'>25 Oct 2006</refmiscinfo>
<refmiscinfo class="source">libreswan</refmiscinfo>
<refmiscinfo class="manual">Executable programs</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>ipsec auto</refname>
<refpurpose>control automatically-keyed IPsec connections</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv id='synopsis'>
<cmdsynopsis>
  <command>ipsec</command>
    <arg choice='plain'><replaceable>auto</replaceable></arg>
    <arg choice='opt'>--showonly </arg>
    <arg choice='opt'>--asynchronous </arg>
    <sbr/>
    <arg choice='opt'><arg choice='plain'>--config </arg><arg choice='plain'><replaceable>configfile</replaceable></arg></arg>
    <arg choice='opt'>--verbose </arg>
    <arg choice='plain'><replaceable>operation
connection</replaceable></arg>
    <sbr/>
</cmdsynopsis>
<cmdsynopsis>
  <command>ipsec</command>
    <arg choice='plain'><replaceable>auto</replaceable></arg>
    <arg choice='opt'>--showonly </arg>
    <arg choice='opt'>--asynchronous </arg>
    <sbr/>
    <arg choice='opt'><arg choice='plain'>--config </arg><arg choice='plain'><replaceable>configfile</replaceable></arg></arg>
    <arg choice='opt'>--verbose </arg>
    <arg choice='plain'><replaceable>operation
connection</replaceable></arg>
    <sbr/>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1 id='examples'><title>EXAMPLES</title>
<cmdsynopsis>
  <command>ipsec</command>
    <arg choice='plain'><replaceable>auto</replaceable></arg>
    <arg choice='plain'>{ --add | --delete | --replace | --start }</arg>
    <arg choice='plain'><replaceable>connection</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
  <command>ipsec</command>
    <arg choice='plain'><replaceable>auto</replaceable></arg>
    <arg choice='plain'>{ --up | --down }</arg>
    <arg choice='plain'><replaceable>connection</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
  <command>ipsec</command>
    <arg choice='plain'><replaceable>auto</replaceable></arg>
    <arg choice='plain'>{ --route | --unroute | --ondemand }</arg>
    <arg choice='plain'><replaceable>connection</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
  <command>ipsec</command>
    <arg choice='plain'><replaceable>auto</replaceable></arg>
    <arg choice='plain'>{ --status | --ready  }</arg>
</cmdsynopsis>
<cmdsynopsis>
  <command>ipsec</command>
    <arg choice='plain'><replaceable>auto</replaceable></arg>
    <arg choice='opt'>--utc </arg>
    <arg choice='opt'>--listall | --rereadall </arg>
    <arg choice='opt'>--rereadsecrets </arg>
    <arg choice='opt'>--listcerts </arg>
    <arg choice='opt'>--listpubkeys </arg>
    <arg choice='opt'>--checkpubkeys </arg>
    <arg choice='opt'>--listcacerts</arg>
    <arg choice='opt'>--fetchcrls </arg>
    <arg choice='opt'>--listcrls </arg>
    <arg choice='opt'>--purgeocsp </arg>

</cmdsynopsis>
<cmdsynopsis>
  <command>ipsec</command>
    <arg choice='plain'><replaceable>auto</replaceable></arg>
    <arg choice='opt'>--utc </arg>
    <arg choice='opt'>--rereadcerts</arg>
    <arg choice='plain'><replaceable>connection</replaceable></arg>
</cmdsynopsis>
</refsect1>
<refsect1 id='description'><title>DESCRIPTION</title>
<para><emphasis remap='I'>Auto</emphasis>
manipulates automatically-keyed Libreswan IPsec connections,
setting them up and shutting them down
based on the information in the IPsec configuration file.
In the normal usage,
<emphasis remap='I'>connection</emphasis>
is the name of a connection specification in the configuration file;
<emphasis remap='I'>operation</emphasis>
is
<option>--add</option>,
<option>--delete</option>,
<option>--replace</option>,
<option>--start</option>,
<option>--up</option>,
<option>--down</option>,
<option>--route</option>,
<option>--unroute</option>,
<option>--ondemand</option>,
The
<option>--ready</option>,
<option>--rereadsecrets</option>,
and
<option>--status</option>
<replaceable>operations</replaceable> do not take a connection name.
<emphasis remap='I'>Auto</emphasis>
generates suitable
commands and feeds them to a shell for execution.</para>

<para>The
<option>--add</option>
operation adds a connection specification to the internal database
within
<emphasis remap='I'>pluto</emphasis>;
it will fail if
<emphasis remap='I'>pluto</emphasis>
already has a specification by that name.
The
<option>--delete</option>
operation deletes a connection specification from
<emphasis remap='I'>pluto</emphasis>'s
internal database (also tearing down any connections based on it);
The
<option>--replace</option>
operation is equivalent to
<option>--delete</option>
(if there is already a loaded connection by the given name)
followed by
<option>--add</option>,
and is a convenience for updating
<emphasis remap='I'>pluto</emphasis>'s
internal specification to match an external one.
(Note that a
<option>--rereadsecrets</option>
may also be needed.)
The
<option>--start</option>
operation is equivalent to running first with
<option>--add</option>
and then with
<option>--up</option>, causing same effect as connection configuration option
<option>auto=start</option>.
</para>

<para>The
<option>--up</option>
operation asks
<emphasis remap='I'>pluto</emphasis>
to establish a connection based on an entry in its internal database.
The
<option>--down</option>
operation tells
<emphasis remap='I'>pluto</emphasis>
to tear down such a connection.</para>

<para>Normally,
<emphasis remap='I'>pluto</emphasis>
establishes a route to the destination specified for a connection as
part of the
<option>--up</option>
operation.
However, the route can be established with the
<option>--route</option>
operation.
Until and unless an actual connection is established,
this discards any packets sent there,
which may be preferable to having them sent elsewhere based on a more
general route (e.g., a default route).</para>

<para>Normally,
<emphasis remap='I'>pluto</emphasis>'s
route  to a destination remains in place when a
<option>--down</option>
operation is used to take the connection down
(or if connection setup, or later automatic rekeying, fails).
This permits establishing a new connection (perhaps using a
different specification; the route is altered as necessary)
without having a &ldquo;window&rdquo; in which packets might go elsewhere
based on a more general route.
Such a route can be removed using the
<option>--unroute</option>
operation
(and is implicitly removed by
<option>--delete</option>).</para>

<para>The
<option>--ondemand</option>
operation is equivalent to running first with
<option>--add</option>
and then with
<option>--route</option>, causing same effect as connection configuration option
<option>auto=ondemand</option>.</para>

<para>The
<option>--ready</option>
operation tells
<emphasis remap='I'>pluto</emphasis>
to listen for connection-setup requests from other hosts.
Doing an
<option>--up</option>
operation before doing
<option>--ready</option>
on both ends is futile and will not work,
although this is now automated as part of IPsec startup and
should not normally be an issue.</para>

<para>The
<option>--status</option>
operation asks
<emphasis remap='I'>pluto</emphasis>
for current connection status.
The output format is ad-hoc and likely to change.</para>

<para>The
<option>--rereadsecrets</option>
operation tells
<emphasis remap='I'>pluto</emphasis>
to re-read the
<filename>@IPSEC_SECRETS_FILE@</filename>
secret-keys file,
which it normally reads only at startup time.
(This is currently a synonym for
<option>--ready</option>,
but that may change.)</para>

<para>       The <option>--fetchcrls</option> operation reads all certificate revocation list  (CRL)
       entries of loaded certificates and tries to fetch updates for these from the CRL servers.
</para>
<para>       The <option>--rereadall</option> operation is equivalent to the execution of
         --rereadsecrets (in the past there were other kinds of reread operations)
</para>
<para>       The <option>--listpubkeys</option> operation lists all RSA public keys  either  received
       from  peers  via the IKE protocol embedded in authenticated certificate
       payloads or loaded locally using the rightcert /  leftcert  or  rightr-
       sasigkey / leftrsasigkey parameters in ipsec.conf(5).

</para>
<para>      The  <option>--listcerts</option>  operation  lists  all  X.509 certificates
       loaded  locally  using  the  rightcert  and  leftcert   parameters   in
       ipsec.conf(5). To see all certificates in the NSS database, use <option>certutil -d @IPSEC_NSSDIR@ -L</option>.
</para>
<para>      The  <option>--checkpubkeys</option>  operation  lists  all loaded X.509 certificates
	that are about to expire or have expired.
</para>
<para>       The  <option>--listcacerts</option>  operation  lists  all  X.509 CA certificates contained in
	the NSS database.
</para>
<para>       The <option>--listcrls</option> operation lists all Certificate Revocation Lists  (CRLs)
       either  loaded  locally from the /etc/ipsec.d/crls directory or fetched
       dynamically from an HTTP or LDAP server.
</para>
<para>       The  <option>--listall</option>  operation is equivalent to the execution of
       --listpubkeys,  --listcerts,  --listcacerts,  --listcrls.
</para>
<para>       The  <option>--purgeocsp</option>  operation displays --listall and purges the NSS OCSP cache.
</para>

<para>The
<option>--showonly</option>
option causes
<emphasis remap='I'>auto</emphasis>
to show the commands it would run, on standard output,
and not run them.</para>

<para>The
<option>--asynchronous</option>
option, applicable only to the
<emphasis remap='B'>up</emphasis>
operation,
tells
<emphasis remap='I'>pluto</emphasis>
to attempt to establish the connection,
but does not delay to report results.
This is especially useful to start multiple connections in parallel
when network links are slow.</para>

<para>The
<option>--verbose</option>
option instructs
<emphasis remap='I'>auto</emphasis>
to pass through all output from
<citerefentry><refentrytitle>ipsec_whack</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
including log output that is normally filtered out as uninteresting.</para>

<para>The
<option>--config</option>
option specifies a non-standard location for the IPsec
configuration file (default
<filename>/etc/ipsec.conf</filename>).</para>

<para>See
<citerefentry><refentrytitle>ipsec.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details of the configuration file.
</para>
</refsect1>

<refsect1 id='files'><title>FILES</title>
<para>
<literallayout remap='.nf'>
/etc/ipsec.conf			default IPSEC configuration file
@IPSEC_NSSDIR@			X.509 and Opportunistic Encryption files
/var/run/pluto/pluto.ctl	Pluto command socket
</literallayout>
</para>
</refsect1>

<refsect1 id='see_also'><title>SEE ALSO</title>
<para><citerefentry><refentrytitle>ipsec.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>ipsec</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>ipsec_pluto</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>ipsec_whack</refentrytitle><manvolnum>8</manvolnum></citerefentry></para>
</refsect1>

<refsect1 id='history'><title>HISTORY</title>
<para>Originally written for the FreeS/WAN project
&lt;<ulink url='https://www.freeswan.org'>https://www.freeswan.org</ulink>&gt;
by Henry Spencer.</para>
</refsect1>

<refsect1 id='bugs'><title>BUGS</title>
<para>Although an
<option>--up</option>
operation does connection setup on both ends,
<option>--down</option>
tears only one end of the connection down
(although the orphaned end will eventually time out).</para>

<para>There is no support for
<emphasis remap='B'>passthrough</emphasis>
connections.</para>

<para>A connection description that uses
<emphasis remap='B'>%defaultroute</emphasis>
for one of its
<emphasis remap='B'>nexthop</emphasis>
parameters but not the other may be falsely
rejected as erroneous in some circumstances.</para>

<para>The exit status of
<option>--showonly</option>
does not always reflect errors discovered during processing of the request.
(This is fine for human inspection, but not so good for use in scripts.)</para>
</refsect1>
</refentry>