# Postfix Frequently Asked Questions

Up one level | Postfix FAQ

## Table of contents

- Postfix warnings and error messages
- POP or IMAP problems
- Problems with specific Operating Systems
- Example configurations
- Sendmail incompatibility
- Running hundreds of Postfix processes
- Postfix performance
- Receiving mail via the network
- Mail relaying
- Remote delivery
- Local (non-virtual) delivery
- Mailing lists
- Virtual domains
- Address rewriting
- Content filtering
- Other transports: UUCP, FAX, etc.
- Postfix queue maintenance
- Compiling and installing Postfix

### Postfix warnings and error messages

- Postfix rejects mail with "User unknown in local recipient table"
- Postfix rejects mail with "User unknown in virtual alias table"
- Postfix rejects mail with "User unknown in virtual mailbox table"
- Mail for unknown users in virtual domains fails with "mail loops back to myself"
- Postfix refuses mail for virtual domains with "relay access denied"
- What does "warning: cannot access UNIX password database" mean?
- What does "Error: too many hops" mean?
- What does "fatal: open database /etc/aliases.db" mean?
- What does "fatal: unknown service: smtp/tcp" mean?
- What does "biff_notify: Connection refused" mean?
- What does "NIS domain name not set - NIS lookups disabled" mean?
- Mail stays queued with: Host not found, try again
- Mail fails consistently with timeout or lost connection
- sendmail has set-uid root file permissions, or is run from a set-uid root process
- sendmail: unable to find out your login name
- warning: xxx.xxx.xxx.xxx: address not listed for hostname yyy.yyy.yyy
- Mail delivery fails with: "unknown mail transport error"
- Too many connections
- write queue file: No such file or directory
- write queue file: Unknown error 4294967289

### Example configurations

- Stand-alone machine
- Workstations and servers
- Null clients
- Running Postfix inside an intranet
- Running Postfix on a firewall
- Running Postfix on a dialup machine

### Sendmail incompatibility

- Postfix breaks "sendmail -v"
- Postfix sends no "delayed mail" notices
- Root's mail is delivered to nobody
- Postfix sends duplicate mail
- Postfix sends mail to every member of a distribution list
- Getting rid of the ugly Delivered-To: header
- Postfix breaks the majordomo "approve" command
- Postfix does not try all the MX addresses
- Postfix accepts MAIL FROM and RCPT TO "| command"

### Running hundreds of Postfix processes

- Running hundreds of Postfix processes on FreeBSD
- Running hundreds of Postfix processes on Linux
- Running hundreds of Postfix processes on Solaris
- Running thousands of Postfix delivery agents

### Postfix performance

- Mail stays queued in the incoming queue
- Postfix responds slowly to incoming SMTP connections

### Receiving mail via the network

- Postfix responds slowly to incoming SMTP connections
- Postfix logs SMTP clients as IP addresses
- warning: xxx.xxx.xxx.xxx: address not listed for hostname yyy.yyy.yyy

### Mail relaying

- Relaying mail for mobile users
- Postfix refuses mail for virtual domains with "relay access denied"
- Restricting what users can send mail to off-site destinations
- Configuring Postfix as MX host for a remote site

### Remote delivery

- Mail stays queued with: Host not found, try again
- Mail fails consistently with timeout or lost connection
- Postfix does not try all the MX addresses
- What does "fatal: unknown service: smtp/tcp" mean?
- Mail delivery fails with: "unknown mail transport error"

### Local (non-virtual) delivery

- Root's mail is delivered to nobody
- What does "biff_notify: Connection refused" mean?
- What does "NIS domain name not set - NIS lookups disabled" mean?
- Postfix rejects mail with "User unknown in local recipient table"
- Delivering some users locally while sending mail as user@domain
- Support for maildir-style mailboxes
- Using Procmail for system-wide local delivery
- Getting rid of the ugly Delivered-To: header
- Postfix sends duplicate mail
- Postfix sends mail to every member of a distribution list
- Postfix ignores the owner-list alias
- What does "fatal: open database /etc/aliases.db" mean?
- Mail delivery fails with: "unknown mail transport error"

### Mailing lists

- Postfix breaks the majordomo "approve" command
- Protecting internal email distribution lists
- Postfix sends duplicate mail
- Postfix sends mail to every member of a distribution list
- Postfix ignores the owner-list alias
- Commands, mailing lists, and /file/name destinations don't work in Postfix virtual maps

### Virtual domains

- Postfix rejects mail with "User unknown in virtual alias table"
- Postfix rejects mail with "User unknown in virtual mailbox table"
- Postfix does not refuse mail for unknown users in virtual domains
- Mail for unknown users in virtual domains fails with "mail loops back to myself"
- Postfix refuses mail for virtual domains with "relay access denied"
- Commands, mailing lists, and /file/name destinations don't work in Postfix virtual maps
- Receiving a virtual domain in a mailbox

### Address rewriting

- Address masquerading with exceptions

### Content filtering

- What does "Error: too many hops" mean?

### Other transports: UUCP, FAX, etc.

- Using UUCP over TCP
- Setting up an Internet to UUCP gateway
- Using UUCP as the default transport
- Sending mail to a FAX machine

### Postfix queue maintenance

- Deleting a message from the Postfix queue
- Moving or restoring the Postfix queue

### Compiling and installing Postfix

- Undefined symbols: ___dn_expand, ___res_init etc.
- Undefined symbols: dbm_pagfno, dbm_dirfno etc.
- Using third-party DB libraries
- IRIX problems translating IP address to string

### Problems with specific Operating Systems

- Problems with Compaq
- Problems with IRIX

### Problems with Compaq

- Compaq mail blackhole problem

### Problems with IRIX

- IRIX problems translating IP address to string

### POP or IMAP problems

Postfix is a mail delivery system. Postfix does not implement services such as POP or IMAP to read mail. Several POP/IMAP implementations exist that can cooperate with software such as Postfix.

Examples of software that is used successfully with Postfix:

- Cyrus IMAP implements IMAP, POP3, and KPOP, later versions also support TLS. This software implements its own private mail database system. Not for beginners.

- Courier-Imap provides POP3 and IMAP, and supports access over SSL. This software supports the maildir-style mailbox format only (one message per file, same format as qmail).

- Qpopper supports POP3, TLS (SSL), and uses the traditional UNIX-style mailbox format (multiple messages per file, each message starts with "From sender date...").

### Stand-alone machine

Out of the box, Postfix should work without change on a stand-alone machine that has direct Internet access. At least, that is how Postfix installs when you download the Postfix source code. If you are on a firewalled intranet, or if your machine is dial-up connected only a small part of the time, see the respective sections.

### Workstations and servers

This section describes a workstation-server environment. All systems send mail as user@domain. All systems receive mail for user@hostname. The server receives mail for user@domain, too.

Postfix has sane defaults for all parameters, so the text below shows only the overrides. In particular, Postfix will relay mail only from clients in its own subnetworks. The master.cf file (somewhat like inetd.conf) needs tweaking only if you have a very slow or a very fast network and/or machine.

Workstation:

        /usr/local/etc/postfix/main.cf:
            myorigin = $mydomain

Server:

        /usr/local/etc/postfix/main.cf:
            myorigin = $mydomain
            mydestination = $myhostname, localhost.$mydomain, $mydomain

In an environment like this. either the mail spool directory is shared via NFS, users access their mailboxes via POP, or each user receives her mail on her own workstation. In the latter case, each user has an alias on the server that forwards mail to the respective workstation:

Server:

        /etc/aliases:
            joe:    joe@joes.workstation
            jane:   jane@janes.workstation

On some systems the alias database is not in /etc/aliases. To find out the location for your system, execute the command postconf alias_maps.

### Null clients

A null client is a machine that can only send mail. It receives no mail from the network, and it does not deliver any mail locally. A null client typically uses POP or NFS for mailbox access.

