13
13
<b>proxymap</b> [generic Postfix daemon options]
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
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
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
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
29
27
<a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> =
30
28
<a href="proxymap.8.html">proxy</a>:unix:passwd.byname $<a href="postconf.5.html#alias_maps">alias_maps</a>
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:
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:
38
35
<a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> =
39
36
<a href="proxymap.8.html">proxy</a>:<a href="mysql_table.5.html">mysql</a>:/etc/postfix/virtual_alias.cf
41
The total number of connections is limited by the
42
number of proxymap server processes.
38
The total number of connections is limited by the number of
39
proxymap server processes.
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).
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
48
45
The <a href="proxymap.8.html"><b>proxymap</b>(8)</a> server implements the following requests:
50
47
<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).
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-
56
53
<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.
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>
62
59
<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.
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.
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.
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.
72
67
This request is supported in Postfix 2.5 and later.
74
69
<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.
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.
80
74
This request is supported in Postfix 2.5 and later.
82
76
<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.
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
88
82
This request is supported in Postfix 2.9 and later.
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).
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).
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.
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
99
92
<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>
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>
106
98
clients or after <b>$<a href="postconf.5.html#max_idle">max_idle</a></b> seconds of idle time.
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.
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
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-
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>.
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.
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.
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.
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.
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>.
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
136
125
<b>DIAGNOSTICS</b>
137
126
Problems and transactions are logged to <b>syslogd</b>(8).
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.
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.
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.
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.
154
140
<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.
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
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.
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.
162
148
<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.
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-
166
152
<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).
153
The directory with Postfix-writable data files (for example:
154
caches, pseudo-random numbers).
170
156
<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.
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.
175
160
<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.
161
The time limit for sending or receiving information over an
162
internal communication channel.
179
164
<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.
165
The maximum amount of time that an idle Postfix daemon process
166
waits for an incoming connection before terminating voluntarily.
184
168
<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-
169
The maximal number of incoming connections that a Postfix daemon
170
process will service before terminating voluntarily.
189
172
<b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
190
The process ID of a Postfix command or daemon
173
The process ID of a Postfix command or daemon process.
193
175
<b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
194
The process name of a Postfix command or daemon
176
The process name of a Postfix command or daemon process.
197
178
<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.
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.
201
182
Available in Postfix 2.5 and later:
203
184
<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).
185
The directory with Postfix-writable data files (for example:
186
caches, pseudo-random numbers).
207
188
<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.
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.
212
193
<a href="postconf.5.html">postconf(5)</a>, configuration parameters
added
removed
html/proxymap.8.html
