diff options
author | Yves-Alexis Perez <corsac@corsac.net> | 2012-06-28 21:16:07 +0200 |
---|---|---|
committer | Yves-Alexis Perez <corsac@corsac.net> | 2012-06-28 21:16:07 +0200 |
commit | b34738ed08c2227300d554b139e2495ca5da97d6 (patch) | |
tree | 62f33b52820f2e49f0e53c0f8c636312037c8054 /man | |
parent | 0a9d51a49042a68daa15b0c74a2b7f152f52606b (diff) | |
download | vyos-strongswan-b34738ed08c2227300d554b139e2495ca5da97d6.tar.gz vyos-strongswan-b34738ed08c2227300d554b139e2495ca5da97d6.zip |
Imported Upstream version 4.6.4
Diffstat (limited to 'man')
-rw-r--r-- | man/Makefile.in | 7 | ||||
-rw-r--r-- | man/ipsec.conf.5 | 105 | ||||
-rw-r--r-- | man/ipsec.conf.5.in | 105 | ||||
-rw-r--r-- | man/ipsec.secrets.5 | 23 | ||||
-rw-r--r-- | man/ipsec.secrets.5.in | 23 | ||||
-rw-r--r-- | man/strongswan.conf.5 | 347 | ||||
-rw-r--r-- | man/strongswan.conf.5.in | 347 |
7 files changed, 869 insertions, 88 deletions
diff --git a/man/Makefile.in b/man/Makefile.in index 679e3464b..a38cf70ba 100644 --- a/man/Makefile.in +++ b/man/Makefile.in @@ -170,6 +170,9 @@ am__leading_dot = @am__leading_dot@ am__quote = @am__quote@ am__tar = @am__tar@ am__untar = @am__untar@ +attest_plugins = @attest_plugins@ +axis2c_CFLAGS = @axis2c_CFLAGS@ +axis2c_LIBS = @axis2c_LIBS@ bindir = @bindir@ build = @build@ build_alias = @build_alias@ @@ -178,6 +181,7 @@ build_os = @build_os@ build_vendor = @build_vendor@ builddir = @builddir@ c_plugins = @c_plugins@ +clearsilver_LIBS = @clearsilver_LIBS@ datadir = @datadir@ datarootdir = @datarootdir@ dbusservicedir = @dbusservicedir@ @@ -194,11 +198,13 @@ host_cpu = @host_cpu@ host_os = @host_os@ host_vendor = @host_vendor@ htmldir = @htmldir@ +imcvdir = @imcvdir@ includedir = @includedir@ infodir = @infodir@ install_sh = @install_sh@ ipsecdir = @ipsecdir@ ipsecgroup = @ipsecgroup@ +ipseclibdir = @ipseclibdir@ ipsecuser = @ipsecuser@ libcharon_plugins = @libcharon_plugins@ libdir = @libdir@ @@ -242,6 +248,7 @@ sharedstatedir = @sharedstatedir@ soup_CFLAGS = @soup_CFLAGS@ soup_LIBS = @soup_LIBS@ srcdir = @srcdir@ +starter_plugins = @starter_plugins@ strongswan_conf = @strongswan_conf@ sysconfdir = @sysconfdir@ systemdsystemunitdir = @systemdsystemunitdir@ diff --git a/man/ipsec.conf.5 b/man/ipsec.conf.5 index b36a7ece7..0a7f8bfe5 100644 --- a/man/ipsec.conf.5 +++ b/man/ipsec.conf.5 @@ -1,4 +1,4 @@ -.TH IPSEC.CONF 5 "2010-10-19" "4.5.2" "strongSwan" +.TH IPSEC.CONF 5 "2011-12-14" "4.6.4" "strongSwan" .SH NAME ipsec.conf \- IPsec configuration and connections .SH DESCRIPTION @@ -268,7 +268,7 @@ IKEv1 additionally supports the values .B xauthpsk and .B xauthrsasig -that will enable eXtended AUTHentication (XAUTH) in addition to IKEv1 main mode +that will enable eXtended Authentication (XAuth) in addition to IKEv1 main mode based on shared secrets or digital RSA signatures, respectively. IKEv2 additionally supports the value .BR eap , @@ -298,7 +298,7 @@ and .B rightsubnet , a connection is established. .B start -loads a connection and brings it up immediatly. +loads a connection and brings it up immediately. .B ignore ignores the connection. This is equal to delete a connection from the config file. @@ -367,11 +367,17 @@ See .IR strongswan.conf (5) for a description of the IKEv2 retransmission timeout. .TP +.BR closeaction " = " none " | clear | hold | restart" +defines the action to take if the remote peer unexpectedly closes a CHILD_SA +(IKEv2 only, see dpdaction for meaning of values). A closeaction should not be +used if the peer uses reauthentication or uniquids checking, as these events +might trigger a closeaction when not desired. +.TP .BR inactivity " = <time>" defines the timeout interval, after which a CHILD_SA is closed if it did not send or receive any traffic. Currently supported in IKEv2 connections only. .TP -.BR eap " = md5 | mschapv2 | radius | ... | <type> | <type>-<vendor> +.BR eap " = aka | ... | radius | ... | <type> | <type>-<vendor> defines the EAP type to propose as server if the client requests EAP authentication. Currently supported values are .B aka @@ -382,10 +388,17 @@ for EAP-GTC, for EAP-MD5, .B mschapv2 for EAP-MS-CHAPv2, +.B peap +for EAP-PEAPv0, .B radius -for the EAP-RADIUS proxy and +for the EAP-RADIUS proxy, .B sim -for EAP-SIM. Additionally, IANA assigned EAP method numbers are accepted, or a +for EAP-SIM, +.B tls +for EAP-TLS, and +.B ttls +for EAP-TTLSv0. +Additionally, IANA assigned EAP method numbers are accepted, or a definition in the form .B eap=type-vendor (e.g. eap=7-12345) can be used to specify vendor specific EAP types. @@ -409,19 +422,34 @@ comma-separated list of ESP encryption/authentication algorithms to be used for the connection, e.g. .BR aes128-sha256 . The notation is -.BR encryption-integrity[-dhgroup][-esnmodes] . +.BR encryption-integrity[-dhgroup][-esnmode] . +.br +Defaults to +.BR aes128-sha1,3des-sha1 +for IKEv1. The IKEv2 daemon adds its extensive default proposal to this default +or the configured value. To restrict it to the configured proposal an +exclamation mark +.RB ( ! ) +can be added at the end. +.br +.BR Note : +As a responder both daemons accept the first supported proposal received from +the peer. In order to restrict a responder to only accept specific cipher +suites, the strict flag +.RB ( ! , +exclamation mark) can be used, e.g: aes256-sha512-modp4096! .br If .B dh-group -is specified, CHILD_SA setup and rekeying include a separate diffe hellman -exchange (IKEv2 only). Valid -.B esnmodes +is specified, CHILD_SA setup and rekeying include a separate Diffie-Hellman +exchange (IKEv2 only). Valid values for +.B esnmode (IKEv2 only) are .B esn and -.B noesn. -Specifying both negotiates Extended Sequence number support with the peer, -the defaut is +.BR noesn . +Specifying both negotiates Extended Sequence Number support with the peer, +the default is .B noesn. .TP .BR forceencaps " = yes | " no @@ -436,7 +464,22 @@ to be used, e.g. The notation is .BR encryption-integrity-dhgroup . In IKEv2, multiple algorithms and proposals may be included, such as -.B aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024. +aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024. +.br +Defaults to +.B aes128-sha1-modp2048,3des-sha1-modp1536 +for IKEv1. The IKEv2 daemon adds its extensive default proposal to this +default or the configured value. To restrict it to the configured proposal an +exclamation mark +.RB ( ! ) +can be added at the end. +.br +.BR Note : +As a responder both daemons accept the first supported proposal received from +the peer. In order to restrict a responder to only accept specific cipher +suites, the strict flag +.BR ( ! , +exclamation mark) can be used, e.g: aes256-sha512-modp4096! .TP .BR ikelifetime " = " 3h " | <time>" how long the keying channel of a connection (ISAKMP or IKE SA) @@ -468,11 +511,11 @@ whereas in older strongSwan releases .B ikev1 was assumed. .TP -.BR keyingtries " = " %forever " | <number>" +.BR keyingtries " = " 3 " | <number> | %forever" how many attempts (a whole number or \fB%forever\fP) should be made to negotiate a connection, or a replacement for one, before giving up (default -.BR %forever ). +.BR 3 ). The value \fB%forever\fP means 'never give up'. Relevant only locally, other end need not agree on it. @@ -564,10 +607,12 @@ an optional EAP method can be appended. Currently defined methods are .BR eap-aka , .BR eap-gtc , .BR eap-md5 , +.BR eap-mschapv2 , +.BR eap-peap , +.BR eap-sim , .BR eap-tls , -.B eap-mschapv2 and -.BR eap-sim . +.BR eap-ttls . Alternatively, IANA assigned EAP method numbers are accepted. Vendor specific EAP methods are defined in the form .B eap-type-vendor @@ -995,15 +1040,9 @@ signifying that packets should be discarded; and signifying that packets should be discarded and a diagnostic ICMP returned .RB ( reject is currently not supported by the NETKEY stack of the Linux 2.6 kernel). -The IKEv2 daemon charon currently supports -.BR tunnel , -.BR transport , -and -.BR transport_proxy -connection types, only. .TP .BR xauth " = " client " | server" -specifies the role in the XAUTH protocol if activated by +specifies the role in the XAuth protocol if activated by .B authby=xauthpsk or .B authby=xauthrsasig. @@ -1012,6 +1051,10 @@ Accepted values are and .B client (the default). +.TP +.BR xauth_identity " = <id>" +defines the identity/username the client uses to reply to an XAuth request. +If not defined, the IKEv1 identity will be used as XAuth identity. .SS "CONN PARAMETERS: IKEv2 MEDIATION EXTENSION" The following parameters are relevant to IKEv2 Mediation Extension @@ -1166,7 +1209,7 @@ so a new (automatically-keyed) connection using the same ID is almost invariably intended to replace an old one. The IKEv2 daemon also accepts the value .B replace -wich is identical to +which is identical to .B yes and the value .B keep @@ -1277,15 +1320,17 @@ parameters are used by the IKEv2 charon daemon only: .TP .BR charondebug " = <debug list>" how much charon debugging output should be logged. -A comma separated list containing type level/pairs may +A comma separated list containing type/level-pairs may be specified, e.g: .B dmn 3, ike 1, net -1. Acceptable values for types are -.B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib +.B dmn, mgr, ike, chd, job, cfg, knl, net, asn, enc, lib, tls, tnc, imc, imv, pts and the level is one of .B -1, 0, 1, 2, 3, 4 -(for silent, audit, control, controlmore, raw, private). -For more flexibility see LOGGER CONFIGURATION in +(for silent, audit, control, controlmore, raw, private). By default, the level +is set to +.B 1 +for all types. For more flexibility see LOGGER CONFIGURATION in .IR strongswan.conf (5). .SH IKEv2 EXPIRY/REKEY diff --git a/man/ipsec.conf.5.in b/man/ipsec.conf.5.in index 295100444..ab255304d 100644 --- a/man/ipsec.conf.5.in +++ b/man/ipsec.conf.5.in @@ -1,4 +1,4 @@ -.TH IPSEC.CONF 5 "2010-10-19" "@IPSEC_VERSION@" "strongSwan" +.TH IPSEC.CONF 5 "2011-12-14" "@IPSEC_VERSION@" "strongSwan" .SH NAME ipsec.conf \- IPsec configuration and connections .SH DESCRIPTION @@ -268,7 +268,7 @@ IKEv1 additionally supports the values .B xauthpsk and .B xauthrsasig -that will enable eXtended AUTHentication (XAUTH) in addition to IKEv1 main mode +that will enable eXtended Authentication (XAuth) in addition to IKEv1 main mode based on shared secrets or digital RSA signatures, respectively. IKEv2 additionally supports the value .BR eap , @@ -298,7 +298,7 @@ and .B rightsubnet , a connection is established. .B start -loads a connection and brings it up immediatly. +loads a connection and brings it up immediately. .B ignore ignores the connection. This is equal to delete a connection from the config file. @@ -367,11 +367,17 @@ See .IR strongswan.conf (5) for a description of the IKEv2 retransmission timeout. .TP +.BR closeaction " = " none " | clear | hold | restart" +defines the action to take if the remote peer unexpectedly closes a CHILD_SA +(IKEv2 only, see dpdaction for meaning of values). A closeaction should not be +used if the peer uses reauthentication or uniquids checking, as these events +might trigger a closeaction when not desired. +.TP .BR inactivity " = <time>" defines the timeout interval, after which a CHILD_SA is closed if it did not send or receive any traffic. Currently supported in IKEv2 connections only. .TP -.BR eap " = md5 | mschapv2 | radius | ... | <type> | <type>-<vendor> +.BR eap " = aka | ... | radius | ... | <type> | <type>-<vendor> defines the EAP type to propose as server if the client requests EAP authentication. Currently supported values are .B aka @@ -382,10 +388,17 @@ for EAP-GTC, for EAP-MD5, .B mschapv2 for EAP-MS-CHAPv2, +.B peap +for EAP-PEAPv0, .B radius -for the EAP-RADIUS proxy and +for the EAP-RADIUS proxy, .B sim -for EAP-SIM. Additionally, IANA assigned EAP method numbers are accepted, or a +for EAP-SIM, +.B tls +for EAP-TLS, and +.B ttls +for EAP-TTLSv0. +Additionally, IANA assigned EAP method numbers are accepted, or a definition in the form .B eap=type-vendor (e.g. eap=7-12345) can be used to specify vendor specific EAP types. @@ -409,19 +422,34 @@ comma-separated list of ESP encryption/authentication algorithms to be used for the connection, e.g. .BR aes128-sha256 . The notation is -.BR encryption-integrity[-dhgroup][-esnmodes] . +.BR encryption-integrity[-dhgroup][-esnmode] . +.br +Defaults to +.BR aes128-sha1,3des-sha1 +for IKEv1. The IKEv2 daemon adds its extensive default proposal to this default +or the configured value. To restrict it to the configured proposal an +exclamation mark +.RB ( ! ) +can be added at the end. +.br +.BR Note : +As a responder both daemons accept the first supported proposal received from +the peer. In order to restrict a responder to only accept specific cipher +suites, the strict flag +.RB ( ! , +exclamation mark) can be used, e.g: aes256-sha512-modp4096! .br If .B dh-group -is specified, CHILD_SA setup and rekeying include a separate diffe hellman -exchange (IKEv2 only). Valid -.B esnmodes +is specified, CHILD_SA setup and rekeying include a separate Diffie-Hellman +exchange (IKEv2 only). Valid values for +.B esnmode (IKEv2 only) are .B esn and -.B noesn. -Specifying both negotiates Extended Sequence number support with the peer, -the defaut is +.BR noesn . +Specifying both negotiates Extended Sequence Number support with the peer, +the default is .B noesn. .TP .BR forceencaps " = yes | " no @@ -436,7 +464,22 @@ to be used, e.g. The notation is .BR encryption-integrity-dhgroup . In IKEv2, multiple algorithms and proposals may be included, such as -.B aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024. +aes128-aes256-sha1-modp1536-modp2048,3des-sha1-md5-modp1024. +.br +Defaults to +.B aes128-sha1-modp2048,3des-sha1-modp1536 +for IKEv1. The IKEv2 daemon adds its extensive default proposal to this +default or the configured value. To restrict it to the configured proposal an +exclamation mark +.RB ( ! ) +can be added at the end. +.br +.BR Note : +As a responder both daemons accept the first supported proposal received from +the peer. In order to restrict a responder to only accept specific cipher +suites, the strict flag +.BR ( ! , +exclamation mark) can be used, e.g: aes256-sha512-modp4096! .TP .BR ikelifetime " = " 3h " | <time>" how long the keying channel of a connection (ISAKMP or IKE SA) @@ -468,11 +511,11 @@ whereas in older strongSwan releases .B ikev1 was assumed. .TP -.BR keyingtries " = " %forever " | <number>" +.BR keyingtries " = " 3 " | <number> | %forever" how many attempts (a whole number or \fB%forever\fP) should be made to negotiate a connection, or a replacement for one, before giving up (default -.BR %forever ). +.BR 3 ). The value \fB%forever\fP means 'never give up'. Relevant only locally, other end need not agree on it. @@ -564,10 +607,12 @@ an optional EAP method can be appended. Currently defined methods are .BR eap-aka , .BR eap-gtc , .BR eap-md5 , +.BR eap-mschapv2 , +.BR eap-peap , +.BR eap-sim , .BR eap-tls , -.B eap-mschapv2 and -.BR eap-sim . +.BR eap-ttls . Alternatively, IANA assigned EAP method numbers are accepted. Vendor specific EAP methods are defined in the form .B eap-type-vendor @@ -995,15 +1040,9 @@ signifying that packets should be discarded; and signifying that packets should be discarded and a diagnostic ICMP returned .RB ( reject is currently not supported by the NETKEY stack of the Linux 2.6 kernel). -The IKEv2 daemon charon currently supports -.BR tunnel , -.BR transport , -and -.BR transport_proxy -connection types, only. .TP .BR xauth " = " client " | server" -specifies the role in the XAUTH protocol if activated by +specifies the role in the XAuth protocol if activated by .B authby=xauthpsk or .B authby=xauthrsasig. @@ -1012,6 +1051,10 @@ Accepted values are and .B client (the default). +.TP +.BR xauth_identity " = <id>" +defines the identity/username the client uses to reply to an XAuth request. +If not defined, the IKEv1 identity will be used as XAuth identity. .SS "CONN PARAMETERS: IKEv2 MEDIATION EXTENSION" The following parameters are relevant to IKEv2 Mediation Extension @@ -1166,7 +1209,7 @@ so a new (automatically-keyed) connection using the same ID is almost invariably intended to replace an old one. The IKEv2 daemon also accepts the value .B replace -wich is identical to +which is identical to .B yes and the value .B keep @@ -1277,15 +1320,17 @@ parameters are used by the IKEv2 charon daemon only: .TP .BR charondebug " = <debug list>" how much charon debugging output should be logged. -A comma separated list containing type level/pairs may +A comma separated list containing type/level-pairs may be specified, e.g: .B dmn 3, ike 1, net -1. Acceptable values for types are -.B dmn, mgr, ike, chd, job, cfg, knl, net, enc, lib +.B dmn, mgr, ike, chd, job, cfg, knl, net, asn, enc, lib, tls, tnc, imc, imv, pts and the level is one of .B -1, 0, 1, 2, 3, 4 -(for silent, audit, control, controlmore, raw, private). -For more flexibility see LOGGER CONFIGURATION in +(for silent, audit, control, controlmore, raw, private). By default, the level +is set to +.B 1 +for all types. For more flexibility see LOGGER CONFIGURATION in .IR strongswan.conf (5). .SH IKEv2 EXPIRY/REKEY diff --git a/man/ipsec.secrets.5 b/man/ipsec.secrets.5 index 993b2ad10..c7c092502 100644 --- a/man/ipsec.secrets.5 +++ b/man/ipsec.secrets.5 @@ -1,4 +1,4 @@ -.TH IPSEC.SECRETS 5 "2010-05-30" "4.5.2" "strongSwan" +.TH IPSEC.SECRETS 5 "2011-12-14" "4.6.2dr3" "strongSwan" .SH NAME ipsec.secrets \- secrets for IKE/IPsec authentication .SH DESCRIPTION @@ -124,12 +124,17 @@ whitespace). .SS TYPES OF SECRETS .TP .B [ <selectors> ] : PSK <secret> -A preshared secret is most conveniently represented as a sequence of -characters, delimited by double-quote characters (\fB"\fP). -The sequence cannot contain a newline or double-quote. -Strictly speaking, the secret is actually the sequence -of bytes that is used in the file to represent the sequence of -characters (excluding the delimiters). +A preshared \fIsecret\fP is most conveniently represented as a sequence of +characters, which is delimited by double-quote characters (\fB"\fP). +The sequence cannot contain newline or double-quote characters. +.br +Alternatively, preshared secrets can be represented as hexadecimal or Base64 +encoded binary values. A character sequence beginning with +.B 0x +is interpreted as sequence of hexadecimal digits. +Similarly, a character sequence beginning with +.B 0s +is interpreted as Base64 encoded binary data. .TP .B [ <selectors> ] : RSA <private key file> [ <passphrase> | %prompt ] .TQ @@ -142,12 +147,12 @@ can be used which then causes the daemons to ask the user for the password whenever it is required to decrypt the key. .TP .B <user id> : EAP <secret> -As with \fBPSK\fP secrets the \fIsecret\fP is a sequence of characters, -delimited by double-quote characters (\fB"\fP). +The format of \fIsecret\fP is the same as that of \fBPSK\fP secrets. .br \fBEAP\fP secrets are IKEv2 only. .TP .B [ <servername> ] <username> : XAUTH <password> +The format of \fIpassword\fP is the same as that of \fBPSK\fP secrets. \fBXAUTH\fP secrets are IKEv1 only. .TP .B : PIN <smartcard selector> <pin code> | %prompt diff --git a/man/ipsec.secrets.5.in b/man/ipsec.secrets.5.in index 875b8e219..aa1b5c9c1 100644 --- a/man/ipsec.secrets.5.in +++ b/man/ipsec.secrets.5.in @@ -1,4 +1,4 @@ -.TH IPSEC.SECRETS 5 "2010-05-30" "@IPSEC_VERSION@" "strongSwan" +.TH IPSEC.SECRETS 5 "2011-12-14" "@IPSEC_VERSION@" "strongSwan" .SH NAME ipsec.secrets \- secrets for IKE/IPsec authentication .SH DESCRIPTION @@ -124,12 +124,17 @@ whitespace). .SS TYPES OF SECRETS .TP .B [ <selectors> ] : PSK <secret> -A preshared secret is most conveniently represented as a sequence of -characters, delimited by double-quote characters (\fB"\fP). -The sequence cannot contain a newline or double-quote. -Strictly speaking, the secret is actually the sequence -of bytes that is used in the file to represent the sequence of -characters (excluding the delimiters). +A preshared \fIsecret\fP is most conveniently represented as a sequence of +characters, which is delimited by double-quote characters (\fB"\fP). +The sequence cannot contain newline or double-quote characters. +.br +Alternatively, preshared secrets can be represented as hexadecimal or Base64 +encoded binary values. A character sequence beginning with +.B 0x +is interpreted as sequence of hexadecimal digits. +Similarly, a character sequence beginning with +.B 0s +is interpreted as Base64 encoded binary data. .TP .B [ <selectors> ] : RSA <private key file> [ <passphrase> | %prompt ] .TQ @@ -142,12 +147,12 @@ can be used which then causes the daemons to ask the user for the password whenever it is required to decrypt the key. .TP .B <user id> : EAP <secret> -As with \fBPSK\fP secrets the \fIsecret\fP is a sequence of characters, -delimited by double-quote characters (\fB"\fP). +The format of \fIsecret\fP is the same as that of \fBPSK\fP secrets. .br \fBEAP\fP secrets are IKEv2 only. .TP .B [ <servername> ] <username> : XAUTH <password> +The format of \fIpassword\fP is the same as that of \fBPSK\fP secrets. \fBXAUTH\fP secrets are IKEv1 only. .TP .B : PIN <smartcard selector> <pin code> | %prompt diff --git a/man/strongswan.conf.5 b/man/strongswan.conf.5 index e1e4dbe91..e56e786e0 100644 --- a/man/strongswan.conf.5 +++ b/man/strongswan.conf.5 @@ -1,4 +1,4 @@ -.TH STRONGSWAN.CONF 5 "2010-09-09" "4.5.2" "strongSwan" +.TH STRONGSWAN.CONF 5 "2011-07-26" "4.6.4" "strongSwan" .SH NAME strongswan.conf \- strongSwan configuration file .SH DESCRIPTION @@ -126,6 +126,13 @@ will return 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 charon.block_threshold " [5]" @@ -151,6 +158,9 @@ Section to define file loggers, see LOGGER CONFIGURATION .BR charon.flush_auth_cfg " [no]" .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 @@ -166,6 +176,14 @@ Size of the IKE_SA hash table .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.install_routes " [yes]" Install routes into a separate routing table for established IPsec tunnels .TP @@ -295,6 +313,9 @@ Start phase2 EAP TNC protocol after successful client authentication 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.class_group " [no]" Use the .I class @@ -449,20 +470,57 @@ Section to configure the load-tester plugin, see LOAD TESTS .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.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.tnc-ifmap.device_name +Unique name of strongSwan as a PEP and/or PDP device +.TP +.BR charon.plugins.tnc-ifmap.key_file +Concatenated client certificate and private key +.TP +.BR charon.plugins.tnc-ifmap.password +Authentication password of strongSwan MAP client +.TP +.BR charon.plugins.tnc-ifmap.server_cert +Certificate of MAP server +.TP +.BR charon.plugins.tnc-ifmap.ssl_passphrase +Passphrase protecting the private key +.TP +.BR charon.plugins.tnc-ifmap.username +Authentication username of strongSwan MAP client +.TP .BR charon.plugins.tnc-imc.preferred_language " [en]" Preferred language for TNC recommendations .TP -.BR charon.plugins.tnc-imc.tnc_config " [/etc/tnc_config]" -TNC IMC configuration directory +.BR charon.plugins.tnc-pdp.method " [ttls]" +EAP tunnel method to be used .TP -.BR charon.plugins.tnc-imv.tnc_config " [/etc/tnc_config]" -TNC IMV configuration directory +.BR charon.plugins.tnc-pdp.port " [1812]" +RADIUS server port the strongSwan PDP is listening on +.TP +.BR charon.plugins.tnc-pdp.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.whitelist.enable " [yes]" enable loaded whitelist plugin @@ -502,6 +560,10 @@ Check daemon, libstrongswan and plugin integrity at startup .BR libstrongswan.leak_detective.detailed " [yes]" Includes source file names and line numbers in leak detective output .TP +.BR libstrongswan.processor.priority_threads +Subsection to configure the number of reserved threads per priority class +see JOB PRIORITY MANAGEMENT +.TP .BR libstrongswan.x509.enforce_critical " [yes]" Discard certificates with unsupported or unknown critical extensions .SS libstrongswan.plugins subsection @@ -519,8 +581,96 @@ Use faster random numbers in gcrypt; for testing only, produces weak keys! ENGINE ID to use in the OpenSSL plugin .TP .BR libstrongswan.plugins.pkcs11.modules +List of available PKCS#11 modules +.TP +.BR libstrongswan.plugins.pkcs11.use_dh " [no]" +Whether the PKCS#11 modules should be used for DH and ECDH (see use_ecc option) +.TP +.BR libstrongswan.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 libstrongswan.plugins.pkcs11.use_hasher " [no]" +Whether the PKCS#11 modules should be used to hash data +.TP +.BR libstrongswan.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 libstrongswan.plugins.pkcs11.use_rng " [no]" +Whether the PKCS#11 modules should be used as RNG +.SS libtnccs section +.TP +.BR libtnccs.tnc_config " [/etc/tnc_config]" +TNC IMC/IMV configuration directory +.SS libimcv section +.TP +.BR libimcv.debug_level " [1]" +Debug level for a stand-alone libimcv library +.TP +.BR libimcv.stderr_quiet " [no]" +Disable output to stderr with a stand-alone libimcv library +.SS libimcv plugins section +.TP +.BR libimcv.plugins.imc-attestation.platform_info +Information on operating system and hardware platform +.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.database +Path to database with file measurement information +.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.platform_info +Information on operating system and hardware platform +.TP +.BR libimcv.plugins.imv-scanner.closed_port_policy " [yes]" +By default all ports must be closed (yes) or can be open (no) +.TP +.BR libimcv.plugins.imv-scanner.tcp_ports +List of TCP ports that can be open or must be closed +.TP +.BR libimcv.plugins.imv-scanner.udp_ports +List of UDP ports that can be open or must be closed +.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.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 libtls section .TP .BR libtls.cipher @@ -637,6 +787,9 @@ Plugins to load in ipsec pool tool 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/pluto plugin load option warning @@ -700,6 +853,14 @@ identifier for each IKE_SA. 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 @@ -727,6 +888,9 @@ IPsec/Networking kernel interface .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 @@ -735,6 +899,18 @@ libtls 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 @@ -783,6 +959,149 @@ Also include sensitive material in dumps, e.g. keys } .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 libstrongswan.processor.priority_threads.critical " [0]" +Threads reserved for CRITICAL priority class jobs +.TP +.BR libstrongswan.processor.priority_threads.high " [0]" +Threads reserved for HIGH priority class jobs +.TP +.BR libstrongswan.processor.priority_threads.medium " [0]" +Threads reserved for MEDIUM priority class jobs +.TP +.BR libstrongswan.processor.priority_threads.low " [0]" +Threads reserved for LOW priority class jobs +.PP +Let's consider the following configuration: +.PP +.EX + libstrongswan { + 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 to setup thousands of @@ -802,9 +1121,15 @@ Delay between initiatons for each thread .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.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 @@ -814,18 +1139,27 @@ Fake the kernel interface to allow load-testing against self .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.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.iterations " [1]" Number of IKE_SAs to initate by each initiator in load test .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 @@ -835,6 +1169,9 @@ Address to initiation connections to .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.request_virtual_ip " [no]" Request an INTERNAL_IPV4_ADDR from the server .TP diff --git a/man/strongswan.conf.5.in b/man/strongswan.conf.5.in index 2d7475225..05493ec75 100644 --- a/man/strongswan.conf.5.in +++ b/man/strongswan.conf.5.in @@ -1,4 +1,4 @@ -.TH STRONGSWAN.CONF 5 "2010-09-09" "@IPSEC_VERSION@" "strongSwan" +.TH STRONGSWAN.CONF 5 "2011-07-26" "@IPSEC_VERSION@" "strongSwan" .SH NAME strongswan.conf \- strongSwan configuration file .SH DESCRIPTION @@ -126,6 +126,13 @@ will return 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 charon.block_threshold " [5]" @@ -151,6 +158,9 @@ Section to define file loggers, see LOGGER CONFIGURATION .BR charon.flush_auth_cfg " [no]" .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 @@ -166,6 +176,14 @@ Size of the IKE_SA hash table .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.install_routes " [yes]" Install routes into a separate routing table for established IPsec tunnels .TP @@ -295,6 +313,9 @@ Start phase2 EAP TNC protocol after successful client authentication 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.class_group " [no]" Use the .I class @@ -449,20 +470,57 @@ Section to configure the load-tester plugin, see LOAD TESTS .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.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.tnc-ifmap.device_name +Unique name of strongSwan as a PEP and/or PDP device +.TP +.BR charon.plugins.tnc-ifmap.key_file +Concatenated client certificate and private key +.TP +.BR charon.plugins.tnc-ifmap.password +Authentication password of strongSwan MAP client +.TP +.BR charon.plugins.tnc-ifmap.server_cert +Certificate of MAP server +.TP +.BR charon.plugins.tnc-ifmap.ssl_passphrase +Passphrase protecting the private key +.TP +.BR charon.plugins.tnc-ifmap.username +Authentication username of strongSwan MAP client +.TP .BR charon.plugins.tnc-imc.preferred_language " [en]" Preferred language for TNC recommendations .TP -.BR charon.plugins.tnc-imc.tnc_config " [/etc/tnc_config]" -TNC IMC configuration directory +.BR charon.plugins.tnc-pdp.method " [ttls]" +EAP tunnel method to be used .TP -.BR charon.plugins.tnc-imv.tnc_config " [/etc/tnc_config]" -TNC IMV configuration directory +.BR charon.plugins.tnc-pdp.port " [1812]" +RADIUS server port the strongSwan PDP is listening on +.TP +.BR charon.plugins.tnc-pdp.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.whitelist.enable " [yes]" enable loaded whitelist plugin @@ -502,6 +560,10 @@ Check daemon, libstrongswan and plugin integrity at startup .BR libstrongswan.leak_detective.detailed " [yes]" Includes source file names and line numbers in leak detective output .TP +.BR libstrongswan.processor.priority_threads +Subsection to configure the number of reserved threads per priority class +see JOB PRIORITY MANAGEMENT +.TP .BR libstrongswan.x509.enforce_critical " [yes]" Discard certificates with unsupported or unknown critical extensions .SS libstrongswan.plugins subsection @@ -519,8 +581,96 @@ Use faster random numbers in gcrypt; for testing only, produces weak keys! ENGINE ID to use in the OpenSSL plugin .TP .BR libstrongswan.plugins.pkcs11.modules +List of available PKCS#11 modules +.TP +.BR libstrongswan.plugins.pkcs11.use_dh " [no]" +Whether the PKCS#11 modules should be used for DH and ECDH (see use_ecc option) +.TP +.BR libstrongswan.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 libstrongswan.plugins.pkcs11.use_hasher " [no]" +Whether the PKCS#11 modules should be used to hash data +.TP +.BR libstrongswan.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 libstrongswan.plugins.pkcs11.use_rng " [no]" +Whether the PKCS#11 modules should be used as RNG +.SS libtnccs section +.TP +.BR libtnccs.tnc_config " [/etc/tnc_config]" +TNC IMC/IMV configuration directory +.SS libimcv section +.TP +.BR libimcv.debug_level " [1]" +Debug level for a stand-alone libimcv library +.TP +.BR libimcv.stderr_quiet " [no]" +Disable output to stderr with a stand-alone libimcv library +.SS libimcv plugins section +.TP +.BR libimcv.plugins.imc-attestation.platform_info +Information on operating system and hardware platform +.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.database +Path to database with file measurement information +.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.platform_info +Information on operating system and hardware platform +.TP +.BR libimcv.plugins.imv-scanner.closed_port_policy " [yes]" +By default all ports must be closed (yes) or can be open (no) +.TP +.BR libimcv.plugins.imv-scanner.tcp_ports +List of TCP ports that can be open or must be closed +.TP +.BR libimcv.plugins.imv-scanner.udp_ports +List of UDP ports that can be open or must be closed +.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.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 libtls section .TP .BR libtls.cipher @@ -637,6 +787,9 @@ Plugins to load in ipsec pool tool 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/pluto plugin load option warning @@ -700,6 +853,14 @@ identifier for each IKE_SA. 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 @@ -727,6 +888,9 @@ IPsec/Networking kernel interface .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 @@ -735,6 +899,18 @@ libtls 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 @@ -783,6 +959,149 @@ Also include sensitive material in dumps, e.g. keys } .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 libstrongswan.processor.priority_threads.critical " [0]" +Threads reserved for CRITICAL priority class jobs +.TP +.BR libstrongswan.processor.priority_threads.high " [0]" +Threads reserved for HIGH priority class jobs +.TP +.BR libstrongswan.processor.priority_threads.medium " [0]" +Threads reserved for MEDIUM priority class jobs +.TP +.BR libstrongswan.processor.priority_threads.low " [0]" +Threads reserved for LOW priority class jobs +.PP +Let's consider the following configuration: +.PP +.EX + libstrongswan { + 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 to setup thousands of @@ -802,9 +1121,15 @@ Delay between initiatons for each thread .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.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 @@ -814,18 +1139,27 @@ Fake the kernel interface to allow load-testing against self .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.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.iterations " [1]" Number of IKE_SAs to initate by each initiator in load test .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 @@ -835,6 +1169,9 @@ Address to initiation connections to .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.request_virtual_ip " [no]" Request an INTERNAL_IPV4_ADDR from the server .TP |