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