postfix-master/proxymap.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 - proxymap(8) </title>
   6 </head> <body> <pre>
   7 PROXYMAP(8)                                                        PROXYMAP(8)
   8
   9 <b>NAME</b>
  10        proxymap - Postfix lookup table proxy server
  11
  12 <b>SYNOPSIS</b>
  13        <b>proxymap</b> [generic Postfix daemon options]
  14
  15 <b>DESCRIPTION</b>
  16        The  <a href="proxymap.8.html"><b>proxymap</b>(8)</a>  server  provides read-only or read-write
  17        table lookup service to Postfix processes. These  services
  18        are  implemented with distinct service names: <b>proxymap</b> and
  19        <b>proxywrite</b>, respectively. The purpose  of  these  services
  20        is:
  21
  22        <b>o</b>      To  overcome  chroot  restrictions.  For example, a
  23               chrooted SMTP server needs  access  to  the  system
  24               passwd  file  in order to reject mail for non-exis-
  25               tent local addresses, but it is  not  practical  to
  26               maintain  a  copy  of the passwd file in the chroot
  27               jail.  The solution:
  28
  29               <a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> =
  30                   <a href="proxymap.8.html">proxy</a>:unix:passwd.byname $<a href="postconf.5.html#alias_maps">alias_maps</a>
  31
  32        <b>o</b>      To consolidate the number of open lookup tables  by
  33               sharing  one  open  table among multiple processes.
  34               For example, making mysql  connections  from  every
  35               Postfix daemon process results in "too many connec-
  36               tions" errors. The solution:
  37
  38               <a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> =
  39                   <a href="proxymap.8.html">proxy</a>:<a href="mysql_table.5.html">mysql</a>:/etc/postfix/virtual_alias.cf
  40
  41               The total number of connections is limited  by  the
  42               number of proxymap server processes.
  43
  44        <b>o</b>      To  provide single-updater functionality for lookup
  45               tables that do not reliably support multiple  writ-
  46               ers (i.e. all file-based tables).
  47
  48        The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server implements the following requests:
  49
  50        <b>open</b> <i>maptype:mapname flags</i>
  51               Open  the table with type <i>maptype</i> and name <i>mapname</i>,
  52               as controlled by <i>flags</i>. The reply includes the <i>map-</i>
  53               <i>type</i> dependent flags (to distinguish a fixed string
  54               table from a regular expression table).
  55
  56        <b>lookup</b> <i>maptype:mapname flags key</i>
  57               Look up the data stored under  the  requested  key.
  58               The reply is the request completion status code and
  59               the lookup result value.  The  <i>maptype:mapname</i>  and
  60               <i>flags</i> are the same as with the <b>open</b> request.
  61
  62        <b>update</b> <i>maptype:mapname flags key value</i>
  63               Update  the  data  stored  under the requested key.
  64               The reply is the request  completion  status  code.
  65               The  <i>maptype:mapname</i> and <i>flags</i> are the same as with
  66               the <b>open</b> request.
  67
  68               To implement single-updater maps, specify a process
  69               limit  of  1  in  the  <a href="master.5.html">master.cf</a> file entry for the
  70               <b>proxywrite</b> service.
  71
  72               This request is supported in Postfix 2.5 and later.
  73
  74        <b>delete</b> <i>maptype:mapname flags key</i>
  75               Delete  the  data  stored  under the requested key.
  76               The reply is the request  completion  status  code.
  77               The  <i>maptype:mapname</i> and <i>flags</i> are the same as with
  78               the <b>open</b> request.
  79
  80               This request is supported in Postfix 2.5 and later.
  81
  82        The  request  completion status is one of OK, RETRY, NOKEY
  83        (lookup failed because the key was not found),  BAD  (mal-
  84        formed  request)  or  DENY  (the table is not approved for
  85        proxy read or update access).
  86
  87        There is no  <b>close</b>  command,  nor  are  tables  implicitly
  88        closed  when a client disconnects. The purpose is to share
  89        tables among multiple client processes.
  90
  91 <b>SERVER PROCESS MANAGEMENT</b>
  92        <a href="proxymap.8.html"><b>proxymap</b>(8)</a> servers run under control by the Postfix  <a href="master.8.html"><b>mas-</b></a>
  93        <a href="master.8.html"><b>ter</b>(8)</a> server.  Each server can handle multiple simultane-
  94        ous connections.  When all servers are busy while a client
  95        connects,  the  <a href="master.8.html"><b>master</b>(8)</a> creates a new <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server
  96        process, provided that the process limit is not  exceeded.
  97        Each  server  terminates  after  serving at least <b>$<a href="postconf.5.html#max_use">max_use</a></b>
  98        clients or after <b>$<a href="postconf.5.html#max_idle">max_idle</a></b> seconds of idle time.
  99
 100 <b>SECURITY</b>
 101        The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server opens only tables that are approved
 102        via  the <b><a href="postconf.5.html#proxy_read_maps">proxy_read_maps</a></b> or <b><a href="postconf.5.html#proxy_write_maps">proxy_write_maps</a></b> configuration
 103        parameters, does not talk to users, and can run  at  fixed
 104        low  privilege,  chrooted  or  not.   However, running the
 105        proxymap  server  chrooted  severely   limits   usability,
 106        because it can open only chrooted tables.
 107
 108        The  <a href="proxymap.8.html"><b>proxymap</b>(8)</a>  server  is not a trusted daemon process,
 109        and must not be used to look up sensitive information such
 110        as  user  or  group  IDs,  mailbox file/directory names or
 111        external commands.
 112
 113        In Postfix version 2.2 and later, the proxymap client rec-
 114        ognizes  requests to access a table for security-sensitive
 115        purposes, and opens the table directly.  This  allows  the
 116        same  <a href="postconf.5.html">main.cf</a> setting to be used by sensitive and non-sen-
 117        sitive processes.
 118
 119        Postfix-writable data files should be stored under a dedi-
 120        cated  directory that is writable only by the Postfix mail
 121        system, such as the Postfix-owned <b><a href="postconf.5.html#data_directory">data_directory</a></b>.
 122
 123        In particular, Postfix-writable files should  never  exist
 124        in root-owned directories. That would open up a particular
 125        type of security hole where ownership of a file or  direc-
 126        tory does not match the provider of its content.
 127
 128 <b>DIAGNOSTICS</b>
 129        Problems and transactions are logged to <b>syslogd</b>(8).
 130
 131 <b>BUGS</b>
 132        The   <a href="proxymap.8.html"><b>proxymap</b>(8)</a>  server  provides  service  to  multiple
 133        clients, and must therefore not be used  for  tables  that
 134        have high-latency lookups.
 135
 136        The  <a href="proxymap.8.html"><b>proxymap</b>(8)</a>  read-write  service  does not explicitly
 137        close lookup tables (even if it did,  this  could  not  be
 138        relied  on,  because the process may be terminated between
 139        table updates).  The read-write service  should  therefore
 140        not  be  used with tables that leave persistent storage in
 141        an inconsistent state between updates (for example,  CDB).
 142        Tables  that  support "sync on update" should be safe (for
 143        example, Berkeley DB) as should  tables  that  are  imple-
 144        mented by a real DBMS.
 145
 146 <b>CONFIGURATION PARAMETERS</b>
 147        On  busy  mail  systems  a long time may pass before <a href="proxymap.8.html"><b>prox-</b></a>
 148        <a href="proxymap.8.html"><b>ymap</b>(8)</a> relevant changes to <a href="postconf.5.html"><b>main.cf</b></a> are picked up. Use the
 149        command "<b>postfix reload</b>" to speed up a change.
 150
 151        The  text  below  provides  only  a parameter summary. See
 152        <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
 153
 154        <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
 155               The default location of  the  Postfix  <a href="postconf.5.html">main.cf</a>  and
 156               <a href="master.5.html">master.cf</a> configuration files.
 157
 158        <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b>
 159               The directory with Postfix-writable data files (for
 160               example: caches, pseudo-random numbers).
 161
 162        <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
 163               How much time a Postfix daemon process may take  to
 164               handle  a  request  before  it  is  terminated by a
 165               built-in watchdog timer.
 166
 167        <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
 168               The time limit for sending or receiving information
 169               over an internal communication channel.
 170
 171        <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
 172               The  maximum  amount  of  time that an idle Postfix
 173               daemon process waits  for  an  incoming  connection
 174               before terminating voluntarily.
 175
 176        <b><a href="postconf.5.html#max_use">max_use</a> (100)</b>
 177               The  maximal  number of incoming connections that a
 178               Postfix daemon process will service  before  termi-
 179               nating voluntarily.
 180
 181        <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
 182               The  process  ID  of  a  Postfix  command or daemon
 183               process.
 184
 185        <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
 186               The process name of a  Postfix  command  or  daemon
 187               process.
 188
 189        <b><a href="postconf.5.html#proxy_read_maps">proxy_read_maps</a> (see 'postconf -d' output)</b>
 190               The  lookup  tables  that the <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server is
 191               allowed to access for the read-only service.
 192
 193        Available in Postfix 2.5 and later:
 194
 195        <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b>
 196               The directory with Postfix-writable data files (for
 197               example: caches, pseudo-random numbers).
 198
 199        <b><a href="postconf.5.html#proxy_write_maps">proxy_write_maps</a> (see 'postconf -d' output)</b>
 200               The  lookup  tables  that the <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server is
 201               allowed to access for the read-write service.
 202
 203 <b>SEE ALSO</b>
 204        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 205        <a href="master.5.html">master(5)</a>, generic daemon options
 206
 207 <b>README FILES</b>
 208        <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
 209
 210 <b>LICENSE</b>
 211        The  Secure  Mailer  license must be distributed with this
 212        software.
 213
 214 <b>HISTORY</b>
 215        The proxymap service was introduced with Postfix 2.0.
 216
 217 <b>AUTHOR(S)</b>
 218        Wietse Venema
 219        IBM T.J. Watson Research
 220        P.O. Box 704
 221        Yorktown Heights, NY 10598, USA
 222
 223                                                                    PROXYMAP(8)
 224 </pre> </body> </html>