1PROXYMAP(8)                 System Manager's Manual                PROXYMAP(8)
2
3
4

NAME

6       proxymap - Postfix lookup table proxy server
7

SYNOPSIS

9       proxymap [generic Postfix daemon options]
10

DESCRIPTION

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
17       ·      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
23              local_recipient_maps =
24                  proxy:unix:passwd.byname $alias_maps
25
26       ·      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
31              virtual_alias_maps =
32                  proxy:mysql:/etc/postfix/virtual_alias.cf
33
34              The  total  number  of  connections  is limited by the number of
35              proxymap server processes.
36
37       ·      To provide single-updater functionality for lookup  tables  that
38              do  not  reliably  support multiple writers (i.e. all file-based
39              tables).
40
41       The proxymap(8) server implements the following requests:
42
43       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
49       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
55       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
60              To implement single-updater maps, specify a process limit  of  1
61              in the master.cf file entry for the proxywrite service.
62
63              This request is supported in Postfix 2.5 and later.
64
65       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
70              This request is supported in Postfix 2.5 and later.
71
72       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
78              This request is supported in Postfix 2.9 and later.
79
80       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
84       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

SERVER PROCESS MANAGEMENT

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

SECURITY

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
103       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
107       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
112       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
116       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

DIAGNOSTICS

122       Problems and transactions are logged to syslogd(8).
123

BUGS

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
128       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

CONFIGURATION PARAMETERS

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
141       The text below provides only a parameter summary. See  postconf(5)  for
142       more details including examples.
143
144       config_directory (see 'postconf -d' output)
145              The  default  location of the Postfix main.cf and master.cf con‐
146              figuration files.
147
148       data_directory (see 'postconf -d' output)
149              The directory with Postfix-writable  data  files  (for  example:
150              caches, pseudo-random numbers).
151
152       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
156       ipc_timeout (3600s)
157              The time limit for sending  or  receiving  information  over  an
158              internal communication channel.
159
160       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
164       max_use (100)
165              The maximal number of incoming connections that a Postfix daemon
166              process will service before terminating voluntarily.
167
168       process_id (read-only)
169              The process ID of a Postfix command or daemon process.
170
171       process_name (read-only)
172              The process name of a Postfix command or daemon process.
173
174       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
178       Available in Postfix 2.5 and later:
179
180       data_directory (see 'postconf -d' output)
181              The directory with Postfix-writable  data  files  (for  example:
182              caches, pseudo-random numbers).
183
184       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
188       Available in Postfix 3.3 and later:
189
190       service_name (read-only)
191              The master.cf service name of a Postfix daemon process.
192

SEE ALSO

194       postconf(5), configuration parameters
195       master(5), generic daemon options
196

README FILES

198       Use "postconf readme_directory" or "postconf html_directory" to  locate
199       this information.
200       DATABASE_README, Postfix lookup table overview
201

LICENSE

203       The Secure Mailer license must be distributed with this software.
204

HISTORY

206       The proxymap service was introduced with Postfix 2.0.
207

AUTHOR(S)

209       Wietse Venema
210       IBM T.J. Watson Research
211       P.O. Box 704
212       Yorktown Heights, NY 10598, USA
213
214       Wietse Venema
215       Google, Inc.
216       111 8th Avenue
217       New York, NY 10011, USA
218
219
220
221                                                                   PROXYMAP(8)
Impressum