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.  In order 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 and update
       operations.

MEMCACHE PARAMETERS
       hosts (default: localhost:11211)
              The  memcache servers that Postfix will try to con-
              nect to.  Specify a hostname or address, optionally
              followed  by  ":"  and  a  port name or number. The
              default port is 11211.  Examples:

                  hosts = memcache01.example.com
                      memcache02.example.com

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

              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 dictionaries.   When  specified,  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

       flags (default: 0)
              Optional  flags  that should be stored along with a
              memcache update.

       ttl (default: 604800)
              The expiration time in seconds of memcache updates.
              The default is one week.

              When  using  memcache  tables with postscreen(8) or
              verify(8), specify a zero  *_cache_cleanup_interval
              value,  and specify the largest postscreen(8) *_ttl
              value or verify(8) *_expire_time value as the  mem-
              cache map's ttl value.

              Note: according to memcache protocol documentation,
              a value greater  than  30  days  (2592000  seconds)
              specifies  absolute  UNIX  time. Smaller values are
              relative to the time of the update.

BUGS
       The Postfix memcache client is based on libmemcache, which
       will  terminate  its  process after a memcache server goes
       down. To avoid this, set  up  redundant  memcache  servers
       that have no common source of failure.

       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 and  virtual_gid_maps  (these  specify  UNIX
       process  privileges).   In a typical deployment a memcache
       database is shared via a  TCP  socket,  and  is  therefore
       writable  not only by Postfix, but by any process that can
       talk to the memcache server.

       The Postfix memcache client requires additional configura-
       tion  when  used with the postscreen(8) and verify(8) dae-
       mons.  For details see the ttl parameter discussion at the
       end of the MEMCACHE PARAMETERS section in this document.

       The Postfix memcache client is supported only with libmem-
       cache version 1.4.0.  Some libmemcache features are  docu-
       mented  by  reading  libmemcache  source  code,  instead a
       proper API.

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
       The first memcache client for Postfix was written by  Omar
       Kilani.   Besides  being  implemented on libmemcache, this
       implementation bears no resemblance to his work.

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

                                                             MEMCACHE_TABLE(5)