xref: /src/external/ibm-public/postfix/dist/proto/memcache_table

#++
# 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
#	\fBlmdb:\fR, \fBcdb:\fR, \fBhash:\fR, or \fBdbm:\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_digest (default: empty)\fB"
#	After processing the \fBkey_format\fR setting, and before sending
#	a request to the memcache server, run the key through the named
#	message digest algorithm and convert the result to lowercase
#	hexadecimal characters. This prevents a database access error
#	when keys may exceed the memcache server's key length limit
#	(usually, 250 bytes). Specify the name of a message digest
#	algorithm that is supported by OpenSSL, for example, \fBsha256\fR.
#
#	This feature is available in Postfix 3.11 and later, and requires
#	that Postfix is built with TLS support.
# .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 (a] 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 for "\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
#--