conf: Split strongswan.conf(5) man page and use generated snippet
authorTobias Brunner <tobias@strongswan.org>
Wed, 29 Jan 2014 12:59:34 +0000 (13:59 +0100)
committerTobias Brunner <tobias@strongswan.org>
Wed, 12 Feb 2014 13:34:33 +0000 (14:34 +0100)
conf/.gitignore
conf/Makefile.am
conf/strongswan.conf.5.head.in [new file with mode: 0644]
conf/strongswan.conf.5.in [deleted file]
conf/strongswan.conf.5.tail.in [new file with mode: 0644]
configure.ac

index 04065fb..6ccd325 100644 (file)
@@ -1,4 +1,6 @@
 default.conf
 strongswan.conf.5
+strongswan.conf.5.head
+strongswan.conf.5.tail
 */*.conf
 */*.tmp
\ No newline at end of file
index 5f88815..bc7017b 100644 (file)
@@ -58,6 +58,10 @@ strongswan.conf.5.main: $(alloptions)
        $(AM_V_GEN) \
        $(PYTHON) $(srcdir)/format-options.py -f man $^ > $@
 
+strongswan.conf.5: strongswan.conf.5.head strongswan.conf.5.main strongswan.conf.5.tail
+       $(AM_V_GEN) \
+       cat $^ > $@
+
 maintainer-clean-local:
        cd $(srcdir) && \
                rm -f $(confsnippets) default.conf plugins/*.conf plugins/*.tmp
diff --git a/conf/strongswan.conf.5.head.in b/conf/strongswan.conf.5.head.in
new file mode 100644 (file)
index 0000000..23454e7
--- /dev/null
@@ -0,0 +1,127 @@
+.TH STRONGSWAN.CONF 5 "" "@PACKAGE_VERSION@" "strongSwan"
+.SH NAME
+strongswan.conf \- strongSwan configuration file
+.SH DESCRIPTION
+While the
+.IR ipsec.conf (5)
+configuration file is well suited to define IPsec related configuration
+parameters, it is not useful for other strongSwan applications to read options
+from this file.
+The file is hard to parse and only
+.I ipsec starter
+is capable of doing so. As the number of components of the strongSwan project
+is continually growing, a more flexible configuration file was needed, one that
+is easy to extend and can be used by all components. With strongSwan 4.2.1
+.IR strongswan.conf (5)
+was introduced which meets these requirements.
+
+.SH SYNTAX
+The format of the strongswan.conf file consists of hierarchical
+.B sections
+and a list of
+.B key/value pairs
+in each section. Each section has a name, followed by C-Style curly brackets
+defining the section body. Each section body contains a set of subsections
+and key/value pairs:
+.PP
+.EX
+       settings := (section|keyvalue)*
+       section  := name { settings }
+       keyvalue := key = value\\n
+.EE
+.PP
+Values must be terminated by a newline.
+.PP
+Comments are possible using the \fB#\fP-character, but be careful: The parser
+implementation is currently limited and does not like brackets in comments.
+.PP
+Section names and keys may contain any printable character except:
+.PP
+.EX
+       . { } # \\n \\t space
+.EE
+.PP
+An example file in this format might look like this:
+.PP
+.EX
+       a = b
+       section-one {
+               somevalue = asdf
+               subsection {
+                       othervalue = xxx
+               }
+               # yei, a comment
+               yetanother = zz
+       }
+       section-two {
+               x = 12
+       }
+.EE
+.PP
+Indentation is optional, you may use tabs or spaces.
+
+.SH INCLUDING FILES
+Using the
+.B include
+statement it is possible to include other files into strongswan.conf, e.g.
+.PP
+.EX
+       include /some/path/*.conf
+.EE
+.PP
+If the file name is not an absolute path, it is considered to be relative
+to the directory of the file containing the include statement. The file name
+may include shell wildcards (see
+.IR sh (1)).
+Also, such inclusions can be nested.
+.PP
+Sections loaded from included files
+.I extend
+previously loaded sections; already existing values are
+.IR replaced .
+It is important to note that settings are added relative to the section the
+include statement is in.
+.PP
+As an example, the following three files result in the same final
+config as the one given above:
+.PP
+.EX
+       a = b
+       section-one {
+               somevalue = before include
+               include include.conf
+       }
+       include other.conf
+
+include.conf:
+       # settings loaded from this file are added to section-one
+       # the following replaces the previous value
+       somevalue = asdf
+       subsection {
+               othervalue = yyy
+       }
+       yetanother = zz
+
+other.conf:
+       # this extends section-one and subsection
+       section-one {
+               subsection {
+                       # this replaces the previous value
+                       othervalue = xxx
+               }
+       }
+       section-two {
+               x = 12
+       }
+.EE
+
+.SH READING VALUES
+Values are accessed using a dot-separated section list and a key.
+With reference to the example above, accessing
+.B section-one.subsection.othervalue
+will return
+.BR xxx .
+
+.SH DEFINED KEYS
+The following keys are currently defined (using dot notation). The default
+value (if any) is listed in brackets after the key.
diff --git a/conf/strongswan.conf.5.in b/conf/strongswan.conf.5.in
deleted file mode 100644 (file)
index 02f910e..0000000
+++ /dev/null
@@ -1,1781 +0,0 @@
-.TH STRONGSWAN.CONF 5 "2013-10-29" "@PACKAGE_VERSION@" "strongSwan"
-.SH NAME
-strongswan.conf \- strongSwan configuration file
-.SH DESCRIPTION
-While the
-.IR ipsec.conf (5)
-configuration file is well suited to define IPsec related configuration
-parameters, it is not useful for other strongSwan applications to read options
-from this file.
-The file is hard to parse and only
-.I ipsec starter
-is capable of doing so. As the number of components of the strongSwan project
-is continually growing, a more flexible configuration file was needed, one that
-is easy to extend and can be used by all components. With strongSwan 4.2.1
-.IR strongswan.conf (5)
-was introduced which meets these requirements.
-
-.SH SYNTAX
-The format of the strongswan.conf file consists of hierarchical
-.B sections
-and a list of
-.B key/value pairs
-in each section. Each section has a name, followed by C-Style curly brackets
-defining the section body. Each section body contains a set of subsections
-and key/value pairs:
-.PP
-.EX
-       settings := (section|keyvalue)*
-       section  := name { settings }
-       keyvalue := key = value\\n
-.EE
-.PP
-Values must be terminated by a newline.
-.PP
-Comments are possible using the \fB#\fP-character, but be careful: The parser
-implementation is currently limited and does not like brackets in comments.
-.PP
-Section names and keys may contain any printable character except:
-.PP
-.EX
-       . { } # \\n \\t space
-.EE
-.PP
-An example file in this format might look like this:
-.PP
-.EX
-       a = b
-       section-one {
-               somevalue = asdf
-               subsection {
-                       othervalue = xxx
-               }
-               # yei, a comment
-               yetanother = zz
-       }
-       section-two {
-               x = 12
-       }
-.EE
-.PP
-Indentation is optional, you may use tabs or spaces.
-
-.SH INCLUDING FILES
-Using the
-.B include
-statement it is possible to include other files into strongswan.conf, e.g.
-.PP
-.EX
-       include /some/path/*.conf
-.EE
-.PP
-If the file name is not an absolute path, it is considered to be relative
-to the directory of the file containing the include statement. The file name
-may include shell wildcards (see
-.IR sh (1)).
-Also, such inclusions can be nested.
-.PP
-Sections loaded from included files
-.I extend
-previously loaded sections; already existing values are
-.IR replaced .
-It is important to note that settings are added relative to the section the
-include statement is in.
-.PP
-As an example, the following three files result in the same final
-config as the one given above:
-.PP
-.EX
-       a = b
-       section-one {
-               somevalue = before include
-               include include.conf
-       }
-       include other.conf
-
-include.conf:
-       # settings loaded from this file are added to section-one
-       # the following replaces the previous value
-       somevalue = asdf
-       subsection {
-               othervalue = yyy
-       }
-       yetanother = zz
-
-other.conf:
-       # this extends section-one and subsection
-       section-one {
-               subsection {
-                       # this replaces the previous value
-                       othervalue = xxx
-               }
-       }
-       section-two {
-               x = 12
-       }
-.EE
-
-.SH READING VALUES
-Values are accessed using a dot-separated section list and a key.
-With reference to the example above, accessing
-.B section-one.subsection.othervalue
-will return
-.BR xxx .
-
-.SH DEFINED KEYS
-The following keys are currently defined (using dot notation). The default
-value (if any) is listed in brackets after the key.
-
-.SS attest section
-.TP
-.BR attest.database
-Path to database with file measurement information
-.TP
-.BR attest.load
-Plugins to load in ipsec attest tool
-
-.SS charon section
-.TP
-.BR Note :
-Many of these options also apply to \fBcharon\-cmd\fR and other
-\fBcharon\fR derivatives. Just use their respective name (e.g.
-\fIcharon\-cmd\fR) instead of  \fIcharon\fR. For many options defaults
-can be defined in the \fIlibstrongswan\fR section.
-.TP
-.BR charon.block_threshold " [5]"
-Maximum number of half-open IKE_SAs for a single peer IP
-.TP
-.BR charon.cert_cache " [yes]"
-Whether relations in validated certificate chains should be cached in memory
-.TP
-.BR charon.cisco_unity " [no]
-Send Cisco Unity vendor ID payload (IKEv1 only)
-.TP
-.BR charon.close_ike_on_child_failure " [no]"
-Close the IKE_SA if setup of the CHILD_SA along with IKE_AUTH failed
-.TP
-.BR charon.cookie_threshold " [10]"
-Number of half-open IKE_SAs that activate the cookie mechanism
-.TP
-.BR charon.crypto_test.bench " [no]"
-
-.TP
-.BR charon.crypto_test.bench_size " [1024]"
-
-.TP
-.BR charon.crypto_test.bench_time " [50]"
-
-.TP
-.BR charon.crypto_test.on_add " [no]"
-Test crypto algorithms during registration
-.TP
-.BR charon.crypto_test.on_create " [no]"
-Test crypto algorithms on each crypto primitive instantiation
-.TP
-.BR charon.crypto_test.required " [no]"
-Strictly require at least one test vector to enable an algorithm
-.TP
-.BR charon.crypto_test.rng_true " [no]"
-Whether to test RNG with TRUE quality; requires a lot of entropy
-.TP
-.BR charon.dh_exponent_ansi_x9_42 " [yes]"
-Use ANSI X9.42 DH exponent size or optimum size matched to cryptographical
-strength
-.TP
-.BR charon.dns1
-.TQ
-.BR charon.dns2
-DNS servers assigned to peer via configuration payload (CP)
-.TP
-.BR charon.dos_protection " [yes]"
-Enable Denial of Service protection using cookies and aggressiveness checks
-.TP
-.BR charon.ecp_x_coordinate_only " [yes]"
-Compliance with the errata for RFC 4753
-.TP
-.BR charon.filelog
-Section to define file loggers, see LOGGER CONFIGURATION
-.TP
-.BR charon.flush_auth_cfg " [no]"
-If enabled objects used during authentication (certificates, identities etc.)
-are released to free memory once an IKE_SA is established.
-Enabling this might conflict with plugins that later need access to e.g. the
-used certificates.
-.TP
-.BR charon.fragment_size " [512]"
-Maximum size (in bytes) of a sent fragment when using the proprietary IKEv1
-fragmentation extension.
-.TP
-.BR charon.group
-Name of the group the daemon changes to after startup
-.TP
-.BR charon.half_open_timeout " [30]"
-Timeout in seconds for connecting IKE_SAs (also see IKE_SA_INIT DROPPING).
-.TP
-.BR charon.hash_and_url " [no]"
-Enable hash and URL support
-.TP
-.BR charon.host_resolver.max_threads " [3]"
-Maximum number of concurrent resolver threads (they are terminated if unused)
-.TP
-.BR charon.host_resolver.min_threads " [0]"
-Minimum number of resolver threads to keep around
-.TP
-.BR charon.i_dont_care_about_security_and_use_aggressive_mode_psk " [no]"
-If enabled responders are allowed to use IKEv1 Aggressive Mode with pre-shared
-keys, which is discouraged due to security concerns (offline attacks on the
-openly transmitted hash of the PSK)
-.TP
-.BR charon.ignore_routing_tables
-A space-separated list of routing tables to be excluded from route lookups
-.TP
-.BR charon.ikesa_limit " [0]"
-Maximum number of IKE_SAs that can be established at the same time before new
-connection attempts are blocked
-.TP
-.BR charon.ikesa_table_segments " [1]"
-Number of exclusively locked segments in the hash table
-.TP
-.BR charon.ikesa_table_size " [1]"
-Size of the IKE_SA hash table
-.TP
-.BR charon.inactivity_close_ike " [no]"
-Whether to close IKE_SA if the only CHILD_SA closed due to inactivity
-.TP
-.BR charon.init_limit_half_open " [0]"
-Limit new connections based on the current number of half open IKE_SAs (see
-IKE_SA_INIT DROPPING).
-.TP
-.BR charon.init_limit_job_load " [0]"
-Limit new connections based on the number of jobs currently queued for
-processing (see IKE_SA_INIT DROPPING).
-.TP
-.BR charon.initiator_only " [no]"
-Causes charon daemon to ignore IKE initiation requests.
-.TP
-.BR charon.install_routes " [yes]"
-Install routes into a separate routing table for established IPsec tunnels
-.TP
-.BR charon.install_virtual_ip " [yes]"
-Install virtual IP addresses
-.TP
-.BR charon.install_virtual_ip_on
-The name of the interface on which virtual IP addresses should be installed.
-If not specified the addresses will be installed on the outbound interface.
-.TP
-.BR charon.integrity_test " [no]"
-Check daemon, libstrongswan and plugin integrity at startup
-.TP
-.BR charon.interfaces_ignore
-A comma-separated list of network interfaces that should be ignored, if
-.B charon.interfaces_use
-is specified this option has no effect.
-.TP
-.BR charon.interfaces_use
-A comma-separated list of network interfaces that should be used by charon.
-All other interfaces are ignored.
-.TP
-.BR charon.keep_alive " [20s]"
-NAT keep alive interval
-.TP
-.BR charon.leak_detective.detailed " [yes]"
-Includes source file names and line numbers in leak detective output
-.TP
-.BR charon.leak_detective.usage_threshold " [10240]"
-Threshold in bytes for leaks to be reported (0 to report all)
-.TP
-.BR charon.leak_detective.usage_threshold_count " [0]"
-Threshold in number of allocations for leaks to be reported (0 to report all)
-.TP
-.BR charon.load
-Plugins to load in the IKEv2 daemon charon
-.TP
-.BR charon.load_modular " [no]"
-If enabled, the list of plugins to load is determined via the value of the
-charon.plugins.<name>.load options.  In addition to a simple boolean flag that
-option may take an integer value indicating the priority of a plugin, which
-would influence the order of a plugin in the plugin list (the default is 1).
-If two plugins have the same priority their order in the default plugin list
-is preserved. Enabled plugins not found in that list are ordered alphabetically
-before other plugins with the same priority.
-.TP
-.BR charon.max_packet " [10000]"
-Maximum packet size accepted by charon
-.TP
-.BR charon.multiple_authentication " [yes]"
-Enable multiple authentication exchanges (RFC 4739)
-.TP
-.BR charon.nbns1
-.TQ
-.BR charon.nbns2
-WINS servers assigned to peer via configuration payload (CP)
-.TP
-.BR charon.port " [500]"
-UDP port used locally. If set to 0 a random port will be allocated.
-.TP
-.BR charon.port_nat_t " [4500]"
-UDP port used locally in case of NAT-T. If set to 0 a random port will be
-allocated.  Has to be different from
-.BR charon.port ,
-otherwise a random port will be allocated.
-.TP
-.BR charon.process_route " [yes]"
-Process RTM_NEWROUTE and RTM_DELROUTE events
-.TP
-.BR charon.processor.priority_threads
-Subsection to configure the number of reserved threads per priority class
-see JOB PRIORITY MANAGEMENT
-.TP
-.BR charon.receive_delay " [0]"
-Delay in ms for receiving packets, to simulate larger RTT
-.TP
-.BR charon.receive_delay_response " [yes]"
-Delay response messages
-.TP
-.BR charon.receive_delay_request " [yes]"
-Delay request messages
-.TP
-.BR charon.receive_delay_type " [0]"
-Specific IKEv2 message type to delay, 0 for any
-.TP
-.BR charon.replay_window " [32]"
-Size of the AH/ESP replay window, in packets.
-.TP
-.BR charon.retransmit_base " [1.8]"
-Base to use for calculating exponential back off, see IKEv2 RETRANSMISSION
-.TP
-.BR charon.retransmit_timeout " [4.0]
-Timeout in seconds before sending first retransmit
-.TP
-.BR charon.retransmit_tries " [5]"
-Number of times to retransmit a packet before giving up
-.TP
-.BR charon.retry_initiate_interval " [0]"
-Interval to use when retrying to initiate an IKE_SA (e.g. if DNS resolution
-failed), 0 to disable retries.
-.TP
-.BR charon.reuse_ikesa " [yes]
-Initiate CHILD_SA within existing IKE_SAs
-.TP
-.BR charon.routing_table
-Numerical routing table to install routes to
-.TP
-.BR charon.routing_table_prio
-Priority of the routing table
-.TP
-.BR charon.send_delay " [0]"
-Delay in ms for sending packets, to simulate larger RTT
-.TP
-.BR charon.send_delay_response " [yes]"
-Delay response messages
-.TP
-.BR charon.send_delay_request " [yes]"
-Delay request messages
-.TP
-.BR charon.send_delay_type " [0]"
-Specific IKEv2 message type to delay, 0 for any
-.TP
-.BR charon.send_vendor_id " [no]
-Send strongSwan vendor ID payload
-.TP
-.BR charon.syslog
-Section to define syslog loggers, see LOGGER CONFIGURATION
-.TP
-.BR charon.threads " [16]"
-Number of worker threads in charon. Several of these are reserved for long
-running tasks in internal modules and plugins. Therefore, make sure you don't
-set this value too low. The number of idle worker threads listed in
-.I ipsec statusall
-might be used as indicator on the number of reserved threads.
-.TP
-.BR charon.tls.cipher
-List of TLS encryption ciphers
-.TP
-.BR charon.tls.key_exchange
-List of TLS key exchange methods
-.TP
-.BR charon.tls.mac
-List of TLS MAC algorithms
-.TP
-.BR charon.tls.suites
-List of TLS cipher suites
-.TP
-.BR charon.user
-Name of the user the daemon changes to after startup
-.TP
-.BR charon.x509.enforce_critical " [yes]"
-Discard certificates with unsupported or unknown critical extensions
-.
-.SS charon.plugins subsection
-.TP
-.BR charon.plugins.android_log.loglevel " [1]"
-Loglevel for logging to Android specific logger
-.TP
-.BR charon.plugins.attr
-Section to specify arbitrary attributes that are assigned to a peer via
-configuration payload (CP)
-.TP
-.BR charon.plugins.attr-sql.database
-Database URI for attr-sql plugin used by charon
-.TP
-.BR charon.plugins.attr-sql.lease_history " [yes]"
-Enable logging of SQL IP pool leases
-.TP
-.BR charon.plugins.certexpire.csv.cron
-Cron style string specifying CSV export times
-.TP
-.BR charon.plugins.certexpire.csv.empty_string
-String to use in empty intermediate CA fields
-.TP
-.BR charon.plugins.certexpire.csv.fixed_fields " [yes]"
-Use a fixed intermediate CA field count
-.TP
-.BR charon.plugins.certexpire.csv.force " [yes]"
-Force export of all trustchains we have a private key for
-.TP
-.BR charon.plugins.certexpire.csv.format " [%d:%m:%Y]"
-strftime(3) format string to export expiration dates as
-.TP
-.BR charon.plugins.certexpire.csv.local
-strftime(3) format string for the CSV file name to export local certificates to
-.TP
-.BR charon.plugins.certexpire.csv.remote
-strftime(3) format string for the CSV file name to export remote certificates to
-.TP
-.BR charon.plugins.certexpire.csv.separator " [,]"
-CSV field separator
-.TP
-.BR charon.plugins.coupling.file
-File to store coupling list to
-.TP
-.BR charon.plugins.coupling.hash " [sha1]"
-Hashing algorithm to fingerprint coupled certificates
-.TP
-.BR charon.plugins.coupling.max " [1]"
-Maximum number of coupling entries to create
-.TP
-.BR charon.plugins.dhcp.force_server_address " [no]"
-Always use the configured server address. This might be helpful if the DHCP
-server runs on the same host as strongSwan, and the DHCP daemon does not listen
-on the loopback interface.  In that case the server cannot be reached via
-unicast (or even 255.255.255.255) as that would be routed via loopback.
-Setting this option to yes and configuring the local broadcast address (e.g.
-192.168.0.255) as server address might work.
-.TP
-.BR charon.plugins.dhcp.identity_lease " [no]"
-Derive user-defined MAC address from hash of IKEv2 identity
-.TP
-.BR charon.plugins.dhcp.server " [255.255.255.255]"
-DHCP server unicast or broadcast IP address
-.TP
-.BR charon.plugins.dhcp.interface " []"
-Interface name the plugin uses for address allocation. The default is to bind
-to any (0.0.0.0) and let the system decide which way to route the packets to
-the DHCP server.
-.TP
-.BR charon.plugins.dnscert.enable " [no]"
-Enable fetching of CERT RRs via DNS
-.TP
-.BR charon.plugins.duplicheck.enable " [yes]"
-Enable duplicheck plugin (if loaded)
-.TP
-.BR charon.plugins.duplicheck.socket " [unix://@piddir@/charon.dck]"
-Socket provided by the duplicheck plugin
-.TP
-.BR charon.plugins.eap-aka.request_identity " [yes]"
-
-.TP
-.BR charon.plugins.eap-aka-3ggp2.seq_check
-
-.TP
-.BR charon.plugins.eap-dynamic.preferred
-The preferred EAP method(s) to be used.  If it is not given the first
-registered method will be used initially.  If a comma separated list is given
-the methods are tried in the given order before trying the rest of the
-registered methods.
-.TP
-.BR charon.plugins.eap-dynamic.prefer_user " [no]"
-If enabled the EAP methods proposed in an EAP-Nak message sent by the peer are
-preferred over the methods registered locally.
-.TP
-.BR charon.plugins.eap-gtc.backend " [pam]"
-XAuth backend to be used for credential verification
-.TP
-.BR charon.plugins.eap-peap.fragment_size " [1024]"
-Maximum size of an EAP-PEAP packet
-.TP
-.BR charon.plugins.eap-peap.max_message_count " [32]"
-Maximum number of processed EAP-PEAP packets (0 = no limit)
-.TP
-.BR charon.plugins.eap-peap.include_length " [no]"
-Include length in non-fragmented EAP-PEAP packets
-.TP
-.BR charon.plugins.eap-peap.phase2_method " [mschapv2]"
-Phase2 EAP client authentication method
-.TP
-.BR charon.plugins.eap-peap.phase2_piggyback " [no]"
-Phase2 EAP Identity request piggybacked by server onto TLS Finished message
-.TP
-.BR charon.plugins.eap-peap.phase2_tnc " [no]"
-Start phase2 EAP TNC protocol after successful client authentication
-.TP
-.BR charon.plugins.eap-peap.request_peer_auth " [no]"
-Request peer authentication based on a client certificate
-.TP
-.BR charon.plugins.eap-radius.accounting " [no]"
-Send RADIUS accounting information to RADIUS servers.
-.TP
-.BR charon.plugins.eap-radius.accounting_requires_vip " [no]"
-If enabled, accounting is disabled unless an IKE_SA has at least one virtual IP
-.TP
-.BR charon.plugins.eap-radius.class_group " [no]"
-Use the
-.I class
-attribute sent in the RADIUS-Accept message as group membership information that
-is compared to the groups specified in the
-.B rightgroups
-option in
-.B ipsec.conf (5).
-.TP
-.BR charon.plugins.eap-radius.close_all_on_timeout " [no]"
-Closes all IKE_SAs if communication with the RADIUS server times out. If it is
-not set only the current IKE_SA is closed.
-.TP
-.BR charon.plugins.eap-radius.dae.enable " [no]"
-Enables support for the Dynamic Authorization Extension (RFC 5176)
-.TP
-.BR charon.plugins.eap-radius.dae.listen " [0.0.0.0]"
-Address to listen for DAE messages from the RADIUS server
-.TP
-.BR charon.plugins.eap-radius.dae.port " [3799]"
-Port to listen for DAE requests
-.TP
-.BR charon.plugins.eap-radius.dae.secret
-Shared secret used to verify/sign DAE messages
-.TP
-.BR charon.plugins.eap-radius.eap_start " [no]"
-Send EAP-Start instead of EAP-Identity to start RADIUS conversation
-.TP
-.BR charon.plugins.eap-radius.filter_id " [no]"
-If the RADIUS
-.I tunnel_type
-attribute with value
-.B ESP
-is received, use the
-.I filter_id
-attribute sent in the RADIUS-Accept message as group membership information that
-is compared to the groups specified in the
-.B rightgroups
-option in
-.B ipsec.conf (5).
-.TP
-.BR charon.plugins.eap-radius.forward.ike_to_radius
-RADIUS attributes to be forwarded from IKEv2 to RADIUS (can be defined by
-name or attribute number, a colon can be used to specify vendor-specific
-attributes, e.g. Reply-Message, or 11, or 36906:12).
-.TP
-.BR charon.plugins.eap-radius.forward.radius_to_ike
-Same as
-.B charon.plugins.eap-radius.forward.ike_to_radius
-but from RADIUS to
-IKEv2, a strongSwan specific private notify (40969) is used to transmit the
-attributes.
-.TP
-.BR charon.plugins.eap-radius.id_prefix
-Prefix to EAP-Identity, some AAA servers use a IMSI prefix to select the
-EAP method
-.TP
-.BR charon.plugins.eap-radius.nas_identifier " [strongSwan]"
-NAS-Identifier to include in RADIUS messages
-.TP
-.BR charon.plugins.eap-radius.port " [1812]"
-Port of RADIUS server (authentication)
-.TP
-.BR charon.plugins.eap-radius.secret
-Shared secret between RADIUS and NAS
-.TP
-.BR charon.plugins.eap-radius.server
-IP/Hostname of RADIUS server
-.TP
-.BR charon.plugins.eap-radius.servers
-Section to specify multiple RADIUS servers. The
-.BR nas_identifier ,
-.BR secret ,
-.B sockets
-and
-.B port
-(or
-.BR auth_port )
-options can be specified for each server. A server's IP/Hostname can be
-configured using the
-.B address
-option. The
-.BR acct_port " [1813]"
-option can be used to specify the port used for RADIUS accounting.
-For each RADIUS server a priority can be specified using the
-.BR preference " [0]"
-option.
-.TP
-.BR charon.plugins.eap-radius.sockets " [1]"
-Number of sockets (ports) to use, increase for high load
-.TP
-.BR charon.plugins.eap-radius.xauth
-Section to configure multiple XAuth authentication rounds via RADIUS. The subsections define so called
-authentication profiles with arbitrary names. In each profile section one or more XAuth types can be
-configured, with an assigned message. For each type a separate XAuth exchange will be initiated and all
-replies get concatenated into the User-Password attribute, which then gets verified over RADIUS.
-
-Available XAuth types are \fBpassword\fR, \fBpasscode\fR, \fBnextpin\fR, and \fBanswer\fR. This type is
-not relevant to strongSwan or the AAA server, but the client may show a different dialog (along with the
-configured message).
-
-To use the configured profiles, they have to be configured in the respective connection in
-.IR ipsec.conf (5)
-by appending the profile name, separated by a colon, to the
-.B xauth-radius
-XAauth backend configuration in
-.I rightauth
-or
-.IR rightauth2 ,
-for instance,
-.IR rightauth2=xauth-radius:profile .
-.TP
-.BR charon.plugins.eap-sim.request_identity " [yes]"
-
-.TP
-.BR charon.plugins.eap-simaka-sql.database
-
-.TP
-.BR charon.plugins.eap-simaka-sql.remove_used " [no]"
-
-.TP
-.BR charon.plugins.eap-tls.fragment_size " [1024]"
-Maximum size of an EAP-TLS packet
-.TP
-.BR charon.plugins.eap-tls.max_message_count " [32]"
-Maximum number of processed EAP-TLS packets (0 = no limit)
-.TP
-.BR charon.plugins.eap-tls.include_length " [yes]"
-Include length in non-fragmented EAP-TLS packets
-.TP
-.BR charon.plugins.eap-tnc.max_message_count " [10]"
-Maximum number of processed EAP-TNC packets (0 = no limit)
-.TP
-.BR charon.plugins.eap-tnc.protocol " [tnccs-1.1]"
-IF-TNCCS protocol version to be used (tnccs-1.1, tnccs-2.0, tnccs-dynamic)
-.TP
-.BR charon.plugins.eap-ttls.fragment_size " [1024]"
-Maximum size of an EAP-TTLS packet
-.TP
-.BR charon.plugins.eap-ttls.max_message_count " [32]"
-Maximum number of processed EAP-TTLS packets (0 = no limit)
-.TP
-.BR charon.plugins.eap-ttls.include_length " [yes]"
-Include length in non-fragmented EAP-TTLS packets
-.TP
-.BR charon.plugins.eap-ttls.phase2_method " [md5]"
-Phase2 EAP client authentication method
-.TP
-.BR charon.plugins.eap-ttls.phase2_piggyback " [no]"
-Phase2 EAP Identity request piggybacked by server onto TLS Finished message
-.TP
-.BR charon.plugins.eap-ttls.phase2_tnc " [no]"
-Start phase2 EAP TNC protocol after successful client authentication
-.TP
-.BR charon.plugins.eap-ttls.request_peer_auth " [no]"
-Request peer authentication based on a client certificate
-.TP
-.BR charon.plugins.error-notify.socket " [unix://@piddir@/charon.enfy]"
-Socket provided by the error-notify plugin
-.TP
-.BR charon.plugins.gcrypt.quick_random " [no]"
-Use faster random numbers in gcrypt; for testing only, produces weak keys!
-.TP
-.BR charon.plugins.ha.autobalance " [0]"
-Interval in seconds to automatically balance handled segments between nodes.
-Set to 0 to disable.
-.TP
-.BR charon.plugins.ha.fifo_interface " [yes]"
-
-.TP
-.BR charon.plugins.ha.heartbeat_delay " [1000]"
-
-.TP
-.BR charon.plugins.ha.heartbeat_timeout " [2100]"
-
-.TP
-.BR charon.plugins.ha.local
-
-.TP
-.BR charon.plugins.ha.monitor " [yes]"
-
-.TP
-.BR charon.plugins.ha.pools
-
-.TP
-.BR charon.plugins.ha.remote
-
-.TP
-.BR charon.plugins.ha.resync " [yes]"
-
-.TP
-.BR charon.plugins.ha.secret
-
-.TP
-.BR charon.plugins.ha.segment_count " [1]"
-
-.TP
-.BR charon.plugins.ipseckey.enable " [no]"
-Enable fetching of IPSECKEY RRs via DNS
-.TP
-.BR charon.plugins.led.activity_led
-
-.TP
-.BR charon.plugins.led.blink_time " [50]"
-
-.TP
-.BR charon.plugins.kernel-klips.ipsec_dev_count " [4]"
-Number of ipsecN devices
-.TP
-.BR charon.plugins.kernel-klips.ipsec_dev_mtu " [0]"
-Set MTU of ipsecN device
-.TP
-.BR charon.plugins.kernel-libipsec.allow_peer_ts " [no]"
-Allow that the remote traffic selector equals the IKE peer. The route installed
-for such traffic (via TUN device) usually prevents further IKE traffic. The
-fwmark options for the \fIkernel-netlink\fR and \fIsocket-default\fR plugins can
-be used to circumvent that problem.
-.TP
-.BR charon.plugins.kernel-netlink.fwmark
-Firewall mark to set on the routing rule that directs traffic to our own routing
-table. The format is [!]mark[/mask], where the optional exclamation mark inverts
-the meaning (i.e. the rule only applies to packets that don't match the mark).
-.TP
-.BR charon.plugins.kernel-netlink.roam_events " [yes]"
-Whether to trigger roam events when interfaces, addresses or routes change
-.TP
-.BR charon.plugins.kernel-netlink.xfrm_acq_expires " [165]"
-Lifetime of XFRM acquire state in kernel. The value gets written to
-/proc/sys/net/core/xfrm_acq_expires. Indirectly controls the delay of XFRM
-acquire messages sent.
-.TP
-.BR charon.plugins.kernel-pfroute.vip_wait " [1000]"
-Time in ms to wait until virtual IP addresses appear/disappear before failing.
-.TP
-.BR charon.plugins.load-tester
-Section to configure the load-tester plugin, see LOAD TESTS
-.TP
-.BR charon.plugins.lookip.socket " [unix://@piddir@/charon.lkp]"
-Socket provided by the lookip plugin
-.TP
-.BR charon.plugins.ntru.max_drbg_requests " [4294967294]"
-Number of pseudo-random bit requests from the DRBG before an automatic
-reseeding occurs.
-.TP
-.BR charon.plugins.ntru.parameter_set " [optimum]"
-The following parameter sets are available:
-.BR x9_98_speed ,
-.BR x9_98_bandwidth ,
-.B x9_98_balance
-and
-.BR optimum ,
-the last set not being part of the X9.98 standard but having the best performance.
-.TP
-.BR charon.plugins.openssl.engine_id " [pkcs11]"
-ENGINE ID to use in the OpenSSL plugin
-.TP
-.BR charon.plugins.openssl.fips_mode " [0]"
-Set OpenSSL FIPS mode: disabled(0), enabled(1), Suite B enabled(2)
-.TP
-.BR charon.plugins.pkcs11.modules
-List of available PKCS#11 modules
-.TP
-.BR charon.plugins.pkcs11.load_certs " [yes]"
-Whether to load certificates from tokens
-.TP
-.BR charon.plugins.pkcs11.reload_certs " [no]"
-Reload certificates from all tokens if charon receives a SIGHUP
-.TP
-.BR charon.plugins.pkcs11.use_dh " [no]"
-Whether the PKCS#11 modules should be used for DH and ECDH (see use_ecc option)
-.TP
-.BR charon.plugins.pkcs11.use_ecc " [no]"
-Whether the PKCS#11 modules should be used for ECDH and ECDSA public key
-operations. ECDSA private keys can be used regardless of this option
-.TP
-.BR charon.plugins.pkcs11.use_hasher " [no]"
-Whether the PKCS#11 modules should be used to hash data
-.TP
-.BR charon.plugins.pkcs11.use_pubkey " [no]"
-Whether the PKCS#11 modules should be used for public key operations, even for
-keys not stored on tokens
-.TP
-.BR charon.plugins.pkcs11.use_rng " [no]"
-Whether the PKCS#11 modules should be used as RNG
-.TP
-.BR charon.plugins.radattr.dir
-Directory where RADIUS attributes are stored in client-ID specific files.
-.TP
-.BR charon.plugins.radattr.message_id " [-1]"
-Attributes are added to all IKE_AUTH messages by default (-1), or only to the
-IKE_AUTH message with the given IKEv2 message ID.
-.TP
-.BR charon.plugins.random.random " [@random_device@]"
-File to read random bytes from, instead of @random_device@
-.TP
-.BR charon.plugins.random.urandom " [@urandom_device@]"
-File to read pseudo random bytes from, instead of @urandom_device@
-.TP
-.BR charon.plugins.random.strong_equals_true " [no]"
-If set to yes the RNG_STRONG class reads random bytes from the same source as
-the RNG_TRUE class.
-.TP
-.BR charon.plugins.resolve.file " [/etc/resolv.conf]"
-File where to add DNS server entries
-.TP
-.BR charon.plugins.resolve.resolvconf.iface_prefix " [lo.inet.ipsec.]"
-Prefix used for interface names sent to resolvconf(8). The nameserver address
-is appended to this prefix to make it unique.  The result has to be a valid
-interface name according to the rules defined by resolvconf.  Also, it should
-have a high priority according to the order defined in interface-order(5).
-.TP
-.BR charon.plugins.socket-default.fwmark
-Firewall mark to set on outbound packets.
-.TP
-.BR charon.plugins.socket-default.set_source " [yes]"
-Set source address on outbound packets, if possible.
-.TP
-.BR charon.plugins.socket-default.use_ipv4 " [yes]"
-Listen on IPv4, if possible.
-.TP
-.BR charon.plugins.socket-default.use_ipv6 " [yes]"
-Listen on IPv6, if possible.
-.TP
-.BR charon.plugins.sql.database
-Database URI for charons SQL plugin
-.TP
-.BR charon.plugins.sql.loglevel " [-1]"
-Loglevel for logging to SQL database
-.TP
-.BR charon.plugins.stroke.ignore_missing_ca_basic_constraint " [no]"
-Treat certificates in ipsec.d/cacerts and ipsec.conf ca sections as CA
-certificates even if they don't contain a CA basic constraint.
-.TP
-.BR charon.plugins.stroke.max_concurrent " [4]"
-Maximum number of stroke messages handled concurrently
-.TP
-.BR charon.plugins.stroke.prevent_loglevel_changes " [no]"
-If enabled log level changes via stroke socket are not allowed.
-.TP
-.BR charon.plugins.stroke.socket " [unix://@piddir@/charon.ctl]"
-Socket provided by the stroke plugin
-.TP
-.BR charon.plugins.stroke.timeout " [0]"
-Timeout in ms for any stroke command. Use 0 to disable the timeout
-.TP
-.BR charon.plugins.systime-fix.interval " [0]"
-Interval in seconds to check system time for validity. 0 disables the check
-.TP
-.BR charon.plugins.systime-fix.reauth " [no]"
-Whether to use reauth or delete if an invalid cert lifetime is detected
-.TP
-.BR charon.plugins.systime-fix.threshold
-Threshold date where system time is considered valid. Disabled if not specified
-.TP
-.BR charon.plugins.systime-fix.threshold_format " [%Y]"
-strptime(3) format used to parse threshold option
-.TP
-.BR charon.plugins.tnc-ifmap.client_cert
-Path to X.509 certificate file of IF-MAP client
-.TP
-.BR charon.plugins.tnc-ifmap.client_key
-Path to private key file of IF-MAP client
-.TP
-.BR charon.plugins.tnc-ifmap.device_name
-Unique name of strongSwan server as a PEP and/or PDP device
-.TP
-.BR charon.plugins.tnc-ifmap.renew_session_interval " [150]"
-Interval in seconds between periodic IF-MAP RenewSession requests
-.TP
-.BR charon.plugins.tnc-ifmap.server_uri " [https://localhost:8444/imap]"
-URI of the form [https://]servername[:port][/path]
-.TP
-.BR charon.plugins.tnc-ifmap.server_cert
-Path to X.509 certificate file of IF-MAP server
-.TP
-.BR charon.plugins.tnc-ifmap.username_password
-Credentials of IF-MAP client of the form username:password
-.TP
-.BR charon.plugins.tnc-pdp.pt_tls.enable " [yes]"
-Enable PT-TLS protocol on the strongSwan PDP
-.TP
-.BR charon.plugins.tnc-pdp.pt_tls.port " [271]"
-PT-TLS server port the strongSwan PDP is listening on
-.TP
-.BR charon.plugins.tnc-pdp.radius.enable " [yes]"
-Enable RADIUS protocol on the strongSwan PDP
-.TP
-.BR charon.plugins.tnc-pdp.radius.method " [ttls]"
-EAP tunnel method to be used
-.TP
-.BR charon.plugins.tnc-pdp.radius.port " [1812]"
-RADIUS server port the strongSwan PDP is listening on
-.TP
-.BR charon.plugins.tnc-pdp.radius.secret
-Shared RADIUS secret between strongSwan PDP and NAS
-.TP
-.BR charon.plugins.tnc-pdp.server
-Name of the strongSwan PDP as contained in the AAA certificate
-.TP
-.BR charon.plugins.tnc-pdp.timeout
-Timeout in seconds before closing incomplete connections
-.TP
-.BR charon.plugins.unbound.resolv_conf " [/etc/resolv.conf]"
-File to read DNS resolver configuration from
-.TP
-.BR charon.plugins.unbound.trust_anchors " [/etc/ipsec.d/dnssec.keys]"
-File to read DNSSEC trust anchors from (usually root zone KSK). The format of
-the file is the standard DNS Zone file format, anchors can be stored as DS or
-DNSKEY entries in the file.
-.TP
-.BR charon.plugins.unbound.dlv_anchors
-File to read trusted keys for DLV (DNSSEC Lookaside Validation) from. It uses
-the same format as \fItrust_anchors\fR. Only one DLV can be configured, which
-is then used as a root trusted DLV, this means that it is a lookaside for
-the root.
-.TP
-.BR charon.plugins.updown.dns_handler " [no]"
-Whether the updown script should handle DNS serves assigned via IKEv1 Mode
-Config or IKEv2 Config Payloads (if enabled they can't be handled by other
-plugins, like resolve)
-.TP
-.BR charon.plugins.whitelist.enable " [yes]"
-Enable loaded whitelist plugin
-.TP
-.BR charon.plugins.whitelist.socket " [unix://@piddir@/charon.wlst]"
-Socket provided by the whitelist plugin
-.TP
-.BR charon.plugins.xauth-eap.backend " [radius]"
-EAP plugin to be used as backend for XAuth credential verification
-.TP
-.BR charon.plugins.xauth-pam.pam_service " [login]"
-PAM service to be used for authentication
-.TP
-.BR charon.plugins.xauth-pam.session " [no]"
-Open/close a PAM session for each active IKE_SA
-.TP
-.BR charon.plugins.xauth-pam.trim_email " [yes]"
-If an email address is given as an XAuth username, trim it to just the
-username part.
-.SS libtnccs section
-.TP
-.BR libtnccs.tnc_config " [/etc/tnc_config]"
-TNC IMC/IMV configuration directory
-.PP
-.SS libtnccs plugins section
-.TP
-.BR libtnccs.plugins.tnccs-11.max_message_size " [45000]"
-Maximum size of a PA-TNC message (XML & Base64 encoding)
-.TP
-.BR libtnccs.plugins.tnccs-20.max_batch_size " [65522]"
-Maximum size of a PB-TNC batch (upper limit via PT-EAP = 65529)
-.TP
-.BR libtnccs.plugins.tnccs-20.max_message_size " [65490]"
-Maximum size of a PA-TNC message (upper limit via PT-EAP = 65497)
-.TP
-.BR libtnccs.plugins.tnc-imc.dlclose " [yes]"
-Unload IMC after use
-.TP
-.BR libtnccs.plugins.tnc-imc.preferred_language " [en]"
-Preferred language for TNC recommendations
-.TP
-.BR libtnccs.plugins.tnc-imv.dlclose " [yes]"
-Unload IMV after use
-.SS libimcv section
-.TP
-.BR libimcv.assessment_result " [yes]"
-Whether IMVs send a standard IETF Assessment Result attribute
-.TP
-.BR libimcv.database
-Global IMV policy database URI
-.TP
-.BR libimcv.debug_level " [1]"
-Debug level for a stand-alone libimcv library
-.TP
-.BR libimcv.load " [random nonce gmp pubkey x509]"
-Plugins to load in IMC/IMVs
-.TP
-.BR libimcv.os_info.name
-Manually set the name of the client OS (e.g. Ubuntu)
-.TP
-.BR libimcv.os_info.version
-Manually set the version of the client OS (e.g. 12.04 i686)
-.TP
-.BR libimcv.policy_script " [ipsec _imv_policy]"
-Script called for each TNC connection to generate IMV policies
-.TP
-.BR libimcv.stderr_quiet " [no]"
-isable output to stderr with a stand-alone libimcv library
-.PP
-.SS libimcv plugins section
-.TP
-.BR libimcv.plugins.imc-attestation.aik_blob
-AIK encrypted private key blob file
-.TP
-.BR libimcv.plugins.imc-attestation.aik_cert
-AIK certificate file
-.TP
-.BR libimcv.plugins.imc-attestation.aik_key
-AIK public key file
-.TP
-.BR libimcv.plugins.imv-attestation.nonce_len " [20]"
-DH nonce length
-.TP
-.BR libimcv.plugins.imv-attestation.use_quote2 " [yes]"
-Use Quote2 AIK signature instead of Quote signature
-.TP
-.BR libimcv.plugins.imv-attestation.cadir
-Path to directory with AIK cacerts
-.TP
-.BR libimcv.plugins.imv-attestation.dh_group " [ecp256]"
-Preferred Diffie-Hellman group
-.TP
-.BR libimcv.plugins.imv-attestation.hash_algorithm " [sha256]"
-Preferred measurement hash algorithm
-.TP
-.BR libimcv.plugins.imv-attestation.min_nonce_len " [0]"
-DH minimum nonce length
-.TP
-.BR libimcv.plugins.imv-attestation.remediation_uri
-URI pointing to attestation remediation instructions
-.TP
-.BR libimcv.plugins.imc-os.push_info " [yes]"
-Send operating system info without being prompted
-.TP
-.BR libimcv.plugins.imv-os.remediation_uri
-URI pointing to operating system remediation instructions
-.TP
-.BR libimcv.plugins.imc-scanner.push_info " [yes]"
-Send open listening ports without being prompted
-.TP
-.BR libimcv.plugins.imv-scanner.remediation_uri
-URI pointing to scanner remediation instructions
-.TP
-.BR libimcv.plugins.imc-swid.swid_directory " [@prefix@/share]"
-Directory where SWID tags are located
-.TP
-.BR libimcv.plugins.imc-test.additional_ids " [0]"
-Number of additional IMC IDs
-.TP
-.BR libimcv.plugins.imc-test.command " [none]"
-Command to be sent to the Test IMV
-.TP
-.BR libimcv.plugins.imc-test.dummy_size " [0]"
-Size of dummy attribute to be sent to the Test IMV (0 = disabled)
-.TP
-.BR libimcv.plugins.imv-test.remediation_uri
-URI pointing to test remediation instructions
-.TP
-.BR libimcv.plugins.imc-test.retry " [no]"
-Do a handshake retry
-.TP
-.BR libimcv.plugins.imc-test.retry_command
-Command to be sent to the Test IMV in the handshake retry
-.TP
-.BR libimcv.plugins.imv-test.rounds " [0]"
-Number of IMC-IMV retry rounds
-.SS manager section
-.TP
-.BR manager.database
-Credential database URI for manager
-.TP
-.BR manager.debug " [no]"
-Enable debugging in manager
-.TP
-.BR manager.load
-Plugins to load in manager
-.TP
-.BR manager.socket
-FastCGI socket of manager, to run it statically
-.TP
-.BR manager.threads " [10]"
-Threads to use for request handling
-.TP
-.BR manager.timeout " [15m]"
-Session timeout for manager
-.SS mediation client section
-.TP
-.BR medcli.database
-Mediation client database URI
-.TP
-.BR medcli.dpd " [5m]"
-DPD timeout to use in mediation client plugin
-.TP
-.BR medcli.rekey " [20m]"
-Rekeying time on mediation connections in mediation client plugin
-.SS mediation server section
-.TP
-.BR medsrv.database
-Mediation server database URI
-.TP
-.BR medsrv.debug " [no]"
-Debugging in mediation server web application
-.TP
-.BR medsrv.dpd " [5m]"
-DPD timeout to use in mediation server plugin
-.TP
-.BR medsrv.load
-Plugins to load in mediation server plugin
-.TP
-.BR medsrv.password_length " [6]"
-Minimum password length required for mediation server user accounts
-.TP
-.BR medsrv.rekey " [20m]"
-Rekeying time on mediation connections in mediation server plugin
-.TP
-.BR medsrv.socket
-Run Mediation server web application statically on socket
-.TP
-.BR medsrv.threads " [5]"
-Number of thread for mediation service web application
-.TP
-.BR medsrv.timeout " [15m]"
-Session timeout for mediation service
-.SS openac section
-.TP
-.BR openac.load
-Plugins to load in ipsec openac tool
-.SS pacman section
-.TP
-.BR pacman.database
-Database URI for the database that stores the package information
-.SS pki section
-.TP
-.BR pki.load
-Plugins to load in ipsec pki tool
-.SS pool section
-.TP
-.BR pool.load
-Plugins to load in ipsec pool tool
-.SS pt-tls-client section
-.TP
-.BR pt-tls-client.load
-Plugins to load in ipsec pt-tls-client tool
-.SS scepclient section
-.TP
-.BR scepclient.load
-Plugins to load in ipsec scepclient tool
-.SS starter section
-.TP
-.BR starter.load
-Plugins to load in starter
-.TP
-.BR starter.load_warning " [yes]"
-Disable charon plugin load option warning
-
-.SH LOGGER CONFIGURATION
-The options described below provide a much more flexible way to configure
-loggers for the IKEv2 daemon charon than using the
-.B charondebug
-option in
-.BR ipsec.conf (5).
-.PP
-.B Please note
-that if any loggers are specified in strongswan.conf,
-.B charondebug
-does not have any effect.
-.PP
-There are currently two types of loggers defined:
-.TP
-.B File loggers
-Log directly to a file and are defined by specifying the full path to the
-file as subsection in the
-.B charon.filelog
-section. To log to the console the two special filenames
-.BR stdout " and " stderr
-can be used.
-.TP
-.B Syslog loggers
-Log into a syslog facility and are defined by specifying the facility to log to
-as the name of a subsection in the
-.B charon.syslog
-section. The following facilities are currently supported:
-.BR daemon " and " auth .
-.PP
-Multiple loggers can be defined for each type with different log verbosity for
-the different subsystems of the daemon.
-.SS Options
-.TP
-.BR charon.filelog.<filename>.default " [1]"
-.TQ
-.BR charon.syslog.<facility>.default
-Specifies the default loglevel to be used for subsystems for which no specific
-loglevel is defined.
-.TP
-.BR charon.filelog.<filename>.<subsystem> " [<default>]"
-.TQ
-.BR charon.syslog.<facility>.<subsystem>
-Specifies the loglevel for the given subsystem.
-.TP
-.BR charon.filelog.<filename>.append " [yes]"
-If this option is enabled log entries are appended to the existing file.
-.TP
-.BR charon.filelog.<filename>.flush_line " [no]"
-Enabling this option disables block buffering and enables line buffering.
-.TP
-.BR charon.filelog.<filename>.ike_name " [no]"
-.TQ
-.BR charon.syslog.<facility>.ike_name
-Prefix each log entry with the connection name and a unique numerical
-identifier for each IKE_SA.
-.TP
-.BR charon.filelog.<filename>.time_format
-Prefix each log entry with a timestamp. The option accepts a format string as
-passed to
-.BR strftime (3).
-.TP
-.BR charon.syslog.identifier
-Global identifier used for an
-.BR openlog (3)
-call, prepended to each log message by syslog.  If not configured,
-.BR openlog (3)
-is not called, so the value will depend on system defaults (often the program
-name).
-
-.SS Subsystems
-.TP
-.B dmn
-Main daemon setup/cleanup/signal handling
-.TP
-.B mgr
-IKE_SA manager, handling synchronization for IKE_SA access
-.TP
-.B ike
-IKE_SA
-.TP
-.B chd
-CHILD_SA
-.TP
-.B job
-Jobs queueing/processing and thread pool management
-.TP
-.B cfg
-Configuration management and plugins
-.TP
-.B knl
-IPsec/Networking kernel interface
-.TP
-.B net
-IKE network communication
-.TP
-.B asn
-Low-level encoding/decoding (ASN.1, X.509 etc.)
-.TP
-.B enc
-Packet encoding/decoding encryption/decryption operations
-.TP
-.B tls
-libtls library messages
-.TP
-.B esp
-libipsec library messages
-.TP
-.B lib
-libstrongwan library messages
-.TP
-.B tnc
-Trusted Network Connect
-.TP
-.B imc
-Integrity Measurement Collector
-.TP
-.B imv
-Integrity Measurement Verifier
-.TP
-.B pts
-Platform Trust Service
-.SS Loglevels
-.TP
-.B -1
-Absolutely silent
-.TP
-.B 0
-Very basic auditing logs, (e.g. SA up/SA down)
-.TP
-.B 1
-Generic control flow with errors, a good default to see whats going on
-.TP
-.B 2
-More detailed debugging control flow
-.TP
-.B 3
-Including RAW data dumps in Hex
-.TP
-.B 4
-Also include sensitive material in dumps, e.g. keys
-.SS Example
-.PP
-.EX
-       charon {
-               filelog {
-                       /var/log/charon.log {
-                               time_format = %b %e %T
-                               append = no
-                               default = 1
-                       }
-                       stderr {
-                               ike = 2
-                               knl = 3
-                               ike_name = yes
-                       }
-               }
-               syslog {
-                       # enable logging to LOG_DAEMON, use defaults
-                       daemon {
-                       }
-                       # minimalistic IKE auditing logging to LOG_AUTHPRIV
-                       auth {
-                               default = -1
-                               ike = 0
-                       }
-               }
-       }
-.EE
-
-.SH JOB PRIORITY MANAGEMENT
-Some operations in the IKEv2 daemon charon are currently implemented
-synchronously and blocking. Two examples for such operations are communication
-with a RADIUS server via EAP-RADIUS, or fetching CRL/OCSP information during
-certificate chain verification. Under high load conditions, the thread pool may
-run out of available threads, and some more important jobs, such as liveness
-checking, may not get executed in time.
-.PP
-To prevent thread starvation in such situations job priorities were introduced.
-The job processor will reserve some threads for higher priority jobs, these
-threads are not available for lower priority, locking jobs.
-.SS Implementation
-Currently 4 priorities have been defined, and they are used in charon as
-follows:
-.TP
-.B CRITICAL
-Priority for long-running dispatcher jobs.
-.TP
-.B HIGH
-INFORMATIONAL exchanges, as used by liveness checking (DPD).
-.TP
-.B MEDIUM
-Everything not HIGH/LOW, including IKE_SA_INIT processing.
-.TP
-.B LOW
-IKE_AUTH message processing. RADIUS and CRL fetching block here
-.PP
-Although IKE_SA_INIT processing is computationally expensive, it is explicitly
-assigned to the MEDIUM class. This allows charon to do the DH exchange while
-other threads are blocked in IKE_AUTH. To prevent the daemon from accepting more
-IKE_SA_INIT requests than it can handle, use IKE_SA_INIT DROPPING.
-.PP
-The thread pool processes jobs strictly by priority, meaning it will consume all
-higher priority jobs before looking for ones with lower priority. Further, it
-reserves threads for certain priorities. A priority class having reserved
-.I n
-threads will always have
-.I n
-threads available for this class (either currently processing a job, or waiting
-for one).
-.SS Configuration
-To ensure that there are always enough threads available for higher priority
-tasks, threads must be reserved for each priority class.
-.TP
-.BR charon.processor.priority_threads.critical " [0]"
-Threads reserved for CRITICAL priority class jobs
-.TP
-.BR charon.processor.priority_threads.high " [0]"
-Threads reserved for HIGH priority class jobs
-.TP
-.BR charon.processor.priority_threads.medium " [0]"
-Threads reserved for MEDIUM priority class jobs
-.TP
-.BR charon.processor.priority_threads.low " [0]"
-Threads reserved for LOW priority class jobs
-.PP
-Let's consider the following configuration:
-.PP
-.EX
-       charon {
-               processor {
-                       priority_threads {
-                               high = 1
-                               medium = 4
-                       }
-               }
-       }
-.EE
-.PP
-With this configuration, one thread is reserved for HIGH priority tasks. As
-currently only liveness checking and stroke message processing is done with
-high priority, one or two threads should be sufficient.
-.PP
-The MEDIUM class mostly processes non-blocking jobs. Unless your setup is
-experiencing many blocks in locks while accessing shared resources, threads for
-one or two times the number of CPU cores is fine.
-.PP
-It is usually not required to reserve threads for CRITICAL jobs. Jobs in this
-class rarely return and do not release their thread to the pool.
-.PP
-The remaining threads are available for LOW priority jobs. Reserving threads
-does not make sense (until we have an even lower priority).
-.SS Monitoring
-To see what the threads are actually doing, invoke
-.IR "ipsec statusall" .
-Under high load, something like this will show up:
-.PP
-.EX
-       worker threads: 2 or 32 idle, 5/1/2/22 working,
-               job queue: 0/0/1/149, scheduled: 198
-.EE
-.PP
-From 32 worker threads,
-.IP 2
-are currently idle.
-.IP 5
-are running CRITICAL priority jobs (dispatching from sockets, etc.).
-.IP 1
-is currently handling a HIGH priority job. This is actually the thread currently
-providing this information via stroke.
-.IP 2
-are handling MEDIUM priority jobs, likely IKE_SA_INIT or CREATE_CHILD_SA
-messages.
-.IP 22
-are handling LOW priority jobs, probably waiting for an EAP-RADIUS response
-while processing IKE_AUTH messages.
-.PP
-The job queue load shows how many jobs are queued for each priority, ready for
-execution. The single MEDIUM priority job will get executed immediately, as
-we have two spare threads reserved for MEDIUM class jobs.
-
-.SH IKE_SA_INIT DROPPING
-If a responder receives more connection requests per seconds than it can handle,
-it does not make sense to accept more IKE_SA_INIT messages. And if they are
-queued but can't get processed in time, an answer might be sent after the
-client has already given up and restarted its connection setup. This
-additionally increases the load on the responder.
-.PP
-To limit the responder load resulting from new connection attempts, the daemon
-can drop IKE_SA_INIT messages just after reception. There are two mechanisms to
-decide if this should happen, configured with the following options:
-.TP
-.BR charon.init_limit_half_open " [0]"
-Limit based on the number of half open IKE_SAs. Half open IKE_SAs are SAs in
-connecting state, but not yet established.
-.TP
-.BR charon.init_limit_job_load " [0]"
-Limit based on the number of jobs currently queued for processing (sum over all
-job priorities).
-.PP
-The second limit includes load from other jobs, such as rekeying. Choosing a
-good value is difficult and depends on the hardware and expected load.
-.PP
-The first limit is simpler to calculate, but includes the load from new
-connections only. If your responder is capable of negotiating 100 tunnels/s, you
-might set this limit to 1000. The daemon will then drop new connection attempts
-if generating a response would require more than 10 seconds. If you are
-allowing for a maximum response time of more than 30 seconds, consider adjusting
-the timeout for connecting IKE_SAs
-.RB ( charon.half_open_timeout ).
-A responder, by default, deletes an IKE_SA if the initiator does not establish
-it within 30 seconds. Under high load, a higher value might be required.
-
-.SH LOAD TESTS
-To do stability testing and performance optimizations, the IKEv2 daemon charon
-provides the load-tester plugin. This plugin allows one to setup thousands of
-tunnels concurrently against the daemon itself or a remote host.
-.PP
-.B WARNING:
-Never enable the load-testing plugin on productive systems. It provides
-preconfigured credentials and allows an attacker to authenticate as any user.
-.SS Options
-.TP
-.BR charon.plugins.load-tester.addrs
-Subsection that contains key/value pairs with address pools (in CIDR notation)
-to use for a specific network interface e.g. eth0 = 10.10.0.0/16
-.TP
-.BR charon.plugins.load-tester.addrs_keep " [no]"
-Whether to keep dynamic addresses even after the associated SA got terminated
-.TP
-.BR charon.plugins.load-tester.addrs_prefix " [16]"
-Network prefix length to use when installing dynamic addresses. If set to -1 the
-full address is used (i.e. 32 or 128)
-.TP
-.BR charon.plugins.load-tester.ca_dir
-Directory to load (intermediate) CA certificates from
-.TP
-.BR charon.plugins.load-tester.child_rekey " [600]"
-Seconds to start CHILD_SA rekeying after setup
-.TP
-.BR charon.plugins.load-tester.delay " [0]"
-Delay between initiatons for each thread
-.TP
-.BR charon.plugins.load-tester.delete_after_established " [no]"
-Delete an IKE_SA as soon as it has been established
-.TP
-.BR charon.plugins.load-tester.digest " [sha1]"
-Digest algorithm used when issuing certificates
-.TP
-.BR charon.plugins.load-tester.dpd_delay " [0]"
-DPD delay to use in load test
-.TP
-.BR charon.plugins.load-tester.dynamic_port " [0]"
-Base port to be used for requests (each client uses a different port)
-.TP
-.BR charon.plugins.load-tester.eap_password " [default-pwd]"
-EAP secret to use in load test
-.TP
-.BR charon.plugins.load-tester.enable " [no]"
-Enable the load testing plugin
-.TP
-.BR charon.plugins.load-tester.esp " [aes128-sha1]"
-CHILD_SA proposal to use for load tests
-.TP
-.BR charon.plugins.load-tester.fake_kernel " [no]"
-Fake the kernel interface to allow load-testing against self
-.TP
-.BR charon.plugins.load-tester.ike_rekey " [0]"
-Seconds to start IKE_SA rekeying after setup
-.TP
-.BR charon.plugins.load-tester.init_limit " [0]"
-Global limit of concurrently established SAs during load test
-.TP
-.BR charon.plugins.load-tester.initiator " [0.0.0.0]"
-Address to initiate from
-.TP
-.BR charon.plugins.load-tester.initiators " [0]"
-Number of concurrent initiator threads to use in load test
-.TP
-.BR charon.plugins.load-tester.initiator_auth " [pubkey]"
-Authentication method(s) the intiator uses
-.TP
-.BR charon.plugins.load-tester.initiator_id
-Initiator ID used in load test
-.TP
-.BR charon.plugins.load-tester.initiator_match
-Initiator ID to match against as responder
-.TP
-.BR charon.plugins.load-tester.initiator_tsi
-Traffic selector on initiator side, as proposed by initiator
-.TP
-.BR charon.plugins.load-tester.initiator_tsr
-Traffic selector on responder side, as proposed by initiator
-.TP
-.BR charon.plugins.load-tester.iterations " [1]"
-Number of IKE_SAs to initiate by each initiator in load test
-.TP
-.BR charon.plugins.load-tester.issuer_cert
-Path to the issuer certificate (if not configured a hard-coded value is used)
-.TP
-.BR charon.plugins.load-tester.issuer_key
-Path to private key that is used to issue certificates (if not configured a
-hard-coded value is used)
-.TP
-.BR charon.plugins.load-tester.mode " [tunnel]"
-IPsec mode to use, one of \fBtunnel\fR, \fBtransport\fR, or \fBbeet\fR.
-.TP
-.BR charon.plugins.load-tester.pool
-Provide INTERNAL_IPV4_ADDRs from a named pool
-.TP
-.BR charon.plugins.load-tester.preshared_key " [default-psk]"
-Preshared key to use in load test
-.TP
-.BR charon.plugins.load-tester.proposal " [aes128-sha1-modp768]"
-IKE proposal to use in load test
-.TP
-.BR charon.plugins.load-tester.responder " [127.0.0.1]"
-Address to initiation connections to
-.TP
-.BR charon.plugins.load-tester.responder_auth " [pubkey]"
-Authentication method(s) the responder uses
-.TP
-.BR charon.plugins.load-tester.responder_id
-Responder ID used in load test
-.TP
-.BR charon.plugins.load-tester.responder_tsi " [initiator_tsi]"
-Traffic selector on initiator side, as narrowed by responder
-.TP
-.BR charon.plugins.load-tester.responder_tsr " [initiator_tsr]"
-Traffic selector on responder side, as narrowed by responder
-.TP
-.BR charon.plugins.load-tester.request_virtual_ip " [no]"
-Request an INTERNAL_IPV4_ADDR from the server
-.TP
-.BR charon.plugins.load-tester.shutdown_when_complete " [no]"
-Shutdown the daemon after all IKE_SAs have been established
-.TP
-.BR charon.plugins.load-tester.socket " [unix://@piddir@/charon.ldt]"
-Socket provided by the load-tester plugin
-.TP
-.BR charon.plugins.load-tester.version " [0]"
-IKE version to use (0 means use IKEv2 as initiator and accept any version as
-responder)
-.PP
-.SS Configuration details
-For public key authentication, the responder uses the
-.B \(dqCN=srv, OU=load-test, O=strongSwan\(dq
-identity. For the initiator, each connection attempt uses a different identity
-in the form
-.BR "\(dqCN=c1-r1, OU=load-test, O=strongSwan\(dq" ,
-where the first number inidicates the client number, the second the
-authentication round (if multiple authentication is used).
-.PP
-For PSK authentication, FQDN identities are used. The server uses
-.BR srv.strongswan.org ,
-the client uses an identity in the form
-.BR c1-r1.strongswan.org .
-.PP
-For EAP authentication, the client uses a NAI in the form
-.BR 100000000010001@strongswan.org .
-.PP
-To configure multiple authentication, concatenate multiple methods using, e.g.
-.EX
-       initiator_auth = pubkey|psk|eap-md5|eap-aka
-.EE
-.PP
-The responder uses a hardcoded certificate based on a 1024-bit RSA key.
-This certificate additionally serves as CA certificate. A peer uses the same
-private key, but generates client certificates on demand signed by the CA
-certificate. Install the Responder/CA certificate on the remote host to
-authenticate all clients.
-.PP
-To speed up testing, the load tester plugin implements a special Diffie-Hellman
-implementation called modpnull. By setting
-.EX
-       proposal = aes128-sha1-modpnull
-.EE
-this wicked fast DH implementation is used. It does not provide any security
-at all, but allows one to run tests without DH calculation overhead.
-.SS Examples
-.PP
-In the simplest case, the daemon initiates IKE_SAs against itself using the
-loopback interface. This will actually establish double the number of IKE_SAs,
-as the daemon is initiator and responder for each IKE_SA at the same time.
-Installation of IPsec SAs would fails, as each SA gets installed twice. To
-simulate the correct behavior, a fake kernel interface can be enabled which does
-not install the IPsec SAs at the kernel level.
-.PP
-A simple loopback configuration might look like this:
-.PP
-.EX
-       charon {
-               # create new IKE_SAs for each CHILD_SA to simulate
-               # different clients
-               reuse_ikesa = no
-               # turn off denial of service protection
-               dos_protection = no
-
-               plugins {
-                       load-tester {
-                               # enable the plugin
-                               enable = yes
-                               # use 4 threads to initiate connections
-                               # simultaneously
-                               initiators = 4
-                               # each thread initiates 1000 connections
-                               iterations = 1000
-                               # delay each initiation in each thread by 20ms
-                               delay = 20
-                               # enable the fake kernel interface to
-                               # avoid SA conflicts
-                               fake_kernel = yes
-                       }
-               }
-       }
-.EE
-.PP
-This will initiate 4000 IKE_SAs within 20 seconds. You may increase the delay
-value if your box can not handle that much load, or decrease it to put more
-load on it. If the daemon starts retransmitting messages your box probably can
-not handle all connection attempts.
-.PP
-The plugin also allows one to test against a remote host. This might help to
-test against a real world configuration. A connection setup to do stress
-testing of a gateway might look like this:
-.PP
-.EX
-       charon {
-               reuse_ikesa = no
-               threads = 32
-
-               plugins {
-                       load-tester {
-                               enable = yes
-                               # 10000 connections, ten in parallel
-                               initiators = 10
-                               iterations = 1000
-                               # use a delay of 100ms, overall time is:
-                               # iterations * delay = 100s
-                               delay = 100
-                               # address of the gateway
-                               remote = 1.2.3.4
-                               # IKE-proposal to use
-                               proposal = aes128-sha1-modp1024
-                               # use faster PSK authentication instead
-                               # of 1024bit RSA
-                               initiator_auth = psk
-                               responder_auth = psk
-                               # request a virtual IP using configuration
-                               # payloads
-                               request_virtual_ip = yes
-                               # enable CHILD_SA every 60s
-                               child_rekey = 60
-                       }
-               }
-       }
-.EE
-
-.SH IKEv2 RETRANSMISSION
-Retransmission timeouts in the IKEv2 daemon charon can be configured globally
-using the three keys listed below:
-.PP
-.RS
-.nf
-.BR charon.retransmit_base " [1.8]"
-.BR charon.retransmit_timeout " [4.0]"
-.BR charon.retransmit_tries " [5]"
-.fi
-.RE
-.PP
-The following algorithm is used to calculate the timeout:
-.PP
-.EX
-       relative timeout = retransmit_timeout * retransmit_base ^ (n-1)
-.EE
-.PP
-Where
-.I n
-is the current retransmission count.
-.PP
-Using the default values, packets are retransmitted in:
-
-.TS
-l r r
----
-lB r r.
-Retransmission Relative Timeout        Absolute Timeout
-1      4s      4s
-2      7s      11s
-3      13s     24s
-4      23s     47s
-5      42s     89s
-giving up      76s     165s
-.TE
-
-.SH FILES
-/etc/strongswan.conf
-
-.SH SEE ALSO
-\fBipsec.conf\fR(5), \fBipsec.secrets\fR(5), \fBipsec\fR(8), \fBcharon-cmd\fR(8)
-
-.SH HISTORY
-Written for the
-.UR http://www.strongswan.org
-strongSwan project
-.UE
-by Tobias Brunner, Andreas Steffen and Martin Willi.
diff --git a/conf/strongswan.conf.5.tail.in b/conf/strongswan.conf.5.tail.in
new file mode 100644 (file)
index 0000000..29b842c
--- /dev/null
@@ -0,0 +1,606 @@
+.SH LOGGER CONFIGURATION
+The options described below provide a much more flexible way to configure
+loggers for the IKEv2 daemon charon than using the
+.B charondebug
+option in
+.BR ipsec.conf (5).
+.PP
+.B Please note
+that if any loggers are specified in strongswan.conf,
+.B charondebug
+does not have any effect.
+.PP
+There are currently two types of loggers defined:
+.TP
+.B File loggers
+Log directly to a file and are defined by specifying the full path to the
+file as subsection in the
+.B charon.filelog
+section. To log to the console the two special filenames
+.BR stdout " and " stderr
+can be used.
+.TP
+.B Syslog loggers
+Log into a syslog facility and are defined by specifying the facility to log to
+as the name of a subsection in the
+.B charon.syslog
+section. The following facilities are currently supported:
+.BR daemon " and " auth .
+.PP
+Multiple loggers can be defined for each type with different log verbosity for
+the different subsystems of the daemon.
+.SS Options
+.TP
+.BR charon.filelog.<filename>.default " [1]"
+.TQ
+.BR charon.syslog.<facility>.default
+Specifies the default loglevel to be used for subsystems for which no specific
+loglevel is defined.
+.TP
+.BR charon.filelog.<filename>.<subsystem> " [<default>]"
+.TQ
+.BR charon.syslog.<facility>.<subsystem>
+Specifies the loglevel for the given subsystem.
+.TP
+.BR charon.filelog.<filename>.append " [yes]"
+If this option is enabled log entries are appended to the existing file.
+.TP
+.BR charon.filelog.<filename>.flush_line " [no]"
+Enabling this option disables block buffering and enables line buffering.
+.TP
+.BR charon.filelog.<filename>.ike_name " [no]"
+.TQ
+.BR charon.syslog.<facility>.ike_name
+Prefix each log entry with the connection name and a unique numerical
+identifier for each IKE_SA.
+.TP
+.BR charon.filelog.<filename>.time_format
+Prefix each log entry with a timestamp. The option accepts a format string as
+passed to
+.BR strftime (3).
+.TP
+.BR charon.syslog.identifier
+Global identifier used for an
+.BR openlog (3)
+call, prepended to each log message by syslog.  If not configured,
+.BR openlog (3)
+is not called, so the value will depend on system defaults (often the program
+name).
+
+.SS Subsystems
+.TP
+.B dmn
+Main daemon setup/cleanup/signal handling
+.TP
+.B mgr
+IKE_SA manager, handling synchronization for IKE_SA access
+.TP
+.B ike
+IKE_SA
+.TP
+.B chd
+CHILD_SA
+.TP
+.B job
+Jobs queueing/processing and thread pool management
+.TP
+.B cfg
+Configuration management and plugins
+.TP
+.B knl
+IPsec/Networking kernel interface
+.TP
+.B net
+IKE network communication
+.TP
+.B asn
+Low-level encoding/decoding (ASN.1, X.509 etc.)
+.TP
+.B enc
+Packet encoding/decoding encryption/decryption operations
+.TP
+.B tls
+libtls library messages
+.TP
+.B esp
+libipsec library messages
+.TP
+.B lib
+libstrongwan library messages
+.TP
+.B tnc
+Trusted Network Connect
+.TP
+.B imc
+Integrity Measurement Collector
+.TP
+.B imv
+Integrity Measurement Verifier
+.TP
+.B pts
+Platform Trust Service
+.SS Loglevels
+.TP
+.B -1
+Absolutely silent
+.TP
+.B 0
+Very basic auditing logs, (e.g. SA up/SA down)
+.TP
+.B 1
+Generic control flow with errors, a good default to see whats going on
+.TP
+.B 2
+More detailed debugging control flow
+.TP
+.B 3
+Including RAW data dumps in Hex
+.TP
+.B 4
+Also include sensitive material in dumps, e.g. keys
+.SS Example
+.PP
+.EX
+       charon {
+               filelog {
+                       /var/log/charon.log {
+                               time_format = %b %e %T
+                               append = no
+                               default = 1
+                       }
+                       stderr {
+                               ike = 2
+                               knl = 3
+                               ike_name = yes
+                       }
+               }
+               syslog {
+                       # enable logging to LOG_DAEMON, use defaults
+                       daemon {
+                       }
+                       # minimalistic IKE auditing logging to LOG_AUTHPRIV
+                       auth {
+                               default = -1
+                               ike = 0
+                       }
+               }
+       }
+.EE
+
+.SH JOB PRIORITY MANAGEMENT
+Some operations in the IKEv2 daemon charon are currently implemented
+synchronously and blocking. Two examples for such operations are communication
+with a RADIUS server via EAP-RADIUS, or fetching CRL/OCSP information during
+certificate chain verification. Under high load conditions, the thread pool may
+run out of available threads, and some more important jobs, such as liveness
+checking, may not get executed in time.
+.PP
+To prevent thread starvation in such situations job priorities were introduced.
+The job processor will reserve some threads for higher priority jobs, these
+threads are not available for lower priority, locking jobs.
+.SS Implementation
+Currently 4 priorities have been defined, and they are used in charon as
+follows:
+.TP
+.B CRITICAL
+Priority for long-running dispatcher jobs.
+.TP
+.B HIGH
+INFORMATIONAL exchanges, as used by liveness checking (DPD).
+.TP
+.B MEDIUM
+Everything not HIGH/LOW, including IKE_SA_INIT processing.
+.TP
+.B LOW
+IKE_AUTH message processing. RADIUS and CRL fetching block here
+.PP
+Although IKE_SA_INIT processing is computationally expensive, it is explicitly
+assigned to the MEDIUM class. This allows charon to do the DH exchange while
+other threads are blocked in IKE_AUTH. To prevent the daemon from accepting more
+IKE_SA_INIT requests than it can handle, use IKE_SA_INIT DROPPING.
+.PP
+The thread pool processes jobs strictly by priority, meaning it will consume all
+higher priority jobs before looking for ones with lower priority. Further, it
+reserves threads for certain priorities. A priority class having reserved
+.I n
+threads will always have
+.I n
+threads available for this class (either currently processing a job, or waiting
+for one).
+.SS Configuration
+To ensure that there are always enough threads available for higher priority
+tasks, threads must be reserved for each priority class.
+.TP
+.BR charon.processor.priority_threads.critical " [0]"
+Threads reserved for CRITICAL priority class jobs
+.TP
+.BR charon.processor.priority_threads.high " [0]"
+Threads reserved for HIGH priority class jobs
+.TP
+.BR charon.processor.priority_threads.medium " [0]"
+Threads reserved for MEDIUM priority class jobs
+.TP
+.BR charon.processor.priority_threads.low " [0]"
+Threads reserved for LOW priority class jobs
+.PP
+Let's consider the following configuration:
+.PP
+.EX
+       charon {
+               processor {
+                       priority_threads {
+                               high = 1
+                               medium = 4
+                       }
+               }
+       }
+.EE
+.PP
+With this configuration, one thread is reserved for HIGH priority tasks. As
+currently only liveness checking and stroke message processing is done with
+high priority, one or two threads should be sufficient.
+.PP
+The MEDIUM class mostly processes non-blocking jobs. Unless your setup is
+experiencing many blocks in locks while accessing shared resources, threads for
+one or two times the number of CPU cores is fine.
+.PP
+It is usually not required to reserve threads for CRITICAL jobs. Jobs in this
+class rarely return and do not release their thread to the pool.
+.PP
+The remaining threads are available for LOW priority jobs. Reserving threads
+does not make sense (until we have an even lower priority).
+.SS Monitoring
+To see what the threads are actually doing, invoke
+.IR "ipsec statusall" .
+Under high load, something like this will show up:
+.PP
+.EX
+       worker threads: 2 or 32 idle, 5/1/2/22 working,
+               job queue: 0/0/1/149, scheduled: 198
+.EE
+.PP
+From 32 worker threads,
+.IP 2
+are currently idle.
+.IP 5
+are running CRITICAL priority jobs (dispatching from sockets, etc.).
+.IP 1
+is currently handling a HIGH priority job. This is actually the thread currently
+providing this information via stroke.
+.IP 2
+are handling MEDIUM priority jobs, likely IKE_SA_INIT or CREATE_CHILD_SA
+messages.
+.IP 22
+are handling LOW priority jobs, probably waiting for an EAP-RADIUS response
+while processing IKE_AUTH messages.
+.PP
+The job queue load shows how many jobs are queued for each priority, ready for
+execution. The single MEDIUM priority job will get executed immediately, as
+we have two spare threads reserved for MEDIUM class jobs.
+
+.SH IKE_SA_INIT DROPPING
+If a responder receives more connection requests per seconds than it can handle,
+it does not make sense to accept more IKE_SA_INIT messages. And if they are
+queued but can't get processed in time, an answer might be sent after the
+client has already given up and restarted its connection setup. This
+additionally increases the load on the responder.
+.PP
+To limit the responder load resulting from new connection attempts, the daemon
+can drop IKE_SA_INIT messages just after reception. There are two mechanisms to
+decide if this should happen, configured with the following options:
+.TP
+.BR charon.init_limit_half_open " [0]"
+Limit based on the number of half open IKE_SAs. Half open IKE_SAs are SAs in
+connecting state, but not yet established.
+.TP
+.BR charon.init_limit_job_load " [0]"
+Limit based on the number of jobs currently queued for processing (sum over all
+job priorities).
+.PP
+The second limit includes load from other jobs, such as rekeying. Choosing a
+good value is difficult and depends on the hardware and expected load.
+.PP
+The first limit is simpler to calculate, but includes the load from new
+connections only. If your responder is capable of negotiating 100 tunnels/s, you
+might set this limit to 1000. The daemon will then drop new connection attempts
+if generating a response would require more than 10 seconds. If you are
+allowing for a maximum response time of more than 30 seconds, consider adjusting
+the timeout for connecting IKE_SAs
+.RB ( charon.half_open_timeout ).
+A responder, by default, deletes an IKE_SA if the initiator does not establish
+it within 30 seconds. Under high load, a higher value might be required.
+
+.SH LOAD TESTS
+To do stability testing and performance optimizations, the IKEv2 daemon charon
+provides the load-tester plugin. This plugin allows one to setup thousands of
+tunnels concurrently against the daemon itself or a remote host.
+.PP
+.B WARNING:
+Never enable the load-testing plugin on productive systems. It provides
+preconfigured credentials and allows an attacker to authenticate as any user.
+.SS Options
+.TP
+.BR charon.plugins.load-tester.addrs
+Subsection that contains key/value pairs with address pools (in CIDR notation)
+to use for a specific network interface e.g. eth0 = 10.10.0.0/16
+.TP
+.BR charon.plugins.load-tester.addrs_keep " [no]"
+Whether to keep dynamic addresses even after the associated SA got terminated
+.TP
+.BR charon.plugins.load-tester.addrs_prefix " [16]"
+Network prefix length to use when installing dynamic addresses. If set to -1 the
+full address is used (i.e. 32 or 128)
+.TP
+.BR charon.plugins.load-tester.ca_dir
+Directory to load (intermediate) CA certificates from
+.TP
+.BR charon.plugins.load-tester.child_rekey " [600]"
+Seconds to start CHILD_SA rekeying after setup
+.TP
+.BR charon.plugins.load-tester.delay " [0]"
+Delay between initiatons for each thread
+.TP
+.BR charon.plugins.load-tester.delete_after_established " [no]"
+Delete an IKE_SA as soon as it has been established
+.TP
+.BR charon.plugins.load-tester.digest " [sha1]"
+Digest algorithm used when issuing certificates
+.TP
+.BR charon.plugins.load-tester.dpd_delay " [0]"
+DPD delay to use in load test
+.TP
+.BR charon.plugins.load-tester.dynamic_port " [0]"
+Base port to be used for requests (each client uses a different port)
+.TP
+.BR charon.plugins.load-tester.eap_password " [default-pwd]"
+EAP secret to use in load test
+.TP
+.BR charon.plugins.load-tester.enable " [no]"
+Enable the load testing plugin
+.TP
+.BR charon.plugins.load-tester.esp " [aes128-sha1]"
+CHILD_SA proposal to use for load tests
+.TP
+.BR charon.plugins.load-tester.fake_kernel " [no]"
+Fake the kernel interface to allow load-testing against self
+.TP
+.BR charon.plugins.load-tester.ike_rekey " [0]"
+Seconds to start IKE_SA rekeying after setup
+.TP
+.BR charon.plugins.load-tester.init_limit " [0]"
+Global limit of concurrently established SAs during load test
+.TP
+.BR charon.plugins.load-tester.initiator " [0.0.0.0]"
+Address to initiate from
+.TP
+.BR charon.plugins.load-tester.initiators " [0]"
+Number of concurrent initiator threads to use in load test
+.TP
+.BR charon.plugins.load-tester.initiator_auth " [pubkey]"
+Authentication method(s) the intiator uses
+.TP
+.BR charon.plugins.load-tester.initiator_id
+Initiator ID used in load test
+.TP
+.BR charon.plugins.load-tester.initiator_match
+Initiator ID to match against as responder
+.TP
+.BR charon.plugins.load-tester.initiator_tsi
+Traffic selector on initiator side, as proposed by initiator
+.TP
+.BR charon.plugins.load-tester.initiator_tsr
+Traffic selector on responder side, as proposed by initiator
+.TP
+.BR charon.plugins.load-tester.iterations " [1]"
+Number of IKE_SAs to initiate by each initiator in load test
+.TP
+.BR charon.plugins.load-tester.issuer_cert
+Path to the issuer certificate (if not configured a hard-coded value is used)
+.TP
+.BR charon.plugins.load-tester.issuer_key
+Path to private key that is used to issue certificates (if not configured a
+hard-coded value is used)
+.TP
+.BR charon.plugins.load-tester.mode " [tunnel]"
+IPsec mode to use, one of \fBtunnel\fR, \fBtransport\fR, or \fBbeet\fR.
+.TP
+.BR charon.plugins.load-tester.pool
+Provide INTERNAL_IPV4_ADDRs from a named pool
+.TP
+.BR charon.plugins.load-tester.preshared_key " [default-psk]"
+Preshared key to use in load test
+.TP
+.BR charon.plugins.load-tester.proposal " [aes128-sha1-modp768]"
+IKE proposal to use in load test
+.TP
+.BR charon.plugins.load-tester.responder " [127.0.0.1]"
+Address to initiation connections to
+.TP
+.BR charon.plugins.load-tester.responder_auth " [pubkey]"
+Authentication method(s) the responder uses
+.TP
+.BR charon.plugins.load-tester.responder_id
+Responder ID used in load test
+.TP
+.BR charon.plugins.load-tester.responder_tsi " [initiator_tsi]"
+Traffic selector on initiator side, as narrowed by responder
+.TP
+.BR charon.plugins.load-tester.responder_tsr " [initiator_tsr]"
+Traffic selector on responder side, as narrowed by responder
+.TP
+.BR charon.plugins.load-tester.request_virtual_ip " [no]"
+Request an INTERNAL_IPV4_ADDR from the server
+.TP
+.BR charon.plugins.load-tester.shutdown_when_complete " [no]"
+Shutdown the daemon after all IKE_SAs have been established
+.TP
+.BR charon.plugins.load-tester.socket " [unix://@piddir@/charon.ldt]"
+Socket provided by the load-tester plugin
+.TP
+.BR charon.plugins.load-tester.version " [0]"
+IKE version to use (0 means use IKEv2 as initiator and accept any version as
+responder)
+.PP
+.SS Configuration details
+For public key authentication, the responder uses the
+.B \(dqCN=srv, OU=load-test, O=strongSwan\(dq
+identity. For the initiator, each connection attempt uses a different identity
+in the form
+.BR "\(dqCN=c1-r1, OU=load-test, O=strongSwan\(dq" ,
+where the first number inidicates the client number, the second the
+authentication round (if multiple authentication is used).
+.PP
+For PSK authentication, FQDN identities are used. The server uses
+.BR srv.strongswan.org ,
+the client uses an identity in the form
+.BR c1-r1.strongswan.org .
+.PP
+For EAP authentication, the client uses a NAI in the form
+.BR 100000000010001@strongswan.org .
+.PP
+To configure multiple authentication, concatenate multiple methods using, e.g.
+.EX
+       initiator_auth = pubkey|psk|eap-md5|eap-aka
+.EE
+.PP
+The responder uses a hardcoded certificate based on a 1024-bit RSA key.
+This certificate additionally serves as CA certificate. A peer uses the same
+private key, but generates client certificates on demand signed by the CA
+certificate. Install the Responder/CA certificate on the remote host to
+authenticate all clients.
+.PP
+To speed up testing, the load tester plugin implements a special Diffie-Hellman
+implementation called modpnull. By setting
+.EX
+       proposal = aes128-sha1-modpnull
+.EE
+this wicked fast DH implementation is used. It does not provide any security
+at all, but allows one to run tests without DH calculation overhead.
+.SS Examples
+.PP
+In the simplest case, the daemon initiates IKE_SAs against itself using the
+loopback interface. This will actually establish double the number of IKE_SAs,
+as the daemon is initiator and responder for each IKE_SA at the same time.
+Installation of IPsec SAs would fails, as each SA gets installed twice. To
+simulate the correct behavior, a fake kernel interface can be enabled which does
+not install the IPsec SAs at the kernel level.
+.PP
+A simple loopback configuration might look like this:
+.PP
+.EX
+       charon {
+               # create new IKE_SAs for each CHILD_SA to simulate
+               # different clients
+               reuse_ikesa = no
+               # turn off denial of service protection
+               dos_protection = no
+
+               plugins {
+                       load-tester {
+                               # enable the plugin
+                               enable = yes
+                               # use 4 threads to initiate connections
+                               # simultaneously
+                               initiators = 4
+                               # each thread initiates 1000 connections
+                               iterations = 1000
+                               # delay each initiation in each thread by 20ms
+                               delay = 20
+                               # enable the fake kernel interface to
+                               # avoid SA conflicts
+                               fake_kernel = yes
+                       }
+               }
+       }
+.EE
+.PP
+This will initiate 4000 IKE_SAs within 20 seconds. You may increase the delay
+value if your box can not handle that much load, or decrease it to put more
+load on it. If the daemon starts retransmitting messages your box probably can
+not handle all connection attempts.
+.PP
+The plugin also allows one to test against a remote host. This might help to
+test against a real world configuration. A connection setup to do stress
+testing of a gateway might look like this:
+.PP
+.EX
+       charon {
+               reuse_ikesa = no
+               threads = 32
+
+               plugins {
+                       load-tester {
+                               enable = yes
+                               # 10000 connections, ten in parallel
+                               initiators = 10
+                               iterations = 1000
+                               # use a delay of 100ms, overall time is:
+                               # iterations * delay = 100s
+                               delay = 100
+                               # address of the gateway
+                               remote = 1.2.3.4
+                               # IKE-proposal to use
+                               proposal = aes128-sha1-modp1024
+                               # use faster PSK authentication instead
+                               # of 1024bit RSA
+                               initiator_auth = psk
+                               responder_auth = psk
+                               # request a virtual IP using configuration
+                               # payloads
+                               request_virtual_ip = yes
+                               # enable CHILD_SA every 60s
+                               child_rekey = 60
+                       }
+               }
+       }
+.EE
+
+.SH IKEv2 RETRANSMISSION
+Retransmission timeouts in the IKEv2 daemon charon can be configured globally
+using the three keys listed below:
+.PP
+.RS
+.nf
+.BR charon.retransmit_base " [1.8]"
+.BR charon.retransmit_timeout " [4.0]"
+.BR charon.retransmit_tries " [5]"
+.fi
+.RE
+.PP
+The following algorithm is used to calculate the timeout:
+.PP
+.EX
+       relative timeout = retransmit_timeout * retransmit_base ^ (n-1)
+.EE
+.PP
+Where
+.I n
+is the current retransmission count.
+.PP
+Using the default values, packets are retransmitted in:
+
+.TS
+l r r
+---
+lB r r.
+Retransmission Relative Timeout        Absolute Timeout
+1      4s      4s
+2      7s      11s
+3      13s     24s
+4      23s     47s
+5      42s     89s
+giving up      76s     165s
+.TE
+
+.SH FILES
+/etc/strongswan.conf
+
+.SH SEE ALSO
+\fBipsec.conf\fR(5), \fBipsec.secrets\fR(5), \fBipsec\fR(8), \fBcharon-cmd\fR(8)
+
+.SH HISTORY
+Written for the
+.UR http://www.strongswan.org
+strongSwan project
+.UE
+by Tobias Brunner, Andreas Steffen and Martin Willi.
index 5c7cf5d..9465947 100644 (file)
@@ -1545,7 +1545,8 @@ AC_CONFIG_FILES([
 # =================
 
 AC_CONFIG_FILES([
-       conf/strongswan.conf.5
+       conf/strongswan.conf.5.head
+       conf/strongswan.conf.5.tail
        man/ipsec.conf.5
        man/ipsec.secrets.5
        src/charon-cmd/charon-cmd.8