Manpages

NAME

config, directors, routers, transports, retry, qualify − configuration files used by smail

SUMMARY

/etc/smail/config − see smailconf(5)
/etc/smail/qualify − see smailqual(5)
/etc/smail/directors − see smaildrct(5)
/etc/smail/routers − see smailrtrs(5)
/etc/smail/transports − see smailtrns(5)
/etc/smail/retry − see smailrtry(5)
/etc/smail/methods/ − see smailmeth(5),

DESCRIPTION

The config, qualify, directors, routers, transports, and retry files describe the rules used by smail(8) in processing and delivering mail. The actual paths show above may differ from system to system (though the values given in this manual should be correct for the system it was installed on) and, in addition, the paths to these files may be changed in the config file or possibly on the command line.

Smail is compiled with a default configuration. This default configuration is suitable for many sites that communicate to other systems via UUCP, or SMTP. For such sites, no configuration files are necessary, though it may still be convenient to have a simple config file to set some attributes described in the smailconf(5) manual page. See the smail(8) manual page for instructions on viewing the current configuration, including all of the default values.

COMMON FORMAT CONVENTIONS

In all files used by smail, entries or variable definitions begin with a character in column one that is not white space or the character ’#’. Entries (and variable definitions) continue until the next line which begins with a character other than white-space or the character ’#’, or until the end of the file is encountered.

Comments begin with the character ’#’, in any column and end at the next newline. A ’#’ in the first column does not signify the end of an entry.

Variable and attribute names in configuration files are formed of characters from the set of letters, numbers and the underscore character (_).

Entries in the directors, routers, and transports, files consist of an entry name, followed by a colon character, and then a group of comma-separated, named, attributes which are assigned values with a type of string, number, or boolean. Each group of attributes is optionally split into two sub-groups by a semicolon separator character.

Multi-line un-quoted attribute definitions can be created by putting a backslash (\) as a continuation marker at the end of the line. The newline and any whitespace at the beginning of the next line will be ignored and the value will be concatenated directly with no separation to the value(s) from the previous line(s).

Configuration variable definitions in the config file are parsed similarly to entries in the other files and continue until the next non-comment line without leading whitespace, but consist only of a variable name, optionally followed by an equals character (=) and then the value (optional whitespace around the ’=’ is ignored). Thus they can also be assigned values with a type of string, number, or boolean. The special characters used to separate attributes and groups of attributes in entries are allowed un-quoted in variable string values, and thus these values may continue on multiple lines unquoted without using a backslash (\) continuation character.

String values may be enclosed in double quotes, in which case backslash escapes are processed as in the C language, with the exception of a backslash at the end of a line wich causes leading whitespace on the next line to be ignored (i.e. not included in the value, just as if it were unquoted). If string values are not enclosed in double quotes, the values are limited to characters from the set of letters, digits and the characters ! @ $ % ^ & * − _ + ~ / ? | < > : [ ] { } . ’ and ’. Space, tab, semicolon (;), and comma (,) characters are also allowed in unquoted string values in the config file.

Number values are interpreted as in the C language, with a zero (0) digit prefix specifying an octal constant and a prefix of ’0x’ specifying a hexadecimal constant, and otherwise being interpreted as base-ten integers. In addition, a suffix of ’k’ or ’K’ specifies a multiplier of 1024 and a suffix of ’m’ or ’M’ specifies a multiplier of 1048576, or 1024K.

Boolean values are assigned by prefixing a leading ’+’ character to the attribute name to give it a value of true, and a leading ’−’ character to give it a value of false. Just giving the attribute name with no prefix character also gives it a value of true.

Item Lists
Some variables and attributes with the type of string are really lists of items (such as hostnames, hostname regular expressions, IP addresses, etc.). Lists are normally simply colon (:) separated values. Generally the colon may be preceded and/or followed by arbitrary whitespace, though of course in an attribute value (i.e. anywhere except in the config file) this means the value must be quoted or the whitespace characters must be each escaped with a backslash (\).

