    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 using memcache with persistent backup
                  as postscreen(8) or verify(8) cache, disable  auto-
                  matic  cache cleanup (*_cache_cleanup_interval = 0)
                  in all Postfix instances except  for  one  instance
                  that will be responsible for cache cleanup.

                  NOTE  2:  In the case of a proxied backup database,
                  the  full  backup  database  name  (including   the
                  "proxy:"  prefix) must be specified in the proxymap
                  server's proxy_read_maps or  proxy_write_maps  set-
                  ting  (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.

           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: The key_format feature is not used for backup
                  database requests.

                  When  the  same  memcache database is used to cache
                  information from multiple tables, you can  use  the
                  key_format  feature  to  avoid  name  collisions by
                  prepending a fixed string.  Examples:

                      key_format = aliases:%s
                      key_format = access:%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)