f8d32e478095e6a4146e388f563d0eefb7758af5
[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 READING VALUES
64 Values are accessed using a dot-separated section list and a key.
65 With reference to the example above, accessing
66 .B section-one.subsection.othervalue
67 will return
68 .BR xxx .
69
70 .SH DEFINED KEYS
71 The following keys are currently defines (using dot notation). The default
72 value (if any) is listed in brackets after the key.
73
74 .SS charon section
75 .TP
76 .BR charon.block_threshold " [5]"
77 Maximum number of half-open IKE_SAs for a single peer IP
78 .TP
79 .BR charon.close_ike_on_child_failure " [no]"
80 Close the IKE_SA if setup of the CHILD_SA along with IKE_AUTH failed
81 .TP
82 .BR charon.cookie_threshold " [10]"
83 Number of half-open IKE_SAs that activate the cookie mechanism
84 .TP
85 .BR charon.dns1
86 .TQ
87 .BR charon.dns2
88 DNS servers assigned to peer via configuration payload (CP)
89 .TP
90 .BR charon.dos_protection " [yes]"
91 Enable Denial of Service protection using cookies and aggressiveness checks
92 .TP
93 .BR charon.filelog
94 Section to define file loggers, see LOGGER CONFIGURATION.
95 .TP
96 .BR charon.hash_and_url " [no]"
97 Enable hash and URL support
98 .TP
99 .BR charon.ikesa_table_segments " [1]"
100 Number of exclusively locked segments in the hash table
101 .TP
102 .BR charon.ikesa_table_size " [1]"
103 Size of the IKE_SA hash table
104 .TP
105 .BR charon.inactivity_close_ike " [no]"
106 Whether to close IKE_SA if the only CHILD_SA closed due to inactivity
107 .TP
108 .BR charon.install_routes " [yes]"
109 Install routes into a separate routing table for established IPsec tunnels
110 .TP
111 .BR charon.keep_alive " [20s]"
112 NAT keep alive interval
113 .TP
114 .BR charon.load
115 Plugins to load in IKEv2 charon daemon
116 .TP
117 .BR charon.multiple_authentication " [yes]"
118 Enable multiple authentication exchanges (RFC 4739)
119 .TP
120 .BR charon.nbns1
121 .TQ
122 .BR charon.nbns2
123 WINS servers assigned to peer via configuration payload (CP)
124 .TP
125 .BR charon.process_route " [yes]"
126 Process RTM_NEWROUTE and RTM_DELROUTE events
127 .TP
128 .BR charon.retransmit_base " [1.8]"
129 Base to use for calculating exponential back off, see IKEv2 RETRANSMISSION below
130 .TP
131 .BR charon.retransmit_timeout " [4.0]
132 Timeout in seconds before sending first retransmit
133 .TP
134 .BR charon.retransmit_tries " [5]"
135 Number of times to retransmit a packet before giving up
136 .TP
137 .BR charon.reuse_ikesa " [yes]
138 Initiate CHILD_SA within existing IKE_SAs
139 .TP
140 .BR charon.routing_table
141 Numerical routing table to install routes to
142 .TP
143 .BR charon.routing_table_prio
144 Priority of the routing table
145 .TP
146 .BR charon.send_vendor_id " [no]
147 Send strongSwan vendor ID payload
148 .TP
149 .BR charon.syslog
150 Section to define syslog loggers, see LOGGER CONFIGURATION.
151 .TP
152 .BR charon.threads " [16]"
153 Number of worker threads in charon
154 .SS charon.plugins subsection
155 .TP
156 .BR charon.plugins.dhcp.identity_lease " [no]"
157 Derive user-defined MAC address from hash of IKEv2 identity
158 .TP
159 .BR charon.plugins.dhcp.server " [255.255.255.255]"
160 DHCP server unicast or broadcast IP address
161 .TP
162 .BR charon.plugins.eap-aka.request_identity " [yes]"
163 .TP
164 .BR charon.plugins.eap-aka-3ggp2.seq_check
165 .TP
166 .BR charon.plugins.eap-gtc.pam_service " [login]"
167 PAM service to be used for authentication
168 .TP
169 .BR charon.plugins.eap-radius.secret
170 Shared secret between RADIUS and NAS
171 .TP
172 .BR charon.plugins.eap-radius.server
173 IP/Hostname of RADIUS server
174 .TP
175 .BR charon.plugins.eap-radius.port " [1812]"
176 Port of RADIUS server (authentication)
177 .TP
178 .BR charon.plugins.eap-radius.sockets " [5]"
179 Number of sockets (ports) to use, increase for high load
180 .TP
181 .BR charon.plugins.eap-radius.nas_identifier " [strongSwan]"
182 NAS-Identifier to include in RADIUS messages
183 .TP
184 .BR charon.plugins.eap-radius.eap_start " [no]"
185 Send EAP-Start instead of EAP-Identity to start RADIUS conversation
186 .TP
187 .BR charon.plugins.eap-radius.id_prefix
188 Prefix to EAP-Identity, some AAA servers use a IMSI prefix to select the EAP method
189 .TP
190 .BR charon.plugins.eap-sim.request_identity " [yes]"
191
192 .TP
193 .BR charon.plugins.eap-tls.fragment_size " [1024]"
194 Maximum size of an EAP-TLS packet
195 .TP
196 .BR charon.plugins.eap-tls.max_message_count " [32]"
197 Maximum number of processed EAP-TLS packets
198 .TP
199 .BR charon.plugins.eap-ttls.fragment_size " [1024]"
200 Maximum size of an EAP-TTLS packet
201 .TP
202 .BR charon.plugins.eap-ttls.max_message_count " [32]"
203 Maximum number of processed EAP-TTLS packets
204 .TP
205 .BR charon.plugins.eap-ttls.phase2_method " [md5]"
206 Phase2 EAP client authentication method
207 .TP
208 .BR charon.plugins.eap-ttls.phase2_piggyback " [no]"
209 Phase2 EAP Identity request piggybacked by server onto TLS Finished message
210 .TP
211 .BR charon.plugins.eap-ttls.request_peer_auth " [no]"
212 Request peer authentication based on a client certificate
213 .TP
214 .BR charon.plugins.ha.fifo_interface " [yes]"
215
216 .TP
217 .BR charon.plugins.ha.local
218
219 .TP
220 .BR charon.plugins.ha.monitor " [yes]"
221
222 .TP
223 .BR charon.plugins.ha.remote
224
225 .TP
226 .BR charon.plugins.ha.resync " [yes]"
227
228 .TP
229 .BR charon.plugins.ha.secret
230
231 .TP
232 .BR charon.plugins.ha.segment_count " [1]"
233
234 .TP
235 .BR charon.plugins.kernel-klips.ipsec_dev_mtu " [0]"
236 Set MTU of ipsecN device
237 .TP
238 .BR charon.plugins.load-tester.enable " [no]"
239 Enable the load testing plugin
240 .TP
241 .BR charon.plugins.load-tester.initiators " [0]"
242 Number of concurrent initiator threads to use in load test
243 .TP
244 .BR charon.plugins.load-tester.iterations " [1]"
245 Number of IKE_SAs to initate to self by each initiator in load test
246 .TP
247 .BR charon.plugins.load-tester.delay " [0]"
248 Delay between initiatons for each thread
249 .TP
250 .BR charon.plugins.load-tester.proposal " [aes128-sha1-modp1024]"
251 IKE proposal to use in load test
252 .TP
253 .BR charon.plugins.load-tester.initiator_auth " [pubkey]"
254 Authentication method(s) the intiator uses
255 .TP
256 .BR charon.plugins.load-tester.responder_auth " [pubkey]"
257 Authentication method(s) the responder uses
258 .TP
259 .BR charon.plugins.load-tester.fake_kernel " [no]"
260 Fake the kernel interface to allow load-testing against self
261 .TP
262 .BR charon.plugins.load-tester.delete_after_established " [no]"
263 Delete an IKE_SA as soon as it has been established
264 .TP
265 .BR charon.plugins.load-tester.request_virtual_ip " [no]"
266 Request an INTERNAL_IPV4_ADDR from the server
267 .TP
268 .BR charon.plugins.load-tester.pool
269 Provide INTERNAL_IPV4_ADDRs from a named pool
270 .TP
271 .BR charon.plugins.load-tester.remote " [127.0.0.1]"
272 Address to initiation connections to
273 .TP
274 .BR charon.plugins.load-tester.ike_rekey " [0]"
275 Seconds to start IKE_SA rekeying after setup
276 .TP
277 .BR charon.plugins.load-tester.child_rekey " [600]"
278 Seconds to start CHILD_SA rekeying after setup
279 .TP
280 .BR charon.plugins.resolve.file " [/etc/resolv.conf]"
281 File where to add DNS server entries
282 .TP
283 .BR charon.plugins.sql.database
284 Database URI for charons SQL plugin
285 .TP
286 .BR charon.plugins.sql.loglevel " [-1]"
287 Loglevel for logging to SQL database
288 .SS libstrongswan section
289 .TP
290 .BR libstrongswan.dh_exponent_ansi_x9_42 " [yes]"
291 Use ANSI X9.42 DH exponent size or optimum size matched to cryptographical strength
292 .TP
293 .BR libstrongswan.crypto_test.on_add " [no]"
294 Test crypto algorithms during registration
295 .TP
296 .BR libstrongswan.crypto_test.on_create " [no]"
297 Test crypto algorithms on each crypto primitive instantiation
298 .TP
299 .BR libstrongswan.crypto_test.required " [no]"
300 Strictly require at least one test vector to enable an algorithm
301 .TP
302 .BR libstrongswan.crypto_test.rng_true " [no]"
303 Whether to test RNG with TRUE quality; requires a lot of entropy
304 .TP
305 .BR libstrongswan.ecp_x_coordinate_only " [yes]"
306 Compliance with the errata for RFC 4753
307 .TP
308 .BR libstrongswan.integrity_test " [no]"
309 Check daemon, libstrongswan and plugin integrity at startup
310 .SS libstrongswan.plugins subsection
311 .TP
312 .BR libstrongswan.plugins.attr-sql.database
313 Database URI for attr-sql plugin used by charon and pluto
314 .TP
315 .BR libstrongswan.plugins.attr-sql.lease_history " [yes]"
316 Enable logging of SQL IP pool leases
317 .TP
318 .BR libstrongswan.plugins.gcrypt.quick_random " [no]"
319 Use faster random numbers in gcrypt; for testing only, produces weak keys!
320 .TP
321 .BR libstrongswan.plugins.openssl.engine_id " [pkcs11]"
322 ENGINE ID to use in the OpenSSL plugin
323 .TP
324 .BR libstrongswan.plugins.x509.enforce_critical " [no]"
325 Discard certificates with unsupported or unknown critical extensions
326 .SS libtls section
327 .TP
328 .BR libtls.cipher
329 List of TLS encryption ciphers
330 .TP
331 .BR libtls.key_exchange
332 List of TLS key exchange methods
333 .TP
334 .BR libtls.mac
335 List of TLS MAC algorithms
336 .SS manager section
337 .TP
338 .BR manager.database
339 Credential database URI for manager
340 .TP
341 .BR manager.debug " [no]"
342 Enable debugging in manager
343 .TP
344 .BR manager.load
345 Plugins to load in manager
346 .TP
347 .BR manager.socket
348 FastCGI socket of manager, to run it statically
349 .TP
350 .BR manager.threads " [10]"
351 Threads to use for request handling
352 .TP
353 .BR manager.timeout " [15m]"
354 Session timeout for manager
355 .SS mediation client section
356 .TP
357 .BR medcli.database
358 Mediation client database URI
359 .TP
360 .BR medcli.dpd " [5m]"
361 DPD timeout to use in mediation client plugin
362 .TP
363 .BR medcli.rekey " [20m]"
364 Rekeying time on mediation connections in mediation client plugin
365 .SS mediation server section
366 .TP
367 .BR medsrv.database
368 Mediation server database URI
369 .TP
370 .BR medsrv.debug " [no]"
371 Debugging in mediation server web application
372 .TP
373 .BR medsrv.dpd " [5m]"
374 DPD timeout to use in mediation server plugin
375 .TP
376 .BR medsrv.load
377 Plugins to load in mediation server plugin
378 .TP
379 .BR medsrv.password_length " [6]"
380 Minimum password length required for mediation server user accounts
381 .TP
382 .BR medsrv.rekey " [20m]"
383 Rekeying time on mediation connections in mediation server plugin
384 .TP
385 .BR medsrv.socket
386 Run Mediation server web application statically on socket
387 .TP
388 .BR medsrv.threads " [5]"
389 Number of thread for mediation service web application
390 .TP
391 .BR medsrv.timeout " [15m]"
392 Session timeout for mediation service
393 .SS openac section
394 .TP
395 .BR openac.load
396 Plugins to load in ipsec openac tool
397 .SS pki section
398 .TP
399 .BR pki.load
400 Plugins to load in ipsec pki tool
401 .SS pluto section
402 .TP
403 .BR pluto.dns1
404 .TQ
405 .BR pluto.dns2
406 DNS servers assigned to peer via configuration payload (CP)
407 .TP
408 .BR pluto.load
409 Plugins to load in IKEv1 pluto daemon
410 .TP
411 .BR pluto.nbns1
412 .TQ
413 .BR pluto.nbns2
414 WINS servers assigned to peer via configuration payload (CP)
415 .SS pool section
416 .TP
417 .BR pool.load
418 Plugins to load in ipsec pool tool
419 .SS scepclient section
420 .TP
421 .BR scepclient.load
422 Plugins to load in ipsec scepclient tool
423 .SS starter section
424 .TP
425 .BR starter.load_warning " [yes]"
426 Disable charon/pluto plugin load option warning
427
428 .SH LOGGER CONFIGURATION
429 The options described below provide a much more flexible way to configure
430 loggers for the IKEv2 daemon charon than using the
431 .B charondebug
432 option in
433 .BR ipsec.conf (5).
434 .PP
435 .B Please note
436 that if any loggers are specified in strongswan.conf,
437 .B charondebug
438 does not have any effect.
439 .PP
440 There are currently two types of loggers defined:
441 .TP
442 .B File loggers
443 Log directly to a file and are defined by specifying the full path to the
444 file as subsection in the
445 .B charon.filelog
446 section. To log to the console the two special filenames
447 .BR stdout " and " stderr
448 can be used.
449 .TP
450 .B Syslog loggers
451 Log into a syslog facility and are defined by specifying the facility to log to
452 as the name of a subsection in the
453 .B charon.syslog
454 section. The following facilities are currently supported:
455 .BR daemon " and " auth .
456 .PP
457 Multiple loggers can be defined for each type with different log verbosity for
458 the different subsystems of the daemon.
459 .SS Options
460 .TP
461 .BR charon.filelog.<filename>.default " [1]"
462 .TQ
463 .BR charon.syslog.<facility>.default
464 Specifies the default loglevel to be used for subsystems for which no specific
465 loglevel is defined.
466 .TP
467 .BR charon.filelog.<filename>.<subsystem> " [<default>]"
468 .TQ
469 .BR charon.syslog.<facility>.<subsystem>
470 Defines the loglevel for the given subsystem.
471 .TP
472 .BR charon.filelog.<filename>.append " [yes]"
473 If this option is enabled log entries are appended to the existing file
474 .TP
475 .BR charon.filelog.<filename>.flush_line " [no]"
476 Enabling this option disables block buffering and enables line buffering.
477 .TP
478 .BR charon.filelog.<filename>.ike_name " [no]"
479 .TQ
480 .BR charon.syslog.<facility>.ike_name
481 Prefix each log entry with the connection name and a unique numerical
482 identifier for each IKE_SA.
483 .TP
484 .BR charon.filelog.<filename>.time_format
485 Prefix each log entry with a timestamp. The option accepts a format string as
486 passed to
487 .BR strftime (3).
488
489 .SS Subsystems
490 .TP
491 .B dmn
492 Main daemon setup/cleanup/signal handling
493 .TP
494 .B mgr
495 IKE_SA manager, handling synchronization for IKE_SA access
496 .TP
497 .B ike
498 IKE_SA
499 .TP
500 .B chd
501 CHILD_SA
502 .TP
503 .B job
504 Jobs queueing/processing and thread pool management
505 .TP
506 .B cfg
507 Configuration management and plugins
508 .TP
509 .B knl
510 IPsec/Networking kernel interface
511 .TP
512 .B net
513 IKE network communication
514 .TP
515 .B enc
516 Packet encoding/decoding encryption/decryption operations
517 .TP
518 .B tls
519 libtls library messages
520 .TP
521 .B lib
522 libstrongwan library messages
523 .SS Loglevels
524 .TP
525 .B -1
526 Absolutely silent
527 .TP
528 .B 0
529 Very basic auditing logs, (e.g. SA up/SA down)
530 .TP
531 .B 1
532 Generic control flow with errors, a good default to see whats going on
533 .TP
534 .B 2
535 More detailed debugging control flow
536 .TP
537 .B 3
538 Including RAW data dumps in Hex
539 .TP
540 .B 4
541 Also include sensitive material in dumps, e.g. keys
542 .SS Example
543 .PP
544 .EX
545         charon {
546                 filelog {
547                         /var/log/charon.log {
548                                 time_format = %b %e %T
549                                 append = no
550                                 default = 1
551                         }
552                         stderr {
553                                 ike = 2
554                                 knl = 3
555                                 ike_name = yes
556                         }
557                 }
558                 syslog {
559                         # enable logging to LOG_DAEMON, use defaults
560                         daemon {
561                         }
562                         # minimalistic IKE auditing logging to LOG_AUTHPRIV
563                         auth {
564                                 default = -1
565                                 ike = 0
566                         }
567                 }
568         }
569 .EE
570
571 .SH IKEv2 RETRANSMISSION
572 Retransmission timeouts in the IKEv2 daemon charon can be configured globally
573 using the three keys listed below:
574 .PP
575 .RS
576 .nf
577 .BR charon.retransmit_base " [1.8]"
578 .BR charon.retransmit_timeout " [4.0]"
579 .BR charon.retransmit_tries " [5]"
580 .fi
581 .RE
582 .PP
583 The following algorithm is used to calculate the timeout:
584 .PP
585 .EX
586         relative timeout = retransmit_timeout * retransmit_base ^ (n-1)
587 .EE
588 .PP
589 Where
590 .I n
591 is the current retransmission count.
592 .PP
593 Using the default values, packets are retransmitted in:
594
595 .TS
596 l r r
597 ---
598 lB r r.
599 Retransmission  Relative Timeout        Absolute Timeout
600 1       4s      4s
601 2       7s      11s
602 3       13s     24s
603 4       23s     47s
604 5       42s     89s
605 giving up       76s     165s
606 .TE
607
608 .SH FILES
609 /etc/strongswan.conf
610
611 .SH SEE ALSO
612 ipsec.conf (5), ipsec.secrets (5)
613 .SH HISTORY
614 Written for the
615 .UR http://www.strongswan.org
616 strongSwan project
617 .UE
618 by Tobias Brunner, Andreas Steffen and Martin Willi.