conf/strongswan.conf.5.tail.in

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