conf/strongswan.conf.5.tail.in

   1 .SH LOGGER CONFIGURATION
   2 Options in
   3 .BR strongswan.conf (5)
   4 provide a much more flexible way to configure loggers for the IKE daemon charon
   5 than using the
   6 .B charondebug
   7 option in
   8 .BR ipsec.conf (5).
   9 .PP
  10 .BR Note :
  11 If any loggers are specified in strongswan.conf,
  12 .B charondebug
  13 does not have any effect.
  14 .PP
  15 There are currently two types of loggers:
  16 .TP
  17 .B File loggers
  18 Log directly to a file and are defined by specifying the full path to the
  19 file as subsection in the
  20 .B charon.filelog
  21 section. To log to the console the two special filenames
  22 .BR stdout " and " stderr
  23 can be used.
  24 .TP
  25 .B Syslog loggers
  26 Log into a syslog facility and are defined by specifying the facility to log to
  27 as the name of a subsection in the
  28 .B charon.syslog
  29 section. The following facilities are currently supported:
  30 .BR daemon " and " auth .
  31 .PP
  32 Multiple loggers can be defined for each type with different log verbosity for
  33 the different subsystems of the daemon.
  34
  35 .SS Subsystems
  36 .TP
  37 .B dmn
  38 Main daemon setup/cleanup/signal handling
  39 .TP
  40 .B mgr
  41 IKE_SA manager, handling synchronization for IKE_SA access
  42 .TP
  43 .B ike
  44 IKE_SA
  45 .TP
  46 .B chd
  47 CHILD_SA
  48 .TP
  49 .B job
  50 Jobs queueing/processing and thread pool management
  51 .TP
  52 .B cfg
  53 Configuration management and plugins
  54 .TP
  55 .B knl
  56 IPsec/Networking kernel interface
  57 .TP
  58 .B net
  59 IKE network communication
  60 .TP
  61 .B asn
  62 Low-level encoding/decoding (ASN.1, X.509 etc.)
  63 .TP
  64 .B enc
  65 Packet encoding/decoding encryption/decryption operations
  66 .TP
  67 .B tls
  68 libtls library messages
  69 .TP
  70 .B esp
  71 libipsec library messages
  72 .TP
  73 .B lib
  74 libstrongwan library messages
  75 .TP
  76 .B tnc
  77 Trusted Network Connect
  78 .TP
  79 .B imc
  80 Integrity Measurement Collector
  81 .TP
  82 .B imv
  83 Integrity Measurement Verifier
  84 .TP
  85 .B pts
  86 Platform Trust Service
  87 .SS Loglevels
  88 .TP
  89 .B -1
  90 Absolutely silent
  91 .TP
  92 .B 0
  93 Very basic auditing logs, (e.g. SA up/SA down)
  94 .TP
  95 .B 1
  96 Generic control flow with errors, a good default to see what's going on
  97 .TP
  98 .B 2
  99 More detailed debugging control flow
 100 .TP
 101 .B 3
 102 Including RAW data dumps in Hex
 103 .TP
 104 .B 4
 105 Also include sensitive material in dumps, e.g. keys
 106 .SS Example
 107 .PP
 108 .EX
 109         charon {
 110                 filelog {
 111                         /var/log/charon.log {
 112                                 time_format = %b %e %T
 113                                 append = no
 114                                 default = 1
 115                         }
 116                         stderr {
 117                                 ike = 2
 118                                 knl = 3
 119                                 ike_name = yes
 120                         }
 121                 }
 122                 syslog {
 123                         # enable logging to LOG_DAEMON, use defaults
 124                         daemon {
 125                         }
 126                         # minimalistic IKE auditing logging to LOG_AUTHPRIV
 127                         auth {
 128                                 default = -1
 129                                 ike = 0
 130                         }
 131                 }
 132         }
 133 .EE
 134
 135 .SH JOB PRIORITY MANAGEMENT
 136 Some operations in the IKEv2 daemon charon are currently implemented
 137 synchronously and blocking. Two examples for such operations are communication
 138 with a RADIUS server via EAP-RADIUS, or fetching CRL/OCSP information during
 139 certificate chain verification. Under high load conditions, the thread pool may
 140 run out of available threads, and some more important jobs, such as liveness
 141 checking, may not get executed in time.
 142 .PP
 143 To prevent thread starvation in such situations job priorities were introduced.
 144 The job processor will reserve some threads for higher priority jobs, these
 145 threads are not available for lower priority, locking jobs.
 146 .SS Implementation
 147 Currently 4 priorities have been defined, and they are used in charon as
 148 follows:
 149 .TP
 150 .B CRITICAL
 151 Priority for long-running dispatcher jobs.
 152 .TP
 153 .B HIGH
 154 INFORMATIONAL exchanges, as used by liveness checking (DPD).
 155 .TP
 156 .B MEDIUM
 157 Everything not HIGH/LOW, including IKE_SA_INIT processing.
 158 .TP
 159 .B LOW
 160 IKE_AUTH message processing. RADIUS and CRL fetching block here
 161 .PP
 162 Although IKE_SA_INIT processing is computationally expensive, it is explicitly
 163 assigned to the MEDIUM class. This allows charon to do the DH exchange while
 164 other threads are blocked in IKE_AUTH. To prevent the daemon from accepting more
 165 IKE_SA_INIT requests than it can handle, use IKE_SA_INIT DROPPING.
 166 .PP
 167 The thread pool processes jobs strictly by priority, meaning it will consume all
 168 higher priority jobs before looking for ones with lower priority. Further, it
 169 reserves threads for certain priorities. A priority class having reserved
 170 .I n
 171 threads will always have
 172 .I n
 173 threads available for this class (either currently processing a job, or waiting
 174 for one).
 175 .SS Configuration
 176 To ensure that there are always enough threads available for higher priority
 177 tasks, threads must be reserved for each priority class.
 178 .TP
 179 .BR charon.processor.priority_threads.critical " [0]"
 180 Threads reserved for CRITICAL priority class jobs
 181 .TP
 182 .BR charon.processor.priority_threads.high " [0]"
 183 Threads reserved for HIGH priority class jobs
 184 .TP
 185 .BR charon.processor.priority_threads.medium " [0]"
 186 Threads reserved for MEDIUM priority class jobs
 187 .TP
 188 .BR charon.processor.priority_threads.low " [0]"
 189 Threads reserved for LOW priority class jobs
 190 .PP
 191 Let's consider the following configuration:
 192 .PP
 193 .EX
 194         charon {
 195                 processor {
 196                         priority_threads {
 197                                 high = 1
 198                                 medium = 4
 199                         }
 200                 }
 201         }
 202 .EE
 203 .PP
 204 With this configuration, one thread is reserved for HIGH priority tasks. As
 205 currently only liveness checking and stroke message processing is done with
 206 high priority, one or two threads should be sufficient.
 207 .PP
 208 The MEDIUM class mostly processes non-blocking jobs. Unless your setup is
 209 experiencing many blocks in locks while accessing shared resources, threads for
 210 one or two times the number of CPU cores is fine.
 211 .PP
 212 It is usually not required to reserve threads for CRITICAL jobs. Jobs in this
 213 class rarely return and do not release their thread to the pool.
 214 .PP
 215 The remaining threads are available for LOW priority jobs. Reserving threads
 216 does not make sense (until we have an even lower priority).
 217 .SS Monitoring
 218 To see what the threads are actually doing, invoke
 219 .IR "ipsec statusall" .
 220 Under high load, something like this will show up:
 221 .PP
 222 .EX
 223         worker threads: 2 or 32 idle, 5/1/2/22 working,
 224                 job queue: 0/0/1/149, scheduled: 198
 225 .EE
 226 .PP
 227 From 32 worker threads,
 228 .IP 2
 229 are currently idle.
 230 .IP 5
 231 are running CRITICAL priority jobs (dispatching from sockets, etc.).
 232 .IP 1
 233 is currently handling a HIGH priority job. This is actually the thread currently
 234 providing this information via stroke.
 235 .IP 2
 236 are handling MEDIUM priority jobs, likely IKE_SA_INIT or CREATE_CHILD_SA
 237 messages.
 238 .IP 22
 239 are handling LOW priority jobs, probably waiting for an EAP-RADIUS response
 240 while processing IKE_AUTH messages.
 241 .PP
 242 The job queue load shows how many jobs are queued for each priority, ready for
 243 execution. The single MEDIUM priority job will get executed immediately, as
 244 we have two spare threads reserved for MEDIUM class jobs.
 245
 246 .SH IKE_SA_INIT DROPPING
 247 If a responder receives more connection requests per seconds than it can handle,
 248 it does not make sense to accept more IKE_SA_INIT messages. And if they are
 249 queued but can't get processed in time, an answer might be sent after the
 250 client has already given up and restarted its connection setup. This
 251 additionally increases the load on the responder.
 252 .PP
 253 To limit the responder load resulting from new connection attempts, the daemon
 254 can drop IKE_SA_INIT messages just after reception. There are two mechanisms to
 255 decide if this should happen, configured with the following options:
 256 .TP
 257 .BR charon.init_limit_half_open " [0]"
 258 Limit based on the number of half open IKE_SAs. Half open IKE_SAs are SAs in
 259 connecting state, but not yet established.
 260 .TP
 261 .BR charon.init_limit_job_load " [0]"
 262 Limit based on the number of jobs currently queued for processing (sum over all
 263 job priorities).
 264 .PP
 265 The second limit includes load from other jobs, such as rekeying. Choosing a
 266 good value is difficult and depends on the hardware and expected load.
 267 .PP
 268 The first limit is simpler to calculate, but includes the load from new
 269 connections only. If your responder is capable of negotiating 100 tunnels/s, you
 270 might set this limit to 1000. The daemon will then drop new connection attempts
 271 if generating a response would require more than 10 seconds. If you are
 272 allowing for a maximum response time of more than 30 seconds, consider adjusting
 273 the timeout for connecting IKE_SAs
 274 .RB ( charon.half_open_timeout ).
 275 A responder, by default, deletes an IKE_SA if the initiator does not establish
 276 it within 30 seconds. Under high load, a higher value might be required.
 277
 278 .SH LOAD TESTS
 279 To do stability testing and performance optimizations, the IKE daemon charon
 280 provides the \fIload-tester\fR plugin. This plugin allows one to setup thousands
 281 of tunnels concurrently against the daemon itself or a remote host.
 282 .PP
 283 .B WARNING:
 284 Never enable the load-testing plugin on productive systems. It provides
 285 preconfigured credentials and allows an attacker to authenticate as any user.
 286 .PP
 287 .SS Configuration details
 288 For public key authentication, the responder uses the
 289 .B \(dqCN=srv, OU=load-test, O=strongSwan\(dq
 290 identity. For the initiator, each connection attempt uses a different identity
 291 in the form
 292 .BR "\(dqCN=c1-r1, OU=load-test, O=strongSwan\(dq" ,
 293 where the first number inidicates the client number, the second the
 294 authentication round (if multiple authentication rounds are used).
 295 .PP
 296 For PSK authentication, FQDN identities are used. The server uses
 297 .BR srv.strongswan.org ,
 298 the client uses an identity in the form
 299 .BR c1-r1.strongswan.org .
 300 .PP
 301 For EAP authentication, the client uses a NAI in the form
 302 .BR 100000000010001@strongswan.org .
 303 .PP
 304 To configure multiple authentication rounds, concatenate multiple methods using,
 305 e.g.
 306 .EX
 307         initiator_auth = pubkey|psk|eap-md5|eap-aka
 308 .EE
 309 .PP
 310 The responder uses a hardcoded certificate based on a 1024-bit RSA key.
 311 This certificate additionally serves as CA certificate. A peer uses the same
 312 private key, but generates client certificates on demand signed by the CA
 313 certificate. Install the Responder/CA certificate on the remote host to
 314 authenticate all clients.
 315 .PP
 316 To speed up testing, the load tester plugin implements a special Diffie-Hellman
 317 implementation called \fImodpnull\fR. By setting
 318 .EX
 319         proposal = aes128-sha1-modpnull
 320 .EE
 321 this wicked fast DH implementation is used. It does not provide any security
 322 at all, but allows one to run tests without DH calculation overhead.
 323 .SS Examples
 324 .PP
 325 In the simplest case, the daemon initiates IKE_SAs against itself using the
 326 loopback interface. This will actually establish double the number of IKE_SAs,
 327 as the daemon is initiator and responder for each IKE_SA at the same time.
 328 Installation of IPsec SAs would fail, as each SA gets installed twice. To
 329 simulate the correct behavior, a fake kernel interface can be enabled which does
 330 not install the IPsec SAs at the kernel level.
 331 .PP
 332 A simple loopback configuration might look like this:
 333 .PP
 334 .EX
 335         charon {
 336                 # create new IKE_SAs for each CHILD_SA to simulate
 337                 # different clients
 338                 reuse_ikesa = no
 339                 # turn off denial of service protection
 340                 dos_protection = no
 341
 342                 plugins {
 343                         load-tester {
 344                                 # enable the plugin
 345                                 enable = yes
 346                                 # use 4 threads to initiate connections
 347                                 # simultaneously
 348                                 initiators = 4
 349                                 # each thread initiates 1000 connections
 350                                 iterations = 1000
 351                                 # delay each initiation in each thread by 20ms
 352                                 delay = 20
 353                                 # enable the fake kernel interface to
 354                                 # avoid SA conflicts
 355                                 fake_kernel = yes
 356                         }
 357                 }
 358         }
 359 .EE
 360 .PP
 361 This will initiate 4000 IKE_SAs within 20 seconds. You may increase the delay
 362 value if your box can not handle that much load, or decrease it to put more
 363 load on it. If the daemon starts retransmitting messages your box probably can
 364 not handle all connection attempts.
 365 .PP
 366 The plugin also allows one to test against a remote host. This might help to
 367 test against a real world configuration. A connection setup to do stress
 368 testing of a gateway might look like this:
 369 .PP
 370 .EX
 371         charon {
 372                 reuse_ikesa = no
 373                 threads = 32
 374
 375                 plugins {
 376                         load-tester {
 377                                 enable = yes
 378                                 # 10000 connections, ten in parallel
 379                                 initiators = 10
 380                                 iterations = 1000
 381                                 # use a delay of 100ms, overall time is:
 382                                 # iterations * delay = 100s
 383                                 delay = 100
 384                                 # address of the gateway
 385                                 remote = 1.2.3.4
 386                                 # IKE-proposal to use
 387                                 proposal = aes128-sha1-modp1024
 388                                 # use faster PSK authentication instead
 389                                 # of 1024bit RSA
 390                                 initiator_auth = psk
 391                                 responder_auth = psk
 392                                 # request a virtual IP using configuration
 393                                 # payloads
 394                                 request_virtual_ip = yes
 395                                 # enable CHILD_SA every 60s
 396                                 child_rekey = 60
 397                         }
 398                 }
 399         }
 400 .EE
 401
 402 .SH IKEv2 RETRANSMISSION
 403 Retransmission timeouts in the IKEv2 daemon charon can be configured globally
 404 using the three keys listed below:
 405 .PP
 406 .RS
 407 .nf
 408 .BR charon.retransmit_base " [1.8]"
 409 .BR charon.retransmit_timeout " [4.0]"
 410 .BR charon.retransmit_tries " [5]"
 411 .BR charon.retransmit_jitter " [0]"
 412 .BR charon.retransmit_limit " [0]"
 413 .fi
 414 .RE
 415 .PP
 416 The following algorithm is used to calculate the timeout:
 417 .PP
 418 .EX
 419         relative timeout = retransmit_timeout * retransmit_base ^ (n-1)
 420 .EE
 421 .PP
 422 Where
 423 .I n
 424 is the current retransmission count. The calculated timeout can't exceed the
 425 configured retransmit_limit (if any), which is useful if the number of retries
 426 is high.
 427 .PP
 428 If a jitter in percent is configured, the timeout is modified as follows:
 429 .PP
 430 .EX
 431         relative timeout -= random(0, retransmit_jitter * relative timeout)
 432 .EE
 433 .PP
 434 Using the default values, packets are retransmitted in:
 435
 436 .TS
 437 l r r
 438 ---
 439 lB r r.
 440 Retransmission  Relative Timeout        Absolute Timeout
 441 1       4s      4s
 442 2       7s      11s
 443 3       13s     24s
 444 4       23s     47s
 445 5       42s     89s
 446 giving up       76s     165s
 447 .TE
 448 .
 449 .SH VARIABLES
 450 .
 451 The variables used above are configured as follows:
 452
 453 .nf
 454 .na
 455 ${piddir}               @piddir@
 456 ${prefix}               @prefix@
 457 ${random_device}        @random_device@
 458 ${urandom_device}       @urandom_device@
 459 .ad
 460 .fi
 461 .
 462 .SH FILES
 463 .
 464 .nf
 465 .na
 466 /etc/strongswan.conf       configuration file
 467 /etc/strongswan.d/         directory containing included config snippets
 468 /etc/strongswan.d/charon/  plugin specific config snippets
 469 .ad
 470 .fi
 471 .
 472 .SH SEE ALSO
 473 \fBipsec.conf\fR(5), \fBipsec.secrets\fR(5), \fBipsec\fR(8), \fBcharon-cmd\fR(8)
 474
 475 .SH HISTORY
 476 Written for the
 477 .UR http://www.strongswan.org
 478 strongSwan project
 479 .UE
 480 by Tobias Brunner, Andreas Steffen and Martin Willi.