1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3<html> <head> 4<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 5<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 6<title> Postfix manual - memcache_table(5) </title> 7</head> <body> <pre> 8MEMCACHE_TABLE(5) MEMCACHE_TABLE(5) 9 10<b>NAME</b> 11 memcache_table - Postfix memcache client configuration 12 13<b>SYNOPSIS</b> 14 <b>postmap -q "</b><i>string</i><b>" <a href="memcache_table.5.html">memcache</a>:/etc/postfix/</b><i>filename</i> 15 16 <b>postmap -q - <a href="memcache_table.5.html">memcache</a>:/etc/postfix/</b><i>filename</i> <<i>inputfile</i> 17 18<b>DESCRIPTION</b> 19 The Postfix mail system uses optional tables for address rewriting or 20 mail routing. These tables are usually in <b>dbm</b> or <b>db</b> format. 21 22 Alternatively, lookup tables can be specified as memcache instances. 23 To use memcache lookups, define a memcache source as a lookup table in 24 <a href="postconf.5.html">main.cf</a>, for example: 25 26 <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 27 28 The file /etc/postfix/memcache-aliases.cf has the same format as the 29 Postfix <a href="postconf.5.html">main.cf</a> file, and specifies the parameters described below. 30 31 The Postfix memcache client supports the lookup, update, delete and 32 sequence (first/next) operations. The sequence operation requires a 33 backup database that supports the operation. 34 35<b>MEMCACHE MAIN PARAMETERS</b> 36 <b>memcache (default: inet:localhost:11211)</b> 37 The memcache server (note: singular) that Postfix will try to 38 connect to. For a TCP server specify "inet:" followed by a 39 hostname or address, ":", and a port name or number. Specify an 40 IPv6 address inside "[]". For a UNIX-domain server specify 41 "unix:" followed by the socket pathname. Examples: 42 43 memcache = inet:memcache.example.com:11211 44 memcache = inet:127.0.0.1:11211 45 memcache = inet:[fc00:8d00:189::3]:11211 46 memcache = unix:/path/to/socket 47 48 NOTE: to access a UNIX-domain socket with the <a href="proxymap.8.html">proxymap(8)</a> 49 server, the socket must be accessible by the unprivileged post- 50 fix user. 51 52 <b>backup (default: undefined)</b> 53 An optional Postfix database that provides persistent backup for 54 the memcache database. The Postfix memcache client will update 55 the memcache database whenever it looks up or changes informa- 56 tion in the persistent database. Specify a Postfix "<a href="DATABASE_README.html">type:table</a>" 57 database. Examples: 58 59 # Non-shared postscreen cache. 60 backup = <a href="DATABASE_README.html#types">btree</a>:/var/lib/postfix/<a href="postconf.5.html#postscreen_cache_map">postscreen_cache_map</a> 61 62 # Shared postscreen cache for processes on the same host. 63 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> 64 65 Access to remote proxymap servers is under development. 66 67 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> 68 cache, disable automatic cache cleanup (set 69 *_cache_cleanup_interval = 0) except with one Postfix instance 70 that will be responsible for cache cleanup. 71 72 NOTE 2: When multiple tables share the same memcache database, 73 each table should use the <b>key_format</b> feature (see below) to 74 prepend its own unique string to the lookup key. Otherwise, 75 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. 76 77 NOTE 3: When the backup database is accessed with "<a href="proxymap.8.html">proxy</a>:" 78 lookups, the full backup database name (including the "<a href="proxymap.8.html">proxy</a>:" 79 prefix) must be specified in the proxymap server's 80 <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 81 whether the access is read-only or read-write). 82 83 <b>flags (default: 0)</b> 84 Optional flags that should be stored along with a memcache 85 update. The flags are ignored when looking up information. 86 87 <b>ttl (default: 3600)</b> 88 The expiration time in seconds of memcache updates. 89 90 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> 91 <a href="verify.8.html"><b>ify</b>(8)</a> cache without persistent backup, specify a zero 92 *_cache_cleanup_interval value with all Postfix instances that 93 use the memcache, and specify the largest <a href="postscreen.8.html"><b>postscreen</b>(8)</a> *_ttl 94 value or <a href="verify.8.html"><b>verify</b>(8)</a> *_expire_time value as the memcache table's 95 <b>ttl</b> value. 96 97 NOTE 2: According to memcache protocol documentation, a value 98 greater than 30 days (2592000 seconds) specifies absolute UNIX 99 time. Smaller values are relative to the time of the update. 100 101<b>MEMCACHE KEY PARAMETERS</b> 102 <b>key_format (default: %s)</b> 103 Format of the lookup and update keys that the Postfix memcache 104 client sends to the memcache server. By default, these are the 105 same as the lookup and update keys that the memcache client 106 receives from Postfix applications. 107 108 NOTE 1: The <b>key_format</b> feature is not used for <b>backup</b> database 109 requests. 110 111 NOTE 2: When multiple tables share the same memcache database, 112 each table should prepend its own unique string to the lookup 113 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 114 cleanup may not work. 115 116 Examples: 117 118 key_format = aliases:%s 119 key_format = verify:%s 120 key_format = postscreen:%s 121 122 The <b>key_format</b> parameter supports the following '%' expansions: 123 124 <b>%%</b> This is replaced by a literal '%' character. 125 126 <b>%s</b> This is replaced by the memcache client input key. 127 128 <b>%u</b> When the input key is an address of the form user@domain, 129 <b>%u</b> is replaced by the SQL quoted local part of the 130 address. Otherwise, <b>%u</b> is replaced by the entire search 131 string. If the localpart is empty, a lookup is silently 132 suppressed and returns no results (an update is skipped 133 with a warning). 134 135 <b>%d</b> When the input key is an address of the form user@domain, 136 <b>%d</b> is replaced by the domain part of the address. Other- 137 wise, a lookup is silently suppressed and returns no 138 results (an update is skipped with a warning). 139 140 <b>%[SUD]</b> The upper-case equivalents of the above expansions behave 141 in the <b>key_format</b> parameter identically to their 142 lower-case counter-parts. 143 144 <b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by the corre- 145 sponding most significant component of the input key's 146 domain. If the input key is <i>user@mail.example.com</i>, then 147 %1 is <b>com</b>, %2 is <b>example</b> and %3 is <b>mail</b>. If the input key 148 is unqualified or does not have enough domain components 149 to satisfy all the specified patterns, a lookup is 150 silently suppressed and returns no results (an update is 151 skipped with a warning). 152 153 <b>domain (default: no domain list)</b> 154 This feature can significantly reduce database server load. 155 Specify a list of domain names, paths to files, or "<a href="DATABASE_README.html">type:table</a>" 156 databases. When specified, only fully qualified search keys 157 with a *non-empty* localpart and a matching domain are eligible 158 for lookup or update: bare 'user' lookups, bare domain lookups 159 and "@domain" lookups are silently skipped (updates are skipped 160 with a warning). Example: 161 162 domain = example.com, <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/searchdomains 163 164<b>MEMCACHE ERROR CONTROLS</b> 165 <b>data_size_limit (default: 10240)</b> 166 The maximal memcache reply data length in bytes. 167 168 <b>line_size_limit (default: 1024)</b> 169 The maximal memcache reply line length in bytes. 170 171 <b>max_try (default: 2)</b> 172 The number of times to try a memcache command before giving up. 173 The memcache client does not retry a command when the memcache 174 server accepts no connection. 175 176 <b>retry_pause (default: 1)</b> 177 The time in seconds before retrying a failed memcache command. 178 179 <b>timeout (default: 2)</b> 180 The time limit for sending a memcache command and for receiving 181 a memcache reply. 182 183<b>BUGS</b> 184 The Postfix memcache client cannot be used for security-sensitive 185 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>" 186 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> 187 <b><a href="postconf.5.html#virtual_mailbox_maps">box_maps</a></b> (these specify UNIX process privileges or "<i>/file/name</i>" desti- 188 nations). In a typical deployment a memcache database is writable by 189 any process that can talk to the memcache server; in contrast, secu- 190 rity-sensitive tables must never be writable by the unprivileged Post- 191 fix user. 192 193 The Postfix memcache client requires additional configuration when used 194 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 195 <b>ttl</b> parameter discussions in the MEMCACHE MAIN PARAMETERS section 196 above. 197 198<b>SEE ALSO</b> 199 <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager 200 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 201 202<b>README FILES</b> 203 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview 204 <a href="MEMCACHE_README.html">MEMCACHE_README</a>, Postfix memcache client guide 205 206<b>LICENSE</b> 207 The Secure Mailer license must be distributed with this software. 208 209<b>HISTORY</b> 210 Memcache support was introduced with Postfix version 2.9. 211 212<b>AUTHOR(S)</b> 213 Wietse Venema 214 IBM T.J. Watson Research 215 P.O. Box 704 216 Yorktown Heights, NY 10598, USA 217 218 Wietse Venema 219 Google, Inc. 220 111 8th Avenue 221 New York, NY 10011, USA 222 223 MEMCACHE_TABLE(5) 224</pre> </body> </html> 225