[thirdparty/strongswan.git] / conf / strongswan.conf.5.head.in

.TH STRONGSWAN.CONF 5 "" "@PACKAGE_VERSION@" "strongSwan"
.SH NAME
strongswan.conf \- strongSwan configuration file
.SH DESCRIPTION
While the
.IR ipsec.conf (5)
configuration file is well suited to define IPsec related configuration
parameters, it is not useful for other strongSwan applications to read options
from this file.
The file is hard to parse and only
.I ipsec starter
is capable of doing so. As the number of components of the strongSwan project
is continually growing, a more flexible configuration file was needed, one that
is easy to extend and can be used by all components. With strongSwan 4.2.1
.IR strongswan.conf (5)
was introduced which meets these requirements.

.SH SYNTAX
The format of the strongswan.conf file consists of hierarchical
.B sections
and a list of
.B key/value pairs
in each section. Each section has a name, followed by C-Style curly brackets
defining the section body. Each section body contains a set of subsections
and key/value pairs:
.PP
.EX
	settings := (section|keyvalue)*
	section  := name { settings }
	keyvalue := key = value\\n
.EE
.PP
Values must be terminated by a newline.
.PP
Comments are possible using the \fB#\fP-character, but be careful: The parser
implementation is currently limited and does not like brackets in comments.
.PP
Section names and keys may contain any printable character except:
.PP
.EX
	. { } # \\n \\t space
.EE
.PP
An example file in this format might look like this:
.PP
.EX
	a = b
	section-one {
		somevalue = asdf
		subsection {
			othervalue = xxx
		}
		# yei, a comment
		yetanother = zz
	}
	section-two {
		x = 12
	}
.EE
.PP
Indentation is optional, you may use tabs or spaces.

.SH INCLUDING FILES
Using the
.B include
statement it is possible to include other files into strongswan.conf, e.g.
.PP
.EX
	include /some/path/*.conf
.EE
.PP
If the file name is not an absolute path, it is considered to be relative
to the directory of the file containing the include statement. The file name
may include shell wildcards (see
.IR sh (1)).
Also, such inclusions can be nested.
.PP
Sections loaded from included files
.I extend
previously loaded sections; already existing values are
.IR replaced .
It is important to note that settings are added relative to the section the
include statement is in.
.PP
As an example, the following three files result in the same final
config as the one given above:
.PP
.EX
	a = b
	section-one {
		somevalue = before include
		include include.conf
	}
	include other.conf

include.conf:
	# settings loaded from this file are added to section-one
	# the following replaces the previous value
	somevalue = asdf
	subsection {
		othervalue = yyy
	}
	yetanother = zz

other.conf:
	# this extends section-one and subsection
	section-one {
		subsection {
			# this replaces the previous value
			othervalue = xxx
		}
	}
	section-two {
		x = 12
	}
.EE

.SH READING VALUES
Values are accessed using a dot-separated section list and a key.
With reference to the example above, accessing
.B section-one.subsection.othervalue
will return
.BR xxx .

.SH DEFINED KEYS
The following keys are currently defined (using dot notation). The default
value (if any) is listed in brackets after the key.
Commit	Line	Data
c4bb26b8 TB	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.