259 lines
8.4 KiB
Groff
259 lines
8.4 KiB
Groff
.TH MEMCACHE_TABLE 5
|
|
.ad
|
|
.fi
|
|
.SH NAME
|
|
memcache_table
|
|
\-
|
|
Postfix memcache client configuration
|
|
.SH "SYNOPSIS"
|
|
.na
|
|
.nf
|
|
\fBpostmap \-q "\fIstring\fB" memcache:/etc/postfix/\fIfilename\fR
|
|
|
|
\fBpostmap \-q \- memcache:/etc/postfix/\fIfilename\fB <\fIinputfile\fR
|
|
.SH DESCRIPTION
|
|
.ad
|
|
.fi
|
|
The Postfix mail system uses optional tables for address
|
|
rewriting or mail routing. These tables are usually in
|
|
\fBdbm\fR or \fBdb\fR format.
|
|
|
|
Alternatively, lookup tables can be specified as memcache
|
|
instances. To use memcache lookups, define a memcache
|
|
source as a lookup table in main.cf, for example:
|
|
|
|
.nf
|
|
virtual_alias_maps = memcache:/etc/postfix/memcache\-aliases.cf
|
|
.fi
|
|
|
|
The file /etc/postfix/memcache\-aliases.cf has the same
|
|
format as the Postfix main.cf 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.
|
|
.SH "MEMCACHE MAIN PARAMETERS"
|
|
.na
|
|
.nf
|
|
.ad
|
|
.fi
|
|
.IP "\fBmemcache (default: inet:localhost:11211)\fR"
|
|
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:
|
|
|
|
.nf
|
|
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
|
|
.fi
|
|
|
|
NOTE: to access a UNIX\-domain socket with the proxymap(8)
|
|
server, the socket must be accessible by the unprivileged
|
|
postfix user.
|
|
.IP "\fBbackup (default: undefined)\fR"
|
|
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
|
|
information in the persistent database. Specify a Postfix
|
|
"type:table" database. Examples:
|
|
|
|
.nf
|
|
# Non\-shared postscreen cache.
|
|
backup = btree:/var/lib/postfix/postscreen_cache_map
|
|
|
|
# Shared postscreen cache for processes on the same host.
|
|
backup = proxy:btree:/var/lib/postfix/postscreen_cache_map
|
|
.fi
|
|
|
|
Access to remote proxymap servers is under development.
|
|
|
|
NOTE 1: When sharing a persistent \fBpostscreen\fR(8) or
|
|
\fBverify\fR(8) 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 \fBkey_format\fR feature
|
|
(see below) to prepend its own unique string to the lookup
|
|
key. Otherwise, automatic \fBpostscreen\fR(8) or \fBverify\fR(8)
|
|
cache cleanup may not work.
|
|
|
|
NOTE 3: When the backup database is accessed with "proxy:"
|
|
lookups, the full backup database name (including the
|
|
"proxy:" prefix) must be specified in the proxymap server's
|
|
proxy_read_maps or proxy_write_maps setting (depending on
|
|
whether the access is read\-only or read\-write).
|
|
.IP "\fBflags (default: 0)\fR"
|
|
Optional flags that should be stored along with a memcache
|
|
update. The flags are ignored when looking up information.
|
|
.IP "\fBttl (default: 3600)\fR"
|
|
The expiration time in seconds of memcache updates.
|
|
|
|
NOTE 1: When using a memcache table as \fBpostscreen\fR(8)
|
|
or \fBverify\fR(8) cache without persistent backup, specify
|
|
a zero *_cache_cleanup_interval value with all Postfix
|
|
instances that use the memcache, and specify the largest
|
|
\fBpostscreen\fR(8) *_ttl value or \fBverify\fR(8) *_expire_time
|
|
value as the memcache table's \fBttl\fR 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.
|
|
.SH "MEMCACHE KEY PARAMETERS"
|
|
.na
|
|
.nf
|
|
.ad
|
|
.fi
|
|
.IP "\fBkey_format (default: %s)\fB"
|
|
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 \fBkey_format\fR feature is not used for \fBbackup\fR
|
|
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 \fBpostscreen\fR(8)
|
|
or \fBverify\fR(8) cache cleanup may not work.
|
|
|
|
Examples:
|
|
|
|
.nf
|
|
key_format = aliases:%s
|
|
key_format = verify:%s
|
|
key_format = postscreen:%s
|
|
.fi
|
|
|
|
The \fBkey_format\fR parameter supports the following '%'
|
|
expansions:
|
|
.RS
|
|
.IP "\fB%%\fR"
|
|
This is replaced by a literal '%' character.
|
|
.IP "\fB%s\fR"
|
|
This is replaced by the memcache client input key.
|
|
.IP "\fB%u\fR"
|
|
When the input key is an address of the form user@domain,
|
|
\fB%u\fR is replaced by the SQL quoted local part of the
|
|
address. Otherwise, \fB%u\fR 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).
|
|
.IP "\fB%d\fR"
|
|
When the input key is an address of the form user@domain,
|
|
\fB%d\fR is replaced by the domain part of the address.
|
|
Otherwise, a lookup is silently suppressed and returns no
|
|
results (an update is skipped with a warning).
|
|
.IP "\fB%[SUD]\fR"
|
|
The upper\-case equivalents of the above expansions behave
|
|
in the \fBkey_format\fR parameter identically to their
|
|
lower\-case counter\-parts.
|
|
.IP "\fB%[1\-9]\fR"
|
|
The patterns %1, %2, ... %9 are replaced by the corresponding
|
|
most significant component of the input key's domain. If
|
|
the input key is \fIuser@mail.example.com\fR, then %1 is
|
|
\fBcom\fR, %2 is \fBexample\fR and %3 is \fBmail\fR. 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).
|
|
.RE
|
|
.IP "\fBdomain (default: no domain list)\fR"
|
|
This feature can significantly reduce database server load.
|
|
Specify a list of domain names, paths to files, or "type:table"
|
|
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:
|
|
|
|
.nf
|
|
domain = example.com, hash:/etc/postfix/searchdomains
|
|
.fi
|
|
.SH "MEMCACHE ERROR CONTROLS"
|
|
.na
|
|
.nf
|
|
.ad
|
|
.fi
|
|
.IP "\fBdata_size_limit (default: 10240)\fR"
|
|
The maximal memcache reply data length in bytes.
|
|
.IP "\fBline_size_limit (default: 1024)\fR"
|
|
The maximal memcache reply line length in bytes.
|
|
.IP "\fBmax_try (default: 2)\fR"
|
|
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.
|
|
.IP "\fBretry_pause (default: 1)\fR"
|
|
The time in seconds before retrying a failed memcache command.
|
|
.IP "\fBtimeout (default: 2)\fR"
|
|
The time limit for sending a memcache command and for
|
|
receiving a memcache reply.
|
|
.SH BUGS
|
|
.ad
|
|
.fi
|
|
The Postfix memcache client cannot be used for security\-sensitive
|
|
tables such as \fBalias_maps\fR (these may contain
|
|
"\fI|command\fR and "\fI/file/name\fR" destinations), or
|
|
\fBvirtual_uid_maps\fR, \fBvirtual_gid_maps\fR and
|
|
\fBvirtual_mailbox_maps\fR (these specify UNIX process
|
|
privileges or "\fI/file/name\fR" destinations). In a typical
|
|
deployment a memcache database is writable by any process
|
|
that can talk to the memcache server; in contrast,
|
|
security\-sensitive tables must never be writable by the
|
|
unprivileged Postfix user.
|
|
|
|
The Postfix memcache client requires additional configuration
|
|
when used as \fBpostscreen\fR(8) or \fBverify\fR(8) cache.
|
|
For details see the \fBbackup\fR and \fBttl\fR parameter
|
|
discussions in the MEMCACHE MAIN PARAMETERS section above.
|
|
.SH "SEE ALSO"
|
|
.na
|
|
.nf
|
|
postmap(1), Postfix lookup table manager
|
|
postconf(5), configuration parameters
|
|
.SH "README FILES"
|
|
.na
|
|
.nf
|
|
.ad
|
|
.fi
|
|
Use "\fBpostconf readme_directory\fR" or
|
|
"\fBpostconf html_directory\fR" to locate this information.
|
|
.na
|
|
.nf
|
|
DATABASE_README, Postfix lookup table overview
|
|
MEMCACHE_README, Postfix memcache client guide
|
|
.SH "LICENSE"
|
|
.na
|
|
.nf
|
|
.ad
|
|
.fi
|
|
The Secure Mailer license must be distributed with this software.
|
|
.SH HISTORY
|
|
.ad
|
|
.fi
|
|
.ad
|
|
.fi
|
|
Memcache support was introduced with Postfix version 2.9.
|
|
.SH "AUTHOR(S)"
|
|
.na
|
|
.nf
|
|
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
|