    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.

           sequence maptype:mapname flags function
                  Iterate  over  the specified database. The function
                  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  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)