In some cases an optional semicolon (;) separated sub-field may be given to given with an item value as well. In that case the first sub-field is the primary item value and the second sub-field is, in most cases, a string treated as an error message or other descriptive text to be associated with the item. Note that the message text is not quoted (and is not separately quotable) so it must not contain another colon (’:’) character. Escape processing as described above cannot protect a field separator. Note that in an attribute definition (i.e. anywhere except in the config file, though currently no attributes allow sub-fields) if you use the semicolon separator to specify a sub-field then you must either escape it with a backslash or enclose the entire attribute definition in double quotes. The text message may contain semicolons itself though since it extends to the end of the field (i.e. to the next colon (’:’) character).

Items in a list of hostnames or IP addresses may be negated by prefixing them with an exclamation mark (!). When some value is being compared to the items in the list then a match of a negated item will cause the remainder of the items in the list to be ignored and for a no-match condition to be immediately indicated (thus implementing a ’’first match wins’’ algorithm). For example in a list of IP addresses the following would match any address in the range 10.0.0.0 through 10.255.255.255 except 10.1.1.1:

    ! 10.1.1.1 : 10/8

IP and IP Network Address Representation
As mentioned above some lists may contain strings representing IP addresses. They are specified in a format compatible with inet_net_pton(3). Generally speaking this means a host may be specified in the standard four-octet ASCII form, and any CIDR network may be specified by a four-octet number follwed by a slash (’/’) and a number specifying the number of bits in the network portion.

The magic keyword localnet represents a run-time generated pattern constructed to represent the classical IP network for the local address of the current connection. This keyword is of little use to anyone using either a supernet, or a subnet of anything larger than a Class C (/24) network.

Optionally if smail has been compiled with ’’HAVE=LIBWHOSON’’ then there is also support for a magic keyword whoson which can be used to query a WHOSON server for additonal IP numbers which are currently authorised to relay mail remotely via SMTP.

Hostname Regular Expressions
As mentioned above some lists may contain hostname regular expressions. These are simply regular expression strings which are matched against hostnames. The expression is implicitly anchored at the beginning and end of the hostname.

Note that the backslash character (’\’) must be quoted with itself since it is also the escape character for all configuration entries.

Note that a case-insensitive match is always done if the host platform’s underlying regular expression library is POSIX compliant.

STRING EXPANSIONS

Some string values will be variable and filename expanded before being used. When this is done, certain substrings, beginning with a ’$’, will be replaced by the value of the corresponding smail variable. The names of expansion variables are either a single character, or are multiple characters from the set of letters, digits, and underscore. A variable name can also be enclosed between ’{’ and ’}’ characters, to isolate the variable name from the surrounding text.

In addition to variables, a number of meta-expansions modifiers can be used. These expansions take the form:

    ${meta_name:name}

where meta_name defines some modifier operation to perform on the value of the variable name. Multiple modifiers can be specified, and they are processed from right to left. For example:

    ${lc:strip:user}

This strips quotes from the value of the variable user and then converts characters to lower case.

When a string to be expanded begins with the character ’~’, a home directory is substituted. If only ’~’ is given, or ’~/’ is given, then the home directory associated with an address is substituted. If the form ’’~username’’ is given, where ’’username’’ is the name of a user on the local host, that user’s home directory is substituted.

Conditionals
Conditionals can be used to include text based on whether or not a particular value is non-empty. Conditionals are of the form:

    ${if condition [:] string}

or

${if condition {string1} {string2}}

The first form includes string if the condition is true. The second form includes string1 if the condition is true, or string2 if the condition is false. For readability, the word else can be inserted before the second clause.

Possible conditions are:
!condition

Negate the boolean value of condition.

def:variable

True if the given expansion variable is defined and is non-empty.

header:header

True if the message contains a header field named header.

origin:local

True if the message originated locally.

origin:remote

