Provided by: openswan_2.4.12+dfsg-1.3_i386 bug
 

NAME

        ipsec.conf - IPsec configuration and connections
 

DESCRIPTION

        The  optional  ipsec.conf file specifies most configuration and control
        information for the Openswan IPsec subsystem. (The major  exception  is
        secrets for authentication; see ipsec.secrets(5).) Its contents are not
        security-sensitive unless manual keying is being  done  for  more  than
        just  testing,  in which case the encryption/authentication keys in the
        descriptions for the manually-keyed connections are very sensitive (and
        those  connection  descriptions  are  probably  best kept in a separate
        file, via the include facility described below).
 
        The file is a text file, consisting of  one  or  more  sections.  White
        space  followed  by  # followed by anything to the end of the line is a
        comment and is ignored, as are empty lines which are not within a  sec‐
        tion.
 
        A  line  which  contains  include  and  a file name, separated by white
        space, is replaced by the contents of that file, preceded and  followed
        by  empty lines. If the file name is not a full pathname, it is consid‐
        ered to be relative to the directory  containing  the  including  file.
        Such  inclusions can be nested. Only a single filename may be supplied,
        and it may not contain white space, but it may include shell  wildcards
        (see sh(1)); for example:
 
        include  ipsec.*.conf
 
        The  intention  of  the  include  facility  is mostly to permit keeping
        information on connections, or sets of connections, separate  from  the
        main  configuration  file. This permits such connection descriptions to
        be changed, copied to the other security gateways involved, etc., with‐
        out  having  to constantly extract them from the configuration file and
        then insert them back into it. Note also the also and alsoflip  parame‐
        ters  (described below) which permit splitting a single logical section
        (e.g. a connection description) into several actual sections.
 
        The first significant line of the file must specify the version of this
        specification that it conforms to:
 
        version 2
 
        A section begins with a line of the form:
 
        type  name
 
        where type indicates what type of section follows, and name is an arbi‐
        trary name which distinguishes the section  from  others  of  the  same
        type.  (Names  must  start  with a letter and may contain only letters,
        digits, periods, underscores, and hyphens.)  All  subsequent  non-empty
        lines  which  begin  with white space are part of the section; comments
        within a section must begin with white space too. There may be only one
        section of a given type with a given name.
 
        Lines within the section are generally of the form
 
             parameter=value
 
        (note the mandatory preceding white space). There can be white space on
        either side of the =. Parameter names follow the same syntax as section
        names,  and are specific to a section type. Unless otherwise explicitly
        specified, no parameter name may appear more than once in a section.
 
        An empty value stands for the system default  value  (if  any)  of  the
        parameter, i.e. it is roughly equivalent to omitting the parameter line
        entirely. A value may contain white space only if the entire  value  is
        enclosed  in  double quotes ("); a value cannot itself contain a double
        quote, nor may it be continued across more than one line.
 
        Numeric values are specified to be either an "integer" (a  sequence  of
        digits)  or  a "decimal number" (sequence of digits optionally followed
        by ‘.’ and another sequence of digits).
 
        There is currently one parameter which is available in any type of sec‐
        tion:
 
        also   the  value is a section name; the parameters of that section are
               appended to this section, as if they had been written as part of
               it.  The  specified  section must exist, must follow the current
               one, and must have the same section type. (Nesting is permitted,
               and  there  may  be  more  than  one  also  in a single section,
               although it is forbidden to append the same  section  more  than
               once.) This allows, for example, keeping the encryption keys for
               a connection in a separate file from the rest  of  the  descrip‐
               tion, by using both an also parameter and an include line. (Cau‐
               tion, see BUGS below for some restrictions.)
 
        alsoflip
               can be used in a conn section. It acts like an also  that  flips
               the referenced section’s entries left-for-right.
 
        Parameter  names  beginning  with x- (or X-, or x_, or X_) are reserved
        for user extensions and will  never  be  assigned  meanings  by  IPsec.
        Parameters  with such names must still observe the syntax rules (limits
        on characters used in the name; no white space in a  non-quoted  value;
        no newlines or double quotes within the value). All other as-yet-unused
        parameter names are reserved for future IPsec improvements.
 
        A section with name %default specifies defaults  for  sections  of  the
        same  type.  For  each  parameter in it, any section of that type which
        does not have a parameter of the same name gets a copy of the one  from
        the  %default  section.  There  may  be multiple %default sections of a
        given type, but only one default  may  be  supplied  for  any  specific
        parameter  name, and all %default sections of a given type must precede
        all non-%default sections of that type. %default sections may not  con‐
        tain also or alsoflip parameters.
 
        Currently  there  are  two types of section: a config section specifies
        general configuration information for IPsec, while a conn section spec‐
        ifies an IPsec connection.
        A  conn section contains a connection specification, defining a network
        connection to be made using IPsec. The name given is arbitrary, and  is
        used  to  identify the connection to ipsec_auto(8) and ipsec_manual(8).
        Here’s a simple example:
 
        conn snt
             left=10.11.11.1
             leftsubnet=10.0.1.0/24
             leftnexthop=172.16.55.66
             leftsourceip=10.0.1.1
             right=192.168.22.1
             rightsubnet=10.0.2.0/24
             rightnexthop=172.16.88.99
             rightsourceip=10.0.2.1
             keyingtries=%forever
 
        A note on terminology... In automatic keying, there are  two  kinds  of
        communications  going  on:  transmission  of user IP packets, and gate‐
        way-to-gateway negotiations for keying, rekeying, and general  control.
        The  data  path  (a set of "IPsec SAs") used for user packets is herein
        referred to as the "connection"; the path used for negotiations  (built
        with "ISAKMP SAs") is referred to as the "keying channel".
 
        To  avoid  trivial editing of the configuration file to suit it to each
        system involved in a connection, connection specifications are  written
        in  terms of left and right participants, rather than in terms of local
        and remote. Which participant is considered left or right is arbitrary;
        IPsec figures out which one it is being run on based on internal infor‐
        mation. This permits using identical connection specifications on  both
        ends.  There are cases where there is no symmetry; a good convention is
        to use left for the local side and right for the remote side (the first
        letters are a good mnemonic).
 
        Many of the parameters relate to one participant or the other; only the
        ones for left are listed here, but every parameter  whose  name  begins
        with  left  has  a right counterpart, whose description is the same but
        with left and right reversed.
 
        Parameters  are  optional  unless  marked  "(required)";  a   parameter
        required  for manual keying need not be included for a connection which
        will use only automatic keying, and vice versa.
 
    CONN PARAMETERS:  GENERAL
        The following parameters are relevant to both automatic and manual key‐
        ing. Unless otherwise noted, for a connection to work, in general it is
        necessary for the two ends to agree exactly  on  the  values  of  these
        parameters.
 
        type   the  type  of  the connection; currently the accepted values are
               tunnel (the default) signifying a host-to-host,  host-to-subnet,
               or  subnet-to-subnet  tunnel; transport, signifying host-to-host
               transport mode; passthrough, signifying that no IPsec processing
               should  be  done at all; drop, signifying that packets should be
               discarded; and reject, signifying that packets  should  be  dis‐
               carded and a diagnostic ICMP returned.
 
        left   (required)  the IP address of the left participant’s public-net‐
               work interface, in any form accepted by ipsec_ttoaddr(3) or  one
               of  several magic values. If it is %defaultroute, and the config
               setup section’s,  interfaces  specification  contains  %default‐
               route,   left  will  be  filled  in automatically with the local
               address of the default-route interface (as determined  at  IPsec
               startup  time); this also overrides any value supplied for left‐
               nexthop. (Either left or right may  be  %defaultroute,  but  not
               both.)  The  value %any signifies an address to be filled in (by
               automatic keying) during negotiation. The  value  %opportunistic
               signifies that both left and leftnexthop are to be filled in (by
               automatic keying) from DNS data for left’s  client.  The  values
               %group  and  %opportunisticgroup makes this a policy group conn:
               one that will be instantiated into a  regular  or  opportunistic
               conn  for  each  CIDR block listed in the policy group file with
               the same name as the conn.
 
        leftsubnet
               private subnet behind the left participant,  expressed  as  net‐
               work/netmask  (actually,  any  form  acceptable to ipsec_ttosub     
               net(3)); if omitted, essentially assumed to be left/32, signify‐
               ing that the left end of the connection goes to the left partic‐
               ipant only. If the global option virtual_private has  been  set,
               the  special  keyword  vhost:%priv  can be used to designate the
               allowed NAT’ed networks this option can take. If  one  wants  to
               support  both  the  allowed  virtual_private networks as well as
               non-NAT’ed connection, this subnet option can be set  to  right‐
               subnet=vhost:%priv,  %no. The special value %priv will be filled
               in with the network ranges specified in the global  option  vir‐
               tual_private=
 
        leftprotoport
               allowed  protocols  and  ports over connection, also called Port
               Selectors. The argument is in the form protocol, which can be  a
               number  or a name that will be looked up in /etc/protocols, such
               as leftprotoport=icmp, or in the form of protocol/port, such  as
               tcp/smtp. Ports can be defined as a number (eg. 25) or as a name
               (eg smtp) which will be looked up in  /etc/services.  A  special
               keyword  %any can be used to allow all ports of a certain proto‐
               col. The most common use of this option is for L2TP  connections
               to  only  allow  l2tp  packets  (UDP  port 1701), eg: leftproto‐
               port=17/1701. Some clients, notably older Windows  XP  and  some
               Mac OSX clients, use a random high port as source port. In those
               cases rightprotoport=17/%any can be used to allow all UDP  traf‐
               fic on the connection. Note that this option is part of the pro‐
               posal, so it cannot be arbitrarily left out if one end does  not
               care  about  the  traffic  selection over this connection - both
               peers have to agree. The Port Selectors show up in the output of
               ipsec    eroute    and    ipsec    auto    --status   eg:"l2tp":
               193.110.157.131[@aivd.xelernace.com]:7/1701...%any:17/1701  This
               option  only filters outbound traffic. Inbound traffic selection
               must still be based on firewall rules  activated  by  an  updown
               script. The variablees $PLUTO_MY_PROTOCOL, $PLUTO_PEER_PROTOCOL,
               $PLUTO_MY_PORT, and $PLUTO_PEER_PORT are available  for  use  in
               updown scripts. Older workarounds for bugs involved a setting of
               17/0 to denote all ports were allowed. This notation  should  no
               longer be used.
 
        leftnexthop
               next-hop  gateway  IP address for the left participant’s connec‐
               tion to the public network; defaults to %direct (meaning right).
               If  the  value  is  to  be  overridden by the left=%defaultroute
               method (see above), an explicit value must not be given. If that
               method  is not being used, but leftnexthop is %defaultroute, and
               interfaces=%defaultroute is used in the config   setup  section,
               the next-hop gateway address of the default-route interface will
               be used. The magic value %direct signifies a value to be  filled
               in  (by automatic keying) with the peer’s address. Relevant only
               locally, other end need not agree on it.
 
        leftsourceip
               the IP address for this host to use when transmitting  a  packet
               to the other side of this link. Relevant only locally, the other
               end need not agree. This option is  used  to  make  the  gateway
               itself  use its internal IP, which is part of the leftsubnet, to
               communicate to the rightsubnet or right. Otherwise, it will  use
               its  nearest  IP  address,  which is its public IP address. This
               option is mostly used when defining  subnet-subnet  connections,
               so  that  the  gateways can talk to each other and the subnet at
               the other end, without the need to build additional host-subnet,
               subnet-host and host-host tunnels.
 
        leftupdown
               what "updown" script to run to adjust routing and/or firewalling
               when  the  status  of  the  connection  changes  (default  ipsec
               _updown).  May  include positional parameters separated by white
               space (although this requires  enclosing  the  whole  string  in
               quotes);   including   shell   metacharacters   is  unwise.  See
               ipsec_pluto(8) for details. Relevant  only  locally,  other  end
               need not agree on it.
 
        leftfirewall
               This option is obsolete and should not used anymore.
 
    CONN PARAMETERS:  AUTOMATIC KEYING
        The  following parameters are relevant for automatic keying, the normal
        mode of operation for IPsec. They are ignored in manual keying.  Unless
        otherwise  noted,  for a connection to work, in general it is necessary
        for the two ends to agree exactly on the values of these parameters.
 
        keyexchange
               method of key exchange;  the  default  and  currently  the  only
               accepted value is ike
 
        auto   what  operation,  if  any, should be done automatically at IPsec
               startup; currently-accepted values are add (signifying an  ipsec
               auto    --add),  route  (signifying  that  plus  an  ipsec  auto
               --route), start (signifying that plus an ipsec auto  --up), man‐
               ual  (signifying  an  ipsec  manual  --up), and ignore (also the
               default) (signifying no automatic startup  operation).  See  the
               config  setup discussion below. Relevant only locally, other end
               need not agree on it (but in general, for an intended-to-be-per‐
               manent  connection,  both  ends  should use auto=start to ensure
               that any reboot causes immediate renegotiation). For roadwarrior
               connections  (right=%any), it is not known where the client will
               show up, so one has to use auto=add
 
        auth   whether authentication should be done as part of ESP encryption,
               or  separately  using the AH protocol; acceptable values are esp
               (the default) and ah.
 
        authby how the two security gateways should  authenticate  each  other;
               acceptable  values are secret for shared secrets, rsasig for RSA
               digital signatures (the default), secret|rsasig for either,  and
               never  if negotiation is never to be attempted or accepted (use‐
               ful for shunt-only conns). Digital signatures  are  superior  in
               every way to shared secrets.
 
        ike    IKE  encryption/authentication algorithm to be used for the con‐
               nection   (phase   1   aka   ISAKMP   SA).   The    format    is
               "cipher-hash-modpgroup, cipher-hash-modpgroup, ..." Any left out
               option will be filled in with all allowed default options.  Mul‐
               tiple  proposals  are  seperated  by a comma. If an ike= line is
               specified, no other received proposals will  be  accepted.  For‐
               merly  there  was  a distinction (by using a "!" symbol) between
               "strict mode" or not. That mode has been obsoleted. If  an  ike=
               option is specified, the mode is always strict, meaning no other
               received  proposals  will  be  accepted.   Some   examples   are
               ike=3des-sha1,aes-sha1,     ike=aes,    ike=aes128-md5-modp2048,
               ike=3des-md5-modp1024,esp=aes-sha1-modp1536 or ike=modp1536. The
               options  must  be  suitable  as  a value of ipsec_spi(8)’s --ike
               option. The default is to use IKE, and to allow all combinations
               of:
 
                         cipher:             3des or aes
                         hash:               sha1 or md5
                         pfsgroup (DHgroup): modp1024 or modp1536
 
               If Openswan was compiled with extra INSECURE and BROKEN options,
               then the des (1des) and null cipher,  as  well  as  modp768  are
               available.  This turns your VPN into a joke. Do not enable these
               options.
 
        esp    ESP encryption/authentication algorithm to be used for the  con‐
               nection  (phase2  aka  IPsec SA). The format is identical to the
               ike option listed above. The options must be suitable as a value
               of  ipsec_spi(8)’s  --esp option. The default is to use ESP. The
               default values are the same as for ike= Note also that  not  all
               ciphers  available to the kernel (eg through CryptoAPI) are nec‐
               essarilly supported here.
 
        ah     AH authentication algorithm to be used for the  connection,  e.g
               here.  hmac-md5  The  options  must  be  suitable  as a value of
               ipsec_spi(8)’s --ah option. The default is not to use AH. If for
               some  (invalid)  reason  you still think you need AH, please use
               esp with the null encryption cipher instead. Note also that  not
               all  ciphers  available to the kernel (eg through CryptoAPI) are
               necessarilly supported here.
 
        leftid how the left participant should be  identified  for  authentica‐
               tion;   defaults   to  left.  Can  be  an  IP  address  (in  any
               ipsec_ttoaddr(3) syntax) or a fully-qualified domain  name  pre‐
               ceded by @ (which is used as a literal string and not resolved).
               The magic value %myid stands for the current setting of myid.
 
        leftrsasigkey
               the left participant’s public key for RSA signature  authentica‐
               tion,  in  RFC  2537 format using ipsec_ttodata(3) encoding. The
               magic value %none means the same as not specifying a value (use‐
               ful to override a default). The value %dnsondemand (the default)
               means the key is to be fetched  from  DNS  at  the  time  it  is
               needed. The value %dnsonload means the key is to be fetched from
               DNS  at  the  time  the  connection  description  is  read  from
               ipsec.conf;   currently   this  will  be  treated  as  %none  if
               right=%any or right=%opportunistic. The value %dns is  currently
               treated  as  %dnsonload  but  will change to %dnsondemand in the
               future. The identity used for the left  participant  must  be  a
               specific  host, not %any or another magic value. The value %cert
               will load the information required from a certificate defined in
               %leftcert  and  automatically define leftid for you. Caution: if
               two connection descriptions specify different  public  keys  for
               the same leftid, confusion and madness will ensue.
 
        leftrsasigkey2
               if present, a second public key. Either key can authenticate the
               signature, allowing for key rollover.
 
        leftcert
               If you are using leftrsasigkey=%cert this defines  the  certifi‐
               cate  you  would like to use. It should point to a X.509 encoded
               certificate file. If you do not  specify  a  full  pathname,  by
               default it will look in /etc/ipsec.d/certs. If openswan has been
               compiled with USE_SMARTCARD=true, then this option can  also  be
               set to leftcert=%smartcard. If multiple smartcards or USB tokens
               are  present,  they  can  be  specified  using  leftcert=%smart‐
               card<reader nr><PKCS#15 key id>
 
        leftsendcert
               This  option  configures  when Openswan will send X.509 certifi‐
               cates to the remote host. Acceptable values are yes|always (sig‐
               nifying that we should always send a certificate), ifasked (sig‐
               nifying that we should send a certificate if the remote end asks
               for  it),  and  no|never  (signifying  that we will never send a
               X.509 certificate). The default for this option is ifasked which
               may  break  compatibility  with other vendor’s IPSec implementa‐
               tions, such as Cisco and SafeNet. If you find that you are  get‐
               ting  errors  about no ID/Key found, you likely need to set this
               to always. This per-conn option  replaces  the  obsolete  global
               nocrsend option.
 
        leftca specifies the authorized Certificate Agency (CA) that signed the
               certificate of the peer. If undefined, it  defaults  to  the  CA
               that  signed  the certificate specified in leftcert. The special
               rightca=%same is implied when not specifying a rightca and means
               that  only  peers with certificates signed by the same CA as the
               leftca will be allowed. This option is only  useful  in  complex
               multi  CA certificate situations. When using a single CA, it can
               be safely omitted for left and right.
 
        leftxauthserver
               Left is an XAUTH server. This can use PAM for authentication  or
               md5  passwords in /etc/ipsec.d/passwd. These are additional cre‐
               dentials to verify the user identity, and should not be confused
               with the XAUTH group secret, which is just a regular PSK defined
               in ipsec.secrets. The other side of  the  connection  should  be
               configured  as rightxauthclient. XAUTH connections cannot rekey,
               so rekey=no should  be  specified  in  this  conn.  For  further
               details  on  how  to  compile  and  use XAUTH, see README.XAUTH.
               Acceptable values are yes or no (the default).
 
        leftxauthclient
               Left is an XAUTH client. The xauth connection will  have  to  be
               started interactively and cannot be configured using auto=start.
               Instead, it has to be started from the commandline  using  ipsec
               auto  --up  connname. You will then be prompted for the username
               and password. To setup an  XAUTH  connection  non-interactively,
               which  defeats  the  whole  purpose  of  XAUTH, but is regularly
               requested by users, it is possible to  use  a  whack  command  -
               ipsec   whack   --name  baduser  --ipsecgroup-xauth  --xauthname
               badusername --xauthpass password --initiate The  other  side  of
               the connection should be configured as rightxauthserver. Accept‐
               able values are yes or no (the default).
 
        leftmodecfgserver
               Left is a Mode Config server. It can push network  configuration
               to the client. Acceptable values are yes or no (the default).
 
        leftmodecfgclient
               Left  is a Mode Config client. It can receive network configura‐
               tion from the server. Acceptable  values  are  yes  or  no  (the
               default).
 
        forceencaps
               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. forceencaps=yes forces
               the NAT detection code to lie and  tell  the  remote  peer  that
               RFC-3948  encapsulation  (ESP  in  UDP  port  4500  packets)  is
               required. For this option to have any effect, the setup  section
               option  nat_traversal=yes needs to be set. Acceptable values are
               yes or no (the default).
 
        dpddelay
               Set the delay (in seconds) between  Dead  Peer  Dectection  (RFC
               3706)  keepalives  (R_U_THERE,  R_U_THERE_ACK) that are sent for
               this connection (default 30 seconds). If dpdtimeout is set,  but
               not dpddelay, dpddelay will be set to the default.
 
        dpdtimeout
               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). If dpddelay is set, but not dpdtimeout,
               dpdtimeout will be set to the default.
 
        dpdaction
               When a DPD enabled peer is declared dead, what action should  be
               taken.  hold  (default)  means the eroute will be put into %hold
               status, while clear  means  the  eroute  and  SA  with  both  be
               cleared. dpdaction=clear is really only usefull on the server of
               a Road Warrior config. The action restart  is  used  on  tunnels
               that need to be permanently up, and have static IP addresses.
 
        modecfgpull
               Pull  the  Mode  Config  network  information  from  the server.
               Acceptable values are yes or no (the default).
 
        pfs    whether Perfect Forward Secrecy of keys is desired on  the  con‐
               nection’s   keying   channel   (with  PFS,  penetration  of  the
               key-exchange protocol does not compromise keys  negotiated  ear‐
               lier);  Since  there  is  no reason to ever refuse PFS, Openswan
               will allow a connection defined with pfs=no to use  PFS  anyway.
               Acceptable values are yes (the default) and no.
 
        pfsgroup
               PFS  group to be used if pfs=yes, e.g. pfsgroup=modp1536 Because
               PFS group is not negotiated it is single valued and must be pre‐
               viously  coordinated  with  peer. Possible values are: modp1024,
               modp1536, modp2048, modp3072 and modp4096. If not specified,  it
               will  use  same  DH  group  of phase1. Default value is the same
               value as Phase1’s DH group.
 
        aggrmode
               Use Aggressive Mode instead of Main  Mode.  Aggressive  Mode  is
               less  secure, and vulnerable to Denial Of Service attacks. It is
               also vulnerable to brute force attacks  with  software  such  as
               ikecrack. It should not be used, and it should especially not be
               used with XAUTH and group secrets (PSK). If  the  remote  system
               administrator  insists  on  staying  irresponsible,  enable this
               option.
 
               Aggressive Mode is further limited to only one proposal -  there
               is  no room for negotation. Therefor it is mandatory for Aggres‐
               sive Mode connections that both ike= and esp= options are speci‐
               fied  with exactly one fully specified proposal. Acceptable val‐
               ues are yes or no (the default).
 
        keylife
               how long a particular instance of a connection (a set of encryp‐
               tion/authentication  keys  for  user  packets) should last, from
               successful negotiation to expiry; acceptable values are an inte‐
               ger  optionally  followed  by s (a time in seconds) or a decimal
               number followed by m, h, or d (a time in minutes, hours, or days
               respectively)  (default  8h, maximum 24h). Normally, the connec‐
               tion is renegotiated (via the keying channel) before it expires.
               The two ends need not exactly agree on keylife, although if they
               do not, there will be some clutter of superseded connections  on
               the end which thinks the lifetime is longer.
 
        rekey  whether  a connection should be renegotiated when it is about to
               expire; acceptable values are yes (the default) and no. The  two
               ends need not agree, but while a value of no prevents Pluto from
               requesting renegotiation, it  does  not  prevent  responding  to
               renegotiation  requested  from  the  other  end,  so  no will be
               largely ineffective unless both ends agree on it.
 
        rekeymargin
               how long  before  connection  expiry  or  keying-channel  expiry
               should  attempts  to  negotiate  a replacement begin; acceptable
               values as for keylife (default 9m). Relevant only locally, other
               end need not agree on it.
 
        rekeyfuzz
               maximum  percentage  by  which  rekeymargin  should  be randomly
               increased to randomize rekeying intervals (important  for  hosts
               with  many connections); acceptable values are an integer, which
               may  exceed  100,  followed   by   a   ‘%’   (default   set   by
               ipsec_pluto(8), currently 100%). The value of rekeymargin, after
               this random increase, must not exceed keylife. The value 0% will
               suppress  time  randomization.  Relevant only locally, other end
               need not agree on it.
 
        keyingtries
               how many attempts (a whole number or %forever) should be made to
               negotiate  a connection, or a replacement for one, before giving
               up (default %forever). The value %forever means "never give  up"
               (obsolete:  this can be written 0). Relevant only locally, other
               end need not agree on it.
 
        ikelifetime
               how long the keying channel of a connection (buzzphrase: "ISAKMP
               SA") should last before being renegotiated; acceptable values as
               for keylife (default set by ipsec_pluto(8), currently 1h,  maxi‐
               mum  24h).  The  two-ends-disagree  case  is  similar to that of
               keylife.
 
        compress
               whether IPComp compression of content is proposed on the connec‐
               tion (link-level compression does not work on encrypted data, so
               to be effective, compression must be  done  before  encryption);
               acceptable  values  are  yes  and no (the default). The two ends
               need not agree. A value of yes causes IPsec to propose both com‐
               pressed  and  uncompressed, and prefer compressed. A value of no
               prevents IPsec from proposing compression; a  proposal  to  com‐
               press will still be accepted.
 
        disablearrivalcheck
               whether KLIPS’s normal tunnel-exit check (that a packet emerging
               from a tunnel has plausible addresses in its header)  should  be
               disabled;  acceptable  values are yes and no (the default). Tun‐
               nel-exit checks improve security and do  not  break  any  normal
               configuration.  Relevant  only locally, other end need not agree
               on it.
 
        failureshunt
               what to do with packets when negotiation fails. The  default  is
               none:  no  shunt; passthrough, drop, and reject have the obvious
               meanings.
 
    CONN PARAMETERS:  MANUAL KEYING
        The following parameters are relevant only to manual  keying,  and  are
        ignored  in  automatic  keying. It is  EXTREMELY UNLIKELY that you will
        actually want to use manual keying. It is much harder to configure then
        automatic  keying,  and inheritently insecure when used for a prolonged
        time (eg production) due to the complete lack of key  renewal,  session
        keys or perfect forward secrecy.
 
        Unless otherwise noted, for a connection to work, in general it is nec‐
        essary for the two ends to agree exactly on the values of these parame‐
        ters.  A  manually-keyed  connection must specify at least one of AH or
        ESP.
 
        spi    (this or spibase required for manual keying) the SPI  number  to
               be used for the connection (see ipsec_manual(8)); must be of the
               form 0xhex, where hex is one or more hexadecimal  digits  (note,
               it  will generally be necessary to make spi at least 0x100 to be
               acceptable to KLIPS, and use of SPIs in the range 0x100-0xfff is
               recommended)
 
        spibase
               (this or spi required for manual keying) the base number for the
               SPIs to be used for the connection (see  ipsec_manual(8));  must
               be of the form 0xhex0, where hex is one or more hexadecimal dig‐
               its (note, it will generally be necessary  to  make  spibase  at
               least  0x100  for  the resulting SPIs to be acceptable to KLIPS,
               and use of numbers in the range 0x100-0xff0 is recommended)
 
        espenckey
               ESP  encryption  key  (must  be   suitable   as   a   value   of
               ipsec_spi(8)’s --enckey option) (may be specified separately for
               each direction using leftespenckey  (leftward  SA)  and  righte‐
               spenckey parameters)
 
        espauthkey
               ESP   authentication  key  (must  be  suitable  as  a  value  of
               ipsec_spi(8)’s --authkey option) (may  be  specified  separately
               for each direction using leftespauthkey (leftward SA) and right‐
               espauthkey parameters)
 
        espreplay_window
               ESP replay-window setting, an integer from 0  (the  ipsec_manual
               default, which turns off replay protection) to 64; relevant only
               if ESP authentication is being used
 
        leftespspi
               SPI to be used for the leftward  ESP  SA,  overriding  automatic
               assignment  using spi or spibase; typically a hexadecimal number
               beginning with 0x
 
        ahkey  (required if ah is present) AH authentication key (must be suit‐
               able  as  a  value  of  ipsec_spi(8)’s --authkey option) (may be
               specified separately for each direction using  leftahkey  (left‐
               ward SA) and rightahkey parameters)
 
        ahreplay_window
               AH  replay-window  setting,  an integer from 0 (the ipsec_manual
               default, which turns off replay protection) to 64
 
        leftahspi
               SPI to be used for the  leftward  AH  SA,  overriding  automatic
               assignment  using spi or spibase; typically a hexadecimal number
               beginning with 0x
        At present, the only config section known to the IPsec software is  the
        one  named  setup, which contains information used when the software is
        being started (see ipsec_setup(8)). Here’s an example:
 
        config setup
             interfaces="ipsec0=eth1 ipsec1=ppp0"
             klipsdebug=none
             plutodebug=control
             nat_traversal=yes
             virtual_private=%v4:10.0.0.0/8,%v4:192.168.0.0/16,%4:172.16.0.0/12
 
        Parameters are optional unless marked "(required)".
 
        The currently-accepted parameter names in a config  setup section are:
 
        myid   the identity to be used for %myid. %myid is used in the implicit
               policy  group  conns  and can be used as an identity in explicit
               conns. If unspecified,  %myid  is  set  to  the  IP  address  in
               %defaultroute  (if  that  is  supported  by  a TXT record in its
               reverse domain), or otherwise the system’s hostname (if that  is
               supported  by  a TXT record in its forward domain), or otherwise
               it is undefined. An explicit value generally starts with  ‘‘@’’.
 
        interfaces
               This  option  is  for  KLIPS and KLIPSNG (mast) only and will be
               ignored when using NETKEY, Windows or BSD stacks.  It  specifies
               the  virtual  and physical interfaces for IPsec to use: a single
               virtual=physical pair, a (quoted!) list of  pairs  separated  by
               white  space,  or  %none.  One  of  the  pairs may be written as
               %defaultroute, which  means:  find  the  interface  d  that  the
               default  route  points  to,  and  then  act  as if the value was
               ‘‘ipsec0=d’’. %defaultroute is the default; %none must  be  used
               to denote no interfaces. If %defaultroute is used (implicitly or
               explicitly) information about the default route and  its  inter‐
               face is noted for use by ipsec_manual(8) and ipsec_auto(8).)
 
        nat_traversal
               whether  to accept/offer to support NAT (NAPT, also known as "IP
               Masqurade") workaround for IPsec. Acceptable values are: yes and
               no  (the default). This parameter may eventually become per-con‐
               nection.
 
        virtual_private
               contains the networks that are allowed as subnet= for the remote
               client.  In other words, the address ranges that may live behind
               a NAT router through which a client connects. This value is usu‐
               ally  set to all the RFC-1918 address space, excluding the space
               used in the local subnet behind the NAT (An  IP  address  cannot
               live  at two places at once). IPv4 address ranges are denoted as
               %v4:a.b.c.d/mm      and      IPv6      is       denoted       as
               %v6:aaaa::bbbb:cccc:dddd/mm.  One  can  exclude subnets by using
               the !. For example, if  the  VPN  server  is  giving  access  to
               192.168.1.0/24,  this  option  should  be  set  to: virtual_pri‐
               vate=%v4:10.0.0.0/8,%v4:192.168.0.0/16,%4:172.16.0.0/12,%v4:!192.168.1.0/24.
               This  parameter is only needed on the server side and not on the
               client side that resides behind the NAT router,  as  the  client
               will  just  use  its  IP  address for the inner IP setting. This
               parameter may eventually become per-connection.
 
        nhelpers
               how many pluto helpers are started to  help  with  cryptographic
               operations.  Pluto will start (n-1) of them, where n is the num‐
               ber of CPU’s you have (including hypherthreaded CPU’s). A  value
               of  0  forces  pluto to do all operations in the main process. A
               value of -1 tells pluto to perform the  above  calculation.  Any
               other value forces the number to that amount.
 
        myid   the identity to be used for %myid. %myid is used in the implicit
               policy group conns and can be used as an  identity  in  explicit
               conns.  If  unspecified,  %myid  is  set  to  the  IP address in
               %defaultroute (if that is supported  by  a  TXT  record  in  its
               reverse  domain), or otherwise the system’s hostname (if that is
               supported by a TXT record in its forward domain),  or  otherwise
               it  is undefined. An explicit value generally starts with ‘‘@’’.
 
        crlcheckinterval
               interval, specified in seconds, after which  pluto  will  verify
               loaded  X.509  CRL’s  for  expiration.  If  any  of the CRL’s is
               expired, or if they previously failed  to  get  updated,  a  new
               attempt at updating the CRL is made. The first attempt to update
               a CRL is started at two times the crlcheckinterval. If set to 0,
               which is also the default value if this option is not specified,
               CRL updating is disabled.
 
        strictcrlpolicy
               if not set, pluto is tolerant about  missing  or  expired  X.509
               Certificate  Revocation  Lists (CRL’s), and will allow peer cer‐
               tificates as long as they do not appear on an expired CRL.  When
               this option is enabled, all connections with an expired or miss‐
               ing CRL will be denied. Active connections will be terminated at
               rekey  time.  This  setup is more secure, but also dangerous. If
               the CRL is fetched through an  IPsec  tunnel  with  a  CRL  that
               expired, the entire VPN server will be dead in the water until a
               new CRL is manually transferred to the  machine  (if  it  allows
               non-IPsec  connections).  Acceptable  values  are yes or no (the
               default).
 
        forwardcontrol
               whether setup should turn IP forwarding on (if it’s not  already
               on)  as  IPsec is started, and turn it off again (if it was off)
               as IPsec is stopped; acceptable values are yes and (the default)
               no.  For  this  to have full effect, forwarding must be disabled
               before  the  hardware   interfaces   are   brought   up   (e.g.,
               net.ipv4.ip_forward  =  0  in  /etc/sysctl.conf),  because IPsec
               doesn’t get control early enough to do that. If this  option  is
               not specified, and subnet-subnet tunnels are configured, then IP
               forwarding should be enabled by the system administrator.
 
        rp_filter
               whether and how setup should adjust the reverse  path  filtering
               mechanism  for  the  physical  devices  to  be  used. Values are
               %unchanged (to leave it alone) or 0, 1, 2 (values to set it to).
               /proc/sys/net/ipv4/conf/PHYS/rp_filter  is  badly documented; it
               must be 0 in many cases for ipsec to function. The default value
               for  the  parameter  is 0, that is, to disable rp_filter for all
               interfaces used.
 
        syslog the  syslog(2)  "facility"  name  and  priority   to   use   for
               startup/shutdown log messages, default daemon.error.
 
        klipsdebug
               how  much  KLIPS  debugging  output  should  be logged. An empty
               value, or the magic value none, means no debugging  output  (the
               default).  The magic value all means full output. Otherwise only
               the specified types of output (a quoted list, names separated by
               white  space)  are  enabled;  for details on available debugging
               types, see ipsec_klipsdebug(8). This KLIPS option has no  effect
               on NETKEY, Windows or BSD stacks.
 
        plutodebug
               how  much  Pluto  debugging  output  should  be logged. An empty
               value, or the magic value none, means no debugging  output  (the
               default).  The magic value all means full output. Otherwise only
               the specified types of output (a quoted list, names without  the
               --debug-  prefix,  separated  by  white  space) are enabled; for
               details on available debugging types, see ipsec_pluto(8).
 
        plutorestartoncrash
               prevent pluto from restarting  after  it  crashed.  This  option
               should  only  be  used  when  a  post-mortem  of  a core file is
               desired. It prevents pluto from restarting  and  possibly  over‐
               writing an older core file.
 
        plutoopts
               additional   options   to   pass  to  pluto  upon  startup.  See
               ipsec_pluto(8).
 
        plutostderrlog
               do not use syslog, but rather log to stderr, and  direct  stderr
               to the argument file.
 
        dumpdir
               in  what  directory  should things started by setup (notably the
               Pluto daemon) be allowed to dump  core?  The  empty  value  (the
               default) means they are not allowed to.
 
        manualstart
               which  manually-keyed connections to set up at startup (empty, a
               name, or a quoted list of names separated by white  space);  see
               ipsec_manual(8). Default is none.
 
        pluto  whether  to  start Pluto or not; Values are yes (the default) or
               no (useful only in special circumstances).
 
        plutowait
               should Pluto wait for each negotiation attempt that is  part  of
               startup  to  finish  before proceeding with the next? Values are
               yes or no (the default).
 
        prepluto
               shell command to run before starting Pluto (e.g., to decrypt  an
               encrypted  copy  of  the ipsec.secrets file). It’s run in a very
               simple way; complexities like I/O redirection  are  best  hidden
               within  a  script. Any output is redirected for logging, so run‐
               ning interactive commands is difficult unless they use  /dev/tty
               or equivalent for their interaction. Default is none.
 
        postpluto
               shell  command  to  run  after starting Pluto (e.g., to remove a
               decrypted copy of the ipsec.secrets file). It’s run  in  a  very
               simple  way;  complexities  like I/O redirection are best hidden
               within a script. Any output is redirected for logging,  so  run‐
               ning  interactive commands is difficult unless they use /dev/tty
               or equivalent for their interaction. Default is none.
 
        fragicmp
               whether a tunnel’s need to fragment a packet should be  reported
               back  with  an  ICMP  message,  in an attempt to make the sender
               lower his PMTU estimate; acceptable values are yes (the default)
               and  no.  This  KLIPS option has no effect on NETKEY, Windows or
               BSD stacks.
 
        hidetos
               whether a tunnel packet’s TOS field should be set  to  0  rather
               than  copied  from the user packet inside; acceptable values are
               yes (the default) and no. This KLIPS option  has  no  effect  on
               NETKEY, Windows or BSD stacks.
 
        uniqueids
               whether  a particular participant ID should be kept unique, with
               any new (automatically keyed) connection using an ID from a dif‐
               ferent  IP address deemed to replace all old ones using that ID.
               Acceptable values are yes (the default) and no. Participant  IDs
               normally  are  unique, so a new (automatically-keyed) connection
               using the same ID is almost invariably intended  to  replace  an
               old one.
 
        overridemtu
               value  that the MTU of the ipsecn interface(s) should be set to,
               overriding IPsec’s (large) default.  This  parameter  is  needed
               only  in  special situations. This KLIPS option has no effect on
               NETKEY, Windows or BSD stacks.
        The system automatically defines several  conns  to  implement  default
        policy  groups.  These  are used to enable the establishing of Opportu‐
        nitic Encryption IPsec tunnels. That is, setting up IPsec tunnels  with
        peers  you  have  no  pre-arranged  configuration  with.  Opportunistic
        Encryption is currently only  supported  using  the  KLIPS  or  KLIPSNG
        (mast)  stack,  and should not be enabled when using NETKEY, Windows or
        BSD stacks.
 
        Each can be overridden by explicitly defining a new conn with the  same
        name. If the new conn has auto=ignore, the definition is suppressed.
 
        Here are the automatically supplied definitions.
 
        conn clear
             type=passthrough
             authby=never
             left=%defaultroute
             right=%group
             auto=route
 
        conn clear-or-private
             type=passthrough
             left=%defaultroute
             leftid=%myid
             right=%opportunisticgroup
             failureshunt=passthrough
             keyingtries=3
             ikelifetime=1h
             keylife=1h
             rekey=no
             auto=route
 
        conn private-or-clear
             type=tunnel
             left=%defaultroute
             leftid=%myid
             right=%opportunisticgroup
             failureshunt=passthrough
             keyingtries=3
             ikelifetime=1h
             keylife=1h
             rekey=no
             auto=route
 
        conn private
             type=tunnel
             left=%defaultroute
             leftid=%myid
             right=%opportunisticgroup
             failureshunt=drop
             keyingtries=3
             ikelifetime=1h
             keylife=1h
             rekey=no
             auto=route
 
        conn block
             type=reject
             authby=never
             left=%defaultroute
             right=%group
             auto=route
 
        # default policy
        conn packetdefault
             type=tunnel
             left=%defaultroute
             leftid=%myid
             left=0.0.0.0/0
             right=%opportunistic
             failureshunt=passthrough
             keyingtries=3
             ikelifetime=1h
             keylife=1h
             rekey=no
             auto=route
 
        These  conns  are  not affected by anything in conn %default. They will
        only work if %defaultroute works. The leftid will be the interfaces  IP
        address; this requires that reverse DNS records be set up properly.
 
        The  implicit conns are defined after all others. It is appropriate and
        reasonable to use also=private-or-clear  (for  example)  in  any  other
        opportunistic conn.
        The optional files under /etc/ipsec.d/policy, including
 
        /etc/ipsec.d/policies/clear
        /etc/ipsec.d/policies/clear-or-private
        /etc/ipsec.d/policies/private-or-clear
        /etc/ipsec.d/policies/private
        /etc/ipsec.d/policies/block
 
        may  contain  policy  group  configuration  information  to  supplement
        ipsec.conf. Their contents are not security-sensitive.
 
        These files are text files. Each consists of a list of CIDR blocks, one
        per  line. White space followed by # followed by anything to the end of
        the line is a comment and is ignored, as are empty lines.
 
        A connection in /etc/ipsec.conf which has right=%group or right=%oppor‐
        tunisticgroup is a policy group connection. When a policy group file of
        the same name is loaded, with
 
             ipsec auto --rereadgroups
 
        or at system start, the connection is instantiated such that each  CIDR
        block  serves  as  an  instance’s  right  value.  The system treats the
        resulting instances as normal connections.
 
        For example, given a suitable connection definition  private,  and  the
        file  /etc/ipsec.d/policy/private  with  an entry 192.0.2.3, the system
        creates a connection instance private#192.0.2.3. This connection inher‐
        its  all  details  from  private,  except  that  its  right  client  is
        192.0.2.3.
        The standard Openswan install includes several policy groups which pro‐
        vide  a  way of classifying possible peers into IPsec security classes:
        private (talk encrypted only),  private-or-clear  (prefer  encryption),
        clear-or-private (respond to requests for encryption), clear and block.
        Implicit policy groups apply to the local host  only,  and  are  imple‐
        mented by the IMPLICIT CONNECTIONS described above.
        When choosing a connection to apply to an outbound packet caught with a
        %trap, the system prefers the one with the most  specific  eroute  that
        includes  the packet’s source and destination IP addresses. Source sub‐
        nets are examined before  destination  subnets.  For  initiating,  only
        routed  connections  are considered. For responding, unrouted but added
        connections are considered.
 
        When choosing a connection to use to respond  to  a  negotiation  which
        doesn’t  match  an  ordinary  conn,  an opportunistic connection may be
        instantiated. Eventually, its instance will be /32 -> /32, but for ear‐
        lier  stages  of  the negotiation, there will not be enough information
        about the client subnets to complete the instantiation.
 

FILES

        /etc/ipsec.conf
        /etc/ipsec.d/policies/clear
        /etc/ipsec.d/policies/clear-or-private
        /etc/ipsec.d/policies/private-or-clear
        /etc/ipsec.d/policies/private
        /etc/ipsec.d/policies/block
        ipsec(8), ipsec_ttoaddr(8), ipsec_whack(8),  ipsec_auto(8),  ipsec_man     
        ual(8), ipsec_rsasigkey(8)
 

HISTORY

        Designed    for   the   FreeS/WAN   project   <http://www.freeswan.org:
        http://www.freeswan.org by Henry Spencer.
 

BUGS

        When type or failureshunt is set to drop  or  reject,  Openswan  blocks
        outbound packets using eroutes, but assumes inbound blocking is handled
        by the firewall. Openswan offers firewall hooks via an "updown" script.
        However,  the  default  ipsec _updown provides no help in controlling a
        modern firewall.
 
        The use of %any with the protoport= option is ambiguous. Should the  SA
        permits  any  port  through  or should the SA negotiate any single port
        through? The first is a basic conn with a wildcard.  The  second  is  a
        template. The second is the current behaviour, and it’s wrong for quite
        a number of uses involving TCP. The keyword %one may be  introduced  in
        the future to seperate these two cases.
 
        Including  attributes  of  the  keying channel (authentication methods,
        ikelifetime, etc.) as an attribute of a connection, rather  than  of  a
        participant pair, is dubious and incurs limitations.
 
        Ipsec_manual  is  not  nearly  as generous about the syntax of subnets,
        addresses, etc. as the usual Openswan user  interfaces.  Four-component
        dotted-decimal  must  be  used for all addresses. It is smart enough to
        translate bit-count netmasks to dotted-decimal form.
 
        It would be good to have a line-continuation syntax, especially for the
        very long lines involved in RSA signature keys.
 
        The  ability  to  specify different identities, authby, and public keys
        for different automatic-keyed connections between the same participants
        is misleading; this doesn’t work dependably because the identity of the
        participants is not known early enough. This is especially awkward  for
        the  "Road  Warrior"  case, where the remote IP address is specified as
        0.0.0.0, and that is considered to be the "participant" for  such  con‐
        nections.
 
        In  principle  it  might  be  necessary  to  control  MTU  on an inter‐
        face-by-interface basis, rather than with the  single  global  override
        that overridemtu provides.
 
        A  number  of  features  which  could be implemented in both manual and
        automatic keying actually are not yet implemented  for  manual  keying.
        This is unlikely to be fixed any time soon.
 
        If  conns  are to be added before DNS is available, left=FQDN, leftnex‐
        top=FQDN, and leftrsasigkey=%dnsonload will fail.  ipsec_pluto(8)  does
        not  actually  use  the  public key for our side of a conn but it isn’t
        generally known at a add-time which side  is  ours  (Road  Warrior  and
        Opportunistic conns are currently exceptions).
 
        The  myid  option  does  not affect explicit  ipsec auto --add or ipsec
        auto --replace commands for implicit conns.
 
                                                                  IPSEC.CONF(5)