summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
Diffstat (limited to 'man')
-rw-r--r--man/Makefile.in7
-rw-r--r--man/ipsec.conf.5105
-rw-r--r--man/ipsec.conf.5.in105
-rw-r--r--man/ipsec.secrets.523
-rw-r--r--man/ipsec.secrets.5.in23
-rw-r--r--man/strongswan.conf.5347
-rw-r--r--man/strongswan.conf.5.in347
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
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-26 15:49:17 +0000