Browse code

tls: doc update w/ the new options

- docs updated with the new parameters description
(ssl_release_buffers, ssl_read_ahead, ssl_freelist_max_len,
ssl_max_send_fragment).
- README regenerated
- NEWS updated

Andrei Pelinescu-Onciul authored on 19/03/2010 14:26:45
Showing 3 changed files
... ...
@@ -37,6 +37,11 @@ modules:
37 37
             the mask for possible local replies to the current message.
38 38
            blst_rpl_clear_ignore(mask): like blst_rpl_ignore(mask), but
39 39
             clears instead of setting.
40
+   - tls:
41
+           new options for better tuning memory usage for modern openssl
42
+            versions: ssl_release_buffers, ssl_freelist_max_len,
43
+            ssl_max_send_fragment, ssl_read_ahead. For more info see
44
+            modules/doc/tls/README.
40 45
 tm:
41 46
    - t_reply() can be used both from the main/core onreply_route{} and tm
42 47
      onreply_route[...]{}s.
... ...
@@ -30,11 +30,15 @@ Andrei Pelinescu-Onciul
30 30
         1.8.10. handshake_timeout (int)
31 31
         1.8.11. connection_timeout (int)
32 32
         1.8.12. tls_disable_compression (boolean)
33
-        1.8.13. tls_log (int)
34
-        1.8.14. low_mem_threshold1 (integer)
35
-        1.8.15. low_mem_threshold2 (integer)
36
-        1.8.16. tls_force_run (boolean)
37
-        1.8.17. config (string)
33
+        1.8.13. ssl_release_buffers (integer)
34
+        1.8.14. ssl_free_list_max_len (integer)
35
+        1.8.15. ssl_max_send_fragment (integer)
36
+        1.8.16. ssl_read_ahead (boolean)
37
+        1.8.17. tls_log (int)
38
+        1.8.18. low_mem_threshold1 (integer)
39
+        1.8.19. low_mem_threshold2 (integer)
40
+        1.8.20. tls_force_run (boolean)
41
+        1.8.21. config (string)
38 42
 
39 43
    1.9. Functions
40 44
 
... ...
@@ -435,7 +439,9 @@ modparam("tls", "connection_timeout", 60)
435 439
 
436 440
 1.8.12. tls_disable_compression (boolean)
437 441
 
438
-   If set compression over SSL/TLS will be disabled.
442
+   If set compression over SSL/TLS will be disabled. Note that compression
443
+   uses a lot of memory, so if you want to minimize memory usage is a good
444
+   ideea to disable it.
439 445
 
440 446
    By default compression is enabled.
441 447
 
... ...
@@ -444,19 +450,115 @@ modparam("tls", "connection_timeout", 60)
444 450
 modparam("tls", "tls_disable_compression", 1)
445 451
 ...
446 452
 
