Patrick Welche <prlw1@cam.ac.uk>
[netbsd-mini2440.git] / external / ibm-public / postfix / dist / man / man8 / virtual.8
blob3dd7360db01a7fcf8bafb8a190bb9731c162ceea
1 .\"     $NetBSD$
2 .\"
3 .TH VIRTUAL 8 
4 .ad
5 .fi
6 .SH NAME
7 virtual
8 \-
9 Postfix virtual domain mail delivery agent
10 .SH "SYNOPSIS"
11 .na
12 .nf
13 \fBvirtual\fR [generic Postfix daemon options]
14 .SH DESCRIPTION
15 .ad
16 .fi
17 The \fBvirtual\fR(8) delivery agent is designed for virtual mail
18 hosting services. Originally based on the Postfix \fBlocal\fR(8)
19 delivery
20 agent, this agent looks up recipients with map lookups of their
21 full recipient address, instead of using hard-coded unix password
22 file lookups of the address local part only.
24 This delivery agent only delivers mail.  Other features such as
25 mail forwarding, out-of-office notifications, etc., must be
26 configured via virtual_alias maps or via similar lookup mechanisms.
27 .SH "MAILBOX LOCATION"
28 .na
29 .nf
30 .ad
31 .fi
32 The mailbox location is controlled by the \fBvirtual_mailbox_base\fR
33 and \fBvirtual_mailbox_maps\fR configuration parameters (see below).
34 The \fBvirtual_mailbox_maps\fR table is indexed by the recipient
35 address as described under TABLE SEARCH ORDER below.
37 The mailbox pathname is constructed as follows:
39 .nf
40   \fB$virtual_mailbox_base/$virtual_mailbox_maps(\fIrecipient\fB)\fR
41 .fi
43 where \fIrecipient\fR is the full recipient address.
44 .SH "UNIX MAILBOX FORMAT"
45 .na
46 .nf
47 .ad
48 .fi
49 When the mailbox location does not end in \fB/\fR, the message
50 is delivered in UNIX mailbox format.   This format stores multiple
51 messages in one textfile.
53 The \fBvirtual\fR(8) delivery agent prepends a "\fBFrom \fIsender
54 time_stamp\fR" envelope header to each message, prepends a
55 \fBDelivered-To:\fR message header with the envelope recipient
56 address,
57 prepends an \fBX-Original-To:\fR header with the recipient address as
58 given to Postfix,
59 prepends a \fBReturn-Path:\fR message header with the
60 envelope sender address, prepends a \fB>\fR character to lines
61 beginning with "\fBFrom \fR", and appends an empty line.
63 The mailbox is locked for exclusive access while delivery is in
64 progress. In case of problems, an attempt is made to truncate the
65 mailbox to its original length.
66 .SH "QMAIL MAILDIR FORMAT"
67 .na
68 .nf
69 .ad
70 .fi
71 When the mailbox location ends in \fB/\fR, the message is delivered
72 in qmail \fBmaildir\fR format. This format stores one message per file.
74 The \fBvirtual\fR(8) delivery agent prepends a \fBDelivered-To:\fR
75 message header with the final envelope recipient address,
76 prepends an \fBX-Original-To:\fR header with the recipient address as
77 given to Postfix, and prepends a
78 \fBReturn-Path:\fR message header with the envelope sender address.
80 By definition, \fBmaildir\fR format does not require application-level
81 file locking during mail delivery or retrieval.
82 .SH "MAILBOX OWNERSHIP"
83 .na
84 .nf
85 .ad
86 .fi
87 Mailbox ownership is controlled by the \fBvirtual_uid_maps\fR
88 and \fBvirtual_gid_maps\fR lookup tables, which are indexed
89 with the full recipient address. Each table provides
90 a string with the numerical user and group ID, respectively.
92 The \fBvirtual_minimum_uid\fR parameter imposes a lower bound on
93 numerical user ID values that may be specified in any
94 \fBvirtual_uid_maps\fR.
95 .SH "CASE FOLDING"
96 .na
97 .nf
98 .ad
99 .fi
100 All delivery decisions are made using the full recipient
101 address, folded to lower case. See also the next section
102 for a few exceptions with optional address extensions.
103 .SH "TABLE SEARCH ORDER"
108 Normally, a lookup table is specified as a text file that
109 serves as input to the \fBpostmap\fR(1) command. The result, an
110 indexed file in \fBdbm\fR or \fBdb\fR format, is used for fast
111 searching by the mail system.
113 The search order is as follows. The search stops
114 upon the first successful lookup.
115 .IP \(bu
116 When the recipient has an optional address extension the
117 \fIuser+extension@domain.tld\fR address is looked up first.
119 With Postfix versions before 2.1, the optional address extension
120 is always ignored.
121 .IP \(bu
122 The \fIuser@domain.tld\fR address, without address extension,
123 is looked up next.
124 .IP \(bu
125 Finally, the recipient \fI@domain\fR is looked up.
127 When the table is provided via other means such as NIS, LDAP
128 or SQL, the same lookups are done as for ordinary indexed files.
130 Alternatively, a table can be provided as a regular-expression
131 map where patterns are given as regular expressions. In that case,
132 only the full recipient address is given to the regular-expression
133 map.
134 .SH "SECURITY"
139 The \fBvirtual\fR(8) delivery agent is not security sensitive, provided
140 that the lookup tables with recipient user/group ID information are
141 adequately protected. This program is not designed to run chrooted.
143 The \fBvirtual\fR(8) delivery agent disallows regular expression
144 substitution of $1 etc. in regular expression lookup tables,
145 because that would open a security hole.
147 The \fBvirtual\fR(8) delivery agent will silently ignore requests
148 to use the \fBproxymap\fR(8) server. Instead it will open the
149 table directly. Before Postfix version 2.2, the virtual
150 delivery agent will terminate with a fatal error.
151 .SH "STANDARDS"
154 RFC 822 (ARPA Internet Text Messages)
155 .SH DIAGNOSTICS
158 Mail bounces when the recipient has no mailbox or when the
159 recipient is over disk quota. In all other cases, mail for
160 an existing recipient is deferred and a warning is logged.
162 Problems and transactions are logged to \fBsyslogd\fR(8).
163 Corrupted message files are marked so that the queue
164 manager can move them to the \fBcorrupt\fR queue afterwards.
166 Depending on the setting of the \fBnotify_classes\fR parameter,
167 the postmaster is notified of bounces and of other trouble.
168 .SH BUGS
171 This delivery agent supports address extensions in email
172 addresses and in lookup table keys, but does not propagate
173 address extension information to the result of table lookup.
175 Postfix should have lookup tables that can return multiple result
176 attributes. In order to avoid the inconvenience of maintaining
177 three tables, use an LDAP or MYSQL database.
178 .SH "CONFIGURATION PARAMETERS"
183 Changes to \fBmain.cf\fR are picked up automatically, as
184 \fBvirtual\fR(8)
185 processes run for only a limited amount of time. Use the command
186 "\fBpostfix reload\fR" to speed up a change.
188 The text below provides only a parameter summary. See
189 \fBpostconf\fR(5) for more details including examples.
190 .SH "MAILBOX DELIVERY CONTROLS"
195 .IP "\fBvirtual_mailbox_base (empty)\fR"
196 A prefix that the \fBvirtual\fR(8) delivery agent prepends to all pathname
197 results from $virtual_mailbox_maps table lookups.
198 .IP "\fBvirtual_mailbox_maps (empty)\fR"
199 Optional lookup tables with all valid addresses in the domains that
200 match $virtual_mailbox_domains.
201 .IP "\fBvirtual_minimum_uid (100)\fR"
202 The minimum user ID value that the \fBvirtual\fR(8) delivery agent accepts
203 as a result from $virtual_uid_maps table lookup.
204 .IP "\fBvirtual_uid_maps (empty)\fR"
205 Lookup tables with the per-recipient user ID that the \fBvirtual\fR(8)
206 delivery agent uses while writing to the recipient's mailbox.
207 .IP "\fBvirtual_gid_maps (empty)\fR"
208 Lookup tables with the per-recipient group ID for \fBvirtual\fR(8) mailbox
209 delivery.
211 Available in Postfix version 2.0 and later:
212 .IP "\fBvirtual_mailbox_domains ($virtual_mailbox_maps)\fR"
213 Postfix is final destination for the specified list of domains;
214 mail is delivered via the $virtual_transport mail delivery transport.
215 .IP "\fBvirtual_transport (virtual)\fR"
216 The default mail delivery transport and next-hop destination for
217 final delivery to domains listed with $virtual_mailbox_domains.
219 Available in Postfix version 2.5.3 and later:
220 .IP "\fBstrict_mailbox_ownership (yes)\fR"
221 Defer delivery when a mailbox file is not owned by its recipient.
222 .SH "LOCKING CONTROLS"
227 .IP "\fBvirtual_mailbox_lock (see 'postconf -d' output)\fR"
228 How to lock a UNIX-style \fBvirtual\fR(8) mailbox before attempting
229 delivery.
230 .IP "\fBdeliver_lock_attempts (20)\fR"
231 The maximal number of attempts to acquire an exclusive lock on a
232 mailbox file or \fBbounce\fR(8) logfile.
233 .IP "\fBdeliver_lock_delay (1s)\fR"
234 The time between attempts to acquire an exclusive lock on a mailbox
235 file or \fBbounce\fR(8) logfile.
236 .IP "\fBstale_lock_time (500s)\fR"
237 The time after which a stale exclusive mailbox lockfile is removed.
238 .SH "RESOURCE AND RATE CONTROLS"
243 .IP "\fBvirtual_destination_concurrency_limit ($default_destination_concurrency_limit)\fR"
244 The maximal number of parallel deliveries to the same destination
245 via the virtual message delivery transport.
246 .IP "\fBvirtual_destination_recipient_limit ($default_destination_recipient_limit)\fR"
247 The maximal number of recipients per message for the virtual
248 message delivery transport.
249 .IP "\fBvirtual_mailbox_limit (51200000)\fR"
250 The maximal size in bytes of an individual mailbox or maildir file,
251 or zero (no limit).
252 .SH "MISCELLANEOUS CONTROLS"
257 .IP "\fBconfig_directory (see 'postconf -d' output)\fR"
258 The default location of the Postfix main.cf and master.cf
259 configuration files.
260 .IP "\fBdaemon_timeout (18000s)\fR"
261 How much time a Postfix daemon process may take to handle a
262 request before it is terminated by a built-in watchdog timer.
263 .IP "\fBdelay_logging_resolution_limit (2)\fR"
264 The maximal number of digits after the decimal point when logging
265 sub-second delay values.
266 .IP "\fBipc_timeout (3600s)\fR"
267 The time limit for sending or receiving information over an internal
268 communication channel.
269 .IP "\fBmax_idle (100s)\fR"
270 The maximum amount of time that an idle Postfix daemon process waits
271 for an incoming connection before terminating voluntarily.
272 .IP "\fBmax_use (100)\fR"
273 The maximal number of incoming connections that a Postfix daemon
274 process will service before terminating voluntarily.
275 .IP "\fBprocess_id (read-only)\fR"
276 The process ID of a Postfix command or daemon process.
277 .IP "\fBprocess_name (read-only)\fR"
278 The process name of a Postfix command or daemon process.
279 .IP "\fBqueue_directory (see 'postconf -d' output)\fR"
280 The location of the Postfix top-level queue directory.
281 .IP "\fBsyslog_facility (mail)\fR"
282 The syslog facility of Postfix logging.
283 .IP "\fBsyslog_name (see 'postconf -d' output)\fR"
284 The mail system name that is prepended to the process name in syslog
285 records, so that "smtpd" becomes, for example, "postfix/smtpd".
286 .SH "SEE ALSO"
289 qmgr(8), queue manager
290 bounce(8), delivery status reports
291 postconf(5), configuration parameters
292 syslogd(8), system logging
293 .SH "README_FILES"
296 Use "\fBpostconf readme_directory\fR" or
297 "\fBpostconf html_directory\fR" to locate this information.
298 VIRTUAL_README, domain hosting howto
299 .SH "LICENSE"
304 The Secure Mailer license must be distributed with this software.
305 .SH "HISTORY"
310 This delivery agent was originally based on the Postfix local delivery
311 agent. Modifications mainly consisted of removing code that either
312 was not applicable or that was not safe in this context: aliases,
313 ~user/.forward files, delivery to "|command" or to /file/name.
315 The \fBDelivered-To:\fR message header appears in the \fBqmail\fR
316 system by Daniel Bernstein.
318 The \fBmaildir\fR structure appears in the \fBqmail\fR system
319 by Daniel Bernstein.
320 .SH "AUTHOR(S)"
323 Wietse Venema
324 IBM T.J. Watson Research
325 P.O. Box 704
326 Yorktown Heights, NY 10598, USA
328 Andrew McNamara
329 andrewm@connect.com.au
330 connect.com.au Pty. Ltd.
331 Level 3, 213 Miller St
332 North Sydney 2060, NSW, Australia