diff options
Diffstat (limited to '')
| -rw-r--r-- | man/man5/memcache_table.5 | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/man/man5/memcache_table.5 b/man/man5/memcache_table.5 new file mode 100644 index 0000000..430f73c --- /dev/null +++ b/man/man5/memcache_table.5 @@ -0,0 +1,259 @@ +.TH MEMCACHE_TABLE 5 +.ad +.fi +.SH NAME +memcache_table +\- +Postfix memcache client configuration +.SH "SYNOPSIS" +.na +.nf +\fBpostmap \-q "\fIstring\fB" memcache:/etc/postfix/\fIfilename\fR + +\fBpostmap \-q \- memcache:/etc/postfix/\fIfilename\fB <\fIinputfile\fR +.SH DESCRIPTION +.ad +.fi +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. +.SH "MEMCACHE MAIN PARAMETERS" +.na +.nf +.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 sharing a persistent \fBpostscreen\fR(8) or +\fBverify\fR(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 multiple tables share the same memcache +database, each table should use the \fBkey_format\fR feature +(see below) to prepend its own unique string to the lookup +key. Otherwise, automatic \fBpostscreen\fR(8) or \fBverify\fR(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). +.IP "\fBflags (default: 0)\fR" +Optional flags that should be stored along with a memcache +update. The flags are ignored when looking up information. +.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. +.SH "MEMCACHE KEY PARAMETERS" +.na +.nf +.ad +.fi +.IP "\fBkey_format (default: %s)\fB" +Format of the lookup and update keys that the Postfix +memcache client sends to the memcache server. +By default, these are the same as the lookup and update +keys that the memcache client receives from Postfix +applications. + +NOTE 1: The \fBkey_format\fR feature is not used for \fBbackup\fR +database requests. + +NOTE 2: When multiple tables share the same memcache +database, each table should prepend its own unique string +to the lookup key. Otherwise, automatic \fBpostscreen\fR(8) +or \fBverify\fR(8) cache cleanup may not work. + +Examples: + +.nf + key_format = aliases:%s + key_format = verify:%s + key_format = postscreen:%s +.fi + +The \fBkey_format\fR parameter supports the following '%' +expansions: +.RS +.IP "\fB%%\fR" +This is replaced by a literal '%' character. +.IP "\fB%s\fR" +This is replaced by the memcache client input key. +.IP "\fB%u\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%d\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%[SUD]\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%[1\-9]\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 +.SH "MEMCACHE ERROR CONTROLS" +.na +.nf +.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. +.SH BUGS +.ad +.fi +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. +.SH "SEE ALSO" +.na +.nf +postmap(1), Postfix lookup table manager +postconf(5), configuration parameters +.SH "README FILES" +.na +.nf +.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 +.SH "LICENSE" +.na +.nf +.ad +.fi +The Secure Mailer license must be distributed with this software. +.SH HISTORY +.ad +.fi +.ad +.fi +Memcache support was introduced with Postfix version 2.9. +.SH "AUTHOR(S)" +.na +.nf +Wietse Venema +IBM T.J. Watson Research +P.O. Box 704 +Yorktown Heights, NY 10598, USA + +Wietse Venema +Google, Inc. +111 8th Avenue +New York, NY 10011, USA |