From c4bb26b84901c07a553cc82eb99762d45dd6b29d Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Wed, 29 Jan 2014 13:59:34 +0100 Subject: [PATCH] conf: Split strongswan.conf(5) man page and use generated snippet --- conf/.gitignore | 2 + conf/Makefile.am | 4 + conf/strongswan.conf.5.head.in | 127 +++ conf/strongswan.conf.5.in | 1781 -------------------------------- conf/strongswan.conf.5.tail.in | 606 +++++++++++ configure.ac | 3 +- 6 files changed, 741 insertions(+), 1782 deletions(-) create mode 100644 conf/strongswan.conf.5.head.in delete mode 100644 conf/strongswan.conf.5.in create mode 100644 conf/strongswan.conf.5.tail.in diff --git a/conf/.gitignore b/conf/.gitignore index 04065fbac..6ccd3250e 100644 --- a/conf/.gitignore +++ b/conf/.gitignore @@ -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 diff --git a/conf/Makefile.am b/conf/Makefile.am index 5f88815a5..bc7017b1b 100644 --- a/conf/Makefile.am +++ b/conf/Makefile.am @@ -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 index 000000000..23454e758 --- /dev/null +++ b/conf/strongswan.conf.5.head.in @@ -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 index 02f910e6e..000000000 --- a/conf/strongswan.conf.5.in +++ /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..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..default " [1]" -.TQ -.BR charon.syslog..default -Specifies the default loglevel to be used for subsystems for which no specific -loglevel is defined. -.TP -.BR charon.filelog.. " []" -.TQ -.BR charon.syslog.. -Specifies the loglevel for the given subsystem. -.TP -.BR charon.filelog..append " [yes]" -If this option is enabled log entries are appended to the existing file. -.TP -.BR charon.filelog..flush_line " [no]" -Enabling this option disables block buffering and enables line buffering. -.TP -.BR charon.filelog..ike_name " [no]" -.TQ -.BR charon.syslog..ike_name -Prefix each log entry with the connection name and a unique numerical -identifier for each IKE_SA. -.TP -.BR charon.filelog..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 index 000000000..29b842c3f --- /dev/null +++ b/conf/strongswan.conf.5.tail.in @@ -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..default " [1]" +.TQ +.BR charon.syslog..default +Specifies the default loglevel to be used for subsystems for which no specific +loglevel is defined. +.TP +.BR charon.filelog.. " []" +.TQ +.BR charon.syslog.. +Specifies the loglevel for the given subsystem. +.TP +.BR charon.filelog..append " [yes]" +If this option is enabled log entries are appended to the existing file. +.TP +.BR charon.filelog..flush_line " [no]" +Enabling this option disables block buffering and enables line buffering. +.TP +.BR charon.filelog..ike_name " [no]" +.TQ +.BR charon.syslog..ike_name +Prefix each log entry with the connection name and a unique numerical +identifier for each IKE_SA. +.TP +.BR charon.filelog..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/configure.ac b/configure.ac index 5c7cf5df2..94659478c 100644 --- a/configure.ac +++ b/configure.ac @@ -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