In the following example, mail is sent as user@domain, and all mail is forwarded to the mail server that is responsible for the local domain.

        /usr/local/etc/postfix/main.cf:
            myorigin = $mydomain
            relayhost = $mydomain
    	local_transport = error:local delivery is disabled

        /usr/local/etc/postfix/master.cf:
            Comment out the SMTP server entry
            Comment out the local delivery agent entry

Since everything sends mail as user@domain, nothing sends mail as user@nullclient, and therefore no special configuration needs to be done on the mail server for mail addressed to user@nullclient.

### Running Postfix inside an intranet

The simplest way to set up Postfix on a host inside a firewalled network is to send all your mail to an intranet mail gateway, and to let that mail gateway take care of forwarding.

- Send mail as user@domain. This is optional but highly recommended because it allows users to change machines without hassle.

          /usr/local/etc/postfix/main.cf:
              myorigin = $mydomain

- Forward all mail to an intranet mail gateway, except for mail for the local machine:

          /usr/local/etc/postfix/main.cf:
              relayhost = $mydomain

  This assumes that your organization has set up internal MX records for the local domain.

  If your intranet does not use MX records internally, you have to specify the intranet mail gateway host itself:

          /usr/local/etc/postfix/main.cf:
              relayhost = host.my.domain

  If your intranet does not use DNS internally, you have to disable DNS lookups as well:

          /usr/local/etc/postfix/main.cf:
              disable_dns_lookups = yes

- Instead of the above you can configure Postfix to deliver intranet mail directly instead of sending it via the intranet mail gateway. In this case, do not specify a relayhost!!

  Specify default routing information for the internal domain in the transport table, and enable transport table lookups.

          /usr/local/etc/postfix/transport:
              my.domain               :
              .my.domain              :
              *                       smtp:gateway.my.domain

          /usr/local/etc/postfix/main.cf:
              transport_maps = hash:/usr/local/etc/postfix/transport

  Important: do not specify a relayhost in main.cf, or else mail for internal destinations will still be given to the relayhost.

  Specify dbm instead of hash if your system uses dbm files instead of db. To find out what map types Postfix supports, use the command postconf -m.

  Execute the command postmap /usr/local/etc/postfix/transport whenever you edit the transport table.

- Execute the command postfix reload to make the changes effective.

### Running Postfix on a firewall

Note: this text applies to Postfix versions 2.0 and later. To find out what Postfix version you have, execute the command postconf mail_version.

How to set up Postfix on the firewall machine so that it relays mail for domain.com to a gateway machine on the inside, and so that it refuses mail for *.domain.com? The problem is that the default relay_domains mail relaying restriction allows mail to *.domain.com when you specify domain.com.

- Specify a transport table to route mail for domain.com to the inside machine.

  Specify explicit settings for smtpd_recipient_restrictions and for mynetworks that allow local systems to send mail anywhere, and that allow remote systems to send mail only to user@domain.com.

  Specify what recipients exist (so that your queue does not fill up with undeliverable mail from spammers).

  Specify `local_recipient_maps =` if maintaining recipient information is not practical.

      /usr/local/etc/postfix/main.cf:
          myorigin = domain.com
          mydestination = domain.com
          local_recipient_maps = hash:/usr/local/etc/postfix/recipients
          transport_maps = hash:/usr/local/etc/postfix/transport
          mynetworks = 12.34.56.0/24
          smtpd_recipient_restrictions = permit_mynetworks reject_unauth_destination
          local_transport = error:local mail delivery is disabled on this machine

      /usr/local/etc/postfix/transport:
          domain.com   smtp:inside-gateway.domain.com   forwards user@domain.com

      /usr/local/etc/postfix/master.cf:
          Comment out the local delivery agent

  Specify dbm instead of hash if your system uses dbm files instead of db. To find out what map types Postfix supports, use the command postconf -m.

- Execute the command postmap /usr/local/etc/postfix/transport whenever you change the transport table.

- Execute the command postfix reload after a configuration change.

### Running Postfix on a dialup machine

This section applies to dialup connections that are down most of the time. For dialup connections that are up 24x7, see the workstations and servers section instead.

If you do not have your own hostname (as with dynamic IP addressing) and must send mail as user@your-isp.com, you should also study the the section on delivering some users locally while sending mail as user@domain.

- Route all outgoing mail to your provider.

  If your machine is disconnected most of the time, there isn't a lot of opportunity for Postfix to deliver mail to hard-to-reach corners of the Internet. It's better to drop the mail to a machine that is connected all the time.

          /usr/local/etc/postfix/main.cf:
              relayhost = smtprelay.someprovider.com

- Disable spontaneous SMTP mail delivery (on-demand dialup IP only).

  Normally, Postfix attempts to deliver outbound mail at its convenience. If your machine uses on-demand dialup IP, this causes your system to place a telephone call whenever you submit new mail, and whenever Postfix retries to deliver delayed mail. To prevent such telephone calls from being placed, disable spontaneous SMTP mail deliveries.

          /usr/local/etc/postfix/main.cf:
              defer_transports = smtp (Only for systems that use on-demand dialup IP)

- Disable SMTP client DNS lookups (dialup LAN only).

  Some people use Postfix to deliver mail across a LAN that is disconnected most of the time. Under such conditions, mail delivery can suffer from delays while the Postfix SMTP client performs sender and recipient domain DNS lookups in order to be standards-compliant. To prevent these delays, disable all SMTP client DNS lookups.

          /usr/local/etc/postfix/main.cf:
              disable_dns_lookups = yes (Only for delivery across LANs that are disconnected most of the time)

  When you disable DNS lookups, you must specify the relayhost as either a numeric IP address, or as a hostname that resolves to one or more IP addresses (with DNS lookup disabled, Postfix does no MX lookup).

- Flush the mail queue whenever the Internet link is established.

  Put the following command into your PPP or SLIP dialup scripts:

    /usr/sbin/sendmail -q (whenever the Internet link is up)

  The exact location of the sendmail command is system-specific. With some UNIX versions, use /usr/lib/sendmail.

  In order to find out if the mail queue is flushed, use something like:

          #!/bin/sh

          # Start deliveries.
          /usr/sbin/sendmail -q

          # Allow deliveries to start.
          sleep 10

          # Loop until all messages have been tried at least once.
          while mailq | grep '^[^ ]*\*' >/dev/null
          do
              sleep 10
          done

  If you have disabled spontaneous SMTP mail delivery, you also need to run the above command every now and then while the dialup link is up, so that newly-posted mail is flushed from the queue.

### Postfix breaks "sendmail -v"

Some people will complain that sendmail -v no longer shows the actual mail delivery.

With a distributed mail system such as Postfix, this is difficult to implement. Unlike sendmail, no Postfix mail delivery process runs under control by a user. Instead, Postfix delivers mail with daemon processes that have no parent-child relationship with user processes. This eliminates a large variety of potential security exploits with environment variables, signal handlers, and with other process attributes that UNIX passes on from parent process to child process.

Postfix uses multiple processes in order to insulate subsystems from each other. Making the delivery agents talk directly to user processes would defeat a lot of the effort that went into making Postfix more secure than ordinary mailers.

### Postfix sends no "delayed mail" notices

> When I was using Sendmail, after 4 hours, it would always send a receipt back to the sender saying mail delivery is delayed.

In order to make Postfix send "delayed mail" notifications after four hours, specify:

        /usr/local/etc/postfix/main.cf:
            delay_warning_time = 4h

With Postfix, delayed mail notices are turned off by default - people get enough mail already.

### Postfix sends duplicate mail

Some people will complain that Postfix sends duplicate messages. This happens whenever one message is mailed to multiple addresses that reach the same user. Examples of such scenarios are:

- One message is sent to the user, and to an alias that lists the user. The user receives one copy of the mail directly, and one copy via the alias.

- One message is sent to multiple aliases that list the user. The user receives one copy of the mail via each alias.

Some people will even argue that this is the "right" behavior. It is probably more a matter of expectation and of what one is used to.

