diff options
Diffstat (limited to 'proto/memcache_table')
| -rw-r--r-- | proto/memcache_table | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/proto/memcache_table b/proto/memcache_table new file mode 100644 index 0000000..c97a9b4 --- /dev/null +++ b/proto/memcache_table @@ -0,0 +1,236 @@ +#++ +# NAME +# memcache_table 5 +# SUMMARY +# Postfix memcache client configuration +# SYNOPSIS +# \fBpostmap -q "\fIstring\fB" memcache:/etc/postfix/\fIfilename\fR +# +# \fBpostmap -q - memcache:/etc/postfix/\fIfilename\fB <\fIinputfile\fR +# DESCRIPTION +# 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. +# MEMCACHE MAIN PARAMETERS +# .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. +# MEMCACHE KEY PARAMETERS +# .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 +# MEMCACHE ERROR CONTROLS +# .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. +# BUGS +# 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. +# SEE ALSO +# postmap(1), Postfix lookup table manager +# postconf(5), configuration parameters +# README FILES +# .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 +# LICENSE +# .ad +# .fi +# The Secure Mailer license must be distributed with this software. +# HISTORY +# .ad +# .fi +# Memcache support was introduced with Postfix version 2.9. +# AUTHOR(S) +# 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 +#-- |