diff options
Diffstat (limited to 'html/memcache_table.5.html')
| -rw-r--r-- | html/memcache_table.5.html | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/html/memcache_table.5.html b/html/memcache_table.5.html new file mode 100644 index 0000000..70c9f74 --- /dev/null +++ b/html/memcache_table.5.html @@ -0,0 +1,223 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> +<html> <head> +<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> +<title> Postfix manual - memcache_table(5) </title> +</head> <body> <pre> +MEMCACHE_TABLE(5) MEMCACHE_TABLE(5) + +<b>NAME</b> + memcache_table - Postfix memcache client configuration + +<b>SYNOPSIS</b> + <b>postmap -q "</b><i>string</i><b>" <a href="memcache_table.5.html">memcache</a>:/etc/postfix/</b><i>filename</i> + + <b>postmap -q - <a href="memcache_table.5.html">memcache</a>:/etc/postfix/</b><i>filename</i> <<i>inputfile</i> + +<b>DESCRIPTION</b> + The Postfix mail system uses optional tables for address rewriting or + mail routing. These tables are usually in <b>dbm</b> or <b>db</b> format. + + Alternatively, lookup tables can be specified as memcache instances. + To use memcache lookups, define a memcache source as a lookup table in + <a href="postconf.5.html">main.cf</a>, for example: + + <a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> = <a href="memcache_table.5.html">memcache</a>:/etc/postfix/memcache-aliases.cf + + The file /etc/postfix/memcache-aliases.cf has the same format as the + Postfix <a href="postconf.5.html">main.cf</a> 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. + +<b>MEMCACHE MAIN PARAMETERS</b> + <b>memcache (default: inet:localhost:11211)</b> + 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 <a href="proxymap.8.html">proxymap(8)</a> + server, the socket must be accessible by the unprivileged post- + fix user. + + <b>backup (default: undefined)</b> + 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 informa- + tion in the persistent database. Specify a Postfix "<a href="DATABASE_README.html">type:table</a>" + database. Examples: + + # Non-shared postscreen cache. + backup = <a href="DATABASE_README.html#types">btree</a>:/var/lib/postfix/<a href="postconf.5.html#postscreen_cache_map">postscreen_cache_map</a> + + # Shared postscreen cache for processes on the same host. + backup = <a href="proxymap.8.html">proxy</a>:<a href="DATABASE_README.html#types">btree</a>:/var/lib/postfix/<a href="postconf.5.html#postscreen_cache_map">postscreen_cache_map</a> + + Access to remote proxymap servers is under development. + + NOTE 1: When sharing a persistent <a href="postscreen.8.html"><b>postscreen</b>(8)</a> or <a href="verify.8.html"><b>verify</b>(8)</a> + 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 <b>key_format</b> feature (see below) to + prepend its own unique string to the lookup key. Otherwise, + automatic <a href="postscreen.8.html"><b>postscreen</b>(8)</a> or <a href="verify.8.html"><b>verify</b>(8)</a> cache cleanup may not work. + + NOTE 3: When the backup database is accessed with "<a href="proxymap.8.html">proxy</a>:" + lookups, the full backup database name (including the "<a href="proxymap.8.html">proxy</a>:" + prefix) must be specified in the proxymap server's + <a href="postconf.5.html#proxy_read_maps">proxy_read_maps</a> or <a href="postconf.5.html#proxy_write_maps">proxy_write_maps</a> setting (depending on + whether the access is read-only or read-write). + + <b>flags (default: 0)</b> + Optional flags that should be stored along with a memcache + update. The flags are ignored when looking up information. + + <b>ttl (default: 3600)</b> + The expiration time in seconds of memcache updates. + + NOTE 1: When using a memcache table as <a href="postscreen.8.html"><b>postscreen</b>(8)</a> or <a href="verify.8.html"><b>ver-</b></a> + <a href="verify.8.html"><b>ify</b>(8)</a> cache without persistent backup, specify a zero + *_cache_cleanup_interval value with all Postfix instances that + use the memcache, and specify the largest <a href="postscreen.8.html"><b>postscreen</b>(8)</a> *_ttl + value or <a href="verify.8.html"><b>verify</b>(8)</a> *_expire_time value as the memcache table's + <b>ttl</b> 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. + +<b>MEMCACHE KEY PARAMETERS</b> + <b>key_format (default: %s)</b> + 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 <b>key_format</b> feature is not used for <b>backup</b> 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 <a href="postscreen.8.html"><b>postscreen</b>(8)</a> or <a href="verify.8.html"><b>verify</b>(8)</a> cache + cleanup may not work. + + Examples: + + key_format = aliases:%s + key_format = verify:%s + key_format = postscreen:%s + + The <b>key_format</b> parameter supports the following '%' expansions: + + <b>%%</b> This is replaced by a literal '%' character. + + <b>%s</b> This is replaced by the memcache client input key. + + <b>%u</b> When the input key is an address of the form user@domain, + <b>%u</b> is replaced by the SQL quoted local part of the + address. Otherwise, <b>%u</b> 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). + + <b>%d</b> When the input key is an address of the form user@domain, + <b>%d</b> is replaced by the domain part of the address. Other- + wise, a lookup is silently suppressed and returns no + results (an update is skipped with a warning). + + <b>%[SUD]</b> The upper-case equivalents of the above expansions behave + in the <b>key_format</b> parameter identically to their + lower-case counter-parts. + + <b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by the corre- + sponding most significant component of the input key's + domain. If the input key is <i>user@mail.example.com</i>, then + %1 is <b>com</b>, %2 is <b>example</b> and %3 is <b>mail</b>. 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). + + <b>domain (default: no domain list)</b> + This feature can significantly reduce database server load. + Specify a list of domain names, paths to files, or "<a href="DATABASE_README.html">type:table</a>" + 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: + + domain = example.com, <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/searchdomains + +<b>MEMCACHE ERROR CONTROLS</b> + <b>data_size_limit (default: 10240)</b> + The maximal memcache reply data length in bytes. + + <b>line_size_limit (default: 1024)</b> + The maximal memcache reply line length in bytes. + + <b>max_try (default: 2)</b> + 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. + + <b>retry_pause (default: 1)</b> + The time in seconds before retrying a failed memcache command. + + <b>timeout (default: 2)</b> + The time limit for sending a memcache command and for receiving + a memcache reply. + +<b>BUGS</b> + The Postfix memcache client cannot be used for security-sensitive + tables such as <b><a href="postconf.5.html#alias_maps">alias_maps</a></b> (these may contain "<i>|command</i> and "<i>/file/name</i>" + destinations), or <b><a href="postconf.5.html#virtual_uid_maps">virtual_uid_maps</a></b>, <b><a href="postconf.5.html#virtual_gid_maps">virtual_gid_maps</a></b> and <b><a href="postconf.5.html#virtual_mailbox_maps">virtual_mail</a>-</b> + <b><a href="postconf.5.html#virtual_mailbox_maps">box_maps</a></b> (these specify UNIX process privileges or "<i>/file/name</i>" desti- + nations). In a typical deployment a memcache database is writable by + any process that can talk to the memcache server; in contrast, secu- + rity-sensitive tables must never be writable by the unprivileged Post- + fix user. + + The Postfix memcache client requires additional configuration when used + as <a href="postscreen.8.html"><b>postscreen</b>(8)</a> or <a href="verify.8.html"><b>verify</b>(8)</a> cache. For details see the <b>backup</b> and + <b>ttl</b> parameter discussions in the MEMCACHE MAIN PARAMETERS section + above. + +<b>SEE ALSO</b> + <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager + <a href="postconf.5.html">postconf(5)</a>, configuration parameters + +<b>README FILES</b> + <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview + <a href="MEMCACHE_README.html">MEMCACHE_README</a>, Postfix memcache client guide + +<b>LICENSE</b> + The Secure Mailer license must be distributed with this software. + +<b>HISTORY</b> + Memcache support was introduced with Postfix version 2.9. + +<b>AUTHOR(S)</b> + 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 + + MEMCACHE_TABLE(5) +</pre> </body> </html> |