#++ # NAME # memcache_table 5 # SUMMARY # Postfix memcache client configuration # SYNOPSIS # \fBpostmap -q "\fIstring\fB" memcache:/etc/postfix/filename\fR # # \fBpostmap -q - memcache:/etc/postfix/\fIfilename\fR <\fIinputfile\fR # DESCRIPTION # The Postfix mail system uses optional tables for address # rewriting or mail routing. These tables are usually in # \fBdbm\fR or \fBdb\fR 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: # # .nf # virtual_alias_maps = memcache:/etc/postfix/memcache-aliases.cf # .fi # # 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 # .ad # .fi # .IP "\fBmemcache (default: inet:localhost:11211)\fR" # 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: # # .nf # 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 # .fi # # NOTE: to access a UNIX-domain socket with the proxymap(8) # server, the socket must be accessible by the unprivileged # postfix user. # .IP "\fBbackup (default: undefined)\fR" # An optional Postfix database that provides persistent 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: # # .nf # # 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 # .fi # # Access to remote proxymap servers is under development. # # NOTE 1: When using memcache with persistent backup as # \fBpostscreen\fR(8) or \fBverify\fR(8) cache, disable # automatic 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 # setting (depending on whether the access is read-only or # read-write). # .IP "\fBflags (default: 0)\fR" # Optional flags that should be stored along with a memcache # update. # .IP "\fBttl (default: 3600)\fR" # The expiration time in seconds of memcache updates. # # NOTE 1: When using a memcache table as \fBpostscreen\fR(8) # or \fBverify\fR(8) cache without persistent backup, specify # a zero *_cache_cleanup_interval value with all Postfix # instances that use the memcache, and specify the largest # \fBpostscreen\fR(8) *_ttl value or \fBverify\fR(8) *_expire_time # value as the memcache table's \fBttl\fR value. # # NOTE 2: 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. # MEMCACHE KEY PARAMETERS # .ad # .fi # .IP "\fBkey_format (default: %s)\fB" # 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 Postfix memcache client. # # NOTE: The \fBkey_format\fR feature is not used for \fBbackup\fR # database requests. # # When the same memcache database is used to cache information # from multiple tables, you can use the \fBkey_format\fR # feature to avoid name collisions by prepending a fixed # string. Examples: # # .nf # key_format = aliases:%s # key_format = access:%s # .fi # # The \fBkey_format\fR parameter supports the following '%' # expansions: # .RS # .IP "\fB\fB%%\fR\fR" # This is replaced by a literal '%' character. # .IP "\fB\fB%s\fR\fR" # This is replaced by the memcache client input key. # .IP "\fB\fB%u\fR\fR" # When the input key is an address of the form user@domain, # \fB%u\fR is replaced by the SQL quoted local part of the # address. Otherwise, \fB%u\fR 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 warning). # .IP "\fB\fB%d\fR\fR" # When the input key is an address of the form user@domain, # \fB%d\fR 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). # .IP "\fB\fB%[SUD]\fR\fR" # The upper-case equivalents of the above expansions behave # in the \fBkey_format\fR parameter identically to their # lower-case counter-parts. # .IP "\fB\fB%[1-9]\fR\fR" # The patterns %1, %2, ... %9 are replaced by the corresponding # most significant component of the input key's domain. If # the input key is \fIuser@mail.example.com\fR, then %1 is # \fBcom\fR, %2 is \fBexample\fR and %3 is \fBmail\fR. If the # input key is unqualified or does not have enough domain # components to satisfy all the specified patterns, a lookup # is silently suppressed and returns no results (an update # is skipped with a warning). # .RE # .IP "\fBdomain (default: no domain list)\fR" # This feature can significantly reduce database server load. # Specify a list of domain names, paths to files, or "type:table" # databases. # 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: # # .nf # domain = example.com, hash:/etc/postfix/searchdomains # .fi # MEMCACHE ERROR CONTROLS # .ad # .fi # .IP "\fBdata_size_limit (default: 10240)\fR" # The maximal memcache reply data length in bytes. # .IP "\fBline_size_limit (default: 1024)\fR" # The maximal memcache reply line length in bytes. # .IP "\fBmax_try (default: 2)\fR" # 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. # .IP "\fBretry_pause (default: 1)\fR" # The time in seconds before retrying a failed memcache command. # .IP "\fBtimeout (default: 2)\fR" # 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 \fBalias_maps\fR (these may contain # "\fI|command\fR and "\fI/file/name\fR" destinations), or # \fBvirtual_uid_maps\fR, \fBvirtual_gid_maps\fR and # \fBvirtual_mailbox_maps\fR (these specify UNIX process # privileges or "\fI/file/name\fR" destinations). In a typical # deployment a memcache database is writable by any process # that can talk to the memcache server; in contrast, # security-sensitive tables must never be writable by the # unprivileged Postfix user. # # The Postfix memcache client requires additional configuration # when used as \fBpostscreen\fR(8) or \fBverify\fR(8) cache. # For details see the \fBbackup\fR and \fBttl\fR parameter # discussions in the MEMCACHE MAIN PARAMETERS section above. # SEE ALSO # postmap(1), Postfix lookup table manager # postconf(5), configuration parameters # README FILES # .ad # .fi # Use "\fBpostconf readme_directory\fR" or # "\fBpostconf html_directory\fR" to locate this information. # .na # .nf # DATABASE_README, Postfix lookup table overview # MEMCACHE_README, Postfix memcache client guide # LICENSE # .ad # .fi # The Secure Mailer license must be distributed with this software. # HISTORY # .ad # .fi # 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 #--