summaryrefslogtreecommitdiffstats
path: root/man/man5/memcache_table.5
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man/man5/memcache_table.5259
1 files changed, 259 insertions, 0 deletions
diff --git a/man/man5/memcache_table.5 b/man/man5/memcache_table.5
new file mode 100644
index 0000000..430f73c
--- /dev/null
+++ b/man/man5/memcache_table.5
@@ -0,0 +1,259 @@
+.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