Moved man pages for config files to a separate directory.
authorTobias Brunner <tobias@strongswan.org>
Thu, 9 Sep 2010 11:15:36 +0000 (13:15 +0200)
committerTobias Brunner <tobias@strongswan.org>
Fri, 10 Sep 2010 10:01:19 +0000 (12:01 +0200)
12 files changed:
Makefile.am
configure.in
man/.gitignore [new file with mode: 0644]
man/Makefile.am [new file with mode: 0644]
man/ipsec.conf.5.in [new file with mode: 0644]
man/ipsec.secrets.5.in [new file with mode: 0644]
src/pluto/.gitignore
src/pluto/Makefile.am
src/pluto/ipsec.secrets.5.in [deleted file]
src/starter/.gitignore
src/starter/Makefile.am
src/starter/ipsec.conf.5.in [deleted file]

index af0465f..cba5048 100644 (file)
@@ -1,4 +1,4 @@
-SUBDIRS = src testing
+SUBDIRS = src man testing
 
 if USE_SCRIPTS
   SUBDIRS += scripts
index 0632027..77c2271 100644 (file)
@@ -920,6 +920,7 @@ dnl ==============================
 
 AC_OUTPUT(
        Makefile
+       man/Makefile
        src/Makefile
        src/include/Makefile
        src/libstrongswan/Makefile
diff --git a/man/.gitignore b/man/.gitignore
new file mode 100644 (file)
index 0000000..cf55e34
--- /dev/null
@@ -0,0 +1,2 @@
+ipsec.conf.5
+ipsec.secrets.5
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644 (file)
index 0000000..f57f124
--- /dev/null
@@ -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 (file)
index 0000000..631a1ef
--- /dev/null
@@ -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 (file)
index 0000000..5292a90
--- /dev/null
@@ -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.
index 7c2ab2a..8aa8745 100644 (file)
@@ -1,3 +1,2 @@
 pluto
 _pluto_adns
-ipsec.secrets.5
index 40b1095..934b11a 100644 (file)
@@ -88,9 +88,7 @@ _pluto_adns_LDADD = \
 $(LIBFREESWANDIR)/libfreeswan.a \
 -lresolv $(DLLIB)
 
-CLEANFILES = ipsec.secrets.5
-dist_man_MANS = pluto.8 ipsec.secrets.5
-EXTRA_DIST = ipsec.secrets.5.in
+dist_man_MANS = pluto.8
 
 # compile options
 #################
@@ -137,8 +135,3 @@ if USE_XAUTH
   SUBDIRS += plugins/xauth
 endif
 
-ipsec.secrets.5 : ipsec.secrets.5.in
-       sed \
-       -e "s:@IPSEC_VERSION@:$(PACKAGE_VERSION):" \
-       $(srcdir)/$@.in > $@
-
diff --git a/src/pluto/ipsec.secrets.5.in b/src/pluto/ipsec.secrets.5.in
deleted file mode 100644 (file)
index 5292a90..0000000
+++ /dev/null
@@ -1,177 +0,0 @@
-.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.
index 9b73f4c..c1900a3 100644 (file)
@@ -1,3 +1,2 @@
 starter
 y.output
-ipsec.conf.5
index 0bc7fb4..75297f7 100644 (file)
@@ -24,9 +24,8 @@ AM_CFLAGS = \
 -DDEBUG
 
 starter_LDADD = defs.o $(top_builddir)/src/libfreeswan/libfreeswan.a $(top_builddir)/src/libstrongswan/libstrongswan.la $(SOCKLIB)
-EXTRA_DIST = parser.l parser.y keywords.txt ipsec.conf ipsec.conf.5.in
-dist_man_MANS = ipsec.conf.5 starter.8
-CLEANFILES = ipsec.conf.5
+EXTRA_DIST = parser.l parser.y keywords.txt ipsec.conf
+dist_man_MANS = starter.8
 MAINTAINERCLEANFILES = lex.yy.c y.tab.c y.tab.h keywords.c
 
 PLUTODIR=$(top_srcdir)/src/pluto
@@ -44,11 +43,6 @@ if USE_LOAD_WARNING
   AM_CFLAGS += -DLOAD_WARNING
 endif
 
-ipsec.conf.5:  ipsec.conf.5.in
-               sed \
-               -e "s:@IPSEC_VERSION@:$(PACKAGE_VERSION):" \
-               $(srcdir)/$@.in > $@
-
 lex.yy.c:      $(srcdir)/parser.l $(srcdir)/parser.y $(srcdir)/parser.h y.tab.h
                $(LEX) $(srcdir)/parser.l
 
diff --git a/src/starter/ipsec.conf.5.in b/src/starter/ipsec.conf.5.in
deleted file mode 100644 (file)
index 631a1ef..0000000
+++ /dev/null
@@ -1,1336 +0,0 @@
-.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.