1PROXYMAP(8) System Manager's Manual PROXYMAP(8)
2
6 proxymap - Postfix lookup table proxy server
7
9 proxymap [generic Postfix daemon options]
10
12 The proxymap(8) server provides read-only or read-write table lookup
13 service to Postfix processes. These services are implemented with dis‐
14 tinct service names: proxymap and proxywrite, respectively. The purpose
15 of these services is:
16 · To overcome chroot restrictions. For example, a chrooted SMTP
18 server needs access to the system passwd file in order to reject
19 mail for non-existent local addresses, but it is not practical
20 to maintain a copy of the passwd file in the chroot jail. The
21 solution:
22 local_recipient_maps =
24 proxy:unix:passwd.byname $alias_maps
25 · To consolidate the number of open lookup tables by sharing one
27 open table among multiple processes. For example, making mysql
28 connections from every Postfix daemon process results in "too
29 many connections" errors. The solution:
30 virtual_alias_maps =
32 proxy:mysql:/etc/postfix/virtual_alias.cf
33 The total number of connections is limited by the number of
35 proxymap server processes.
36 · To provide single-updater functionality for lookup tables that
38 do not reliably support multiple writers (i.e. all file-based
39 tables).
40 The proxymap(8) server implements the following requests:
42 open maptype:mapname flags
44 Open the table with type maptype and name mapname, as controlled
45 by flags. The reply includes the maptype dependent flags (to
46 distinguish a fixed string table from a regular expression ta‐
47 ble).
48 lookup maptype:mapname flags key
50 Look up the data stored under the requested key. The reply is
51 the request completion status code and the lookup result value.
52 The maptype:mapname and flags are the same as with the open
53 request.
54 update maptype:mapname flags key value
56 Update the data stored under the requested key. The reply is
57 the request completion status code. The maptype:mapname and
58 flags are the same as with the open request.
59 To implement single-updater maps, specify a process limit of 1
61 in the master.cf file entry for the proxywrite service.
62 This request is supported in Postfix 2.5 and later.
64 delete maptype:mapname flags key
66 Delete the data stored under the requested key. The reply is
67 the request completion status code. The maptype:mapname and
68 flags are the same as with the open request.
69 This request is supported in Postfix 2.5 and later.
71 The request completion status is one of OK, RETRY, NOKEY (lookup failed
73 because the key was not found), BAD (malformed request) or DENY (the
74 table is not approved for proxy read or update access).
75 There is no close command, nor are tables implicitly closed when a
77 client disconnects. The purpose is to share tables among multiple
78 client processes.
79
81 proxymap(8) servers run under control by the Postfix master(8) server.
82 Each server can handle multiple simultaneous connections. When all
83 servers are busy while a client connects, the master(8) creates a new
84 proxymap(8) server process, provided that the process limit is not
85 exceeded. Each server terminates after serving at least $max_use
86 clients or after $max_idle seconds of idle time.
87
89 The proxymap(8) server opens only tables that are approved via the
90 proxy_read_maps or proxy_write_maps configuration parameters, does not
91 talk to users, and can run at fixed low privilege, chrooted or not.
92 However, running the proxymap server chrooted severely limits usabil‐
93 ity, because it can open only chrooted tables.
94 The proxymap(8) server is not a trusted daemon process, and must not be
96 used to look up sensitive information such as user or group IDs, mail‐
97 box file/directory names or external commands.
98 In Postfix version 2.2 and later, the proxymap client recognizes
100 requests to access a table for security-sensitive purposes, and opens
101 the table directly. This allows the same main.cf setting to be used by
102 sensitive and non-sensitive processes.
103 Postfix-writable data files should be stored under a dedicated direc‐
105 tory that is writable only by the Postfix mail system, such as the
106 Postfix-owned data_directory.
107 In particular, Postfix-writable files should never exist in root-owned
109 directories. That would open up a particular type of security hole
110 where ownership of a file or directory does not match the provider of
111 its content.
112
114 Problems and transactions are logged to syslogd(8).
115
117 The proxymap(8) server provides service to multiple clients, and must
118 therefore not be used for tables that have high-latency lookups.
119 The proxymap(8) read-write service does not explicitly close lookup
121 tables (even if it did, this could not be relied on, because the
122 process may be terminated between table updates). The read-write ser‐
123 vice should therefore not be used with tables that leave persistent
124 storage in an inconsistent state between updates (for example, CDB).
125 Tables that support "sync on update" should be safe (for example,
126 Berkeley DB) as should tables that are implemented by a real DBMS.
127
129 On busy mail systems a long time may pass before proxymap(8) relevant
130 changes to main.cf are picked up. Use the command "postfix reload" to
131 speed up a change.
132 The text below provides only a parameter summary. See postconf(5) for
134 more details including examples.
135 config_directory (see 'postconf -d' output)
137 The default location of the Postfix main.cf and master.cf con‐
138 figuration files.
139 data_directory (see 'postconf -d' output)
141 The directory with Postfix-writable data files (for example:
142 caches, pseudo-random numbers).
143 daemon_timeout (18000s)
145 How much time a Postfix daemon process may take to handle a
146 request before it is terminated by a built-in watchdog timer.
147 ipc_timeout (3600s)
149 The time limit for sending or receiving information over an
150 internal communication channel.
151 max_idle (100s)
153 The maximum amount of time that an idle Postfix daemon process
154 waits for an incoming connection before terminating voluntarily.
155 max_use (100)
157 The maximal number of incoming connections that a Postfix daemon
158 process will service before terminating voluntarily.
159 process_id (read-only)
161 The process ID of a Postfix command or daemon process.
162 process_name (read-only)
164 The process name of a Postfix command or daemon process.
165 proxy_read_maps (see 'postconf -d' output)
167 The lookup tables that the proxymap(8) server is allowed to
168 access for the read-only service.
169 Available in Postfix 2.5 and later:
171 data_directory (see 'postconf -d' output)
173 The directory with Postfix-writable data files (for example:
174 caches, pseudo-random numbers).
175 proxy_write_maps (see 'postconf -d' output)
177 The lookup tables that the proxymap(8) server is allowed to
178 access for the read-write service.
179
181 postconf(5), configuration parameters
182 master(5), generic daemon options
183
185 Use "postconf readme_directory" or "postconf html_directory" to locate
186 this information.
187 DATABASE_README, Postfix lookup table overview
188
190 The Secure Mailer license must be distributed with this software.
191
193 The proxymap service was introduced with Postfix 2.0.
194
196 Wietse Venema
197 IBM T.J. Watson Research
198 P.O. Box 704
199 Yorktown Heights, NY 10598, USA
200 PROXYMAP(8)