Manpages

NAME

/etc/smail/transports − smail transports configuration

THE TRANSPORTS FILE

The transports file describes the various possible ways, of delivering mail. For example, some possibilities are to call a program such as uux(1) to deliver mail to a remote host, to connect over TCP/IP to a remote host and converse using an SMTP protocol, or to deliver local mail by appending to a user’s mailbox file.

NOTE: Unlike the routers and directors files, a locally supplied transports file does not replace all compiled-in transports. Rather, entries in the local transports file override existing entries of the same name, or add new entries. Thus, if you wish to add or replace one new transport definition, you need only provide the new definition, and do not need to duplicate all of the existing entries.

The following list describes the possible generic attributes for transport file entries:
bsmtp

type: boolean

Use a batched SMTP format, where the message is enclosed in an envelope of SMTP commands. This is not the same format commonly used on BITNET, as it does not contain FORTRAN carriage control characters. This can be used to send mail to remote hosts using SMTP formats even when direct two-way connections are not feasible. For example, this will work over UUCP and eliminates difficulties with sending arbitrary addresses as arguments to uux. Use of bsmtp also turns on the dots attribute. When used with the uucp attribute, UUCP−style !−path addresses are used in the SMTP envelope.

crlf

type: boolean

If set, then each line of the header and message will end in carriage-return/line-feed rather than a single newline character. This is not typically useful, as the SMTP transport, which requires this as a part of the interactive protocol always does this anyway.

debug

type: boolean

If set, replaces the body of the message with debugging information. This can be used, for example, as a shadow transport to watch the flow of mail for a while for debugging purposes. This essentially allows for debugging without the ethical and space problems of saving the personal correspondence of others.

dots

type: boolean

If set, then use the hidden dot protocol. All output lines which begin with dot will have one more dot prepended. All of the various SMTP modes imply this behaviour.

driver

type: string

The driver attribute names a specific set of low-level functions which will do the work of delivering mail. This attribute is always required.

error_transport

type: string

names another transport that the message should be sent to, if the first transport returns failure.

from

type: boolean

If set, then supply a ’’From<<space>>’’ line before the message when delivering with this transport. If this is a remote transport (i.e., the local_xform attribute is not turned on) then this line will end with ’’remote from hostname’’ where hostname is the UUCP name for the local host. This is useful for delivery over UUCP and for delivery to standard mailbox files, which require this format.

hbsmtp

type: boolean

’’Half-baked’’, or batched, SMTP. This is batched SMTP mode without an initial ’’HELO’’ greeting command or an ending ’’QUIT’’ command. This can be used for creating files which will be concatenated together at a later time to form one batch of SMTP commands containing multiple messages. Use of the hbsmtp attribute also turns on the dots attribute.

local_xform

type: boolean

If set, the form of the header and envelope information will be setup for delivery to the local host. This performs no changes to existing header fields, other than insertion of commas into fields containing sender and recipient addresses. This also affects the form of any generated ’’From<<space>>’’ line and the form of envelope addresses used in SMTP commands.

This can be used with remote delivery, if delivery is to a remote smail3.1 site, which is useful within a domain that maintains consistent user forwarding information. This leaves messages in unqualified format until leaving the domain through a gateway.

local

type: boolean

This implies that delivery really is final delivery to a user, file, or program on the local host. This disables generation of a bounce message resulting from an excessive message hop-count.

max_addrs

type: number

This states the maximum number of recipient addresses that can be given in one call to the transport. If this is turned off then there is no maximum number. The default number is 1 and typically this is either left as 1 or turned off.

max_chars

type: number

This states the maximum number of characters in recipient addresses that can be given in one call to the transport. If this is turned off then there is no maximum number. The default number is about one third of the number characters that can be passed as arguments to a program. When using SMTP transports this should be turned off unless a remote host is known to be unable to handle a large number of addresses. For delivery over UUCP to a remote rmail program, this should be around 200 or 250, to avoid buffer overruns at the remote site. UUCP generally has small buffers to hold argument information.

