Manpages

NAME

router − zmailer message routing daemon

SYNOPSIS

router [ −diksSVW ] [ −f configfile ] [ −n #routers ] [ −o zmshoptions ] [ −r routerdirloops ] [ −t traceflag ] [ −L logfile ] [ −P postoffice ]

DESCRIPTION

The router daemon makes all decisions affecting the processing of messages in ZMailer.

A mail message is submitted by placing it in a file in the POSTOFFICE/router directory. The router frequently scans this directory for new files and will lock and process them as it finds them. The result is a message control file that gets linked into the POSTOFFICE/scheduler and POSTOFFICE/transport directories for use by the scheduler(8) in the next step of message processing. The original message file is then moved to the POSTOFFICE/queue directory.

The router’s behaviour is controlled by a configuration file read at startup. It is really a zmsh(1) script that uses facilities provided builtin to the router.

OPTIONS

Invoking router without any arguments will do nothing (except make it reads its configuration file and promptly exit). The normal startup method is to run the zmailer(1) script, as in zmailer router. This will start the router as a daemon and kill the previous incarnation of the router.

−f configfile

overrides the default configuration file MAILSHARE/router.cf.

−L logfile

overrides the default log file location LOGDIR/router.

−m memtracefile

For debug purposes when compiled with XMEM option, not in general production setup.

−n #routers

starts the specified number of parallel router processes. The default is a single router process.

−o zmshoptions

sets the option string passed on the the internal zmsh invocation. The default is -O. Note that the leading ’-’ is mandatory. See zmsh(1) for the available options.

−P postoffice

specifies an alternate POSTOFFICE directory.

−r routerdirloops

Process routerdirloops messages out of any alternate router directories, then check to see if any higher-priority jobs have been created. If undefined and alternate router directories are in use, the router will clear the entire directory before returning. See below and zmailer(3) about Z-Environment and ROUTERDIRS.

−t traceflag

sets trace options, one per -t switch, even before the configuration file is loaded. This is otherwise equivalent to the builtin trace command. The currently known options are: assign, bind, compare, db, final, functions, matched, memory, on, regexp, resolv, rewrite, router, and sequencer.

To restart a router daemon:

router -dk

To test an address, start up an interactive session:

router -i

or if the ZMailer sendmail(8) is installed:

sendmail -bt

Then just use the pre-defined functions.

CONFIGURATION FILE

The router configuration file must provide some services so the message processing can proceed:

The interface specifications of these items exhaust the expectations the router has of its configuration file. The router contains useful builtin functions that will aid in implementing the required functionality. These functions are described in the section on BUILTIN FUNCTIONS below.

Optionally the router may provide services to other programs. In particular, the smtpserver(8) program relies on the router to do address validation and verification when it is asked (and enabled) to provide this service during an SMTP conversation. The expected name for this function is server.

The following are the interface specifications for the functions mentioned above:
router address attributes

This function is applied to all message envelope addresses. The first argument to this function is a syntactically valid (understood by the parser) address. The second argument is a symbol whose value is a property list for the address. The property list consists of alternating keys and values, and is modified using the lreplace function.

The router function returns a list of address groups. Each address group is a list of mutually exclusive address tuples, i.e. delivering to one is equivalent to delivering to any other destination address in the group. An address tuple is a list of 4 elements (another name for this is a quad), which in order are:

By convention, if either the channel or host is irrelevant, it is given as "-".

For example, these are possible parameters and return value:

z# g0=(privilege 0 type recipient)
z# router rayan g0
(((local - rayan g0)))

This function also handles any alias expansion that may be necessary. The following example shows the expansion of a single address to multiple independent recipients:

z# router root g0
(((local - ken g0)) ((local - rayan g0)))

The router function is free to change the privilege of the address, or to add any other information to the property list for use by the crossbar function.

Note: in the current version of ZMailer, only the router knows about mutually exclusive addresses. Therefore all quads must be the lone element of their address group.

If a resource deferral occurs during processing (e.g., the nameserver is busy or broken), the global variable defer will be set to a non-null string indicating the problem. This string is in a format interpreted by the hold transport agent when it sees a host name in a destination address.

crossbar from to

This function controls policy decisions that require context knowledge. It rewrites the next-address portion of an address quad to the proper form, and determines which style of message header rewriting is appropriate. The arguments are sender and recipient address quads, as returned by the router function. The return value is a list of three elements:

The message header address rewriting function will be called with a single argument, the address in original form, and returns a string argument, the address rewritten.

header_defer address

This function rewrites a message header address that might not have been rewritten properly due to a resource deferral. In that case the defer variable will be set by the router during execution of the message header address rewriting function specified by the crossbar function. To avoid repeatedly having to check for this at the end of such rewriting functions, this mechanism is provided as a convenience. Any resource deferral during the execution of this function is ignored. Typically header_defer would just quote the address and make it relative to the local host.

server key ...

This function is not used by the router while processing mail. It is called from the smtpserver when synchronous address validation is required. Since this function may need services provided by other parts of the normal configuration file, it is included by convention. The first argument is a keyword which describes the desired service, followed by parameters to that service. The known keywords are:

SMTP error codes and text may be echo’ed directly, and multiline output is handled by a filter in the smtpserver.

BUILTIN FUNCTIONS

The following builtin functions are provided in the router that do not exist in zmsh:
Functions that take a list argument:
channel

returns the channel (1st) component of an address quad.

attributes

returns the property list symbol (4th) component of an address quad.

Normal functions that take string parameters and return strings:

basename pathname [ suffix ]

prints the base filename of the pathname. If a suffix is given and matches the filename, the suffix too is stripped from the filename.

db { add|remove|flush|owner|print|toc } [ database [ key [ value ] ] ]

is the access function to the database facilities in the router. The keyword arguments are:

The keywords may be abbreviated to their smallest unique prefix (usually a single character).

erraddron [ file ]

specifies a filename to append all address parsing error messages to. If there is no argument given, the logging is stopped. This is primarily for curious postmasters or other collectors of address trivia.

filepriv file [ uid ]

prints the numeric user id of the least privileged account that can modify the specified file. This is determined by an approximation that pessimistically assumes that any file or directory writable by group or others is insecure, and optimistically assumes that it is enough to check a file and its parent directory instead of all the way to the filesystem root. The reason for the latter is that if grandparent directories are insecure, the system is likely to have just as bad potential problems as can be created by using mail to run processes with forged powers (besides, doing the full check would be quite expensive).

If a second argument is given it is the numeric user id to assume for the file. This means only the parent directory will be checked for non-writability and for having the same (or a 0) uid.

groupmembers groupname

prints the accounts that are listed as members of a group in the system groups file, one per line. Note that accounts with the same login group id in but that are not listed in the groups file will not appear in this list.

homedirectory user

prints the home directory of the specified account.

hostname [ name ]

with an argument this sets the router’s idea of the system hostname, else the name as retrieved from the system is printed. The router has no preconceived notion of what the hostname is, so Message-Id and Received headers will only be generated if a hostname has been set using this function.

lappend varname $values..

Looks up named variable, and gives up if does not find it.

The variable data content is considered to be a simple list, and the values are appended to it as a chain.

listaddresses [ -e error-address ] [ -E errors-to-address ] [ -c
comment ]

filters an RFC822 address list on standard input to produce one normal form (no non-address tokens) address per line on its output. This function can be used to parse the alias file or .forward files or similar. If an error-address is specified, any syntax errors at list parsing will cause a report to be mailed to the given address. If a comment is specified, it will be inserted in the error report. If an errors occurs while messages are being delivered, the ’errors-to-address’ can be used to force error message destination elsewere than to the default ’sender’ of the message.

listexpand [ -c comment ] [ -e erroraddress ] [ -E errors-to ]
$attribute $localpart $origaddr < listfile

implements the most common pipeline where listaddresses was used with more efficient memory consumption handling.

login2uid login

Prints the uid associated with the specified account name, if any. A side-effect is to add the GECOS name field of the account to the fullname in-core database, to add the login name to uid mapping to the pwnam in-core database, and to add the uid to login name mapping to the pwuid in-core database.

lreplace listvarname fieldindex $newvalue

This modifies the content of named listvarname (property-list) variable by replacing:
with numeric index

the value of indexed element; say "1" would replace second data item in simple chain. If the index goes beyond the chain, the new value is added at the tail of the chain.

with property-element name

the value of possibly existing property-element pair (say: "name1" "value1" "name2" "value2") is replaced with a new one. If the name can not be found, name and its value are appended to the variable.

printaliases [ -v ] [ -o indexoutputfile ] file

reads RFC822 syntax header lines from the specified file, parses them assuming contents must be an address list, and sorts and prints the header lines with all addresses in normal form. If the −o switch is specified, each header line will also generate a header TAB byteoffset line in the indexfile. Comments are allowed; they extend from the character ’#’ at the beginning of a line, or after an address, to the end of line. This function is used by the newaliases(1) program to generate the aliases database from a source file.

process messagefile

is the protocol switch function. It is called by the daemon function to process a message found in the POSTOFFICE/router directory. This function will in turn call an internal protocol-specific function which knows the syntax and semantics of the message file. The current version knows about messages submitted using the MSG_RFC822 parameter to mail_open(3). For that case, the protocol function is called rfc822. router has a bit more complex directory semantics, than is stated above. See zmailer(3) for details. Although the process function is provided built in, it is usually overridden by a defined function in the router configuration file.

recipient

is a boolean function that returns the value of the statement "executing a header rewriting function and the address is a recipient address in a message header".

recase [ -u | -l | -p ] string

is a case-mapping function that prints the parameter string in either all-uppercase, all-lowercase, or capitalized (pretty).

relation -t dbtype[,subtype] [ -f file -e# -s# -bilmnNu% -d driver ]
name

informs the router of the existence of a database, and how to access it. It also creates a builtin function with the specified name, which is used to retrieve the value associated with a key in the database. The options are:
−t dbtype

is one of the known types of databases, currently:

unordered

is a file with key-value pairs on every line, separated by whitespace. (See about "−m"-option!)

ordered

is a file with key-value pairs on every line, separated by whitespace, sorted by key. (See about "−m"-option!)

hostsfile

is the hosts(5) file.

−f file

is a file associated with the database, typically the file containing the data, or the basename of DBM files or something similarly relevant to the database access routines.

Updateing such databases should preferrably use mv command to move a new version of the database in place of the old one. ( do not use copy! )

−d driver

specifies a search driver that allows searching for structured keys using special knowledge. The argument to this option must be a known driver.

Currently known drivers are:
pathalias

The lookup sequence for ’’foo.bar.edu’’ is:

foo.bar.edu
.foo.bar.edu
.bar.edu
.edu
.

pathalias.nodot

The lookup sequence for ’’foo.bar.edu’’ is:

bar.edu
edu

longestmatch

The lookup sequence for ’’foo.bar.edu’’ is:

foo.bar.edu
.bar.edu
.edu
.

The ’%0’ is always the full key, ’%1’ may be "wildcarded" portion of the key in case any of the driver routines is used, and the original full key does not give a match.

Nominally ’%1’ thru ’%9’ are positional options to name:

result=$(name $keyval $opt1 $opt2 ... $opt9)

However like is above mentioned, "wildcarding" lookup drivers may change the indices making "$opt1" above to be ’%2’, and eight option would become ’%9’ making ninth inaccessible.

rfc822 messagefile

This function controls the parsing and processing of a message file in RFC822/976 format. It is called by the process function.

rfc822date

prints the current time in RFC822 format.

runas user function [ arguments... ]

changes the current effective user id of the router process to that given (which may be numeric or an account name), then runs the specified function with the specified arguments, then switches the effective user id of the process back (to root).

rfc822syntax address

This is a simple interface to the address parser. If the command line argument is a syntactically valid RFC822 address, this command is silent and returns 0 as exit status. If there is a parse error, a verbose error message is printed to stdout and the function returns a non-0 exit status.

squirrel { [-]event }

sets the kinds of events that cause a message to be copied into the POSTOFFICE/postman directory. The events are: breakin, badheader, illheader, nochannel, nosender. Whether or not a ’-’ is necessary for an event depends on the current state of the event’s flag. The usage message will indicate what to do to toggle the event flag.

stability { on | off }

determines whether the router will process incoming messages in arrival order (when on), or in random order determined by position in the router directory. The router will by default do the first queue scan in stable mode, and subsequent scans in unstable mode. The name of this command is the name for a similar characteristic of sorting algorithms.

trace key1 ... keyN

Enables tracing of the specified items. The valid keywords are:

The rtrace routine at the default router scripts is defined as:

trace all except rfc822 regexp

compare

print sift statement pattern-selector comparisons.

functions

print shell function calls and return values, with nesting indicated by indentation.

matched

print sift statement pattern-selector matches.

rewrite

prints the tokenized addresses sent through the message header address rewriting functions.

sequencer

prints procedural steps taken during message processing.

uid2login uid

Prints the first account name associated with a specified user id, if any, or uid#uid if no account exists with that user id. It has the same side-effects as the login2uid function.

untrace key1 ... keyN

Complement of the trace function.

In addition any defined relations will create a builtin function with the same name as the relation.

GLOBAL VARIABLES

The following shell variables are defined by the router:

envelopeinfo

is set by the rfc822 function as soon as possible after the message has been validated, and before the first call to the router shell function. It is a property list of at least the following elements:

message-id

The message-id.

headersize

The message header size in bytes.

bodysize

The message body size in bytes.

trusted

A "yes" or "no" indicating whether file owner is trusted.

Furthermore every envelope header without address semantics will be added to the list, typically:

rcvdfrom

The host of the last MTA to touch the message.

etc.

HEADERS

The predefined database headers is used to specify to the RFC822 message header parser which headers it should pay attention to and what their semantics are. The database keys are lowercased header field names. The values are strings of three fields separated by a colon (’:’) character. The first field is the name of the semantic rule in the parser that should be used to parse the header. The second field is either Sender or Recipient or null (indicated by a -), corresponding to whether the header contains addresses and if so which type. The third field is used for a Resent flag, which should be given if the header has a proper Resent- prefix, otherwise null.

There are two kinds of entries in the headers database: mandatory, and optional. The mandatory entries are for those headers that are absolutely necessary for the proper relaying of mail. Typically these are purely address headers. The optional entries are for headers that are not essential to the relaying of mail, but whose semantics are in fact specified in RFC822. For example, here is a representative sample of the contents of the database:

You may decide to add or remove header definitions from this database. This is done using the normal database interface function, db. For example, if you want to disable the automatic checking (and rewriting) of Date message headers, you would do "db delete headers date". Such actions should never be done lightly, since it will likely cause violation of the RFC822 protocol when transferring mail to other mailers.

SIGNALS

SIGHUP:

execution of the shell trap handler is deferred until a sequence point. This makes it easier to do log rollovers entirely in the configuration file, without fear of data corruption.

SIGTERM:

exit cleanly (immediately if idle, otherwise after finishing with the message being processed).

Other signals may be handled by shell traps.

Z-ENVIRONMENT VARIABLES

MAILVAR
MAILSHARE

these two tell the directories where the configuration files and routing databases are located at. The MAILVAR files are host dependent, while MAILSHARE files can be common to all of the campus.

NROUTERS

tells how many parallel routers there may be running.

LOGLEVEL

** document missing **

POSTOFFICE

defines directory where all POSTOFFICE functions are under.
Example: POSTOFFICE=/var/spool/postoffice

ROUTERDIRS

defines a ’:’ separated list of alternate router directories. If these are defined at all, they must exist, if alternate queueing priority mechanism is desired to be used.
Example: ROUTERDIRS=router1:router2:router3:router4

SCHEDULERDIRHASH

Carries a numeric value of ’’1’’ or ’’2’’ (if defined at all), which will then override possible ’’-H’’ option at the scheduler. Existence of this ZENV-variable tells the router to send messages directly to the scheduler’s hash subdirectories, thus eliminating a few directory operations which the scheduler would otherwise do, and at the same time limiting the size of the directory files.

SYSLOGFLG

** document missing **

FILES

SEE ALSO

router(8), mailq(1), zmailer(3), zmsh(1)

AUTHOR

This program authored and copyright by:
Rayan Zachariassen <rayan [AT] cs.edu>
A plenty of changes and further developement by:
Matti Aarnio <mea [AT] nic.fi>