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