This can be "fixed" only by making Postfix slower. In the above examples, Postfix would first have to completely expand all distribution lists before starting any delivery. By design, Postfix delivers mail to different destinations in parallel, and local delivery is no exception. This is why Postfix can be faster than sendmail.

### Postfix sends mail to every member of a distribution list

Some people will complain that Postfix sends mail to every member of a distribution list, including the poster. By default, Sendmail deletes the poster from distribution lists. Sendmail sends mail to the poster only when the "metoo" flag is explicitly turned on.

Wietse believes that Postfix implements the "right" behavior, and suspects that Sendmail's default behavior is a remnant from a dark past when Sendmail used some obscure algorithm to avoid aliasing loops.

### Postfix ignores the owner-list alias

Normally, when a local alias foo has a companion alias owner-foo, Postfix reports delivery errors to the owner address rather than the message originator.

However, as a result of a Postfix implementation artefact, the owner-foo alias takes effect only after the alias expansion is completed.

Delivery problems that happen while expanding the alias, including delivery to commands or files, are reported to the original sender envelope address.

The reason is that bounces are sent by the Postfix queue manager, which does not know that the sender address is being replaced.

This limitation will be fixed by changing how the Postfix local delivery agent deals with undeliverable mail.

### What does "fatal: open database /etc/aliases.db" mean?

DB files are maintained by the Berkeley DB library. The above message means one of the following things:

- The existing file does not have the expected file format. The cause is one of the following:

  - The file was created by Berkeley DB version 1 and you are using version 2 or 3 (or vice versa).

  - The file was written in "btree" format and Postfix expects "hash" format (or vice versa).

  To fix the problem for Postfix execute the following command as root:

  >         newaliases

  This creates the aliases.db in the format that Postfix expects.

- Or the problem could be something completely different. If the result of running `newaliases` is a zero-length aliases.db file, then you probably suffer from the following problem.

  - Postfix was compiled with #include files for Berkeley DB version X and was linked against object library files for Berkeley DB version Y, where X and Y are different versions of the Berkeley DB library.

  The fix for this is to properly install the Berkeley DB library. For example, RedHat version 7.0 uses the Berkeley DB version 3 object library by default, but no /usr/include/db.h file is installed by default. In order to correctly build Postfix you must install the db3-devel package.

  On a properly installed system, including the file <db.h> and linking with -ldb should access files from the same Berkeley DB library version.

### sendmail has set-uid root file permissions, or is run from a set-uid root process

Traditionally, the UNIX sendmail command is installed with set-uid root permissions. Even many MTAs other than Sendmail ship with a set-uid root sendmail command. This is not the case with Postfix. The Postfix sendmail command is designed not to be set-uid.

Unfortunately, some Linux systems have a helpful utility called linuxconf that automatically "fixes" file permissions to what they are supposed to be for Sendmail's sendmail command. Even when you reset the set-uid bit on the Postfix sendmail executable file, linuxconf will happily turn it on again for you.

On SuSE systems the file permission fixing utulity is called SuSEconfig. Other Linux systems may use different names. The usual disclaimers about mileages etc. apply.

#### Solutions

- Rask Ingemann Lambertsen has a particularly effective solution :-)

  >     # /etc/rc.d/init.d/linuxconf stop && rpm --erase linuxconf

- According to Matthias Andree, the band-aid fix for SuSE is to add to /etc/permissions.local the following line:

  >     /usr/sbin/sendmail root.root 755

  and to make sure that in /etc/rc.config, PERMISSIONS_SECURITY mentions local last, EXAMPLE:

  >     CHECK_PERMISSIONS=set
  >     PERMISSION_SECURITY="secure local"

### sendmail: unable to find out your login name

This message is logged when submitting mail from a process with a userid that does not exist in the UNIX password file. Postfix uses this information in order to set the envelope sender address.

The envelope sender address is also the default value for the From: header address, when none is specified in the message.

To fix, specify the envelope sender address on the sendmail command line:

>     sendmail -f user@domain ...

### Running hundreds of Postfix processes on FreeBSD

With hundreds of Postfix processes, the kernel will eventually run out of file handles; after that, it will run out of sockets.

To set the following kernel parameters at boot time, add the following lines to the /boot/loader.conf file (this is verified with FreeBSD 4.4):

>     kern.ipc.maxsockets="5000"
>     kern.ipc.nmbclusters="65536"
>     kern.maxproc="2048"
>     kern.maxfiles="16384"
>     kern.maxfilesperproc="16384"

With FreeBSD 4.2, the last three parameters cannot be set from /boot/loader.conf. To set the open file limits, execute the following commands as root:

>     # sysctl -w kern.maxfiles=16384
>     # sysctl -w kern.maxfilesperproc=16384

With FreeBSD 4.2, kern.maxproc can be set only by recompiling the kernel with a different maxusers setting in the kernel configuration file.

### Running hundreds of Postfix processes on Linux

When you increase the number of Postfix processes into the hundreds, the kernel will eventually run out of file handles; after that it is likely to run out of process slots.

The following information is kernel version dependent.

To set parameters at boot time on Linux systems that have /etc/sysctl.conf, add the following lines:

>     fs.file-max = 16384
>     kernel.threads-max = 2048

To set kernel parameters at run time, execute the following commands as root:

>     # echo 16384 > /proc/sys/fs/file-max
>     # echo 2048 > /proc/sys/kernel/threads-max

### Running hundreds of Postfix processes on Solaris

In order to run hundreds of processes you may have to adjust the per-process open file limit. According to the Solaris FAQ, add the following lines to /etc/system on Solaris 2.4 and later:

>     * set hard limit on file descriptors
>     set rlim_fd_max = 4096
>     * set soft limit on file descriptors
>     set rlim_fd_cur = 2048

### Running thousands of Postfix delivery agents

In order to run Postfix with more than a thousand delivery agents you need to recompile the software with an appropriate value of the FD_SETSIZE constant.

>     % make tidy
>     % make makefiles "CCARGS=-DFD_SETSIZE=2048"
>     % make

### Mail stays queued in the incoming queue

> I have lots if mail in the incoming queue, but Postfix only runs a few outbound SMTP deliveries. Why is it not running more SMTP clients?

Your problem could be one of several.

- You're trying to send mail to difficult to reach sites (Hotmail, Yahoo, etc.). Solution: set up transport map entries that give special treatment (many parallel connections, short connection timeouts):

      /usr/local/etc/postfix/main.cf:
          transport_maps = hash:/usr/local/etc/postfix/transport
          deadbeats_destination_concurrency_limit = 50

      /usr/local/etc/postfix/transport:
          hotmail.com		deadbeats:
          yahoo.com		deadbeats:

      /usr/local/etc/postfix/master.cf:
          deadbeats	  unix	-	-	n	-	-	smtp
      	-o smtp_connect_timeout=5 -o smtp_helo_timeout=5

- Incoming mail, destined for a small number of inside mailhubs, is competing with outgoing mail to the Internet. As of Postfix version 2, this should be less of a problem. However, when a single internal mailhub goes down, it can totally ruin the performance because Postfix is wasting huge amounts of time on connection timeouts. The solution is to specify shorter connection timeouts for the inbound relay transport:

      /usr/local/etc/postfix/main.cf:
          mydestination = my.own.host.name
          relay_domains = my.corp.domain
          relay_transport = relay

      /usr/local/etc/postfix/master.cf:
          relay	  unix	-	-	n	-	-	smtp
      	-o smtp_connect_timeout=2 -o smtp_helo_timeout=2

- The disk is saturated with I/O from receiving mail, so that the Postfix queue manager gets insufficient chance to process the requests (many SMTP server processes are competing for disk access against one poor queue manager).

  You solve the problem by getting faster disks, and/or by using different disk drives for logging, mail queue, and mailboxes.

  Currently, the workaround is to configure multiple IP addresses per machine, and to run one Postfix instance per IP address, each instance preferably on a different disk. The Postfix instances can't share queue directories, but sharing mailbox directories is OK.

  Just start each Postfix instance with a different configuration directory:

          # postfix -c config_directory start

  Each main.cf file has a different $myhostname setting, depending on the interface that it is supposed to handle.

          /my/own/main.cf:
              queue_directory = /my/own/queue/directory
              myhostname = foo1.my.domain
              inet_interfaces = $myhostname

