unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

IPSEC.CONF(5)                                                    IPSEC.CONF(5)



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.


CONN SECTIONS
       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


CONFIG SECTIONS
       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.


IMPLICIT CONNS
       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.


POLICY GROUP FILES
       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.


DEFAULT POLICY GROUPS
       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.


CHOOSING A CONNECTION
       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



SEE ALSO
       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  connec-
       tions.


       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)