---
name: "setforward"
section: "1"
platform: "linux"
package: "fastforward"
version: "1:0.51-10"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/setforward"
---

# setforward(1)

create a forwarding database

## NAME

setforward - create a forwarding database

## SYNOPSIS

**setforward** *cdb* *tmp*

## DESCRIPTION

**setforward** reads a table of forwarding instructions from its standard input. It converts the table into a forwarding database. The forwarding database can be used by **fastforward**.

**setforward** writes the forwarding database to *tmp*; it then moves *tmp* to *cdb*. *tmp* and *cdb* must be on the same filesystem.

If there is a problem creating *tmp*, **setforward** complains and leaves *cdb* alone.

The forwarding database format is portable across machines.

## INSTRUCTION FORMAT

A forwarding instruction contains a *target,* a colon, a series of commands, and a semicolon. Each command is a *recipient address,* *owner address,* *external mailing list,* or *program.* Commands are separated by commas.

For example,

```
   root@yp.to: god@heaven.af.mil, staff@af.mil;
```

says that mail for **root@yp.to** should be forwarded to the recipient addresses **god@heaven.af.mil** and **staff@af.mil**.

When **setforward** sees # it ignores all text from # to the end of the line:

```
   # this is a comment
```

**setforward** ignores all other line endings, so you can split a forwarding instruction across lines. It also ignores spaces and tabs. Exception: you can put a space (or tab or comma or whatever) into a target or command by putting a backslash in front of it. (However, NUL bytes are not permitted anywhere.)

## TARGETS

When **fastforward** sees the incoming address *user@host.dom*, it tries three targets: *user@host.dom*, *@host.dom*, and *user@*. It obeys the commands for the first target that it finds. Target names are interpreted without regard to case.

All the commands for a single target must be listed in a single instruction. Exception: an owner address can be listed in a separate instruction.

## RECIPIENT ADDRESSES

If a command begins with an ampersand, **setforward** takes the remaining bytes in the command as a recipient address:

```
   boss@yp.to: &god@heaven.af.mil;
```

**fastforward** sends each incoming mail message to the recipient address. The recipient address must include a fully qualified domain name. It cannot be longer than 800 bytes.

If a recipient address is itself a target in the forwarding table, **fastforward** will recursively handle the instructions for that target. Note that *@host.dom* and *user@* wildcards do not apply here; they apply only to the incoming address.

If a command begins with a letter or number, **setforward** takes the entire command as a recipient address:

```
   boss@yp.to: god@heaven.af.mil;
```

## OWNER ADDRESSES

If a command begins with a question mark, **setforward** takes the remaining bytes in the command as an owner address:

```
   sos@heaven.af.mil: ?owner-sos@heaven.af.mil;
```

**fastforward** uses that address as the envelope sender for forwarded mail, so bounces will go back to that address. (Normally, if a message is forwarded to a bad address, it will bounce back to the original envelope sender.)

## EXTERNAL MAILING LISTS

If a command begins with a dot or slash, **setforward** takes the entire command as the name of a binary mailing list file created by **setmaillist**:

```
   sos@heaven.af.mil: /etc/lists/sos.bin;
```

**fastforward** will read and obey the commands in that file. The file must be world-readable and accessible to **fastforward**.

## PROGRAMS

If a command begins with a vertical bar or exclamation point, **setforward** takes the rest of the command as the name of a program to run:

```
   dew@: |dew-monitor;
```

For a vertical bar, **fastforward** feeds the message to that program. An exclamation point works the same way except that **fastforward** inserts **$UFLINE**, **$RPLINE**, and **$DTLINE** in front of the message.

## DUPLICATES

When **fastforward** is building the recipient list for a message, it keeps track of the recipient addresses and external mailing lists it has used. If the same command shows up again, it skips it. For example:

```
   everybody@yp.to: programmers@yp.to, testers@yp.to;
   programmers@yp.to: joe@yp.to, bob@yp.to;
   testers@yp.to: joe@yp.to, fred@yp.to;
```

A message to **everybody@yp.to** will be sent to **joe@yp.to** only once. (This also means that addresses in an internal forwarding loop are discarded.)

Exception: If a target has an owner address, commands for that target are considered different from commands for \`\`outside'' targets.

## SEE ALSO

[newaliases(1)](/newaliases/1.md), [preline(1)](/preline/1.md), [printforward(1)](/printforward/1.md), [setmaillist(1)](/setmaillist/1.md)