### Postfix responds slowly to incoming SMTP connections

Question:

> My Postfix server is too slow. When I telnet to the SMTP port (`telnet hostname 25`), the response comes after 40 seconds. On the other hand, when I telnet to the POP port (`telnet hostname 110`) the response comes with no delay.

Answers:

> 1) You need to configure Postfix to run more SMTP server processes. Edit the smtpd entry in the master.cf file and asjust the process limit, or increase the default_process_limit setting in the main.cf file. Issue the command postfix reload to make the change effective.

> 2) You have a name service problem.

> Postfix calls the C library routines gethostbyname() and gethostbyaddr() in order to find out the SMTP client hostname. These library routines use several system configuration files in order to satisfy the request. They may in fact end up calling the DNS for reasons that are not under control by Postfix.

> Depending on your system, these controlling files can be named /etc/nsswitch.conf, /etc/svcorder, /etc/host.conf or otherwise. Those files specify whether the C library routines will use local /etc/hosts before or after DNS.

### Postfix logs SMTP clients as IP addresses

> The Postfix SMTP server logs client connections with numerical IP addresses instead of resolving the hostname. When I use nslookup the address does resolve to a name.

You run the Postfix SMTP server inside a chroot jail for extra security, but some configuration files are missing. In order to run inside a chroot jail, the Postfix SMTP client and server need copies of system configuration files inside the Postfix queue directory. The exact list of files is very system dependent, but you will probably need at the very least:

        /var/spool/postfix/etc/resolv.conf
        /var/spool/postfix/etc/services

Of course, these directories and files must be owned by root, but they must be accessible by the postfix user, so directories need mode 0755 and files need mode 0644.

For more details, see the files in the examples/chroot-setup directory of the Postfix source code distribution.

### warning: xxx.xxx.xxx.xxx: address not listed for hostname yyy.yyy.yyy

Postfix uses hostnames in its junk mail and mail relay controls. This means that in theory someone could be motivated to set up bogus DNS information, in order to get past your junk mail or mail relay controls.

When Postfix looks up the SMTP client hostname for the SMTP client IP address, then Postfix also checks if the SMTP client IP address is listed under the SMTP client hostname.

If the SMTP client IP address is not listed under the SMTP client hostname, then Postfix concludes that the SMTP client hostname does not belong to the SMTP client IP address, and ignores the SMTP client hostname. A warning is logged, so that you can find out why an SMTP client is or is not stopped by your junk mail or mail relay checks.

You could contact the people who maintain the SMTP client's DNS records, and explain to them that each IP address needs one PTR record, and that this one PTR record needs a matching A record.

Some people read the RFCs such that one IP address can have multiple PTR records, but that makes PTR records even less useful than they already are. And in any case, having multiple names per IP address only worsens the problem of finding out the SMTP client hostname.

### Relaying mail for mobile users

> I have Postfix setup on a machine but I'd like to have a select group of Internet users be able to relay mail through it. I'd either like to base the relaying on IP address (e.g., a 256-block for dynamic IP people) or on hostname (whatever.dialup.isp.com)

The most preferable way is to have users submit mail via some authenticated protocol instead of plain old SMTP.

The next best way is to use plain old SMTP and to authenticate the user first, for example, with a "please login via POP before using SMTP" scheme. In that case, some software maintains a Postfix-compatible access table with client IP address information.

        /usr/local/etc/postfix/main.cf:
            smtpd_recipient_restrictions =
                permit_mynetworks
                check_client_access hash:/usr/local/etc/postfix/client_access
                reject_unauth_destination

        /usr/local/etc/postfix/client_access:
            4.3.2.1         OK
            5.4.3.2         987654321

Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what map types Postfix supports, use the command postconf -m.

N.B. Some non-Postfix software uses btree files instead of hash files. In that case, you will have to adjust the above check_client_access restriction accordingly.

A less preferable way is based on client IP address (for example, a 256-block) or DNS hostname (for example, whatever.pop.isp.com). This scheme does not authenticate the user. If you use IP/DNS-based relay access control, pray that no customer with that same ISP points their spam software at your machine, or else you may end up on internet-wide black lists.

The least preferable way is based on the sender address. It is trivially easy to spoof by anyone who ever received mail from your site. If you use sender address access control, pray that no spammer ever finds out the address of your users.

        /usr/local/etc/postfix/main.cf:
            smtpd_recipient_restrictions =
                permit_mynetworks
                check_client_access hash:/usr/local/etc/postfix/client_access
                check_sender_access hash:/usr/local/etc/postfix/sender_access
                reject_unauth_destination

        /usr/local/etc/postfix/client_access:
            11.22.33                OK
            dialup.isp.com          OK

        /usr/local/etc/postfix/sender_access:
            joe@my.domain           OK
            blow@my.domain          OK

### Restricting what users can send mail to off-site destinations

> How can I configure Postfix in a way that some users can send mail to the internet and other users not. The users with no access should receive a generic bounce message. Please don't discuss whether such access restrictions are necessary, it was not my decision.

Postfix has support for per-user restrictions. The restrictions are implemented by the SMTP server. Thus, users that violate the policy have their mail rejected by the SMTP server. Like this:

>     554 <user@remote>: Access denied

The implementation uses two lookup tables. One table defines what users are restricted in where they can send mail, and the other table defines what destinations are local. It is left as an exercise for the reader to change this into a scheme where only some users have permission to send mail to off-site destinations, and where most users are restricted.

The example assumes DB/DBM files, but this could also be done with LDAP or SQL.

        /usr/local/etc/postfix/main.cf:
            smtpd_recipient_restrictions =
                check_sender_access hash:/usr/local/etc/postfix/restricted_senders
                ...other stuff...

            smtpd_restriction_classes = local_only
            local_only = check_recipient_access hash:/usr/local/etc/postfix/local_domains, reject

        /usr/local/etc/postfix/restricted_senders:
            foo@domain      local_only
            bar@domain      local_only

        /usr/local/etc/postfix/local_domains:
            this.domain     OK      matches this.domain and subdomains
            that.domain     OK      matches that.domain and subdomains

Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what map types Postfix supports, use the command postconf -m.

The smtpd_restriction_classes verbiage exists so that Postfix can open /usr/local/etc/postfix/local_domains.db before entering a chroot jail, so it is only an artefact of implementation.

This scheme does not authenticate the user, therefore it can be bypassed in several ways:

- By sending mail as someone else who does have permission to send mail to off-site destinations.

- By sending mail as yourself via a less restrictive mail relay host.

### Configuring Postfix as MX host for a remote site

When you are secondary mx for a remote site this is all you need:

        DNS:
            the.backed-up.domain.tld        IN      MX 100 your.machine.tld

        /usr/local/etc/postfix/main.cf:
            relay_domains = $mydestination the.backed-up.domain.tld
            smtpd_recipient_restrictions = permit_mynetworks reject_unauth_destination

DO NOT LIST the.backed-up.domain.tld in MYDESTINATION

When you are primary mx for a remote site you also need:

        /usr/local/etc/postfix/main.cf:
            transport_maps = hash:/usr/local/etc/postfix/transport

        /usr/local/etc/postfix/transport:
            the.backed-up.domain.tld       relay:[their.mail.host.tld]

Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what map types Postfix supports, use the command postconf -m.

### Mail stays queued with: Host not found, try again

> When I send mail to a remote address, the following happens:

>         Jul 14 12:45:38 myhostname postfix/qmgr[2246]: 74FBF30501:
>             from=<sender@sender.domain> size=309 (queue active)
>         Jul 14 12:45:39 myhostname postfix/smtp[2349]: 74FBF30501:
>             to=<recip@recip.domain> relay=none, delay=3944,
>             status=deferred (Name service error for name=recip.domain
>             type=MX: Host not found, try again)