True if the message was received from a remote machine.

dest:local

True if the message is being delivered to an address on the local host.

dest:remote

True if the message is being delivered to a remote host.

xform:transformation

True if the transformation being applied to the message, for delivery by the assigned transport, matches the given type. Valid types are: local, inet, uucp, or none.

eq{variable}{string}

True if the given expansion of variable matches the given string.

gt{variable}{string}

True if the given expansion of variable is lexicographically greater than the given string.

lt{variable}{string}

True if the given expansion of variable is lexicographically less than the given string.

or{{ condition } ... }

True if any of the given conditions are true.

and{{ condition } ... }

True if all of the given conditions are true.

File lookups
String expansions can use lookup procedures to convert a key, taken from a an expansion variable, into a string found in a file or other accessible database. These expansions are defined using the form:

${lookup:variable:proto{file-expansion}\
[:]then-clause}

or

${lookup:variable:proto{file-expansion}\
[then] {then-clause}\
[else] {else-clause}}

Lookups operate by taking the value of the indicated variable as a key for lookup in a file. The proto string defines how the lookup is to be performed, and file-expansion is a string defining the file or database to search. If the key is found, then the then-clause is expanded, otherwise the else-clause is expanded. A $value reference in either clause is replaced by the value found by the lookup. For readability, the word then can be inserted before the then-clause, and the word else can be inserted before the else-clause.

Allowed lookup methods are:
bsearch

Use a binary search to locate the key in a sorted file, organised as lines beginning with a key separated from a value by blanks.

lsearch

Use a linear search to locate the key in a plain file, again organised as lines beginning with a key separated from a value by blanks.

Comments in this file begin with ’#’ and continue until end-of-line. Blank lines are ignored.

If Smail has been compiled with ’’MISC_DEFINES=USE_LSEARCH_REGEXCMP’’ then a line where the first field is surrounded in double quotes ("") specifies a regular expression (without the quotes) against which the key is matched using the host platform’s underlying regular expression library.

aliasyp

Look up the key in a Sun NIS database. This differs from yp in that a NUL byte is added to the end of the key before lookup.

nialias

Look up the key in a NeXT netinfo database.

nisplus

Look up the key in a Sun NIS+ (Sun NIS Version 3) database. NIS+ is not compatible with NIS (otherwise known as YP). The file expansion parameter must be a NIS+ indexed name. The lookup routine within smail allows you to prepend the file-expansion with a string like ’’@2,’’ to use field number 2 from the result instead of using field 1 by default.

Variables
The complete set of available variable names depends upon context, but the following are always available:
compile_date
ld_date

the date when the current smail binary was compiled.

compile_num
ld_num

a decimal number giving the number of times smail has been compiled since the creation of the source file src/ldinfo.c.

ctime

the date and time, in the form returned by the ctime(3) function.

date

The date and time in ARPAnet (RFC 822) format.

spool_date

The date and time that the message was received by the local host, in ARPAnet (RFC 822) format.

grade

The priority character for the current message. See the grades attribute in the smailconf(X_MAN_5_EXT) manual for more information on this value.

ident_sender

The identification code of the user that sent the mail over its last hop as determined by the RFC 1413 protocol (other protocols may be added in future versions). This will generally only be set for mail received by SMTP. It is most useful for putting into the Received: message header field. This string has a null value if no sender-ID can be determined.

ident_method

The identification method used to generate the ident_sender. Currently this will always be ’’rfc1413’’.

This variable will be null if ident_sender is also null.

message_id

message_size
size

the total size of the spooled message.

message_body_size
body_size

the size of the body of the message, which excludes the message header fields, and also excludes any overhead within the message spool file.

primary_name
primary

the canonical name for the local host.

release_date
release

the release date of the smail sources.

sender
from

the address of the sender of a message.

sender_name
fullname

the full-name of the sender, taken either from the ’’−F’’ command line argument, or from the password file.

sender_host

