Browse code

core, lib, modules: restructured source code tree

- new folder src/ to hold the source code for main project applications
- main.c is in src/
- all core files are subfolder are in src/core/
- modules are in src/modules/
- libs are in src/lib/
- application Makefiles are in src/
- application binary is built in src/ (src/kamailio)

Daniel-Constantin Mierla authored on 07/12/2016 11:03:51
Showing 1 changed files
1 1
deleted file mode 100644
... ...
@@ -1,1155 +0,0 @@
1
-<?xml version="1.0" encoding="UTF-8"?>
2
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3
-		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
4
-	[<!-- Include general documentation entities -->
5
-	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
6
-	 %docentities;
7
-	]
8
->
9
-
10
-<section id="tls.parameters">
11
-    <sectioninfo>
12
-    </sectioninfo>
13
-
14
-    <title>Parameters</title>
15
-
16
-	<section id="tls.p.tls_method">
17
-	<title><varname>tls_method</varname> (string)</title>
18
-	<para>
19
-		Sets the SSL/TLS protocol method. Possible values are:
20
-	</para>
21
-	<itemizedlist>
22
-			<listitem>
23
-				<para>
24
-				<emphasis>TLSv1.2</emphasis> - only TLSv1.2 connections are accepted
25
-				(available starting with openssl/libssl v1.0.1e)
26
-				</para>
27
-			</listitem>
28
-			<listitem>
29
-				<para>
30
-				<emphasis>TLSv1.1+</emphasis> - TLSv1.1 or newer (TLSv1.2, ...)
31
-				connections are accepted (available starting with openssl/libssl v1.0.1)
32
-				</para>
33
-			</listitem>
34
-			<listitem>
35
-				<para>
36
-				<emphasis>TLSv1.1</emphasis> - only TLSv1.1 connections are accepted
37
-				(available starting with openssl/libssl v1.0.1)
38
-				</para>
39
-			</listitem>
40
-			<listitem>
41
-				<para>
42
-				<emphasis>TLSv1+</emphasis> - TLSv1.0 or newer (TLSv1.1, TLSv1.2, ...)
43
-				connections are accepted.
44
-				</para>
45
-			</listitem>
46
-			<listitem>
47
-				<para>
48
-				<emphasis>TLSv1</emphasis> - only TLSv1 (TLSv1.0) connections are
49
-				accepted. This is the default value.
50
-				</para>
51
-			</listitem>
52
-			<listitem>
53
-				<para>
54
-				<emphasis>SSLv3</emphasis> - only SSLv3 connections are accepted.
55
-				Note: you shouldn't use SSLv3 for anything which should be highly secure.
56
-				</para>
57
-			</listitem>
58
-			<listitem>
59
-				<para>
60
-				<emphasis>SSLv2</emphasis> - only SSLv2 connections, for old clients.
61
-				Note: you shouldn't use SSLv2 for anything which should be highly secure.
62
-				Newer versions of libssl don't include support for it anymore.
63
-				</para>
64
-			</listitem>
65
-			<listitem>
66
-				<para>
67
-				<emphasis>SSLv23</emphasis> - any of the SSLv2, SSLv3 and TLSv1 or
68
-				newer methods will be accepted.
69
-				</para>
70
-				<para>
71
-				From the OpenSSL manual: "A TLS/SSL connection established with these
72
-				methods may understand the SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols.
73
-				If extensions are required (for example server name) a client will
74
-				send out TLSv1 client hello messages including extensions and will
75
-				indicate that it also understands TLSv1.1, TLSv1.2 and permits a
76
-				fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1
77
-				and TLSv1.2 protocols. This is the best choice when compatibility
78
-				is a concern."
79
-				</para>
80
-				<para>
81
-				Note: For older libssl version, this option allows SSLv2, with hello
82
-				messages done over SSLv2. You shouldn't use SSLv2 or SSLv3 for anything
83
-				which should be highly secure.
84
-				</para>
85
-			</listitem>
86
-	</itemizedlist>
87
-	<para>
88
-		If RFC 3261 conformance is desired, at least TLSv1 must be used. For
89
-		compatibility with older clients SSLv23 is the option, but again, be aware
90
-		of security concerns, SSLv2/3 being considered very insecure by 2014.
91
-	</para>
92
-	<example>
93
-	    <title>Set <varname>tls_method</varname> parameter</title>
94
-	    <programlisting>
95
-...
96
-modparam("tls", "tls_method", "TLSv1")
97
-...
98
-	    </programlisting>
99
-	</example>
100
-	</section>
101
-
102
-	<section id="tls.p.certificate">
103
-	<title><varname>certificate</varname> (string)</title>
104
-	<para>
105
-		Sets the certificate file name. The certificate file can also contain
106
-		the private key in PEM format.
107
-	</para>
108
-	<para>
109
-		If the file name starts with a '.' the path will be relative to the
110
-		working directory (<emphasis>at runtime</emphasis>). If it starts
111
-		with a '/' it will be an absolute path and if it starts with anything
112
-		else the path will be relative to the main config file directory
113
-		(e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
114
-	</para>
115
-	<para>
116
-		<emphasis>Warning:</emphasis> try not to use certificate with keys
117
-		longer then 2048 bytes. Longer keys will severely impact performance,
118
-		in particular the TLS connection rate.
119
-	</para>
120
-	<para>
121
-		The default value is &kamailioconfdir;/cert.pem
122
-	</para>
123
-	<example>
124
-	    <title>Set <varname>certificate</varname> parameter</title>
125
-	    <programlisting>
126
-...
127
-modparam("tls", "certificate", "/usr/local/etc/kamailio/my_certificate.pem")
128
-...
129
-	    </programlisting>
130
-	</example>
131
-	</section>
132
-
133
-	<section id="tls.p.private_key">
134
-	<title><varname>private_key</varname> (string)</title>
135
-	<para>
136
-		Sets the private key file name. The private key can be in the same
137
-		file as the certificate or in a separate file, specified by this
138
-		configuration parameter.
139
-	</para>
140
-	<para>
141
-		If the file name starts with a '.' the path will be relative to the
142
-		working directory (<emphasis>at runtime</emphasis>). If it starts
143
-		with a '/' it will be an absolute path and if it starts with anything
144
-		else the path will be relative to the main config file directory
145
-		(e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
146
-	</para>
147
-	<para>
148
-		Note: the private key can be contained in the same file as the
149
-		certificate (just append it to the certificate file, e.g.:
150
-		cat pkey.pem &gt;&gt; cert.pem)
151
-	</para>
152
-	<para>
153
-		The default value is &kamailioconfdir;/cert.pem
154
-	</para>
155
-	<example>
156
-	    <title>Set <varname>private_key</varname> parameter</title>
157
-	    <programlisting>
158
-...
159
-modparam("tls", "private", "/usr/local/etc/kamailio/my_pkey.pem")
160
-...
161
-	    </programlisting>
162
-	</example>
163
-	</section>
164
-
165
-	<section id="tls.p.ca_list">
166
-	<title><varname>ca_list</varname> (string)</title>
167
-	<para>
168
-		Sets the CA list file name. This file contains a list of all the
169
-		trusted CAs certificates. If a signature in a certificate chain belongs
170
-		to one of the listed CAs, the verification of that certificate will succeed.
171
-	</para>
172
-	<para>
173
-		If the file name starts with a '.' the path will be relative to the
174
-		working directory (<emphasis>at runtime</emphasis>). If it starts
175
-		with a '/' it will be an absolute path and if it starts with anything
176
-		else the path will be relative to the main config file directory
177
-		(e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
178
-	</para>
179
-	<para>
180
-		By default the CA file is not set.
181
-	</para>
182
-	<para>
183
-		An easy way to create the CA list is to append each trusted trusted CA
184
-		certificate in the PEM format to one file, e.g.: for f in
185
-		trusted_cas/*.pem ; do cat "$f" &gt;&gt; ca_list.pem ; done .
186
-	</para>
187
-	<para>
188
-		See also
189
-		<emphasis>verify_certificate</emphasis>,
190
-		<emphasis>verify_depth</emphasis>,
191
-		<emphasis>require_certificate</emphasis> and
192
-		<emphasis>crl</emphasis>.
193
-	</para>
194
-	<example>
195
-	    <title>Set <varname>ca_list</varname> parameter</title>
196
-	    <programlisting>
197
-...
198
-modparam("tls", "ca_list", "/usr/local/etc/kamailio/ca_list.pem")
199
-...
200
-	    </programlisting>
201
-	</example>
202
-	</section>
203
-
204
-	<section id="tls.p.crl">
205
-	<title><varname>crl</varname> (string)</title>
206
-	<para>
207
-		Sets the certificate revocation list (CRL) file name. This file contains a
208
-		list of revoked certificates. Any attempt to verify a revoked
209
-		certificate will fail.
210
-	</para>
211
-	<para>
212
-		If not set, no CRL list will be used.
213
-	</para>
214
-	<para>
215
-		If the file name starts with a '.' the path will be relative to the
216
-		working directory (<emphasis>at runtime</emphasis>). If it starts
217
-		with a '/' it will be an absolute path and if it starts with anything
218
-		else the path will be relative to the main config file directory
219
-		(e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
220
-	</para>
221
-	<note><para>
222
-		If set, <varname>require_certificate</varname> should also be set
223
-		or it will not have any effect.
224
-	</para></note>
225
-	<para>
226
-		By default the CRL file name is not set.
227
-	</para>
228
-	<para>
229
-		To update the CRL in a running &kamailio;, make sure you configure TLS
230
-		via a separate TLS config file
231
-		(the <varname>config</varname> modparam) and issue a tls.reload
232
-		RPC call, e.g.:
233
-		<programlisting>
234
- $ &sercmd; tls.reload
235
-		</programlisting>
236
-	</para>
237
-	<para>
238
-		A quick way to create the CRL in PEM format, using OpenSSL is:
239
-		<programlisting>
240
- $ openssl ca -gencrl -keyfile cacert.key -cert cacert.pem -out my_crl.pem
241
-		</programlisting>
242
-		 my_crl.pem will contain the signed list of the revoked certificates.
243
-	</para>
244
-	<para>
245
-		To revoke a TLS certificate use something like:
246
-		<programlisting>
247
- $ openssl ca -revoke bad_cert.pem -keyfile cacert.key -cert cacert.pem
248
-		</programlisting>
249
-		and then refresh the crl file using the command above.
250
-	</para>
251
-	<para>
252
-		To display the CRL contents use:
253
-		<programlisting>
254
- $ openssl crl -in crl.pem -noout -text
255
-		</programlisting>
256
-	</para>
257
-	<para>
258
-		See also
259
-		<emphasis>ca_list</emphasis>,
260
-		<emphasis>verify_certificate</emphasis>,
261
-		<emphasis>verify_depth</emphasis> and
262
-		<emphasis>require_certificate</emphasis>.
263
-	</para>
264
-	<example>
265
-	    <title>Set <varname>crl</varname> parameter</title>
266
-	    <programlisting>
267
-...
268
-modparam("tls", "crl", "/usr/local/etc/kamailio/crl.pem")
269
-...
270
-	    </programlisting>
271
-	</example>
272
-	</section>
273
-
274
-<section id="tls.p.verify_certificate">
275
-	<title><varname>verify_certificate</varname> (boolean)</title>
276
-	<para>
277
-		If enabled it will force certificate verification.
278
-		For more information see the <ulink url="http://www.openssl.org/docs/apps/verify.html">verify(1)</ulink> openssl man page.
279
-	</para>
280
-	<para>
281
-		Note: the certificate verification will always fail if the ca_list is empty.
282
-	</para>
283
-	<para>
284
-		See also: <varname>ca_list</varname>, <varname>require_certificate</varname>, <varname>verify_depth</varname>.
285
-	</para>
286
-	<para>
287
-		By default the certificate verification is off.
288
-	</para>
289
-	<example>
290
-	    <title>Set <varname>verify_certificate</varname> parameter</title>
291
-	    <programlisting>
292
-...
293
-modparam("tls", "verify_certificate", 1)
294
-...
295
-	    </programlisting>
296
-	</example>
297
-	</section>
298
-
299
-<section id="tls.p.verify_depth">
300
-	<title><varname>verify_depth</varname> (integer)</title>
301
-	<para>
302
-		Sets how far up the certificate chain will the certificate verification go in the search for a trusted CA.
303
-	</para>
304
-	<para>
305
-		See also: <varname>ca_list</varname>, <varname>require_certificate</varname>, <varname>verify_certificate</varname>,
306
-	</para>
307
-	<para>
308
-		The default value is 9.
309
-	</para>
310
-	<example>
311
-	    <title>Set <varname>verify_depth</varname> parameter</title>
312
-	    <programlisting>
313
-...
314
-modparam("tls", "verify_depth", 9)
315
-...
316
-	    </programlisting>
317
-	</example>
318
-	</section>
319
-
320
-<section id="tls.p.require_certificate">
321
-	<title><varname>require_certificate</varname> (boolean)</title>
322
-	<para>
323
-		When enabled it will require a certificate from a client. If the client does not offer a certificate
324
-		and <varname>verify_certificate</varname> is on, certificate verification will fail.
325
-	</para>
326
-	<para>
327
-		The default value is off.
328
-	</para>
329
-	<example>
330
-	    <title>Set <varname>require_certificate</varname> parameter</title>
331
-	    <programlisting>
332
-...
333
-modparam("tls", "require_certificate", 1)
334
-...
335
-	    </programlisting>
336
-	</example>
337
-	</section>
338
-
339
-<section id="tls.p.cipher_list">
340
-	<title><varname>cipher_list</varname> (string)</title>
341
-	<para>
342
-		Sets the list of accepted ciphers. The list consists of cipher strings separated by colons.
343
-		For more information on the cipher list format see the
344
-		<ulink url="https://www.openssl.org/docs/manmaster/apps/ciphers.html">cipher(1)</ulink> openssl man page.
345
-	</para>
346
-	<para>
347
-		The default value is not set (all the Openssl supported ciphers are enabled).
348
-	</para>
349
-	<example>
350
-	    <title>Set <varname>cipher_list</varname> parameter</title>
351
-	    <programlisting>
352
-...
353
-modparam("tls", "cipher_list", "HIGH")
354
-...
355
-	    </programlisting>
356
-	</example>
357
-	</section>
358
-
359
-	<section id="tls.p.server_name">
360
-	<title><varname>server_name</varname> (string)</title>
361
-	<para>
362
-		Sets the Server Name Indication (SNI) value.
363
-	</para>
364
-	<para>
365
-		This is a TLS extension and is not working for old and obsoleted
366
-		SSL versions.
367
-	</para>
368
-	<para>
369
-		The default value is empty (not set).
370
-	</para>
371
-	<example>
372
-	    <title>Set <varname>server_name</varname> parameter</title>
373
-	    <programlisting>
374
-...
375
-modparam("tls", "server_name", "kamailio.org")
376
-...
377
-	    </programlisting>
378
-	</example>
379
-	</section>
380
-
381
-	<section id="tls.p.send_timeout">
382
-	<title><varname>send_timeout</varname> (int)</title>
383
-	<para>
384
-		This parameter is <emphasis>obsolete</emphasis> and cannot be used
385
-		in newer TLS versions (&gt; &kamailio; 3.0). In these versions the
386
-		send_timeout is replaced by <varname>tcp_send_timeout</varname>
387
-		(common with all the tcp connections).
388
-	</para>
389
-	</section>
390
-
391
-	<section id="tls.p.handshake_timeout">
392
-	<title><varname>handshake_timeout</varname> (int)</title>
393
-	<para>
394
-		This parameter is <emphasis>obsolete</emphasis> and cannot be used
395
-		in newer TLS versions (&gt; &kamailio; 3.0). In these versions the
396
-		handshake_timeout is replaced by <varname>tcp_connect_timeout</varname>
397
-		(common with all the tcp connections).
398
-	</para>
399
-	</section>
400
-
401
-	<section id="tls.p.connection_timeout">
402
-	<title><varname>connection_timeout</varname> (int)</title>
403
-	<para>
404
-		Sets the amount of time after which an idle TLS connection will be
405
-		closed, if no I/O ever occurred after the initial open. If an I/O event
406
-		occurs, the timeout will be extended with tcp_connection_lifetime.
407
-		The value is expressed in seconds.
408
-	</para>
409
-	<para>
410
-		The default value is 10 min.
411
-	</para>
412
-	<para>
413
-		If the value set is -1, the connection will never be close on idle.
414
-	</para>
415
-	<para>
416
-		This setting can be changed also at runtime, via the RPC interface and config
417
-		framework. The config variable name is tls.connection_timeout.
418
-	</para>
419
-	<example>
420
-	    <title>Set <varname>connection_timeout</varname> parameter</title>
421
-	    <programlisting>
422
-...
423
-modparam("tls", "connection_timeout", 60)
424
-...
425
-	    </programlisting>
426
-	</example>
427
-	<example>
428
-		<title>Set <varname>tls.connection_timeout</varname> at runtime</title>
429
-		<programlisting>
430
- $ &sercmd; cfg.set_now_int tls connection_timeout 180
431
-		</programlisting>
432
-	</example>
433
-	</section>
434
-
435
-	<section id="tls.p.tls_disable_compression">
436
-	<title><varname>tls_disable_compression</varname> (boolean)</title>
437
-	<para>
438
-		If set compression over TLS will be disabled.
439
-		Note that compression uses a lot of memory (about 10x more then with
440
-		the compression disabled), so if you want to minimize
441
-		memory usage is a good idea to disable it.
442
-	</para>
443
-	<para>
444
-		By default compression is disabled.
445
-	</para>
446
-	<example>
447
-	    <title>Set <varname>tls_disable_compression</varname> parameter</title>
448
-	    <programlisting>
449
-...
450
-modparam("tls", "tls_disable_compression", 0) # enable
451
-...
452
-	    </programlisting>
453
-	</example>
454
-	</section>
455
-
456
-
457
-<section id="tls.p.ssl_release_buffers">
458
-	<title><varname>ssl_release_buffers</varname> (integer)</title>
459
-	<para>
460
-		Release internal OpenSSL read or write buffers as soon as they are
461
-		no longer needed. Combined with
462
-		<varname>ssl_freelist_max_len</varname> has the potential of saving
463
-		a lot of memory ( ~ 32k per connection in the default configuration,
464
-		or 16k + <varname>ssl_max_send_fragment</varname>).
465
-		For &kamailio; versions &gt; 3.0 it makes little sense to disable it (0)
466
-		since the tls module already has its own internal buffering.
467
-	</para>
468
-	<para>
469
-		A value of -1 would not change this option from its openssl default.
470
-		Use 0 or 1 for enable/disable.
471
-	</para>
472
-	<para>
473
-		By default the value is 1 (enabled).
474
-	</para>
475
-	<note>
476
-		<para>
477
-			This option is supported only for
478
-			OpenSSL versions >= <emphasis>1.0.0</emphasis>.
479
-			On all the other versions attempting
480
-			to change the default will trigger an error.
481
-		</para>
482
-	</note>
483
-	<example>
484
-	    <title>Set <varname>ssl_release_buffers</varname> parameter</title>
485
-	    <programlisting>
486
-modparam("tls", "ssl_release_buffers", 1)
487
-	    </programlisting>
488
-	</example>
489
-	</section>
490
-
491
-
492
-<section id="tls.p.ssl_freelist_max_len">
493
-	<title><varname>ssl_freelist_max_len</varname> (integer)</title>
494
-	<para>
495
-		Sets the maximum number of free memory chunks, that OpenSSL will keep
496
-		per connection. Setting it to 0 would cause any unused memory chunk
497
-		to be immediately freed, reducing the memory footprint. A too large
498
-		value would result in extra memory consumption.
499
-	</para>
500
-	<para>
501
-		Should be combined with <varname>ssl_release_buffers</varname>.
502
-	</para>
503
-	<para>
504
-		A value of -1 has a special meaning: the OpenSSL default will be used
505
-		(no attempt on changing the value will be made). For OpenSSL 1.0
506
-		the internal default is 32.
507
-	</para>
508
-	<para>
509
-		By default the value is 0 (no freelist).
510
-	</para>
511
-	<note>
512
-		<para>
513
-			This option is supported only for
514
-			OpenSSL versions >= <emphasis>1.0.0</emphasis>.
515
-			On all the other versions attempting
516
-			to change the default will trigger an error.
517
-		</para>
518
-	</note>
519
-	<example>
520
-		<title>Set <varname>ssl_freelist_max_len</varname> parameter</title>
521
-		<programlisting>
522
-modparam("tls", "ssl_freelist_max_len", 0)
523
-		</programlisting>
524
-	</example>
525
-	</section>
526
-
527
-
528
-<section id="tls.p.ssl_max_send_fragment">
529
-	<title><varname>ssl_max_send_fragment</varname> (integer)</title>
530
-	<para>
531
-		Sets the maximum number of bytes (from the clear text) sent into
532
-		one TLS or SSL record. Valid values are between 512 and 16384.
533
-		Note however that even valid low values might not be big enough to
534
-		allow a succesfull handshake (try minimum 1024).
535
-	</para>
536
-	<para>
537
-		Lower values would lead to less memory usage, but values lower then
538
-		the typical &kamailio; write size would incur a slight performance
539
-		penalty. Good values are bigger then the  size of the biggest
540
-		SIP packet one normally expects to forward. For example in most
541
-		setups 2048 would be a good value.
542
-	</para>
543
-	<note>
544
-		<para>
545
-			Values on the lower side, even if valid (> 512), might not allow
546
-			for a succesfull initial handshake. This happens if the
547
-			certificate does not fit inside one send fragment.
548
-			Values lower then 1024 should not be used.
549
-			Even with higher values, if the handshake fails,
550
-			try increasing the value.
551
-		</para>
552
-	</note>
553
-	<para>
554
-		A value of -1 has a special meaning: the OpenSSL default will be used
555
-		(no attempt on changing the value will be made).
556
-	</para>
557
-	<para>
558
-		By default the value is -1 (the OpenSSL default, which at least in
559
-		OpenSSL 1.0.0 is ~ 16k).
560
-	</para>
561
-	<note>
562
-		<para>
563
-			This option is supported only for
564
-			OpenSSL versions >= <emphasis>0.9.9</emphasis>.
565
-			On all the other versions attempting
566
-			to change the default will trigger an error.
567
-		</para>
568
-	</note>
569
-	<example>
570
-		<title>Set <varname>ssl_max_send_fragment</varname> parameter</title>
571
-		<programlisting>
572
-modparam("tls", "ssl_max_send_fragment", 4096)
573
-		</programlisting>
574
-	</example>
575
-	</section>
576
-
577
-
578
-<section id="tls.p.ssl_read_ahead">
579
-	<title><varname>ssl_read_ahead</varname> (boolean)</title>
580
-	<para>
581
-		Enables read ahead, reducing the number of internal OpenSSL BIO read()
582
-		calls. This option has only debugging value, in normal circumstances
583
-		it should not be changed from the default.
584
-	</para>
585
-	<para>
586
-		When disabled OpenSSL will make at least 2 BIO read() calls per
587
-		received record: one to get the record header and one to get the
588
-		rest of the record.
589
-	</para>
590
-	<para>
591
-		The TLS module buffers internally all read()s and defines its own fast
592
-		BIO so enabling this option would only cause more memory consumption
593
-		and a minor slow-down (extra memcpy).
594
-	</para>
595
-	<para>
596
-		A value of -1 has a special meaning: the OpenSSL default will be used
597
-		(no attempt on changing the value will be made).
598
-	</para>
599
-	<para>
600
-		By default the value is 0 (disabled).
601
-	</para>
602
-	<example>
603
-		<title>Set <varname>ssl_read_ahead</varname> parameter</title>
604
-		<programlisting>
605
-modparam("tls", "ssl_read_ahead", 1)
606
-		</programlisting>
607
-	</example>
608
-	</section>
609
-
610
-
611
-	<section id="tls.p.send_close_notify">
612
-	<title><varname>send_close_notify</varname> (boolean)</title>
613
-	<para>
614
-		Enables/disables sending close notify alerts prior to closing the
615
-		corresponding TCP connection.  Sending the close notify prior to TCP
616
-		shutdown is "nicer" from a TLS point of view, but it has a measurable
617
-		performance impact. Default: off. Can be set at runtime
618
-		(tls.send_close_notify).
619
-	</para>
620
-	<para>
621
-		The default value is 0 (off).
622
-	</para>
623
-	<para>
624
-		It can be changed also at runtime, via the RPC interface and config
625
-		framework. The config variable name is tls.send_close_notify.
626
-	</para>
627
-	<example>
628
-	    <title>Set <varname>send_close_notify</varname> parameter</title>
629
-	    <programlisting>
630
-...
631
-modparam("tls", "send_close_notify", 1)
632
-...
633
-	    </programlisting>
634
-	</example>
635
-	<example>
636
-		<title>Set <varname>tls.send_close_notify</varname> at runtime</title>
637
-		<programlisting>
638
- $ &sercmd; cfg.set_now_int tls send_close_notify 1
639
-		</programlisting>
640
-	</example>
641
-	</section>
642
-
643
-
644
-	<section id="tls.p.con_ct_wq_max">
645
-	<title><varname>con_ct_wq_max</varname> (integer)</title>
646
-	<para>
647
-		Sets the maximum allowed per connection clear-text send queue size in
648
-		bytes. This queue is used when data cannot be encrypted and sent
649
-		immediately because of an ongoing TLS/SSL level renegotiation.
650
-	</para>
651
-	<para>
652
-		The default value is 65536 (64 Kb).
653
-	</para>
654
-	<para>
655
-		It can be changed also at runtime, via the RPC interface and config
656
-		framework. The config variable name is tls.con_ct_wq_max.
657
-	</para>
658
-	<example>
659
-	    <title>Set <varname>con_ct_wq_max</varname> parameter</title>
660
-	    <programlisting>
661
-...
662
-modparam("tls", "con_ct_wq_max", 1048576)
663
-...
664
-	    </programlisting>
665
-	</example>
666
-	<example>
667
-		<title>Set <varname>tls.con_ct_wq_max</varname> at runtime</title>
668
-		<programlisting>
669
- $ &sercmd; cfg.set_now_int tls con_ct_wq_max 1048576
670
-		</programlisting>
671
-	</example>
672
-	</section>
673
-
674
-
675
-	<section id="tls.p.ct_wq_max">
676
-	<title><varname>ct_wq_max</varname> (integer)</title>
677
-	<para>
678
-		Sets the maximum total number of bytes queued in all the clear-text
679
-		send queues.  These queues are used when data cannot be encrypted and
680
-		sent immediately because of an ongoing TLS level renegotiation.
681
-	</para>
682
-	<para>
683
-		The default value is 10485760 (10 Mb).
684
-	</para>
685
-	<para>
686
-		It can be changed also at runtime, via the RPC interface and config
687
-		framework. The config variable name is tls.ct_wq_max.
688
-	</para>
689
-	<example>
690
-	    <title>Set <varname>ct_wq_max</varname> parameter</title>
691
-	    <programlisting>
692
-...
693
-modparam("tls", "ct_wq_max", 4194304)
694
-...
695
-	    </programlisting>
696
-	</example>
697
-	<example>
698
-		<title>Set <varname>tls.ct_wq_max</varname> at runtime</title>
699
-		<programlisting>
700
- $ &sercmd; cfg.set_now_int tls ct_wq_max 4194304
701
-		</programlisting>
702
-	</example>
703
-	</section>
704
-
705
-
706
-	<section id="tls.p.ct_wq_blk_size">
707
-	<title><varname>ct_wq_blk_size</varname> (integer)</title>
708
-	<para>
709
-		Minimum block size for the internal clear-text send queues
710
-		(debugging / advanced tunning).
711
-		Good values are multiple of typical datagram sizes.
712
-	</para>
713
-	<para>
714
-		The default value is 4096.
715
-	</para>
716
-	<para>
717
-		It can be changed also at runtime, via the RPC interface and config
718
-		framework. The config variable name is tls.ct_wq_blk_size.
719
-	</para>
720
-	<example>
721
-	    <title>Set <varname>ct_wq_blk_size</varname> parameter</title>
722
-	    <programlisting>
723
-...
724
-modparam("tls", "ct_wq_blk_size", 2048)
725
-...
726
-	    </programlisting>
727
-	</example>
728
-	<example>
729
-		<title>Set <varname>tls.ct_wq_max</varname> at runtime</title>
730
-		<programlisting>
731
- $ &sercmd; cfg.set_now_int tls ct_wq_blk_size 2048
732
-		</programlisting>
733
-	</example>
734
-	</section>
735
-
736
-
737
-	<section id="tls.p.tls_log">
738
-	<title><varname>tls_log</varname> (int)</title>
739
-	<para>
740
-		Sets the log level at which TLS related messages will be logged.
741
-	</para>
742
-	<para>
743
-		The default value is 3 (L_DBG).
744
-	</para>
745
-	<para>
746
-		It can be changed also at runtime, via the RPC interface and config
747
-		framework. The config variable name is tls.log.
748
-	</para>
749
-	<example>
750
-		<title>Set <varname>tls_log</varname> parameter</title>
751
-		<programlisting>
752
-...
753
-# ignore TLS messages if Kamailio is started with debug less than 10
754
-modparam("tls", "tls_log", 10)
755
-...
756
-		</programlisting>
757
-	</example>
758
-	<example>
759
-		<title>Set <varname>tls.log</varname> at runtime</title>
760
-		<programlisting>
761
- $ &sercmd; cfg.set_now_int tls log 10
762
-		</programlisting>
763
-	</example>
764
-	</section>
765
-
766
-
767
-	<section id="tls.p.tls_debug">
768
-	<title><varname>tls_debug</varname> (int)</title>
769
-	<para>
770
-		Sets the log level at which TLS debug messages will be logged.
771
-		Note that TLS debug messages are enabled only if the TLS module
772
-		is compiled with debugging enabled (e.g. -DTLS_WR_DEBUG,
773
-		-DTLS_RD_DEBUG or -DTLS_BIO_DEBUG).
774
-	</para>
775
-	<para>
776
-		The default value is 3 (L_DBG).
777
-	</para>
778
-	<para>
779
-		It can be changed also at runtime, via the RPC interface and config
780
-		framework. The config variable name is tls.debug.
781
-	</para>
782
-	<example>
783
-		<title>Set <varname>tls_debug</varname> parameter</title>
784
-		<programlisting>
785
-...
786
-# ignore TLS debug messages if Kamailio is started with debug less than 10
787
-modparam("tls", "tls_debug", 10)
788
-...
789
-		</programlisting>
790
-	</example>
791
-	<example>
792
-		<title>Set <varname>tls.debug</varname> at runtime</title>
793
-		<programlisting>
794
- $ &sercmd; cfg.set_now_int tls debug 10
795
-		</programlisting>
796
-	</example>
797
-	</section>
798
-
799
-
800
-<section id="tls.p.low_mem_threshold1">
801
-	<title><varname>low_mem_threshold1</varname> (integer)</title>
802
-	<para>
803
-		Sets the minimal free memory from which attempts to open or accept
804
-		new TLS connections will start to fail. The value is expressed in KB.
805
-	</para>
806
-	<para>
807
-		The default value depends on whether the openssl library used handles well
808
-		low memory situations (openssl bug #1491).
809
-		As of this writing this is not true for any openssl version (including 0.9.8e).
810
-	</para>
811
-	<para>
812
-		If an ill-behaved OpenSSL version is detected, a very conservative value is choosed,
813
-		which depends on the maximum possible number of simultaneously created TLS connections
814
-		(and hence on the process number).
815
-	</para>
816
-	<para>
817
-		The following values have a special meaning:
818
-	</para>
819
-	<itemizedlist>
820
-			<listitem>
821
-				<para>
822
-					-1 - use the default value
823
-				</para>
824
-			</listitem>
825
-			<listitem>
826
-				<para>
827
-					0 - disable (TLS connections will not fail preemptively)
828
-				</para>
829
-			</listitem>
830
-	</itemizedlist>
831
-	<para>
832
-		It can be changed also at runtime, via the RPC interface and config
833
-		framework. The config variable name is tls.low_mem_threshold1.
834
-	</para>
835
-	<para>
836
-		See also <varname>low_mem_threshold2</varname>.
837
-	</para>
838
-	<example>
839
-		<title>Set <varname>low_mem_threshold1</varname> parameter</title>
840
-		<programlisting>
841
-...
842
-modparam("tls", "low_mem_threshold1", -1)
843
-...
844
-	</programlisting>
845
-	</example>
846
-	<example>
847
-		<title>Set <varname>tls.low_mem_threshold1</varname> at runtime</title>
848
-		<programlisting>
849
- $ &sercmd; cfg.set_now_int tls low_mem_threshold1 2048
850
-		</programlisting>
851
-	</example>
852
-	</section>
853
-
854
-<section id="tls.p.low_mem_threshold2">
855
-	<title><varname>low_mem_threshold2</varname> (integer)</title>
856
-	<para>
857
-		Sets the minimal free memory from which TLS operations on already established
858
-		TLS connections will start to fail preemptively.  The value is expressed in KB.
859
-	</para>
860
-	<para>
861
-		The default value depends on whether the OpenSSL library used handles well low memory
862
-		situations (openssl bug #1491). As of this writing this is not true for any OpenSSL version (including 0.9.8e).
863
-	</para>
864
-	<para>
865
-		If an ill-behaved openssl version is detected, a very conservative value is choosed,
866
-		which depends on the maximum possible number of simultaneously created TLS connections (and hence on the process number).
867
-	</para>
868
-	<para>
869
-		The following values have a special meaning:
870
-	</para>
871
-	<itemizedlist>
872
-			<listitem>
873
-				<para>
874
-					-1 - use the default value
875
-				</para>
876
-			</listitem>
877
-			<listitem>
878
-				<para>
879
-					0 - disable (TLS operations will not fail preemptively)
880
-				</para>
881
-			</listitem>
882
-	</itemizedlist>
883
-	<para>
884
-		It can be changed also at runtime, via the RPC interface and config
885
-		framework. The config variable name is tls.low_mem_threshold2.
886
-	</para>
887
-	<para>
888
-		See also <varname>low_mem_threshold1</varname>.
889
-	</para>
890
-	<example>
891
-		<title>Set <varname>low_mem_threshold2</varname> parameter</title>
892
-		<programlisting>
893
-...
894
-modparam("tls", "low_mem_threshold2", -1)
895
-...
896
-	</programlisting>
897