> However, I can nslookup the hostname just fine.

There can be several different problems.

- First of all, the result of nslookup for the hostname may be irrelevant. Postfix is required to look up the MX record first. So your nslookup test should begin with asking for the MX record. Some DNS servers are broken and produce no reply when asked for a non-existent MX record.

- Secondly, the nslookup test is invalid if you ran it as a privileged user. Postfix DNS lookups are known to fail because of incorrect permissions on system files and directories. For example, a common beginner's mistake is to lose world read permission for the /etc/resolv.conf file.

- Check out your Postfix master.cf file. If the SMTP client runs chrooted, then it needs a bunch of files inside the Postfix queue directory. Examples are in the source distribution in the examples subdirectory.

### Mail fails consistently with timeout or lost connection

Every now and then, mail fails with "timed out while sending end of data -- message may be sent more than once", or with: "lost connection after DATA". Network outages happen, systems crash. There isn't much you can do about it. Usually the problem goes away by itself.

However, when you see mail deliveries fail consistently, you may have a different problem: broken path MTU discovery. Or it could be a broken PIX firewall.

#### Cisco PIX "fixup protocol smtp" bug

The Cisco PIX firewall has a bug when running software older than version 5.2(4) or 6.0(1).

The bug ID is CSCds90792. The "fixup protocol smtp" feature does not correctly handle the case where the "." and the "CRLF" at the end of mail are sent in separate packets.

How does one recognize a mailer behind a Cisco PIX with "fixup protocol smtp" enabled? As of version 5.1 and later, the fixup protocol smtp command changes the characters in the SMTP banner to asterisks except for the "2", "0" and "0 SPACE" characters.

When you connect to a mailer behind such a filter you see something like:

>     220 **************************************0******0*********20 ****200**0*********0*00

#### IP path MTU discovery

A little background is in order. With the SMTP protocol, the HELO, MAIL FROM and RCPT TO commands and responses are relatively short. When you're talking to old versions of sendmail, every command and every response is sent as a separate packet, because sendmail didn't implement ESMTP command pipelining until recently.

The message content, however, is sent as a few datagrams, each datagram typically a kbyte large or even bigger, depending on your local network MTU.

When mail fails consistently due to a timeout, I suspect that the sending machine runs a modern UNIX which implements path MTU discovery. That causes the machine to send packets as large as it would send over the LAN, with the IP DON'T FRAGMENT bit set, preventing intermediate routers from fragmenting the packets that are too big for their networks.

Depending on what network path a message follows, some router on the way responds with an ICMP MUST FRAGMENT message saying the packet is too big. Normally, the sending machine will re-send the data after chopping it up into smaller pieces.

However, things break when some router closer to the sending system is dropping such ICMP feedback messages, in a mistaken attempt to protect systems against certain attacks. In that case, the ICMP feedback message never reaches the sending machine, and the connection times out.

This is the same configuration problem that causes trouble with web servers behind a misconfigured packet filter: small images/files are sent intact, large images/files time out because the server does not see the MUST FRAGMENT ICMP feedback messages.

Workaround: at the sending machine, disable path MTU discovery. Mail will get out, but of course everyone else will still suffer. How to disable path MTU discovery? It depends. Solaris has an ndd command; other systems use different means such as sysctl to control kernel parameters on a running system.

Workaround: at the receiving machine, set a smaller MTU. For example, people using PPPoE (PPP over Ethernet) often have to choose an MTU lightly smaller than the default 1500 for ethernet.

Fix: find the router that drops the ICMP MUST FRAGMENT messages, and convince the person responsible for it to fix the configuration.

### Postfix does not try all the MX addresses

When delivering mail, Postfix tries all MX addresses in order of preference, and stops at the first server that speaks SMTP. However, once an SMTP greeting is received, Postfix will not move on to the next MX host if the delivery fails.

This will eventually be solved when Postfix implements SMTP connection caching.

### What does "fatal: unknown service: smtp/tcp" mean?

Your Postfix /usr/local/etc/postfix/master.cf file specifies that the Postfix SMTP client runs inside a chroot environment. However, the files necessary for that mode of operation are not installed below /var/spool/postfix.

Enabling chroot operation adds a non-trivial barrier for system penetrators.

Two solutions:

- Disable the chroot in /usr/local/etc/postfix/master.cf (and issue postfix reload when done).

- Install the necessary files for chroot operation. Instructions are given in the source code distribution, in the examples/chroot-setup directory.

### Mail delivery fails with: "unknown mail transport error"

This is an opportunity to meet your friends egrep and less. Postfix activity, including progres and failure, is logged to a logfile, typically named /var/log/maillog. To find out where Postfix activity is logged on your machine, examine the /etc/syslog.conf file.

To find out the cause for the "unknown mail transport error", type the following command:

> `egrep '(warning|fatal|panic):' /var/log/maillog | less`

Pay particular attention to messages that are labeled as fatal and panic. These describe catastrophic failures that need to be addressed before Postfix is happy. Problems labeled as fatal are fixed by you, by adjusting configuration files, file permissions and so on. Problems labeled as panic are fixed by the Postfix author, by changing Postfix source code.

### Root's mail is delivered to nobody

If you use procmail (or some other command) for local mail delivery, Postfix will not deliver mail as root. Instead, Postfix runs procmail (or whatever) as nobody. Perhaps some day Wietse will trust Postfix enough to run external commands as root.

Solution: just like you're not supposed to log in as root (except for unusual conditions), you're not supposed to receive mail as root.

- Create a mail alias for root that forwards mail to a real user.

      /etc/aliases:
          root:       you

- Execute the command newaliases whenever you change the alias database.

On some systems the alias database is not in /etc/aliases. To find out the location for your system, execute the command postconf alias_maps.

### What does "biff_notify: Connection refused" mean?

By default, the Postfix local delivery agent attempts to notify local users of the arrival of new mail. This feature makes use of the comsat network service, which is turned off on many UNIX systems for performance and/or security reasons.

The Postfix warning message means that new mail notification failed because the comsat network service is turned off.

To disable the comsat client code in the Postfix delivery agent, specify:

    /usr/local/etc/postfix/main.cf:
        biff = no

Note: recent versions of procmail also produce biff notifications. To silence biff completely you may also have to update procmail configuration files.

To enable the comsat network service, uncomment the corresponding entry in the inetd.conf file, and kill -HUP the inetd process.

### What does "NIS domain name not set - NIS lookups disabled" mean?

The warning message means that NIS (Network Information Service) is not enabled on your machine. That is perfectly OK. It's just hard for Postfix to find out about these things ahead of time.

To disable the NIS client code in the Postfix local delivery agent, update the corresponding section in the main.cf file and specify one of the following, depending on the type of aliases file:

    /usr/local/etc/postfix/main.cf:
        alias_maps = $alias_database

This forces Postfix to use only the local aliases database, if one is defined.

### Postfix rejects mail with "User unknown in local recipient table"

As of version Postfix 2.0, you are expected to tell the Postfix SMTP server what local users exist by listing all tables with local usernames or addresses in the local_recipient_maps parameter. To find out what Postfix version you have, execute the command postconf mail_version.

The default local_recipient_maps setting assumes that you use the default Postfix local delivery agent:

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

You need the proxy: part only if master.cf specifies that the Postfix SMTP server runs chrooted. As distributed by the author, Postfix runs no daemons chrooted.

The local recipients tables are searched by the recipient address (user@domain) and by the recipient name (the address minus the domain). Postfix does not care what the lookup result looks like, so you can use any database that Postfix understands the format of.

To stop Postfix from rejecting local mail incorrectly:

- If you run the Postfix SMTP server chrooted, you need to access the system password database through the Postfix proxymap service, as shown in the above example. The alternative is simply not practical: placing a copy of the passwd file inside the chroot jail (typically: in /var/spool/postfix/etc) together with a list of system dependent files.

- If you enable the local delivery agent luser_relay feature, then you must disable the local_recipient_maps feature as described below.

