external/ibm-public/postfix/dist/html/tlsmgr.8.html

   1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
   2         "http://www.w3.org/TR/html4/loose.dtd">
   3 <html> <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
   5 <title> Postfix manual - tlsmgr(8) </title>
   6 </head> <body> <pre>
   7 TLSMGR(8)                                                            TLSMGR(8)
   8
   9 <b>NAME</b>
  10        tlsmgr - Postfix TLS session cache and PRNG manager
  11
  12 <b>SYNOPSIS</b>
  13        <b>tlsmgr</b> [generic Postfix daemon options]
  14
  15 <b>DESCRIPTION</b>
  16        The  <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> manages the Postfix TLS session caches.  It
  17        stores and retrieves cache entries on request by  <a href="smtpd.8.html"><b>smtpd</b>(8)</a>
  18        and  <a href="smtp.8.html"><b>smtp</b>(8)</a>  processes,  and periodically removes entries
  19        that have expired.
  20
  21        The <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> also manages the PRNG (pseudo random  number
  22        generator)  pool.  It  answers queries by the <a href="smtpd.8.html"><b>smtpd</b>(8)</a> and
  23        <a href="smtp.8.html"><b>smtp</b>(8)</a> processes to seed their internal PRNG pools.
  24
  25        The <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a>'s PRNG pool  is  initially  seeded  from  an
  26        external  source (EGD, /dev/urandom, or regular file).  It
  27        is updated at configurable  pseudo-random  intervals  with
  28        data  from the external source. It is updated periodically
  29        with data from TLS session cache entries and with the time
  30        of  day,  and  is  updated with the time of day whenever a
  31        process requests <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> service.
  32
  33        The <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> saves the PRNG state  to  an  exchange  file
  34        periodically  and  when  the process terminates, and reads
  35        the exchange file when initializing its PRNG.
  36
  37 <b>SECURITY</b>
  38        The <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> is not  security-sensitive.  The  code  that
  39        maintains  the  external  and internal PRNG pools does not
  40        "trust" the data that it manipulates, and  the  code  that
  41        maintains  the  TLS  session cache does not touch the con-
  42        tents of the cached entries, except for seeding its inter-
  43        nal PRNG pool.
  44
  45        The  <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> can be run chrooted and with reduced privi-
  46        leges.  At process startup  it  connects  to  the  entropy
  47        source  and  exchange  file,  and creates or truncates the
  48        optional TLS session cache files.
  49
  50        With Postfix version  2.5  and  later,  the  <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a>  no
  51        longer  uses  root  privileges  when  opening cache files.
  52        These files should now be stored under  the  Postfix-owned
  53        <b><a href="postconf.5.html#data_directory">data_directory</a></b>.   As a migration aid, an attempt to open a
  54        cache file under a non-Postfix directory is redirected  to
  55        the Postfix-owned <b><a href="postconf.5.html#data_directory">data_directory</a></b>, and a warning is logged.
  56
  57 <b>DIAGNOSTICS</b>
  58        Problems and transactions are logged to the syslog daemon.
  59
  60 <b>BUGS</b>
  61        There is no automatic means to limit the number of entries
  62        in the TLS session caches and/or the size of the TLS cache
  63        files.
  64
  65 <b>CONFIGURATION PARAMETERS</b>
  66        Changes  to  <a href="postconf.5.html"><b>main.cf</b></a>  are  not  picked  up  automatically,
  67        because <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> is a persistent processes.  Use the com-
  68        mand "<b>postfix reload</b>" after a configuration change.
  69
  70        The  text  below  provides  only  a parameter summary. See
  71        <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
  72
  73 <b>TLS SESSION CACHE</b>
  74        <b><a href="postconf.5.html#lmtp_tls_loglevel">lmtp_tls_loglevel</a> (0)</b>
  75               The LMTP-specific version of the  <a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a>
  76               configuration parameter.
  77
  78        <b><a href="postconf.5.html#lmtp_tls_session_cache_database">lmtp_tls_session_cache_database</a> (empty)</b>
  79               The  LMTP-specific  version  of  the  smtp_tls_ses-
  80               sion_cache_database configuration parameter.
  81
  82        <b><a href="postconf.5.html#lmtp_tls_session_cache_timeout">lmtp_tls_session_cache_timeout</a> (3600s)</b>
  83               The  LMTP-specific  version  of  the  smtp_tls_ses-
  84               sion_cache_timeout configuration parameter.
  85
  86        <b><a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> (0)</b>
  87               Enable  additional  Postfix  SMTP client logging of
  88               TLS activity.
  89
  90        <b><a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> (empty)</b>
  91               Name of the file containing  the  optional  Postfix
  92               SMTP client TLS session cache.
  93
  94        <b><a href="postconf.5.html#smtp_tls_session_cache_timeout">smtp_tls_session_cache_timeout</a> (3600s)</b>
  95               The expiration time of Postfix SMTP client TLS ses-
  96               sion cache information.
  97
  98        <b><a href="postconf.5.html#smtpd_tls_loglevel">smtpd_tls_loglevel</a> (0)</b>
  99               Enable additional Postfix SMTP  server  logging  of
 100               TLS activity.
 101
 102        <b><a href="postconf.5.html#smtpd_tls_session_cache_database">smtpd_tls_session_cache_database</a> (empty)</b>
 103               Name  of  the  file containing the optional Postfix
 104               SMTP server TLS session cache.
 105
 106        <b><a href="postconf.5.html#smtpd_tls_session_cache_timeout">smtpd_tls_session_cache_timeout</a> (3600s)</b>
 107               The expiration time of Postfix SMTP server TLS ses-
 108               sion cache information.
 109
 110 <b>PSEUDO RANDOM NUMBER GENERATOR</b>
 111        <b><a href="postconf.5.html#tls_random_source">tls_random_source</a> (see 'postconf -d' output)</b>
 112               The  external  entropy  source  for  the  in-memory
 113               <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> pseudo  random  number  generator  (PRNG)
 114               pool.
 115
 116        <b><a href="postconf.5.html#tls_random_bytes">tls_random_bytes</a> (32)</b>
 117               The  number  of  bytes  that  <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a>  reads from
 118               $<a href="postconf.5.html#tls_random_source">tls_random_source</a> when (re)seeding  the  in-memory
 119               pseudo random number generator (PRNG) pool.
 120
 121        <b><a href="postconf.5.html#tls_random_exchange_name">tls_random_exchange_name</a> (see 'postconf -d' output)</b>
 122               Name  of  the pseudo random number generator (PRNG)
 123               state file that is maintained by <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a>.
 124
 125        <b><a href="postconf.5.html#tls_random_prng_update_period">tls_random_prng_update_period</a> (3600s)</b>
 126               The time between attempts by <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> to save  the
 127               state  of the pseudo random number generator (PRNG)
 128               to    the    file    specified    with    $<a href="postconf.5.html#tls_random_exchange_name">tls_ran</a>-
 129               <a href="postconf.5.html#tls_random_exchange_name">dom_exchange_name</a>.
 130
 131        <b><a href="postconf.5.html#tls_random_reseed_period">tls_random_reseed_period</a> (3600s)</b>
 132               The  maximal  time between attempts by <a href="tlsmgr.8.html"><b>tlsmgr</b>(8)</a> to
 133               re-seed the in-memory pseudo random number  genera-
 134               tor (PRNG) pool from external sources.
 135
 136 <b>MISCELLANEOUS CONTROLS</b>
 137        <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
 138               The  default  location  of  the Postfix <a href="postconf.5.html">main.cf</a> and
 139               <a href="master.5.html">master.cf</a> configuration files.
 140
 141        <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b>
 142               The directory with Postfix-writable data files (for
 143               example: caches, pseudo-random numbers).
 144
 145        <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
 146               How  much time a Postfix daemon process may take to
 147               handle a request  before  it  is  terminated  by  a
 148               built-in watchdog timer.
 149
 150        <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
 151               The  process  ID  of  a  Postfix  command or daemon
 152               process.
 153
 154        <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
 155               The process name of a  Postfix  command  or  daemon
 156               process.
 157
 158        <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
 159               The syslog facility of Postfix logging.
 160
 161        <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
 162               The  mail  system  name  that  is  prepended to the
 163               process name in syslog  records,  so  that  "smtpd"
 164               becomes, for example, "postfix/smtpd".
 165
 166 <b>SEE ALSO</b>
 167        <a href="smtp.8.html">smtp(8)</a>, Postfix SMTP client
 168        <a href="smtpd.8.html">smtpd(8)</a>, Postfix SMTP server
 169        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 170        <a href="master.5.html">master(5)</a>, generic daemon options
 171        <a href="master.8.html">master(8)</a>, process manager
 172        syslogd(8), system logging
 173
 174 <b>README FILES</b>
 175        <a href="TLS_README.html">TLS_README</a>, Postfix TLS configuration and operation
 176
 177 <b>LICENSE</b>
 178        The Secure Mailer license must be  distributed  with  this
 179        software.
 180
 181 <b>AUTHOR(S)</b>
 182        Lutz Jaenicke
 183        BTU Cottbus
 184        Allgemeine Elektrotechnik
 185        Universitaetsplatz 3-4
 186        D-03044 Cottbus, Germany
 187
 188        Adapted by:
 189        Wietse Venema
 190        IBM T.J. Watson Research
 191        P.O. Box 704
 192        Yorktown Heights, NY 10598, USA
 193
 194                                                                      TLSMGR(8)
 195 </pre> </body> </html>