If smail is given an address whose length exceeds this number, then the address will be passed with one call to the transport. Thus, this limit is not strictly enforced.

max_hosts

type: number

This states the maximum number of different hosts that can be given in one call to the transport. If this is turned off, using the form −max_hosts then there is no maximum number. The default number is 1 and typically this is not changed.

received

type: boolean

If set, then a Received: header field is inserted for mail being delivered with this transport. The form of this field is taken from the received_field attribute. This attribute is on by default.

return_path

type: boolean

If set, then a Return-Path: field is inserted for mail being delivered with this transport. The form of this field is taken from the return_path_field attribute. This should only be used for transports which perform final delivery to local destinations.

shadow

type: string

This names another transport that the message should be sent to. This could be used to, for example, to create a local copy of all e-mail carried by the primary transport. The shadow transport is called only if the primary transport successfully performs delivery.

strict

type: boolean

If this flag is set, then some effort is done to transform mail which does not conform to RFC 822 standards. This is potentially useful for sites which gateway between the UUCP zone and the Internet. In general, it is not a good idea to turn this on as it changes the contents of headers fields.

This should only be done when it is known that some remote hosts only understand mail which conforms to the RFC 822 standard.

unix_from_hack

type: boolean

If set then any line in the body of the message which begins with ’’From<space>’’ will have the character ’>’ inserted at the beginning. This is required for local delivery to mailbox files that are in the standard Unix mailbox form.

uucp

type: boolean

If set then outgoing recipient addresses will be converted into UUCP−style paths of the form hosta!hostb!hostc!user. An exception is that any use of ’%’ as an address operator is preserved. Thus, an envelope address of user%hostb@hosta would be converted to hosta!user%hostb. This only affects envelope addresses and does not affect the message header fields.

inet

type: boolean

If set then outgoing recipient addresses will be conform into to internet specifications. This is not the same as the strict attribute, since the transformations apply only to the envelope addresses, and not to headers. If inet is defined, then route-addr addresses will be generated when routing to remote destinations, rather than !−style addresses. Thus, if smail is given the address user%host@gateway and gateway is reached through the path hosta!hostb!hostc, then smail will generate the address @hostb,@hostc:user%host@gateway to be sent to the host @hosta.

retry_dir

type: string

The subdirectory under /var/mail/retry to use for managing host retry intervals for this transport. By default, the name of the transport is used. However, multiple transports can share a retry directory by setting retry_dir for several transports to the same value. For example, by default all of the default TCP/IP SMTP transports (inet_zone_smtp, uucp_zone_smtp, and local_smtp set retry_dir to ’’smtp’’).

remove_header

type: string

Identify a header field that will be removed from the message for transport. This is an expansion string, so header removal can be made dependent upon some conditions. If expansion of the string results in an empty string, then no header is removed. Any number of remove_header attributes can be specified.

insert_header
append_header

type: string

Add the given header field at the beginning (with insert_header) or end (with append_header) of the message header for transport. These are expansion strings, so the header (and the existence of the header) can be made dependent on some conditions. If expansion of the string results in an empty string, then no header is added. Any number of insert_header and append_header attributes can be specified.

As an example of the manipulation of headers, consider the addition of an ’’Organization’’ header for all locally generated mail that does not already have an Organization header. This can be done with:

    append_header="${if and{{origin:local}{!header:organization}} \
                   Organization: ACME Explosives Corp.}"

To configure a ’’Content-Length’’ field, which some systems use to identify the length of a message within a mailbox file rather than keying on lines starting with ’’<newline>From<space>’’, use:

    remove_header="Content-Length",
    append_header="Content-Length: $body_size"

THE TRANSPORT DRIVERS

This section details the usage and driver-specific attributes for all of the transport drivers distributed with smail.

The Pipe Driver
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:

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

MESSAGE_ID

the message-ID as assigned by smail

PRIMARY_NAME

the official name for the host

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:

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.

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.

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
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.

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:

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.

The TCPSMTP Driver
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.

DEFAULT CONFIGURATION

