[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.
.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 REFERENCING OTHER SECTIONS
It is possible to inherit settings and sections from another section. This
feature is mainly useful in swanctl.conf (which uses the same file format).
The syntax is as follows:
.PP
.EX
	section    := name : references { settings }
	references := absname[, absname]*
	absname    := name[.name]*
.EE
.PP
All key/value pairs and all subsections of the referenced sections will be
inherited by the section that references them via their absolute name. Values
may be overridden in the section or any of its sub-sections (use an empty
assignment to clear a value so its default value, if any, will apply). It is
currently not possible to limit the inclusion level or clear/remove inherited
sub-sections.

If the order is important (e.g. for auth rounds in a connection, if \fIround\fR
is not used), it should be noted that inherited settings/sections will follow
those defined in the current section (if multiple sections are referenced, their
settings are enumerated left to right).

References are evaluated dynamically at runtime, so referring to sections later
in the config file or included via other files is no problem.

Here is an example of how this might look like:
.PP
.EX
	conn-defaults {
		# default settings for all conns (e.g. a cert, or IP pools)
	}
	eap-defaults {
		# defaults if eap is used (e.g. a remote auth round)
	}
	child-defaults {
		# defaults for child configs (e.g. traffic selectors)
	}
	connections {
		conn-a : conn-defaults, eap-defaults {
			# set/override stuff specific to this connection
			children {
				child-a : child-defaults {
					# set/override stuff specific to this child
				}
			}
		}
		conn-b : conn-defaults {
			# set/override stuff specific to this connection
			children {
				child-b : child-defaults {
					# set/override stuff specific to this child
				}
			}
		}
		conn-c : connections.conn-a {
			# everything is inherited, including everything conn-a
			# already inherits from the sections it and its
			# sub-section reference
		}
	}
.EE
.PP

.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
	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
	63	.SH REFERENCING OTHER SECTIONS
	64	It is possible to inherit settings and sections from another section. This
	65	feature is mainly useful in swanctl.conf (which uses the same file format).
	66	The syntax is as follows:
	67	.PP
	68	.EX
	69	section := name : references { settings }
	70	references := absname[, absname]*
	71	absname := name[.name]*
	72	.EE
	73	.PP
	74	All key/value pairs and all subsections of the referenced sections will be
	75	inherited by the section that references them via their absolute name. Values
	76	may be overridden in the section or any of its sub-sections (use an empty
	77	assignment to clear a value so its default value, if any, will apply). It is
	78	currently not possible to limit the inclusion level or clear/remove inherited
	79	sub-sections.
	80
	81	If the order is important (e.g. for auth rounds in a connection, if \fIround\fR
	82	is not used), it should be noted that inherited settings/sections will follow
	83	those defined in the current section (if multiple sections are referenced, their
	84	settings are enumerated left to right).
	85
	86	References are evaluated dynamically at runtime, so referring to sections later
	87	in the config file or included via other files is no problem.
	88
	89	Here is an example of how this might look like:
	90	.PP
	91	.EX
	92	conn-defaults {
	93	# default settings for all conns (e.g. a cert, or IP pools)
	94	}
	95	eap-defaults {
	96	# defaults if eap is used (e.g. a remote auth round)
	97	}
	98	child-defaults {
	99	# defaults for child configs (e.g. traffic selectors)
	100	}
	101	connections {
	102	conn-a : conn-defaults, eap-defaults {
	103	# set/override stuff specific to this connection
	104	children {
	105	child-a : child-defaults {
	106	# set/override stuff specific to this child
	107	}
	108	}
	109	}
	110	conn-b : conn-defaults {
	111	# set/override stuff specific to this connection
	112	children {
	113	child-b : child-defaults {
	114	# set/override stuff specific to this child
	115	}
	116	}
	117	}
	118	conn-c : connections.conn-a {
	119	# everything is inherited, including everything conn-a
	120	# already inherits from the sections it and its
	121	# sub-section reference
	122	}
	123	}
	124	.EE
	125	.PP
	126
	127	.SH INCLUDING FILES
	128	Using the
	129	.B include
	130	statement it is possible to include other files into strongswan.conf, e.g.
	131	.PP
	132	.EX
	133	include /some/path/*.conf
	134	.EE
	135	.PP
	136	If the file name is not an absolute path, it is considered to be relative
	137	to the directory of the file containing the include statement. The file name
	138	may include shell wildcards (see
	139	.IR sh (1)).
	140	Also, such inclusions can be nested.
	141	.PP
	142	Sections loaded from included files
	143	.I extend
	144	previously loaded sections; already existing values are
	145	.IR replaced .
	146	It is important to note that settings are added relative to the section the
	147	include statement is in.
	148	.PP
	149	As an example, the following three files result in the same final
	150	config as the one given above:
	151	.PP
	152	.EX
	153	a = b
	154	section-one {
	155	somevalue = before include
	156	include include.conf
	157	}
	158	include other.conf
	159
	160	include.conf:
	161	# settings loaded from this file are added to section-one
	162	# the following replaces the previous value
	163	somevalue = asdf
	164	subsection {
	165	othervalue = yyy
	166	}
	167	yetanother = zz
	168
	169	other.conf:
	170	# this extends section-one and subsection
	171	section-one {
	172	subsection {
	173	# this replaces the previous value
	174	othervalue = xxx
	175	}
	176	}
	177	section-two {
	178	x = 12
	179	}
	180	.EE
	181
	182	.SH READING VALUES
	183	Values are accessed using a dot-separated section list and a key.
	184	With reference to the example above, accessing
	185	.B section-one.subsection.othervalue
	186	will return
	187	.BR xxx .
	188
	189	.SH DEFINED KEYS
	190	The following keys are currently defined (using dot notation). The default
	191	value (if any) is listed in brackets after the key.