The pipe driver is the most general form of transport. Its job is to send mail messages to another program, such as uux(1), mail.local(8), or mabye even sh(1).

The driver attributes for the pipe driver are:

cmd

type: string

The program to be run and the arguments to be passed. This is string expanded using some special rules. To handle multiple addresses being given to a transport, the forms ``$('' and ``$)'' can be used to bracket a section of the command string which is to be repeated for each address given to the transport. Single quotes ('), double quotes (") and backslash (\) work as with /bin/sh. Variables are expanded as described in smail(5). It is a configuration error for this variable to be unset or for string expansion to fail or for the resulting command not to specified with an absolute pathname.

defer_child_errors

type: boolean

Generally, only child failures from the signal SIGTERM are re-attempted at a later time. If this is set, then retries are performed at a later time if the exit code is non-zero, or if the write failed on the pipe. This is useful for treating errors from UUCP as configuration or as temporary filespace problems.

group

type: string

The name of the group to set-group-ID to within the child process. If not set then the default group-ID of the user specified in the user attribute is used. Useful only if the mailer is running as root.

ignore_status

type: boolean

If set, the exit status of the child process is ignored. If this is not set, an exit value other than 0 is noted and mail is sent to the postmaster stating this. See also status_to_sender described below.

ignore_write_errors

type: boolean

If set, write errors are ignored. This is useful for running programs that may not actually read their standard input. If this is not set, a write error will cause mail to be returned to the sender.

log_output

type: boolean

The standard output and standard error files of a command are logged and returned to the sender in case of problems. The current implementation is not very good as it actually returns the logs for all such transports in the event that any transports fail. This attribute is on by default.

parent_env

type: boolean

Stuff the environment with data taken from the parent of the input address, rather than the input address itself. This is useful for the transport specifically named pipe which is used by smail for delivery to shell-command addresses. Here the recipient address stored into the environment will then be the address that produced the shell-command address, rather than the shell-command address itself.

pipe_as_sender

type: boolean

If set, the child process' UID is taken from the real UID at the time the message was read by smail. This does not affect the group id for the child. This overrides the UID obtained from the pipe_as_user attribute.

pipe_as_user

type: boolean

Obtain a UID and, if group attribute is not given, a GID associated with the address (such as the user for a ~/.forward file). Then set these via setuid(2) and setgid(2) in the child process.

NOTE: This attribute is on by default.

status_to_sender

type: boolean

This flag modifies the ignore_status attribute so that any errors resulting in a non-zero status are reported to the sender rather than the postmaster. It is of use if a transport is required (for example) to send an informative message back to the sender detailing local addresses that did not correspond to local users. This would be done using the smartuser director to pass addresses directly to this transport, and then setting -ignore_status, +status_to_sender, and +log_output to send a more detailed error message to the sender, possibly giving details of close matches for the incorrect mailboxes(s).

umask

type: number

file creation mask for the child process.

user

type: string

The name of the user to set-user-ID to within the child process. Also sets the group ID if the group attribute is not set using the default group-ID of the specified user. Useful only if the mailer is running as root.

The environment of the child process is entirely initialised and loaded with variables which may be useful in shell scripts or intelligent mail processing programs. Exactly one environment variable is passed through from the environment handed to smail: the TZ variable defining the time zone. The following portion of the environment is independent of the recipient addresses:

BASENAME

the basename for the spool file

GRADE

the grade character

MESSAGE_ID

the message-ID as assigned by smail

PATH

command search path, usually just ``/bin:/usr/bin''

PRIMARY_NAME

the official name for the host

SENDER

the sender address

SHELL

system shell, usually ``/bin/sh''

SPOOL_FILE

the full pathname for the spool file

UUCP_NAME

the name for this host on the uucp network

VISIBLE_NAME

the name for the host used in addresses

The rest of the environment is loaded from the appropriate internal data structure associated with each address, which will be either that of resolved address or that of its parent address, depending in the value of the parent_env attribute:

ADDR

The mailbox name (local part) of the recipient address (or one of the recipient addresses, if more than one is given to the transport for a given message).

DESTMBOX

The remainder part of the address from the parent address. Only provided if parent_env is not set, and of course if there is a parent address.

HOME

The home directory (or one of home directories, if more than one recipient address is given to the driver). If no home directory is associated with an address, ``/'' is used.

HOST

The recipient hostname (or one of the recipient hosts, if more than one host is given to the driver).

MBOX_PREFIX

If the director which resolved this address used the user driver and if it had a prefix attribute then the matching prefix string which was stripped from the mailbox name will be provided in this variable's value. This is the same value that is available by expanding the $user_prefix variable in the cmd string.

MBOX_SUFFIX

If the director which resolved this address used the user driver and if it had a suffix attribute then the matching suffix string which was stripped from the mailbox name will be provided in this variable's value. This is the same value that is available by expanding the $user_suffix variable in the cmd string.

USER

LOGNAME

These two variables are loaded with the name of a user on the local host, if one is found with some association to the address.

Examples of the use of the pipe driver are:

    # transport used for delivery to shell-command addresses 
    pipe:
        from, 
        local, 
        return_path, 
        unix_from_hack, 
        driver=pipe; 
        cmd="/bin/sh -c $user", 
        # if the system supports #! interpreter file execution
        # the cmd above could be given as just:
        #cmd="$user",
        pipe_as_user, 
        -ignore_status, 
        -ignore_write_errors, 
        parent_env, 
        log_output,

    # delivery to a remote rmail(8) program using uux(1) 
    # Note quoting of $user with parens as well as use of $( and $) 
    uux: 
        max_addrs=5, 
        max_chars=200, 
        from, received, 
        driver=pipe;
        cmd="/usr/bin/uux - -r -g$grade $host!rmail $((${strip:user})$)", 
        # see ``String expansion'' above 
        pipe_as_sender,

The appendfile driver creates or appends to files. It can either write to a filename derived from the recipient address, or it write a unique file into a directory. This latter capability can be used to implement a primitive output queue for some purposes.

The driver-specific attributes are:

append_as_user

type: boolean

Get the UID and, perhaps, the GID from the user-ID and group-ID associated with the address. For example, the user associated with a forward file might be used. This attribute is on by default.

check_user

type: boolean

Reject an address if the $user variable would contain a `/'. This prevents a $user expansion from accessing a different directory.

dir

type: string

Defines a directory in which to write unique files. Files written to this directory always begin with the letter `q', while temporary files used in the creation process begin with ``temp''. This string is expanded similarly to the file attribute. It is a configuration error for any string expansion to fail.

expand_user

type: boolean

If set the value for $user value is string expanded before the value for the file or dir attribute is expanded. This is useful if a local-form address may require `~' or `$' expansions.

file

type: string

Defines a file to append messages to. This string is expanded, and the variables $user and $host are set from the recipient address. It is a configuration error for this string expansion to fail.

group

type: string

become this group. Similar to the user attribute.

mode

type: number

When creating a file use this access mode. The default is 0666.

notify_comsat

type: boolean

Notify the COMSAT daemon of the message delivery, so that users can be notified that they received mail. This has no effect if your system does not support the COMSAT daemon. This should be used for delivery to user mailbox files.

prefix

type: string

This prefix is inserted in the file before the message. This string is expanded, with $user and $host being available from the recipient address. It is a configuration error for this string expansion to fail.

suffix

type: string

This suffix is appended to the file after the message. This string is expanded, with $user and $host being available from the recipient address. It is a configuration error for this string expansion to fail.

user

type: string

This become this user (effectively at least) when opening or creating the file. Access permissions are checked relative to this user, and the user will own the file if it did not previously exist.

To better understand the use of some of these attributes, consider the transport file entry:

    file:
        driver=appendfile, 
        from, 
        return_path, 
        local; 
        file=$user, 
        suffix="\n", 
        expand_user, 
        append_as_user, 
        mode=0664

This transport will be called when a file address is produced by a director. Such addresses should be expanded, because they may require `~' expansions. Also, to keep standard many user agents happy, an extra newline is inserted after each message. The append_as_user attribute is set to ensure that addresses produced from, say, a forward file are only created or appended to if the associated user has permissions to do so.

When given an address of ``~/Incoming,'' with an associated home directory of ``/u/joe-user'' and an associated user of ``joe-user'', the following steps occur:

1.

The $user variable is expanded to ``/u/joeuser/Incoming.''

2.

The file attribute is also expanded to ``/u/joeuser/Incoming.''

3.

The directories ``/'', ``/u'' and ``/u/joe-user'' are all checked for accessibility by the user ``joe-user''. If any of these is not searchable by that user, then delivery fails.

4.

The file ``/u/joe-user/Incoming'' is opened for append access. If it does not exist, it is created, will be owned by ``joe-user'' and will have mode 0664. Creation will of course fail if ``joe-user'' cannot write the directory.

5.

The message is written with a local-form ``From<space>'' line.

6.

An extra newline is appended to the file, after the message.

NOTE: Smail will follow the local conventions on locking protocols for mailbox files, which may involve creating a ``.lock'' file or using a file lock system call, such as lockf(3) or lock(2).

Next, lets examine:

    local:
        driver=appendfile, 
        local, 
        from, 
        return_path; 
        file=/var/mail/$user, 
        append_as_user, 
        check_user, 
        mode=0600, 
        notify_comsat

In this example, the $user value is not expanded before expanding the file attribute. Also, just to make sure, $user is verified to not contain a `/'. Given an input address of ``jane-doe,'' associated with the user ``jane-doe'', mail will be appended to the file ``/var/mail/jane-doe''. If it did not previously exist, it will be owned by ``jane-doe'' and will have a mode of 0600.

Support exists in smail for delivery using SMTP over TCP/IP, for systems that have BSD compatible networking.

The smtp driver can be used for delivery of any number of addresses to one remote host, where the remote host can be specified either in form of a hostname known by the networking software or by an internet number in square brackets, such as ``[192.0.2.142]''. For example, the routing drivers gethostbyaddr and gethostbyname are suitable for matching addresses to be delivered using the SMTP driver.

The attributes for the tcpsmtp driver are:

short_timeout

type: interval

This defines the response timeout for operations that are assumed to be short, such as protocol startup and protocol exit. This can use suffix letters of `s', `m', `h', and `d' to mean seconds, minutes, hours or days, with no suffix signifying seconds. Times can be added through direct concatenation. For example, the value `5m30s' signifies 5 minutes and 30 seconds. The default value is 5 minutes.

long_timeout

type: interval

This defines the response timeout for long operations, i.e., those that might require processing on the remote end. Suffix letters can be used in the same manner as with short_timeout. The default value is 5 hours.

service

type: string_or_number

This attribute identifies a TCP/IP port number, either directly as a number, or as a name to be searched for in the /etc/services file. This port number will be used in connecting to the remote host. The default is ``smtp''.

use_bind

type: boolean

Use DNS name resolution, if supported, to locate and use MX and A records associated with the target and MX hosts. Without this option, the gethostbyname(3n) function is used to locate the address to use for delivery. If the target host was matched with the bind router driver, then MX and A records found by the bind router will be used independent of the use_bind attribute.

If use_bind is specified, the defer_no_connect, local_mx_okay, defnames, ignore_domains, domain_required, and mx_only attributes control the behaviour of the tcpsmtp transport's use of DNS resolution. See the documentation for the bind router in smailrtrs(5) for an explanation of these attributes.

The tcpsmtp driver attempts to connect immediately and deliver a single message. If access to the remote host is currently not possible, the driver will tell smail that delivery should be attempted at a later time.

An example of the use of the tcpsmtp driver is the entry:

    # deliver using SMTP over TCP/IP to the remote host 
    tcpsmtp: 
        -max_chars, 
        -max_addrs, 
        driver=smtp

If your site is on the Internet and gateways from the UUCP zone, it may be reasonable to set the strict attribute. Otherwise, this is probably not a good idea.

If the local attribute is set (see the generic transport attributes), then mail will be transmitted in a form that contains little reference to the transmitting host.

This can be used within a local network to make all mail transmitted within the network look like local mail (i.e., local addresses will not be qualified with the domain name). This is often convenient in environments that use a central host for processing all mailing lists and user addresses, but where mail can originate and be delivered anywhere in the network, and where user names are consistent throughout the network.

When mail is transmitted outside of the local network, a tcpsmtp transport with the local attribute turned off will qualify any mail sent from anywhere inside the network.

The SMTP transport is also affected by the inet and uucp generic transport attributes. If inet is set, then sender and recipient addresses transmitted in the protocol envelope will strictly conform to the RFC 821 and RFC 1123 protocol specifications. However, route-addr addresses may be generated, despite the recommendations of RFC 1123 against such practice. Note that networks connected completely by domain name servers will not result in generation of route-addr addresses, although they will be honoured if received.

If the uucp transport attribute is set, then sender and recipient addresses will conform to the envelope specifications of RFC 976, and will thus use !-style routes. Addresses transmitted to the remote host will consist only of ! and % operators. % operators will never be generated, but may be included if they were present in the original sender or recipient addresses.

If neither the uucp nor the inet attributes are specified, then an intermediate form will be used that nearly eliminates route-addr addresses. This form uses RFC 976 !-style addresses when routing is necessary, but otherwise stays within the formal SMTP specification.

The tcpsmtp driver always sets the crlf and dots transport attributes.