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 sequence maptype:mapname flags function
73 Iterate over the specified database. The function is one of
74 DICT_SEQ_FUN_FIRST or DICT_SEQ_FUN_NEXT. The reply is the
75 request completion status code and a lookup key and result
76 value, if found.
77 This request is supported in Postfix 2.9 and later.
79 The request completion status is one of OK, RETRY, NOKEY (lookup failed
81 because the key was not found), BAD (malformed request) or DENY (the
82 table is not approved for proxy read or update access).
83 There is no close command, nor are tables implicitly closed when a
85 client disconnects. The purpose is to share tables among multiple
86 client processes.
87
89 proxymap(8) servers run under control by the Postfix master(8) server.
90 Each server can handle multiple simultaneous connections. When all
91 servers are busy while a client connects, the master(8) creates a new
92 proxymap(8) server process, provided that the process limit is not
93 exceeded. Each server terminates after serving at least $max_use
94 clients or after $max_idle seconds of idle time.
95
97 The proxymap(8) server opens only tables that are approved via the
98 proxy_read_maps or proxy_write_maps configuration parameters, does not
99 talk to users, and can run at fixed low privilege, chrooted or not.
100 However, running the proxymap server chrooted severely limits usabil‐
101 ity, because it can open only chrooted tables.
102 The proxymap(8) server is not a trusted daemon process, and must not be
104 used to look up sensitive information such as UNIX user or group IDs,
105 mailbox file/directory names or external commands.
106 In Postfix version 2.2 and later, the proxymap client recognizes
108 requests to access a table for security-sensitive purposes, and opens
109 the table directly. This allows the same main.cf setting to be used by
110 sensitive and non-sensitive processes.
111 Postfix-writable data files should be stored under a dedicated direc‐
113 tory that is writable only by the Postfix mail system, such as the
114 Postfix-owned data_directory.
115 In particular, Postfix-writable files should never exist in root-owned
117 directories. That would open up a particular type of security hole
118 where ownership of a file or directory does not match the provider of
119 its content.
120
122 Problems and transactions are logged to syslogd(8).
123
125 The proxymap(8) server provides service to multiple clients, and must
126 therefore not be used for tables that have high-latency lookups.
127 The proxymap(8) read-write service does not explicitly close lookup
129 tables (even if it did, this could not be relied on, because the
130 process may be terminated between table updates). The read-write ser‐
131 vice should therefore not be used with tables that leave persistent
132 storage in an inconsistent state between updates (for example, CDB).
133 Tables that support "sync on update" should be safe (for example,
134 Berkeley DB) as should tables that are implemented by a real DBMS.
135
137 On busy mail systems a long time may pass before proxymap(8) relevant
138 changes to main.cf are picked up. Use the command "postfix reload" to
139 speed up a change.
140 The text below provides only a parameter summary. See postconf(5) for
142 more details including examples.
143 config_directory (see 'postconf -d' output)
145 The default location of the Postfix main.cf and master.cf con‐
146 figuration files.
147 data_directory (see 'postconf -d' output)
149 The directory with Postfix-writable data files (for example:
150 caches, pseudo-random numbers).
151 daemon_timeout (18000s)
153 How much time a Postfix daemon process may take to handle a
154 request before it is terminated by a built-in watchdog timer.
155 ipc_timeout (3600s)
157 The time limit for sending or receiving information over an
158 internal communication channel.
159 max_idle (100s)
161 The maximum amount of time that an idle Postfix daemon process
162 waits for an incoming connection before terminating voluntarily.
163 max_use (100)
165 The maximal number of incoming connections that a Postfix daemon
166 process will service before terminating voluntarily.
167 process_id (read-only)
169 The process ID of a Postfix command or daemon process.
170 process_name (read-only)
172 The process name of a Postfix command or daemon process.
173 proxy_read_maps (see 'postconf -d' output)
175 The lookup tables that the proxymap(8) server is allowed to
176 access for the read-only service.
177 Available in Postfix 2.5 and later:
179 data_directory (see 'postconf -d' output)
181 The directory with Postfix-writable data files (for example:
182 caches, pseudo-random numbers).
183 proxy_write_maps (see 'postconf -d' output)
185 The lookup tables that the proxymap(8) server is allowed to
186 access for the read-write service.
187
189 postconf(5), configuration parameters
190 master(5), generic daemon options
191
193 Use "postconf readme_directory" or "postconf html_directory" to locate
194 this information.
195 DATABASE_README, Postfix lookup table overview
196
198 The Secure Mailer license must be distributed with this software.
199
201 The proxymap service was introduced with Postfix 2.0.
202
204 Wietse Venema
205 IBM T.J. Watson Research
206 P.O. Box 704
207 Yorktown Heights, NY 10598, USA
208 PROXYMAP(8)