diff options
Diffstat (limited to 'html/proxymap.8.html')
| -rw-r--r-- | html/proxymap.8.html | 222 |
1 files changed, 222 insertions, 0 deletions
diff --git a/html/proxymap.8.html b/html/proxymap.8.html new file mode 100644 index 0000000..8a65c60 --- /dev/null +++ b/html/proxymap.8.html @@ -0,0 +1,222 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> +<html> <head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<title> Postfix manual - proxymap(8) </title> +</head> <body> <pre> +PROXYMAP(8) PROXYMAP(8) + +<b>NAME</b> + proxymap - Postfix lookup table proxy server + +<b>SYNOPSIS</b> + <b>proxymap</b> [generic Postfix daemon options] + +<b>DESCRIPTION</b> + The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server provides read-only or read-write table lookup + service to Postfix processes. These services are implemented with dis- + tinct service names: <b>proxymap</b> and <b>proxywrite</b>, respectively. The purpose + of these services is: + + <b>o</b> 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: + + <a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> = + <a href="proxymap.8.html">proxy</a>:unix:passwd.byname $<a href="postconf.5.html#alias_maps">alias_maps</a> + + <b>o</b> 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: + + <a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> = + <a href="proxymap.8.html">proxy</a>:<a href="mysql_table.5.html">mysql</a>:/etc/postfix/virtual_alias.cf + + The total number of connections is limited by the number of + proxymap server processes. + + <b>o</b> To provide single-updater functionality for lookup tables that + do not reliably support multiple writers (i.e. all file-based + tables). + + The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server implements the following requests: + + <b>open</b> <i>maptype:mapname flags</i> + Open the table with type <i>maptype</i> and name <i>mapname</i>, as controlled + by <i>flags</i>. The reply includes the <i>maptype</i> dependent flags (to + distinguish a fixed string table from a regular expression ta- + ble). + + <b>lookup</b> <i>maptype:mapname flags key</i> + Look up the data stored under the requested key. The reply is + the request completion status code and the lookup result value. + The <i>maptype:mapname</i> and <i>flags</i> are the same as with the <b>open</b> + request. + + <b>update</b> <i>maptype:mapname flags key value</i> + Update the data stored under the requested key. The reply is + the request completion status code. The <i>maptype:mapname</i> and + <i>flags</i> are the same as with the <b>open</b> request. + + To implement single-updater maps, specify a process limit of 1 + in the <a href="master.5.html">master.cf</a> file entry for the <b>proxywrite</b> service. + + This request is supported in Postfix 2.5 and later. + + <b>delete</b> <i>maptype:mapname flags key</i> + Delete the data stored under the requested key. The reply is + the request completion status code. The <i>maptype:mapname</i> and + <i>flags</i> are the same as with the <b>open</b> request. + + This request is supported in Postfix 2.5 and later. + + <b>sequence</b> <i>maptype:mapname flags function</i> + Iterate over the specified database. The <i>function</i> 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. + + This request is supported in Postfix 2.9 and later. + + 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 <b>close</b> command, nor are tables implicitly closed when a + client disconnects. The purpose is to share tables among multiple + client processes. + +<b>SERVER PROCESS MANAGEMENT</b> + <a href="proxymap.8.html"><b>proxymap</b>(8)</a> servers run under control by the Postfix <a href="master.8.html"><b>master</b>(8)</a> server. + Each server can handle multiple simultaneous connections. When all + servers are busy while a client connects, the <a href="master.8.html"><b>master</b>(8)</a> creates a new + <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server process, provided that the process limit is not + exceeded. Each server terminates after serving at least <b>$<a href="postconf.5.html#max_use">max_use</a></b> + clients or after <b>$<a href="postconf.5.html#max_idle">max_idle</a></b> seconds of idle time. + +<b>SECURITY</b> + The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server opens only tables that are approved via the + <b><a href="postconf.5.html#proxy_read_maps">proxy_read_maps</a></b> or <b><a href="postconf.5.html#proxy_write_maps">proxy_write_maps</a></b> 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 usabil- + ity, because it can open only chrooted tables. + + The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> 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 <a href="postconf.5.html">main.cf</a> setting to be used by + sensitive and non-sensitive processes. + + Postfix-writable data files should be stored under a dedicated direc- + tory that is writable only by the Postfix mail system, such as the + Postfix-owned <b><a href="postconf.5.html#data_directory">data_directory</a></b>. + + 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. + +<b>DIAGNOSTICS</b> + Problems and transactions are logged to <b>syslogd</b>(8) or <a href="postlogd.8.html"><b>postlogd</b>(8)</a>. + +<b>BUGS</b> + The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server provides service to multiple clients, and must + therefore not be used for tables that have high-latency lookups. + + The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> 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 ser- + vice 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. + +<b>CONFIGURATION PARAMETERS</b> + On busy mail systems a long time may pass before <a href="proxymap.8.html"><b>proxymap</b>(8)</a> relevant + changes to <a href="postconf.5.html"><b>main.cf</b></a> are picked up. Use the command "<b>postfix reload</b>" to + speed up a change. + + The text below provides only a parameter summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for + more details including examples. + + <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> + The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con- + figuration files. + + <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b> + The directory with Postfix-writable data files (for example: + caches, pseudo-random numbers). + + <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b> + How much time a Postfix daemon process may take to handle a + request before it is terminated by a built-in watchdog timer. + + <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b> + The time limit for sending or receiving information over an + internal communication channel. + + <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b> + The maximum amount of time that an idle Postfix daemon process + waits for an incoming connection before terminating voluntarily. + + <b><a href="postconf.5.html#max_use">max_use</a> (100)</b> + The maximal number of incoming connections that a Postfix daemon + process will service before terminating voluntarily. + + <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b> + The process ID of a Postfix command or daemon process. + + <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b> + The process name of a Postfix command or daemon process. + + <b><a href="postconf.5.html#proxy_read_maps">proxy_read_maps</a> (see 'postconf -d' output)</b> + The lookup tables that the <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server is allowed to + access for the read-only service. + + Available in Postfix 2.5 and later: + + <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b> + The directory with Postfix-writable data files (for example: + caches, pseudo-random numbers). + + <b><a href="postconf.5.html#proxy_write_maps">proxy_write_maps</a> (see 'postconf -d' output)</b> + The lookup tables that the <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server is allowed to + access for the read-write service. + + Available in Postfix 3.3 and later: + + <b><a href="postconf.5.html#service_name">service_name</a> (read-only)</b> + The <a href="master.5.html">master.cf</a> service name of a Postfix daemon process. + +<b>SEE ALSO</b> + <a href="postconf.5.html">postconf(5)</a>, configuration parameters + <a href="master.5.html">master(5)</a>, generic daemon options + +<b>README FILES</b> + <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview + +<b>LICENSE</b> + The Secure Mailer license must be distributed with this software. + +<b>HISTORY</b> + The proxymap service was introduced with Postfix 2.0. + +<b>AUTHOR(S)</b> + 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 + + PROXYMAP(8) +</pre> </body> </html> |