1#++ 2# NAME 3# memcache_table 5 4# SUMMARY 5# Postfix memcache client configuration 6# SYNOPSIS 7# \fBpostmap -q "\fIstring\fB" memcache:/etc/postfix/\fIfilename\fR 8# 9# \fBpostmap -q - memcache:/etc/postfix/\fIfilename\fB <\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 multiple 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 that the Postfix 107# memcache client sends to the memcache server. 108# By default, these are the same as the lookup and update 109# keys that the memcache client receives from Postfix 110# applications. 111# 112# NOTE 1: The \fBkey_format\fR feature is not used for \fBbackup\fR 113# database requests. 114# 115# NOTE 2: When multiple tables share the same memcache 116# database, each table should prepend its own unique string 117# to the lookup key. Otherwise, automatic \fBpostscreen\fR(8) 118# or \fBverify\fR(8) cache cleanup may not work. 119# 120# Examples: 121# 122# .nf 123# key_format = aliases:%s 124# key_format = verify:%s 125# key_format = postscreen:%s 126# .fi 127# 128# The \fBkey_format\fR parameter supports the following '%' 129# expansions: 130# .RS 131# .IP "\fB%%\fR" 132# This is replaced by a literal '%' character. 133# .IP "\fB%s\fR" 134# This is replaced by the memcache client input key. 135# .IP "\fB%u\fR" 136# When the input key is an address of the form user@domain, 137# \fB%u\fR is replaced by the SQL quoted local part of the 138# address. Otherwise, \fB%u\fR is replaced by the entire 139# search string. If the localpart is empty, a lookup is 140# silently suppressed and returns no results (an update is 141# skipped with a warning). 142# .IP "\fB%d\fR" 143# When the input key is an address of the form user@domain, 144# \fB%d\fR is replaced by the domain part of the address. 145# Otherwise, a lookup is silently suppressed and returns no 146# results (an update is skipped with a warning). 147# .IP "\fB%[SUD]\fR" 148# The upper-case equivalents of the above expansions behave 149# in the \fBkey_format\fR parameter identically to their 150# lower-case counter-parts. 151# .IP "\fB%[1-9]\fR" 152# The patterns %1, %2, ... %9 are replaced by the corresponding 153# most significant component of the input key's domain. If 154# the input key is \fIuser@mail.example.com\fR, then %1 is 155# \fBcom\fR, %2 is \fBexample\fR and %3 is \fBmail\fR. If the 156# input key is unqualified or does not have enough domain 157# components to satisfy all the specified patterns, a lookup 158# is silently suppressed and returns no results (an update 159# is skipped with a warning). 160# .RE 161# .IP "\fBdomain (default: no domain list)\fR" 162# This feature can significantly reduce database server load. 163# Specify a list of domain names, paths to files, or "type:table" 164# databases. 165# When specified, only fully qualified search keys with a 166# *non-empty* localpart and a matching domain are eligible 167# for lookup or update: bare 'user' lookups, bare domain 168# lookups and "@domain" lookups are silently skipped (updates 169# are skipped with a warning). Example: 170# 171# .nf 172# domain = example.com, hash:/etc/postfix/searchdomains 173# .fi 174# MEMCACHE ERROR CONTROLS 175# .ad 176# .fi 177# .IP "\fBdata_size_limit (default: 10240)\fR" 178# The maximal memcache reply data length in bytes. 179# .IP "\fBline_size_limit (default: 1024)\fR" 180# The maximal memcache reply line length in bytes. 181# .IP "\fBmax_try (default: 2)\fR" 182# The number of times to try a memcache command before giving 183# up. The memcache client does not retry a command when the 184# memcache server accepts no connection. 185# .IP "\fBretry_pause (default: 1)\fR" 186# The time in seconds before retrying a failed memcache command. 187# .IP "\fBtimeout (default: 2)\fR" 188# The time limit for sending a memcache command and for 189# receiving a memcache reply. 190# BUGS 191# The Postfix memcache client cannot be used for security-sensitive 192# tables such as \fBalias_maps\fR (these may contain 193# "\fI|command\fR and "\fI/file/name\fR" destinations), or 194# \fBvirtual_uid_maps\fR, \fBvirtual_gid_maps\fR and 195# \fBvirtual_mailbox_maps\fR (these specify UNIX process 196# privileges or "\fI/file/name\fR" destinations). In a typical 197# deployment a memcache database is writable by any process 198# that can talk to the memcache server; in contrast, 199# security-sensitive tables must never be writable by the 200# unprivileged Postfix user. 201# 202# The Postfix memcache client requires additional configuration 203# when used as \fBpostscreen\fR(8) or \fBverify\fR(8) cache. 204# For details see the \fBbackup\fR and \fBttl\fR parameter 205# discussions in the MEMCACHE MAIN PARAMETERS section above. 206# SEE ALSO 207# postmap(1), Postfix lookup table manager 208# postconf(5), configuration parameters 209# README FILES 210# .ad 211# .fi 212# Use "\fBpostconf readme_directory\fR" or 213# "\fBpostconf html_directory\fR" to locate this information. 214# .na 215# .nf 216# DATABASE_README, Postfix lookup table overview 217# MEMCACHE_README, Postfix memcache client guide 218# LICENSE 219# .ad 220# .fi 221# The Secure Mailer license must be distributed with this software. 222# HISTORY 223# .ad 224# .fi 225# Memcache support was introduced with Postfix version 2.9. 226# AUTHOR(S) 227# Wietse Venema 228# IBM T.J. Watson Research 229# P.O. Box 704 230# Yorktown Heights, NY 10598, USA 231# 232# Wietse Venema 233# Google, Inc. 234# 111 8th Avenue 235# New York, NY 10011, USA 236#-- 237