Prevent deadlock while shutting down thread pool.
[strongswan.git] / man / strongswan.conf.5.in
1 .TH STRONGSWAN.CONF 5 "2010-09-09" "@IPSEC_VERSION@" "strongSwan"
2 .SH NAME
3 strongswan.conf \- strongSwan configuration file
4 .SH DESCRIPTION
5 While the
6 .IR ipsec.conf (5)
7 configuration file is well suited to define IPsec related configuration
8 parameters, it is not useful for other strongSwan applications to read options
9 from this file.
10 The file is hard to parse and only
11 .I ipsec starter
12 is capable of doing so. As the number of components of the strongSwan project
13 is continually growing, a more flexible configuration file was needed, one that
14 is easy to extend and can be used by all components. With strongSwan 4.2.1
15 .IR strongswan.conf (5)
16 was introduced which meets these requirements.
17
18 .SH SYNTAX
19 The format of the strongswan.conf file consists of hierarchical
20 .B sections
21 and a list of
22 .B key/value pairs
23 in each section. Each section has a name, followed by C-Style curly brackets
24 defining the section body. Each section body contains a set of subsections
25 and key/value pairs:
26 .PP
27 .EX
28         settings := (section|keyvalue)*
29         section  := name { settings }
30         keyvalue := key = value\\n
31 .EE
32 .PP
33 Values must be terminated by a newline.
34 .PP
35 Comments are possible using the \fB#\fP-character, but be careful: The parser
36 implementation is currently limited and does not like brackets in comments.
37 .PP
38 Section names and keys may contain any printable character except:
39 .PP
40 .EX
41         . { } # \\n \\t space
42 .EE
43 .PP
44 An example file in this format might look like this:
45 .PP
46 .EX
47         a = b
48         section-one {
49                 somevalue = asdf
50                 subsection {
51                         othervalue = xxx
52                 }
53                 # yei, a comment
54                 yetanother = zz
55         }
56         section-two {
57                 x = 12
58         }
59 .EE
60 .PP
61 Indentation is optional, you may use tabs or spaces.
62
63 .SH INCLUDING FILES
64 Using the
65 .B include
66 statement it is possible to include other files into strongswan.conf, e.g.
67 .PP
68 .EX
69         include /some/path/*.conf
70 .EE
71 .PP
72 If the file name is not an absolute path, it is considered to be relative
73 to the directory of the file containing the include statement. The file name
74 may include shell wildcards (see
75 .IR sh (1)).
76 Also, such inclusions can be nested.
77 .PP
78 Sections loaded from included files
79 .I extend
80 previously loaded sections; already existing values are
81 .IR replaced .
82 It is important to note that settings are added relative to the section the
83 include statement is in.
84 .PP
85 As an example, the following three files result in the same final
86 config as the one given above:
87 .PP
88 .EX
89         a = b
90         section-one {
91                 somevalue = before include
92                 include include.conf
93         }
94         include other.conf
95
96 include.conf:
97         # settings loaded from this file are added to section-one
98         # the following replaces the previous value
99         somevalue = asdf
100         subsection {
101                 othervalue = yyy
102         }
103         yetanother = zz
104
105 other.conf:
106         # this extends section-one and subsection
107         section-one {
108                 subsection {
109                         # this replaces the previous value
110                         othervalue = xxx
111                 }
112         }
113         section-two {
114                 x = 12
115         }
116 .EE
117
118 .SH READING VALUES
119 Values are accessed using a dot-separated section list and a key.
120 With reference to the example above, accessing
121 .B section-one.subsection.othervalue
122 will return
123 .BR xxx .
124
125 .SH DEFINED KEYS
126 The following keys are currently defined (using dot notation). The default
127 value (if any) is listed in brackets after the key.
128
129 .SS charon section
130 .TP
131 .BR charon.block_threshold " [5]"
132 Maximum number of half-open IKE_SAs for a single peer IP
133 .TP
134 .BR charon.close_ike_on_child_failure " [no]"
135 Close the IKE_SA if setup of the CHILD_SA along with IKE_AUTH failed
136 .TP
137 .BR charon.cookie_threshold " [10]"
138 Number of half-open IKE_SAs that activate the cookie mechanism
139 .TP
140 .BR charon.dns1
141 .TQ
142 .BR charon.dns2
143 DNS servers assigned to peer via configuration payload (CP)
144 .TP
145 .BR charon.dos_protection " [yes]"
146 Enable Denial of Service protection using cookies and aggressiveness checks
147 .TP
148 .BR charon.filelog
149 Section to define file loggers, see LOGGER CONFIGURATION
150 .TP
151 .BR charon.flush_auth_cfg " [no]"
152
153 .TP
154 .BR charon.hash_and_url " [no]"
155 Enable hash and URL support
156 .TP
157 .BR charon.ignore_routing_tables
158 A list of routing tables to be excluded from route lookup
159 .TP
160 .BR charon.ikesa_table_segments " [1]"
161 Number of exclusively locked segments in the hash table
162 .TP
163 .BR charon.ikesa_table_size " [1]"
164 Size of the IKE_SA hash table
165 .TP
166 .BR charon.inactivity_close_ike " [no]"
167 Whether to close IKE_SA if the only CHILD_SA closed due to inactivity
168 .TP
169 .BR charon.install_routes " [yes]"
170 Install routes into a separate routing table for established IPsec tunnels
171 .TP
172 .BR charon.install_virtual_ip " [yes]"
173 Install virtual IP addresses
174 .TP
175 .BR charon.keep_alive " [20s]"
176 NAT keep alive interval
177 .TP
178 .BR charon.load
179 Plugins to load in the IKEv2 daemon charon
180 .TP
181 .BR charon.max_packet " [10000]"
182 Maximum packet size accepted by charon
183 .TP
184 .BR charon.multiple_authentication " [yes]"
185 Enable multiple authentication exchanges (RFC 4739)
186 .TP
187 .BR charon.nbns1
188 .TQ
189 .BR charon.nbns2
190 WINS servers assigned to peer via configuration payload (CP)
191 .TP
192 .BR charon.process_route " [yes]"
193 Process RTM_NEWROUTE and RTM_DELROUTE events
194 .TP
195 .BR charon.receive_delay " [0]"
196 Delay for receiving packets, to simulate larger RTT
197 .TP
198 .BR charon.receive_delay_response " [yes]"
199 Delay response messages
200 .TP
201 .BR charon.receive_delay_request " [yes]"
202 Delay request messages
203 .TP
204 .BR charon.receive_delay_type " [0]"
205 Specific IKEv2 message type to delay, 0 for any
206 .TP
207 .BR charon.replay_window " [32]"
208 Size of the AH/ESP replay window, in packets.
209 .TP
210 .BR charon.retransmit_base " [1.8]"
211 Base to use for calculating exponential back off, see IKEv2 RETRANSMISSION
212 .TP
213 .BR charon.retransmit_timeout " [4.0]
214 Timeout in seconds before sending first retransmit
215 .TP
216 .BR charon.retransmit_tries " [5]"
217 Number of times to retransmit a packet before giving up
218 .TP
219 .BR charon.reuse_ikesa " [yes]
220 Initiate CHILD_SA within existing IKE_SAs
221 .TP
222 .BR charon.routing_table
223 Numerical routing table to install routes to
224 .TP
225 .BR charon.routing_table_prio
226 Priority of the routing table
227 .TP
228 .BR charon.send_delay " [0]"
229 Delay for sending packets, to simulate larger RTT
230 .TP
231 .BR charon.send_delay_response " [yes]"
232 Delay response messages
233 .TP
234 .BR charon.send_delay_request " [yes]"
235 Delay request messages
236 .TP
237 .BR charon.send_delay_type " [0]"
238 Specific IKEv2 message type to delay, 0 for any
239 .TP
240 .BR charon.send_vendor_id " [no]
241 Send strongSwan vendor ID payload
242 .TP
243 .BR charon.syslog
244 Section to define syslog loggers, see LOGGER CONFIGURATION
245 .TP
246 .BR charon.threads " [16]"
247 Number of worker threads in charon
248 .SS charon.plugins subsection
249 .TP
250 .BR charon.plugins.android.loglevel " [1]"
251 Loglevel for logging to Android specific logger
252 .TP
253 .BR charon.plugins.attr
254 Section to specify arbitrary attributes that are assigned to a peer via
255 configuration payload (CP)
256 .TP
257 .BR charon.plugins.dhcp.identity_lease " [no]"
258 Derive user-defined MAC address from hash of IKEv2 identity
259 .TP
260 .BR charon.plugins.dhcp.server " [255.255.255.255]"
261 DHCP server unicast or broadcast IP address
262 .TP
263 .BR charon.plugins.duplicheck.enable " [yes]"
264 enable loaded duplicheck plugin
265 .TP
266 .BR charon.plugins.eap-aka.request_identity " [yes]"
267
268 .TP
269 .BR charon.plugins.eap-aka-3ggp2.seq_check
270
271 .TP
272 .BR charon.plugins.eap-gtc.pam_service " [login]"
273 PAM service to be used for authentication
274
275 .TP
276 .BR charon.plugins.eap-peap.fragment_size " [1024]"
277 Maximum size of an EAP-PEAP packet
278 .TP
279 .BR charon.plugins.eap-peap.max_message_count " [32]"
280 Maximum number of processed EAP-PEAP packets
281 .TP
282 .BR charon.plugins.eap-peap.include_length " [no]"
283 Include length in non-fragmented EAP-PEAP packets
284 .TP
285 .BR charon.plugins.eap-peap.phase2_method " [mschapv2]"
286 Phase2 EAP client authentication method
287 .TP
288 .BR charon.plugins.eap-peap.phase2_piggyback " [no]"
289 Phase2 EAP Identity request piggybacked by server onto TLS Finished message
290 .TP
291 .BR charon.plugins.eap-peap.phase2_tnc " [no]"
292 Start phase2 EAP TNC protocol after successful client authentication
293 .TP
294 .BR charon.plugins.eap-peap.request_peer_auth " [no]"
295 Request peer authentication based on a client certificate
296
297 .TP
298 .BR charon.plugins.eap-radius.class_group " [no]"
299 Use the
300 .I class
301 attribute sent in the RADIUS-Accept message as group membership information that
302 is compared to the groups specified in the
303 .B rightgroups
304 option in
305 .B ipsec.conf (5).
306 .TP
307 .BR charon.plugins.eap-radius.eap_start " [no]"
308 Send EAP-Start instead of EAP-Identity to start RADIUS conversation
309 .TP
310 .BR charon.plugins.eap-radius.filter_id " [no]"
311 If the RADIUS
312 .I tunnel_type
313 attribute with value
314 .B ESP
315 is received, use the
316 .I filter_id
317 attribute sent in the RADIUS-Accept message as group membership information that
318 is compared to the groups specified in the
319 .B rightgroups
320 option in
321 .B ipsec.conf (5).
322 .TP
323 .BR charon.plugins.eap-radius.id_prefix
324 Prefix to EAP-Identity, some AAA servers use a IMSI prefix to select the
325 EAP method
326 .TP
327 .BR charon.plugins.eap-radius.nas_identifier " [strongSwan]"
328 NAS-Identifier to include in RADIUS messages
329 .TP
330 .BR charon.plugins.eap-radius.port " [1812]"
331 Port of RADIUS server (authentication)
332 .TP
333 .BR charon.plugins.eap-radius.secret
334 Shared secret between RADIUS and NAS
335 .TP
336 .BR charon.plugins.eap-radius.server
337 IP/Hostname of RADIUS server
338 .TP
339 .BR charon.plugins.eap-radius.servers
340 Section to specify multiple RADIUS servers. The
341 .BR nas_identifier ,
342 .BR secret ,
343 .B sockets
344 and
345 .B port
346 options can be specified for each server. A server's IP/Hostname can be
347 configured using the
348 .B address
349 option. For each RADIUS server a priority can be specified using the
350 .BR preference " [0]"
351 option.
352 .TP
353 .BR charon.plugins.eap-radius.sockets " [1]"
354 Number of sockets (ports) to use, increase for high load
355 .TP
356 .BR charon.plugins.eap-sim.request_identity " [yes]"
357
358 .TP
359 .BR charon.plugins.eap-simaka-sql.database
360
361 .TP
362 .BR charon.plugins.eap-simaka-sql.remove_used
363
364 .TP
365 .BR charon.plugins.eap-tls.fragment_size " [1024]"
366 Maximum size of an EAP-TLS packet
367 .TP
368 .BR charon.plugins.eap-tls.max_message_count " [32]"
369 Maximum number of processed EAP-TLS packets
370 .TP
371 .BR charon.plugins.eap-tls.include_length " [yes]"
372 Include length in non-fragmented EAP-TLS packets
373 .TP
374 .BR charon.plugins.eap-tnc.fragment_size " [50000]"
375 Maximum size of an EAP-TNC packet
376 .TP
377 .BR charon.plugins.eap-tnc.max_message_count " [10]"
378 Maximum number of processed EAP-TNC packets
379 .TP
380 .BR charon.plugins.eap-tnc.include_length " [yes]"
381 Include length in non-fragmented EAP-TNC packets
382 .TP
383 .BR charon.plugins.eap-ttls.fragment_size " [1024]"
384 Maximum size of an EAP-TTLS packet
385 .TP
386 .BR charon.plugins.eap-ttls.max_message_count " [32]"
387 Maximum number of processed EAP-TTLS packets
388 .TP
389 .BR charon.plugins.eap-ttls.include_length " [yes]"
390 Include length in non-fragmented EAP-TTLS packets
391 .TP
392 .BR charon.plugins.eap-ttls.phase2_method " [md5]"
393 Phase2 EAP client authentication method
394 .TP
395 .BR charon.plugins.eap-ttls.phase2_piggyback " [no]"
396 Phase2 EAP Identity request piggybacked by server onto TLS Finished message
397 .TP
398 .BR charon.plugins.eap-ttls.phase2_tnc " [no]"
399 Start phase2 EAP TNC protocol after successful client authentication
400 .TP
401 .BR charon.plugins.eap-ttls.request_peer_auth " [no]"
402 Request peer authentication based on a client certificate
403 .TP
404 .BR charon.plugins.ha.fifo_interface " [yes]"
405
406 .TP
407 .BR charon.plugins.ha.heartbeat_delay " [1000]"
408
409 .TP
410 .BR charon.plugins.ha.heartbeat_timeout " [2100]"
411
412 .TP
413 .BR charon.plugins.ha.local
414
415 .TP
416 .BR charon.plugins.ha.monitor " [yes]"
417
418 .TP
419 .BR charon.plugins.ha.pools
420
421 .TP
422 .BR charon.plugins.ha.remote
423
424 .TP
425 .BR charon.plugins.ha.resync " [yes]"
426
427 .TP
428 .BR charon.plugins.ha.secret
429
430 .TP
431 .BR charon.plugins.ha.segment_count " [1]"
432
433 .TP
434 .BR charon.plugins.led.activity_led
435
436 .TP
437 .BR charon.plugins.led.blink_time " [50]"
438
439 .TP
440 .BR charon.plugins.kernel-klips.ipsec_dev_count " [4]"
441 Number of ipsecN devices
442 .TP
443 .BR charon.plugins.kernel-klips.ipsec_dev_mtu " [0]"
444 Set MTU of ipsecN device
445 .TP
446 .BR charon.plugins.load-tester
447 Section to configure the load-tester plugin, see LOAD TESTS
448 .TP
449 .BR charon.plugins.resolve.file " [/etc/resolv.conf]"
450 File where to add DNS server entries
451 .TP
452 .BR charon.plugins.sql.database
453 Database URI for charons SQL plugin
454 .TP
455 .BR charon.plugins.sql.loglevel " [-1]"
456 Loglevel for logging to SQL database
457 .TP
458 .BR charon.plugins.tnc-imc.preferred_language " [en]"
459 Preferred language for TNC recommendations
460 .TP
461 .BR charon.plugins.tnc-imc.tnc_config " [/etc/tnc_config]"
462 TNC IMC configuration directory
463 .TP
464 .BR charon.plugins.tnc-imv.tnc_config " [/etc/tnc_config]"
465 TNC IMV configuration directory
466 .TP
467 .BR charon.plugins.whitelist.enable " [yes]"
468 enable loaded whitelist plugin
469 .SS libstrongswan section
470 .TP
471 .BR libstrongswan.crypto_test.bench " [no]"
472
473 .TP
474 .BR libstrongswan.crypto_test.bench_size " [1024]"
475
476 .TP
477 .BR libstrongswan.crypto_test.bench_time " [50]"
478
479 .TP
480 .BR libstrongswan.crypto_test.on_add " [no]"
481 Test crypto algorithms during registration
482 .TP
483 .BR libstrongswan.crypto_test.on_create " [no]"
484 Test crypto algorithms on each crypto primitive instantiation
485 .TP
486 .BR libstrongswan.crypto_test.required " [no]"
487 Strictly require at least one test vector to enable an algorithm
488 .TP
489 .BR libstrongswan.crypto_test.rng_true " [no]"
490 Whether to test RNG with TRUE quality; requires a lot of entropy
491 .TP
492 .BR libstrongswan.dh_exponent_ansi_x9_42 " [yes]"
493 Use ANSI X9.42 DH exponent size or optimum size matched to cryptographical
494 strength
495 .TP
496 .BR libstrongswan.ecp_x_coordinate_only " [yes]"
497 Compliance with the errata for RFC 4753
498 .TP
499 .BR libstrongswan.integrity_test " [no]"
500 Check daemon, libstrongswan and plugin integrity at startup
501 .TP
502 .BR libstrongswan.leak_detective.detailed " [yes]"
503 Includes source file names and line numbers in leak detective output
504 .TP
505 .BR libstrongswan.x509.enforce_critical " [yes]"
506 Discard certificates with unsupported or unknown critical extensions
507 .SS libstrongswan.plugins subsection
508 .TP
509 .BR libstrongswan.plugins.attr-sql.database
510 Database URI for attr-sql plugin used by charon and pluto
511 .TP
512 .BR libstrongswan.plugins.attr-sql.lease_history " [yes]"
513 Enable logging of SQL IP pool leases
514 .TP
515 .BR libstrongswan.plugins.gcrypt.quick_random " [no]"
516 Use faster random numbers in gcrypt; for testing only, produces weak keys!
517 .TP
518 .BR libstrongswan.plugins.openssl.engine_id " [pkcs11]"
519 ENGINE ID to use in the OpenSSL plugin
520 .TP
521 .BR libstrongswan.plugins.pkcs11.modules
522 .TP
523 .BR libstrongswan.plugins.pkcs11.use_hasher " [no]"
524 .SS libtls section
525 .TP
526 .BR libtls.cipher
527 List of TLS encryption ciphers
528 .TP
529 .BR libtls.key_exchange
530 List of TLS key exchange methods
531 .TP
532 .BR libtls.mac
533 List of TLS MAC algorithms
534 .TP
535 .BR libtls.suites
536 List of TLS cipher suites
537 .SS manager section
538 .TP
539 .BR manager.database
540 Credential database URI for manager
541 .TP
542 .BR manager.debug " [no]"
543 Enable debugging in manager
544 .TP
545 .BR manager.load
546 Plugins to load in manager
547 .TP
548 .BR manager.socket
549 FastCGI socket of manager, to run it statically
550 .TP
551 .BR manager.threads " [10]"
552 Threads to use for request handling
553 .TP
554 .BR manager.timeout " [15m]"
555 Session timeout for manager
556 .SS mediation client section
557 .TP
558 .BR medcli.database
559 Mediation client database URI
560 .TP
561 .BR medcli.dpd " [5m]"
562 DPD timeout to use in mediation client plugin
563 .TP
564 .BR medcli.rekey " [20m]"
565 Rekeying time on mediation connections in mediation client plugin
566 .SS mediation server section
567 .TP
568 .BR medsrv.database
569 Mediation server database URI
570 .TP
571 .BR medsrv.debug " [no]"
572 Debugging in mediation server web application
573 .TP
574 .BR medsrv.dpd " [5m]"
575 DPD timeout to use in mediation server plugin
576 .TP
577 .BR medsrv.load
578 Plugins to load in mediation server plugin
579 .TP
580 .BR medsrv.password_length " [6]"
581 Minimum password length required for mediation server user accounts
582 .TP
583 .BR medsrv.rekey " [20m]"
584 Rekeying time on mediation connections in mediation server plugin
585 .TP
586 .BR medsrv.socket
587 Run Mediation server web application statically on socket
588 .TP
589 .BR medsrv.threads " [5]"
590 Number of thread for mediation service web application
591 .TP
592 .BR medsrv.timeout " [15m]"
593 Session timeout for mediation service
594 .SS openac section
595 .TP
596 .BR openac.load
597 Plugins to load in ipsec openac tool
598 .SS pki section
599 .TP
600 .BR pki.load
601 Plugins to load in ipsec pki tool
602 .SS pluto section
603 .TP
604 .BR pluto.dns1
605 .TQ
606 .BR pluto.dns2
607 DNS servers assigned to peer via Mode Config
608 .TP
609 .BR pluto.load
610 Plugins to load in IKEv1 pluto daemon
611 .TP
612 .BR pluto.nbns1
613 .TQ
614 .BR pluto.nbns2
615 WINS servers assigned to peer via Mode Config
616 .TP
617 .BR pluto.threads " [4]"
618 Number of worker threads in pluto
619 .SS pluto.plugins section
620 .TP
621 .BR pluto.plugins.attr
622 Section to specify arbitrary attributes that are assigned to a peer via
623 Mode Config
624 .TP
625 .BR charon.plugins.kernel-klips.ipsec_dev_count " [4]"
626 Number of ipsecN devices
627 .TP
628 .BR charon.plugins.kernel-klips.ipsec_dev_mtu " [0]"
629 Set MTU of ipsecN device
630 .SS pool section
631 .TP
632 .BR pool.load
633 Plugins to load in ipsec pool tool
634 .SS scepclient section
635 .TP
636 .BR scepclient.load
637 Plugins to load in ipsec scepclient tool
638 .SS starter section
639 .TP
640 .BR starter.load_warning " [yes]"
641 Disable charon/pluto plugin load option warning
642
643 .SH LOGGER CONFIGURATION
644 The options described below provide a much more flexible way to configure
645 loggers for the IKEv2 daemon charon than using the
646 .B charondebug
647 option in
648 .BR ipsec.conf (5).
649 .PP
650 .B Please note
651 that if any loggers are specified in strongswan.conf,
652 .B charondebug
653 does not have any effect.
654 .PP
655 There are currently two types of loggers defined:
656 .TP
657 .B File loggers
658 Log directly to a file and are defined by specifying the full path to the
659 file as subsection in the
660 .B charon.filelog
661 section. To log to the console the two special filenames
662 .BR stdout " and " stderr
663 can be used.
664 .TP
665 .B Syslog loggers
666 Log into a syslog facility and are defined by specifying the facility to log to
667 as the name of a subsection in the
668 .B charon.syslog
669 section. The following facilities are currently supported:
670 .BR daemon " and " auth .
671 .PP
672 Multiple loggers can be defined for each type with different log verbosity for
673 the different subsystems of the daemon.
674 .SS Options
675 .TP
676 .BR charon.filelog.<filename>.default " [1]"
677 .TQ
678 .BR charon.syslog.<facility>.default
679 Specifies the default loglevel to be used for subsystems for which no specific
680 loglevel is defined.
681 .TP
682 .BR charon.filelog.<filename>.<subsystem> " [<default>]"
683 .TQ
684 .BR charon.syslog.<facility>.<subsystem>
685 Specifies the loglevel for the given subsystem.
686 .TP
687 .BR charon.filelog.<filename>.append " [yes]"
688 If this option is enabled log entries are appended to the existing file.
689 .TP
690 .BR charon.filelog.<filename>.flush_line " [no]"
691 Enabling this option disables block buffering and enables line buffering.
692 .TP
693 .BR charon.filelog.<filename>.ike_name " [no]"
694 .TQ
695 .BR charon.syslog.<facility>.ike_name
696 Prefix each log entry with the connection name and a unique numerical
697 identifier for each IKE_SA.
698 .TP
699 .BR charon.filelog.<filename>.time_format
700 Prefix each log entry with a timestamp. The option accepts a format string as
701 passed to
702 .BR strftime (3).
703
704 .SS Subsystems
705 .TP
706 .B dmn
707 Main daemon setup/cleanup/signal handling
708 .TP
709 .B mgr
710 IKE_SA manager, handling synchronization for IKE_SA access
711 .TP
712 .B ike
713 IKE_SA
714 .TP
715 .B chd
716 CHILD_SA
717 .TP
718 .B job
719 Jobs queueing/processing and thread pool management
720 .TP
721 .B cfg
722 Configuration management and plugins
723 .TP
724 .B knl
725 IPsec/Networking kernel interface
726 .TP
727 .B net
728 IKE network communication
729 .TP
730 .B enc
731 Packet encoding/decoding encryption/decryption operations
732 .TP
733 .B tls
734 libtls library messages
735 .TP
736 .B lib
737 libstrongwan library messages
738 .SS Loglevels
739 .TP
740 .B -1
741 Absolutely silent
742 .TP
743 .B 0
744 Very basic auditing logs, (e.g. SA up/SA down)
745 .TP
746 .B 1
747 Generic control flow with errors, a good default to see whats going on
748 .TP
749 .B 2
750 More detailed debugging control flow
751 .TP
752 .B 3
753 Including RAW data dumps in Hex
754 .TP
755 .B 4
756 Also include sensitive material in dumps, e.g. keys
757 .SS Example
758 .PP
759 .EX
760         charon {
761                 filelog {
762                         /var/log/charon.log {
763                                 time_format = %b %e %T
764                                 append = no
765                                 default = 1
766                         }
767                         stderr {
768                                 ike = 2
769                                 knl = 3
770                                 ike_name = yes
771                         }
772                 }
773                 syslog {
774                         # enable logging to LOG_DAEMON, use defaults
775                         daemon {
776                         }
777                         # minimalistic IKE auditing logging to LOG_AUTHPRIV
778                         auth {
779                                 default = -1
780                                 ike = 0
781                         }
782                 }
783         }
784 .EE
785
786 .SH LOAD TESTS
787 To do stability testing and performance optimizations, the IKEv2 daemon charon
788 provides the load-tester plugin. This plugin allows to setup thousands of
789 tunnels concurrently against the daemon itself or a remote host.
790 .PP
791 .B WARNING:
792 Never enable the load-testing plugin on productive systems. It provides
793 preconfigured credentials and allows an attacker to authenticate as any user.
794 .SS Options
795 .TP
796 .BR charon.plugins.load-tester.child_rekey " [600]"
797 Seconds to start CHILD_SA rekeying after setup
798 .TP
799 .BR charon.plugins.load-tester.delay " [0]"
800 Delay between initiatons for each thread
801 .TP
802 .BR charon.plugins.load-tester.delete_after_established " [no]"
803 Delete an IKE_SA as soon as it has been established
804 .TP
805 .BR charon.plugins.load-tester.dynamic_port " [0]"
806 Base port to be used for requests (each client uses a different port)
807 .TP
808 .BR charon.plugins.load-tester.enable " [no]"
809 Enable the load testing plugin
810 .TP
811 .BR charon.plugins.load-tester.fake_kernel " [no]"
812 Fake the kernel interface to allow load-testing against self
813 .TP
814 .BR charon.plugins.load-tester.ike_rekey " [0]"
815 Seconds to start IKE_SA rekeying after setup
816 .TP
817 .BR charon.plugins.load-tester.initiators " [0]"
818 Number of concurrent initiator threads to use in load test
819 .TP
820 .BR charon.plugins.load-tester.initiator_auth " [pubkey]"
821 Authentication method(s) the intiator uses
822 .TP
823 .BR charon.plugins.load-tester.iterations " [1]"
824 Number of IKE_SAs to initate by each initiator in load test
825 .TP
826 .BR charon.plugins.load-tester.pool
827 Provide INTERNAL_IPV4_ADDRs from a named pool
828 .TP
829 .BR charon.plugins.load-tester.proposal " [aes128-sha1-modp768]"
830 IKE proposal to use in load test
831 .TP
832 .BR charon.plugins.load-tester.remote " [127.0.0.1]"
833 Address to initiation connections to
834 .TP
835 .BR charon.plugins.load-tester.responder_auth " [pubkey]"
836 Authentication method(s) the responder uses
837 .TP
838 .BR charon.plugins.load-tester.request_virtual_ip " [no]"
839 Request an INTERNAL_IPV4_ADDR from the server
840 .TP
841 .BR charon.plugins.load-tester.shutdown_when_complete " [no]"
842 Shutdown the daemon after all IKE_SAs have been established
843 .SS Configuration details
844 For public key authentication, the responder uses the
845 .B \(dqCN=srv, OU=load-test, O=strongSwan\(dq
846 identity. For the initiator, each connection attempt uses a different identity
847 in the form
848 .BR "\(dqCN=c1-r1, OU=load-test, O=strongSwan\(dq" ,
849 where the first number inidicates the client number, the second the
850 authentication round (if multiple authentication is used).
851 .PP
852 For PSK authentication, FQDN identities are used. The server uses
853 .BR srv.strongswan.org ,
854 the client uses an identity in the form
855 .BR c1-r1.strongswan.org .
856 .PP
857 For EAP authentication, the client uses a NAI in the form
858 .BR 100000000010001@strongswan.org .
859 .PP
860 To configure multiple authentication, concatenate multiple methods using, e.g.
861 .EX
862         initiator_auth = pubkey|psk|eap-md5|eap-aka
863 .EE
864 .PP
865 The responder uses a hardcoded certificate based on a 1024-bit RSA key.
866 This certificate additionally serves as CA certificate. A peer uses the same
867 private key, but generates client certificates on demand signed by the CA
868 certificate. Install the Responder/CA certificate on the remote host to
869 authenticate all clients.
870 .PP
871 To speed up testing, the load tester plugin implements a special Diffie-Hellman
872 implementation called modpnull. By setting
873 .EX
874         proposal = aes128-sha1-modpnull
875 .EE
876 this wicked fast DH implementation is used. It does not provide any security
877 at all, but allows to run tests without DH calculation overhead.
878 .SS Examples
879 .PP
880 In the simplest case, the daemon initiates IKE_SAs against itself using the
881 loopback interface. This will actually establish double the number of IKE_SAs,
882 as the daemon is initiator and responder for each IKE_SA at the same time.
883 Installation of IPsec SAs would fails, as each SA gets installed twice. To
884 simulate the correct behavior, a fake kernel interface can be enabled which does
885 not install the IPsec SAs at the kernel level.
886 .PP
887 A simple loopback configuration might look like this:
888 .PP
889 .EX
890         charon {
891                 # create new IKE_SAs for each CHILD_SA to simulate
892                 # different clients
893                 reuse_ikesa = no
894                 # turn off denial of service protection
895                 dos_protection = no
896
897                 plugins {
898                         load-tester {
899                                 # enable the plugin
900                                 enable = yes
901                                 # use 4 threads to initiate connections
902                                 # simultaneously
903                                 initiators = 4
904                                 # each thread initiates 1000 connections
905                                 iterations = 1000
906                                 # delay each initiation in each thread by 20ms
907                                 delay = 20
908                                 # enable the fake kernel interface to
909                                 # avoid SA conflicts
910                                 fake_kernel = yes
911                         }
912                 }
913         }
914 .EE
915 .PP
916 This will initiate 4000 IKE_SAs within 20 seconds. You may increase the delay
917 value if your box can not handle that much load, or decrease it to put more
918 load on it. If the daemon starts retransmitting messages your box probably can
919 not handle all connection attempts.
920 .PP
921 The plugin also allows to test against a remote host. This might help to test
922 against a real world configuration. A connection setup to do stress testing of
923 a gateway might look like this:
924 .PP
925 .EX
926         charon {
927                 reuse_ikesa = no
928                 threads = 32
929
930                 plugins {
931                         load-tester {
932                                 enable = yes
933                                 # 10000 connections, ten in parallel
934                                 initiators = 10
935                                 iterations = 1000
936                                 # use a delay of 100ms, overall time is:
937                                 # iterations * delay = 100s
938                                 delay = 100
939                                 # address of the gateway
940                                 remote = 1.2.3.4
941                                 # IKE-proposal to use
942                                 proposal = aes128-sha1-modp1024
943                                 # use faster PSK authentication instead
944                                 # of 1024bit RSA
945                                 initiator_auth = psk
946                                 responder_auth = psk
947                                 # request a virtual IP using configuration
948                                 # payloads
949                                 request_virtual_ip = yes
950                                 # enable CHILD_SA every 60s
951                                 child_rekey = 60
952                         }
953                 }
954         }
955 .EE
956
957 .SH IKEv2 RETRANSMISSION
958 Retransmission timeouts in the IKEv2 daemon charon can be configured globally
959 using the three keys listed below:
960 .PP
961 .RS
962 .nf
963 .BR charon.retransmit_base " [1.8]"
964 .BR charon.retransmit_timeout " [4.0]"
965 .BR charon.retransmit_tries " [5]"
966 .fi
967 .RE
968 .PP
969 The following algorithm is used to calculate the timeout:
970 .PP
971 .EX
972         relative timeout = retransmit_timeout * retransmit_base ^ (n-1)
973 .EE
974 .PP
975 Where
976 .I n
977 is the current retransmission count.
978 .PP
979 Using the default values, packets are retransmitted in:
980
981 .TS
982 l r r
983 ---
984 lB r r.
985 Retransmission  Relative Timeout        Absolute Timeout
986 1       4s      4s
987 2       7s      11s
988 3       13s     24s
989 4       23s     47s
990 5       42s     89s
991 giving up       76s     165s
992 .TE
993
994 .SH FILES
995 /etc/strongswan.conf
996
997 .SH SEE ALSO
998 ipsec.conf(5), ipsec.secrets(5), ipsec(8)
999 .SH HISTORY
1000 Written for the
1001 .UR http://www.strongswan.org
1002 strongSwan project
1003 .UE
1004 by Tobias Brunner, Andreas Steffen and Martin Willi.