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)