8470120bcbdbb5d64f4b709e9fb49773e1201ed9
[strongswan.git] / 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 whats 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 IKEv2 daemon charon
280 provides the load-tester plugin. This plugin allows one to setup thousands of
281 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 .SS Options
287 .TP
288 .BR charon.plugins.load-tester.addrs
289 Subsection that contains key/value pairs with address pools (in CIDR notation)
290 to use for a specific network interface e.g. eth0 = 10.10.0.0/16
291 .TP
292 .BR charon.plugins.load-tester.addrs_keep " [no]"
293 Whether to keep dynamic addresses even after the associated SA got terminated
294 .TP
295 .BR charon.plugins.load-tester.addrs_prefix " [16]"
296 Network prefix length to use when installing dynamic addresses. If set to -1 the
297 full address is used (i.e. 32 or 128)
298 .TP
299 .BR charon.plugins.load-tester.ca_dir
300 Directory to load (intermediate) CA certificates from
301 .TP
302 .BR charon.plugins.load-tester.child_rekey " [600]"
303 Seconds to start CHILD_SA rekeying after setup
304 .TP
305 .BR charon.plugins.load-tester.delay " [0]"
306 Delay between initiatons for each thread
307 .TP
308 .BR charon.plugins.load-tester.delete_after_established " [no]"
309 Delete an IKE_SA as soon as it has been established
310 .TP
311 .BR charon.plugins.load-tester.digest " [sha1]"
312 Digest algorithm used when issuing certificates
313 .TP
314 .BR charon.plugins.load-tester.dpd_delay " [0]"
315 DPD delay to use in load test
316 .TP
317 .BR charon.plugins.load-tester.dynamic_port " [0]"
318 Base port to be used for requests (each client uses a different port)
319 .TP
320 .BR charon.plugins.load-tester.eap_password " [default-pwd]"
321 EAP secret to use in load test
322 .TP
323 .BR charon.plugins.load-tester.enable " [no]"
324 Enable the load testing plugin
325 .TP
326 .BR charon.plugins.load-tester.esp " [aes128-sha1]"
327 CHILD_SA proposal to use for load tests
328 .TP
329 .BR charon.plugins.load-tester.fake_kernel " [no]"
330 Fake the kernel interface to allow load-testing against self
331 .TP
332 .BR charon.plugins.load-tester.ike_rekey " [0]"
333 Seconds to start IKE_SA rekeying after setup
334 .TP
335 .BR charon.plugins.load-tester.init_limit " [0]"
336 Global limit of concurrently established SAs during load test
337 .TP
338 .BR charon.plugins.load-tester.initiator " [0.0.0.0]"
339 Address to initiate from
340 .TP
341 .BR charon.plugins.load-tester.initiators " [0]"
342 Number of concurrent initiator threads to use in load test
343 .TP
344 .BR charon.plugins.load-tester.initiator_auth " [pubkey]"
345 Authentication method(s) the intiator uses
346 .TP
347 .BR charon.plugins.load-tester.initiator_id
348 Initiator ID used in load test
349 .TP
350 .BR charon.plugins.load-tester.initiator_match
351 Initiator ID to match against as responder
352 .TP
353 .BR charon.plugins.load-tester.initiator_tsi
354 Traffic selector on initiator side, as proposed by initiator
355 .TP
356 .BR charon.plugins.load-tester.initiator_tsr
357 Traffic selector on responder side, as proposed by initiator
358 .TP
359 .BR charon.plugins.load-tester.iterations " [1]"
360 Number of IKE_SAs to initiate by each initiator in load test
361 .TP
362 .BR charon.plugins.load-tester.issuer_cert
363 Path to the issuer certificate (if not configured a hard-coded value is used)
364 .TP
365 .BR charon.plugins.load-tester.issuer_key
366 Path to private key that is used to issue certificates (if not configured a
367 hard-coded value is used)
368 .TP
369 .BR charon.plugins.load-tester.mode " [tunnel]"
370 IPsec mode to use, one of \fBtunnel\fR, \fBtransport\fR, or \fBbeet\fR.
371 .TP
372 .BR charon.plugins.load-tester.pool
373 Provide INTERNAL_IPV4_ADDRs from a named pool
374 .TP
375 .BR charon.plugins.load-tester.preshared_key " [default-psk]"
376 Preshared key to use in load test
377 .TP
378 .BR charon.plugins.load-tester.proposal " [aes128-sha1-modp768]"
379 IKE proposal to use in load test
380 .TP
381 .BR charon.plugins.load-tester.responder " [127.0.0.1]"
382 Address to initiation connections to
383 .TP
384 .BR charon.plugins.load-tester.responder_auth " [pubkey]"
385 Authentication method(s) the responder uses
386 .TP
387 .BR charon.plugins.load-tester.responder_id
388 Responder ID used in load test
389 .TP
390 .BR charon.plugins.load-tester.responder_tsi " [initiator_tsi]"
391 Traffic selector on initiator side, as narrowed by responder
392 .TP
393 .BR charon.plugins.load-tester.responder_tsr " [initiator_tsr]"
394 Traffic selector on responder side, as narrowed by responder
395 .TP
396 .BR charon.plugins.load-tester.request_virtual_ip " [no]"
397 Request an INTERNAL_IPV4_ADDR from the server
398 .TP
399 .BR charon.plugins.load-tester.shutdown_when_complete " [no]"
400 Shutdown the daemon after all IKE_SAs have been established
401 .TP
402 .BR charon.plugins.load-tester.socket " [unix://@piddir@/charon.ldt]"
403 Socket provided by the load-tester plugin
404 .TP
405 .BR charon.plugins.load-tester.version " [0]"
406 IKE version to use (0 means use IKEv2 as initiator and accept any version as
407 responder)
408 .PP
409 .SS Configuration details
410 For public key authentication, the responder uses the
411 .B \(dqCN=srv, OU=load-test, O=strongSwan\(dq
412 identity. For the initiator, each connection attempt uses a different identity
413 in the form
414 .BR "\(dqCN=c1-r1, OU=load-test, O=strongSwan\(dq" ,
415 where the first number inidicates the client number, the second the
416 authentication round (if multiple authentication is used).
417 .PP
418 For PSK authentication, FQDN identities are used. The server uses
419 .BR srv.strongswan.org ,
420 the client uses an identity in the form
421 .BR c1-r1.strongswan.org .
422 .PP
423 For EAP authentication, the client uses a NAI in the form
424 .BR 100000000010001@strongswan.org .
425 .PP
426 To configure multiple authentication, concatenate multiple methods using, e.g.
427 .EX
428         initiator_auth = pubkey|psk|eap-md5|eap-aka
429 .EE
430 .PP
431 The responder uses a hardcoded certificate based on a 1024-bit RSA key.
432 This certificate additionally serves as CA certificate. A peer uses the same
433 private key, but generates client certificates on demand signed by the CA
434 certificate. Install the Responder/CA certificate on the remote host to
435 authenticate all clients.
436 .PP
437 To speed up testing, the load tester plugin implements a special Diffie-Hellman
438 implementation called modpnull. By setting
439 .EX
440         proposal = aes128-sha1-modpnull
441 .EE
442 this wicked fast DH implementation is used. It does not provide any security
443 at all, but allows one to run tests without DH calculation overhead.
444 .SS Examples
445 .PP
446 In the simplest case, the daemon initiates IKE_SAs against itself using the
447 loopback interface. This will actually establish double the number of IKE_SAs,
448 as the daemon is initiator and responder for each IKE_SA at the same time.
449 Installation of IPsec SAs would fails, as each SA gets installed twice. To
450 simulate the correct behavior, a fake kernel interface can be enabled which does
451 not install the IPsec SAs at the kernel level.
452 .PP
453 A simple loopback configuration might look like this:
454 .PP
455 .EX
456         charon {
457                 # create new IKE_SAs for each CHILD_SA to simulate
458                 # different clients
459                 reuse_ikesa = no
460                 # turn off denial of service protection
461                 dos_protection = no
462
463                 plugins {
464                         load-tester {
465                                 # enable the plugin
466                                 enable = yes
467                                 # use 4 threads to initiate connections
468                                 # simultaneously
469                                 initiators = 4
470                                 # each thread initiates 1000 connections
471                                 iterations = 1000
472                                 # delay each initiation in each thread by 20ms
473                                 delay = 20
474                                 # enable the fake kernel interface to
475                                 # avoid SA conflicts
476                                 fake_kernel = yes
477                         }
478                 }
479         }
480 .EE
481 .PP
482 This will initiate 4000 IKE_SAs within 20 seconds. You may increase the delay
483 value if your box can not handle that much load, or decrease it to put more
484 load on it. If the daemon starts retransmitting messages your box probably can
485 not handle all connection attempts.
486 .PP
487 The plugin also allows one to test against a remote host. This might help to
488 test against a real world configuration. A connection setup to do stress
489 testing of a gateway might look like this:
490 .PP
491 .EX
492         charon {
493                 reuse_ikesa = no
494                 threads = 32
495
496                 plugins {
497                         load-tester {
498                                 enable = yes
499                                 # 10000 connections, ten in parallel
500                                 initiators = 10
501                                 iterations = 1000
502                                 # use a delay of 100ms, overall time is:
503                                 # iterations * delay = 100s
504                                 delay = 100
505                                 # address of the gateway
506                                 remote = 1.2.3.4
507                                 # IKE-proposal to use
508                                 proposal = aes128-sha1-modp1024
509                                 # use faster PSK authentication instead
510                                 # of 1024bit RSA
511                                 initiator_auth = psk
512                                 responder_auth = psk
513                                 # request a virtual IP using configuration
514                                 # payloads
515                                 request_virtual_ip = yes
516                                 # enable CHILD_SA every 60s
517                                 child_rekey = 60
518                         }
519                 }
520         }
521 .EE
522
523 .SH IKEv2 RETRANSMISSION
524 Retransmission timeouts in the IKEv2 daemon charon can be configured globally
525 using the three keys listed below:
526 .PP
527 .RS
528 .nf
529 .BR charon.retransmit_base " [1.8]"
530 .BR charon.retransmit_timeout " [4.0]"
531 .BR charon.retransmit_tries " [5]"
532 .fi
533 .RE
534 .PP
535 The following algorithm is used to calculate the timeout:
536 .PP
537 .EX
538         relative timeout = retransmit_timeout * retransmit_base ^ (n-1)
539 .EE
540 .PP
541 Where
542 .I n
543 is the current retransmission count.
544 .PP
545 Using the default values, packets are retransmitted in:
546
547 .TS
548 l r r
549 ---
550 lB r r.
551 Retransmission  Relative Timeout        Absolute Timeout
552 1       4s      4s
553 2       7s      11s
554 3       13s     24s
555 4       23s     47s
556 5       42s     89s
557 giving up       76s     165s
558 .TE
559
560 .SH FILES
561 /etc/strongswan.conf
562
563 .SH SEE ALSO
564 \fBipsec.conf\fR(5), \fBipsec.secrets\fR(5), \fBipsec\fR(8), \fBcharon-cmd\fR(8)
565
566 .SH HISTORY
567 Written for the
568 .UR http://www.strongswan.org
569 strongSwan project
570 .UE
571 by Tobias Brunner, Andreas Steffen and Martin Willi.