PROXYMAP(8)                                                        PROXYMAP(8)

NAME
       proxymap - Postfix lookup table proxy server

SYNOPSIS
       proxymap [generic Postfix daemon options]

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

       o      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:

              local_recipient_maps =
                  proxy:unix:passwd.byname $alias_maps

       o      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:

              virtual_alias_maps =
                  proxy:mysql:/etc/postfix/virtual_alias.cf

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

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

       The proxymap(8) server implements the following requests:

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

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

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

              To implement single-updater maps, specify a process
              limit  of  1  in  the  master.cf file entry for the
              proxywrite service.

              This request is supported in Postfix 2.5 and later.

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

              This request is supported in Postfix 2.5 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  close  command,  nor  are  tables  implicitly
       closed  when a client disconnects. The purpose is to share
       tables among multiple client processes.

SERVER PROCESS MANAGEMENT
       proxymap(8) servers run under control by the Postfix  mas-
       ter(8) server.  Each server can handle multiple simultane-
       ous connections.  When all servers are busy while a client
       connects,  the  master(8) creates a new proxymap(8) server
       process, provided that the process limit is not  exceeded.
       Each  server  terminates  after  serving at least $max_use
       clients or after $max_idle seconds of idle time.

SECURITY
       The proxymap(8) server opens only tables that are approved
       via  the proxy_read_maps or proxy_write_maps 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  proxymap(8)  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  main.cf 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 data_directory.

       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.

DIAGNOSTICS
       Problems and transactions are logged to syslogd(8).

BUGS
       The   proxymap(8)  server  provides  service  to  multiple
       clients, and must therefore not be used  for  tables  that
       have high-latency lookups.

       The  proxymap(8)  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.

CONFIGURATION PARAMETERS
       On  busy  mail  systems  a long time may pass before prox-
       ymap(8) relevant changes to main.cf are picked up. Use the
       command "postfix reload" to speed up a change.

       The  text  below  provides  only  a parameter summary. See
       postconf(5) for more details including examples.

       config_directory (see 'postconf -d' output)
              The default location of  the  Postfix  main.cf  and
              master.cf configuration files.

       data_directory (see 'postconf -d' output)
              The directory with Postfix-writable data files (for
              example: caches, pseudo-random numbers).

       daemon_timeout (18000s)
              How much time a Postfix daemon process may take  to
              handle  a  request  before  it  is  terminated by a
              built-in watchdog timer.

       ipc_timeout (3600s)
              The time limit for sending or receiving information
              over an internal communication channel.

       max_idle (100s)
              The  maximum  amount  of  time that an idle Postfix
              daemon process waits  for  an  incoming  connection
              before terminating voluntarily.

       max_use (100)
              The  maximal  number of incoming connections that a
              Postfix daemon process will service  before  termi-
              nating voluntarily.

       process_id (read-only)
              The  process  ID  of  a  Postfix  command or daemon
              process.

       process_name (read-only)
              The process name of a  Postfix  command  or  daemon
              process.

       proxy_read_maps (see 'postconf -d' output)
              The  lookup  tables  that the proxymap(8) server is
              allowed to access for the read-only service.

       Available in Postfix 2.5 and later:

       data_directory (see 'postconf -d' output)
              The directory with Postfix-writable data files (for
              example: caches, pseudo-random numbers).

       proxy_write_maps (see 'postconf -d' output)
              The  lookup  tables  that the proxymap(8) server is
              allowed to access for the read-write service.

SEE ALSO
       postconf(5), configuration parameters
       master(5), generic daemon options

README FILES
       DATABASE_README, Postfix lookup table overview

LICENSE
       The  Secure  Mailer  license must be distributed with this
       software.

HISTORY
       The proxymap service was introduced with Postfix 2.0.

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

                                                                   PROXYMAP(8)