the sending host, if one is known. This is set automatically for mail received via UUCP or SMTP. It can also be set with ’’−oMs’’ from the command line.

sender_host_address

the sending host’s address, if one is known. This is set automatically for mail received via SMTP. It can also be set with ’’−oMa’’ from the command line.

sender_proto

the sending protocol (e.g. ’’smtp’’ or ’’uucp’’), if one is known. This is set automatically for mail received via UUCP or SMTP. It can also be set with ’’−oMr’’ from the command line.

sender_program

The program that queued the message. For mail received via UUCP, this will be, typically, ’’rmail’’. Otherwise, the sender program will likely by set to ’’sendmail’’ or ’’smail’’, depending upon the program that typically is invoked for receiving mail.

uucp_name

the UUCP−network name for the local host.

version

a short version string for Smail.

version_string

a verbose version string.

visible_name
name

the local host name used in outgoing addresses.

smail_lib_dir
lib_dir

the value of the config file variable smail_lib_dir, which is the directory in which configuration files are found.

In addition, the following variables are defined if they are available in the current context:
HOME
home

the home directory of a user associated with an address.

host

the remote host string associated with a remote address.

local_domain

The local domain an address may have matched, if it matched a local domain.

user
addr

a user name or remaining local part of the address after all rewriting.

user_prefix

any string matching the regular expression given in the optional prefix attribute of a director instance using the user director driver.

user_suffix

any string matching the regular expression given in the optional suffix attribute of a director instance using the user director driver.

input_addr

The address specified in the message, or in an alias or mailing list expansion, that is being processed.

mailbox

The ’’local part’’ of the input address.

route

Any route specification from the input address.

director

The name of the director that matched the address, if appropriate.

router

The name of the router that matched the address, if appropriate.

transport

The name of the transport to be used for delivering to the address, if the address has been successfully resolved.

Meta-Expansion Modifiers
The following modifiers are available for meta-expansions. Note that multiple modifiers can be specified and that they are interpreted strictly from left to right.

The following are sample string expansions:

    /usr/spool/mail/${lc:user}

with a $user value of ’’Tron’’ will become:

    /usr/spool/mail/tron

whereas:

    Received: by $primary_name ($version_string)
              id <$message_id@primary_name>;
              $spool_date

will become something such as:

    Received: by futatsu.uts.amdahl.com (smail 3.0.2 03-dec-87)
              id <m0c87zK-007zXpC [AT] futatsu.com>;
              Tue, 8 Dec 87 19:45 PST

and:

    $host!rmail ${strip:addr}

with an $addr value of ’’Ronald S. Karr’’ and a $host value of ’’amdahl’’ will become:

    amdahl!rmail Ronald.S.Karr

Another important example

    smart_user="|/bin/mquery -f ${shquote:lc:sender} ${shquote:lc:user}"

with a $sender value of:

    Foo’;rm /etc/passwd;’

and a $user value of ’’Got Ya!’’ will become:

    |/bin/mquery -f ’foo’"’"’;rm /etc/passwd;’"’"’’ ’got ya!’