- If you use the local delivery agent mailbox_transport or fallback_transport features to receive mail for users not in /etc/passwd, then you need to list those users under local_recipient_maps, or you need to disable the local_recipient_maps feature as described below.

- If you redefine the local delivery agent in master.cf or in the local_transport setting in main.cf, then you need to list the local recipients under local_recipient_maps, or you need to disable the local_recipient_maps feature as described below.

To disable the local_recipient_maps feature, specify:

        /usr/local/etc/postfix/main.cf:
            local_recipient_maps =

With this setting, the Postfix SMTP server will not reject mail for unknown local recipients.

### Delivering some users locally while sending mail as user@domain

- In order to send mail as user@domain.tld, specify what domain is to be appended to addresses that do not have a domain:

      /usr/local/etc/postfix/main.cf:
          myorigin = domain.tld

- In order to receive some users locally, such as root or postmaster, specify a virtual lookup table with the non-default destinations:

      /usr/local/etc/postfix/main.cf:
          virtual_alias_maps = hash:/usr/local/etc/postfix/virtual

      /usr/local/etc/postfix/virtual:
          root        root@localhost
          postmaster  postmaster@localhost

  Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what map types Postfix supports, use the command postconf -m.

- Execute the command postmap /usr/local/etc/postfix/virtual whenever you edit the virtual table.

- Execute the command postfix reload to make the changes effective.

### Support for maildir-style mailboxes

Maildir is a specific one-file-per-message organization that was introduced with the qmail system by Daniel Bernstein. In order to turn on maildir-style delivery, specify, for example:

        /usr/local/etc/postfix/main.cf:
            home_mailbox = Maildir/

Any relative pathname that ends in / turns on maildir delivery. The home_mailbox value is appended to the user's home directory pathname.

The maildir format is also supported with delivery via aliases or via .forward files. Specify /file/name/ as destination. The trailing / turns on maildir delivery.

### Using Procmail for system-wide local delivery

Warning: if you use procmail in this manner, you must set up an alias for root that forwards mail for root to a real user. See the FAQ entry titled "Mail for root is delivered to nobody".

- Specify that all mailbox delivery is to be done by procmail. For example:

          /usr/local/etc/postfix/main.cf:
              mailbox_command = /path/to/procmail

          /usr/local/etc/postfix/main.cf:
              mailbox_command = /path/to/procmail -a $EXTENSION

  If you can, avoid using any shell meta characters or built-ins such as $ or " or IFS or &&, because they force Postfix to run an expensive shell process. However, procmail is a pig, and the gain of avoiding a shell can be unnoticeable.

- Execute the command postfix reload to make the changes effective.

Postfix exports information via environment variables. The contents are censored. Characters that may have special meaning to the shell, including whitespace, are replaced by underscores.

> DOMAIN
>   The text to the right-hand side of the @ in the recipient address.
> EXTENSION
>   Optional address extension part.
> HOME
>   The recipient's home directory.
> LOCAL
>   The text to the left-hand side of the @ in the recipient address, for example, $USER+$EXTENSION.
> LOGNAME
>   The recipient username.
> RECIPIENT
>   The entire recipient address, $LOCAL@$DOMAIN.
> SENDER
>   The complete sender address.
> SHELL
>   The recipient's login shell.
> USER
>   The recipient username.

### What does "warning: cannot access UNIX password database" mean?

This message is logged when, for example, the Postfix SMTP server is unable to access the UNIX password database.

- If you're running the Postfix SMTP server chrooted (see master.cf) then you need to access the system password database through the Postfix proxymap service. The alternative is not practical: copying the password file and perhaps a bunch of other system dependent files into the Postfix queue directory.

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

- Chrooted or not, be sure that you have world execute permissions on directories and world read permission on the passwd file and any auxiliary files that may be needed (such as /etc/nsswitch.conf and libnss*.so* files referenced by /etc/nsswitch.conf).

### Getting rid of the ugly Delivered-To: header

Some people will complain about the ugly Delivered-To: message header that Postfix prepends to their mail. By default, Postfix prepends this header when forwarding mail, and when delivering to file (mailbox) or command. The purpose is to stop mail forwarding loops as early as possible, that is, before they have a chance to happen. But the header is ugly, no question about it.

Solutions, ranging from fighting symptoms to turning off the Delivered-To: header:

- Fortunately, many mail user agents have per-user or even system-wide configuration files that can be set up to suppress Delivered-To: headers (for example ~/.mailrc and /usr/lib/Mail.rc).

- With mailing lists, Delivered-To: can get in the way when the list exploder uses a "secret" alias that should not be shown in outbound mail. The recommended solution is to use a regular expression-based filter at the SMTP port:

          /usr/local/etc/postfix/main.cf:
              smtpd_recipient_restrictions =
                  ... regexp:/usr/local/etc/postfix/access_regexp ...
              smtpd_recipient_restrictions =
                  ... pcre:/usr/local/etc/postfix/access_regexp ...

          /usr/local/etc/postfix/access_regexp:
              /^(.*)-outgoing@(.*)/   554 Use $1@$2 instead

  POSIX regular expression support (regexp) is enabled by default on modern UNIX systems. Perl-compatible regular expression support (pcre) is optional; see the PCRE_README file in the top-level Postfix source directory.

- The prepend_delivered_header configuration parameter controls when Delivered-To: is prepended. The default setting is command, file, forward (translation: prepend Delivered-To: when delivering to command, when delivering to file, and when forwarding mail). Turning off Delivered-To: when forwarding mail is not recommended.

See also the FAQ item for problems with the majordomo approve command.

### Postfix breaks the majordomo "approve" command

The Postfix local delivery agent prepends a Delivered-To: message header to prevent mail forwarding loops. With majordomo mailing lists, Delivered-To: gets in the way when the moderator wants to approve postings that were sent to the list. The Postfix system claims that the mail is looping.

Currently, the recommended workaround is to edit the approve script to strip any header lines that match:

        /delivered-to/i

Yes, this assumes that the moderator knows what she is doing.

A less-preferred workaround is to not insert Delivered-To: when delivering to commands such as majordomo. See the FAQ entry titled "Getting rid of the ugly Delivered-To: header".

### Postfix accepts MAIL FROM and RCPT TO "| command"

With Postfix, | or / has special meaning only when it appears in aliases, .forward files or in :include: files. It has no special meaning in mail addresses.

If you must receive mail for systems with 10-year old vulnerabilities, it is prudent to set up a regexp filter that rejects potentially harmful MAIL FROM or RCPT TO commands.

        /usr/local/etc/postfix/main.cf:
            smtpd_sender_restrictions =
                regexp:/usr/local/etc/postfix/envelope-regexp
                reject_unknown_sender_domain
            smtpd_recipient_restrictions =
                regexp:/usr/local/etc/postfix/envelope-regexp
                permit_mynetworks
                reject_unauth_destination

        /usr/local/etc/postfix/envelope-regexp:
            /[/|]/  REJECT

However, rejecting all envelope addresses with / causes trouble with simple-minded X.400 to Internet address mappings that leave the X.400 address structure exposed.

See also the documentation on header checks restrictions for message header contents. These restrictions can be used to protect against attacks with command/file destinations in, for example, Errors-To: or Return-Receipt_To: message headers.

### Protecting internal email distribution lists

> We want to implement an internal email distribution list. Something like all@our.domain.com, which aliases to all employees. My first thought was to use the aliases map, but that would lead to "all" being accessible from the "outside", and this is not desired... :-)

Postfix can implement per-address access controls. What follows is based on the SMTP client IP address, and therefore is subject to IP spoofing.

        /usr/local/etc/postfix/main.cf:
            smtpd_recipient_restrictions =
                hash:/usr/local/etc/postfix/access
                ..the usual stuff...

        /usr/local/etc/postfix/access:
            all     permit_mynetworks,reject

Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what map types Postfix supports, use the command postconf -m.

