Pipes in ~/.forward File

Forwarding of UNIX e-mail is accomplished through a ~/.forward file. This file, commonly referred to as "dot forward", contains a location to send your incoming mail. If the file does not exist, mail is saved in your inbox. Beginning with V8 sendmail, a user must have a valid shell to run programs from the ~/.forward file. Because sendmail sorts all addresses and deletes duplicates before delivering to any of them, it is important that programs in ~/.forward files be unique. Commends can be used to ensure this ( .forward file uses shell style comments which start with a # character). Sendmail temporarily switch to user ID before trying to read the ~/.forward file so that reads will work across NFS. If sendmail cannot read the ~/.forward file (for any reason), it silently ignores that file. First sendmail checks to see whether it is a "safe" file - one that is owned by the user or root and that has the read permission bit set for the owner. If the ~/.forward file is not safe, sendmail silently ignores it. After that, sendmail opens the file for reading and gathers a list of recipients from it. Internally, the ~/.forward file is exactly the same as a :include: file. Each line of text in it may contain one or more recipient addresses. Recipient addresses may be email addresses, the names of files onto which the message should be appended, the names of programs through which to pipe the message, or :include: files.

Four types of destination can be used.

Address
Remote email address to relay the mail to, such as user@example.net. This is th traditional use of the ~/.forward file, as its name implies. Unfortunately, as users move from machine to machine, they can leave behind a series of ~/.forward files, each of which points to the next machine in a chain. As machine names change and as old machines are retired, the links in this chain can be broken. One common consequence is a bounced mail message ("host unknown") with a dozen or so Received: header lines.
Force local delivery
To force delivery to the local mailbox, precede the mailbox name (typically the username) with a backslash: \user. Recall that prefixing a local address with a backslash tells sendmail to skip additional alias transformations. For \user this causes sendmail to deliver the message (via the local delivery agent) directly to the user's spool mail box.
Appending to file
To specify a literal file where mail should be deposited, use a fully qualified path: /home/user/archive/mailstore.
Such filenames must begin with a slash character that cannot be quoted. For example, if a user wishes to keep a backup copy of incoming mail:
```
\user
/home/user/mail/in.backup
```
The first line (\user) tells sendmail to deliver directly to the user's mail spool file using the local delivery agent. The second line tells sendmail to append a copy of the mail message to the file specified (in.backup).
Pipe. The syntax is as follows:
```
|prg
"|prg args"
|"prg args"
```

Note: prg should contain the full path to executable like in "|$HOME/bin/your.program"
(the environment variable PATH is not available). If command-line arguments are needed for the program, they must follow prg, and the entire expression must be quoted. The leading full quotation mark may either precede or follow the |. If the address is quoted with full quotation marks, the leading quotation mark is ignored in determining the leading | character.

For example

"|IFS=' '&&exec /usr/local/bin/procmail -f-||exit 75 #YOUR_USERNAME"

"|IFS=' ';if /usr/bin/sparc;then exec /home/berg/bin.sun4/procmail;else exec /home/berg/bin.sun3/procmail;fi ||exit 75 #YOUR_USERNAME"

"|IFS=' ' && export IFS && exec /home/berg/bin.`/usr/bin/arch`/procmail || exit 75 #YOUR_USERNAME"

The above can be combined as comma separated values on a single line, or on multiple lines to split mail delivery to multiple destinations.

There are several type of information you can put in the .forward file. Vacation Program also allows you to send a message back to the person sending you mail with information about your availability (e.g. if you're on vacation) or that your e-mail address has changed.

Security restrictions have been placed users using .forward files to pipe mail to a program or redirect mail to a file. The default shell (as listed in /etc/passwd) of these users must be listed in /etc/shells. This restriction does not affect mail that is being redirected to another alias. Additional restrictions have been put in place on .forward and :include: files. These files and the directory structure that they are placed in cannot be group- or world-writable.

Forwarding to an address

To forward mail to to another address, you need to place the email address of the account you want to forward to in the .forward file.

The .forward file may contain multiple locations to forward your e-mail. For example, you may wish to forward mail from one account to several, or keep a copy of the mail you forward in your local account. To do this, simply add a line in your .forward for every location you wish to forward e-mail to. So, if Bob wanted to forward his mail to Mary and Joe, but also keep a copy of it, he could have a .forward that looks like this:

The backslash (" \ ") before Bob's address leaves a copy of the message in Bob's account as well as forwards a copy of the message to Mary and Joe.

Warning: Please take care when forwarding mail. Place the .forward file in the account you want to forward mail from containing the destination e-mail address. The destination address should NOT be the same as the source address. Also, the destination address should NOT be an address which will forward mail back to the source address. These kinds of loops cause mail to be bounced between machines and will eventually cause your mail not to be delivered.

Appending to Files

The ~/.forward file can contain the names of files onto which mail is to be appended. Such filenames must begin with a slash character that cannot be quoted. For example, if a user wishes to keep a backup copy of incoming mail:

\user
/home/user/mail/in.backup

The first line (\user) tells sendmail to deliver directly to the user's mail spool file using the local delivery agent. The second line tells sendmail to append a copy of the mail message to the file specified (in.backup).

If the SafeFileEnvironment option is set, the user should be advised to specify the path of that safe directory:

\user
/arch/bob.backup           here /arch was specified by the SafeFileEnvironment option

When the SafeFileEnvironment option is used, the cooperation of the system administration may be needed if users are to have the capability of saving mail to files via the ~/.forward file.

Pipes in ~/.forward file

Any delivery agent for which the F=| flag is set can also pipe messages through programs. To disable this ability, simply remove the F=| flag from all delivery agent declarations in your configuration file.

The syntax is as follows:

|prg
"|prg args"
|"prg args"

Here, prg is the full path of the program to be run (the environment variable PATH is not available). If command-line arguments are needed for the program, they must follow prg, and the entire expression must be quoted. The leading full quotation mark may either precede or follow the |. If the address is quoted with full quotation marks, the leading quotation mark is ignored in determining the leading | character.

To execute the program, sendmail executes the command in the P= equate of the prog delivery agent. That command is one of the following:

/bin/sh -c
/bin/smrsh -c

These tell sendmail to run /bin/sh (the Bourne shell) or /bin/smrsh (the sendmail restricted shell) to execute the program specified by prg. The -c tells that shell to take any arguments that follow and execute them as though they were commands typed interactively to the shell. These arguments are constructed by removing the leading | from the program address and appending what remains, quotation marks and all, to the P= command. For example, if an alias looked like this:

jim: "|/etc/local/relo jim@otherhost"

the Bourne shell would be executed with the following command line:

/bin/sh -c "/etc/local/relo jim@otherhost"

he result of all this is that sendmail runs the Bourne shell and then the Bourne shell runs the /etc/local/relo program.

Mail is delivered under this scheme by attaching the output of sendmail to the standard input of the shell and attaching the standard output and standard error output of the shell to the input of sendmail. The sendmail program simply prints the mail message to the shell and reads any errors that the shell prints in return.

Although this process appears to be fairly straightforward, there are many things that can go wrong. Failure usually results in the mail message being bounced.

A user must have a valid shell listed in /etc/shells to run programs from the ~/.forward file.

Because sendmail sorts all addresses and deletes duplicates before delivering to any of them, it is important that programs in ~/.forward files be unique. Consider a program that doesn't take an argument and suppose that two users both specified that program in their ~/.forward files:

user 1   \user1, "|/bin/notify"
user 2   \user2, "|/bin/notify"

The address /bin/notify appeared twice in the list of addresses. The sendmail program might eliminate what seems to be a duplicate. V8 sendmail uses the owner of the ~/.forward file in addition to the program name when comparing.

If a program requires no arguments (as opposed to ignoring them), the ~/.forward program specifications can be made unique by including a shell comment:

user 1   \user1, "|/bin/notify #user1"
user 2   \user2, "|/bin/notify #user2"

Rather than expecting users to write home-grown programs for use in ~/.forward files, offer them any or all of the publicly available alternatives. The most common are listed below.

The deliver(1) program, by Chip Salzenberg, is specifically designed to handle all types of final delivery for users. It is intended for use in the ~/.forward file but also functions as a local delivery agent. The deliver program supports a large number of command-line options and can reliably handle delivery to files and through programs. It is typically used in the~/.forward file like this:

 "|/usr/local/bin/deliver user"
The deliver program is available via anonymous FTP from many archive sites.

The procmail(1) program, by Stephen R. van den Berg, is purported to be the most reliable of the delivery programs. It can sort incoming mail into separate folders and files, run programs, preprocess mail (filtering out unwanted mail), and selectively forward mail elsewhere. It can function as a substitute for the local delivery agent or handle mail delivery for the individual user. The procmail program is typically used in the ~/.forward file like this:

 "|exec /usr/local/bin/procmail #user"

The slocal program, distributed with the mh distribution, is useful for sorting incoming mail into separate files and folders. It can be used with both UNIX-style mail files and with mh-style mail directory folders. It is typically used in the ~/.forward file like this:

 "| /usr/local/lib/mh/slocal -user user"

The disposition of mail is controlled using a companion file called ~/.maildelivery.

Normally, a program in the user's ~/.forward file is executed with the Bourne shell. The precise means that is used is defined by the prog delivery agent.

Mprog, P=/bin/sh,   F=lsDFMeuP,  S=10, R=20, A=sh -c $u
                                                 
                                              The Bourne shell

One drawback to using the Bourne shell to run programs is that it exits with a value of 1 when the program cannot be executed. When sendmail sees the exit value 1, it bounces the mail message.

There will be times when bouncing a mail message because the program could not execute is not desirable. For example, consider the following ~/.forward file:

 "| /usr/local/lib/slocal -user george"

If the directory /usr/local/lib is unavailable (perhaps because a file server is down or because an automounter failed), the mail message should be queued, rather than bounced. To arrange for requeueing of the message on failure, users should be encouraged to construct their ~/.forward files like this:

 "| /usr/local/lib/slocal -user george || exit 75"

Here, the || tells the Bourne shell to perform what follows (the exit 75) if the preceding program could not be executed or if the program exited because of an error. The exit value 75 is special, in that it tells sendmail to queue the message for later delivery, rather than to bounce it.

The ~/.forward file can contain the names of programs to run. A program name is indicated by a leading pipe (|) character, which may or may not be quoted. For example, a user may be away on a trip and want mail to be handled by the vacation(1) program:

\user, "|/usr/ucb/vacation user"

Recall that prefixing a local address with a backslash tells sendmail to skip additional alias transformations. For \user this causes sendmail to deliver the message (via the local delivery agent) directly to the user's spool mail box.

The quotes around the vacation program are necessary to prevent the program and its single argument (user) from being viewed as two separate addresses. The vacation program is run with the command-line argument user, and the mail message is given to it via its standard input.

Unscrambling Forwards

The traditional use of the ~/.forward file, as its name implies, is to forward mail to another site. Unfortunately, as users move from machine to machine, they can leave behind a series of ~/.forward files, each of which points to the next machine in a chain. As machine names change and as old machines are retired, the links in this chain can be broken. One common consequence is a bounced mail message ("host unknown") with a dozen or so Received: header lines.

As the mail administrator, you should beware of the ~/.forward files of users at your site. If any contain offsite addresses, you should periodically use the SMTP expn command to examine them. For example, consider a local user whose ~/.forward contains the following line:

user@remote.domain

This causes all local mail for the user to be forwarded to the host remote.domain for delivery there. The validity of that address can be checked with telnet(1) at port 25 [9] and the SMTP expn command:

% telnet remote.domain 25
Trying 123.45.123.45 ...
Connected to remote.domain.
Escape character is '^]'.
220 remote.domain Sendmail 8.6.13/8.6.12 ready at Tue, 7 May 1996 13:39:21 -0700
220 ESMTP spoken here
expn user
250 <user@another.site>
quit
221 remote.domain closing connection
Connection closed by foreign host.
%

This shows that the user is known at remote.site but also shows that mail will be forwarded (yet again) from there to another.site. By repeating this process, you will eventually find the site at which the user's mail will be delivered. Depending on your site's policies, you can either correct the user's ~/.forward file or have the user correct it. It should contain the address of the host where that user's mail will ultimately be delivered.

News	Recommended Books	Recommended Links	Tutorials	Recommended Papers	Procmail
Forwarding to addresses	Force local delivery	Appending to file	Forwarding to a pipe	Humor	Etc

Pipes in ~/.forward File

Forwarding to an address

Appending to Files

Pipes in ~/.forward file

Unscrambling Forwards

Forwarding Loops

Recommended Links

Etc

Disabling .forward