.TH IPSEC.CONF 5 "2012-06-26" "@IPSEC_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, preceded and followed by empty lines. 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. Names must start with a letter and may contain only letters, digits, periods, underscores, and hyphens. All subsequent non-empty lines which begin with white space are part of the section; comments within a section must begin with white space too. There may be only one section of a given type with a given name. .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 follow the same syntax as section names, and are specific to a section type. Unless otherwise explicitly specified, no parameter name may appear more than once in a section. .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. A .I value may contain white space only if the entire .I value is enclosed in double quotes (\fB"\fR); a .I value cannot itself contain a double quote, nor may it be continued across more than one line. .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 appended to this section, as if they had been written as part of it. The specified section must exist, must follow the current one, and must have the same section type. (Nesting is permitted, and there may be more than one .B also in a single section, although it is forbidden to append the same section more than once.) .PP A section with name .B %default specifies defaults for sections of the same type. For each parameter in it, any section of that type which does not have a parameter of the same name gets a copy of the one from the .B %default section. There may be multiple .B %default sections of a given type, but only one default may be supplied for any specific parameter name, and all .B %default sections of a given type must precede all non-\c .B %default sections of that type. .B %default sections may not contain the .B also parameter. .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 also " = " includes conn section .BR . .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 .B rightsubnet , a connection is established. .B start loads a connection and brings it up immediately. .B ignore ignores the connection. This is equal to delete 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. Currently not supported with IKEv1. .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. If no activity is detected, all connections with a dead peer are stopped and unrouted .RB ( clear ), put in the hold state .RB ( hold ) or restarted .RB ( restart ). The default is .B none which disables the active sending of DPD messages. .TP .BR dpddelay " = " 30s " |