1#++ 2# NAME 3# memcache_table 5 4# SUMMARY 5# Postfix memcache client configuration 6# SYNOPSIS 7# \fBpostmap -q "\fIstring\fB" memcache:/etc/postfix/filename\fR 8# 9# \fBpostmap -q - memcache:/etc/postfix/\fIfilename\fR <\fIinputfile\fR 10# DESCRIPTION 11# The Postfix mail system uses optional tables for address 12# rewriting or mail routing. These tables are usually in 13# \fBdbm\fR or \fBdb\fR format. 14# 15# Alternatively, lookup tables can be specified as memcache 16# instances. To use memcache lookups, define a memcache 17# source as a lookup table in main.cf, for example: 18# 19# .nf 20# virtual_alias_maps = memcache:/etc/postfix/memcache-aliases.cf 21# .fi 22# 23# The file /etc/postfix/memcache-aliases.cf has the same 24# format as the Postfix main.cf file, and specifies the 25# parameters described below. 26# 27# The Postfix memcache client supports the lookup, update, 28# delete and sequence (first/next) operations. The sequence 29# operation requires a backup database that supports the 30# operation. 31# MEMCACHE MAIN PARAMETERS 32# .ad 33# .fi 34# .IP "\fBmemcache (default: inet:localhost:11211)\fR" 35# The memcache server (note: singular) that Postfix will try 36# to connect to. For a TCP server specify "inet:" followed by 37# a hostname or address, ":", and a port name or number. 38# Specify an IPv6 address inside "[]". 39# For a UNIX-domain server specify "unix:" followed by the 40# socket pathname. Examples: 41# 42# .nf 43# memcache = inet:memcache.example.com:11211 44# memcache = inet:127.0.0.1:11211 45# memcache = inet:[fc00:8d00:189::3]:11211 46# memcache = unix:/path/to/socket 47# .fi 48# 49# NOTE: to access a UNIX-domain socket with the proxymap(8) 50# server, the socket must be accessible by the unprivileged 51# postfix user. 52# .IP "\fBbackup (default: undefined)\fR" 53# An optional Postfix database that provides persistent backup 54# for the memcache database. The Postfix memcache client will 55# update the memcache database whenever it looks up or changes 56# information in the persistent database. Specify a Postfix 57# "type:table" database. Examples: 58# 59# .nf 60# # Non-shared postscreen cache. 61# backup = btree:/var/lib/postfix/postscreen_cache_map 62# 63# # Shared postscreen cache for processes on the same host. 64# backup = proxy:btree:/var/lib/postfix/postscreen_cache_map 65# .fi 66# 67# Access to remote proxymap servers is under development. 68# 69# NOTE 1: When sharing a persistent \fBpostscreen\fR(8) or 70# \fBverify\fR(8) cache, disable automatic cache cleanup (set 71# *_cache_cleanup_interval = 0) except with one Postfix 72# instance that will be responsible for cache cleanup. 73# 74# NOTE 2: When different tables share the same memcache 75# database, each table should use the \fBkey_format\fR feature 76# (see below) to prepend its own unique string to the lookup 77# key. Otherwise, automatic \fBpostscreen\fR(8) or \fBverify\fR(8) 78# cache cleanup may not work. 79# 80# NOTE 3: When the backup database is accessed with "proxy:" 81# lookups, the full backup database name (including the 82# "proxy:" prefix) must be specified in the proxymap server's 83# proxy_read_maps or proxy_write_maps setting (depending on 84# whether the access is read-only or read-write). 85# .IP "\fBflags (default: 0)\fR" 86# Optional flags that should be stored along with a memcache 87# update. The flags are ignored when looking up information. 88# .IP "\fBttl (default: 3600)\fR" 89# The expiration time in seconds of memcache updates. 90# 91# NOTE 1: When using a memcache table as \fBpostscreen\fR(8) 92# or \fBverify\fR(8) cache without persistent backup, specify 93# a zero *_cache_cleanup_interval value with all Postfix 94# instances that use the memcache, and specify the largest 95# \fBpostscreen\fR(8) *_ttl value or \fBverify\fR(8) *_expire_time 96# value as the memcache table's \fBttl\fR value. 97# 98# NOTE 2: According to memcache protocol documentation, a 99# value greater than 30 days (2592000 seconds) specifies 100# absolute UNIX 101# time. Smaller values are relative to the time of the update. 102# MEMCACHE KEY PARAMETERS 103# .ad 104# .fi 105# .IP "\fBkey_format (default: %s)\fB" 106# Format of the lookup and update keys in memcache requests. 107# By default, these are the same as the lookup and update 108# keys that are given to the Postfix memcache client. 109# 110# NOTE 1: The \fBkey_format\fR feature is not used for \fBbackup\fR 111# database requests. 112# 113# NOTE 2: When different tables share the same memcache 114# database, each table should prepend its own unique string 115# to the lookup key. Otherwise, automatic \fBpostscreen\fR(8) 116# or \fBverify\fR(8) cache cleanup may not work. 117# 118# Examples: 119# 120# .nf 121# key_format = aliases:%s 122# key_format = verify:%s 123# key_format = postscreen:%s 124# .fi 125# 126# The \fBkey_format\fR parameter supports the following '%' 127# expansions: 128# .RS 129# .IP "\fB\fB%%\fR\fR" 130# This is replaced by a literal '%' character. 131# .IP "\fB\fB%s\fR\fR" 132# This is replaced by the memcache client input key. 133# .IP "\fB\fB%u\fR\fR" 134# When the input key is an address of the form user@domain, 135# \fB%u\fR is replaced by the SQL quoted local part of the 136# address. Otherwise, \fB%u\fR is replaced by the entire 137# search string. If the localpart is empty, a lookup is 138# silently suppressed and returns no results (an update is 139# skipped with a warning). 140# .IP "\fB\fB%d\fR\fR" 141# When the input key is an address of the form user@domain, 142# \fB%d\fR is replaced by the domain part of the address. 143# Otherwise, a lookup is silently suppressed and returns no 144# results (an update is skipped with a warning). 145# .IP "\fB\fB%[SUD]\fR\fR" 146# The upper-case equivalents of the above expansions behave 147# in the \fBkey_format\fR parameter identically to their 148# lower-case counter-parts. 149# .IP "\fB\fB%[1-9]\fR\fR" 150# The patterns %1, %2, ... %9 are replaced by the corresponding 151# most significant component of the input key's domain. If 152# the input key is \fIuser@mail.example.com\fR, then %1 is 153# \fBcom\fR, %2 is \fBexample\fR and %3 is \fBmail\fR. If the 154# input key is unqualified or does not have enough domain 155# components to satisfy all the specified patterns, a lookup 156# is silently suppressed and returns no results (an update 157# is skipped with a warning). 158# .RE 159# .IP "\fBdomain (default: no domain list)\fR" 160# This feature can significantly reduce database server load. 161# Specify a list of domain names, paths to files, or "type:table" 162# databases. 163# When specified, only fully qualified search keys with a 164# *non-empty* localpart and a matching domain are eligible 165# for lookup or update: bare 'user' lookups, bare domain 166# lookups and "@domain" lookups are silently skipped (updates 167# are skipped with a warning). Example: 168# 169# .nf 170# domain = example.com, hash:/etc/postfix/searchdomains 171# .fi 172# MEMCACHE ERROR CONTROLS 173# .ad 174# .fi 175# .IP "\fBdata_size_limit (default: 10240)\fR" 176# The maximal memcache reply data length in bytes. 177# .IP "\fBline_size_limit (default: 1024)\fR" 178# The maximal memcache reply line length in bytes. 179# .IP "\fBmax_try (default: 2)\fR" 180# The number of times to try a memcache command before giving 181# up. The memcache client does not retry a command when the 182# memcache server accepts no connection. 183# .IP "\fBretry_pause (default: 1)\fR" 184# The time in seconds before retrying a failed memcache command. 185# .IP "\fBtimeout (default: 2)\fR" 186# The time limit for sending a memcache command and for 187# receiving a memcache reply. 188# BUGS 189# The Postfix memcache client cannot be used for security-sensitive 190# tables such as \fBalias_maps\fR (these may contain 191# "\fI|command\fR and "\fI/file/name\fR" destinations), or 192# \fBvirtual_uid_maps\fR, \fBvirtual_gid_maps\fR and 193# \fBvirtual_mailbox_maps\fR (these specify UNIX process 194# privileges or "\fI/file/name\fR" destinations). In a typical 195# deployment a memcache database is writable by any process 196# that can talk to the memcache server; in contrast, 197# security-sensitive tables must never be writable by the 198# unprivileged Postfix user. 199# 200# The Postfix memcache client requires additional configuration 201# when used as \fBpostscreen\fR(8) or \fBverify\fR(8) cache. 202# For details see the \fBbackup\fR and \fBttl\fR parameter 203# discussions in the MEMCACHE MAIN PARAMETERS section above. 204# SEE ALSO 205# postmap(1), Postfix lookup table manager 206# postconf(5), configuration parameters 207# README FILES 208# .ad 209# .fi 210# Use "\fBpostconf readme_directory\fR" or 211# "\fBpostconf html_directory\fR" to locate this information. 212# .na 213# .nf 214# DATABASE_README, Postfix lookup table overview 215# MEMCACHE_README, Postfix memcache client guide 216# LICENSE 217# .ad 218# .fi 219# The Secure Mailer license must be distributed with this software. 220# HISTORY 221# .ad 222# .fi 223# Memcache support was introduced with Postfix version 2.9. 224# AUTHOR(S) 225# Wietse Venema 226# IBM T.J. Watson Research 227# P.O. Box 704 228# Yorktown Heights, NY 10598, USA 229#-- 230