libtls: Move settings to <ns>.tls with fallback to libtls
[strongswan.git] / man / strongswan.conf.5.in
1 .TH STRONGSWAN.CONF 5 "2013-10-29" "@PACKAGE_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 attest section
130 .TP
131 .BR attest.database
132 Path to database with file measurement information
133 .TP
134 .BR attest.load
135 Plugins to load in ipsec attest tool
136
137 .SS charon section
138 .TP
139 .BR Note :
140 Many of these options also apply to \fBcharon\-cmd\fR and other
141 \fBcharon\fR derivatives. Just use their respective name (e.g.
142 \fIcharon\-cmd\fR) instead of  \fIcharon\fR. For many options defaults
143 can be defined in the \fIlibstrongswan\fR section.
144 .TP
145 .BR charon.block_threshold " [5]"
146 Maximum number of half-open IKE_SAs for a single peer IP
147 .TP
148 .BR charon.cert_cache " [yes]"
149 Whether relations in validated certificate chains should be cached in memory
150 .TP
151 .BR charon.cisco_unity " [no]
152 Send Cisco Unity vendor ID payload (IKEv1 only)
153 .TP
154 .BR charon.close_ike_on_child_failure " [no]"
155 Close the IKE_SA if setup of the CHILD_SA along with IKE_AUTH failed
156 .TP
157 .BR charon.cookie_threshold " [10]"
158 Number of half-open IKE_SAs that activate the cookie mechanism
159 .TP
160 .BR charon.crypto_test.bench " [no]"
161
162 .TP
163 .BR charon.crypto_test.bench_size " [1024]"
164
165 .TP
166 .BR charon.crypto_test.bench_time " [50]"
167
168 .TP
169 .BR charon.crypto_test.on_add " [no]"
170 Test crypto algorithms during registration
171 .TP
172 .BR charon.crypto_test.on_create " [no]"
173 Test crypto algorithms on each crypto primitive instantiation
174 .TP
175 .BR charon.crypto_test.required " [no]"
176 Strictly require at least one test vector to enable an algorithm
177 .TP
178 .BR charon.crypto_test.rng_true " [no]"
179 Whether to test RNG with TRUE quality; requires a lot of entropy
180 .TP
181 .BR charon.dh_exponent_ansi_x9_42 " [yes]"
182 Use ANSI X9.42 DH exponent size or optimum size matched to cryptographical
183 strength
184 .TP
185 .BR charon.dns1
186 .TQ
187 .BR charon.dns2
188 DNS servers assigned to peer via configuration payload (CP)
189 .TP
190 .BR charon.dos_protection " [yes]"
191 Enable Denial of Service protection using cookies and aggressiveness checks
192 .TP
193 .BR charon.ecp_x_coordinate_only " [yes]"
194 Compliance with the errata for RFC 4753
195 .TP
196 .BR charon.filelog
197 Section to define file loggers, see LOGGER CONFIGURATION
198 .TP
199 .BR charon.flush_auth_cfg " [no]"
200 If enabled objects used during authentication (certificates, identities etc.)
201 are released to free memory once an IKE_SA is established.
202 Enabling this might conflict with plugins that later need access to e.g. the
203 used certificates.
204 .TP
205 .BR charon.fragment_size " [512]"
206 Maximum size (in bytes) of a sent fragment when using the proprietary IKEv1
207 fragmentation extension.
208 .TP
209 .BR charon.group
210 Name of the group the daemon changes to after startup
211 .TP
212 .BR charon.half_open_timeout " [30]"
213 Timeout in seconds for connecting IKE_SAs (also see IKE_SA_INIT DROPPING).
214 .TP
215 .BR charon.hash_and_url " [no]"
216 Enable hash and URL support
217 .TP
218 .BR charon.host_resolver.max_threads " [3]"
219 Maximum number of concurrent resolver threads (they are terminated if unused)
220 .TP
221 .BR charon.host_resolver.min_threads " [0]"
222 Minimum number of resolver threads to keep around
223 .TP
224 .BR charon.i_dont_care_about_security_and_use_aggressive_mode_psk " [no]"
225 If enabled responders are allowed to use IKEv1 Aggressive Mode with pre-shared
226 keys, which is discouraged due to security concerns (offline attacks on the
227 openly transmitted hash of the PSK)
228 .TP
229 .BR charon.ignore_routing_tables
230 A space-separated list of routing tables to be excluded from route lookups
231 .TP
232 .BR charon.ikesa_limit " [0]"
233 Maximum number of IKE_SAs that can be established at the same time before new
234 connection attempts are blocked
235 .TP
236 .BR charon.ikesa_table_segments " [1]"
237 Number of exclusively locked segments in the hash table
238 .TP
239 .BR charon.ikesa_table_size " [1]"
240 Size of the IKE_SA hash table
241 .TP
242 .BR charon.inactivity_close_ike " [no]"
243 Whether to close IKE_SA if the only CHILD_SA closed due to inactivity
244 .TP
245 .BR charon.init_limit_half_open " [0]"
246 Limit new connections based on the current number of half open IKE_SAs (see
247 IKE_SA_INIT DROPPING).
248 .TP
249 .BR charon.init_limit_job_load " [0]"
250 Limit new connections based on the number of jobs currently queued for
251 processing (see IKE_SA_INIT DROPPING).
252 .TP
253 .BR charon.initiator_only " [no]"
254 Causes charon daemon to ignore IKE initiation requests.
255 .TP
256 .BR charon.install_routes " [yes]"
257 Install routes into a separate routing table for established IPsec tunnels
258 .TP
259 .BR charon.install_virtual_ip " [yes]"
260 Install virtual IP addresses
261 .TP
262 .BR charon.install_virtual_ip_on
263 The name of the interface on which virtual IP addresses should be installed.
264 If not specified the addresses will be installed on the outbound interface.
265 .TP
266 .BR charon.integrity_test " [no]"
267 Check daemon, libstrongswan and plugin integrity at startup
268 .TP
269 .BR charon.interfaces_ignore
270 A comma-separated list of network interfaces that should be ignored, if
271 .B charon.interfaces_use
272 is specified this option has no effect.
273 .TP
274 .BR charon.interfaces_use
275 A comma-separated list of network interfaces that should be used by charon.
276 All other interfaces are ignored.
277 .TP
278 .BR charon.keep_alive " [20s]"
279 NAT keep alive interval
280 .TP
281 .BR charon.leak_detective.detailed " [yes]"
282 Includes source file names and line numbers in leak detective output
283 .TP
284 .BR charon.leak_detective.usage_threshold " [10240]"
285 Threshold in bytes for leaks to be reported (0 to report all)
286 .TP
287 .BR charon.leak_detective.usage_threshold_count " [0]"
288 Threshold in number of allocations for leaks to be reported (0 to report all)
289 .TP
290 .BR charon.load
291 Plugins to load in the IKEv2 daemon charon
292 .TP
293 .BR charon.max_packet " [10000]"
294 Maximum packet size accepted by charon
295 .TP
296 .BR charon.multiple_authentication " [yes]"
297 Enable multiple authentication exchanges (RFC 4739)
298 .TP
299 .BR charon.nbns1
300 .TQ
301 .BR charon.nbns2
302 WINS servers assigned to peer via configuration payload (CP)
303 .TP
304 .BR charon.port " [500]"
305 UDP port used locally. If set to 0 a random port will be allocated.
306 .TP
307 .BR charon.port_nat_t " [4500]"
308 UDP port used locally in case of NAT-T. If set to 0 a random port will be
309 allocated.  Has to be different from
310 .BR charon.port ,
311 otherwise a random port will be allocated.
312 .TP
313 .BR charon.process_route " [yes]"
314 Process RTM_NEWROUTE and RTM_DELROUTE events
315 .TP
316 .BR charon.processor.priority_threads
317 Subsection to configure the number of reserved threads per priority class
318 see JOB PRIORITY MANAGEMENT
319 .TP
320 .BR charon.receive_delay " [0]"
321 Delay in ms for receiving packets, to simulate larger RTT
322 .TP
323 .BR charon.receive_delay_response " [yes]"
324 Delay response messages
325 .TP
326 .BR charon.receive_delay_request " [yes]"
327 Delay request messages
328 .TP
329 .BR charon.receive_delay_type " [0]"
330 Specific IKEv2 message type to delay, 0 for any
331 .TP
332 .BR charon.replay_window " [32]"
333 Size of the AH/ESP replay window, in packets.
334 .TP
335 .BR charon.retransmit_base " [1.8]"
336 Base to use for calculating exponential back off, see IKEv2 RETRANSMISSION
337 .TP
338 .BR charon.retransmit_timeout " [4.0]
339 Timeout in seconds before sending first retransmit
340 .TP
341 .BR charon.retransmit_tries " [5]"
342 Number of times to retransmit a packet before giving up
343 .TP
344 .BR charon.retry_initiate_interval " [0]"
345 Interval to use when retrying to initiate an IKE_SA (e.g. if DNS resolution
346 failed), 0 to disable retries.
347 .TP
348 .BR charon.reuse_ikesa " [yes]
349 Initiate CHILD_SA within existing IKE_SAs
350 .TP
351 .BR charon.routing_table
352 Numerical routing table to install routes to
353 .TP
354 .BR charon.routing_table_prio
355 Priority of the routing table
356 .TP
357 .BR charon.send_delay " [0]"
358 Delay in ms for sending packets, to simulate larger RTT
359 .TP
360 .BR charon.send_delay_response " [yes]"
361 Delay response messages
362 .TP
363 .BR charon.send_delay_request " [yes]"
364 Delay request messages
365 .TP
366 .BR charon.send_delay_type " [0]"
367 Specific IKEv2 message type to delay, 0 for any
368 .TP
369 .BR charon.send_vendor_id " [no]
370 Send strongSwan vendor ID payload
371 .TP
372 .BR charon.syslog
373 Section to define syslog loggers, see LOGGER CONFIGURATION
374 .TP
375 .BR charon.threads " [16]"
376 Number of worker threads in charon. Several of these are reserved for long
377 running tasks in internal modules and plugins. Therefore, make sure you don't
378 set this value too low. The number of idle worker threads listed in
379 .I ipsec statusall
380 might be used as indicator on the number of reserved threads.
381 .TP
382 .BR charon.tls.cipher
383 List of TLS encryption ciphers
384 .TP
385 .BR charon.tls.key_exchange
386 List of TLS key exchange methods
387 .TP
388 .BR charon.tls.mac
389 List of TLS MAC algorithms
390 .TP
391 .BR charon.tls.suites
392 List of TLS cipher suites
393 .TP
394 .BR charon.user
395 Name of the user the daemon changes to after startup
396 .TP
397 .BR charon.x509.enforce_critical " [yes]"
398 Discard certificates with unsupported or unknown critical extensions
399 .
400 .SS charon.plugins subsection
401 .TP
402 .BR charon.plugins.android_log.loglevel " [1]"
403 Loglevel for logging to Android specific logger
404 .TP
405 .BR charon.plugins.attr
406 Section to specify arbitrary attributes that are assigned to a peer via
407 configuration payload (CP)
408 .TP
409 .BR charon.plugins.attr-sql.database
410 Database URI for attr-sql plugin used by charon
411 .TP
412 .BR charon.plugins.attr-sql.lease_history " [yes]"
413 Enable logging of SQL IP pool leases
414 .TP
415 .BR charon.plugins.certexpire.csv.cron
416 Cron style string specifying CSV export times
417 .TP
418 .BR charon.plugins.certexpire.csv.empty_string
419 String to use in empty intermediate CA fields
420 .TP
421 .BR charon.plugins.certexpire.csv.fixed_fields " [yes]"
422 Use a fixed intermediate CA field count
423 .TP
424 .BR charon.plugins.certexpire.csv.force " [yes]"
425 Force export of all trustchains we have a private key for
426 .TP
427 .BR charon.plugins.certexpire.csv.format " [%d:%m:%Y]"
428 strftime(3) format string to export expiration dates as
429 .TP
430 .BR charon.plugins.certexpire.csv.local
431 strftime(3) format string for the CSV file name to export local certificates to
432 .TP
433 .BR charon.plugins.certexpire.csv.remote
434 strftime(3) format string for the CSV file name to export remote certificates to
435 .TP
436 .BR charon.plugins.certexpire.csv.separator " [,]"
437 CSV field separator
438 .TP
439 .BR charon.plugins.coupling.file
440 File to store coupling list to
441 .TP
442 .BR charon.plugins.coupling.hash " [sha1]"
443 Hashing algorithm to fingerprint coupled certificates
444 .TP
445 .BR charon.plugins.coupling.max " [1]"
446 Maximum number of coupling entries to create
447 .TP
448 .BR charon.plugins.dhcp.force_server_address " [no]"
449 Always use the configured server address. This might be helpful if the DHCP
450 server runs on the same host as strongSwan, and the DHCP daemon does not listen
451 on the loopback interface.  In that case the server cannot be reached via
452 unicast (or even 255.255.255.255) as that would be routed via loopback.
453 Setting this option to yes and configuring the local broadcast address (e.g.
454 192.168.0.255) as server address might work.
455 .TP
456 .BR charon.plugins.dhcp.identity_lease " [no]"
457 Derive user-defined MAC address from hash of IKEv2 identity
458 .TP
459 .BR charon.plugins.dhcp.server " [255.255.255.255]"
460 DHCP server unicast or broadcast IP address
461 .TP
462 .BR charon.plugins.dhcp.interface " []"
463 Interface name the plugin uses for address allocation. The default is to bind
464 to any (0.0.0.0) and let the system decide which way to route the packets to
465 the DHCP server.
466 .TP
467 .BR charon.plugins.dnscert.enable " [no]"
468 Enable fetching of CERT RRs via DNS
469 .TP
470 .BR charon.plugins.duplicheck.enable " [yes]"
471 Enable duplicheck plugin (if loaded)
472 .TP
473 .BR charon.plugins.duplicheck.socket " [unix://@piddir@/charon.dck]"
474 Socket provided by the duplicheck plugin
475 .TP
476 .BR charon.plugins.eap-aka.request_identity " [yes]"
477
478 .TP
479 .BR charon.plugins.eap-aka-3ggp2.seq_check
480
481 .TP
482 .BR charon.plugins.eap-dynamic.preferred
483 The preferred EAP method(s) to be used.  If it is not given the first
484 registered method will be used initially.  If a comma separated list is given
485 the methods are tried in the given order before trying the rest of the
486 registered methods.
487 .TP
488 .BR charon.plugins.eap-dynamic.prefer_user " [no]"
489 If enabled the EAP methods proposed in an EAP-Nak message sent by the peer are
490 preferred over the methods registered locally.
491 .TP
492 .BR charon.plugins.eap-gtc.backend " [pam]"
493 XAuth backend to be used for credential verification
494 .TP
495 .BR charon.plugins.eap-peap.fragment_size " [1024]"
496 Maximum size of an EAP-PEAP packet
497 .TP
498 .BR charon.plugins.eap-peap.max_message_count " [32]"
499 Maximum number of processed EAP-PEAP packets (0 = no limit)
500 .TP
501 .BR charon.plugins.eap-peap.include_length " [no]"
502 Include length in non-fragmented EAP-PEAP packets
503 .TP
504 .BR charon.plugins.eap-peap.phase2_method " [mschapv2]"
505 Phase2 EAP client authentication method
506 .TP
507 .BR charon.plugins.eap-peap.phase2_piggyback " [no]"
508 Phase2 EAP Identity request piggybacked by server onto TLS Finished message
509 .TP
510 .BR charon.plugins.eap-peap.phase2_tnc " [no]"
511 Start phase2 EAP TNC protocol after successful client authentication
512 .TP
513 .BR charon.plugins.eap-peap.request_peer_auth " [no]"
514 Request peer authentication based on a client certificate
515 .TP
516 .BR charon.plugins.eap-radius.accounting " [no]"
517 Send RADIUS accounting information to RADIUS servers.
518 .TP
519 .BR charon.plugins.eap-radius.accounting_requires_vip " [no]"
520 If enabled, accounting is disabled unless an IKE_SA has at least one virtual IP
521 .TP
522 .BR charon.plugins.eap-radius.class_group " [no]"
523 Use the
524 .I class
525 attribute sent in the RADIUS-Accept message as group membership information that
526 is compared to the groups specified in the
527 .B rightgroups
528 option in
529 .B ipsec.conf (5).
530 .TP
531 .BR charon.plugins.eap-radius.close_all_on_timeout " [no]"
532 Closes all IKE_SAs if communication with the RADIUS server times out. If it is
533 not set only the current IKE_SA is closed.
534 .TP
535 .BR charon.plugins.eap-radius.dae.enable " [no]"
536 Enables support for the Dynamic Authorization Extension (RFC 5176)
537 .TP
538 .BR charon.plugins.eap-radius.dae.listen " [0.0.0.0]"
539 Address to listen for DAE messages from the RADIUS server
540 .TP
541 .BR charon.plugins.eap-radius.dae.port " [3799]"
542 Port to listen for DAE requests
543 .TP
544 .BR charon.plugins.eap-radius.dae.secret
545 Shared secret used to verify/sign DAE messages
546 .TP
547 .BR charon.plugins.eap-radius.eap_start " [no]"
548 Send EAP-Start instead of EAP-Identity to start RADIUS conversation
549 .TP
550 .BR charon.plugins.eap-radius.filter_id " [no]"
551 If the RADIUS
552 .I tunnel_type
553 attribute with value
554 .B ESP
555 is received, use the
556 .I filter_id
557 attribute sent in the RADIUS-Accept message as group membership information that
558 is compared to the groups specified in the
559 .B rightgroups
560 option in
561 .B ipsec.conf (5).
562 .TP
563 .BR charon.plugins.eap-radius.forward.ike_to_radius
564 RADIUS attributes to be forwarded from IKEv2 to RADIUS (can be defined by
565 name or attribute number, a colon can be used to specify vendor-specific
566 attributes, e.g. Reply-Message, or 11, or 36906:12).
567 .TP
568 .BR charon.plugins.eap-radius.forward.radius_to_ike
569 Same as
570 .B charon.plugins.eap-radius.forward.ike_to_radius
571 but from RADIUS to
572 IKEv2, a strongSwan specific private notify (40969) is used to transmit the
573 attributes.
574 .TP
575 .BR charon.plugins.eap-radius.id_prefix
576 Prefix to EAP-Identity, some AAA servers use a IMSI prefix to select the
577 EAP method
578 .TP
579 .BR charon.plugins.eap-radius.nas_identifier " [strongSwan]"
580 NAS-Identifier to include in RADIUS messages
581 .TP
582 .BR charon.plugins.eap-radius.port " [1812]"
583 Port of RADIUS server (authentication)
584 .TP
585 .BR charon.plugins.eap-radius.secret
586 Shared secret between RADIUS and NAS
587 .TP
588 .BR charon.plugins.eap-radius.server
589 IP/Hostname of RADIUS server
590 .TP
591 .BR charon.plugins.eap-radius.servers
592 Section to specify multiple RADIUS servers. The
593 .BR nas_identifier ,
594 .BR secret ,
595 .B sockets
596 and
597 .B port
598 (or
599 .BR auth_port )
600 options can be specified for each server. A server's IP/Hostname can be
601 configured using the
602 .B address
603 option. The
604 .BR acct_port " [1813]"
605 option can be used to specify the port used for RADIUS accounting.
606 For each RADIUS server a priority can be specified using the
607 .BR preference " [0]"
608 option.
609 .TP
610 .BR charon.plugins.eap-radius.sockets " [1]"
611 Number of sockets (ports) to use, increase for high load
612 .TP
613 .BR charon.plugins.eap-radius.xauth
614 Section to configure multiple XAuth authentication rounds via RADIUS. The subsections define so called
615 authentication profiles with arbitrary names. In each profile section one or more XAuth types can be
616 configured, with an assigned message. For each type a separate XAuth exchange will be initiated and all
617 replies get concatenated into the User-Password attribute, which then gets verified over RADIUS.
618
619 Available XAuth types are \fBpassword\fR, \fBpasscode\fR, \fBnextpin\fR, and \fBanswer\fR. This type is
620 not relevant to strongSwan or the AAA server, but the client may show a different dialog (along with the
621 configured message).
622
623 To use the configured profiles, they have to be configured in the respective connection in
624 .IR ipsec.conf (5)
625 by appending the profile name, separated by a colon, to the
626 .B xauth-radius
627 XAauth backend configuration in
628 .I rightauth
629 or
630 .IR rightauth2 ,
631 for instance,
632 .IR rightauth2=xauth-radius:profile .
633 .TP
634 .BR charon.plugins.eap-sim.request_identity " [yes]"
635
636 .TP
637 .BR charon.plugins.eap-simaka-sql.database
638
639 .TP
640 .BR charon.plugins.eap-simaka-sql.remove_used " [no]"
641
642 .TP
643 .BR charon.plugins.eap-tls.fragment_size " [1024]"
644 Maximum size of an EAP-TLS packet
645 .TP
646 .BR charon.plugins.eap-tls.max_message_count " [32]"
647 Maximum number of processed EAP-TLS packets (0 = no limit)
648 .TP
649 .BR charon.plugins.eap-tls.include_length " [yes]"
650 Include length in non-fragmented EAP-TLS packets
651 .TP
652 .BR charon.plugins.eap-tnc.max_message_count " [10]"
653 Maximum number of processed EAP-TNC packets (0 = no limit)
654 .TP
655 .BR charon.plugins.eap-tnc.protocol " [tnccs-1.1]"
656 IF-TNCCS protocol version to be used (tnccs-1.1, tnccs-2.0, tnccs-dynamic)
657 .TP
658 .BR charon.plugins.eap-ttls.fragment_size " [1024]"
659 Maximum size of an EAP-TTLS packet
660 .TP
661 .BR charon.plugins.eap-ttls.max_message_count " [32]"
662 Maximum number of processed EAP-TTLS packets (0 = no limit)
663 .TP
664 .BR charon.plugins.eap-ttls.include_length " [yes]"
665 Include length in non-fragmented EAP-TTLS packets
666 .TP
667 .BR charon.plugins.eap-ttls.phase2_method " [md5]"
668 Phase2 EAP client authentication method
669 .TP
670 .BR charon.plugins.eap-ttls.phase2_piggyback " [no]"
671 Phase2 EAP Identity request piggybacked by server onto TLS Finished message
672 .TP
673 .BR charon.plugins.eap-ttls.phase2_tnc " [no]"
674 Start phase2 EAP TNC protocol after successful client authentication
675 .TP
676 .BR charon.plugins.eap-ttls.request_peer_auth " [no]"
677 Request peer authentication based on a client certificate
678 .TP
679 .BR charon.plugins.error-notify.socket " [unix://@piddir@/charon.enfy]"
680 Socket provided by the error-notify plugin
681 .TP
682 .BR charon.plugins.gcrypt.quick_random " [no]"
683 Use faster random numbers in gcrypt; for testing only, produces weak keys!
684 .TP
685 .BR charon.plugins.ha.autobalance " [0]"
686 Interval in seconds to automatically balance handled segments between nodes.
687 Set to 0 to disable.
688 .TP
689 .BR charon.plugins.ha.fifo_interface " [yes]"
690
691 .TP
692 .BR charon.plugins.ha.heartbeat_delay " [1000]"
693
694 .TP
695 .BR charon.plugins.ha.heartbeat_timeout " [2100]"
696
697 .TP
698 .BR charon.plugins.ha.local
699
700 .TP
701 .BR charon.plugins.ha.monitor " [yes]"
702
703 .TP
704 .BR charon.plugins.ha.pools
705
706 .TP
707 .BR charon.plugins.ha.remote
708
709 .TP
710 .BR charon.plugins.ha.resync " [yes]"
711
712 .TP
713 .BR charon.plugins.ha.secret
714
715 .TP
716 .BR charon.plugins.ha.segment_count " [1]"
717
718 .TP
719 .BR charon.plugins.ipseckey.enable " [no]"
720 Enable fetching of IPSECKEY RRs via DNS
721 .TP
722 .BR charon.plugins.led.activity_led
723
724 .TP
725 .BR charon.plugins.led.blink_time " [50]"
726
727 .TP
728 .BR charon.plugins.kernel-klips.ipsec_dev_count " [4]"
729 Number of ipsecN devices
730 .TP
731 .BR charon.plugins.kernel-klips.ipsec_dev_mtu " [0]"
732 Set MTU of ipsecN device
733 .TP
734 .BR charon.plugins.kernel-libipsec.allow_peer_ts " [no]"
735 Allow that the remote traffic selector equals the IKE peer. The route installed
736 for such traffic (via TUN device) usually prevents further IKE traffic. The
737 fwmark options for the \fIkernel-netlink\fR and \fIsocket-default\fR plugins can
738 be used to circumvent that problem.
739 .TP
740 .BR charon.plugins.kernel-netlink.fwmark
741 Firewall mark to set on the routing rule that directs traffic to our own routing
742 table. The format is [!]mark[/mask], where the optional exclamation mark inverts
743 the meaning (i.e. the rule only applies to packets that don't match the mark).
744 .TP
745 .BR charon.plugins.kernel-netlink.roam_events " [yes]"
746 Whether to trigger roam events when interfaces, addresses or routes change
747 .TP
748 .BR charon.plugins.kernel-netlink.xfrm_acq_expires " [165]"
749 Lifetime of XFRM acquire state in kernel. The value gets written to
750 /proc/sys/net/core/xfrm_acq_expires. Indirectly controls the delay of XFRM
751 acquire messages sent.
752 .TP
753 .BR charon.plugins.kernel-pfroute.vip_wait " [1000]"
754 Time in ms to wait until virtual IP addresses appear/disappear before failing.
755 .TP
756 .BR charon.plugins.load-tester
757 Section to configure the load-tester plugin, see LOAD TESTS
758 .TP
759 .BR charon.plugins.lookip.socket " [unix://@piddir@/charon.lkp]"
760 Socket provided by the lookip plugin
761 .TP
762 .BR charon.plugins.ntru.max_drbg_requests " [4294967294]"
763 Number of pseudo-random bit requests from the DRBG before an automatic
764 reseeding occurs.
765 .TP
766 .BR charon.plugins.ntru.parameter_set " [optimum]"
767 The following parameter sets are available:
768 .BR x9_98_speed ,
769 .BR x9_98_bandwidth ,
770 .B x9_98_balance
771 and
772 .BR optimum ,
773 the last set not being part of the X9.98 standard but having the best performance.
774 .TP
775 .BR charon.plugins.openssl.engine_id " [pkcs11]"
776 ENGINE ID to use in the OpenSSL plugin
777 .TP
778 .BR charon.plugins.openssl.fips_mode " [0]"
779 Set OpenSSL FIPS mode: disabled(0), enabled(1), Suite B enabled(2)
780 .TP
781 .BR charon.plugins.pkcs11.modules
782 List of available PKCS#11 modules
783 .TP
784 .BR charon.plugins.pkcs11.load_certs " [yes]"
785 Whether to load certificates from tokens
786 .TP
787 .BR charon.plugins.pkcs11.reload_certs " [no]"
788 Reload certificates from all tokens if charon receives a SIGHUP
789 .TP
790 .BR charon.plugins.pkcs11.use_dh " [no]"
791 Whether the PKCS#11 modules should be used for DH and ECDH (see use_ecc option)
792 .TP
793 .BR charon.plugins.pkcs11.use_ecc " [no]"
794 Whether the PKCS#11 modules should be used for ECDH and ECDSA public key
795 operations. ECDSA private keys can be used regardless of this option
796 .TP
797 .BR charon.plugins.pkcs11.use_hasher " [no]"
798 Whether the PKCS#11 modules should be used to hash data
799 .TP
800 .BR charon.plugins.pkcs11.use_pubkey " [no]"
801 Whether the PKCS#11 modules should be used for public key operations, even for
802 keys not stored on tokens
803 .TP
804 .BR charon.plugins.pkcs11.use_rng " [no]"
805 Whether the PKCS#11 modules should be used as RNG
806 .TP
807 .BR charon.plugins.radattr.dir
808 Directory where RADIUS attributes are stored in client-ID specific files.
809 .TP
810 .BR charon.plugins.radattr.message_id " [-1]"
811 Attributes are added to all IKE_AUTH messages by default (-1), or only to the
812 IKE_AUTH message with the given IKEv2 message ID.
813 .TP
814 .BR charon.plugins.random.random " [@random_device@]"
815 File to read random bytes from, instead of @random_device@
816 .TP
817 .BR charon.plugins.random.urandom " [@urandom_device@]"
818 File to read pseudo random bytes from, instead of @urandom_device@
819 .TP
820 .BR charon.plugins.random.strong_equals_true " [no]"
821 If set to yes the RNG_STRONG class reads random bytes from the same source as
822 the RNG_TRUE class.
823 .TP
824 .BR charon.plugins.resolve.file " [/etc/resolv.conf]"
825 File where to add DNS server entries
826 .TP
827 .BR charon.plugins.resolve.resolvconf.iface_prefix " [lo.inet.ipsec.]"
828 Prefix used for interface names sent to resolvconf(8). The nameserver address
829 is appended to this prefix to make it unique.  The result has to be a valid
830 interface name according to the rules defined by resolvconf.  Also, it should
831 have a high priority according to the order defined in interface-order(5).
832 .TP
833 .BR charon.plugins.socket-default.fwmark
834 Firewall mark to set on outbound packets.
835 .TP
836 .BR charon.plugins.socket-default.set_source " [yes]"
837 Set source address on outbound packets, if possible.
838 .TP
839 .BR charon.plugins.socket-default.use_ipv4 " [yes]"
840 Listen on IPv4, if possible.
841 .TP
842 .BR charon.plugins.socket-default.use_ipv6 " [yes]"
843 Listen on IPv6, if possible.
844 .TP
845 .BR charon.plugins.sql.database
846 Database URI for charons SQL plugin
847 .TP
848 .BR charon.plugins.sql.loglevel " [-1]"
849 Loglevel for logging to SQL database
850 .TP
851 .BR charon.plugins.stroke.ignore_missing_ca_basic_constraint " [no]"
852 Treat certificates in ipsec.d/cacerts and ipsec.conf ca sections as CA
853 certificates even if they don't contain a CA basic constraint.
854 .TP
855 .BR charon.plugins.stroke.max_concurrent " [4]"
856 Maximum number of stroke messages handled concurrently
857 .TP
858 .BR charon.plugins.stroke.prevent_loglevel_changes " [no]"
859 If enabled log level changes via stroke socket are not allowed.
860 .TP
861 .BR charon.plugins.stroke.socket " [unix://@piddir@/charon.ctl]"
862 Socket provided by the stroke plugin
863 .TP
864 .BR charon.plugins.stroke.timeout " [0]"
865 Timeout in ms for any stroke command. Use 0 to disable the timeout
866 .TP
867 .BR charon.plugins.systime-fix.interval " [0]"
868 Interval in seconds to check system time for validity. 0 disables the check
869 .TP
870 .BR charon.plugins.systime-fix.reauth " [no]"
871 Whether to use reauth or delete if an invalid cert lifetime is detected
872 .TP
873 .BR charon.plugins.systime-fix.threshold
874 Threshold date where system time is considered valid. Disabled if not specified
875 .TP
876 .BR charon.plugins.systime-fix.threshold_format " [%Y]"
877 strptime(3) format used to parse threshold option
878 .TP
879 .BR charon.plugins.tnc-ifmap.client_cert
880 Path to X.509 certificate file of IF-MAP client
881 .TP
882 .BR charon.plugins.tnc-ifmap.client_key
883 Path to private key file of IF-MAP client
884 .TP
885 .BR charon.plugins.tnc-ifmap.device_name
886 Unique name of strongSwan server as a PEP and/or PDP device
887 .TP
888 .BR charon.plugins.tnc-ifmap.renew_session_interval " [150]"
889 Interval in seconds between periodic IF-MAP RenewSession requests
890 .TP
891 .BR charon.plugins.tnc-ifmap.server_uri " [https://localhost:8444/imap]"
892 URI of the form [https://]servername[:port][/path]
893 .TP
894 .BR charon.plugins.tnc-ifmap.server_cert
895 Path to X.509 certificate file of IF-MAP server
896 .TP
897 .BR charon.plugins.tnc-ifmap.username_password
898 Credentials of IF-MAP client of the form username:password
899 .TP
900 .BR charon.plugins.tnc-pdp.pt_tls.enable " [yes]"
901 Enable PT-TLS protocol on the strongSwan PDP
902 .TP
903 .BR charon.plugins.tnc-pdp.pt_tls.port " [271]"
904 PT-TLS server port the strongSwan PDP is listening on
905 .TP
906 .BR charon.plugins.tnc-pdp.radius.enable " [yes]"
907 Enable RADIUS protocol on the strongSwan PDP
908 .TP
909 .BR charon.plugins.tnc-pdp.radius.method " [ttls]"
910 EAP tunnel method to be used
911 .TP
912 .BR charon.plugins.tnc-pdp.radius.port " [1812]"
913 RADIUS server port the strongSwan PDP is listening on
914 .TP
915 .BR charon.plugins.tnc-pdp.radius.secret
916 Shared RADIUS secret between strongSwan PDP and NAS
917 .TP
918 .BR charon.plugins.tnc-pdp.server
919 Name of the strongSwan PDP as contained in the AAA certificate
920 .TP
921 .BR charon.plugins.tnc-pdp.timeout
922 Timeout in seconds before closing incomplete connections
923 .TP
924 .BR charon.plugins.unbound.resolv_conf " [/etc/resolv.conf]"
925 File to read DNS resolver configuration from
926 .TP
927 .BR charon.plugins.unbound.trust_anchors " [/etc/ipsec.d/dnssec.keys]"
928 File to read DNSSEC trust anchors from (usually root zone KSK). The format of
929 the file is the standard DNS Zone file format, anchors can be stored as DS or
930 DNSKEY entries in the file.
931 .TP
932 .BR charon.plugins.unbound.dlv_anchors
933 File to read trusted keys for DLV (DNSSEC Lookaside Validation) from. It uses
934 the same format as \fItrust_anchors\fR. Only one DLV can be configured, which
935 is then used as a root trusted DLV, this means that it is a lookaside for
936 the root.
937 .TP
938 .BR charon.plugins.updown.dns_handler " [no]"
939 Whether the updown script should handle DNS serves assigned via IKEv1 Mode
940 Config or IKEv2 Config Payloads (if enabled they can't be handled by other
941 plugins, like resolve)
942 .TP
943 .BR charon.plugins.whitelist.enable " [yes]"
944 Enable loaded whitelist plugin
945 .TP
946 .BR charon.plugins.whitelist.socket " [unix://@piddir@/charon.wlst]"
947 Socket provided by the whitelist plugin
948 .TP
949 .BR charon.plugins.xauth-eap.backend " [radius]"
950 EAP plugin to be used as backend for XAuth credential verification
951 .TP
952 .BR charon.plugins.xauth-pam.pam_service " [login]"
953 PAM service to be used for authentication
954 .TP
955 .BR charon.plugins.xauth-pam.session " [no]"
956 Open/close a PAM session for each active IKE_SA
957 .TP
958 .BR charon.plugins.xauth-pam.trim_email " [yes]"
959 If an email address is given as an XAuth username, trim it to just the
960 username part.
961 .SS libtnccs section
962 .TP
963 .BR libtnccs.tnc_config " [/etc/tnc_config]"
964 TNC IMC/IMV configuration directory
965 .PP
966 .SS libtnccs plugins section
967 .TP
968 .BR libtnccs.plugins.tnccs-11.max_message_size " [45000]"
969 Maximum size of a PA-TNC message (XML & Base64 encoding)
970 .TP
971 .BR libtnccs.plugins.tnccs-20.max_batch_size " [65522]"
972 Maximum size of a PB-TNC batch (upper limit via PT-EAP = 65529)
973 .TP
974 .BR libtnccs.plugins.tnccs-20.max_message_size " [65490]"
975 Maximum size of a PA-TNC message (upper limit via PT-EAP = 65497)
976 .TP
977 .BR libtnccs.plugins.tnc-imc.dlclose " [yes]"
978 Unload IMC after use
979 .TP
980 .BR libtnccs.plugins.tnc-imc.preferred_language " [en]"
981 Preferred language for TNC recommendations
982 .TP
983 .BR libtnccs.plugins.tnc-imv.dlclose " [yes]"
984 Unload IMV after use
985 .SS libimcv section
986 .TP
987 .BR libimcv.assessment_result " [yes]"
988 Whether IMVs send a standard IETF Assessment Result attribute
989 .TP
990 .BR libimcv.database
991 Global IMV policy database URI
992 .TP
993 .BR libimcv.debug_level " [1]"
994 Debug level for a stand-alone libimcv library
995 .TP
996 .BR libimcv.load " [random nonce gmp pubkey x509]"
997 Plugins to load in IMC/IMVs
998 .TP
999 .BR libimcv.os_info.name
1000 Manually set the name of the client OS (e.g. Ubuntu)
1001 .TP
1002 .BR libimcv.os_info.version
1003 Manually set the version of the client OS (e.g. 12.04 i686)
1004 .TP
1005 .BR libimcv.policy_script " [ipsec _imv_policy]"
1006 Script called for each TNC connection to generate IMV policies
1007 .TP
1008 .BR libimcv.stderr_quiet " [no]"
1009 isable output to stderr with a stand-alone libimcv library
1010 .PP
1011 .SS libimcv plugins section
1012 .TP
1013 .BR libimcv.plugins.imc-attestation.aik_blob
1014 AIK encrypted private key blob file
1015 .TP
1016 .BR libimcv.plugins.imc-attestation.aik_cert
1017 AIK certificate file
1018 .TP
1019 .BR libimcv.plugins.imc-attestation.aik_key
1020 AIK public key file
1021 .TP
1022 .BR libimcv.plugins.imv-attestation.nonce_len " [20]"
1023 DH nonce length
1024 .TP
1025 .BR libimcv.plugins.imv-attestation.use_quote2 " [yes]"
1026 Use Quote2 AIK signature instead of Quote signature
1027 .TP
1028 .BR libimcv.plugins.imv-attestation.cadir
1029 Path to directory with AIK cacerts
1030 .TP
1031 .BR libimcv.plugins.imv-attestation.dh_group " [ecp256]"
1032 Preferred Diffie-Hellman group
1033 .TP
1034 .BR libimcv.plugins.imv-attestation.hash_algorithm " [sha256]"
1035 Preferred measurement hash algorithm
1036 .TP
1037 .BR libimcv.plugins.imv-attestation.min_nonce_len " [0]"
1038 DH minimum nonce length
1039 .TP
1040 .BR libimcv.plugins.imv-attestation.remediation_uri
1041 URI pointing to attestation remediation instructions
1042 .TP
1043 .BR libimcv.plugins.imc-os.push_info " [yes]"
1044 Send operating system info without being prompted
1045 .TP
1046 .BR libimcv.plugins.imv-os.remediation_uri
1047 URI pointing to operating system remediation instructions
1048 .TP
1049 .BR libimcv.plugins.imc-scanner.push_info " [yes]"
1050 Send open listening ports without being prompted
1051 .TP
1052 .BR libimcv.plugins.imv-scanner.remediation_uri
1053 URI pointing to scanner remediation instructions
1054 .TP
1055 .BR libimcv.plugins.imc-swid.swid_directory " [@prefix@/share]"
1056 Directory where SWID tags are located
1057 .TP
1058 .BR libimcv.plugins.imc-test.additional_ids " [0]"
1059 Number of additional IMC IDs
1060 .TP
1061 .BR libimcv.plugins.imc-test.command " [none]"
1062 Command to be sent to the Test IMV
1063 .TP
1064 .BR libimcv.plugins.imc-test.dummy_size " [0]"
1065 Size of dummy attribute to be sent to the Test IMV (0 = disabled)
1066 .TP
1067 .BR libimcv.plugins.imv-test.remediation_uri
1068 URI pointing to test remediation instructions
1069 .TP
1070 .BR libimcv.plugins.imc-test.retry " [no]"
1071 Do a handshake retry
1072 .TP
1073 .BR libimcv.plugins.imc-test.retry_command
1074 Command to be sent to the Test IMV in the handshake retry
1075 .TP
1076 .BR libimcv.plugins.imv-test.rounds " [0]"
1077 Number of IMC-IMV retry rounds
1078 .SS manager section
1079 .TP
1080 .BR manager.database
1081 Credential database URI for manager
1082 .TP
1083 .BR manager.debug " [no]"
1084 Enable debugging in manager
1085 .TP
1086 .BR manager.load
1087 Plugins to load in manager
1088 .TP
1089 .BR manager.socket
1090 FastCGI socket of manager, to run it statically
1091 .TP
1092 .BR manager.threads " [10]"
1093 Threads to use for request handling
1094 .TP
1095 .BR manager.timeout " [15m]"
1096 Session timeout for manager
1097 .SS mediation client section
1098 .TP
1099 .BR medcli.database
1100 Mediation client database URI
1101 .TP
1102 .BR medcli.dpd " [5m]"
1103 DPD timeout to use in mediation client plugin
1104 .TP
1105 .BR medcli.rekey " [20m]"
1106 Rekeying time on mediation connections in mediation client plugin
1107 .SS mediation server section
1108 .TP
1109 .BR medsrv.database
1110 Mediation server database URI
1111 .TP
1112 .BR medsrv.debug " [no]"
1113 Debugging in mediation server web application
1114 .TP
1115 .BR medsrv.dpd " [5m]"
1116 DPD timeout to use in mediation server plugin
1117 .TP
1118 .BR medsrv.load
1119 Plugins to load in mediation server plugin
1120 .TP
1121 .BR medsrv.password_length " [6]"
1122 Minimum password length required for mediation server user accounts
1123 .TP
1124 .BR medsrv.rekey " [20m]"
1125 Rekeying time on mediation connections in mediation server plugin
1126 .TP
1127 .BR medsrv.socket
1128 Run Mediation server web application statically on socket
1129 .TP
1130 .BR medsrv.threads " [5]"
1131 Number of thread for mediation service web application
1132 .TP
1133 .BR medsrv.timeout " [15m]"
1134 Session timeout for mediation service
1135 .SS openac section
1136 .TP
1137 .BR openac.load
1138 Plugins to load in ipsec openac tool
1139 .SS pacman section
1140 .TP
1141 .BR pacman.database
1142 Database URI for the database that stores the package information
1143 .SS pki section
1144 .TP
1145 .BR pki.load
1146 Plugins to load in ipsec pki tool
1147 .SS pool section
1148 .TP
1149 .BR pool.load
1150 Plugins to load in ipsec pool tool
1151 .SS pt-tls-client section
1152 .TP
1153 .BR pt-tls-client.load
1154 Plugins to load in ipsec pt-tls-client tool
1155 .SS scepclient section
1156 .TP
1157 .BR scepclient.load
1158 Plugins to load in ipsec scepclient tool
1159 .SS starter section
1160 .TP
1161 .BR starter.load
1162 Plugins to load in starter
1163 .TP
1164 .BR starter.load_warning " [yes]"
1165 Disable charon plugin load option warning
1166
1167 .SH LOGGER CONFIGURATION
1168 The options described below provide a much more flexible way to configure
1169 loggers for the IKEv2 daemon charon than using the
1170 .B charondebug
1171 option in
1172 .BR ipsec.conf (5).
1173 .PP
1174 .B Please note
1175 that if any loggers are specified in strongswan.conf,
1176 .B charondebug
1177 does not have any effect.
1178 .PP
1179 There are currently two types of loggers defined:
1180 .TP
1181 .B File loggers
1182 Log directly to a file and are defined by specifying the full path to the
1183 file as subsection in the
1184 .B charon.filelog
1185 section. To log to the console the two special filenames
1186 .BR stdout " and " stderr
1187 can be used.
1188 .TP
1189 .B Syslog loggers
1190 Log into a syslog facility and are defined by specifying the facility to log to
1191 as the name of a subsection in the
1192 .B charon.syslog
1193 section. The following facilities are currently supported:
1194 .BR daemon " and " auth .
1195 .PP
1196 Multiple loggers can be defined for each type with different log verbosity for
1197 the different subsystems of the daemon.
1198 .SS Options
1199 .TP
1200 .BR charon.filelog.<filename>.default " [1]"
1201 .TQ
1202 .BR charon.syslog.<facility>.default
1203 Specifies the default loglevel to be used for subsystems for which no specific
1204 loglevel is defined.
1205 .TP
1206 .BR charon.filelog.<filename>.<subsystem> " [<default>]"
1207 .TQ
1208 .BR charon.syslog.<facility>.<subsystem>
1209 Specifies the loglevel for the given subsystem.
1210 .TP
1211 .BR charon.filelog.<filename>.append " [yes]"
1212 If this option is enabled log entries are appended to the existing file.
1213 .TP
1214 .BR charon.filelog.<filename>.flush_line " [no]"
1215 Enabling this option disables block buffering and enables line buffering.
1216 .TP
1217 .BR charon.filelog.<filename>.ike_name " [no]"
1218 .TQ
1219 .BR charon.syslog.<facility>.ike_name
1220 Prefix each log entry with the connection name and a unique numerical
1221 identifier for each IKE_SA.
1222 .TP
1223 .BR charon.filelog.<filename>.time_format
1224 Prefix each log entry with a timestamp. The option accepts a format string as
1225 passed to
1226 .BR strftime (3).
1227 .TP
1228 .BR charon.syslog.identifier
1229 Global identifier used for an
1230 .BR openlog (3)
1231 call, prepended to each log message by syslog.  If not configured,
1232 .BR openlog (3)
1233 is not called, so the value will depend on system defaults (often the program
1234 name).
1235
1236 .SS Subsystems
1237 .TP
1238 .B dmn
1239 Main daemon setup/cleanup/signal handling
1240 .TP
1241 .B mgr
1242 IKE_SA manager, handling synchronization for IKE_SA access
1243 .TP
1244 .B ike
1245 IKE_SA
1246 .TP
1247 .B chd
1248 CHILD_SA
1249 .TP
1250 .B job
1251 Jobs queueing/processing and thread pool management
1252 .TP
1253 .B cfg
1254 Configuration management and plugins
1255 .TP
1256 .B knl
1257 IPsec/Networking kernel interface
1258 .TP
1259 .B net
1260 IKE network communication
1261 .TP
1262 .B asn
1263 Low-level encoding/decoding (ASN.1, X.509 etc.)
1264 .TP
1265 .B enc
1266 Packet encoding/decoding encryption/decryption operations
1267 .TP
1268 .B tls
1269 libtls library messages
1270 .TP
1271 .B esp
1272 libipsec library messages
1273 .TP
1274 .B lib
1275 libstrongwan library messages
1276 .TP
1277 .B tnc
1278 Trusted Network Connect
1279 .TP
1280 .B imc
1281 Integrity Measurement Collector
1282 .TP
1283 .B imv
1284 Integrity Measurement Verifier
1285 .TP
1286 .B pts
1287 Platform Trust Service
1288 .SS Loglevels
1289 .TP
1290 .B -1
1291 Absolutely silent
1292 .TP
1293 .B 0
1294 Very basic auditing logs, (e.g. SA up/SA down)
1295 .TP
1296 .B 1
1297 Generic control flow with errors, a good default to see whats going on
1298 .TP
1299 .B 2
1300 More detailed debugging control flow
1301 .TP
1302 .B 3
1303 Including RAW data dumps in Hex
1304 .TP
1305 .B 4
1306 Also include sensitive material in dumps, e.g. keys
1307 .SS Example
1308 .PP
1309 .EX
1310         charon {
1311                 filelog {
1312                         /var/log/charon.log {
1313                                 time_format = %b %e %T
1314                                 append = no
1315                                 default = 1
1316                         }
1317                         stderr {
1318                                 ike = 2
1319                                 knl = 3
1320                                 ike_name = yes
1321                         }
1322                 }
1323                 syslog {
1324                         # enable logging to LOG_DAEMON, use defaults
1325                         daemon {
1326                         }
1327                         # minimalistic IKE auditing logging to LOG_AUTHPRIV
1328                         auth {
1329                                 default = -1
1330                                 ike = 0
1331                         }
1332                 }
1333         }
1334 .EE
1335
1336 .SH JOB PRIORITY MANAGEMENT
1337 Some operations in the IKEv2 daemon charon are currently implemented
1338 synchronously and blocking. Two examples for such operations are communication
1339 with a RADIUS server via EAP-RADIUS, or fetching CRL/OCSP information during
1340 certificate chain verification. Under high load conditions, the thread pool may
1341 run out of available threads, and some more important jobs, such as liveness
1342 checking, may not get executed in time.
1343 .PP
1344 To prevent thread starvation in such situations job priorities were introduced.
1345 The job processor will reserve some threads for higher priority jobs, these
1346 threads are not available for lower priority, locking jobs.
1347 .SS Implementation
1348 Currently 4 priorities have been defined, and they are used in charon as
1349 follows:
1350 .TP
1351 .B CRITICAL
1352 Priority for long-running dispatcher jobs.
1353 .TP
1354 .B HIGH
1355 INFORMATIONAL exchanges, as used by liveness checking (DPD).
1356 .TP
1357 .B MEDIUM
1358 Everything not HIGH/LOW, including IKE_SA_INIT processing.
1359 .TP
1360 .B LOW
1361 IKE_AUTH message processing. RADIUS and CRL fetching block here
1362 .PP
1363 Although IKE_SA_INIT processing is computationally expensive, it is explicitly
1364 assigned to the MEDIUM class. This allows charon to do the DH exchange while
1365 other threads are blocked in IKE_AUTH. To prevent the daemon from accepting more
1366 IKE_SA_INIT requests than it can handle, use IKE_SA_INIT DROPPING.
1367 .PP
1368 The thread pool processes jobs strictly by priority, meaning it will consume all
1369 higher priority jobs before looking for ones with lower priority. Further, it
1370 reserves threads for certain priorities. A priority class having reserved
1371 .I n
1372 threads will always have
1373 .I n
1374 threads available for this class (either currently processing a job, or waiting
1375 for one).
1376 .SS Configuration
1377 To ensure that there are always enough threads available for higher priority
1378 tasks, threads must be reserved for each priority class.
1379 .TP
1380 .BR charon.processor.priority_threads.critical " [0]"
1381 Threads reserved for CRITICAL priority class jobs
1382 .TP
1383 .BR charon.processor.priority_threads.high " [0]"
1384 Threads reserved for HIGH priority class jobs
1385 .TP
1386 .BR charon.processor.priority_threads.medium " [0]"
1387 Threads reserved for MEDIUM priority class jobs
1388 .TP
1389 .BR charon.processor.priority_threads.low " [0]"
1390 Threads reserved for LOW priority class jobs
1391 .PP
1392 Let's consider the following configuration:
1393 .PP
1394 .EX
1395         charon {
1396                 processor {
1397                         priority_threads {
1398                                 high = 1
1399                                 medium = 4
1400                         }
1401                 }
1402         }
1403 .EE
1404 .PP
1405 With this configuration, one thread is reserved for HIGH priority tasks. As
1406 currently only liveness checking and stroke message processing is done with
1407 high priority, one or two threads should be sufficient.
1408 .PP
1409 The MEDIUM class mostly processes non-blocking jobs. Unless your setup is
1410 experiencing many blocks in locks while accessing shared resources, threads for
1411 one or two times the number of CPU cores is fine.
1412 .PP
1413 It is usually not required to reserve threads for CRITICAL jobs. Jobs in this
1414 class rarely return and do not release their thread to the pool.
1415 .PP
1416 The remaining threads are available for LOW priority jobs. Reserving threads
1417 does not make sense (until we have an even lower priority).
1418 .SS Monitoring
1419 To see what the threads are actually doing, invoke
1420 .IR "ipsec statusall" .
1421 Under high load, something like this will show up:
1422 .PP
1423 .EX
1424         worker threads: 2 or 32 idle, 5/1/2/22 working,
1425                 job queue: 0/0/1/149, scheduled: 198
1426 .EE
1427 .PP
1428 From 32 worker threads,
1429 .IP 2
1430 are currently idle.
1431 .IP 5
1432 are running CRITICAL priority jobs (dispatching from sockets, etc.).
1433 .IP 1
1434 is currently handling a HIGH priority job. This is actually the thread currently
1435 providing this information via stroke.
1436 .IP 2
1437 are handling MEDIUM priority jobs, likely IKE_SA_INIT or CREATE_CHILD_SA
1438 messages.
1439 .IP 22
1440 are handling LOW priority jobs, probably waiting for an EAP-RADIUS response
1441 while processing IKE_AUTH messages.
1442 .PP
1443 The job queue load shows how many jobs are queued for each priority, ready for
1444 execution. The single MEDIUM priority job will get executed immediately, as
1445 we have two spare threads reserved for MEDIUM class jobs.
1446
1447 .SH IKE_SA_INIT DROPPING
1448 If a responder receives more connection requests per seconds than it can handle,
1449 it does not make sense to accept more IKE_SA_INIT messages. And if they are
1450 queued but can't get processed in time, an answer might be sent after the
1451 client has already given up and restarted its connection setup. This
1452 additionally increases the load on the responder.
1453 .PP
1454 To limit the responder load resulting from new connection attempts, the daemon
1455 can drop IKE_SA_INIT messages just after reception. There are two mechanisms to
1456 decide if this should happen, configured with the following options:
1457 .TP
1458 .BR charon.init_limit_half_open " [0]"
1459 Limit based on the number of half open IKE_SAs. Half open IKE_SAs are SAs in
1460 connecting state, but not yet established.
1461 .TP
1462 .BR charon.init_limit_job_load " [0]"
1463 Limit based on the number of jobs currently queued for processing (sum over all
1464 job priorities).
1465 .PP
1466 The second limit includes load from other jobs, such as rekeying. Choosing a
1467 good value is difficult and depends on the hardware and expected load.
1468 .PP
1469 The first limit is simpler to calculate, but includes the load from new
1470 connections only. If your responder is capable of negotiating 100 tunnels/s, you
1471 might set this limit to 1000. The daemon will then drop new connection attempts
1472 if generating a response would require more than 10 seconds. If you are
1473 allowing for a maximum response time of more than 30 seconds, consider adjusting
1474 the timeout for connecting IKE_SAs
1475 .RB ( charon.half_open_timeout ).
1476 A responder, by default, deletes an IKE_SA if the initiator does not establish
1477 it within 30 seconds. Under high load, a higher value might be required.
1478
1479 .SH LOAD TESTS
1480 To do stability testing and performance optimizations, the IKEv2 daemon charon
1481 provides the load-tester plugin. This plugin allows one to setup thousands of
1482 tunnels concurrently against the daemon itself or a remote host.
1483 .PP
1484 .B WARNING:
1485 Never enable the load-testing plugin on productive systems. It provides
1486 preconfigured credentials and allows an attacker to authenticate as any user.
1487 .SS Options
1488 .TP
1489 .BR charon.plugins.load-tester.addrs
1490 Subsection that contains key/value pairs with address pools (in CIDR notation)
1491 to use for a specific network interface e.g. eth0 = 10.10.0.0/16
1492 .TP
1493 .BR charon.plugins.load-tester.addrs_keep " [no]"
1494 Whether to keep dynamic addresses even after the associated SA got terminated
1495 .TP
1496 .BR charon.plugins.load-tester.addrs_prefix " [16]"
1497 Network prefix length to use when installing dynamic addresses. If set to -1 the
1498 full address is used (i.e. 32 or 128)
1499 .TP
1500 .BR charon.plugins.load-tester.ca_dir
1501 Directory to load (intermediate) CA certificates from
1502 .TP
1503 .BR charon.plugins.load-tester.child_rekey " [600]"
1504 Seconds to start CHILD_SA rekeying after setup
1505 .TP
1506 .BR charon.plugins.load-tester.delay " [0]"
1507 Delay between initiatons for each thread
1508 .TP
1509 .BR charon.plugins.load-tester.delete_after_established " [no]"
1510 Delete an IKE_SA as soon as it has been established
1511 .TP
1512 .BR charon.plugins.load-tester.digest " [sha1]"
1513 Digest algorithm used when issuing certificates
1514 .TP
1515 .BR charon.plugins.load-tester.dpd_delay " [0]"
1516 DPD delay to use in load test
1517 .TP
1518 .BR charon.plugins.load-tester.dynamic_port " [0]"
1519 Base port to be used for requests (each client uses a different port)
1520 .TP
1521 .BR charon.plugins.load-tester.eap_password " [default-pwd]"
1522 EAP secret to use in load test
1523 .TP
1524 .BR charon.plugins.load-tester.enable " [no]"
1525 Enable the load testing plugin
1526 .TP
1527 .BR charon.plugins.load-tester.esp " [aes128-sha1]"
1528 CHILD_SA proposal to use for load tests
1529 .TP
1530 .BR charon.plugins.load-tester.fake_kernel " [no]"
1531 Fake the kernel interface to allow load-testing against self
1532 .TP
1533 .BR charon.plugins.load-tester.ike_rekey " [0]"
1534 Seconds to start IKE_SA rekeying after setup
1535 .TP
1536 .BR charon.plugins.load-tester.init_limit " [0]"
1537 Global limit of concurrently established SAs during load test
1538 .TP
1539 .BR charon.plugins.load-tester.initiator " [0.0.0.0]"
1540 Address to initiate from
1541 .TP
1542 .BR charon.plugins.load-tester.initiators " [0]"
1543 Number of concurrent initiator threads to use in load test
1544 .TP
1545 .BR charon.plugins.load-tester.initiator_auth " [pubkey]"
1546 Authentication method(s) the intiator uses
1547 .TP
1548 .BR charon.plugins.load-tester.initiator_id
1549 Initiator ID used in load test
1550 .TP
1551 .BR charon.plugins.load-tester.initiator_match
1552 Initiator ID to match against as responder
1553 .TP
1554 .BR charon.plugins.load-tester.initiator_tsi
1555 Traffic selector on initiator side, as proposed by initiator
1556 .TP
1557 .BR charon.plugins.load-tester.initiator_tsr
1558 Traffic selector on responder side, as proposed by initiator
1559 .TP
1560 .BR charon.plugins.load-tester.iterations " [1]"
1561 Number of IKE_SAs to initiate by each initiator in load test
1562 .TP
1563 .BR charon.plugins.load-tester.issuer_cert
1564 Path to the issuer certificate (if not configured a hard-coded value is used)
1565 .TP
1566 .BR charon.plugins.load-tester.issuer_key
1567 Path to private key that is used to issue certificates (if not configured a
1568 hard-coded value is used)
1569 .TP
1570 .BR charon.plugins.load-tester.mode " [tunnel]"
1571 IPsec mode to use, one of \fBtunnel\fR, \fBtransport\fR, or \fBbeet\fR.
1572 .TP
1573 .BR charon.plugins.load-tester.pool
1574 Provide INTERNAL_IPV4_ADDRs from a named pool
1575 .TP
1576 .BR charon.plugins.load-tester.preshared_key " [default-psk]"
1577 Preshared key to use in load test
1578 .TP
1579 .BR charon.plugins.load-tester.proposal " [aes128-sha1-modp768]"
1580 IKE proposal to use in load test
1581 .TP
1582 .BR charon.plugins.load-tester.responder " [127.0.0.1]"
1583 Address to initiation connections to
1584 .TP
1585 .BR charon.plugins.load-tester.responder_auth " [pubkey]"
1586 Authentication method(s) the responder uses
1587 .TP
1588 .BR charon.plugins.load-tester.responder_id
1589 Responder ID used in load test
1590 .TP
1591 .BR charon.plugins.load-tester.responder_tsi " [initiator_tsi]"
1592 Traffic selector on initiator side, as narrowed by responder
1593 .TP
1594 .BR charon.plugins.load-tester.responder_tsr " [initiator_tsr]"
1595 Traffic selector on responder side, as narrowed by responder
1596 .TP
1597 .BR charon.plugins.load-tester.request_virtual_ip " [no]"
1598 Request an INTERNAL_IPV4_ADDR from the server
1599 .TP
1600 .BR charon.plugins.load-tester.shutdown_when_complete " [no]"
1601 Shutdown the daemon after all IKE_SAs have been established
1602 .TP
1603 .BR charon.plugins.load-tester.socket " [unix://@piddir@/charon.ldt]"
1604 Socket provided by the load-tester plugin
1605 .TP
1606 .BR charon.plugins.load-tester.version " [0]"
1607 IKE version to use (0 means use IKEv2 as initiator and accept any version as
1608 responder)
1609 .PP
1610 .SS Configuration details
1611 For public key authentication, the responder uses the
1612 .B \(dqCN=srv, OU=load-test, O=strongSwan\(dq
1613 identity. For the initiator, each connection attempt uses a different identity
1614 in the form
1615 .BR "\(dqCN=c1-r1, OU=load-test, O=strongSwan\(dq" ,
1616 where the first number inidicates the client number, the second the
1617 authentication round (if multiple authentication is used).
1618 .PP
1619 For PSK authentication, FQDN identities are used. The server uses
1620 .BR srv.strongswan.org ,
1621 the client uses an identity in the form
1622 .BR c1-r1.strongswan.org .
1623 .PP
1624 For EAP authentication, the client uses a NAI in the form
1625 .BR 100000000010001@strongswan.org .
1626 .PP
1627 To configure multiple authentication, concatenate multiple methods using, e.g.
1628 .EX
1629         initiator_auth = pubkey|psk|eap-md5|eap-aka
1630 .EE
1631 .PP
1632 The responder uses a hardcoded certificate based on a 1024-bit RSA key.
1633 This certificate additionally serves as CA certificate. A peer uses the same
1634 private key, but generates client certificates on demand signed by the CA
1635 certificate. Install the Responder/CA certificate on the remote host to
1636 authenticate all clients.
1637 .PP
1638 To speed up testing, the load tester plugin implements a special Diffie-Hellman
1639 implementation called modpnull. By setting
1640 .EX
1641         proposal = aes128-sha1-modpnull
1642 .EE
1643 this wicked fast DH implementation is used. It does not provide any security
1644 at all, but allows one to run tests without DH calculation overhead.
1645 .SS Examples
1646 .PP
1647 In the simplest case, the daemon initiates IKE_SAs against itself using the
1648 loopback interface. This will actually establish double the number of IKE_SAs,
1649 as the daemon is initiator and responder for each IKE_SA at the same time.
1650 Installation of IPsec SAs would fails, as each SA gets installed twice. To
1651 simulate the correct behavior, a fake kernel interface can be enabled which does
1652 not install the IPsec SAs at the kernel level.
1653 .PP
1654 A simple loopback configuration might look like this:
1655 .PP
1656 .EX
1657         charon {
1658                 # create new IKE_SAs for each CHILD_SA to simulate
1659                 # different clients
1660                 reuse_ikesa = no
1661                 # turn off denial of service protection
1662                 dos_protection = no
1663
1664                 plugins {
1665                         load-tester {
1666                                 # enable the plugin
1667                                 enable = yes
1668                                 # use 4 threads to initiate connections
1669                                 # simultaneously
1670                                 initiators = 4
1671                                 # each thread initiates 1000 connections
1672                                 iterations = 1000
1673                                 # delay each initiation in each thread by 20ms
1674                                 delay = 20
1675                                 # enable the fake kernel interface to
1676                                 # avoid SA conflicts
1677                                 fake_kernel = yes
1678                         }
1679                 }
1680         }
1681 .EE
1682 .PP
1683 This will initiate 4000 IKE_SAs within 20 seconds. You may increase the delay
1684 value if your box can not handle that much load, or decrease it to put more
1685 load on it. If the daemon starts retransmitting messages your box probably can
1686 not handle all connection attempts.
1687 .PP
1688 The plugin also allows one to test against a remote host. This might help to
1689 test against a real world configuration. A connection setup to do stress
1690 testing of a gateway might look like this:
1691 .PP
1692 .EX
1693         charon {
1694                 reuse_ikesa = no
1695                 threads = 32
1696
1697                 plugins {
1698                         load-tester {
1699                                 enable = yes
1700                                 # 10000 connections, ten in parallel
1701                                 initiators = 10
1702                                 iterations = 1000
1703                                 # use a delay of 100ms, overall time is:
1704                                 # iterations * delay = 100s
1705                                 delay = 100
1706                                 # address of the gateway
1707                                 remote = 1.2.3.4
1708                                 # IKE-proposal to use
1709                                 proposal = aes128-sha1-modp1024
1710                                 # use faster PSK authentication instead
1711                                 # of 1024bit RSA
1712                                 initiator_auth = psk
1713                                 responder_auth = psk
1714                                 # request a virtual IP using configuration
1715                                 # payloads
1716                                 request_virtual_ip = yes
1717                                 # enable CHILD_SA every 60s
1718                                 child_rekey = 60
1719                         }
1720                 }
1721         }
1722 .EE
1723
1724 .SH IKEv2 RETRANSMISSION
1725 Retransmission timeouts in the IKEv2 daemon charon can be configured globally
1726 using the three keys listed below:
1727 .PP
1728 .RS
1729 .nf
1730 .BR charon.retransmit_base " [1.8]"
1731 .BR charon.retransmit_timeout " [4.0]"
1732 .BR charon.retransmit_tries " [5]"
1733 .fi
1734 .RE
1735 .PP
1736 The following algorithm is used to calculate the timeout:
1737 .PP
1738 .EX
1739         relative timeout = retransmit_timeout * retransmit_base ^ (n-1)
1740 .EE
1741 .PP
1742 Where
1743 .I n
1744 is the current retransmission count.
1745 .PP
1746 Using the default values, packets are retransmitted in:
1747
1748 .TS
1749 l r r
1750 ---
1751 lB r r.
1752 Retransmission  Relative Timeout        Absolute Timeout
1753 1       4s      4s
1754 2       7s      11s
1755 3       13s     24s
1756 4       23s     47s
1757 5       42s     89s
1758 giving up       76s     165s
1759 .TE
1760
1761 .SH FILES
1762 /etc/strongswan.conf
1763
1764 .SH SEE ALSO
1765 \fBipsec.conf\fR(5), \fBipsec.secrets\fR(5), \fBipsec\fR(8), \fBcharon-cmd\fR(8)
1766
1767 .SH HISTORY
1768 Written for the
1769 .UR http://www.strongswan.org
1770 strongSwan project
1771 .UE
1772 by Tobias Brunner, Andreas Steffen and Martin Willi.