SMAIL(5) Local SMAIL(5)NAME
config, directors, routers, transports, retry, qualify - configuration
files used by smailSUMMARY
/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 configu‐
ration 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 configura‐
tion, 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 char‐
acters 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 simi‐
larly 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 back‐
slash (\) 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' specify‐
ing 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 val‐
ues. 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 prefix‐
ing them with an exclamation mark (!). When some value is being com‐
pared 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 speci‐
fied 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 con‐
structed 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 plat‐
form'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 mul‐
tiple 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 con‐
verts 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 par‐
ticular 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 con‐
dition 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 deliv‐
ery 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, oth‐
erwise 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, organ‐
ised 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 reg‐
ular expression (without the quotes) against which the key is
matched using the host platform's underlying regular expression
library.
dbm Look up the key in a dbm database.
yp Look up the key in a Sun NIS database.
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. Cur‐
rently this will always be ``rfc1413''.
This variable will be null if ident_sender is also null.
message_id
id the message-ID for the current message.
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.
pid
$ the current process-ID.
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 automati‐
cally 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.
eval expand all variable expansions, file lookups, etc. in specified
variable. (This is probably only useful when used on the com‐
mand line with -bP.)
lc convert to lower case.
parent interpret the value within the context of the parent local
address that produced the associated address. This is useful
when the local address that produced an address is desired.
Expansion fails if no parent exists.
quote enclose the value in quotes, if it would not otherwise be a
valid local-form address, within the rules of RFC 822. Uses
backslash escapes as appropriate.
rxquote make the whole string only match exactly when used as a regular
expression (RE) by properly escaping any RE meta-characters.
This can be used when expanding lists of hostnames within other
lists, for example.
shquote make the value of a variable into a single quoted string (i.e.
one shell argument), and properly escape any internal quote
characters. This tidies up a variable value that may have been
supplied from an untrusted source to allow it to be passed to a
shell command without nasty effects. Note that you only have
to use ``${shquote:'' on string values that will be passed as
arguments on a shell command line. In some cases even the pipe
driver does not use the shell.
strip Remove backslashes and double quotes from a value. If a dou‐
ble-quote is preceded by a backslash, the backslash is removed,
but the double quote is not. Sequences of whitespace charac‐
ters and dots are converted to exactly one dot character.
top interpret the value within the context of the original address,
supplied to the mailer, that produced the associated address.
uc convert to upper case.
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@futatsu.uts.amdahl.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 com‐
mon 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 possi‐
ble 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 semi‐
colon. 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:
a. Each address is parsed to find a domain name, called the target,
and the remaining part of the address, called the remainder. As a
simple example, in the address ``tron@uts.amdahl.com'', the domain
part ``uts.amdahl.com'' is the target and ``tron'' is the remain‐
der. In the address ``sun!amdahl!tron'', the target is ``sun'' and
the remainder is ``amdahl!tron''. More information on e-mail
addressing forms can usually be found in mailaddr(7).
b. Each local address is given to the directors, in the order speci‐
fied by the directors file, until one of the directors says that it
knows what to do with that address.
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 pro‐
cessed from step `a' again.
c. The addresses returned by the directors are classified as either to
be delivered to some remote host, or locally deliverable.
d. Each remote address is passed to the routers, in the order speci‐
fied by the routers file, until one of the routers is able to match
the target name for the address. If no router is able to match the
complete target, then the first router with the longest match will
be used. The router specifies the transport to be used for deliv‐
ery to that address, plus some other information required by the
transport, such as the next_host and next_addr values. The trans‐
port may be specified either by a router attribute or it may come
from a method file.
e. When all addresses have been resolved, they are sorted out and
passed to the transports. It is the job of the transport to
deliver a message to the set of addresses that it is handed.
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 dupli‐
cate deliveries.
FILES
The following files and directories are from a typical smail configura‐
tion:
/etc/smail/config
Optional general smail configuration. This file can override com‐
piled-in configuration.
/etc/smail/transports
Optional configuration for smail transports; i.e., configured meth‐
ods of mail delivery. This file replaces the compiled-in transport
configuration.
/etc/smail/directors
Optional configuration for smail directors, i.e., configured meth‐
ods 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 ALSObinmail(1), mailx(1) under System V, Mail(1) under BSD, resolver(3),
mailaddr(7), named(8), pathto(1), smailconf(5), smaildrct(5), smail‐
meth(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_for‐
mat(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.
Smail-3 RELEASE-3_2_0_115 SMAIL(5)
