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