Now, that would be sufficient when your machine receives all Internet mail directly from the Internet. That's unlikely if your network is a bit larger than an office. For example your backup MX hosts would "launder" the client IP address of mail from outside so it would appear to come from a trusted machine.

In the general case you need two lookup tables: one table that lists destinations that need to be protected, and one table that lists domains that are allowed to send to the protected destinations.

What follows is based on the sender SMTP envelope address, and therefore is subject to SMTP sender spoofing.

        /usr/local/etc/postfix/main.cf:
            smtpd_recipient_restrictions =
                hash:/usr/local/etc/postfix/protected_destinations
                ..the usual stuff...

            smtpd_restriction_classes = insiders_only
            insiders_only = check_sender_access hash:/usr/local/etc/postfix/insiders, reject

        /usr/local/etc/postfix/protected_destinations:
            all@my.domain   insiders_only
            all@my.hostname insiders_only

        /usr/local/etc/postfix/insiders:
            my.domain       OK
            another.domain  OK

The smtpd_restriction_classes verbiage is needed so that Postfix knows what lookup tables to open before it goes to chroot jail. It is only an artefact of the implementation.

Getting past this scheme is relatively easy, because all one has to do is to spoof the SMTP sender address.

If the internal list is a low-volume one, perhaps it makes more sense to make it moderated.

### Postfix rejects mail with "User unknown in virtual alias table"

Answer: you have listed the virtual domain name in the tables specified with the virtual_alias_domains parameter, but the recipient address is not listed in the tables specified with the virtual_alias_maps parameter.

If you want to deliver the domain via the Postfix virtual(8) mailbox delivery agent, then you should list the virtual domain name in the tables specified with the virtual_mailbox_domains parameter instead.

### Postfix rejects mail with "User unknown in virtual mailbox table"

Answer: you have listed the virtual domain name in the tables specified with the virtual_mailbox_domains parameter, but the recipient address is not listed in the tables specified with the virtual_mailbox_maps parameter.

If you want to deliver the domain as a virtual(5) alias domain, where each address is aliased to a real local or remote address, then you should list the virtual domain name in the tables specified with the virtual_alias_domains parameter instead.

### Postfix does not refuse mail for unknown users in virtual domains

### Mail for unknown users in a virtual domain fails with "mail loops back to myself"

### Postfix refuses mail for virtual domains with "relay access denied"

Solutions:

- Specify a virtual alias domain as per the virtual(5) manual page.

- Specify a virtual mailbox domain as per the virtual(8) manual page.

### Commands, mailing lists, and /file/name destinations don't work in virtual domains

Quick answer: set up "punch through" virtual aliases that redirect the mail to local Postfix aliases:

        /usr/local/etc/postfix/main.cf:
            virtual_alias_maps = hash:/usr/local/etc/postfix/virtual

        /usr/local/etc/postfix/virtual:
            listname@virtual.tld            listname
            owner-listname@virtual.tld      owner-listname
            listname-request@virtual.tld    listname-request

        /etc/aliases:
            listname: "|whatever"
            owner-listname: user@domain
            listname-request: "|whatever"

This redirects mail for virtual address listname@virtual.tld etc. to local address listname@your.domain.tld etc.. Mail for these local aliases is then delivered to external commands or files etc. by the Postfix local delivery agent.

Long answer:

Delivering mail to a file or command is a security-sensitive operation, because the operation must be executed with the right privileges. Only root-privileged software such as the Postfix local delivery agent can set the privileges for command or file delivery.

For security reasons, Postfix tries to avoid using root privileges where possible. In particular, Postfix virtual mapping is done by an unprivileged daemon, so there is no secure way to execute commands or to deliver to files specified in virtual maps.

### Receiving a virtual domain in a mailbox

Question: how to receive all mail for a domain in a mailbox without losing the original recipient information? The Postfix Delivered-To: mail header shows only the mailbox owner, not the virtual address that the mail was sent to.

Answer: Postfix logs the original recipient address in the X-Original-To: message header.

This requires that the enable_original_recipient parameter is not changed from its default value of yes. With enable_original_recipient set to no, messages to multiple recipients in the domain will only be delivered to the first recipient, and the X-Original-To: header will not be added to the message.

### Address masquerading with exceptions

For people outside your organization it can be desirable to only see addresses of the form user@company.com rather than addresses with individual internal host names. This can be achieved with address masquerading.

Address masquerading is intended for use only on mail gateways.

- In order to have all mail through the gateway host appear as coming from user@my.domain, specify:

          /usr/local/etc/postfix/main.cf:
              masquerade_domains = $mydomain

  Note that the gateway should have append_dot_mydomain and append_at_myorigin turned on (which is the default setting) so that all addresses are fully qualified before they are subjected to address masquerading.

In some cases, you may wish to have certain users or hosts exempted from masquerading.

- To exempt certain users from masquerading, such as root, specify:

          /usr/local/etc/postfix/main.cf:
              masquerade_exceptions = root

- To exempt certain hosts from masquerading, write masquerade_domains as:

          /usr/local/etc/postfix/main.cf:
              masquerade_domains = somehost.my.domain otherhost.my.domain $mydomain

  Note that the order above is crucial: exemptions such as somehost.my.domain must precede $mydomain in the statement.

  It should go without saying that if a particular host you wish to exempt this way is originating mail as user@my.domain in the first place, you can hardly exempt it.

As usual, execute the command postfix reload to make the changes effective.

### What does "Error: too many hops" mean?

Short answer: this message means that mail is probably looping. If you see this after you turned on Postfix content filtering, then you have made a mistake that causes mail to be filtered repeatedly. This is cured by appropriate use of `content_filter=`, `header_checks=`, and `body_checks=`.

Long answer: the message has too many Received: message headers. A received header is added whenever Postfix (or any MTA) receives a message. A large number of Received: message headers is an indication that mail is looping around.

Side comment: email uses the opposite of the technique that is used to avoid IP forwarding loops. With IP, the sender sets a TTL (time to live) field in the IP header. The field is decremented by each router. When the TTL reaches zero the packet is discarded and an ICMP error message is returned to the sender.

### Using UUCP over TCP

This subject comes up whenever someone asks about a "domain in a mailbox" solution. For first-hand information, see the guides listed below.

- Jim Seymour's guide for using UUCP over TCP.

- Craig Sanders's guide for using SSL-encrypted UUCP over tcp using stunnel.

### Setting up an Internet to UUCP gateway

Here is how to set up a machine that sits on the Internet and that delivers some but not all non-local mail via UUCP. See the UUCP-only FAQ entry for setting a UUCP-only host.

- You need an rmail program that extracts the sender address from mail that arrives via UUCP, and that feeds the mail into the Postfix sendmail command. Most UNIX systems come with an rmail utility. If you're in a pinch, try the one bundled with the Postfix source code in the auxiliary directory. Some day Postfix may have its own rmail command.

- Specify that mail for, let's say, some.domain, should be delivered via UUCP, for example, to a host named uucp-host:

          /usr/local/etc/postfix/transport:
              some.domain     uucp:uucp-host
              .some.domain    uucp:uucp-host

  See the transport manual page for more details.

- Execute the command postmap /usr/local/etc/postfix/transport whenever you change the transport file.

- Enable transport table lookups:

          /usr/local/etc/postfix/main.cf:
              transport_maps = hash:/usr/local/etc/postfix/transport

  Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what map types Postfix supports, use the command postconf -m.

- Define a mail transport for delivery via UUCP:

          /usr/local/etc/postfix/master.cf:
              uucp      unix  -       n       n       -       -       pipe
                flags=F user=uucp argv=uux -r -n -z -a$sender - $nexthop!rmail ($recipient)

  This runs the uux command, and substitutes the next-hop hostname (uucp-host) and the recipients before executing the command. The uux command is executed without assistance from the shell, so there are no problems with shell meta characters.

- Add some.domain to the list of domains that your site is willing to relay mail for.

          /usr/local/etc/postfix/main.cf:
              relay_domains = some.domain $mydestination ...

  See the relay_domains configuration parameter description for details.

