dist/html/proxymap.8.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html> <head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<title> Postfix manual - proxymap(8) </title>
</head> <body> <pre>
PROXYMAP(8)                                                        PROXYMAP(8)

<b>NAME</b>
       proxymap - Postfix lookup table proxy server

<b>SYNOPSIS</b>
       <b>proxymap</b> [generic Postfix daemon options]

<b>DESCRIPTION</b>
       The  <a href="proxymap.8.html"><b>proxymap</b>(8)</a>  server  provides read-only or read-write
       table lookup service to Postfix processes. These  services
       are  implemented with distinct service names: <b>proxymap</b> and
       <b>proxywrite</b>, respectively. The purpose  of  these  services
       is:

       <b>o</b>      To  overcome  chroot  restrictions.  For example, a
              chrooted SMTP server needs  access  to  the  system
              passwd  file  in order to reject mail for non-exis-
              tent local addresses, but it is  not  practical  to
              maintain  a  copy  of the passwd file in the chroot
              jail.  The solution:

              <a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> =
                  <a href="proxymap.8.html">proxy</a>:unix:passwd.byname $<a href="postconf.5.html#alias_maps">alias_maps</a>

       <b>o</b>      To consolidate the number of open lookup tables  by
              sharing  one  open  table among multiple processes.
              For example, making mysql  connections  from  every
              Postfix daemon process results in "too many connec-
              tions" errors. The solution:

              <a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> =
                  <a href="proxymap.8.html">proxy</a>:<a href="mysql_table.5.html">mysql</a>:/etc/postfix/virtual_alias.cf

              The total number of connections is limited  by  the
              number of proxymap server processes.

       <b>o</b>      To  provide single-updater functionality for lookup
              tables that do not reliably support multiple  writ-
              ers (i.e. all file-based tables).

       The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server implements the following requests:

       <b>open</b> <i>maptype:mapname flags</i>
              Open  the table with type <i>maptype</i> and name <i>mapname</i>,
              as controlled by <i>flags</i>. The reply includes the <i>map-</i>
              <i>type</i> dependent flags (to distinguish a fixed string
              table from a regular expression table).

       <b>lookup</b> <i>maptype:mapname flags key</i>
              Look up the data stored under  the  requested  key.
              The reply is the request completion status code and
              the lookup result value.  The  <i>maptype:mapname</i>  and
              <i>flags</i> are the same as with the <b>open</b> request.

       <b>update</b> <i>maptype:mapname flags key value</i>
              Update  the  data  stored  under the requested key.
              The reply is the request  completion  status  code.
              The  <i>maptype:mapname</i> and <i>flags</i> are the same as with
              the <b>open</b> request.

              To implement single-updater maps, specify a process
              limit  of  1  in  the  <a href="master.5.html">master.cf</a> file entry for the
              <b>proxywrite</b> service.

              This request is supported in Postfix 2.5 and later.

       <b>delete</b> <i>maptype:mapname flags key</i>
              Delete  the  data  stored  under the requested key.
              The reply is the request  completion  status  code.
              The  <i>maptype:mapname</i> and <i>flags</i> are the same as with
              the <b>open</b> request.

              This request is supported in Postfix 2.5 and later.

       <b>sequence</b> <i>maptype:mapname flags function</i>
              Iterate  over  the specified database. The <i>function</i>
              is one of DICT_SEQ_FUN_FIRST or  DICT_SEQ_FUN_NEXT.
              The reply is the request completion status code and
              a lookup key and result value, if found.

              This request is supported in Postfix 2.9 and later.

       The  request  completion status is one of OK, RETRY, NOKEY
       (lookup failed because the key was not found),  BAD  (mal-
       formed  request)  or  DENY  (the table is not approved for
       proxy read or update access).

       There is no  <b>close</b>  command,  nor  are  tables  implicitly
       closed  when a client disconnects. The purpose is to share
       tables among multiple client processes.

<b>SERVER PROCESS MANAGEMENT</b>
       <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>
       <a href="master.8.html"><b>ter</b>(8)</a> server.  Each server can handle multiple simultane-
       ous connections.  When all servers are busy while a client
       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
       process, provided that the process limit is not  exceeded.
       Each  server  terminates  after  serving at least <b>$<a href="postconf.5.html#max_use">max_use</a></b>
       clients or after <b>$<a href="postconf.5.html#max_idle">max_idle</a></b> seconds of idle time.

