1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3<html> <head> 4<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 5<title> Postfix manual - proxymap(8) </title> 6</head> <body> <pre> 7PROXYMAP(8) PROXYMAP(8) 8 9<b>NAME</b> 10 proxymap - Postfix lookup table proxy server 11 12<b>SYNOPSIS</b> 13 <b>proxymap</b> [generic Postfix daemon options] 14 15<b>DESCRIPTION</b> 16 The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server provides read-only or read-write table lookup 17 service to Postfix processes. These services are implemented with dis- 18 tinct service names: <b>proxymap</b> and <b>proxywrite</b>, respectively. The purpose 19 of these services is: 20 21 <b>o</b> To overcome chroot restrictions. For example, a chrooted SMTP 22 server needs access to the system passwd file in order to reject 23 mail for non-existent local addresses, but it is not practical 24 to maintain a copy of the passwd file in the chroot jail. The 25 solution: 26 27 <a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> = 28 <a href="proxymap.8.html">proxy</a>:unix:passwd.byname $<a href="postconf.5.html#alias_maps">alias_maps</a> 29 30 <b>o</b> To consolidate the number of open lookup tables by sharing one 31 open table among multiple processes. For example, making mysql 32 connections from every Postfix daemon process results in "too 33 many connections" errors. The solution: 34 35 <a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> = 36 <a href="proxymap.8.html">proxy</a>:<a href="mysql_table.5.html">mysql</a>:/etc/postfix/virtual_alias.cf 37 38 The total number of connections is limited by the number of 39 proxymap server processes. 40 41 <b>o</b> To provide single-updater functionality for lookup tables that 42 do not reliably support multiple writers (i.e. all file-based 43 tables). 44 45 The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server implements the following requests: 46 47 <b>open</b> <i>maptype:mapname flags</i> 48 Open the table with type <i>maptype</i> and name <i>mapname</i>, as controlled 49 by <i>flags</i>. The reply includes the <i>maptype</i> dependent flags (to 50 distinguish a fixed string table from a regular expression ta- 51 ble). 52 53 <b>lookup</b> <i>maptype:mapname flags key</i> 54 Look up the data stored under the requested key. The reply is 55 the request completion status code and the lookup result value. 56 The <i>maptype:mapname</i> and <i>flags</i> are the same as with the <b>open</b> 57 request. 58 59 <b>update</b> <i>maptype:mapname flags key value</i> 60 Update the data stored under the requested key. The reply is 61 the request completion status code. The <i>maptype:mapname</i> and 62 <i>flags</i> are the same as with the <b>open</b> request. 63 64 To implement single-updater maps, specify a process limit of 1 65 in the <a href="master.5.html">master.cf</a> file entry for the <b>proxywrite</b> service. 66 67 This request is supported in Postfix 2.5 and later. 68 69 <b>delete</b> <i>maptype:mapname flags key</i> 70 Delete the data stored under the requested key. The reply is 71 the request completion status code. The <i>maptype:mapname</i> and 72 <i>flags</i> are the same as with the <b>open</b> request. 73 74 This request is supported in Postfix 2.5 and later. 75 76 <b>sequence</b> <i>maptype:mapname flags function</i> 77 Iterate over the specified database. The <i>function</i> is one of 78 DICT_SEQ_FUN_FIRST or DICT_SEQ_FUN_NEXT. The reply is the 79 request completion status code and a lookup key and result 80 value, if found. 81 82 This request is supported in Postfix 2.9 and later. 83 84 The request completion status is one of OK, RETRY, NOKEY (lookup failed 85 because the key was not found), BAD (malformed request) or DENY (the 86 table is not approved for proxy read or update access). 87 88 There is no <b>close</b> command, nor are tables implicitly closed when a 89 client disconnects. The purpose is to share tables among multiple 90 client processes. 91 92<b>SERVER PROCESS MANAGEMENT</b> 93 <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. 94 Each server can handle multiple simultaneous connections. When all 95 servers are busy while a client connects, the <a href="master.8.html"><b>master</b>(8)</a> creates a new 96 <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server process, provided that the process limit is not 97 exceeded. Each server terminates after serving at least <b>$<a href="postconf.5.html#max_use">max_use</a></b> 98 clients or after <b>$<a href="postconf.5.html#max_idle">max_idle</a></b> seconds of idle time. 99 100<b>SECURITY</b> 101 The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server opens only tables that are approved via the 102 <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 103 talk to users, and can run at fixed low privilege, chrooted or not. 104 However, running the proxymap server chrooted severely limits usabil- 105 ity, because it can open only chrooted tables. 106 107 The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server is not a trusted daemon process, and must not be 108 used to look up sensitive information such as UNIX user or group IDs, 109 mailbox file/directory names or external commands. 110 111 In Postfix version 2.2 and later, the proxymap client recognizes 112 requests to access a table for security-sensitive purposes, and opens 113 the table directly. This allows the same <a href="postconf.5.html">main.cf</a> setting to be used by 114 sensitive and non-sensitive processes. 115 116 Postfix-writable data files should be stored under a dedicated direc- 117 tory that is writable only by the Postfix mail system, such as the 118 Postfix-owned <b><a href="postconf.5.html#data_directory">data_directory</a></b>. 119 120 In particular, Postfix-writable files should never exist in root-owned 121 directories. That would open up a particular type of security hole 122 where ownership of a file or directory does not match the provider of 123 its content. 124 125<b>DIAGNOSTICS</b> 126 Problems and transactions are logged to <b>syslogd</b>(8). 127 128<b>BUGS</b> 129 The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server provides service to multiple clients, and must 130 therefore not be used for tables that have high-latency lookups. 131 132 The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> read-write service does not explicitly close lookup 133 tables (even if it did, this could not be relied on, because the 134 process may be terminated between table updates). The read-write ser- 135 vice should therefore not be used with tables that leave persistent 136 storage in an inconsistent state between updates (for example, CDB). 137 Tables that support "sync on update" should be safe (for example, 138 Berkeley DB) as should tables that are implemented by a real DBMS. 139 140<b>CONFIGURATION PARAMETERS</b> 141 On busy mail systems a long time may pass before <a href="proxymap.8.html"><b>proxymap</b>(8)</a> relevant 142 changes to <a href="postconf.5.html"><b>main.cf</b></a> are picked up. Use the command "<b>postfix reload</b>" to 143 speed up a change. 144 145 The text below provides only a parameter summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for 146 more details including examples. 147 148 <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> 149 The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con- 150 figuration files. 151 152 <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b> 153 The directory with Postfix-writable data files (for example: 154 caches, pseudo-random numbers). 155 156 <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b> 157 How much time a Postfix daemon process may take to handle a 158 request before it is terminated by a built-in watchdog timer. 159 160 <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b> 161 The time limit for sending or receiving information over an 162 internal communication channel. 163 164 <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b> 165 The maximum amount of time that an idle Postfix daemon process 166 waits for an incoming connection before terminating voluntarily. 167 168 <b><a href="postconf.5.html#max_use">max_use</a> (100)</b> 169 The maximal number of incoming connections that a Postfix daemon 170 process will service before terminating voluntarily. 171 172 <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b> 173 The process ID of a Postfix command or daemon process. 174 175 <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b> 176 The process name of a Postfix command or daemon process. 177 178 <b><a href="postconf.5.html#proxy_read_maps">proxy_read_maps</a> (see 'postconf -d' output)</b> 179 The lookup tables that the <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server is allowed to 180 access for the read-only service. 181 182 Available in Postfix 2.5 and later: 183 184 <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b> 185 The directory with Postfix-writable data files (for example: 186 caches, pseudo-random numbers). 187 188 <b><a href="postconf.5.html#proxy_write_maps">proxy_write_maps</a> (see 'postconf -d' output)</b> 189 The lookup tables that the <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server is allowed to 190 access for the read-write service. 191 192<b>SEE ALSO</b> 193 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 194 <a href="master.5.html">master(5)</a>, generic daemon options 195 196<b>README FILES</b> 197 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview 198 199<b>LICENSE</b> 200 The Secure Mailer license must be distributed with this software. 201 202<b>HISTORY</b> 203 The proxymap service was introduced with Postfix 2.0. 204 205<b>AUTHOR(S)</b> 206 Wietse Venema 207 IBM T.J. Watson Research 208 P.O. Box 704 209 Yorktown Heights, NY 10598, USA 210 211 PROXYMAP(8) 212</pre> </body> </html> 213