- Execute the command postfix reload to make the changes effective.

### Using UUCP as the default transport

Here is how to relay all your mail over a UUCP link. See the Internet to UUCP FAQ entry for setting up a machine that gateways between UUCP and SMTP.

- There is no need for a transport table.

- Specify that all remote mail must be sent via the uucp mail transport to your UUCP gateway host, say, uucp-gateway:

          /usr/local/etc/postfix/main.cf:
              relayhost = uucp-gateway
              default_transport = uucp

- Define a message transport for mail delivery via UUCP:

          /usr/local/etc/postfix/master.cf:
              uucp      unix  -       n       n       -       -       pipe
                flags=F user=uucp argv=uux -r -n -z -a$sender - $nexthop!rmail ($recipient)

  This runs the uux command, and substitutes the next-hop hostname (uucp-gateway, or whatever you specified) and the recipients before executing the command. The uux command is executed without assistance from the shell, so there are no problems with shell meta characters.

- Execute the command postfix reload to make the changes effective.

### Sending mail to a FAX machine

The following information is by Joerg Henne:

Over here we are using the scheme <fax number>@fax.our.domain with Postfix and HylaFax. Here's the setup used:

        /usr/local/etc/postfix/master.cf:
            fax       unix  -       n       n       -       1       pipe
                flags= user=fax argv=/usr/bin/faxmail -d -n ${user}

        /usr/local/etc/postfix/transport:
            fax.your.domain   fax:localhost

        /usr/local/etc/postfix/main.cf:
            transport_maps = hash:/usr/local/etc/postfix/transport
            fax_destination_recipient_limit = 1

The process limit of 1 in the master.cf file is necessary with fax software that cannot handle multiple requests at the same time. It won't hurt otherwise.

The fax_destination_recipient_limit entry (by Simon, Mr. Simix) is necessary with fax software that can't have more than one destination on its command line. It won't hurt otherwise.

Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what map types Postfix supports, use the command postconf -m.

Note: be sure to not advertise fax.your.domain in the DNS :-)

### Deleting a message from the Postfix queue

The postsuper command has an option to delete Postfix message queue files. To delete the message with queue id ABCDEF, perhaps obtained from mailq output, one would use:

>     # postsuper -d ABCDEF

To delete a large number of files one would use:

>     # postsuper -d - < filename-with-queue-ids

It is usually safe to do this while the Postfix system is running. However, there is a small chance of deleting the wrong queue file. The scenario goes like this:

- The Postfix queue manager deletes the file that postsuper was supposed to delete, because Postfix was finished with the message.

- New mail arrives, and the new message is given the same queue ID as the message that postsuper was supposed to delete. The probability for reusing a deleted queue ID is about 1 in 215 (the number of different microsecond values that the system clock can distinguish).

- postsuper deletes the new message file, instead of the old file that should have been deleted.

### Moving or restoring the Postfix queue

It is not safe to simply copy Postfix queue files from one file system (or backup) to another file system. The reason for this is that queue file names must be unique across the Postfix incoming, active and deferred queue directories. If two queue files have the same file (base) name, then one of the queue files may be lost as files are moved from queue directory to queue directory.

Postfix names a queue file after its inode number and after the microsecond part of the time of day. Thus, if a queue file has a name based on someone elses inode number there is a small chance that the file name will collide with another queue file.

The text below describes two different procedures to restore queue files from another machine or from backup.

#### Procedure 1: Your Postfix queue is empty, and you run Postfix release 20010525 or later

- Stop Postfix, if it was running.

  >     # postfix stop

- Execute the mailq command. If there is any output, do not complete this procedure, but use procedure 2 instead.

  >     # mailq

- Copy or restore the queue to the usual place.

  >     # cd /var/spool/postfix
  >     ...restore maildrop, incoming, active, deferred, defer, bounce here...

- Run the postsuper command. This command will rename queue files so that the file names match their message file inode numbers.

  >     # postsuper

#### Procedure 2: Your Postfix queue is not empty, or you are running a Postfix release prior to 20010525

- Stop Postfix, if it was running.

  >     # postfix stop

- To avoid queue file name collisions when restoring queue files, copy or restore the incoming, active and deferred queue files under the maildrop directory instead.

  >     # cd /var/spool/postfix/maildrop
  >     ...restore incoming, active, deferred here...

- While the next step is going on, don't submit new mail locally, because that could collide with the files you are restoring under the maildrop directory.

- As of late 2000, Postfix queues are all hashed (for example, file ABCDEF is stored as A/B/ABCDEF), so you need an additional step to move files down from their subdirectories.

          # find incoming active deferred -type f -exec mv '{}' . ';'
          # rm -rf incoming active deferred
          # postfix start

- When Postfix is started, it will pick up queue files from the maildrop directory and will give them proper queue file names.

### Undefined symbols: ___dn_expand, ___res_init etc.

Question: When I build Postfix I get the following errors:

        ld: Undefined symbol
           ___dn_expand
           ___res_init
           ___res_search
        *** Error code 1

Answer: you're mixing BIND version 8 include files with a different version of the resolver library.

Fix: use the right include files. For example:

        make makefiles CCARGS="-I/usr/include".

### Undefined symbols: dbm_pagfno, dbm_dirfno etc.

Question: When I build Postfix I get the following errors:

        Undefined                       first referenced
         symbol                             in file
           dbm_pagfno                          ../lib/libutil.a(dict_dbm.o)
           dbm_dirfno                          ../lib/libutil.a(dict_dbm.o)

Answer: instead of using /usr/include/ndbm.h, you're building Postfix with some incompatible third-party file, typically /usr/local/include/ndbm.h.

Fix: get rid of the third-party ndbm.h include file.

### Using third-party DB libraries

The old dbm UNIX database has severe limitations when you try to store lots of information. It breaks when the number of hash collisions becomes so large that the entries no longer fit together in a single disk block. The more modern db database does not suffer these limitations. It is standard on 4.4BSD and Linux systems.

In order to build Postfix with db support on UNIX systems that do not have db support out of the box, you can use the Berkeley DB source code from www.sleepycat.com. See the file DB_README in the Postfix source code distribution for instructions on how to build Postfix with Sleepycat's Berkeley DB.

### IRIX problems translating IP address to string

Question:
  While installing IRIX 6.5.7m on a clean disk and no special options or software I stumbled upon the following problem; the inet_ntoa() function seems to return INADDR_NONE (malformed request?) for every call to it.

Answer:
  There is an incompatibility between gcc and system libraries compiled with SGI's cc. See a description in http://freeware.sgi.com/shared/howto.html.

  If you must use gcc, a possible workaround is to use the inet_ntoa() routine from the BIND source code at http://www.isc.org/.

### Compaq mail blackhole problem

On some Compaq Tru64 UNIX configurations, Postfix will receive mail and then nothing happens. The mail does not even show up with the mailq command.

Postfix sets the execute bit on a queue file to indicate that it is done receiving a message. As long as a queue file does not have the execute bit set, Postfix will ignore it as "mail still being received".

With enhanced security enabled, Compaq Tru64 UNIX has a feature that disallows non-superuser attempts to set the execute bit on a queuefile. Unfortunately, Postfix is never informed that such attempts fail, and mail seems to disappear into a black hole.

Postfix could be modified to use some other bit than the execute bit, but that might equally well fail on other systems. Another possibility is to allow non-superusers to set the execute bit on files, and to mount the Postfix queue file system with the noexec option or equivalent.

### Too many connections

This message is produced by the MYQSL server. You need to increase the number of connections that it can handle. Things to bear in mind: the virtual and canonical maps are accessed by every smtpd and cleanup process.

### write queue file: No such file or directory

### write queue file: Unknown error 4294967289

Reiserfs reports the wrong error code when a message exceeds the message_size_limit setting. As a result, the Postfix SMTP server reports a "queue file write error" to the SMTP client, rather than reporting a "file too large" condition. The client will keep sending the same email again and again until the mail is too old.

Up one level | Postfix FAQ