    MEMCACHE_TABLE(5)                                            MEMCACHE_TABLE(5)

    NAME
           memcache_table - Postfix memcache client configuration

    SYNOPSIS
           postmap -q "string" memcache:/etc/postfix/filename

           postmap -q - memcache:/etc/postfix/filename <inputfile

    DESCRIPTION
           The  Postfix  mail system uses optional tables for address
           rewriting or mail routing. These tables are usually in dbm
           or db format.

           Alternatively,  lookup tables can be specified as memcache
           instances.  To use memcache  lookups,  define  a  memcache
           source as a lookup table in main.cf, for example:

               virtual_alias_maps = memcache:/etc/postfix/memcache-aliases.cf

           The  file  /etc/postfix/memcache-aliases.cf  has  the same
           format as the Postfix  main.cf  file,  and  specifies  the
           parameters described below.

           The  Postfix  memcache client supports the lookup, update,
           delete and sequence (first/next) operations. The  sequence
           operation  requires  a  backup  database that supports the
           operation.

    MEMCACHE MAIN PARAMETERS
           memcache (default: inet:localhost:11211)
                  The memcache server (note: singular)  that  Postfix
                  will  try  to connect to.  For a TCP server specify
                  "inet:" followed by a hostname or address, ":", and
                  a  port  name  or  number.  Specify an IPv6 address
                  inside "[]".   For  a  UNIX-domain  server  specify
                  "unix:" followed by the socket pathname. Examples:

                      memcache = inet:memcache.example.com:11211
                      memcache = inet:127.0.0.1:11211
                      memcache = inet:[fc00:8d00:189::3]:11211
                      memcache = unix:/path/to/socket

                  NOTE: to access a UNIX-domain socket with the prox-
                  ymap(8) server, the socket must  be  accessible  by
                  the unprivileged postfix user.

           backup (default: undefined)
                  An  optional Postfix database that provides persis-
                  tent backup for the memcache database. The  Postfix
                  memcache  client  will update the memcache database
                  whenever it looks up or changes information in  the
                  persistent database. Specify a Postfix "type:table"
                  database. Examples:

                      # Non-shared postscreen cache.
                      backup = btree:/var/lib/postfix/postscreen_cache_map

                      # Shared postscreen cache for processes on the same host.
                      backup = proxy:btree:/var/lib/postfix/postscreen_cache_map

                  Access to remote proxymap servers is under develop-
                  ment.

                  NOTE  1: When sharing a persistent postscreen(8) or
                  verify(8) cache, disable  automatic  cache  cleanup
                  (set  *_cache_cleanup_interval = 0) except with one
                  Postfix instance that will be responsible for cache
                  cleanup.

                  NOTE  2:  When different tables share the same mem-
                  cache database, each table should use the  key_for-
                  mat  feature  (see below) to prepend its own unique
                  string to the  lookup  key.   Otherwise,  automatic
                  postscreen(8)  or  verify(8)  cache cleanup may not
                  work.

                  NOTE 3: When the backup database is  accessed  with
                  "proxy:"  lookups,  the  full  backup database name
                  (including the "proxy:" prefix) must  be  specified
                  in   the   proxymap   server's  proxy_read_maps  or
                  proxy_write_maps setting (depending on whether  the
                  access is read-only or read-write).

           flags (default: 0)
                  Optional  flags  that should be stored along with a
                  memcache update. The flags are ignored when looking
                  up information.

           ttl (default: 3600)
                  The expiration time in seconds of memcache updates.

                  NOTE  1:   When   using   a   memcache   table   as
                  postscreen(8) or verify(8) cache without persistent
                  backup,  specify  a  zero  *_cache_cleanup_interval
                  value  with all Postfix instances that use the mem-
                  cache, and specify the largest postscreen(8)  *_ttl
                  value  or verify(8) *_expire_time value as the mem-
                  cache table's ttl value.

                  NOTE 2: According to memcache  protocol  documenta-
                  tion,  a  value  greater than 30 days (2592000 sec-
                  onds) specifies absolute UNIX time. Smaller  values
                  are relative to the time of the update.

    MEMCACHE KEY PARAMETERS
           key_format (default: %s)
                  Format  of  the  lookup and update keys in memcache
                  requests.  By default, these are the  same  as  the
                  lookup  and update keys that are given to the Post-
                  fix memcache client.

                  NOTE 1: The key_format  feature  is  not  used  for
                  backup database requests.

                  NOTE  2:  When different tables share the same mem-
                  cache database, each table should prepend  its  own
                  unique  string to the lookup key.  Otherwise, auto-
                  matic postscreen(8) or verify(8) cache cleanup  may
                  not work.

                  Examples:

                      key_format = aliases:%s
                      key_format = verify:%s
                      key_format = postscreen:%s

                  The key_format parameter supports the following '%'
                  expansions:

                  %%     This is replaced by a literal '%' character.

                  %s     This  is  replaced  by  the  memcache client
                         input key.

                  %u     When the input key is an address of the form
                         user@domain,  %u  is  replaced  by  the  SQL
                         quoted local part of  the  address.   Other-
                         wise,  %u  is  replaced by the entire search
                         string.  If the localpart is empty, a lookup
                         is   silently   suppressed  and  returns  no
                         results (an update is skipped with  a  warn-
                         ing).

                  %d     When the input key is an address of the form
                         user@domain, %d is replaced  by  the  domain
                         part of the address.  Otherwise, a lookup is
                         silently suppressed and returns  no  results
                         (an update is skipped with a warning).

                  %[SUD] The  upper-case  equivalents  of  the  above
                         expansions behave in the key_format  parame-
                         ter identically to their lower-case counter-
                         parts.

                  %[1-9] The patterns %1, %2, ... %9 are replaced  by
                         the corresponding most significant component
                         of the input key's domain. If the input  key
                         is user@mail.example.com, then %1 is com, %2
                         is example and %3 is mail. If the input  key
                         is  unqualified  or  does  not  have  enough
                         domain components to satisfy all the  speci-
                         fied  patterns,  a  lookup  is silently sup-
                         pressed and returns no results (an update is
                         skipped with a warning).

           domain (default: no domain list)
                  This  feature  can  significantly  reduce  database
                  server load.  Specify a list of domain names, paths
                  to  files,  or "type:table" databases.  When speci-
                  fied, only fully qualified search keys with a *non-
                  empty* localpart and a matching domain are eligible
                  for lookup or update:  bare  'user'  lookups,  bare
                  domain  lookups  and "@domain" lookups are silently
                  skipped  (updates  are  skipped  with  a  warning).
                  Example:

                      domain = example.com, hash:/etc/postfix/searchdomains

    MEMCACHE ERROR CONTROLS
           data_size_limit (default: 10240)
                  The maximal memcache reply data length in bytes.

           line_size_limit (default: 1024)
                  The maximal memcache reply line length in bytes.

           max_try (default: 2)
                  The  number  of  times  to  try  a memcache command
                  before giving up.  The  memcache  client  does  not
                  retry a command when the memcache server accepts no
                  connection.

           retry_pause (default: 1)
                  The time in seconds before retrying a  failed  mem-
                  cache command.

           timeout (default: 2)
                  The  time  limit for sending a memcache command and
                  for receiving a memcache reply.

    BUGS
           The Postfix memcache client cannot be used  for  security-
           sensitive  tables  such  as  alias_maps (these may contain
           "|command  and   "/file/name"   destinations),   or   vir-
           tual_uid_maps,  virtual_gid_maps  and virtual_mailbox_maps
           (these specify UNIX  process  privileges  or  "/file/name"
           destinations).   In  a typical deployment a memcache data-
           base is writable by any process that can talk to the  mem-
           cache  server; in contrast, security-sensitive tables must
           never be writable by the unprivileged Postfix user.

           The Postfix memcache client requires additional configura-
           tion  when  used as postscreen(8) or verify(8) cache.  For
           details see the backup and ttl  parameter  discussions  in
           the MEMCACHE MAIN PARAMETERS section above.

    SEE ALSO
           postmap(1), Postfix lookup table manager
           postconf(5), configuration parameters

    README FILES
           DATABASE_README, Postfix lookup table overview
           MEMCACHE_README, Postfix memcache client guide

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

    HISTORY
           Memcache  support was introduced with Postfix version 2.9.

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

                                                                 MEMCACHE_TABLE(5)