447
-1.8.13. tls_log (int)
453
+1.8.13. ssl_release_buffers (integer)
454
+
455
+   Release internal OpenSSL read or write buffers as soon as they are no
456
+   longer needed. Combined with ssl_free_list_max_len has the potential of
457
+   saving a lot of memory ( ~ 32k per connection in the default
458
+   configuration, or 16k + ssl_max_send_fragment).
459
+
460
+   A value of -1 would not change this option from its openssl default.
461
+   Use 0 or 1 for enable/disable.
462
+
463
+   By default the value is -1 (the openssl default, which at least in
464
+   openssl 1.0.0 is 0/disabled).
465
+
466
+Note
467
+
468
+   This option is supported only for OpenSSL versions >= 1.0.0. On all the
469
+   other versions attempting to change the default will trigger an error.
470
+
471
+   Example 14. Set ssl_release_buffers parameter
472
+modparam("tls", "ssl_release_buffers", 1)
473
+
474
+1.8.14. ssl_free_list_max_len (integer)
475
+
476
+   Sets the maximum number of free memory chunks, that OpenSSL will keep
477
+   per connection. Setting it to 0 would cause any unused memory chunk to
478
+   be immediately freed, reducing the memory footprint. A too large value
479
+   would result in extra memory consumption.
480
+
481
+   Should be combined with ssl_release_buffers.
482
+
483
+   A value of -1 has a special meaning: the OpenSSL default will be used
484
+   (no attempt on changing the value will be made).
485
+
486
+   By default the value is -1 (the OpenSSL default, which at least in
487
+   OpenSSL 1.0.0 is 32).
488
+
489
+Note
490
+
491
+   This option is supported only for OpenSSL versions >= 1.0.0. On all the
492
+   other versions attempting to change the default will trigger an error.
493
+
494
+   Example 15. Set ssl_freelist_max_len parameter
495
+modparam("tls", "ssl_freelist_max_len", 0)
496
+
497
+1.8.15. ssl_max_send_fragment (integer)
498
+
499
+   Sets the maximum number of bytes (from the clear text) sent into one
500
+   TLS or SSL record. Valid values are between 512 and 16384. Note however
501
+   that even valid low values might not be big enough to allow a
502
+   succesfull handshake (try minimum 1024).
503
+
504
+   Lower values would lead to less memory usage, but values lower then the
505
+   typical ser/sip-router write size would incur a slight performance
506
+   penalty. Good values are bigger then the size of the biggest SIP packet
507
+   one normally expects to forward. For example in most setups 2048 would
508
+   be a good value.
509
+
510
+Note
511
+
512
+   Values on the lower side, even if valid (> 512), might not allow for a
513
+   succesfull initial handshake. This happens if the certificate does not
514
+   fit inside one send fragment. Values lower then 1024 should not be
515
+   used. Even with higher values, if the handshake fails, try increasing
516
+   the value.
517
+
518
+   A value of -1 has a special meaning: the OpenSSL default will be used
519
+   (no attempt on changing the value will be made).
520
+
521
+   By default the value is -1 (the OpenSSL default, which at least in
522
+   OpenSSL 1.0.0 is ~ 16k).
523
+
524
+Note
525
+
526
+   This option is supported only for OpenSSL versions >= 0.9.9. On all the
527
+   other versions attempting to change the default will trigger an error.
528
+
529
+   Example 16. Set ssl_max_send_fragment parameter
530
+modparam("tls", "ssl_max_send_fragment", 4096)
531
+
532
+1.8.16. ssl_read_ahead (boolean)
533
+
534
+   Enables read ahead, reducing the number of read() system calls done
535
+   internally by the OpenSSL library.
536
+
537
+   When disabled OpenSSL will make at least 2 read() sytem calls per
538
+   received record: one to get the record header and one to get the rest
539
+   of the record.
540
+
541
+   A value of -1 has a special meaning: the OpenSSL default will be used
542
+   (no attempt on changing the value will be made).
543
+
544
+   By default the value is 1 (enabled).
545
+
546
+   Example 17. Set ssl_read_ahead parameter
547
+modparam("tls", "ssl_read_ahead", 1)
548
+
549
+1.8.17. tls_log (int)
448 550
 
449 551
    Sets the log level at which TLS related messages will be logged.
450 552
 
451 553
    The default value is 3.
452 554
 
453
-   Example 14. Set tls_log parameter
555
+   Example 18. Set tls_log parameter
454 556
 ...
455 557
 # ignore TLS messages if SIP-router is started with debug less than 10
456 558
 modparam("tls", "tls_log", 10)
457 559
 ...
458 560
 
459
-1.8.14. low_mem_threshold1 (integer)
561
+1.8.18. low_mem_threshold1 (integer)
460 562
 
461 563
    Sets the minimal free memory from which new TLS connection will start
462 564
    to fail. The value is expressed in KB.
... ...
@@ -476,12 +578,12 @@ modparam("tls", "tls_log", 10)
476 578
 
477 579
    See also low_mem_threshold2.
478 580
 
479
-   Example 15. Set low_mem_threshold1 parameter
581
+   Example 19. Set low_mem_threshold1 parameter
480 582
 ...
481 583
 modparam("tls", "low_mem_threshold1", -1)
482 584
 ...
483 585
 
484
-1.8.15. low_mem_threshold2 (integer)
586
+1.8.19. low_mem_threshold2 (integer)
485 587
 
486 588
    Sets the minimal free memory from which TLS operations on already
487 589
    established TLS connections will start to fail preemptively. The value
... ...
@@ -502,12 +604,12 @@ modparam("tls", "low_mem_threshold1", -1)
502 604
 
503 605
    See also low_mem_threshold1.
504 606
 
505
-   Example 16. Set low_mem_threshold2 parameter
607
+   Example 20. Set low_mem_threshold2 parameter
506 608
 ...
507 609
 modparam("tls", "low_mem_threshold2", -1)
508 610
 ...
509 611
 
510
-1.8.16. tls_force_run (boolean)
612
+1.8.20. tls_force_run (boolean)
511 613
 
