Move README to README.md so it gets evaluated as Markdown

1 files changed, 1514 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 000000000..aa40fe394
--- /dev/null
+++ b/README.md
@@ -0,0 +1,1514 @@
+                 ----------------------------
+                  strongSwan - Configuration
+                 ----------------------------
+
+
+Contents
+--------
+
+   1. Overview
+   2. Quickstart
+    2.1 Site-to-Site case
+    2.2 Host-to-Host case
+    2.3 Roadwarrior case
+    2.4 Roadwarrior case with virtual IP
+   3. Generating X.509 certificates and CRLs
+    3.1 Generating a CA certificate
+    3.2 Generating a host or user certificate
+    3.3 Generating a CRL
+    3.4 Revoking a certificate
+   4. Configuring the connections - ipsec.conf
+    4.1 Configuring my side
+    4.2 Multiple certificates
+    4.3 Configuring the peer side using CA certificates
+    4.4 Handling Virtual IPs and wildcard subnets
+    4.5 Protocol and port selectors
+    4.6 IPsec policies based on wildcards
+    4.7 IPsec policies based on CA certificates
+   5. Configuring certificates and CRLs
+    5.1 Installing CA certificates
+    5.2 Installing optional Certificate Revocation Lists (CRLs)
+    5.3 Dynamic update of certificates and CRLs
+    5.4 Local caching of CRLs
+    5.5 Online Certificate Status Protocol (OCSP)
+    5.6 CRL policy
+    5.7 Configuring the peer side using locally stored certificates
+   6. Configuring the private keys - ipsec.secrets
+    6.1 Loading private key files in PKCS#1 format
+    6.2 Entering passphrases interactively
+    6.3 Multiple private keys
+   7. Configuring CA properties - ipsec.conf
+   8. Monitoring functions
+   9. Firewall support functions
+       9.1 Environment variables in the updown script
+       9.2 Automatic insertion and deletion of iptables firewall rules
+
+
+1. Overview
+   --------
+
+strongSwan is an OpenSource IPsec solution for Unix based operating systems.
+
+This document is just a short introduction, for more detailed information
+consult the manual pages and our wiki:
+
+    http://wiki.strongswan.org
+
+
+2. Quickstart
+   ----------
+
+In the following examples we assume for reasons of clarity that left designates
+the local host and that right is the remote host.  Certificates for users,
+hosts and gateways are issued by a fictitious strongSwan CA.  How to generate
+private keys and certificates using OpenSSL or the strongSwan PKI tool will be
+explained in section 3.  The CA certificate "strongswanCert.pem" must be present
+on all VPN end points in order to be able to authenticate the peers.
+
+
+2.1 Site-to-site case
+    -----------------
+
+In this scenario two security gateways moon and sun will connect the
+two subnets moon-net and sun-net with each other through a VPN tunnel
+set up between the two gateways:
+
+    10.1.0.0/16 -- | 192.168.0.1 | === | 192.168.0.2 | -- 10.2.0.0/16
+      moon-net          moon                 sun           sun-net
+
+Configuration on gateway moon:
+
+    /etc/ipsec.d/cacerts/strongswanCert.pem
+
+    /etc/ipsec.d/certs/moonCert.pem
+
+    /etc/ipsec.secrets:
+
+        : RSA moonKey.pem "<optional passphrase>"
+
+    /etc/ipsec.conf:
+
+        conn net-net
+            leftsubnet=10.1.0.0/16
+            leftcert=moonCert.pem
+            right=192.168.0.2
+            rightsubnet=10.2.0.0/16
+            rightid="C=CH, O=strongSwan, CN=sun.strongswan.org"
+            auto=start
+
+Configuration on gateway sun:
+
+    /etc/ipsec.d/cacerts/strongswanCert.pem
+
+    /etc/ipsec.d/certs/sunCert.pem
+
+    /etc/ipsec.secrets:
+
+        : RSA sunKey.pem "<optional passphrase>"
+
+    /etc/ipsec.conf:
+
+        conn net-net
+            leftsubnet=10.2.0.0/16
+            leftcert=sunCert.pem
+            right=192.168.0.1
+            rightsubnet=10.1.0.0/16
+            rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
+            auto=start
+
+
+2.2 Host-to-host case
+    -----------------
+
+This is a setup between two single hosts which don't have a subnet behind
+them.  Although IPsec transport mode would be sufficient for host-to-host
+connections we will use the default IPsec tunnel mode.
+
+    | 192.168.0.1 | === | 192.168.0.2 |
+         moon                sun
+
+Configuration on host moon:
+
+    /etc/ipsec.d/cacerts/strongswanCert.pem
+
+    /etc/ipsec.d/certs/moonCert.pem
+
+    /etc/ipsec.secrets:
+
+        : RSA moonKey.pem "<optional passphrase>"
+
+    /etc/ipsec.conf:
+
+        conn host-host
+            leftcert=moonCert.pem
+            right=192.168.0.2
+            rightid="C=CH, O=strongSwan, CN=sun.strongswan.org"
+            auto=start
+
+Configuration on host sun:
+
+    /etc/ipsec.d/cacerts/strongswanCert.pem
+
+    /etc/ipsec.d/certs/sunCert.pem
+
+    /etc/ipsec.secrets:
+
+        : RSA sunKey.pem "<optional passphrase>"
+
+    /etc/ipsec.conf:
+
+        conn host-host
+            leftcert=sunCert.pem
+            right=192.168.0.1
+            rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
+            auto=start
+
+
+2.3 Roadwarrior case
+    ----------------
+
+This is a very common case where a strongSwan gateway serves an arbitrary
+number of remote VPN clients usually having dynamic IP addresses.
+
+    10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x |
+      moon-net          moon              carol
+
+Configuration on gateway moon:
+
+    /etc/ipsec.d/cacerts/strongswanCert.pem
+
+    /etc/ipsec.d/certs/moonCert.pem
+
+    /etc/ipsec.secrets:
+
+        : RSA moonKey.pem "<optional passphrase>"
+
+    /etc/ipsec.conf:
+
+        conn rw
+            leftsubnet=10.1.0.0/16
+            leftcert=moonCert.pem
+            right=%any
+            auto=add
+
+Configuration on roadwarrior carol:
+
+    /etc/ipsec.d/cacerts/strongswanCert.pem
+
+    /etc/ipsec.d/certs/carolCert.pem
+
+    /etc/ipsec.secrets:
+
+        : RSA carolKey.pem "<optional passphrase>"
+
+    /etc/ipsec.conf:
+
+        conn home
+            leftcert=carolCert.pem
+            right=192.168.0.1
+            rightsubnet=10.1.0.0/16
+            rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
+            auto=start
+
+
+2.6 Roadwarrior case with virtual IP
+    --------------------------------
+
+Roadwarriors usually have dynamic IP addresses assigned by the ISP they are
+currently attached to.  In order to simplify the routing from moon-net back
+to the remote access client carol it would be desirable if the roadwarrior had
+an inner IP address chosen from a pre-assigned pool.
+
+    10.1.0.0/16 -- | 192.168.0.1 | === | x.x.x.x | -- 10.3.0.1
+      moon-net          moon              carol       virtual IP
+
+In our example the virtual IP address is chosen from the address pool
+10.3.0.0/16 which can be configured by adding the parameter
+
+    rightsourceip=10.3.0.0/16
+
+to the gateway's ipsec.conf.  To request an IP address from this pool a
+roadwarrior can use IKEv1 mode config or IKEv2 configuration payloads.
+The configuration for both is the same
+
+    leftsourceip=%config
+
+Configuration on gateway moon:
+
+    /etc/ipsec.d/cacerts/strongswanCert.pem
+
+    /etc/ipsec.d/certs/moonCert.pem
+
+    /etc/ipsec.secrets:
+
+        : RSA moonKey.pem "<optional passphrase>"
+
+    /etc/ipsec.conf:
+
+        conn rw
+            leftsubnet=10.1.0.0/16
+            leftcert=moonCert.pem
+            right=%any
+            rightsourceip=10.3.0.0/16
+            auto=add
+
+Configuration on roadwarrior carol:
+
+    /etc/ipsec.d/cacerts/strongswanCert.pem
+
+    /etc/ipsec.d/certs/carolCert.pem
+
+    /etc/ipsec.secrets:
+
+        : RSA carolKey.pem "<optional passphrase>"
+
+    /etc/ipsec.conf:
+
+        conn home
+            leftsourceip=%config
+            leftcert=carolCert.pem
+            right=192.168.0.1
+            rightsubnet=10.1.0.0/16
+            rightid="C=CH, O=strongSwan, CN=moon.strongswan.org"
+            auto=start
+
+
+3. Generating certificates and CRLs
+   --------------------------------
+
+This section is not a full-blown tutorial on how to use OpenSSL or the
+strongSwan PKI tool.  It just lists a few points that are relevant if you want
+to generate your own certificates and CRLs for use with strongSwan.
+
+
+3.1 Generating a CA certificate
+    ---------------------------
+
+The OpenSSL statement
+
+    openssl req -x509 -days 1460 -newkey rsa:4096 \
+                -keyout strongswanKey.pem -out strongswanCert.pem
+
+creates a 4096 bit RSA private key strongswanKey.pem and a self-signed CA
+certificate strongswanCert.pem with a validity of 4 years (1460 days).
+
+    openssl x509 -in cert.pem -noout -text
+
+lists the properties of  a X.509 certificate cert.pem. It allows you to verify
+whether the configuration defaults in openssl.cnf have been inserted correctly.
+
+If you prefer the CA certificate to be in binary DER format then the following
+command achieves this transformation:
+
+     openssl x509 -in strongswanCert.pem -outform DER -out strongswanCert.der
+
+The statements
+
+    ipsec pki --gen -s 4096 > strongswanKey.der
+    ipsec pki --self --ca --lifetime 1460 --in strongswanKey.der \
+              --dn "C=CH, O=strongSwan, CN=strongSwan Root CA" \
+              > strongswanCert.der
+    ipsec pki --print --in strongswanCert.der
+
+achieve about the same with the strongSwan PKI tool.  Unlike OpenSSL the tool
+stores keys and certificates in the binary DER format by default.  The --outform
+option may be used to write PEM encoded files.
+
+The directory /etc/ipsec.d/cacerts contains all required CA certificates either
+in binary DER or in base64 PEM format, irrespective of the file suffix the
+correct format will be determined.
+
+
+3.2 Generating a host or user certificate
+    -------------------------------------
+
+The OpenSSL statement
+
+     openssl req -newkey rsa:2048 -keyout hostKey.pem \
+                 -out hostReq.pem
+
+generates a 2048 bit RSA private key hostKey.pem and a certificate request
+hostReq.pem which has to be signed by the CA.
+
+If you want to add a subjectAltName field to the host certificate you must edit
+the OpenSSL configuration file openssl.cnf and add the following line in the
+[ usr_cert ] section:
+
+     subjectAltName=DNS:moon.strongswan.org
+
+if you want to identify the host by its Fully Qualified Domain Name (FQDN), or
+
+     subjectAltName=IP:192.168.0.1
+
+if you want the ID to be of type IPV4_ADDR. Of course you could include both
+ID types with
+
+     subjectAltName=DNS:moon.strongswan.org,IP:192.168.0.1
+
+but the use of an IP address for the identification of a host should be
+discouraged anyway.
+
+For user certificates the appropriate ID type is RFC822_ADDR which can be
+specified as
+
+     subjectAltName=email:carol@strongswan.org
+
+or if the user's e-mail address is part of the subject's distinguished name
+
+     subjectAltName=email:copy
+
+Now the certificate request can be signed by the CA with the command
+
+     openssl ca -in hostReq.pem -days 730 -out hostCert.pem -notext
+
+If you omit the -days option then the default_days value (365 days) specified
+in openssl.cnf is used.  The -notext option avoids that a human readable
+listing of the certificate is prepended to the base64 encoded certificate
+body.
+
+If you want to use the dynamic CRL fetching feature described in section 4.7
+then you may include one or several crlDistributionPoints in your end
+certificates.  This can be done in the [ usr_cert ] section of the openssl.cnf
+configuration file:
+
+    crlDistributionPoints=@crl_dp
+
+    [ crl_dp ]
+
+    URI.1="http://crl.strongswan.org/strongswan.crl"
+    URI.2="ldap://ldap.strongswan.org/cn=strongSwan Root CA, o=strongSwan,
+           c=CH?certificateRevocationList"
+
+If you have only a single HTTP distribution point then the short form
+
+    crlDistributionPoints="URI:http://crl.strongswan.org/strongswan.crl"
+
+also works.
+
+Again the statements
+
+    ipsec pki --gen > moonKey.der
+    ipsec pki --pub --in moonKey.der | ipsec pki --issue --lifetime 730 \
+              --cacert strongswanCert.der --cakey strongswanKey.der \
+              --dn "C=CH, O=strongSwan, CN=moon.strongswan.org" \
+              --san moon.strongswan.org --san 192.168.0.1 \
+              --crl http://crl.strongswan.org/strongswan.crl > moonCert.der
+
+do something thing similar using the strongSwan PKI tool.
+
+Usually, a Windows or Mac OS X (or iOS) based VPN client needs its private key,
+its host or user certificate, and the CA certificate. The most convenient way
+to load this information is to put everything into a PKCS#12 file:
+
+     openssl pkcs12 -export -inkey carolKey.pem \
+                    -in carolCert.pem -name "carol" \
+                    -certfile strongswanCert.pem -caname "strongSwan Root CA" \
+                    -out carolCert.p12
+
+
+3.3 Generating a CRL
+    ----------------
+
+An empty CRL that is signed by the CA can be generated with the command
+
+     openssl ca -gencrl -crldays 15 -out crl.pem
+
+If you omit the -crldays option then the default_crl_days value (30 days)
+specified in openssl.cnf is used.
+
+If you prefer the CRL to be in binary DER format then this conversion
+can be achieved with
+
+     openssl crl -in crl.pem -outform DER -out cert.crl
+
+The strongSwan PKI tool provides the ipsec pki --signcrl command to sign CRLs.
+
+The directory /etc/ipsec.d/crls contains all CRLs either in binary DER
+or in base64 PEM format, irrespective of the file suffix the correct format
+will be determined.
+
+
+3.4 Revoking a certificate
+    ----------------------
+
+A specific host certificate stored in the file host.pem is revoked with the
+command
+
+     openssl ca -revoke host.pem
+
+Next the CRL file must be updated
+
+     openssl ca -gencrl -crldays 60 -out crl.pem
+
+The content of the CRL file can be listed with the command
+
+     openssl crl -in crl.pem -noout -text
+
+in the case of a base64 CRL, or alternatively for a CRL in DER format
+
+     openssl crl -inform DER -in cert.crl -noout -text
+
+Again the ipsec pki --signcrl command may be used to create new CRLs containing
+additional certificates.
+
+
+4. Configuring the connections - ipsec.conf
+   ----------------------------------------
+
+4.1 Configuring my side
+    -------------------
+
+Usually the local side is the same for all connections.  Therefore it makes
+sense to put the definitions characterizing the strongSwan security gateway into
+the conn %default section of the configuration file /etc/ipsec.conf.  If we
+assume throughout this document that the strongSwan security gateway is left and
+the peer is right then we can write
+
+conn %default
+     leftcert=moonCert.pem
+     # load connection definitions automatically
+     auto=add
+
+The X.509 certificate by which the strongSwan security gateway will authenticate
+itself by sending it in binary form to its peers as part of the Internet Key
+Exchange (IKE) is specified in the line
+
+     leftcert=moonCert.pem
+
+The certificate can either be stored in base64 PEM-format or in the binary
+DER-format. Irrespective of the file suffix the correct format will be
+determined.  Therefore
+
+     leftcert=moonCert.der
+
+or
+
+     leftcert=moonCert.cer
+
+would also be valid alternatives.
+
+When using relative pathnames as in the examples above, the certificate files
+must be stored in in the directory /etc/ipsec.d/certs.  In order to distinguish
+strongSwan's own certificates from locally stored trusted peer certificates
+(see section 5.5 for details), they could also be stored in a subdirectory
+below /etc/ipsec.d/certs as e.g. in
+
+    leftcert=mycerts/moonCert.pem
+
+Absolute pathnames are also possible as in
+
+    leftcert=/usr/ssl/certs/moonCert.pem
+
+As an ID for the VPN gateway we recommend the use of a Fully Qualified Domain
+Name (FQDN) of the form
+
+conn rw
+     right=%any
+     leftid=@moon.strongswan.org
+
+Important: When a FQDN identifier is used it must be explicitly included as a
+so called subjectAltName of type dnsName (DNS:) in the certificate indicated
+by leftcert.  For details on how to generate certificates with subjectAltNames,
+please refer to section 3.2.
+
+If you don't want to mess with subjectAltNames, you can use the certificate's
+Distinguished Name (DN) instead, which is an identifier of type DER_ASN1_DN
+and which can be written e.g. in the LDAP-type format
+
+conn rw
+     right=%any
+     leftid="C=CH, O=strongSwan, CN=moon.strongswan.org"
+
+Since the subject's DN is part of the certificate, the leftid does not have to
+be declared explicitly. Thus the entry
+
+conn rw
+     right=%any
+
+automatically assumes the subject DN of leftcert to be the host ID.
+
+
+4.2 Multiple certificates
+    ---------------------
+
+strongSwan supports multiple local host certificates and corresponding
+RSA private keys:
+
+conn rw1
+     right=%any
+     rightid=@peer1.domain1
+     leftcert=myCert1.pem
+     # leftid is DN of myCert1
+
+conn rw2
+     right=%any
+     rightid=@peer2.domain2
+     leftcert=myCert2.pem
+     # leftid is DN of myCert2
+
+When peer1 initiates a connection then strongSwan will send myCert1 and will
+sign with myKey1 defined in /etc/ipsec.secrets (see section 6.2) whereas
+myCert2 and myKey2 will be used in a connection setup started from peer2.
+
+
+4.3 Configuring the peer side using CA certificates
+    -----------------------------------------------
+
+Now we can proceed to define our connections.  In many applications we might
+have dozens of road warriors connecting to a central strongSwan security
+gateway. The following most simple statement:
+
+conn rw
+     right=%any
+
+defines the general roadwarrior case.  The line right=%any literally means that
+any IPsec peer is accepted, regardless of its current IP source address and its
+ID, as long as the peer presents a valid X.509 certificate signed by a CA the
+strongSwan security gateway puts explicit trust in.  Additionally, the signature
+during IKE gives proof that the peer is in possession of the private RSA key
+matching the public key contained in the transmitted certificate.
+
+The ID by which a peer is identifying itself during IKE can by any of the ID
+types IPV[46]_ADDR, FQDN, RFC822_ADDR or DER_ASN1_DN.  If one of the first
+three ID types is used, then the accompanying X.509 certificate of the peer
+must contain a matching subjectAltName field of the type ipAddress (IP:),
+dnsName (DNS:) or rfc822Name (email:), respectively.  With the fourth type
+DER_ASN1_DN the identifier must completely match the subject field of the
+peer's certificate.  One of the two possible representations of a
+Distinguished Name (DN) is the LDAP-type format
+
+     rightid="C=CH, O=strongSwan IPsec, CN=sun.strongswan.org"
+
+Additional whitespace can be added everywhere as desired since it will be
+automatically eliminated by the X.509 parser.  An exception is the single
+whitespace between individual words, like e.g. in strongSwan IPsec, which is
+preserved by the parser.
+
+The Relative Distinguished Names (RDNs) can alternatively be separated by a
+slash '/' instead of a comma ','
+
+     rightid="/C=CH/O=strongSwan IPsec/CN=sun.strongswan.org"
+
+This is the representation extracted from the certificate by the OpenSSL
+command line option
+
+     openssl x509 -in sunCert.pem -noout -subject
+
+The following RDNs are supported by strongSwan
+
++-------------------------------------------------------+
+| DC                   Domain Component                 |
+|-------------------------------------------------------|
+| C                    Country                          |
+|-------------------------------------------------------|
+| ST                   State or province                |
+|-------------------------------------------------------|
+| L                    Locality or town                 |
+|-------------------------------------------------------|
+| O                    Organization                     |
+|-------------------------------------------------------|
+| OU                   Organizational Unit              |
+|-------------------------------------------------------|
+| CN                   Common Name                      |
+|-------------------------------------------------------|
+| ND                   NameDistinguisher, used with CN  |
+|-------------------------------------------------------|
+| N                    Name                             |
+|-------------------------------------------------------|
+| G                    Given name                       |
+|-------------------------------------------------------|
+| S                    Surname                          |
+|-------------------------------------------------------|
+| I                    Initials                         |
+|-------------------------------------------------------|
+| T                    Personal title                   |
+|-------------------------------------------------------|
+| E                    E-mail                           |
+|-------------------------------------------------------|
+| Email                E-mail                           |
+|-------------------------------------------------------|
+| emailAddress         E-mail                           |
+|-------------------------------------------------------|
+| SN                   Serial number                    |
+|-------------------------------------------------------|
+| serialNumber         Serial number                    |
+|-------------------------------------------------------|
+| D                    Description                      |
+|-------------------------------------------------------|
+| ID                   X.500 Unique Identifier          |
+|-------------------------------------------------------|
+| UID                  User ID                          |
+|-------------------------------------------------------|
+| TCGID                [Siemens] Trust Center Global ID |
+|-------------------------------------------------------|
+| UN                   Unstructured Name                |
+|-------------------------------------------------------|
+| unstructuredName     Unstructured Name                |
+|-------------------------------------------------------|
+| UA                   Unstructured Address             |
+|-------------------------------------------------------|
+| unstructuredAddress  Unstructured Address             |
+|-------------------------------------------------------|
+| EN                   Employee Number                  |
+|-------------------------------------------------------|
+| employeeNumber       Employee Number                  |
+|-------------------------------------------------------|
+| dnQualifier          DN Qualifier                     |
++-------------------------------------------------------+
+
+With the roadwarrior connection definition listed above, an IPsec SA for
+the strongSwan security gateway moon.strongswan.org itself can be established.
+If any roadwarrior should be able to reach e.g. the two subnets 10.1.0.0/24
+and 10.1.3.0/24 behind the security gateway then the following connection
+definitions will make this possible
+
+conn rw1
+     right=%any
+     leftsubnet=10.1.0.0/24
+
+conn rw3
+     right=%any
+     leftsubnet=10.1.3.0/24
+
+For IKEv2 connections this can even be simplified by using
+
+    leftsubnet=10.1.0.0/24,10.1.3.0/24
+
+If not all peers in possession of a X.509 certificate signed by a specific
+certificate authority shall be given access to the Linux security gateway,
+then either a subset of them can be barred by listing the serial numbers of
+their certificates in a certificate revocation list (CRL) as specified in
+section 5.2 or as an alternative, access can be controlled by explicitly
+putting a roadwarrior entry for each eligible peer into ipsec.conf:
+
+conn sun
+     right=%any
+     rightid=@sun.strongswan.org
+
+conn carol
+     right=%any
+     rightid=carol@strongswan.org
+
+conn dave
+     right=%any
+     rightid="C=CH, O=strongSwan, CN=dave@strongswan.org"
+
+When the IP address of a peer is known to be stable, it can be specified as
+well.  This entry is mandatory when the strongSwan host wants to act as the
+initiator of an IPsec connection.
+
+conn sun
+     right=192.168.0.2
+     rightid=@sun.strongswan.org
+
+conn carol
+     right=192.168.0.100
+     rightid=carol@strongswan.org
+
+conn dave
+     right=192.168.0.200
+     rightid="C=CH, O=strongSwan, CN=dave@strongswan.org"
+
+conn venus
+     right=192.168.0.50
+
+In the last example the ID types FQDN, RFC822_ADDR, DER_ASN1_DN and IPV4_ADDR,
+respectively, were used.  Of course all connection definitions presented so far
+have included the lines in the conn %defaults section, comprising among other
+a leftcert entry.
+
+
+4.4 Handling Virtual IPs and narrowing
+    ----------------------------------
+
+Often roadwarriors are behind NAT-boxes with IPsec passthrough, which causes
+the inner IP source address of an IPsec tunnel to be different from the
+outer IP source address usually assigned dynamically by the ISP.
+Whereas the varying outer IP address can be handled by the right=%any
+construct, the inner IP address or subnet must always be declared in a
+connection definition. Therefore for the three roadwarriors rw1 to rw3
+connecting to a strongSwan security gateway the following entries are
+required in /etc/ipsec.conf:
+
+conn rw1
+     right=%any
+     righsubnet=10.4.0.5/32
+
+conn rw2
+     right=%any
+     rightsubnet=10.4.0.47/32
+
+conn rw3
+     right=%any
+     rightsubnet=10.4.0.128/28
+
+Because the charon daemon uses narrowing (even for IKEv1) these three entries
+can be reduced to the single connection definition
+
+conn rw
+     right=%any
+     rightsubnet=10.4.0.0/24
+
+Any host will be accepted (of course after successful authentication based on
+the peer's X.509 certificate only) if it declares a client subnet lying totally
+within the brackets defined by the subnet definition (in our example
+10.4.0.0/24).
+
+This strongSwan feature can also be helpful with VPN clients getting a
+dynamically assigned inner IP from a DHCP server located on the NAT router box.
+
+
+4.5 Protocol and Port Selectors
+    ---------------------------
+
+strongSwan offer the possibility to restrict the protocol and optionally the
+ports in an IPsec SA using the rightprotoport and leftprotoport parameters.
+
+Some examples:
+
+conn icmp
+     right=%any
+     rightprotoport=icmp
+     leftid=@moon.strongswan.org
+     leftprotoport=icmp
+
+conn http
+     right=%any
+     rightprotoport=6
+     leftid=@moon.strongswan.org
+     leftprotoport=6/80
+
+conn l2tp       # with port wildcard for Mac OS X Panther interoperability
+     right=%any
+     rightprotoport=17/%any
+     leftid=@moon.strongswan.org
+     leftprotoport=17/1701
+
+conn dhcp
+     right=%any
+     rightprotoport=udp/bootpc
+     leftid=@moon.strongswan.org
+     leftsubnet=0.0.0.0/0  #allows DHCP discovery broadcast
+     leftprotoport=udp/bootps
+     rekey=no
+     keylife=20s
+     rekeymargin=10s
+     auto=add
+
+Protocols and ports can be designated either by their numerical values
+or by their acronyms defined in /etc/services.
+
+    ipsec status
+
+shows the following connection definitions:
+
+"icmp": 192.168.0.1[@moon.strongswan.org]:1/0...%any:1/0
+"http": 192.168.0.1[@moon.strongswan.org]:6/80...%any:6/0
+"l2tp": 192.168.0.1[@moon.strongswan.org]:17/1701...%any:17/%any
+"dhcp": 0.0.0.0/0===192.168.0.1[@moon.strongswan.org]:17/67...%any:17/68
+
+Based on the protocol and port selectors appropriate policies will be set
+up, so that only the specified payload types will pass through the IPsec
+tunnel.
+
+
+4.6 IPsec policies based on wildcards
+    ---------------------------------
+
+In large VPN-based remote access networks there is often a requirement that
+access to the various parts of an internal network must be granted selectively,
+e.g. depending on the group membership of the remote access user.  strongSwan
+makes this possible by applying wildcard filtering on the VPN user's
+distinguished name (ID_DER_ASN1_DN).
+
+Let's make a practical example:
+
+An organization has a sales department (OU=Sales) and a research group
+(OU=Research).  In the company intranet there are separate subnets for Sales
+(10.0.0.0/24) and Research (10.0.1.0/24) but both groups share a common web
+server (10.0.2.100).  The VPN clients use Virtual IP addresses that are either
+assigned statically or from a dynamic pool.  The sales and research departments
+use IP addresses from separate address pools (10.1.0.0/24) and (10.1.1.0/24),
+respectively.  An X.509 certificate is issued to each employee, containing in
+its subject distinguished name the country (C=CH), the company (O=ACME),
+the group membership(OU=Sales or OU=Research) and the common name (e.g.
+CN=Bart Simpson).
+
+The IPsec policy defined above can now be enforced with the following three
+IPsec security associations:
+
+conn sales
+     right=%any
+     rightid="C=CH, O=ACME, OU=Sales, CN=*"
+     rightsubnet=10.1.0.0/24         # Sales IP range
+     leftsubnet=10.0.0.0/24          # Sales subnet
+
+conn research
+     right=%any
+     rightid="C=CH, O=ACME, OU=Research, CN=*"
+     rightsubnet=10.1.1.0/24         # Research IP range
+     leftsubnet=10.0.1.0/24          # Research subnet
+
+conn web
+     right=%any
+     rightid="C=CH, O=ACME, OU=*, CN=*"
+     rightsubnet=10.1.0.0/23         # Remote access IP range
+     leftsubnet=10.0.2.100/32        # Web server
+     rightprotoport=tcp              # TCP protocol only
+     leftprotoport=tcp/http          # TCP port 80 only
+
+The '*' character is used as a wildcard in relative distinguished names (RDNs).
+In order to match a wildcard template, the ID_DER_ASN1_DN of a peer must contain
+the same number of RDNs (selected from the list in section 4.3) appearing in the
+exact order defined by the template.
+
+    "C=CH, O=ACME, OU=Research, OU=Special Effects, CN=Bart Simpson"
+
+matches the templates
+
+    "C=CH, O=ACME, OU=Research, OU=*, CN=*"
+
+    "C=CH, O=ACME, OU=*, OU=Special Effects, CN=*"
+
+    "C=CH, O=ACME, OU=*, OU=*, CN=*"
+
+but not the template
+
+    "C=CH, O=ACME, OU=*, CN=*"
+
+which doesn't have the same number of RDNs.
+
+
+4.7 IPsec policies based on CA certificates
+    ---------------------------------------
+
+As an alternative to the wildcard based IPsec policies described in section 4.6,
+access to specific client host and subnets can be controlled on the basis of
+the CA that issued the peer certificate
+
+
+conn sales
+     right=%any
+     rightca="C=CH, O=ACME, OU=Sales, CN=Sales CA"
+     rightsubnet=10.1.0.0/24         # Sales IP range
+     leftsubnet=10.0.0.0/24          # Sales subnet
+
+conn research
+     right=%any
+     rightca="C=CH, O=ACME, OU=Research, CN=Research CA"
+     rightsubnet=10.1.1.0/24         # Research IP range
+     leftsubnet=10.0.1.0/24          # Research subnet
+
+conn web
+     right=%any
+     rightca="C=CH, O=ACME, CN=ACME Root CA"
+     rightsubnet=10.1.0.0/23         # Remote access IP range
+     leftsubnet=10.0.2.100/32        # Web server
+     rightprotoport=tcp              # TCP protocol only
+     leftprotoport=tcp/http          # TCP port 80 only
+
+In the example above, the connection "sales" can be used by peers
+presenting certificates issued by the Sales CA, only.  In the same way,
+the use of the connection "research" is restricted to owners of certificates
+issued by the Research CA.  The connection "web" is open to both "Sales" and
+"Research" peers because the required "ACME Root CA" is the issuer of the
+Research and Sales intermediate CAs.  If no rightca parameter is present
+then any valid certificate issued by one of the trusted CAs in
+/etc/ipsec.d/cacerts can be used by the peer.
+
+The leftca parameter usually doesn't have to be set explicitly because
+by default it is set to the issuer field of the certificate loaded via
+leftcert.  The statement
+
+     rightca=%same
+
+sets the CA requested from the peer to the CA used by the left side itself
+as e.g. in
+
+conn sales
+     right=%any
+     rightca=%same
+     leftcert=mySalesCert.pem
+
+
+5. Configuring certificates and CRLs
+   ---------------------------------
+
+
+5.1 Installing the CA certificates
+    ------------------------------
+
+X.509 certificates received by strongSwan during the IKE protocol are
+automatically authenticated by going up the trust chain until a self-signed
+root CA certificate is reached.  Usually host certificates are directly signed
+by a root CA, but strongSwan also supports multi-level hierarchies with
+intermediate CAs in between.  All CA certificates belonging to a trust chain
+must be copied in either binary DER or base64 PEM format into the directory
+
+     /etc/ipsec.d/cacerts/
+
+
+5.2 Installing optional certificate revocation lists (CRLs)
+    -------------------------------------------------------
+
+By copying a CA certificate into /etc/ipsec.d/cacerts/, automatically all user
+or host certificates issued by this CA are declared valid.  Unfortunately,
+private keys might get compromised inadvertently or intentionally, personal
+certificates of users leaving a company have to be blocked immediately, etc.
+To this purpose certificate revocation lists (CRLs) have been created.  CRLs
+contain the serial numbers of all user or host certificates that have been
+revoked due to various reasons.
+
+After successful verification of the X.509 trust chain, strongSwan searches its
+list of CRLs either obtained by loading them from the /etc/ipsec.d/crls/
+directory or fetching them dynamically from a HTTP or LDAP server for the
+presence of a CRL issued by the CA that has signed the certificate.
+
+If the serial number of the certificate is found in the CRL then the public key
+contained in the certificate is declared invalid and the IPsec SA will not be
+established.  If no CRL is found or if the deadline defined in the nextUpdate
+field of the CRL has been reached, a warning is issued but the public key will
+nevertheless be accepted.  CRLs must be stored either in binary DER or base64
+PEM format in the crls directory.
+
+
+5.3 Dynamic update of certificates and CRLs
+    ---------------------------------------
+
+strongSwan reads certificates and CRLs from their respective files during system
+startup and keeps them in memory.  X.509 certificates have a finite life span
+defined by their validity field.  Therefore it must be possible to replace CA or
+OCSP certificates kept in system memory without disturbing established IKE SAs.
+Certificate revocation lists should also be updated in the regular intervals
+indicated by the nextUpdate field in the CRL body.  The following interactive
+commands allow the manual replacement of the various files:
+
++---------------------------------------------------------------------------+
+| ipsec rereadsecrets       reload file /etc/ipsec.secrets                  |
+|---------------------------------------------------------------------------|
+| ipsec rereadcacerts       reload all files in /etc/ipsec.d/cacerts/       |
+|---------------------------------------------------------------------------|
+| ipsec rereadaacerts       reload all files in /etc/ipsec.d/aacerts/       |
+|---------------------------------------------------------------------------|
+| ipsec rereadocspcerts     reload all files in /etc/ipsec.d/ocspcerts/     |
+|---------------------------------------------------------------------------|
+| ipsec rereadacerts        reload all files in /etc/ipsec.d/acerts/        |
+|---------------------------------------------------------------------------|
+| ipsec rereadcrls          reload all files in /etc/ipsec.d/crls/          |
+|---------------------------------------------------------------------------|
+| ipsec rereadall           ipsec rereadsecrets                             |
+|                                 rereadcacerts                             |
+|                                 rereadaacerts                             |
+|                                 rereadocspcerts                           |
+|                                 rereadacerts                              |
+|                                 rereadcrls                                |
+|---------------------------------------------------------------------------|
+| ipsec purgeocsp           purge the OCSP cache and fetching requests      |
++---------------------------------------------------------------------------+
+
+CRLs can also be automatically fetched from an HTTP or LDAP server by using
+the CRL distribution points contained in X.509 certificates.
+
+
+5.4 Local caching of CRLs
+    ---------------------
+
+The the ipsec.conf option
+
+   config setup
+        cachecrls=yes
+
+activates the local caching of CRLs that were dynamically fetched from an
+HTTP or LDAP server.  Cached copies are stored in /etc/ipsec.d/crls using a
+unique filename formed from the issuer's SubjectKeyIdentifier and the
+suffix .crl.
+
+With the cached copy the CRL is immediately available after startup.  When the
+local copy is about to expire it is automatically replaced with an updated CRL
+fetched from one of the defined CRL distribution points.
+
+
+5.5 Online Certificate Status Protocol (OCSP)
+    -----------------------------------------
+
+The Online Certificate Status Protocol is defined by RFC 2560.  It can be
+used to query an OCSP server about the current status of an X.509 certificate
+and is often used as a more dynamic alternative to a static Certificate
+Revocation List (CRL).  Both the OCSP request sent by the client and the OCSP
+response messages returned by the server are transported via a standard
+TCP/HTTP connection.  Therefore cURL support must be enabled during
+configuration.
+
+In the simplest OCSP setup, a default URI under which the OCSP server for a
+given CA can be accessed is defined in ipsec.conf:
+
+   ca strongswan
+        cacert=strongswanCert.pem
+        ocspuri=http://ocsp.strongswan.org:8880
+        auto=add
+
+The HTTP port can be freely chosen.
+
+OpenSSL implements an OCSP server that can be used in conjunction with an
+openssl-based Public Key Infrastructure.  The OCSP server is started with the
+following command:
+
+    openssl ocsp -index index.txt -CA strongswanCert.pem -port 8880 \
+                 -rkey ocspKey.pem -rsigner ocspCert.pem \
+                 -resp_no_certs -nmin 60 -text
+
+The command consists of the parameters
+
+ -index    index.txt is a copy of the OpenSSL index file containing the list of
+           all issued certificates.  The certificate status in index.txt
+           is designated either by V for valid or R for revoked.  If a new
+           certificate is added or if a certificate is revoked using the
+           openssl ca command, the OCSP server must be restarted in order for
+           the changes in index.txt to take effect.
+
+ -CA       the CA certificate
+
+ -port     the HTTP port the OCSP server is listening on.
+
+ -rkey     the private key used to sign the OCSP response.  The use of the
+           sensitive CA private key is not recommended since this could
+           jeopardize the security of your production PKI if the OCSP
+           server is hacked.  It is much better to generate a special
+           RSA private key just for OCSP signing use instead.
+
+ -rsigner  the certificate of the OCSP server containing a public key which
+           matches the private key defined by -rkey and which can be used by
+           the client to check the trustworthiness of the signed OCSP response.
+
+ -resp_no_certs  With this option the OCSP signer certificate defined by
+                 -rsigner is not included in the OCSP response.
+
+ -nmin     the validity interval of an OCSP response given in minutes.
+
+ -text     this option activates a verbose logging output, showing the contents
+           of both the received OCSP request and sent OCSP response.
+
+
+The OCSP signer certificate can either be put into the default directory
+
+    /etc/ipsec.d/ocspcerts
+
+or alternatively strongSwan can receive it as part of the OCSP response from the
+remote OCSP server.  In order to verify that the server is indeed authorized by
+a CA to deal out certificate status information an extended key usage attribute
+must be included in the OCSP server certificate.  Just insert the parameter
+
+    extendedKeyUsage=OCSPSigner
+
+in the [ usr_cert ] section of your openssl.cnf configuration file before
+the CA signs the OCSP server certificate.
+
+For a given CA the corresponding ca section in ipsec.conf (see section 7) allows
+to define the URI of a single OCSP server.  As an alternative an OCSP URI can be
+embedded into each host and user certificate by putting the line
+
+    authorityInfoAccess = OCSP;URI:http://ocsp.strongswan.org:8880
+
+into the [ usr_cert ] section of your openssl.cnf configuration file.
+If an OCSP authorityInfoAccess extension is present in a certificate then this
+record overrides the default URI defined by the ca section.
+
+
+5.6 CRL Policy
+    ----------
+
+By default strongSwan is quite tolerant concerning the handling of CRLs. It is
+not mandatory for a CRL to be present in /etc/ipsec.d/crls and if the expiration
+date defined by the nextUpdate field of a CRL has been reached just a warning
+is issued but a peer certificate will always be accepted if it has not been
+revoked.
+
+If you want to enforce a stricter CRL policy then you can do this by setting
+the "strictcrlpolicy" option.  This is done in the "config setup" section
+of the ipsec.conf file:
+
+    config setup
+         strictcrlpolicy=yes
+          ...
+
+A certificate received from a peer will not be accepted if no corresponding
+CRL or OCSP response is available.  And if an ISAKMP SA re-negotiation takes
+place after the nextUpdate deadline has been reached, the peer certificate
+will be declared invalid and the cached RSA public key will be deleted, causing
+the connection in question to fail.  Therefore if you are going to use the
+"strictcrlpolicy=yes" option, make sure that the CRLs will always be updated
+in time.  Otherwise a total standstill would ensue.
+
+As mentioned earlier the default setting is "strictcrlpolicy=no"
+
+
+5.7 Configuring the peer side using locally stored certificates
+    -----------------------------------------------------------
+
+If you don't want to use trust chains based on CA certificates as proposed in
+section 4.3 you can alternatively import trusted peer certificates directly.
+Thus you do not have to rely on the certificate to be transmitted by the peer
+as part of the IKE protocol.
+
+With the conn %default section defined in section 4.1 and the use of the
+rightcert keyword for the peer side, the connection definitions in section 4.3
+can alternatively be written as
+
+    conn sun
+          right=%any
+          rightid=@sun.strongswan.org
+          rightcert=sunCert.cer
+
+     conn carol
+          right=192.168.0.100
+          rightcert=carolCert.der
+
+If the peer certificates are loaded locally then there is no sense in sending
+any certificates to the other end via the IKE protocol.  Especially if
+self-signed certificates are used which wouldn't be accepted anyway by
+the other side.  In these cases it is recommended to add
+
+    leftsendcert=never
+
+to the connection definition[s] in order to avoid the sending of the host's
+own certificate.  The default value is
+
+    leftsendcert=ifasked
+
+If a peer does not send a certificate request then use the setting
+
+    leftsendcert=always
+
+If a peer certificate contains a subjectAltName extension, then an alternative
+rightid type can be used, as the example "conn sun" shows.  If no rightid
+entry is present then the subject distinguished name contained in the
+certificate is taken as the ID.
+
+Using the same rules concerning pathnames that apply to strongSwan's own
+certificates, the following two definitions are also valid for trusted peer
+certificates:
+
+    rightcert=peercerts/carolCert.der
+
+or
+
+    rightcert=/usr/ssl/certs/carolCert.der
+
+
+6. Configuring the private keys - ipsec.secrets
+   --------------------------------------------
+
+6.1 Loading private key files in PKCS#1 or PKCS#8 format
+    ----------------------------------------------------
+
+Besides strongSwan's raw private key format strongSwan has been enabled to
+load RSA (or ECDSA) private keys in the PKCS#1 or PKCS#8 file format.
+The key files can be optionally secured with a passphrase.
+
+RSA private key files are declared in /etc/ipsec.secrets using the syntax
+
+    : RSA <my keyfile> "<optional passphrase>"
+
+The key file can be either in base64 PEM-format or binary DER-format.  The
+actual coding is detected automatically.  The example
+
+    : RSA moonKey.pem
+
+uses a pathname relative to the default directory
+
+    /etc/ipsec.d/private
+
+As an alternative an absolute pathname can be given as in
+
+    : RSA /usr/ssl/private/moonKey.pem
+
+In both cases make sure that the key files are root readable only.
+
+Often a private key must be transported from the Certification Authority
+where it was generated to the target security gateway where it is going
+to be used.  In order to protect the key it can be encrypted with a symmetric
+cipher using a transport key derived from a cryptographically strong
+passphrase.
+
+Once on the security gateway the private key can either be permanently
+unlocked so that it can be used by Pluto without having to know a
+passphrase
+
+    openssl rsa -in moonKey.pem -out moonKey.pem
+
+or as an option the key file can remain secured.  In this case the passphrase
+unlocking the private key must be added after the pathname in
+/etc/ipsec.secrets
+
+    : RSA moonKey.pem "This is my passphrase"
+
+Some CAs distribute private keys embedded in a PKCS#12 file. Since strongSwan
+is not yet able to read this format directly, the private key part must
+first be extracted using the command
+
+     openssl pkcs12 -nocerts -in moonCert.p12 -out moonKey.pem
+
+if the key file moonKey.pem is to be secured again by a passphrase, or
+
+     openssl pkcs12 -nocerts  -nodes -in moonCert.p12 -out moonKey.pem
+
+if the private key is to be stored unlocked.
+
+
+6.2 Entering passphrases interactively
+    ----------------------------------
+
+On a VPN gateway you would want to put the passphrase protecting the private
+key file right into /etc/ipsec.secrets as described in the previous paragraph,
+so that the gateway can be booted in unattended mode.  The risk of keeping
+unencrypted secrets on a server can be minimized by putting the box into a
+locked room.  As long as no one can get root access on the machine the private
+keys are safe.
+
+On a mobile laptop computer the situation is quite different.  The computer can
+be stolen or the user is leaving it unattended so that unauthorized persons
+can get access to it.  In theses cases it would be preferable not to keep any
+passphrases openly in /etc/ipsec.secrets but to prompt for them interactively
+instead.  This is easily done by defining
+
+    : RSA moonKey.pem %prompt
+
+Since strongSwan is usually started during the boot process, usually no
+interactive console windows is available which can be used to prompt for
+the passphrase.  This must be initiated by the user by typing
+
+    ipsec secrets
+
+which actually is an alias for the existing command
+
+    ipsec rereadsecrets
+
+and which causes a passphrase prompt to appear.  To abort entering a passphrase
+enter just a carriage return.
+
+
+6.3 Multiple private keys
+    ---------------------
+
+strongSwan supports multiple private keys. Since the connections defined
+in ipsec.conf can find the correct private key based on the public key
+contained in the certificate assigned by leftcert, default private key
+definitions without specific IDs can be used
+
+    : RSA myKey1.pem "<optional passphrase1>"
+
+    : RSA myKey2.pem "<optional passphrase2>"
+
+
+7. Configuring CA properties - ipsec.conf
+   --------------------------------------
+
+Besides the definition of IPsec connections the ipsec.conf file can also
+be used to configure a few properties of the certification authorities
+needed to establish the X.509 trust chains.  The following example shows
+some of the parameters that are currently available:
+
+    ca strongswan
+       cacert=strongswanCert.pem
+       ocspuri=http://ocsp.strongswan.org:8880
+       crluri=http://crl.strongswan.org/strongswan.crl'
+       crluri2="ldap://ldap.strongswan.org/O=strongSwan, C=CH?certificateRevocationList"
+       auto=add
+
+In a similar way as conn sections are used for connection definitions, an
+arbitrary number of optional ca sections define the basic properties of CAs.
+
+Each ca section is named with a unique label
+
+       ca strongswan
+
+The only mandatory parameter is
+
+       cacert=strongswanCert.pem
+
+which points to the CA certificate which usually resides in the default
+directory /etc/ipsec.d/cacerts/ but could also be retrieved via an absolute
+path name.
+
+The OCSP URI
+
+       ocspuri=http://ocsp.strongswan.org:8880
+
+allows to define an individual OCSP server per CA.  Also up to two additional
+CRL distribution points (CDPs) can be defined
+
+       crluri=http://crl.strongswan.org/strongswan.crl'
+       crluri2="ldap://ldap.strongswan.org/O=strongSwan, C=CH?certificateRevocationList"
+
+which are added to any CDPs already present in the received certificates
+themselves.
+
+With the auto=add statement the ca definition is automatically loaded during
+startup.  Setting auto=ignore will ignore the ca section.
+
+Any parameters which appear in several ca definitions can be put in
+a common ca %default section
+
+    ca %default
+       crluri=http://crl.strongswan.org/strongswan.crl'
+
+
+8. Monitoring functions
+   --------------------
+
+strongSwan offers the following monitoring functions:
+
+The command
+
+    ipsec listalgs
+
+lists all IKE cryptographic algorithms that are currently
+registered with strongSwan.
+
+
+The command
+
+    ipsec listcerts [--utc]
+
+lists all local certificates, both strongSwan's own and those of
+trusted peer loaded via leftcert and rightcert, respectively.
+
+
+The command
+
+    ipsec listcacerts [--utc]
+
+lists all CA certificates that have been either been loaded from the directory
+/etc/ipsec.d/cacerts/ or received via the IKE protocol.
+
+
+The command
+
+    ipsec listaacerts [--utc]
+
+lists all Authorization Authority certificates that have been loaded from
+the directory /etc/ipsec.d/aacerts/.
+
+
+The command
+
+    ipsec listocspcerts [--utc]
+
+lists all OCSO signer certificates that have been either loaded from
+/etc/ipsec.d/ocspcerts/ or have been received included in the OCSP server
+response.
+
+
+The command
+
+    ipsec listacerts [--utc]
+
+lists all X.509 attribute certificates that have been loaded from the directory
+/etc/ipsec.d/acerts/.
+
+
+The command
+
+    ipsec listcainfos [--utc]
+
+lists the properties defined by the ca definition sections in ipsec.conf.
+
+
+The command
+
+    ipsec listcrls [--utc]
+
+lists all CRLs that have been loaded from /etc/ipsec.d/crls/.
+
+
+The command
+
+
+    ipsec listocsp [--utc]
+
+lists the contents of the OCSP response cache.
+
+
+The command
+
+    ipsec listall [--utc]
+
+is equivalent to using all of the above commands.
+
+
+9. Firewall support functions
+   --------------------------
+
+
+9.1 Environment variables in the updown script
+    ------------------------------------------
+
+strongSwan makes the following environment variables available
+in the updown script indicated by the leftupdown option:
+
++-------------------------------------------------------------------+
+| Variable               Example                    Comment         |
+|-------------------------------------------------------------------|
+| $PLUTO_PEER_ID         carol@strongswan.org       RFC822_ADDR (1) |
+|-------------------------------------------------------------------|
+| $PLUTO_PEER_PROTOCOL   17                         udp         (2) |
+|-------------------------------------------------------------------|
+| $PLUTO_PEER_PORT       68                         bootpc      (3) |
+|-------------------------------------------------------------------|
+| $PLUTO_PEER_CA         C=CH, O=ACME, CN=Sales CA              (4) |
+|-------------------------------------------------------------------|
+| $PLUTO_MY_ID           @moon.strongswan.org       FQDN        (1) |
+|-------------------------------------------------------------------|
+| $PLUTO_MY_PROTOCOL     17                         udp         (2) |
+|-------------------------------------------------------------------|
+| $PLUTO_MY_PORT         67                         bootps      (3) |
++-------------------------------------------------------------------+
+
+(1) $PLUTO_PEER_ID/$PLUTO_MY_ID contain the IDs of the two ends
+    of an established connection. In our examples these
+    correspond to the strings defined by rightid and leftid,
+    respectively.
+
+(2) $PLUTO_PEER_PROTOCOL/$PLUTO_MY_PROTOCOL contain the protocol
+    defined by the rightprotoport and leftprotoport options,
+    respectively. Both variables contain the same protocol value.
+    The variables take on the value '0' if no protocol has been defined.
+
+(3) $PLUTO_PEER_PORT/$PLUTO_MY_PORT contain the ports defined by
+    the rightprotoport and leftprotoport options, respectively.
+    The variables take on the value '0' if no port has been defined.
+
+(4) $PLUTO_PEER_CA contains the distinguished name of the CA that
+    issued the peer's certificate.
+
+There are several more, refer to the provided default script for a documentation
+of these.
+
+
+9.2 Automatic insertion and deletion of iptables firewall rules
+    -----------------------------------------------------------
+
+The default _updown script automatically inserts and deletes dynamic iptables
+firewall rules upon the establishment or teardown, respectively, of an IPsec
+security association.  This feature is activated with the line
+
+   leftfirewall=yes
+
+If you define a local client subnet with a netmask larger than /32 behind
+the gateway then the automatically inserted FORWARD iptables rules will
+not allow to access the internal IP address of the host although it is
+part of the client subnet definition.  If you want additional INPUT and
+OUTPUT iptables rules to be inserted, so that the host itself can be accessed
+then add the following line:
+
+   lefthostaccess=yes
+
+The _updown script also features a logging facility which will register the
+creation (+) and the expiration (-) of each successfully established VPN
+connection in a special syslog file in the following concise and easily
+readable format:
+
+Jul 19 18:58:38 moon vpn:
+    + @carol.strongswan.org  192.168.0.100 -- 192.168.0.1 == 10.1.0.0/16
+Jul 19 22:15:17 moon vpn:
+    - @carol.strongswan.org  192.168.0.100 -- 192.168.0.1 == 10.1.0.0/16