Adding upstream version 3.4.23.upstream/3.4.23upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 243 insertions, 0 deletions

diff --git a/man/man8/proxymap.8 b/man/man8/proxymap.8
new file mode 100644
index 0000000..e734a2b
--- /dev/null
+++ b/man/man8/proxymap.8
@@ -0,0 +1,243 @@
+.TH PROXYMAP 8 
+.ad
+.fi
+.SH NAME
+proxymap
+\-
+Postfix lookup table proxy server
+.SH "SYNOPSIS"
+.na
+.nf
+\fBproxymap\fR [generic Postfix daemon options]
+.SH DESCRIPTION
+.ad
+.fi
+The \fBproxymap\fR(8) server provides read\-only or read\-write
+table lookup service to Postfix processes. These services are
+implemented with distinct service names: \fBproxymap\fR and
+\fBproxywrite\fR, respectively. The purpose of these services is:
+.IP \(bu
+To overcome chroot restrictions. For example, a chrooted SMTP
+server needs access to the system passwd file in order to
+reject mail for non\-existent local addresses, but it is not
+practical to maintain a copy of the passwd file in the chroot
+jail.  The solution:
+.sp
+.nf
+local_recipient_maps =
+    proxy:unix:passwd.byname $alias_maps
+.fi
+.IP \(bu
+To consolidate the number of open lookup tables by sharing
+one open table among multiple processes. For example, making
+mysql connections from every Postfix daemon process results
+in "too many connections" errors. The solution:
+.sp
+.nf
+virtual_alias_maps =
+    proxy:mysql:/etc/postfix/virtual_alias.cf
+.fi
+.sp
+The total number of connections is limited by the number of
+proxymap server processes.
+.IP \(bu
+To provide single\-updater functionality for lookup tables
+that do not reliably support multiple writers (i.e. all
+file\-based tables).
+.PP
+The \fBproxymap\fR(8) server implements the following requests:
+.IP "\fBopen\fR \fImaptype:mapname flags\fR"
+Open the table with type \fImaptype\fR and name \fImapname\fR,
+as controlled by \fIflags\fR. The reply includes the \fImaptype\fR
+dependent flags (to distinguish a fixed string table from a regular
+expression table).
+.IP "\fBlookup\fR \fImaptype:mapname flags key\fR"
+Look up the data stored under the requested key.
+The reply is the request completion status code and
+the lookup result value.
+The \fImaptype:mapname\fR and \fIflags\fR are the same
+as with the \fBopen\fR request.
+.IP "\fBupdate\fR \fImaptype:mapname flags key value\fR"
+Update the data stored under the requested key.
+The reply is the request completion status code.
+The \fImaptype:mapname\fR and \fIflags\fR are the same
+as with the \fBopen\fR request.
+.sp
+To implement single\-updater maps, specify a process limit
+of 1 in the master.cf file entry for the \fBproxywrite\fR
+service.
+.sp
+This request is supported in Postfix 2.5 and later.
+.IP "\fBdelete\fR \fImaptype:mapname flags key\fR"
+Delete the data stored under the requested key.
+The reply is the request completion status code.
+The \fImaptype:mapname\fR and \fIflags\fR are the same
+as with the \fBopen\fR request.
+.sp
+This request is supported in Postfix 2.5 and later.
+.IP "\fBsequence\fR \fImaptype:mapname flags function\fR"
+Iterate over the specified database. The \fIfunction\fR
+is one of DICT_SEQ_FUN_FIRST or DICT_SEQ_FUN_NEXT.
+The reply is the request completion status code and
+a lookup key and result value, if found.
+.sp
+This request is supported in Postfix 2.9 and later.
+.PP
+The request completion status is one of OK, RETRY, NOKEY
+(lookup failed because the key was not found), BAD (malformed
+request) or DENY (the table is not approved for proxy read
+or update access).
+
+There is no \fBclose\fR command, nor are tables implicitly closed
+when a client disconnects. The purpose is to share tables among
+multiple client processes.
+.SH "SERVER PROCESS MANAGEMENT"
+.na
+.nf
+.ad
+.fi
+\fBproxymap\fR(8) servers run under control by the Postfix
+\fBmaster\fR(8)
+server.  Each server can handle multiple simultaneous connections.
+When all servers are busy while a client connects, the \fBmaster\fR(8)
+creates a new \fBproxymap\fR(8) server process, provided that the
+process limit is not exceeded.
+Each server terminates after serving at least \fB$max_use\fR clients
+or after \fB$max_idle\fR seconds of idle time.
+.SH "SECURITY"
+.na
+.nf
+.ad
+.fi
+The \fBproxymap\fR(8) server opens only tables that are
+approved via the \fBproxy_read_maps\fR or \fBproxy_write_maps\fR
+configuration parameters, does not talk to
+users, and can run at fixed low privilege, chrooted or not.
+However, running the proxymap server chrooted severely limits
+usability, because it can open only chrooted tables.
+
+The \fBproxymap\fR(8) server is not a trusted daemon process, and must
+not be used to look up sensitive information such as UNIX user or
+group IDs, mailbox file/directory names or external commands.
+
+In Postfix version 2.2 and later, the proxymap client recognizes
+requests to access a table for security\-sensitive purposes,
+and opens the table directly. This allows the same main.cf
+setting to be used by sensitive and non\-sensitive processes.
+
+Postfix\-writable data files should be stored under a dedicated
+directory that is writable only by the Postfix mail system,
+such as the Postfix\-owned \fBdata_directory\fR.
+
+In particular, Postfix\-writable files should never exist
+in root\-owned directories. That would open up a particular
+type of security hole where ownership of a file or directory
+does not match the provider of its content.
+.SH DIAGNOSTICS
+.ad
+.fi
+Problems and transactions are logged to \fBsyslogd\fR(8)
+or \fBpostlogd\fR(8).
+.SH BUGS
+.ad
+.fi
+The \fBproxymap\fR(8) server provides service to multiple clients,
+and must therefore not be used for tables that have high\-latency
+lookups.
+
+The \fBproxymap\fR(8) read\-write service does not explicitly
+close lookup tables (even if it did, this could not be relied on,
+because the process may be terminated between table updates).
+The read\-write service should therefore not be used with tables that
+leave persistent storage in an inconsistent state between
+updates (for example, CDB). Tables that support "sync on
+update" should be safe (for example, Berkeley DB) as should
+tables that are implemented by a real DBMS.
+.SH "CONFIGURATION PARAMETERS"
+.na
+.nf
+.ad
+.fi
+On busy mail systems a long time may pass before
+\fBproxymap\fR(8) relevant
+changes to \fBmain.cf\fR are picked up. Use the command
+"\fBpostfix reload\fR" to speed up a change.
+
+The text below provides only a parameter summary. See
+\fBpostconf\fR(5) for more details including examples.
+.IP "\fBconfig_directory (see 'postconf -d' output)\fR"
+The default location of the Postfix main.cf and master.cf
+configuration files.
+.IP "\fBdata_directory (see 'postconf -d' output)\fR"
+The directory with Postfix\-writable data files (for example:
+caches, pseudo\-random numbers).
+.IP "\fBdaemon_timeout (18000s)\fR"
+How much time a Postfix daemon process may take to handle a
+request before it is terminated by a built\-in watchdog timer.
+.IP "\fBipc_timeout (3600s)\fR"
+The time limit for sending or receiving information over an internal
+communication channel.
+.IP "\fBmax_idle (100s)\fR"
+The maximum amount of time that an idle Postfix daemon process waits
+for an incoming connection before terminating voluntarily.
+.IP "\fBmax_use (100)\fR"
+The maximal number of incoming connections that a Postfix daemon
+process will service before terminating voluntarily.
+.IP "\fBprocess_id (read\-only)\fR"
+The process ID of a Postfix command or daemon process.
+.IP "\fBprocess_name (read\-only)\fR"
+The process name of a Postfix command or daemon process.
+.IP "\fBproxy_read_maps (see 'postconf -d' output)\fR"
+The lookup tables that the \fBproxymap\fR(8) server is allowed to
+access for the read\-only service.
+.PP
+Available in Postfix 2.5 and later:
+.IP "\fBdata_directory (see 'postconf -d' output)\fR"
+The directory with Postfix\-writable data files (for example:
+caches, pseudo\-random numbers).
+.IP "\fBproxy_write_maps (see 'postconf -d' output)\fR"
+The lookup tables that the \fBproxymap\fR(8) server is allowed to
+access for the read\-write service.
+.PP
+Available in Postfix 3.3 and later:
+.IP "\fBservice_name (read\-only)\fR"
+The master.cf service name of a Postfix daemon process.
+.SH "SEE ALSO"
+.na
+.nf
+postconf(5), configuration parameters
+master(5), generic daemon options
+.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
+.SH "LICENSE"
+.na
+.nf
+.ad
+.fi
+The Secure Mailer license must be distributed with this software.
+.SH HISTORY
+.ad
+.fi
+.ad
+.fi
+The proxymap service was introduced with Postfix 2.0.
+.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