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 An example file in this format might look like this:
  44 .PP
  45 .EX
  46         a = b
  47         section-one {
  48                 somevalue = asdf
  49                 subsection {
  50                         othervalue = xxx
  51                 }
  52                 # yei, a comment
  53                 yetanother = zz
  54         }
  55         section-two {
  56                 x = 12
  57         }
  58 .EE
  59 .PP
  60 Indentation is optional, you may use tabs or spaces.
  61
  62 .SH NUMBER FORMATS
  63 Options that define an integer value can be specified as decimal (the default)
  64 or hexadecimal ("0x" prefix, upper- or lowercase letters are accepted).
  65 Locale-dependent strings (e.g. the thousands separator of the current locale)
  66 may also be accepted in locales other than "C".
  67 .PP
  68 Options that define a floating-point value can be specified as decimal (the
  69 default) or hexadecimal ("0x" prefix, upper- or lowercase letters are accepted).
  70 The radix character (decimal separator) in either case is locale-dependent,
  71 usually ".".
  72
  73 .SH TIME FORMATS
  74 Unless stated otherwise, options that define a time are specified in seconds.
  75 The "s", "m", "h" and "d" suffixes may be used to automatically convert values
  76 given in seconds, minutes, hours or days (for instance, instead of configuring
  77 a rekey time of 4 hours as "14400" seconds, "4h" may be used).
  78 .PP
  79 There are some global options that don't accept these suffixes as they are
  80 configured as integer values in seconds or milliseconds, or even as
  81 floating-point numbers (e.g. the retransmission timeout). Options that accept
  82 the suffixes have a corresponding default value.
  83
  84 .SH REFERENCING OTHER SECTIONS
  85 It is possible to inherit settings and sections from another section. This
  86 feature is mainly useful in swanctl.conf (which uses the same file format).
  87 The syntax is as follows:
  88 .PP
  89 .EX
  90         section    := name : references { settings }
  91         references := absname[, absname]*
  92         absname    := name[.name]*
  93 .EE
  94 .PP
  95 All key/value pairs and all subsections of the referenced sections will be
  96 inherited by the section that references them via their absolute name. Values
  97 may be overridden in the section or any of its sub-sections (use an empty
  98 assignment to clear a value so its default value, if any, will apply). It is
  99 currently not possible to limit the inclusion level or clear/remove inherited
 100 sub-sections.
 101
 102 If the order is important (e.g. for auth rounds in a connection, if \fIround\fR
 103 is not used), it should be noted that inherited settings/sections will follow
 104 those defined in the current section (if multiple sections are referenced, their
 105 settings are enumerated left to right).
 106
 107 References are evaluated dynamically at runtime, so referring to sections later
 108 in the config file or included via other files is no problem.
 109
 110 Here is an example of how this might look like:
 111 .PP
 112 .EX
 113         conn-defaults {
 114                 # default settings for all conns (e.g. a cert, or IP pools)
 115         }
 116         eap-defaults {
 117                 # defaults if eap is used (e.g. a remote auth round)
 118         }
 119         child-defaults {
 120                 # defaults for child configs (e.g. traffic selectors)
 121         }
 122         connections {
 123                 conn-a : conn-defaults, eap-defaults {
 124                         # set/override stuff specific to this connection
 125                         children {
 126                                 child-a : child-defaults {
 127                                         # set/override stuff specific to this child
 128                                 }
 129                         }
 130                 }
 131                 conn-b : conn-defaults {
 132                         # set/override stuff specific to this connection
 133                         children {
 134                                 child-b : child-defaults {
 135                                         # set/override stuff specific to this child
 136                                 }
 137                         }
 138                 }
 139                 conn-c : connections.conn-a {
 140                         # everything is inherited, including everything conn-a
 141                         # already inherits from the sections it and its
 142                         # sub-section reference
 143                 }
 144         }
 145 .EE
 146 .PP
 147
 148 .SH INCLUDING FILES
 149 Using the
 150 .B include
 151 statement it is possible to include other files into strongswan.conf, e.g.
 152 .PP
 153 .EX
 154         include /some/path/*.conf
 155 .EE
 156 .PP
 157 If the file name is not an absolute path, it is considered to be relative
 158 to the directory of the file containing the include statement. The file name
 159 may include shell wildcards (see
 160 .IR sh (1)).
 161 Also, such inclusions can be nested.
 162 .PP
 163 Sections loaded from included files
 164 .I extend
 165 previously loaded sections; already existing values are
 166 .IR replaced .
 167 It is important to note that settings are added relative to the section the
 168 include statement is in.
 169 .PP
 170 As an example, the following three files result in the same final
 171 config as the one given above:
 172 .PP
 173 .EX
 174         a = b
 175         section-one {
 176                 somevalue = before include
 177                 include include.conf
 178         }
 179         include other.conf
 180
 181 include.conf:
 182         # settings loaded from this file are added to section-one
 183         # the following replaces the previous value
 184         somevalue = asdf
 185         subsection {
 186                 othervalue = yyy
 187         }
 188         yetanother = zz
 189
 190 other.conf:
 191         # this extends section-one and subsection
 192         section-one {
 193                 subsection {
 194                         # this replaces the previous value
 195                         othervalue = xxx
 196                 }
 197         }
 198         section-two {
 199                 x = 12
 200         }
 201 .EE
 202
 203 .SH READING VALUES
 204 Values are accessed using a dot-separated section list and a key.
 205 With reference to the example above, accessing
 206 .B section-one.subsection.othervalue
 207 will return
 208 .BR xxx .
 209
 210 .SH DEFINED KEYS
 211 The following keys are currently defined (using dot notation). The default
 212 value (if any) is listed in brackets after the key.