<b>SECURITY</b>
       The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server opens only tables that are approved
       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
       parameters, does not talk to users, and can run  at  fixed
       low  privilege,  chrooted  or  not.   However, running the
       proxymap  server  chrooted  severely   limits   usability,
       because it can open only chrooted tables.

       The  <a href="proxymap.8.html"><b>proxymap</b>(8)</a>  server  is not a trusted daemon process,
       and must not be used to look up sensitive information such
       as  user  or  group  IDs,  mailbox file/directory names or
       external commands.

       In Postfix version 2.2 and later, the proxymap client rec-
       ognizes  requests to access a table for security-sensitive
       purposes, and opens the table directly.  This  allows  the
       same  <a href="postconf.5.html">main.cf</a> setting to be used by sensitive and non-sen-
       sitive processes.

       Postfix-writable data files should be stored under a dedi-
       cated  directory that is writable only by the Postfix mail
       system, such as the Postfix-owned <b><a href="postconf.5.html#data_directory">data_directory</a></b>.

       In particular, Postfix-writable files should  never  exist
       in root-owned directories. That would open up a particular
       type of security hole where ownership of a file or  direc-
       tory does not match the provider of its content.

<b>DIAGNOSTICS</b>
       Problems and transactions are logged to <b>syslogd</b>(8).

<b>BUGS</b>
       The   <a href="proxymap.8.html"><b>proxymap</b>(8)</a>  server  provides  service  to  multiple
       clients, and must therefore not be used  for  tables  that
       have high-latency lookups.

       The  <a href="proxymap.8.html"><b>proxymap</b>(8)</a>  read-write  service  does not explicitly
       close lookup tables (even if it did,  this  could  not  be
       relied  on,  because the process may be terminated between
       table updates).  The read-write service  should  therefore
       not  be  used with tables that leave persistent storage in
       an inconsistent state between updates (for example,  CDB).
       Tables  that  support "sync on update" should be safe (for
       example, Berkeley DB) as should  tables  that  are  imple-
       mented by a real DBMS.

<b>CONFIGURATION PARAMETERS</b>
       On  busy  mail  systems  a long time may pass before <a href="proxymap.8.html"><b>prox-</b></a>
       <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
       command "<b>postfix reload</b>" to speed up a change.

       The  text  below  provides  only  a parameter summary. See
       <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.

       <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
              The default location of  the  Postfix  <a href="postconf.5.html">main.cf</a>  and
              <a href="master.5.html">master.cf</a> configuration files.

       <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b>
              The directory with Postfix-writable data files (for
              example: caches, pseudo-random numbers).

       <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
              How much time a Postfix daemon process may take  to
              handle  a  request  before  it  is  terminated by a
              built-in watchdog timer.

       <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
              The time limit for sending or receiving information
              over an internal communication channel.

       <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
              The  maximum  amount  of  time that an idle Postfix
              daemon process waits  for  an  incoming  connection
              before terminating voluntarily.

       <b><a href="postconf.5.html#max_use">max_use</a> (100)</b>
              The  maximal  number of incoming connections that a
              Postfix daemon process will service  before  termi-
              nating voluntarily.

       <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
              The  process  ID  of  a  Postfix  command or daemon
              process.

       <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
              The process name of a  Postfix  command  or  daemon
              process.

       <b><a href="postconf.5.html#proxy_read_maps">proxy_read_maps</a> (see 'postconf -d' output)</b>
              The  lookup  tables  that the <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server is
              allowed to access for the read-only service.

       Available in Postfix 2.5 and later:

       <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b>
              The directory with Postfix-writable data files (for
              example: caches, pseudo-random numbers).

       <b><a href="postconf.5.html#proxy_write_maps">proxy_write_maps</a> (see 'postconf -d' output)</b>
              The  lookup  tables  that the <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server is
              allowed to access for the read-write service.

<b>SEE ALSO</b>
       <a href="postconf.5.html">postconf(5)</a>, configuration parameters
       <a href="master.5.html">master(5)</a>, generic daemon options

<b>README FILES</b>
       <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview

<b>LICENSE</b>
       The  Secure  Mailer  license must be distributed with this
       software.

<b>HISTORY</b>
       The proxymap service was introduced with Postfix 2.0.

<b>AUTHOR(S)</b>
       Wietse Venema
       IBM T.J. Watson Research
       P.O. Box 704
       Yorktown Heights, NY 10598, USA

                                                                   PROXYMAP(8)
</pre> </body> </html>