LOCAL_RECIPIENT_README   [plain text]

Introduction
============

As of Postfix version 2.0, the Postfix SMTP server now rejects mail
for recipients in $mydestination domains that it does not know about.
This feature was optional with previous Postfix versions.

The benefit is that this keeps undeliverable mail out of your queue.
The downside is that it may cause mail to be rejected when you
upgrade from a Postfix system that was not configured to reject
mail for unknown local recipients.

This document describes what steps you may need to take in order
to not have Postfix reject mail incorrectly.

For safety's sake, if you upgrade from a Postfix version that did
not use this feature, the Postfix SMTP server replies with a 450
(try again later) status code for users it does not know about.

Configuring the local_recipient_maps parameter
==============================================

The local_recipient_maps parameter specifies lookup tables with
all names or addresses of local recipients. A recipient address is
local when the address domain matches $mydestination or $inet_interfaces.

The right-hand side of the lookup tables is conveniently ignored.
In the left-hand side, specify a bare username, an @domain.tld
wild-card, or specify a user@domain.tld address.

If the local_recipient_maps parameter value is non-empty, then the
SMTP server will reject for an unknown local recipient mail with
"User unknown in local recipient table".

To turn off unknown local recipient rejects by the SMTP server, specify:

    /etc/postfix/main.cf:
	local_recipient_maps =

That is, an empty value. With this setting, the Postfix SMTP server
will not reject mail with "User unknown in local recipient table".

The default setting assumes that you use the default Postfix local
delivery agent for local delivery, where recipients are either UNIX
accounts or local aliases:

    /etc/postfix/main.cf:
	local_recipient_maps = proxy:unix:passwd.byname $alias_maps

You need to update the local_recipient_maps setting if one of the
following is true:

1 - You define your $mydestination domain recipients in files other
    than /etc/passwd or /etc/aliases.

    For example, you define $mydestination domain recipients in the
    $virtual_mailbox_maps files. In that case, you specify your local
    recipients as follows:

	/etc/postfix/main.cf:
	    local_recipient_maps = $virtual_mailbox_maps

    For non-Postfix delivery agents (i.e. not "local" or "virtual"),
    see further down this document.

2 - You run the Postfix SMTP server chrooted (specified in master.cf).

    On many systems you will have to copy the passwd file into the
    chroot environment.

    For example, on 4.4 BSD systems one would do the following:

	# mkdir /var/spool/postfix/etc
	# cp /etc/pwd.db /var/spool/postfix/etc

    On other systems one would do:

	# mkdir /var/spool/postfix/etc
	# cp /etc/pwd.db /var/spool/postfix/etc

    You may also have to copy /etc/nsswitch.conf, as well as files
    that are referenced by /etc/nsswitch.conf, but that is unlikely.

    The Postfix SMTP server has a safety net in place in case of a
    missing or inaccessible passwd file and will reply with a 450
    status code (try again) instead of losing your mail. Watch your
    maillog file for the obvious error messages.

3 - You redefined the local delivery agent in master.cf, or you
    redefined the "local_transport" setting in main.cf, so that
    mail for $mydestination domain recipients is delivered by
    something else than the default Postfix local delivery agent.

    Your local_recipient_maps setting needs to specify a database
    that lists all the known user names or addresses for that
    delivery agent. For example, if you deliver users in $mydestination
    domains via the virtual delivery agent, specify:

	/etc/postfix/main.cf
	    local_recipient_maps = $virtual_mailbox_maps

    Your user database will be searched for the user@domain address
    as well as for the bare username.

4 - You use the mailbox_transport or fallback_transport feature of
    the Postfix local delivery agent in order to deliver mail non-UNIX
    accounts.

    You need to add the database that lists the non-UNIX users:

	/etc/postfix/main.cf
	    local_recipient_maps = unix:passwd.byname, $alias_maps,
		<the database with non-UNIX accounts>

    Your database will be searched for the user@domain address as
    well as for the bare username.

5 - You use the luser_relay feature of the Postfix local delivery agent.

    In this case, you must disable the local_recipient_maps feature
    completely, so that Postfix accepts mail for all local addresses:

	/etc/postfix/main.cf
	    local_recipient_maps =