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