1MEMCACHE_TABLE(5)             File Formats Manual            MEMCACHE_TABLE(5)
2
3
4

NAME

6       memcache_table - Postfix memcache client configuration
7

SYNOPSIS

9       postmap -q "string" memcache:/etc/postfix/filename
10
11       postmap -q - memcache:/etc/postfix/filename <inputfile
12

DESCRIPTION

14       The  Postfix  mail system uses optional tables for address rewriting or
15       mail routing. These tables are usually in dbm or db format.
16
17       Alternatively, lookup tables can be specified  as  memcache  instances.
18       To  use memcache lookups, define a memcache source as a lookup table in
19       main.cf, for example:
20
21           virtual_alias_maps = memcache:/etc/postfix/memcache-aliases.cf
22
23       The file /etc/postfix/memcache-aliases.cf has the same  format  as  the
24       Postfix main.cf file, and specifies the parameters described below.
25
26       The  Postfix  memcache  client  supports the lookup, update, delete and
27       sequence (first/next) operations. The  sequence  operation  requires  a
28       backup database that supports the operation.
29

MEMCACHE MAIN PARAMETERS

31       memcache (default: inet:localhost:11211)
32              The  memcache  server  (note: singular) that Postfix will try to
33              connect to.  For a TCP server  specify  "inet:"  followed  by  a
34              hostname or address, ":", and a port name or number.  Specify an
35              IPv6 address inside "[]".   For  a  UNIX-domain  server  specify
36              "unix:" followed by the socket pathname. Examples:
37
38                  memcache = inet:memcache.example.com:11211
39                  memcache = inet:127.0.0.1:11211
40                  memcache = inet:[fc00:8d00:189::3]:11211
41                  memcache = unix:/path/to/socket
42
43              NOTE:  to  access  a  UNIX-domain  socket  with  the proxymap(8)
44              server, the socket must be accessible by the unprivileged  post‐
45              fix user.
46
47       backup (default: undefined)
48              An optional Postfix database that provides persistent backup for
49              the memcache database. The Postfix memcache client  will  update
50              the  memcache  database whenever it looks up or changes informa‐
51              tion in the persistent database. Specify a Postfix  "type:table"
52              database. Examples:
53
54                  # Non-shared postscreen cache.
55                  backup = btree:/var/lib/postfix/postscreen_cache_map
56
57                  # Shared postscreen cache for processes on the same host.
58                  backup = proxy:btree:/var/lib/postfix/postscreen_cache_map
59
60              Access to remote proxymap servers is under development.
61
62              NOTE  1:  When  sharing  a persistent postscreen(8) or verify(8)
63              cache,     disable     automatic     cache     cleanup      (set
64              *_cache_cleanup_interval  =  0) except with one Postfix instance
65              that will be responsible for cache cleanup.
66
67              NOTE 2: When different tables share the same memcache  database,
68              each  table  should  use  the  key_format feature (see below) to
69              prepend its own unique string to  the  lookup  key.   Otherwise,
70              automatic postscreen(8) or verify(8) cache cleanup may not work.
71
72              NOTE  3:  When  the  backup  database  is accessed with "proxy:"
73              lookups, the full backup database name (including  the  "proxy:"
74              prefix)   must   be   specified   in   the   proxymap   server's
75              proxy_read_maps  or  proxy_write_maps  setting   (depending   on
76              whether the access is read-only or read-write).
77
78       flags (default: 0)
79              Optional  flags  that  should  be  stored  along with a memcache
80              update. The flags are ignored when looking up information.
81
82       ttl (default: 3600)
83              The expiration time in seconds of memcache updates.
84
85              NOTE 1: When using a memcache table  as  postscreen(8)  or  ver‐
86              ify(8)   cache   without   persistent  backup,  specify  a  zero
87              *_cache_cleanup_interval value with all Postfix  instances  that
88              use  the  memcache,  and specify the largest postscreen(8) *_ttl
89              value or verify(8) *_expire_time value as the  memcache  table's
90              ttl value.
91
92              NOTE  2:  According  to memcache protocol documentation, a value
93              greater than 30 days (2592000 seconds) specifies  absolute  UNIX
94              time. Smaller values are relative to the time of the update.
95

MEMCACHE KEY PARAMETERS

