diff options
Diffstat (limited to 'src/starter/ipsec.conf.5.in')
| -rw-r--r-- | src/starter/ipsec.conf.5.in | 1330 |
1 files changed, 1330 insertions, 0 deletions
diff --git a/src/starter/ipsec.conf.5.in b/src/starter/ipsec.conf.5.in new file mode 100644 index 000000000..3d2940a66 --- /dev/null +++ b/src/starter/ipsec.conf.5.in @@ -0,0 +1,1330 @@ +.TH IPSEC.CONF 5 "2010-05-30" "@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 currently uses two separate keying daemons. \fIpluto\fP handles +all IKEv1 connections, \fIcharon\fP is the daemon handling the IKEv2 +protocol. +.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 14 +.B ah +AH authentication algorithm to be used +for the connection, e.g. +.B hmac-md5. +.TP +.B auth +whether authentication should be done as part of +ESP encryption, or separately using the AH protocol; +acceptable values are +.B esp +(the default) and +.BR ah . +.br +The IKEv2 daemon currently supports ESP only. +.TP +.B authby +how the two security gateways should authenticate each other; +acceptable values are +.B secret +or +.B psk +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. +IKEv2 additionally supports the value +.BR eap , +which indicates an initiator to request EAP authentication. The EAP method +to use is selected by the server (see +.BR eap ). +This parameter is deprecated for IKEv2 connections, as two peers do not need +to agree on an authentication method. Use the +.B leftauth +parameter instead to define authentication methods in IKEv2. +.TP +.B auto +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 immediatly. +.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 +(but in general, for an intended-to-be-permanent connection, +both ends should use +.B auto=start +to ensure that any reboot causes immediate renegotiation). +.TP +.B compress +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 IPsec to propose both compressed and uncompressed, +and prefer compressed. +A value of +.B no +prevents IPsec from proposing compression; +a proposal to compress will still be accepted. +.TP +.B dpdaction +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 ). +For IKEv1, the default is +.B none +which disables the active sending of R_U_THERE notifications. +Nevertheless pluto will always send the DPD Vendor ID during connection set up +in order to signal the readiness to act passively as a responder if the peer +wants to use DPD. For IKEv2, +.B none +does't make sense, since all messages are used to detect dead peers. If specified, +it has the same meaning as the default +.RB ( clear ). +.TP +.B dpddelay +defines the period time interval with which R_U_THERE messages/INFORMATIONAL +exchanges are sent to the peer. These are only sent if no other traffic is +received. In IKEv2, a value of 0 sends no additional INFORMATIONAL +messages and uses only standard messages (such as those to rekey) to detect +dead peers. +.TP +.B dpdtimeout +defines the timeout interval, after which all connections to a peer are deleted +in case of inactivity. This only applies to IKEv1, in IKEv2 the default +retransmission timeout applies, as every exchange is used to detect dead peers. +.TP +.B inactivity +defines the timeout interval, after which a CHILD_SA is closed if it did +not send or receive any traffic. Currently supported in IKEv2 connections only. +.TP +.B eap +defines the EAP type to propose as server if the client requests EAP +authentication. Currently supported values are +.B aka +for EAP-AKA, +.B gtc +for EAP-GTC, +.B md5 +for EAP-MD5, +.B mschapv2 +for EAP-MS-CHAPv2, +.B radius +for the EAP-RADIUS proxy and +.B sim +for EAP-SIM. Additionally, IANA assigned EAP method numbers are accepted, or a +definition in the form +.B eap=type-vendor +(e.g. eap=7-12345) can be used to specify vendor specific EAP types. +This parameter is deprecated in the favour of +.B leftauth. + +To forward EAP authentication to a RADIUS server using the EAP-RADIUS plugin, +set +.BR eap=radius . +.TP +.B eap_identity +defines the identity the client uses to reply to a EAP Identity request. +If defined on the EAP server, the defined identity will be used as peer +identity during EAP authentication. The special value +.B %identity +uses the EAP Identity method to ask the client for an EAP identity. If not +defined, the IKEv2 identity will be used as EAP identity. +.TP +.B esp +comma-separated list of ESP encryption/authentication algorithms to be used +for the connection, e.g. +.BR 3des-md5 . +The notation is +.BR encryption-integrity-[dh-group] . +.br +If +.B dh-group +is specified, CHILD_SA setup and rekeying include a separate diffe hellman +exchange (IKEv2 only). +.TP +.B forceencaps +Force UDP encapsulation for ESP packets even if no NAT situation is detected. +This may help to surmount restrictive firewalls. In order to force the peer to +encapsulate packets, NAT detection payloads are faked (IKEv2 only). +.TP +.B ike +comma-separated list of IKE/ISAKMP SA encryption/authentication algorithms +to be used, e.g. +.BR aes128-sha1-modp2048 . +The notation is +.BR encryption-integrity-dhgroup . +In IKEv2, multiple algorithms and proposals may be included, such as +.B aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024. +.TP +.B ikelifetime +how long the keying channel of a connection (ISAKMP or IKE SA) +should last before being renegotiated. +.TP +.B installpolicy +decides whether IPsec policies are installed in the kernel by the IKEv2 +charon daemon for a given connection. Allows peaceful cooperation e.g. with +the Mobile IPv6 daemon mip6d who wants to control the kernel policies. +Acceptable values are +.B yes +(the default) and +.BR no . +.TP +.B keyexchange +method of key exchange; +which protocol should be used to initialize the connection. Connections marked with +.B ikev1 +are initiated with pluto, those marked with +.B ikev2 +with charon. An incoming request from the remote peer is handled by the correct +daemon, unaffected from the +.B keyexchange +setting. The default value +.B ike +currently is a synonym for +.BR ikev1 . +.TP +.B keyingtries +how many attempts (a whole number or \fB%forever\fP) should be made to +negotiate a connection, or a replacement for one, before giving up +(default +.BR %forever ). +The value \fB%forever\fP +means 'never give up'. +Relevant only locally, other end need not agree on it. +.TP +.B keylife +synonym for +.BR lifetime . +.TP +.B left +(required) +the IP address of the left participant's public-network interface +or one of several magic values. +If it is +.BR %defaultroute , +.B left +will be filled in automatically with the local address +of the default-route interface (as determined at IPsec startup time and +during configuration update). +Either +.B left +or +.B right +may be +.BR %defaultroute , +but not both. +The prefix +.B % +in front of a fully-qualified domain name or an IP address will implicitly set +.B leftallowany=yes. +If the domain name cannot be resolved into an IP address at IPsec startup or +update time then +.B left=%any +and +.B leftallowany=no +will be assumed. + +In case of an IKEv2 connection, the value +.B %any +for the local endpoint signifies an address to be filled in (by automatic +keying) during negotiation. If the local peer initiates the connection setup +the routing table will be queried to determine the correct local IP address. +In case the local peer is responding to a connection setup then any IP address +that is assigned to a local interface will be accepted. +.br +Note that specifying +.B %any +for the local endpoint is not supported by the IKEv1 pluto daemon. + +If +.B %any +is used for the remote endpoint it literally means any IP address. + +Please note that with the usage of wildcards multiple connection descriptions +might match a given incoming connection attempt. The most specific description +is used in that case. +.TP +.B leftallowany +a modifier for +.B left +, making it behave as +.B %any +although a concrete IP address has been assigned. +Recommended for dynamic IP addresses that can be resolved by DynDNS at IPsec +startup or update time. +Acceptable values are +.B yes +and +.B no +(the default). +.TP +.B leftauth +Authentication method to use locally (left) or require from the remote (right) +side. +This parameter is supported in IKEv2 only. Acceptable values are +.B pubkey +for public key authentication (RSA/ECDSA), +.B psk +for pre-shared key authentication and +.B eap +to (require the) use of the Extensible Authentication Protocol. In the case +of +.B eap, +an optional EAP method can be appended. Currently defined methods are +.BR eap-aka , +.BR eap-gtc , +.BR eap-md5 , +.B eap-mschapv2 +and +.BR eap-sim . +Alternatively, IANA assigned EAP method numbers are accepted. Vendor specific +EAP methods are defined in the form +.B eap-type-vendor +.RB "(e.g. " eap-7-12345 ). +.TP +.B leftauth2 +Same as +.BR leftauth , +but defines an additional authentication exchange. IKEv2 supports multiple +authentication rounds using "Multiple Authentication Exchanges" defined +in RFC4739. This allows, for example, separated authentication +of host and user (IKEv2 only). +.TP +.B leftca +the distinguished name of a certificate authority which is required to +lie in the trust path going from the left participant's certificate up +to the root certification authority. +.TP +.B leftca2 +Same as +.B leftca, +but for the second authentication round (IKEv2 only). +.TP +.B leftcert +the path to the left participant's X.509 certificate. The file can be encoded +either in PEM or DER format. OpenPGP certificates are supported as well. +Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP +are accepted. By default +.B leftcert +sets +.B leftid +to the distinguished name of the certificate's subject and +.B leftca +to the distinguished name of the certificate's issuer. +The left participant's ID can be overriden by specifying a +.B leftid +value which must be certified by the certificate, though. +.TP +.B leftcert2 +Same as +.B leftcert, +but for the second authentication round (IKEv2 only). +.TP +.B leftfirewall +whether the left participant is doing forwarding-firewalling +(including masquerading) using iptables for traffic from \fIleftsubnet\fR, +which should be turned off (for traffic to the other subnet) +once the connection is established; +acceptable values are +.B yes +and +.B no +(the default). +May not be used in the same connection description with +.BR leftupdown . +Implemented as a parameter to the default \fBipsec _updown\fR script. +See notes below. +Relevant only locally, other end need not agree on it. + +If one or both security gateways are doing forwarding firewalling +(possibly including masquerading), +and this is specified using the firewall parameters, +tunnels established with IPsec are exempted from it +so that packets can flow unchanged through the tunnels. +(This means that all subnets connected in this manner must have +distinct, non-overlapping subnet address blocks.) +This is done by the default \fBipsec _updown\fR script (see +.IR pluto (8)). + +In situations calling for more control, +it may be preferable for the user to supply his own +.I updown +script, +which makes the appropriate adjustments for his system. +.TP +.B leftgroups +a comma separated list of group names. If the +.B leftgroups +parameter is present then the peer must be a member of at least one +of the groups defined by the parameter. Group membership must be certified +by a valid attribute certificate stored in \fI/etc/ipsec.d/acerts/\fP thas has +been issued to the peer by a trusted Authorization Authority stored in +\fI/etc/ipsec.d/aacerts/\fP. +.br +Attribute certificates are not supported in IKEv2 yet. +.TP +.B lefthostaccess +inserts a pair of INPUT and OUTPUT iptables rules using the default +\fBipsec _updown\fR script, thus allowing access to the host itself +in the case where the host's internal interface is part of the +negotiated client subnet. +Acceptable values are +.B yes +and +.B no +(the default). +.TP +.B leftid +how the left participant should be identified for authentication; +defaults to +.BR left . +Can be an IP address or a fully-qualified domain name preceded by +.B @ +(which is used as a literal string and not resolved). +.TP +.B leftid2 +identity to use for a second authentication for the left participant +(IKEv2 only); defaults to +.BR leftid . +.TP +.B leftikeport +UDP port the left participant uses for IKE communication. Currently supported in +IKEv2 connections only. If unspecified, port 500 is used with the port floating +to 4500 if a NAT is detected or MOBIKE is enabled. Specifying a local IKE port +different from the default additionally requires a socket implementation that +listens to this port. +.TP +.B leftnexthop +this parameter is usually not needed any more because the NETKEY IPsec stack +does not require explicit routing entries for the traffic to be tunneled. If +.B leftsourceip +is used with IKEv1 then +.B leftnexthop +must still be set in order for the source routes to work properly. +.TP +.B leftprotoport +restrict the traffic selector to a single protocol and/or port. +Examples: +.B leftprotoport=tcp/http +or +.B leftprotoport=6/80 +or +.B leftprotoport=udp +.TP +.B leftrsasigkey +the left participant's +public key for RSA signature authentication, +in RFC 2537 format using +.IR ttodata (3) +encoding. +The magic value +.B %none +means the same as not specifying a value (useful to override a default). +The value +.B %cert +(the default) +means that the key is extracted from a certificate. +The identity used for the left participant +must be a specific host, not +.B %any +or another magic value. +.B Caution: +if two connection descriptions +specify different public keys for the same +.BR leftid , +confusion and madness will ensue. +.TP +.B leftsendcert +Accepted values are +.B never +or +.BR no , +.B always +or +.BR yes , +and +.BR ifasked , +the latter meaning that the peer must send a certificate request payload in +order to get a certificate in return. +.TP +.B leftsourceip +The internal source IP to use in a tunnel, also known as virtual IP. If the +value is one of the synonyms +.BR %modeconfig , +.BR %modecfg , +.BR %config , +or +.BR %cfg , +an address is requested from the peer. In IKEv2, a statically defined address +is also requested, since the server may change it. +.TP +.B rightsourceip +The internal source IP to use in a tunnel for the remote peer. If the +value is +.B %config +on the responder side, the initiator must propose an address which is then +echoed back. Also supported are address pools expressed as +\fInetwork\fB/\fInetmask\fR +or the use of an external IP address pool using %\fIpoolname\fR, +where \fIpoolname\fR is the name of the IP address pool used for the lookup. +.TP +.B leftsubnet +private subnet behind the left participant, expressed as +\fInetwork\fB/\fInetmask\fR; +if omitted, essentially assumed to be \fIleft\fB/32\fR, +signifying that the left end of the connection goes to the left participant +only. When using IKEv2, the configured subnet of the peers may differ, the +protocol narrows it to the greatest common subnet. Further, IKEv2 supports +multiple subnets separated by commas. IKEv1 only interprets the first subnet +of such a definition. +.TP +.B leftsubnetwithin +the peer can propose any subnet or single IP address that fits within the +range defined by +.BR leftsubnetwithin. +Not relevant for IKEv2, as subnets are narrowed. +.TP +.B leftupdown +what ``updown'' script to run to adjust routing and/or firewalling +when the status of the connection +changes (default +.BR "ipsec _updown" ). +May include positional parameters separated by white space +(although this requires enclosing the whole string in quotes); +including shell metacharacters is unwise. +See +.IR pluto (8) +for details. +Relevant only locally, other end need not agree on it. IKEv2 uses the updown +script to insert firewall rules only, since routing has been implemented +directly into charon. +.TP +.B lifebytes +the number of bytes transmitted over an IPsec SA before it expires (IKEv2 +only). +.TP +.B lifepackets +the number of packets transmitted over an IPsec SA before it expires (IKEv2 +only). +.TP +.B lifetime +how long a particular instance of a connection +(a set of encryption/authentication keys for user packets) should last, +from successful negotiation to expiry; +acceptable values are an integer optionally followed by +.BR s +(a time in seconds) +or a decimal number followed by +.BR m , +.BR h , +or +.B d +(a time +in minutes, hours, or days respectively) +(default +.BR 1h , +maximum +.BR 24h ). +Normally, the connection is renegotiated (via the keying channel) +before it expires (see +.BR margintime ). +The two ends need not exactly agree on +.BR lifetime , +although if they do not, +there will be some clutter of superseded connections on the end +which thinks the lifetime is longer. +.TP +.B marginbytes +how many bytes before IPsec SA expiry (see +.BR lifebytes ) +should attempts to negotiate a replacement begin (IKEv2 only). +.TP +.B marginpackets +how many packets before IPsec SA expiry (see +.BR lifepackets ) +should attempts to negotiate a replacement begin (IKEv2 only). +.TP +.B margintime +how long before connection expiry or keying-channel expiry +should attempts to +negotiate a replacement +begin; acceptable values as for +.B lifetime +(default +.BR 9m ). +Relevant only locally, other end need not agree on it. +.TP +.B mark +sets an XFRM mark of the form <value>[/<mask>] in the inbound and outbound +IPsec SAs and policies (IKEv2 only). If the mask is missing then a default +mask of +.B 0xffffffff +is assumed. +.TP +.B mark_in +sets an XFRM mark of the form <value>[/<mask>] in the inbound IPsec SA and policy +(IKEv2 only). If the mask is missing then a default mask of +.B 0xffffffff +is assumed. +.TP +.B mark_out +sets an XFRM mark of the form <value>[/<mask>] in the outbound IPsec SA and policy +(IKEv2 only). If the mask is missing then a default mask of +.B 0xffffffff +is assumed. +.TP +.B mobike +enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted values are +.B yes +(the default) and +.BR no . +If set to +.BR no , +the IKEv2 charon daemon will not actively propose MOBIKE as initiator and +ignore the MOBIKE_SUPPORTED notify as responder. +.TP +.B modeconfig +defines which mode is used to assign a virtual IP. +Accepted values are +.B push +and +.B pull +(the default). +Currently relevant for IKEv1 only since IKEv2 always uses the configuration +payload in pull mode. Cisco VPN gateways usually operate in +.B push +mode. +.TP +.B pfs +whether Perfect Forward Secrecy of keys is desired on the connection's +keying channel +(with PFS, penetration of the key-exchange protocol +does not compromise keys negotiated earlier); +acceptable values are +.B yes +(the default) +and +.BR no. +IKEv2 always uses PFS for IKE_SA rekeying whereas for CHILD_SA rekeying +PFS is enforced by defining a Diffie-Hellman modp group in the +.B esp +parameter. +.TP +.B pfsgroup +defines a Diffie-Hellman group for perfect forward secrecy in IKEv1 Quick Mode +differing from the DH group used for IKEv1 Main Mode (IKEv1 only). +.TP +.B reauth +whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1, +reauthentication is always done. In IKEv2, a value of +.B no +rekeys without uninstalling the IPsec SAs, a value of +.B yes +(the default) creates a new IKE_SA from scratch and tries to recreate +all IPsec SAs. +.TP +.B rekey +whether a connection should be renegotiated when it is about to expire; +acceptable values are +.B yes +(the default) +and +.BR no . +The two ends need not agree, but while a value of +.B no +prevents pluto/charon from requesting renegotiation, +it does not prevent responding to renegotiation requested from the other end, +so +.B no +will be largely ineffective unless both ends agree on it. +.TP +.B rekeyfuzz +maximum percentage by which +.BR marginbytes , +.B marginpackets +and +.B margintime +should be randomly increased to randomize rekeying intervals +(important for hosts with many connections); +acceptable values are an integer, +which may exceed 100, +followed by a `%' +(defaults to +.BR 100% ). +The value of +.BR marginTYPE , +after this random increase, +must not exceed +.B lifeTYPE +(where TYPE is one of +.IR bytes , +.I packets +or +.IR time ). +The value +.B 0% +will suppress randomization. +Relevant only locally, other end need not agree on it. +.TP +.B rekeymargin +synonym for +.BR margintime . +.TP +.B reqid +sets the reqid for a given connection to a pre-configured fixed value (IKEv2 only). +.TP +.B type +the type of the connection; currently the accepted values +are +.B tunnel +(the default) +signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel; +.BR transport , +signifying host-to-host transport mode; +.BR transport_proxy , +signifying the special Mobile IPv6 transport proxy mode; +.BR passthrough , +signifying that no IPsec processing should be done at all; +.BR drop , +signifying that packets should be discarded; and +.BR reject , +signifying that packets should be discarded and a diagnostic ICMP returned. +The IKEv2 daemon charon currently supports +.BR tunnel , +.BR transport , +and +.BR tunnel_proxy +connection types, only. +.TP +.B xauth +specifies the role in the XAUTH protocol if activated by +.B authby=xauthpsk +or +.B authby=xauthrsasig. +Accepted values are +.B server +and +.B client +(the default). + +.SS "CONN PARAMETERS: IKEv2 MEDIATION EXTENSION" +The following parameters are relevant to IKEv2 Mediation Extension +operation only. +.TP 14 +.B mediation +whether this connection is a mediation connection, ie. whether this +connection is used to mediate other connections. Mediation connections +create no child SA. Acceptable values are +.B no +(the default) and +.BR yes . +.TP +.B mediated_by +the name of the connection to mediate this connection through. If given, +the connection will be mediated through the named mediation connection. +The mediation connection must set +.BR mediation=yes . +.TP +.B me_peerid +ID as which the peer is known to the mediation server, ie. which the other +end of this connection uses as its +.B leftid +on its connection to the mediation server. This is the ID we request the +mediation server to mediate us with. If +.B me_peerid +is not given, the +.B rightid +of this connection will be used as peer ID. + +.SH "CA SECTIONS" +This are optional sections that can be used to assign special +parameters to a Certification Authority (CA). +.TP 10 +.B auto +currently can have either the value +.B ignore +or +.B add +. +.TP +.B cacert +defines a path to the CA certificate either relative to +\fI/etc/ipsec.d/cacerts\fP or as an absolute path. +.TP +.B crluri +defines a CRL distribution point (ldap, http, or file URI) +.TP +.B crluri1 +synonym for +.B crluri. +.TP +.B crluri2 +defines an alternative CRL distribution point (ldap, http, or file URI) +.TP +.B ldaphost +defines an ldap host. Currently used by IKEv1 only. +.TP +.B ocspuri +defines an OCSP URI. +.TP +.B ocspuri1 +synonym for +.B ocspuri. +.TP +.B ocspuri2 +defines an alternative OCSP URI. Currently used by IKEv2 only. +.TP +.B certuribase +defines the base URI for the Hash and URL feature supported by IKEv2. +Instead of exchanging complete certificates, IKEv2 allows to send an URI +that resolves to the DER encoded certificate. The certificate URIs are built +by appending the SHA1 hash of the DER encoded certificates to this base URI. +.SH "CONFIG SECTIONS" +At present, the only +.B config +section known to the IPsec software is the one named +.BR setup , +which contains information used when the software is being started. +Here's an example: +.PP +.ne 8 +.nf +.ft B +.ta 1c +config setup + plutodebug=all + crlcheckinterval=10m + strictcrlpolicy=yes +.ft +.fi +.PP +Parameters are optional unless marked ``(required)''. +The currently-accepted +.I parameter +names in a +.B config +.B setup +section affecting both daemons are: +.TP 14 +.B cachecrls +certificate revocation lists (CRLs) fetched via http or ldap will be cached in +\fI/etc/ipsec.d/crls/\fR under a unique file name derived from the certification +authority's public key. +Accepted values are +.B yes +and +.B no +(the default). +.TP +.B charonstart +whether to start the IKEv2 Charon daemon or not. +Accepted values are +.B yes +or +.BR no . +The default is +.B yes +if starter was compiled with IKEv2 support. +.TP +.B dumpdir +in what directory should things started by \fBipsec starter\fR +(notably the Pluto and Charon daemons) be allowed to dump core? +The empty value (the default) means they are not +allowed to. +This feature is currently not yet supported by \fBipsec starter\fR. +.TP +.B plutostart +whether to start the IKEv1 Pluto daemon or not. +Accepted values are +.B yes +or +.BR no . +The default is +.B yes +if starter was compiled with IKEv1 support. +.TP +.B strictcrlpolicy +defines if a fresh CRL must be available in order for the peer authentication based +on RSA signatures to succeed. +Accepted values are +.B yes +and +.B no +(the default). +IKEv2 additionally recognizes +.B ifuri +which reverts to +.B yes +if at least one CRL URI is defined and to +.B no +if no URI is known. +.TP +.B uniqueids +whether a particular participant ID should be kept unique, +with any new (automatically keyed) +connection using an ID from a different IP address +deemed to replace all old ones using that ID; +acceptable values are +.B yes +(the default) +and +.BR no . +Participant IDs normally \fIare\fR unique, +so a new (automatically-keyed) connection using the same ID is +almost invariably intended to replace an old one. +The IKEv2 daemon also accepts the value +.B replace +wich is identical to +.B yes +and the value +.B keep +to reject new IKE_SA setups and keep the duplicate established earlier. +.PP +The following +.B config section +parameters are used by the IKEv1 Pluto daemon only: +.TP +.B crlcheckinterval +interval in seconds. CRL fetching is enabled if the value is greater than zero. +Asynchronous, periodic checking for fresh CRLs is currently done by the +IKEv1 Pluto daemon only. +.TP +.B keep_alive +interval in seconds between NAT keep alive packets, the default being 20 seconds. +.TP +.B nat_traversal +activates NAT traversal by accepting source ISAKMP ports different from udp/500 and +being able of floating to udp/4500 if a NAT situation is detected. +Accepted values are +.B yes +and +.B no +(the default). +Used by IKEv1 only, NAT traversal always being active in IKEv2. +.TP +.B nocrsend +no certificate request payloads will be sent. +Accepted values are +.B yes +and +.B no +(the default). +.TP +.B pkcs11initargs +non-standard argument string for PKCS#11 C_Initialize() function; +required by NSS softoken. +.TP +.B pkcs11module +defines the path to a dynamically loadable PKCS #11 library. +.TP +.B pkcs11keepstate +PKCS #11 login sessions will be kept during the whole lifetime of the keying +daemon. Useful with pin-pad smart card readers. +Accepted values are +.B yes +and +.B no +(the default). +.TP +.B pkcs11proxy +Pluto will act as a PKCS #11 proxy accessible via the whack interface. +Accepted values are +.B yes +and +.B no +(the default). +.TP +.B plutodebug +how much Pluto debugging output should be logged. +An empty value, +or the magic value +.BR none , +means no debugging output (the default). +The magic value +.B all +means full output. +Otherwise only the specified types of output +(a quoted list, names without the +.B \-\-debug\- +prefix, +separated by white space) are enabled; +for details on available debugging types, see +.IR pluto (8). +.TP +.B plutostderrlog +Pluto will not use syslog, but rather log to stderr, and redirect stderr +to the argument file. +.TP +.B postpluto +shell command to run after starting Pluto +(e.g., to remove a decrypted copy of the +.I ipsec.secrets +file). +It's run in a very simple way; +complexities like I/O redirection are best hidden within a script. +Any output is redirected for logging, +so running interactive commands is difficult unless they use +.I /dev/tty +or equivalent for their interaction. +Default is none. +.TP +.B prepluto +shell command to run before starting Pluto +(e.g., to decrypt an encrypted copy of the +.I ipsec.secrets +file). +It's run in a very simple way; +complexities like I/O redirection are best hidden within a script. +Any output is redirected for logging, +so running interactive commands is difficult unless they use +.I /dev/tty +or equivalent for their interaction. +Default is none. +.TP +.B virtual_private +defines private networks using a wildcard notation. +.PP +The following +.B config section +parameters are used by the IKEv2 Charon daemon only: +.TP +.B charondebug +how much Charon debugging output should be logged. +A comma separated list containing type level/pairs may +be specified, e.g: +.B dmn 3, ike 1, net -1. +Acceptable values for types are +.B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib +and the level is one of +.B -1, 0, 1, 2, 3, 4 +(for silent, audit, control, controlmore, raw, private). +.PP +The following +.B config section +parameters only make sense if the KLIPS IPsec stack +is used instead of the default NETKEY stack of the Linux 2.6 kernel: +.TP +.B fragicmp +whether a tunnel's need to fragment a packet should be reported +back with an ICMP message, +in an attempt to make the sender lower his PMTU estimate; +acceptable values are +.B yes +(the default) +and +.BR no . +.TP +.B hidetos +whether a tunnel packet's TOS field should be set to +.B 0 +rather than copied from the user packet inside; +acceptable values are +.B yes +(the default) +and +.BR no +.TP +.B interfaces +virtual and physical interfaces for IPsec to use: +a single +\fIvirtual\fB=\fIphysical\fR pair, a (quoted!) list of pairs separated +by white space, or +.BR %none . +One of the pairs may be written as +.BR %defaultroute , +which means: find the interface \fId\fR that the default route points to, +and then act as if the value was ``\fBipsec0=\fId\fR''. +.B %defaultroute +is the default; +.B %none +must be used to denote no interfaces. +.TP +.B overridemtu +value that the MTU of the ipsec\fIn\fR interface(s) should be set to, +overriding IPsec's (large) default. +.SH FILES +.nf +/etc/ipsec.conf +/etc/ipsec.d/aacerts +/etc/ipsec.d/acerts +/etc/ipsec.d/cacerts +/etc/ipsec.d/certs +/etc/ipsec.d/crls + +.SH SEE ALSO +ipsec(8), pluto(8), starter(8) +.SH HISTORY +Originally written for the FreeS/WAN project by Henry Spencer. +Updated and extended for the strongSwan project <http://www.strongswan.org> by +Tobias Brunner, Andreas Steffen and Martin Willi. +.SH BUGS +.PP +If conns are to be added before DNS is available, \fBleft=\fP\fIFQDN\fP +will fail. |