10
10
memcache_table - Postfix memcache client configuration
13
<b>postmap -q "</b><i>string</i><b>" <a href="memcache_table.5.html">memcache</a>:/etc/postfix/filename</b>
13
<b>postmap -q "</b><i>string</i><b>" <a href="memcache_table.5.html">memcache</a>:/etc/postfix/</b><i>filename</i>
15
15
<b>postmap -q - <a href="memcache_table.5.html">memcache</a>:/etc/postfix/</b><i>filename</i> <<i>inputfile</i>
18
The Postfix mail system uses optional tables for address
19
rewriting or mail routing. These tables are usually in <b>dbm</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.
22
Alternatively, lookup tables can be specified as memcache
23
instances. To use memcache lookups, define a memcache
24
source as a lookup table in <a href="postconf.5.html">main.cf</a>, for example:
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:
26
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
28
The file /etc/postfix/memcache-aliases.cf has the same
29
format as the Postfix <a href="postconf.5.html">main.cf</a> file, and specifies the
30
parameters described below.
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.
32
The Postfix memcache client supports the lookup, update,
33
delete and sequence (first/next) operations. The sequence
34
operation requires a backup database that supports the
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.
37
34
<b>MEMCACHE MAIN PARAMETERS</b>
38
35
<b>memcache (default: inet:localhost:11211)</b>
39
The memcache server (note: singular) that Postfix
40
will try to connect to. For a TCP server specify
41
"inet:" followed by a hostname or address, ":", and
42
a port name or number. Specify an IPv6 address
43
inside "[]". For a UNIX-domain server specify
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
44
40
"unix:" followed by the socket pathname. Examples:
46
42
memcache = inet:memcache.example.com:11211
48
44
memcache = inet:[fc00:8d00:189::3]:11211
49
45
memcache = unix:/path/to/socket
51
NOTE: to access a UNIX-domain socket with the <a href="proxymap.8.html">prox-</a>
52
<a href="proxymap.8.html">ymap(8)</a> server, the socket must be accessible by
53
the unprivileged postfix user.
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-
55
51
<b>backup (default: undefined)</b>
56
An optional Postfix database that provides persis-
57
tent backup for the memcache database. The Postfix
58
memcache client will update the memcache database
59
whenever it looks up or changes information in the
60
persistent database. Specify a Postfix "<a href="DATABASE_README.html">type:table</a>"
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>"
61
56
database. Examples:
63
58
# Non-shared postscreen cache.
64
backup = btree:/var/lib/postfix/<a href="postconf.5.html#postscreen_cache_map">postscreen_cache_map</a>
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>
66
61
# Shared postscreen cache for processes on the same host.
67
backup = <a href="proxymap.8.html">proxy</a>:btree:/var/lib/postfix/<a href="postconf.5.html#postscreen_cache_map">postscreen_cache_map</a>
69
Access to remote proxymap servers is under develop-
72
NOTE 1: When sharing a persistent <a href="postscreen.8.html"><b>postscreen</b>(8)</a> or
73
<a href="verify.8.html"><b>verify</b>(8)</a> cache, disable automatic cache cleanup
74
(set *_cache_cleanup_interval = 0) except with one
75
Postfix instance that will be responsible for cache
78
NOTE 2: When different tables share the same mem-
79
cache database, each table should use the <b>key_for-</b>
80
<b>mat</b> feature (see below) to prepend its own unique
81
string to the lookup key. Otherwise, automatic
82
<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
85
NOTE 3: When the backup database is accessed with
86
"<a href="proxymap.8.html">proxy</a>:" lookups, the full backup database name
87
(including the "<a href="proxymap.8.html">proxy</a>:" prefix) must be specified
88
in the proxymap server's <a href="postconf.5.html#proxy_read_maps">proxy_read_maps</a> or
89
<a href="postconf.5.html#proxy_write_maps">proxy_write_maps</a> setting (depending on whether the
90
access is read-only or read-write).
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>
64
Access to remote proxymap servers is under development.
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.
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.
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).
92
82
<b>flags (default: 0)</b>
93
Optional flags that should be stored along with a
94
memcache update. The flags are ignored when looking
83
Optional flags that should be stored along with a memcache
84
update. The flags are ignored when looking up information.
97
86
<b>ttl (default: 3600)</b>
98
87
The expiration time in seconds of memcache updates.
100
NOTE 1: When using a memcache table as
101
<a href="postscreen.8.html"><b>postscreen</b>(8)</a> or <a href="verify.8.html"><b>verify</b>(8)</a> cache without persistent
102
backup, specify a zero *_cache_cleanup_interval
103
value with all Postfix instances that use the mem-
104
cache, and specify the largest <a href="postscreen.8.html"><b>postscreen</b>(8)</a> *_ttl
105
value or <a href="verify.8.html"><b>verify</b>(8)</a> *_expire_time value as the mem-
106
cache table's <b>ttl</b> value.
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
108
NOTE 2: According to memcache protocol documenta-
109
tion, a value greater than 30 days (2592000 sec-
110
onds) specifies absolute UNIX time. Smaller values
111
are relative to the time of the update.
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.
113
100
<b>MEMCACHE KEY PARAMETERS</b>
114
101
<b>key_format (default: %s)</b>
115
Format of the lookup and update keys in memcache
116
requests. By default, these are the same as the
117
lookup and update keys that are given to the Post-
120
NOTE 1: The <b>key_format</b> feature is not used for
121
<b>backup</b> database requests.
123
NOTE 2: When different tables share the same mem-
124
cache database, each table should prepend its own
125
unique string to the lookup key. Otherwise, auto-
126
matic <a href="postscreen.8.html"><b>postscreen</b>(8)</a> or <a href="verify.8.html"><b>verify</b>(8)</a> cache cleanup may
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.
107
NOTE 1: The <b>key_format</b> feature is not used for <b>backup</b> database
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.
132
118
key_format = verify:%s
133
119
key_format = postscreen:%s
135
The <b>key_format</b> parameter supports the following '%'
121
The <b>key_format</b> parameter supports the following '%' expansions:
138
123
<b>%%</b> This is replaced by a literal '%' character.
140
<b>%s</b> This is replaced by the memcache client
143
<b>%u</b> When the input key is an address of the form
144
user@domain, <b>%u</b> is replaced by the SQL
145
quoted local part of the address. Other-
146
wise, <b>%u</b> is replaced by the entire search
147
string. If the localpart is empty, a lookup
148
is silently suppressed and returns no
149
results (an update is skipped with a warn-
152
<b>%d</b> When the input key is an address of the form
153
user@domain, <b>%d</b> is replaced by the domain
154
part of the address. Otherwise, a lookup is
155
silently suppressed and returns no results
156
(an update is skipped with a warning).
158
<b>%[SUD]</b> The upper-case equivalents of the above
159
expansions behave in the <b>key_format</b> parame-
160
ter identically to their lower-case counter-
163
<b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by
164
the corresponding most significant component
165
of the input key's domain. If the input key
166
is <i>user@mail.example.com</i>, then %1 is <b>com</b>, %2
167
is <b>example</b> and %3 is <b>mail</b>. If the input key
168
is unqualified or does not have enough
169
domain components to satisfy all the speci-
170
fied patterns, a lookup is silently sup-
171
pressed and returns no results (an update is
125
<b>%s</b> This is replaced by the memcache client input key.
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
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).
139
<b>%[SUD]</b> The upper-case equivalents of the above expansions behave
140
in the <b>key_format</b> parameter identically to their lower-
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
172
150
skipped with a warning).
174
152
<b>domain (default: no domain list)</b>
175
This feature can significantly reduce database
176
server load. Specify a list of domain names, paths
177
to files, or "<a href="DATABASE_README.html">type:table</a>" databases. When speci-
178
fied, only fully qualified search keys with a *non-
179
empty* localpart and a matching domain are eligible
180
for lookup or update: bare 'user' lookups, bare
181
domain lookups and "@domain" lookups are silently
182
skipped (updates are skipped with a warning).
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:
185
domain = example.com, hash:/etc/postfix/searchdomains
161
domain = example.com, <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/searchdomains
187
163
<b>MEMCACHE ERROR CONTROLS</b>
188
164
<b>data_size_limit (default: 10240)</b>
192
168
The maximal memcache reply line length in bytes.
194
170
<b>max_try (default: 2)</b>
195
The number of times to try a memcache command
196
before giving up. The memcache client does not
197
retry a command when the memcache server accepts no
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.
200
175
<b>retry_pause (default: 1)</b>
201
The time in seconds before retrying a failed mem-
176
The time in seconds before retrying a failed memcache command.
204
178
<b>timeout (default: 2)</b>
205
The time limit for sending a memcache command and
206
for receiving a memcache reply.
179
The time limit for sending a memcache command and for receiving
209
The Postfix memcache client cannot be used for security-
210
sensitive tables such as <b><a href="postconf.5.html#alias_maps">alias_maps</a></b> (these may contain
211
"<i>|command</i> and "<i>/file/name</i>" destinations), or <b><a href="postconf.5.html#virtual_uid_maps">vir</a>-</b>
212
<b><a href="postconf.5.html#virtual_uid_maps">tual_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_mailbox_maps</a></b>
213
(these specify UNIX process privileges or "<i>/file/name</i>"
214
destinations). In a typical deployment a memcache data-
215
base is writable by any process that can talk to the mem-
216
cache server; in contrast, security-sensitive tables must
217
never be writable by the unprivileged Postfix user.
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-
219
The Postfix memcache client requires additional configura-
220
tion 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
221
details see the <b>backup</b> and <b>ttl</b> parameter discussions in
222
the MEMCACHE MAIN PARAMETERS section above.
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
225
198
<a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager