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