Provided by: openswan_2.4.4-3ubuntu1_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
       section.

       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
       considered 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.,
       without  having  to constantly extract them from the configuration file
       and then insert them back into it.  Note also  the  also  and  alsoflip
       parameters  (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
       arbitrary 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
       section:

       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 description, by using both an also parameter and  an
              include  line.  (Caution, 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
       contain also or alsoflip parameters.

       Currently  there  are  two types of section: a config section specifies
       general configuration information  for  IPsec,  while  a  conn  section
       specifies 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
           right=192.168.22.1
           rightsubnet=10.0.2.0/24
           rightnexthop=172.16.88.99
           keyingtries=%forever

       A note on terminology...  In automatic keying, there are two  kinds  of
       communications  going on: transmission of user IP packets, and gateway-
       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  information.   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
       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.

       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 discarded
                     and a diagnostic ICMP returned.

       connaddrfamily
                     (optional) Either ipv4 (the default) or ipv6  to  support
                     IPv6 connections

       left          (required)  the  IP  address  of  the  left participant’s
                     public-network  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  %defaultroute,  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
                     leftnexthop.  (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
                     network/netmask   (actually,   any   form  acceptable  to
                     ipsec_ttosubnet(3)); if omitted, essentially  assumed  to
                     be   left/32,   signifying  that  the  left  end  of  the
                     connection goes to the left participant only

       leftnexthop   next-hop gateway IP address for  the  left  participant’s
                     connection  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.

       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.

              If  one  or  both  security  gateways   are   doing   forwarding
              firewalling
              (possibly including masquerading), and this is  specified  using
              the  firewall  parameters,  tunnels  established  with IPsec are
              exempted from it so that packets can flow unchanged through  the
              tunnels.   (This means that all subnets connected in this manner
              must have  distinct,  non-overlapping  subnet  address  blocks.)
              This  is done by the default updown script (see ipsec_pluto(8)).

   CONN PARAMETERS:  AUTOMATIC KEYING
       The following parameters are relevant only to automatic keying, and 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), manual (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-
                     permanent  connection, both ends should use auto=start to
                     ensure that any reboot causes immediate renegotiation).

       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 (useful for  shunt-only
                     conns).   Digital signatures are superior in every way to
                     shared secrets.

       leftid        how  the  left  participant  should  be  identified   for
                     authentication;  defaults  to left.  Can be an IP address
                     (in any ipsec_ttoaddr(3)  syntax)  or  a  fully-qualified
                     domain  name  preceded  by  @ (which is used as a literal
                     string and not resolved).  The magic value  %myid  stands
                     for  the  current setting of myid.  This is set in config
                     setup or by ipsec_whack(8)), or, if not set, it is the IP
                     address  in  %defaultroute (if that is supported by a TXT
                     record in its reverse domain), or  otherwise  it  is  the
                     system’s  hostname  (if that is supported by a TXT record
                     in its forward domain), or otherwise it is undefined.

       leftrsasigkey the left  participant’s  public  key  for  RSA  signature
                     authentication, in RFC 2537 format using ipsec_ttodata(3)
                     encoding.  The magic value %none means the  same  as  not
                     specifying  a  value (useful 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
                     certificate  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.

       leftsendcert  This option configures  when  Openswan  will  send  X.509
                     certificates  to  the  remote host. Acceptable values are
                     yes|always (signifying  that  we  should  always  send  a
                     certificate),  ifasked  (signifying 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 implementations,
                     such as Cisco and SafeNet.  If  you  find  that  you  are
                     getting  errors about no ID/Key found, you likely need to
                     set this to always.

       aggrmode      Use aggressive mode ISAKMP negotiation.  The  default  is
                     main  mode. Aggressive mode is less secure than main mode
                     as it reveals your identity to an  eavesdropper,  but  is
                     needed  to  support  road  warriors  using PSK keys or to
                     interoperate with other buggy  implementations  insisting
                     on using aggressive mode.

       xauth         Use  XAUTH  / Mode Config for this connection.  This uses
                     PAM  for  authentication  currently,  and  it  not   well
                     documented.  Use the source :)  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.

       pfs           whether Perfect Forward Secrecy of keys is desired on the
                     connection’s keying channel (with PFS, penetration of the
                     key-exchange protocol does not compromise keys negotiated
                     earlier); acceptable values are yes (the default) and no.

       keylife       how long a particular instance of a connection (a set  of
                     encryption/authentication  keys  for user packets) should
                     last, from successful negotiation to  expiry;  acceptable
                     values are an integer 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
                     8.0h,  maximum  24h).   Normally,   the   connection   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, maximum 8h).  The two-ends-
                     disagree case is similar to that of keylife.

       compress      whether  IPComp compression of content is proposed on the
                     connection  (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   compressed   and
                     uncompressed,  and  prefer  compressed.   A  value  of no
                     prevents IPsec from proposing compression; a proposal  to
                     compress 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).  Tunnel-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.  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.  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  digits  (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)

       esp           ESP encryption/authentication algorithm to  be  used  for
                     the  connection, e.g.  3des-md5-96 (must be suitable as a
                     value of ipsec_spi(8)’s --esp option); default is not  to
                     use ESP

       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 rightespenckey 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 rightespauthkey 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

       ah            AH   authentication   algorithm   to   be  used  for  the
                     connection, e.g.  hmac-md5-96  (must  be  suitable  as  a
                     value  of  ipsec_spi(8)’s --ah option); default is not to
                     use AH

       ahkey         (required if ah is present) AH authentication  key  (must
                     be  suitable  as  a  value  of  ipsec_spi(8)’s  --authkey
                     option) (may be specified separately for  each  direction
                     using leftahkey (leftward 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=all
           manualstart=

       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    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 interface  is
                     noted for use by ipsec_manual(8) and ipsec_auto(8).)

       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  Red  Hat 6.x /etc/sysctl.conf), because IPsec doesn’t
                     get control early enough to do that.

       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.

       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).

       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).

       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   running   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   running   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.

       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.

       uniqueids     whether  a  particular  participant  ID  should  be  kept
                     unique, with any  new  (automatically  keyed)  connection
                     using an ID from a different 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.

       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-connection.

IMPLICIT CONNS

       The  system  automatically  defines  several conns to implement default
       policy groups.  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=%opportunisticgroup 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
       inherits 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
       provide 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 implemented 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
       subnets  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
       earlier 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_auto(8),     ipsec_manual(8),
       ipsec_rsasigkey(8)

HISTORY

       Designed for the FreeS/WAN project <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.

       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
       connections.

       In  principle  it might be necessary to control MTU on an interface-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,
       leftnextop=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.

                                  26 Nov 2001                    IPSEC.CONF(5)