conf/strongswan.conf.5.head.in

   1 .TH STRONGSWAN.CONF 5 "" "@PACKAGE_VERSION@" "strongSwan"
   2 .SH NAME
   3 strongswan.conf \- strongSwan configuration file
   4 .SH DESCRIPTION
   5 While the
   6 .IR ipsec.conf (5)
   7 configuration file is well suited to define IPsec related configuration
   8 parameters, it is not useful for other strongSwan applications to read options
   9 from this file.
  10 The file is hard to parse and only
  11 .I ipsec starter
  12 is capable of doing so. As the number of components of the strongSwan project
  13 is continually growing, a more flexible configuration file was needed, one that
  14 is easy to extend and can be used by all components. With strongSwan 4.2.1
  15 .IR strongswan.conf (5)
  16 was introduced which meets these requirements.
  17
  18 .SH SYNTAX
  19 The format of the strongswan.conf file consists of hierarchical
  20 .B sections
  21 and a list of
  22 .B key/value pairs
  23 in each section. Each section has a name, followed by C-Style curly brackets
  24 defining the section body. Each section body contains a set of subsections
  25 and key/value pairs:
  26 .PP
  27 .EX
  28         settings := (section|keyvalue)*
  29         section  := name { settings }
  30         keyvalue := key = value\\n
  31 .EE
  32 .PP
  33 Values must be terminated by a newline.
  34 .PP
  35 Comments are possible using the \fB#\fP-character.
  36 .PP
  37 Section names and keys may contain any printable character except:
  38 .PP
  39 .EX
  40         . , : { } = " # \\n \\t space
  41 .EE
  42 .PP
  43 In rare circumstances \fB.\fP characters may be used in section names (e.g. for
  44 log file names in a filelog section), but should generally be avoided.
  45 To use \fB:\fP characters in section names (e.g. for Windows log file paths)
  46 they may be written as \fB::\fP, which the parser replaces with a single
  47 \fB:\fP.
  48
  49 An example file in this format might look like this:
  50 .PP
  51 .EX
  52         a = b
  53         section-one {
  54                 somevalue = asdf
  55                 subsection {
  56                         othervalue = xxx
  57                 }
  58                 # yei, a comment
  59                 yetanother = zz
  60         }
  61         section-two {
  62                 x = 12
  63         }
  64 .EE
  65 .PP
  66 Indentation is optional, you may use tabs or spaces.
  67
  68
  69 .SH REFERENCING OTHER SECTIONS
  70 It is possible to inherit settings and sections from another section. This
  71 feature is mainly useful in swanctl.conf (which uses the same file format).
  72 The syntax is as follows:
  73 .PP
  74 .EX
  75         section    := name : references { settings }
  76         references := absname[, absname]*
  77         absname    := name[.name]*
  78 .EE
  79 .PP
  80 All key/value pairs and all subsections of the referenced sections will be
  81 inherited by the section that references them via their absolute name. Values
  82 may be overridden in the section or any of its sub-sections (use an empty
  83 assignment to clear a value so its default value, if any, will apply). It is
  84 currently not possible to limit the inclusion level or clear/remove inherited
  85 sub-sections.
  86
  87 If the order is important (e.g. for auth rounds in a connection, if \fIround\fR
  88 is not used), it should be noted that inherited settings/sections will follow
  89 those defined in the current section (if multiple sections are referenced, their
  90 settings are enumerated left to right).
  91
  92 References are evaluated dynamically at runtime, so referring to sections later
  93 in the config file or included via other files is no problem.
  94
  95 Here is an example of how this might look like:
  96 .PP
  97 .EX
  98         conn-defaults {
  99                 # default settings for all conns (e.g. a cert, or IP pools)
 100         }
 101         eap-defaults {
 102                 # defaults if eap is used (e.g. a remote auth round)
 103         }
 104         child-defaults {
 105                 # defaults for child configs (e.g. traffic selectors)
 106         }
 107         connections {
 108                 conn-a : conn-defaults, eap-defaults {
 109                         # set/override stuff specific to this connection
 110                         children {
 111                                 child-a : child-defaults {
 112                                         # set/override stuff specific to this child
 113                                 }
 114                         }
 115                 }
 116                 conn-b : conn-defaults {
 117                         # set/override stuff specific to this connection
 118                         children {
 119                                 child-b : child-defaults {
 120                                         # set/override stuff specific to this child
 121                                 }
 122                         }
 123                 }
 124                 conn-c : connections.conn-a {
 125                         # everything is inherited, including everything conn-a
 126                         # already inherits from the sections it and its
 127                         # sub-section reference
 128                 }
 129         }
 130 .EE
 131 .PP
 132
 133 .SH INCLUDING FILES
 134 Using the
 135 .B include
 136 statement it is possible to include other files into strongswan.conf, e.g.
 137 .PP
 138 .EX
 139         include /some/path/*.conf
 140 .EE
 141 .PP
 142 If the file name is not an absolute path, it is considered to be relative
 143 to the directory of the file containing the include statement. The file name
 144 may include shell wildcards (see
 145 .IR sh (1)).
 146 Also, such inclusions can be nested.
 147 .PP
 148 Sections loaded from included files
 149 .I extend
 150 previously loaded sections; already existing values are
 151 .IR replaced .
 152 It is important to note that settings are added relative to the section the
 153 include statement is in.
 154 .PP
 155 As an example, the following three files result in the same final
 156 config as the one given above:
 157 .PP
 158 .EX
 159         a = b
 160         section-one {
 161                 somevalue = before include
 162                 include include.conf
 163         }
 164         include other.conf
 165
 166 include.conf:
 167         # settings loaded from this file are added to section-one
 168         # the following replaces the previous value
 169         somevalue = asdf
 170         subsection {
 171                 othervalue = yyy
 172         }
 173         yetanother = zz
 174
 175 other.conf:
 176         # this extends section-one and subsection
 177         section-one {
 178                 subsection {
 179                         # this replaces the previous value
 180                         othervalue = xxx
 181                 }
 182         }
 183         section-two {
 184                 x = 12
 185         }
 186 .EE
 187
 188 .SH READING VALUES
 189 Values are accessed using a dot-separated section list and a key.
 190 With reference to the example above, accessing
 191 .B section-one.subsection.othervalue
 192 will return
 193 .BR xxx .
 194
 195 .SH DEFINED KEYS
 196 The following keys are currently defined (using dot notation). The default
 197 value (if any) is listed in brackets after the key.