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, but be careful: The parser
  36 implementation is currently limited and does not like brackets in comments.
  37 .PP
  38 Section names and keys may contain any printable character except:
  39 .PP
  40 .EX
  41         . { } # \\n \\t space
  42 .EE
  43 .PP
  44 An example file in this format might look like this:
  45 .PP
  46 .EX
  47         a = b
  48         section-one {
  49                 somevalue = asdf
  50                 subsection {
  51                         othervalue = xxx
  52                 }
  53                 # yei, a comment
  54                 yetanother = zz
  55         }
  56         section-two {
  57                 x = 12
  58         }
  59 .EE
  60 .PP
  61 Indentation is optional, you may use tabs or spaces.
  62
  63 .SH INCLUDING FILES
  64 Using the
  65 .B include
  66 statement it is possible to include other files into strongswan.conf, e.g.
  67 .PP
  68 .EX
  69         include /some/path/*.conf
  70 .EE
  71 .PP
  72 If the file name is not an absolute path, it is considered to be relative
  73 to the directory of the file containing the include statement. The file name
  74 may include shell wildcards (see
  75 .IR sh (1)).
  76 Also, such inclusions can be nested.
  77 .PP
  78 Sections loaded from included files
  79 .I extend
  80 previously loaded sections; already existing values are
  81 .IR replaced .
  82 It is important to note that settings are added relative to the section the
  83 include statement is in.
  84 .PP
  85 As an example, the following three files result in the same final
  86 config as the one given above:
  87 .PP
  88 .EX
  89         a = b
  90         section-one {
  91                 somevalue = before include
  92                 include include.conf
  93         }
  94         include other.conf
  95
  96 include.conf:
  97         # settings loaded from this file are added to section-one
  98         # the following replaces the previous value
  99         somevalue = asdf
 100         subsection {
 101                 othervalue = yyy
 102         }
 103         yetanother = zz
 104
 105 other.conf:
 106         # this extends section-one and subsection
 107         section-one {
 108                 subsection {
 109                         # this replaces the previous value
 110                         othervalue = xxx
 111                 }
 112         }
 113         section-two {
 114                 x = 12
 115         }
 116 .EE
 117
 118 .SH READING VALUES
 119 Values are accessed using a dot-separated section list and a key.
 120 With reference to the example above, accessing
 121 .B section-one.subsection.othervalue
 122 will return
 123 .BR xxx .
 124
 125 .SH DEFINED KEYS
 126 The following keys are currently defined (using dot notation). The default
 127 value (if any) is listed in brackets after the key.