.TH IPSEC.CONF 5 "2012-06-26" "@PACKAGE_VERSION@" "strongSwan" .SH NAME ipsec.conf \- IPsec configuration and connections .SH DESCRIPTION The optional .I ipsec.conf file specifies most configuration and control information for the strongSwan IPsec subsystem. The major exception is secrets for authentication; see .IR ipsec.secrets (5). Its contents are not security-sensitive. .PP The file is a text file, consisting of one or more .IR sections . White space followed by .B # followed by anything to the end of the line is a comment and is ignored, as are empty lines which are not within a section. .PP A line which contains .B include and a file name, separated by white space, is replaced by the contents of that file. If the file name is not a full pathname, it is considered to be relative to the directory containing the including file. Such inclusions can be nested. Only a single filename may be supplied, and it may not contain white space, but it may include shell wildcards (see .IR sh (1)); for example: .PP .B include .B "ipsec.*.conf" .PP The intention of the include facility is mostly to permit keeping information on connections, or sets of connections, separate from the main configuration file. This permits such connection descriptions to be changed, copied to the other security gateways involved, etc., without having to constantly extract them from the configuration file and then insert them back into it. Note also the .B also parameter (described below) which permits splitting a single logical section (e.g. a connection description) into several actual sections. .PP A section begins with a line of the form: .PP .I type .I name .PP where .I type indicates what type of section follows, and .I name is an arbitrary name which distinguishes the section from others of the same type. All subsequent non-empty lines which begin with white space are part of the section. Sections of the same type that share the same name are merged. .PP Lines within the section are generally of the form .PP \ \ \ \ \ \fIparameter\fB=\fIvalue\fR .PP (note the mandatory preceding white space). There can be white space on either side of the .BR = . Parameter names are specific to a section type. .PP An empty .I value stands for the system default value (if any) of the parameter, i.e. it is roughly equivalent to omitting the parameter line entirely. This may be useful to clear a setting inherited from a .B %default section or via .B also parameter (see below). A .I value may contain single spaces (additional white space is reduced to one space). To preserve white space as written enclose the entire .I value in double quotes (\fB"\fR); in such values double quotes themselves may be escaped by prefixing them with .B \\\\ characters. A double-quoted string may span multiple lines by ending them with .B \\\\ characters (following lines don't have to begin with white space, as that will be preserved). Additionally, the following control characters may be encoded in double-quoted strings: \\n, \\r, \\t, \\b, \\f. .PP Numeric values are specified to be either an ``integer'' (a sequence of digits) or a ``decimal number'' (sequence of digits optionally followed by `.' and another sequence of digits). .PP There is currently one parameter which is available in any type of section: .TP .B also the value is a section name; the parameters of that section are inherited by the current section. Parameters in the current section always override inherited parameters, even if an .B also follows after them. The specified section must exist and must have the same section type; it doesn't if it is defined before or after the current section. Nesting is permitted, and there may be more than one .B also in a single section (parameters from referenced sections are inherited and overridden in the order of these .B also parameters). .PP A section with name .B %default specifies defaults for sections of the same type. All parameters in it, are inherited by all other sections of that type. .PP Currently there are three types of sections: a .B config section specifies general configuration information for IPsec, a .B conn section specifies an IPsec connection, while a .B ca section specifies special properties of a certification authority. .SH "CONN SECTIONS" A .B conn section contains a .IR "connection specification" , defining a network connection to be made using IPsec. The name given is arbitrary, and is used to identify the connection. Here's a simple example: .PP .ne 10 .nf .ft B .ta 1c conn snt left=192.168.0.1 leftsubnet=10.1.0.0/16 right=192.168.0.2 rightsubnet=10.1.0.0/16 keyingtries=%forever auto=add .ft .fi .PP A note on terminology: There are two kinds of communications going on: transmission of user IP packets, and gateway-to-gateway negotiations for keying, rekeying, and general control. The path to control the connection is called 'ISAKMP SA' in IKEv1 and 'IKE SA' in the IKEv2 protocol. That what is being negotiated, the kernel level data path, is called 'IPsec SA' or 'Child SA'. strongSwan previously used two separate keying daemons, \fIpluto\fP and \fIcharon\fP. This manual does not discuss \fIpluto\fP options anymore, but only \fIcharon\fP that since strongSwan 5.0 supports both IKEv1 and IKEv2. .PP To avoid trivial editing of the configuration file to suit it to each system involved in a connection, connection specifications are written in terms of .I left and .I right participants, rather than in terms of local and remote. Which participant is considered .I left or .I right is arbitrary; for every connection description an attempt is made to figure out whether the local endpoint should act as the .I left or .I right endpoint. This is done by matching the IP addresses defined for both endpoints with the IP addresses assigned to local network interfaces. If a match is found then the role (left or right) that matches is going to be considered local. If no match is found during startup, .I left is considered local. This permits using identical connection specifications on both ends. There are cases where there is no symmetry; a good convention is to use .I left for the local side and .I right for the remote side (the first letters are a good mnemonic). .PP Many of the parameters relate to one participant or the other; only the ones for .I left are listed here, but every parameter whose name begins with .B left has a .B right counterpart, whose description is the same but with .B left and .B right reversed. .PP Parameters are optional unless marked '(required)'. .SS "CONN PARAMETERS" Unless otherwise noted, for a connection to work, in general it is necessary for the two ends to agree exactly on the values of these parameters. .TP .BR aaa_identity " = " defines the identity of the AAA backend used during IKEv2 EAP authentication. This is required if the EAP client uses a method that verifies the server identity (such as EAP-TLS), but it does not match the IKEv2 gateway identity. .TP .BR aggressive " = yes | " no whether to use IKEv1 Aggressive or Main Mode (the default). .TP .BR ah " = " comma-separated list of AH algorithms to be used for the connection, e.g. .BR sha1-sha256-modp1024 . The notation is .BR integrity[-dhgroup] . For IKEv2, multiple algorithms (separated by -) of the same type can be included in a single proposal. IKEv1 only includes the first algorithm in a proposal. Only either the .B ah or .B esp keyword may be used, AH+ESP bundles are not supported. There is no default AH cipher suite since by default ESP is used. The daemon adds its extensive default proposal to the configured value. To restrict it to the configured proposal an exclamation mark .RB ( ! ) can be added at the end. If .B dh-group is specified, CHILD_SA/Quick Mode setup and rekeying include a separate Diffie-Hellman exchange (refer to the .B esp keyword for details). .TP .BR also " = " includes conn section .BR . .TP .BR auth " = " was used by the .B pluto IKEv1 daemon to use AH integrity protection for ESP encrypted packets, but is not supported in charon. The .B ah keyword specifies algorithms to use for integrity protection with AH, but without encryption. AH+ESP bundles are not supported. .TP .BR authby " = " pubkey " | rsasig | ecdsasig | psk | secret | never | xauthpsk | xauthrsasig" how the two security gateways should authenticate each other; acceptable values are .B psk or .B secret for pre-shared secrets, .B pubkey (the default) for public key signatures as well as the synonyms .B rsasig for RSA digital signatures and .B ecdsasig for Elliptic Curve DSA signatures. .B never can be used if negotiation is never to be attempted or accepted (useful for shunt-only conns). Digital signatures are superior in every way to shared secrets. IKEv1 additionally supports the values .B xauthpsk and .B xauthrsasig that will enable eXtended AUTHentication (XAUTH) in addition to IKEv1 main mode based on shared secrets or digital RSA signatures, respectively. This parameter is deprecated, as two peers do not need to agree on an authentication method in IKEv2. Use the .B leftauth parameter instead to define authentication methods. .TP .BR auto " = " ignore " | add | route | start" what operation, if any, should be done automatically at IPsec startup; currently-accepted values are .BR add , .BR route , .B start and .B ignore (the default). .B add loads a connection without starting it. .B route loads a connection and installs kernel traps. If traffic is detected between .B leftsubnet and .BR rightsubnet , a connection is established. .B start loads a connection and brings it up immediately. .B ignore ignores the connection. This is equal to deleting a connection from the config file. Relevant only locally, other end need not agree on it. .TP .BR closeaction " = " none " | clear | hold | restart" defines the action to take if the remote peer unexpectedly closes a CHILD_SA (see .B dpdaction for meaning of values). A .B closeaction should not be used if the peer uses reauthentication or uniquids checking, as these events might trigger the defined action when not desired. .TP .BR compress " = yes | " no whether IPComp compression of content is proposed on the connection (link-level compression does not work on encrypted data, so to be effective, compression must be done \fIbefore\fR encryption); acceptable values are .B yes and .B no (the default). A value of .B yes causes the daemon to propose both compressed and uncompressed, and prefer compressed. A value of .B no prevents the daemon from proposing or accepting compression. .TP .BR dpdaction " = " none " | clear | hold | restart" controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2) are periodically sent in order to check the liveliness of the IPsec peer. The values .BR clear , .BR hold , and .B restart all activate DPD and determine the action to perform on a timeout. With .B clear the connection is closed with no further actions taken. .B hold installs a trap policy, which will catch matching traffic and tries to re-negotiate the connection on demand. .B restart will immediately trigger an attempt to re-negotiation the connection. The default is .B none which disables the active sending of DPD messages. .TP .BR dpddelay " = " 30s " |