(but he won’t have ’’got’’ you because you used ’’${shquote:’’!)

If a value does not exist (such as $HOME being used when no associated home directory is known, or when a string begins with ’’~username’’ and ’’username’’ is not a known use, or when $host is used for a local address) then the expansion fails.

DIRECTOR, ROUTER AND TRANSPORT FILE FORMATS

The directors, routers, and transports configuration files share a common format, which is described in this section. The specific contents for each file are described in separate manual pages.

Each entry in one of these files specifies a name for the entry, a set of generic attributes and a set of driver-specific attributes. The generic attributes and the driver attributes define the characteristics for the entry.

The list of possible generic attributes are common to all entries in a configuration file. One generic attribute is always required: the driver attribute. This attribute names the underlying set of internal functions that will be used when using that entry. The list of possible driver attributes are specific to each different driver.

The form of an entry is:

    entry_name:
        generic_attribute, ... ; driver_attribute, ...

where a comma separates the definitions for specific attributes and where a semicolon separates the generic attributes from the driver attributes. It is not an error for an entry to end in a comma or semicolon. The form for generic and driver attributes is the same as for entries in the config file.

As an example, consider an entry in the transport file that specifies use of the program /bin/mail to deliver mail to local users. The mail messages are to contain a Return-Path: header field, and the /bin/mail program is to be given no more than 20 addresses per invocation. A simple entry to specify this is:

    # call /bin/mail to deliver to local users local:
    max_addrs=20,
    return_path,
    driver=pipe;
    cmd="/bin/mail $($user$)"

INTERACTION BETWEEN DIRECTORS, ROUTERS AND TRANSPORTS

To better understand the use of the directors, routers, and transports this section describes, briefly, how address resolving and delivery is accomplished in Smail. Of course the configuration specified in these files is intimately involved in this process.

When Smail is given a list of addresses to which a message is to be delivered, the list is processed iteratively until a list of resolved addresses is produced. When an address is resolved, the transport (the part of Smail that performs delivery of messages to local users or remote hosts) and all data required by the transport to perform the message delivery will be known.

To accomplish this the Smail program goes through the following steps:

That director has the option of returning a new list of addresses or of putting the address on a list of resolved addresses. If new addresses are produced, they are put on the input list, to be processed from step ’a’ again.

It is important to note that all domain names (and normally all local usernames) are matched independent of case, so that, for example, ’’Postmaster’’, ’’POSTMASTER’’, ’’PostMaster’’, and ’’postmaster’’ all compare equal.

In addition an internal hash table is kept of all regular recipient addresses on a per-transport basis, that is, all addresses which do not specify files or shell commands. This table is used to prevent duplicate deliveries.

FILES

The following files and directories are from a typical smail configuration:
/etc/smail/config

Optional general smail configuration. This file can override compiled-in configuration.

/etc/smail/transports

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

/etc/smail/directors

Optional configuration for smail directors, i.e., configured methods for resolving local addresses. This file replaces the compiled-in director configuration.

/etc/smail/routers

Optional configuration for smail routers, i.e., configured methods for resolving or routing to remote hosts. This file replaces the compiled-in router configuration.

/etc/smail/aliases

A file of aliases for local addresses.

/etc/smail/paths

A file of paths to remote hosts.

/etc/smail/lists/

A directory of mailing list files.

~/.forward

Lists of forwarding addresses for local users.

/var/mail

The top of the spool directory hierarchy.

/var/mail/input

The directory containing messages to be processed and delivered.

/var/mail/msglog

A directory of transaction logs for individual messages.

/var/mail/lock

A directory used in smail input spool files.

/var/log/smail/logfile

A log of smail transactions.

/var/log/smail/paniclog

A log of configuration or system errors encountered by smail.

/var/mail/error

Messages that failed due to a small set of fatal error such as a configuration error are placed in this directory. Currently the site administrator must move these back into /var/mail/input when the error condition is resolved.

/var/mail

The directory for user mailbox files.

SEE ALSO

binmail(1), mailx(1) under System V, Mail(1) under BSD, resolver(3), mailaddr(7), named(8), pathto(1), smailconf(5), smaildrct(5), smailmeth(5), smailqual(5), smailrtrs(5), smailrtry(5), smailtrns(5), smail(8). whosond(8).

Smail Administration and Installation Guide.

DARPA Internet Requests for Comments: RFC 821, RFC 822, RFC 974, RFC 976, and RFC 1123.

Regular expression documentation for your host, perhaps in re_format(7), regex(3), ed(1), or grep(1).

BUGS

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

Some database files cannot contain ’’#’’ in the left-hand field and have no other mechanism for introducing comments.

There should be a way of specifying that different errors encountered by smail should result in different actions (i.e., mailing a message to the postmaster, storing a detailed error message in a file).

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.