512 614
    If enabled SIP-router will start even if some of the openssl sanity
513 615
    checks fail (turn it on at your own risk).
... ...
@@ -523,12 +625,12 @@ modparam("tls", "low_mem_threshold2", -1)
523 625
 
524 626
    By default tls_force_run is disabled.
525 627
 
526
-   Example 17. Set tls_force_run parameter
628
+   Example 21. Set tls_force_run parameter
527 629
 ...
528 630
 modparam("tls", "tls_force_run", 11)
529 631
 ...
530 632
 
531
-1.8.17. config (string)
633
+1.8.21. config (string)
532 634
 
533 635
    Sets the name of the TLS specific config file.
534 636
 
... ...
@@ -554,7 +656,7 @@ modparam("tls", "tls_force_run", 11)
554 656
    client when it initiates a new connection by itself (it connects to
555 657
    something).
556 658
 
557
-   Example 18. Short config file
659
+   Example 22. Short config file
558 660
 [server:default]
559 661
 method = TLSv1
560 662
 verify_certificate = no
... ...
@@ -580,7 +682,7 @@ ca_list = local_ca.pem
580 682
    For a more complete example check the tls.cfg distributed with the
581 683
    SIP-router source (sip_router/modules/tls/tls.cfg).
582 684
 
583
-   Example 19. Set config parameter
685
+   Example 23. Set config parameter
584 686
 ...
585 687
 modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
586 688
 ...
... ...
@@ -596,7 +698,7 @@ modparam("tls", "config", "/usr/local/etc/ser/tls.cfg")
596 698
    , the peer presented an X509 certificate and the certificate chain
597 699
    verified ok. It can be used only in a request route.
598 700
 
