    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  dis-
           tinct 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-existent 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 connections" 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 writers (i.e. all file-based
                  tables that are not based on lmdb).

           The proxymap(8) server implements the following requests:

           open maptype:mapname instance-flags
                  Open the table with type maptype and name mapname, with  initial
                  dictionary  flags  instance-flags. The reply contains the actual
                  dictionary flags (for example, to distinguish a fixed-string ta-
                  ble from a regular-expression table).

           lookup maptype:mapname instance-flags request-flags key
                  Look  up  the data stored under the requested key using the dic-
                  tionary flags in request-flags.  The reply contains the  request
                  completion  status code, the resulting dictionary flags, and the
                  lookup result value.  The maptype:mapname and instance-flags are
                  the same as with the open request.

           update maptype:mapname instance-flags request-flags key value
                  Update the data stored under the requested key using the dictio-
                  nary flags in request-flags.  The  reply  contains  the  request
                  completion  status code and the resulting dictionary flags.  The
                  maptype:mapname and instance-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 instance-flags request-flags key
                  Delete the data stored under the requested key, using  the  dic-
                  tionary  flags in request-flags.  The reply contains the request
                  completion status code and the resulting dictionary flags.   The
                  maptype:mapname and instance-flags are the same as with the open
                  request.

                  This request is supported in Postfix 2.5 and later.

           sequence maptype:mapname instance-flags request-flags function
                  Iterate over the specified database, using the dictionary  flags
                  in  request-flags.  The function is either DICT_SEQ_FUN_FIRST or
                  DICT_SEQ_FUN_NEXT.  The reply contains  the  request  completion
                  status  code,  the  resulting dictionary flags, and a lookup key
                  and  result   value   if   found.    The   maptype:mapname   and
                  instance-flags are the same as with the open request.

                  This request is supported in Postfix 2.9 and later.

           Not implemented: close
                  There is no close request, nor are tables implicitly closed when
                  a client disconnects. The purpose is to share tables among  mul-
                  tiple  client  processes.  Due  to the absence of an explicit or
                  implicit close, updates are forced to be synchronous.

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

    SERVER PROCESS MANAGEMENT
           proxymap(8) servers run under control by the Postfix master(8)  server.
           Each  server  can  handle  multiple simultaneous 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  usabil-
           ity, 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 UNIX user or  group  IDs,
           mailbox file/directory names or external commands.

           In  Postfix  version  2.2  and  later,  the  proxymap client recognizes
           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-sensitive processes.

           Postfix-writable data files should be stored under a  dedicated  direc-
           tory  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 directory does not match the  provider  of
           its content.

    DIAGNOSTICS
           Problems and transactions are logged to syslogd(8) or postlogd(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  ser-
           vice  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 implemented by a real DBMS.

    CONFIGURATION PARAMETERS
           On busy mail systems a long time may pass before  proxymap(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 con-
                  figuration 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 terminating 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.

           Available in Postfix 3.3 and later:

           service_name (read-only)
                  The master.cf service name of a Postfix daemon process.

    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

           Wietse Venema
           Google, Inc.
           111 8th Avenue
           New York, NY 10011, USA

           Wietse Venema
           porcupine.org

                                                                       PROXYMAP(8)