conf: Split strongswan.conf(5) man page and use generated snippet
[strongswan.git] / 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.