settings: Don't allow dots in section/key names anymore
[strongswan.git] / conf / strongswan.conf.5.tail.in
index 29b842c..a93fe02 100644 (file)
@@ -1,16 +1,18 @@
 .SH LOGGER CONFIGURATION
-The options described below provide a much more flexible way to configure
-loggers for the IKEv2 daemon charon than using the
+Options in
+.BR strongswan.conf (5)
+provide a much more flexible way to configure loggers for the IKE 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,
+.BR Note :
+If any loggers are specified in strongswan.conf,
 .B charondebug
 does not have any effect.
 .PP
-There are currently two types of loggers defined:
+There are currently two types of loggers:
 .TP
 .B File loggers
 Log directly to a file and are defined by specifying the full path to the
@@ -29,43 +31,6 @@ section. The following facilities are currently supported:
 .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
@@ -128,7 +93,7 @@ Absolutely silent
 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
+Generic control flow with errors, a good default to see what's going on
 .TP
 .B 2
 More detailed debugging control flow
@@ -311,135 +276,13 @@ 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.
+To do stability testing and performance optimizations, the IKE daemon charon
+provides the \fIload-tester\fR 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
@@ -448,7 +291,7 @@ 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).
+authentication round (if multiple authentication rounds are used).
 .PP
 For PSK authentication, FQDN identities are used. The server uses
 .BR srv.strongswan.org ,
@@ -458,7 +301,8 @@ the client uses an identity in the form
 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.
+To configure multiple authentication rounds, concatenate multiple methods using,
+e.g.
 .EX
        initiator_auth = pubkey|psk|eap-md5|eap-aka
 .EE
@@ -470,7 +314,7 @@ 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
+implementation called \fImodpnull\fR. By setting
 .EX
        proposal = aes128-sha1-modpnull
 .EE
@@ -481,7 +325,7 @@ at all, but allows one to run tests without DH calculation overhead.
 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
+Installation of IPsec SAs would fail, 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
@@ -564,6 +408,8 @@ using the three keys listed below:
 .BR charon.retransmit_base " [1.8]"
 .BR charon.retransmit_timeout " [4.0]"
 .BR charon.retransmit_tries " [5]"
+.BR charon.retransmit_jitter " [0]"
+.BR charon.retransmit_limit " [0]"
 .fi
 .RE
 .PP
@@ -575,7 +421,15 @@ The following algorithm is used to calculate the timeout:
 .PP
 Where
 .I n
-is the current retransmission count.
+is the current retransmission count. The calculated timeout can't exceed the
+configured retransmit_limit (if any), which is useful if the number of retries
+is high.
+.PP
+If a jitter in percent is configured, the timeout is modified as follows:
+.PP
+.EX
+       relative timeout -= random(0, retransmit_jitter * relative timeout)
+.EE
 .PP
 Using the default values, packets are retransmitted in:
 
@@ -591,10 +445,30 @@ Retransmission    Relative Timeout        Absolute Timeout
 5      42s     89s
 giving up      76s     165s
 .TE
+.
+.SH VARIABLES
+.
+The variables used above are configured as follows:
 
+.nf
+.na
+${piddir}               @piddir@
+${prefix}               @prefix@
+${random_device}        @random_device@
+${urandom_device}       @urandom_device@
+.ad
+.fi
+.
 .SH FILES
-/etc/strongswan.conf
-
+.
+.nf
+.na
+/etc/strongswan.conf       configuration file
+/etc/strongswan.d/         directory containing included config snippets
+/etc/strongswan.d/charon/  plugin specific config snippets
+.ad
+.fi
+.
 .SH SEE ALSO
 \fBipsec.conf\fR(5), \fBipsec.secrets\fR(5), \fBipsec\fR(8), \fBcharon-cmd\fR(8)