97       key_format (default: %s)
98              Format  of  the lookup and update keys in memcache requests.  By
99              default, these are the same as the lookup and update  keys  that
100              are given to the Postfix memcache client.
101
102              NOTE  1:  The key_format feature is not used for backup database
103              requests.
104
105              NOTE 2: When different tables share the same memcache  database,
106              each  table  should  prepend its own unique string to the lookup
107              key.  Otherwise,  automatic  postscreen(8)  or  verify(8)  cache
108              cleanup may not work.
109
110              Examples:
111
112                  key_format = aliases:%s
113                  key_format = verify:%s
114                  key_format = postscreen:%s
115
116              The key_format parameter supports the following '%' expansions:
117
118              %%     This is replaced by a literal '%' character.
119
120              %s     This is replaced by the memcache client input key.
121
122              %u     When the input key is an address of the form user@domain,
123                     %u is replaced by  the  SQL  quoted  local  part  of  the
124                     address.   Otherwise, %u is replaced by the entire search
125                     string.  If the localpart is empty, a lookup is  silently
126                     suppressed  and  returns no results (an update is skipped
127                     with a warning).
128
129              %d     When the input key is an address of the form user@domain,
130                     %d is replaced by the domain part of the address.  Other‐
131                     wise, a lookup is  silently  suppressed  and  returns  no
132                     results (an update is skipped with a warning).
133
134              %[SUD] The upper-case equivalents of the above expansions behave
135                     in the key_format parameter identically to  their  lower-
136                     case counter-parts.
137
138              %[1-9] The  patterns  %1,  %2, ... %9 are replaced by the corre‐
139                     sponding most significant component of  the  input  key's
140                     domain.  If  the input key is user@mail.example.com, then
141                     %1 is com, %2 is example and %3 is mail. If the input key
142                     is  unqualified or does not have enough domain components
143                     to satisfy  all  the  specified  patterns,  a  lookup  is
144                     silently  suppressed and returns no results (an update is
145                     skipped with a warning).
146
147       domain (default: no domain list)
148              This feature can  significantly  reduce  database  server  load.
149              Specify  a list of domain names, paths to files, or "type:table"
150              databases.  When specified, only  fully  qualified  search  keys
151              with  a *non-empty* localpart and a matching domain are eligible
152              for lookup or update: bare 'user' lookups, bare  domain  lookups
153              and  "@domain" lookups are silently skipped (updates are skipped
154              with a warning).  Example:
155
156                  domain = example.com, hash:/etc/postfix/searchdomains
157

MEMCACHE ERROR CONTROLS

159       data_size_limit (default: 10240)
160              The maximal memcache reply data length in bytes.
161
162       line_size_limit (default: 1024)
163              The maximal memcache reply line length in bytes.
164
165       max_try (default: 2)
166              The number of times to try a memcache command before giving  up.
167              The  memcache  client does not retry a command when the memcache
168              server accepts no connection.
169
170       retry_pause (default: 1)
171              The time in seconds before retrying a failed memcache command.
172
173       timeout (default: 2)
174              The time limit for sending a memcache command and for  receiving
175              a memcache reply.
176

BUGS

178       The  Postfix  memcache  client  cannot  be  used for security-sensitive
179       tables such as alias_maps (these may contain "|command and "/file/name"
180       destinations),  or virtual_uid_maps, virtual_gid_maps and virtual_mail‐
181       box_maps (these specify UNIX process privileges or "/file/name"  desti‐
182       nations).   In  a typical deployment a memcache database is writable by
183       any process that can talk to the memcache server;  in  contrast,  secu‐
184       rity-sensitive  tables must never be writable by the unprivileged Post‐
185       fix user.
186
187       The Postfix memcache client requires additional configuration when used
188       as  postscreen(8)  or  verify(8) cache.  For details see the backup and
189       ttl parameter discussions  in  the  MEMCACHE  MAIN  PARAMETERS  section
190       above.
191

SEE ALSO

193       postmap(1), Postfix lookup table manager
194       postconf(5), configuration parameters
195

README FILES

197       Use  "postconf readme_directory" or "postconf html_directory" to locate
198       this information.
199       DATABASE_README, Postfix lookup table overview
200       MEMCACHE_README, Postfix memcache client guide
201

LICENSE

203       The Secure Mailer license must be distributed with this software.
204

HISTORY

206       Memcache support was introduced with Postfix version 2.9.
207

AUTHOR(S)

209       Wietse Venema
210       IBM T.J. Watson Research
211       P.O. Box 704
212       Yorktown Heights, NY 10598, USA
213
214
215
216                                                             MEMCACHE_TABLE(5)
Impressum