NOTE: A transports file, unlike routers and directors files, does not replace all compiled-in transport definitions. Rather, entries in the transports file override existing entries of the same name, or add new entries. Thus, if you wish to add or replace transport definitions, you need only create a transports file containing the new definition, and you do not need to duplicate all of the compiled-in entries.

The default internal transports configuration can be viewed by typing smail -oT /no-such-file -v -bP TRANSPORTS

The default transport configuration defines:

demand_uusmtp

invoke uux to deliver mail to a remote rsmtp program (supplied in the Smail distribution).

The transmitted message will be encapsulated in an envelope of SMTP directives, with addresses passed in through the SMTP envelope rather than in the argument list to uux. This works better than the standard ’’rmail’’ protocol, because quoted addresses can pass through unscathed, and because no limits are given on the number of addresses that can be given in a single transfer. This last point can significantly reduce the number of UUCP transfers needed for large mailing lists, since the normal method of using rmail is limited by uux’s internal limit of (usually) 300 characters of worth of arguments.

Note that the uusmtp transports are not likely to be useful unless both the receiving host also uses Smail-3.

The uusmtp transport passes the ’’-r’’ option to uux, while the demand_uusmtp transport does not.

Also, the uucp generic transport attribute is used by uusmtp and demand_uusmtp to transfer addresses in accordance with the RFC 976 specification. This violates the RFC821 and RFC1123 specifications, but is none-the-less useful between sites operating in the UUCP zone.

inet_uusmtp
inet_demand_uusmtp

These transports are identical to the uusmtp and demand_uusmtp transports, except that the inet transport attribute is enabled, and the uucp attribute is disabled. This causes mail addresses to be transferred in accordance with the SMTP specifications.

If routing is required to reach a destination, then route-addr addresses are generated (e.g., <@host1,@host2:user@destination>).

uucp_zone_smtp
inet_zone_smtp

deliver mail to a remote host by using the SMTP protocol over a TCP/IP connection. If used in conjunction with the bind router, MX records will be handled in accordance with RFC 974 and RFC 1123.

The uucp_zone_smtp transport has the uucp transport attribute set, causing transferred addresses to use !−style addresses, as specified in RFC 976. This can often be useful when using SMTP within the UUCP zone, but is otherwise inappropriate.

The inet_zone_smtp transport has the inet transport attribute set, causing transferred addresses to conform to the RFC 821 and RFC 1123 specifications for SMTP. This is necessary for correct operation with arbitrary nodes on the Internet. Both the uucp_zone_smtp and inet_zone_smtp transports will handle generated routes (from paths files) correctly between nodes running Smail-3. The inet_zone_smtp transport will use route-addr addresses for routing despite RFC 1123’s recommendations against such a practice. However, generated routes should never be necessary on the Internet with fully connected DNS and proper MX records.

The smtp transport is identical to either the uucp_zone_smtp transport or the inet_zone_smtp transport, depending upon local configuration information specified when the smail program is compiled, namely the setting of the ’’UUCP_ZONE’’ attribute in the conf/EDITME file.

FILES

/etc/smail/transports

Optional configuration for smail transports; i.e., configured methods of mail delivery. This file replaces the compiled-in transport configuration.

/var/log/smail/logfile

A log of smail transactions.

/var/log/smail/paniclog

A log of configuration or system errors encountered by smail.

SEE ALSO

smail(5). smailconf(5), smaildrct(5), smailmeth(5), smailqual(5), smailrtrs(5), smailrtry(5), smail(8). Smail Administration and Installation Guide. DARPA Internet Requests for Comments RFC 821, RFC 822, RFC 974, RFC 976, and RFC 1123.

BUGS

Colons cannot be included in the value of a list element.

Database files cannot contain ’’#’’ in the left-hand field.

COPYRIGHT

Copyright (C) 1987, 1988 Ronald S. Karr and Landon Curt Noll Copyright (C) 1992 Ronald S. Karr

See a file COPYING, distributed with the source code, or type smail −bc, to view distribution rights and restrictions associated with this software.