Moved man pages for config files to a separate directory.

4 files changed, 1526 insertions, 0 deletions

diff --git a/man/.gitignore b/man/.gitignore
new file mode 100644
index 000000000..cf55e342f
--- /dev/null
+++ b/man/.gitignore
@@ -0,0 +1,2 @@
+ipsec.conf.5
+ipsec.secrets.5
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644
index 000000000..f57f12477
--- /dev/null
+++ b/man/Makefile.am
@@ -0,0 +1,11 @@
+dist_man_MANS = ipsec.conf.5 ipsec.secrets.5
+EXTRA_DIST = ipsec.conf.5.in ipsec.secrets.5.in
+CLEANFILES = ipsec.conf.5 ipsec.secrets.5
+
+SUFFIXES = .in
+
+.in:
+	sed \
+	-e "s:@IPSEC_VERSION@:$(PACKAGE_VERSION):" \
+	$(srcdir)/$@.in > $@
+
diff --git a/man/ipsec.conf.5.in b/man/ipsec.conf.5.in
new file mode 100644
index 000000000..631a1ef7c
--- /dev/null
+++ b/man/ipsec.conf.5.in
@@ -0,0 +1,1336 @@
+.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 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
+.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 ,
+.BR eap-tls ,
+.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. 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. 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. 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.
+.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.
diff --git a/man/ipsec.secrets.5.in b/man/ipsec.secrets.5.in
new file mode 100644
index 000000000..5292a9061
--- /dev/null
+++ b/man/ipsec.secrets.5.in
@@ -0,0 +1,177 @@
+.TH IPSEC.SECRETS 5 "2010-05-30" "@IPSEC_VERSION@" "strongSwan"
+.SH NAME
+ipsec.secrets \- secrets for IKE/IPsec authentication
+.SH DESCRIPTION
+The file \fIipsec.secrets\fP holds a table of secrets.
+These secrets are used by the strongSwan Internet Key Exchange (IKE) daemons
+pluto (IKEv1) and charon (IKEv2) to authenticate other hosts.
+.LP
+It is vital that these secrets be protected.  The file should be owned
+by the super-user,
+and its permissions should be set to block all access by others.
+.LP
+The file is a sequence of entries and include directives.
+Here is an example.
+.LP
+.RS
+.nf
+# /etc/ipsec.secrets - strongSwan IPsec secrets file
+192.168.0.1 %any : PSK "v+NkxY9LLZvwj4qCC2o/gGrWDF2d21jL"
+
+: RSA moonKey.pem
+
+alice@strongswan.org : EAP "x3.dEhgN"
+
+carol : XAUTH "4iChxLT3"
+
+dave  : XAUTH "ryftzG4A"
+
+# get secrets from other files
+include ipsec.*.secrets
+.fi
+.RE
+.LP
+Each entry in the file is a list of optional ID selectors, followed by a secret.
+The two parts are separated by a colon (\fB:\fP) that is surrounded
+by whitespace. If no ID selectors are specified the line must start with a
+colon.
+.LP
+A selector is an IP address, a Fully Qualified Domain Name, user@FQDN,
+\fB%any\fP or \fB%any6\fP (other kinds may come).  An IP address may be written
+in the familiar dotted quad form or as a domain name to be looked up
+when the file is loaded.
+In many cases it is a bad idea to use domain names because
+the name server may not be running or may be insecure.  To denote a
+Fully Qualified Domain Name (as opposed to an IP address denoted by
+its domain name), precede the name with an at sign (\fB@\fP).
+.LP
+Matching IDs with selectors is fairly straightforward: they have to be
+equal.  In the case of a ``Road Warrior'' connection, if an equal
+match is not found for the Peer's ID, and it is in the form of an IP
+address, a selector of \fB%any\fP will match the peer's IP address if IPV4
+and \fB%any6\fP will match a the peer's IP address if IPV6.
+Currently, the obsolete notation \fB0.0.0.0\fP may be used in place of
+\fB%any\fP.
+.LP
+In IKEv1 an additional complexity
+arises in the case of authentication by preshared secret: the
+responder will need to look up the secret before the Peer's ID payload has
+been decoded, so the ID used will be the IP address.
+.LP
+To authenticate a connection between two hosts, the entry that most
+specifically matches the host and peer IDs is used.  An entry with no
+selectors will match any host and peer.  More specifically, an entry with one
+selector will match a host and peer if the selector matches the host's ID (the
+peer isn't considered).  Still more specifically, an entry with multiple
+selectors will match a host and peer if the host ID and peer ID each match one
+of the selectors.  If the key is for an asymmetric authentication technique
+(i.e. a public key system such as RSA), an entry with multiple selectors will
+match a host and peer even if only the host ID matches a selector (it is
+presumed that the selectors are all identities of the host).
+It is acceptable for two entries to be the best match as
+long as they agree about the secret or private key.
+.LP
+Authentication by preshared secret requires that both systems find the
+identical secret (the secret is not actually transmitted by the IKE
+protocol).  If both the host and peer appear in the selector list, the
+same entry will be suitable for both systems so verbatim copying
+between systems can be used.  This naturally extends to larger groups
+sharing the same secret.  Thus multiple-selector entries are best for PSK
+authentication.
+.LP
+Authentication by public key systems such as RSA requires that each host
+have its own private key.  A host could reasonably use a different private keys
+for different interfaces and for different peers.  But it would not
+be normal to share entries between systems.  Thus thus no-selector and
+one-selector forms of entry often make sense for public key authentication.
+.LP
+The key part of an entry must start with a token indicating the kind of
+key.  The following types of secrets are currently supported:
+.TP
+.B PSK
+defines a pre-shared key
+.TP
+.B RSA
+defines an RSA private key
+.TP
+.B ECDSA
+defines an ECDSA private key
+.TP
+.B EAP
+defines EAP credentials
+.TP
+.B XAUTH
+defines XAUTH credentials
+.TP
+.B PIN
+defines a smartcard PIN
+.LP
+Details on each type of secret are given below.
+.LP
+Whitespace at the end of a line is ignored. At the start of a line or
+after whitespace, \fB#\fP and the following text up to the end of the
+line is treated as a comment.
+.LP
+An include directive causes the contents of the named file to be processed
+before continuing with the current file.  The filename is subject to
+``globbing'' as in \fIsh\fP(1), so every file with a matching name
+is processed.  Includes may be nested to a modest
+depth (10, currently).  If the filename doesn't start with a \fB/\fP, the
+directory containing the current file is prepended to the name.  The
+include directive is a line that starts with the word \fBinclude\fP,
+followed by whitespace, followed by the filename (which must not contain
+whitespace).
+.SS TYPES OF SECRETS
+.TP
+.B [ <selectors> ] : PSK <secret>
+A preshared secret is most conveniently represented as a sequence of
+characters, delimited by double-quote characters (\fB"\fP).
+The sequence cannot contain a newline or double-quote.
+Strictly speaking, the secret is actually the sequence
+of bytes that is used in the file to represent the sequence of
+characters (excluding the delimiters).
+.TP
+.B [ <selectors> ] : RSA <private key file> [ <passphrase> | %prompt ]
+.TQ
+.B [ <selectors> ] : ECDSA <private key file> [ <passphrase> | %prompt ]
+For the private key file both absolute paths or paths relative to
+\fI/etc/ipsec.d/private\fP are accepted. If the private key file is
+encrypted, the \fIpassphrase\fP must be defined. Instead of a passphrase
+.B %prompt
+can be used which then causes the daemons to ask the user for the password
+whenever it is required to decrypt the key.
+.TP
+.B <user id> : EAP <secret>
+As with \fBPSK\fP secrets the \fIsecret\fP is a sequence of characters,
+delimited by double-quote characters (\fB"\fP).
+.br
+\fBEAP\fP secrets are IKEv2 only.
+.TP
+.B [ <servername> ] <username> : XAUTH <password>
+\fBXAUTH\fP secrets are IKEv1 only.
+.TP
+.B : PIN <smartcard selector> <pin code> | %prompt
+IKEv1 uses the format
+.B "%smartcard[<slot nr>[:<key id>]]"
+to specify the smartcard selector (e.g. %smartcard1:50).
+The IKEv2 daemon supports multiple modules with the format
+.B "%smartcard[<slot nr>[@<module>]]:<keyid>"
+, but always requires a keyid to uniquely select the correct key. Instead of
+specifying the pin code statically,
+.B %prompt
+can be specified, which causes the daemons to ask the user for the pin code.
+.LP
+
+.SH FILES
+/etc/ipsec.secrets
+.SH SEE ALSO
+\fIipsec.conf\fP(5),
+\fIipsec\fP(8)
+.br
+.SH HISTORY
+Originally written for the FreeS/WAN project by D. Hugh Redelmeier.
+Updated and extended for the strongSwan project <http://www.strongswan.org> by
+Tobias Brunner and Andreas Steffen.
+.SH BUGS
+If an ID is \fB0.0.0.0\fP, it will match \fB%any\fP;
+if it is \fB0::0\fP, it will match \fB%any6\fP.