599
-   Example 20. is_peer_verified usage
701
+   Example 24. is_peer_verified usage
600 702
         if (proto==TLS && !is_peer_verified()){
601 703
                 sl_send_reply("400", "No certificate or verification failed");
602 704
                 drop;
... ...
@@ -259,6 +259,8 @@ modparam("tls", "connection_timeout", 60)
259 259
 	<title><varname>tls_disable_compression</varname> (boolean)</title>
260 260
 	<para>
261 261
 		If set compression over SSL/TLS will be disabled.
262
+		Note that compression uses a lot of memory, so if you want to minimize
263
+		memory usage is a good ideea to disable it.
262 264
 	</para>
263 265
 	<para>
264 266
 		By default compression is enabled.
... ...
@@ -273,6 +275,154 @@ modparam("tls", "tls_disable_compression", 1)
273 275
 	</example>
274 276
 	</section>
275 277
 
278
+
279
+<section id="ssl_release_buffers">
280
+	<title><varname>ssl_release_buffers</varname> (integer)</title>
281
+	<para>
282
+		Release internal OpenSSL read or write buffers as soon as they are
283
+		no longer needed. Combined with
284
+		<varname>ssl_free_list_max_len</varname> has the potential of saving
285
+		a lot of memory ( ~ 32k per connection in the default configuration,
286
+		or 16k + <varname>ssl_max_send_fragment</varname>).
287
+	</para>
288
+	<para>
289
+		A value of -1 would not change this option from its openssl default.
290
+		Use 0 or 1 for enable/disable.
291
+	</para>
292
+	<para>
293
+		By default the value is -1 (the openssl default, which at least in
294
+		openssl 1.0.0 is 0/disabled).
295
+	</para>
296
+	<note>
297
+		<para>
298
+			This option is supported only for
299
+			OpenSSL versions >= <emphasis>1.0.0</emphasis>.
300
+			On all the other versions attempting
301
+			to change the default will trigger an error.
302
+		</para>
303
+	</note>
304
+	<example>
305
+	    <title>Set <varname>ssl_release_buffers</varname> parameter</title>
306
+	    <programlisting>
307
+modparam("tls", "ssl_release_buffers", 1)
308
+	    </programlisting>
309
+	</example>
310
+	</section>
311
+
312
+
313
+<section id="ssl_freelist_max_len">
314
+	<title><varname>ssl_free_list_max_len</varname> (integer)</title>
315
+	<para>
316
+		Sets the maximum number of free memory chunks, that OpenSSL will keep
317
+		per connection. Setting it to 0 would cause any unused memory chunk
318
+		to be immediately freed, reducing the memory footprint. A too large
319
+		value would result in extra memory consumption.
320
+	</para>
321
+	<para>
322
+		Should be combined with <varname>ssl_release_buffers</varname>.
323
+	</para>
324
+	<para>
325
+		A value of -1 has a special meaning: the OpenSSL default will be used
326
+		(no attempt on changing the value will be made).
327
+	</para>
328
+	<para>
329
+		By default the value is -1 (the OpenSSL default, which at least in
330
+		OpenSSL 1.0.0 is 32).
331
+	</para>
332
+	<note>
333
+		<para>
334
+			This option is supported only for
335
+			OpenSSL versions >= <emphasis>1.0.0</emphasis>.
336
+			On all the other versions attempting
337
+			to change the default will trigger an error.
338
+		</para>
339
+	</note>
340
+	<example>
341
+		<title>Set <varname>ssl_freelist_max_len</varname> parameter</title>
342
+		<programlisting>
343
+modparam("tls", "ssl_freelist_max_len", 0)
344
+		</programlisting>
345
+	</example>
346
+	</section>
347
+
348
+
349
+<section id="ssl_max_send_fragment">
350
+	<title><varname>ssl_max_send_fragment</varname> (integer)</title>
351
+	<para>
352
+		Sets the maximum number of bytes (from the clear text) sent into
353
+		one TLS or SSL record. Valid values are between 512 and 16384.
354
+		Note however that even valid low values might not be big enough to
355
+		allow a succesfull handshake (try minimum 1024).
356
+	</para>
357
+	<para>
358
+		Lower values would lead to less memory usage, but values lower then
359
+		the typical ser/sip-router write size would incur a slight performance
360
+		penalty. Good values are bigger then the  size of the biggest
361
+		SIP packet one normally expects to forward. For example in most
362
+		setups 2048 would be a good value.
363
+	</para>
364
+	<note>
365
+		<para>
366
+			Values on the lower side, even if valid (> 512), might not allow
367
+			for a succesfull initial handshake. This happens if the
368
+			certificate does not fit inside one send fragment.
369
+			Values lower then 1024 should not be used.
370
+			Even with higher values, if the handshake fails,
371
+			try increasing the value.
372
+		</para>
373
+	</note>
374
+	<para>
375
+		A value of -1 has a special meaning: the OpenSSL default will be used
376
+		(no attempt on changing the value will be made).
377
+	</para>
378
+	<para>
379
+		By default the value is -1 (the OpenSSL default, which at least in
380
+		OpenSSL 1.0.0 is ~ 16k).
381
+	</para>
382
+	<note>
383
+		<para>
384
+			This option is supported only for
385
+			OpenSSL versions >= <emphasis>0.9.9</emphasis>.
386
+			On all the other versions attempting
387
+			to change the default will trigger an error.
388
+		</para>
389
+	</note>
390
+	<example>
391
+		<title>Set <varname>ssl_max_send_fragment</varname> parameter</title>
392
+		<programlisting>
393
+modparam("tls", "ssl_max_send_fragment", 4096)
394
+		</programlisting>
395
+	</example>
396
+	</section>
397
+
398
+
399
+<section id="ssl_read_ahead">
400
+	<title><varname>ssl_read_ahead</varname> (boolean)</title>
401
+	<para>
402
+		Enables read ahead, reducing the number of read() system calls
403
+		done internally by the OpenSSL library.
404
+	</para>
405
+	<para>
406
+		When disabled OpenSSL will make at least 2 read() sytem calls per
407
+		received record: one to get the record header and one to get the
408
+		rest of the record.
409
+	</para>
410
+	<para>
411
+		A value of -1 has a special meaning: the OpenSSL default will be used
412
+		(no attempt on changing the value will be made).
413
+	</para>
414
+	<para>
415
+		By default the value is 1 (enabled).
416
+	</para>
417
+	<example>
418
+		<title>Set <varname>ssl_read_ahead</varname> parameter</title>
419
+		<programlisting>
420
+modparam("tls", "ssl_read_ahead", 1)
421
+		</programlisting>
422
+	</example>
423
+	</section>
424
+
425
+
276 426
 	<section id="tls_log">
277 427
 	<title><varname>tls_log</varname> (int)</title>
278 428
 	<para>
... ...
@@ -292,6 +442,7 @@ modparam("tls", "tls_log", 10)
292 442
 	</example>
293 443
 	</section>
294 444
 
445
+
295 446
 <section id="low_mem_threshold1">
296 447
 	<title><varname>low_mem_threshold1</varname> (integer)</title>
297 448
 	<para>