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 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.
Usage:
Invoking router without any arguments will do nothing (except make it read 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.
router [ -diksSV ] [ -f configfile ] [ -n #routers ] [ -o zmshoptions ] [ -t traceflag ] [ -L logfile ] [ -P postoffice ] |
Parameters:
Detach and run as a daemon.
Overrides the default configuration file $MAILSHARE/router.cf.
Run interactively, presenting a zmsh session with the configuration file preloaded.
Kill the currently running router by sending it a SIGTERM signal.
Overrides the default log file location $LOGDIR/router.
Starts the specified number of parallel router processes. The default is a single router process.
Sets the option string passed on the internal zmsh invocation. The default is -O. Note that the leading ``-'' is mandatory. See zmsh(1) for the available options.
Specifies an alternate $POSTOFFICE/ directory.
Can be used to turn off non-serious syslogging.
Turns stability-flag off and on. Without this flag, the search of new jobs will be done with (sometimes) timeconsuming care of organizing the job files into time order.
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.
Print version message and run interactively.
To restart a router daemon:
router -dk |
To test an address, start up an interactive session:
router -i |
sendmail -bt |
Then just use the pre-defined functions.
zmsh is an implementation of the Bourne shell suitable for use with the ZMailer router(8) as its configuration file language interpreter. It contains extensions that allow structured data (in the form of lists) to be manipulated.
The shell supports three basic kinds of functions: Unix commands, user-defined functions, and builtin commands. The latter comes in two variations: normal functions which take string arguments and return a status code (much as an embedded Unix command would work), and list-manipulation functions which understand list arguments and can return list arguments. The defined functions can take any form of argument and return any form of value (a status code, a string, or a list).
Shell operations (pipes, backquote evaluation and substitution) will work between combinations of builtin functions, defined functions, and Unix commands.
The shell precompiles its input to a (possibly optimized) byte-code form, which is then interpreted as required. This means that the original form of the input is not kept around in-core for future reference. If the input is an included file, the shell will try to save the byte-code form in a .fc file associated with the input file. For example, if input is from file.cf, the shell will try to create fc/file.fc and then file.fc. These files will in turn be searched for and loaded (after a consistency check) whenever a .cf file is included.
The effects of input and output redirections are predicted prior to the execution of a command and its I/O setup.
zmsh [ -CILOPRSYaefhinstuvx ] [ -c command ] [ script ...] |
See the Debugging section for [-CILOPRSY] debugging options.
Run the given argument as a shell command script.
Automatically export new or changed shell variables.
Exit on non-zero status return of any command.
Disables filename generation.
Hash and cache the location of Unix commands. The option is set by default.
This shell is interactive, meaning prompts are printed when ready for more input, SIGTERM signal is ignored, and the shell does not exit easily. This flag is automatically set if STDIN and STDERR are both attached to a /dev/tty.
Read commands but do not execute them.
Read commands from STDIN. If there are non-option arguments to the shell, the first of these will be interpreted as a shell script to open on stdin, and the rest as arguments to the script.
Exit after running one command.
Unset variables produce an error on substitution.
Print shell input as it is read.
Print commands as they are executed.
Text to be inserted here. |
The following debugging options are specific to the internal function of zmsh:
Print code generation output onto stdout. If this option is doubled, the non-optimized code is printed out instead.
Print runtime interpreter activity onto /dev/tty.
Print lexer output onto stdout.
Optimize the compiled script. If this option is doubled, the optimized code is also printed out.
Print parser output (S/SL trace output) onto stdout.
Print I/O actions onto /dev/tty.
Print scanner output (token assembly) onto stdout.
Open /dev/tty for internal debugging use.
Text to be inserted here. |
This section describes the router internal functions.
: <SPC> anything else forming a command pipeline |
none
0
none
none
. scriptfilename |
status
none
none
[ {test parameters} ] |
test {test parameters} |
True.
False.
Error.
File testing unary prefix functions:
True if file exists and is block special.
True if file exists and is character special.
True if file exists and is a directory.
True if file exists and is a regular file.
True if file exists and is set-group-id.
True if file has its ``sticky'' bit set.
True if file exists and is a named pipe.
True if file exists and is readable.
True if file exists and has a size greater than zero.
True if fd is opened on a terminal. If fd is omitted, it defaults to 1 (standard output).
True if file exists and its set-user-id bit is set.
True if file exists and is writable.
True if file exists and is executable.
String testing binary functions:
True if the strings are equal.
True if the strings are not equal.
Interget value testing binary functions:
True if values are equal.
True if values are not equal.
True if value1 is greater than value2.
True if value1 is greater or equal than value2.
True if value1 is less than value2.
True if value1 is less or equal than value2.
File comparison binary functions:
True if file1's mtime is newer than file2's.
True if file1's mtime is older than file2's.
True if both files have same inode, and device.
Logical functions:
Unary NOT
Binary AND
Binary OR
Parenthesis
This is basically the shell ``['' a.k.a. ``test'' program.
attributes object-reference |
The property list symbol (4th) component of an address quad.
none
none
basename pathname [ suffix ] |
ok, result string to STDOUT.
Error.
If a suffix is given and matches the filename, the suffix too is stripped from the filename.
Prints the base filename of the pathname.
while ... do ... break ... done case ... ... break ... esac |
none
none
NOT IMPLEMENTED!
builtin {builtin command name, and its params} |
none
NOT IMPLEMENTED!
Ensures that named command is builtin within the scheduler, and not a) external, b) script based.
car object-reference |
Pointer to copied lisp-object of object-reference's car operation.
none
This command is synonymous to the channel and first functions.
cd [directory] |
cd successful.
Error.
none
none
cdr object-reference |
Pointer to copied lisp-object of object-reference's cdr operation.
none
This command is synonymous to the rest function.
channel object-reference |
The channel (1st) component of an address quad.
none
The car and first functions are synonymous to this one.
continue |
none
none
daemon |
none
Starts the router running in daemon mode, scanning the $POSTOFFICE/router/ directory every few seconds for message files to process. This function is invoked automatically by other code in the router program and has no other purpose.
db {add} {database} {key} {value}
db {flush} {database}
db {owner} {database}
db {print} {database}
db {remove} {database} {key}
db {toc}
Error.
Add a {\tt key,value} entry to the database, if possible.
Remove all entries from the database, if possible.
Print the account name of the owner of the database, if possible. This is usually determined by the files associated with the database.
Print all entries of the database, if possible.
Remove a {\tt key} entry from the database, if possible.
Print a table of defined relations and their associated information. This table has five columns, in order: the name of the relation, its type and subtype, cache entries and maximum size, flags, and associated files. See the relation function for more information.
DBType add flush owner print remove ------ ---------------------------- incore yes yes yes yes yes header yes yes yes yes yes ordered no yes yes yes no unordered yes yes yes yes yes hostsfile no no no yes no bind no no no no no ndbm yes yes yes yes yes gdbm yes yes yes yes yes dbm yes yes yes yes yes yp no no yes yes no bhash yes yes yes yes yes btree yes yes yes yes yes ldap no no yes no no |
Does lookup via relation defined dblookup vector:
dblookup key |
Lookup result
Error.
none
The access function to the database facilities in the router.
echo [-n] [string-expressions] |
Don't print newline at end of string.
none
elements lisp-object |
lisp-object
none
none
envars |
none
Print internal variable tree.
erraddron [file] |
none
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.
{\tt eval expression}
status
none
none
{\tt exit}
none
Exit from the shell with exit code.
{\tt export [variable-name ...]}
none
Exports variable name(s). If no variables are given, export prints a list of which variables have been exported.
{\tt filepriv file [uid]}
Error.
none
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 nonwritability and for having the same (or a 0) uid.
{\tt first object-reference}
Pointer to copied lisp-object of object-reference's {\tt car} operation.
none
This command is synonymous to the {\tt car} and {\tt channel} commands.
{\tt gensym}
none
Generates and prints a new symbol name in the sequence {\tt g0} to {\tt gN} every time it is called. The sequence is reset and any symbol values destroyed after the {\em router} has processed a message. This function is used to generate new symbols, to hold attached address property lists, during alias expansion.
{\tt get property-list key}
{\tt property-list}
none
Returns a property list corresponding to key string.
{\tt getopts optstring-name [arguments ...]}
Error.
none
none
{\tt grind lisp-object}
Pointer to list of {\tt varcell}.
none
none
{\tt groupmembers groupname}
none
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, but that are not listed in the groups file, will not appear in this list.
{\tt hash [-r] [command names]}
Path is flushed.
none
{\tt homedirectory user}
Error.
none
Prints the home directory of the specified user account.
{\tt host object-reference}
The host (2nd) component of an address quad.
none
none
{\tt hostname [name]}
Error.
none
Sets the {\em router}'s idea of the system hostname. Without an argument the name is retrieved from the system and printed. The {\em 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.
{\tt lappend varname anyvalue}
none
none
This appends content of list object ({\em anyvalue}) to named {\em varname} variable.
{\tt last lisp-object}
Return a pointer to last cell of {\tt varcell}'s list.
none
none
{\tt length lisp-object}
String of length of {\tt varcell}'s parameter list.
none
none
{\tt list lisp-object}
{\tt lisp-object}
none
none
{\tt listaddresses [-e error-address] [-E errors-to-address] [-c comment]}
Error.
Any syntax errors at list parsing will cause a report to be mailed to the given address.
If an error occurs while messages are being delivered, the `errors-to-address' can be used to force error message destination elsewhere than to the default `sender' of the message.
A comment will be inserted in the error report.
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.
{\tt listexpand [-c comment] [-e error-address] [-E errors-to-address] \$attribute \$localpart \$origaddr {\(<\)} listfile}
{\tt lisp-object}
Any syntax errors at list parsing will cause a report to be mailed to the given address.
If an error occurs while messages are being delivered, the `errors-to-address' can be used to force error message destination elsewhere than to the default `sender' of the message.
A comment will be inserted in the error report.
Implements the most common pipeline where {\tt listaddresses} was used with more efficient memory consumption handling.
{\tt login2uid username}
none
Error.
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 {\tt fullname} in-core database, to add the login name to uid mapping to the {\tt pwnam} in-core database, and to add the uid to login name mapping to the {\tt pwuid} in-core database.
{\tt lreplace varname indexnum anyvalue}
{\tt lreplace varname fieldname anyvalue}
none
none
This replaces designated field on {\em varname} variable containing list-like data with {\em anyvalue} value.
The field designation can be given in numeric form, where the field index can be numeric (first field is zero), or {\em keyname} on key/value pair list.
If a key is not found (with key/value pairs), then designated pair is added to the list.
tt=(aa 11 bb 22 cc 33 dd 44) lreplace tt aa zz grind $tt (zz 11 bb 22 cc 33 dd 44) lreplace tt 0 aaa grind $tt (aaa 11 bb 22 cc 33 dd 44) lreplace tt zz aa grind $tt (aaa 11 bb 22 cc 33 dd 44 zz aa) |
{\tt malcontents}
none
none
none
{\tt printaliases [-v] [-o indexoutputfile] file}
Error.
Verbose.
Each header line will also generate a {\tt header TAB byteoffset} line in the indexfile.
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. 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 {\em newaliases(1)} program to generate the aliases database from a source file.
{\tt process messagefile}
none
The protocol switch function. It is called by the {\tt daemon} function to process a message found in the {\tt \$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 {\tt MSG\_RFC822} parameter to {\tt mail\_open(3)}. For that case, the protocol function is called {\tt rfc822}. {\em router} has a bit more complex directory semantics, than is stated above. See {\tt zmailer(3)} for details. Although the {\tt process} function is provided built in, it is usually overridden by a defined function in the {\em router} configuration file.
{\tt read [variable]}
Successful read.
Error.
none
none
{\tt recase [-u \verb/|/ -l \verb/|/ -p] string}
Error.
Convert into uppercase.
Convert into lowercase.
Prettify.
A case-mapping function that prints the parameter string in either all-uppercase, all-lowercase, or capitalized (pretty).
{\tt recipient}
Is a recipient address.
Is not.
none
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''.
{\tt relation -t {dbtype[,subtype] [-f file -e\# -s\# -bilmnu -d driver]} name} Options are listed below. {\tt name} is the name of the relation that is wanted to be created. Examples: \begin{alltt} relation -t bind,mx mxhost relation -t ordered -f $MAILVAR/db/routes routes relation -t ordered -b -f /usr/lib/news/active.sorted newsgroups \end{alltt}
Error.
One of the known types of databases, currently:
A database maintained in virtual memeory (using splay trees). This type should not be used for any database that must periodically be flushed, since all occupied memory can be freed.
A database type used to store RFC822 header semantics information. It is unlikely to be used for anything else.
A file with key-value pairs on every line, separated by whitespace, sorted by key.
A file with key-value pairs on every line, separated by whitespace.
{\em hosts(5)} file.
The BIND implementation of a Domain Name System resolver. The subtype for this type is the name of a Resource Record type in the {\tt IN} class.
The new DBM library. The BSD4.4 has a thing called {\tt db}, which is a different thing, but it can be used in place of {\tt ndbm} via its interface library. (The {\tt BSD4.4-db} does have only one database file, not two, like {\tt ndbm} does.)
The GNU implementation of the new DBM library. {\bf Note:} GDBM uses one file, which is named exactly as you parametrize it. This is unlike NDBM, which appends .dir and .pag to the supplied name!
The old DBM library. There can be only one DBM open at the time, and this system keeps them all open all the time. Avoid if you can.
The Network Information Service from Sun Microsystems Inc. (Later renamed to be NIS, the still newer NIS+ is not supported).
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 routine.
The default time-to-live on cached information. When the information has been in the cache for this many seconds, it is discarded. The default is 0.
Sets the cache size to the specified number. The default is usually 10, depending on the database type.
If the key exists in the database, return the key as the value.
If the key exists, its value is a byte offset into a file named by the subtype for this database. The value then becomes the concatenation of the data on the lines following that offset which start with whitespace. This is used for the aliases file.
Map all keys to lowercase before searching.
Check for file content modification before every access. Reopen the file when a change is detected. This option is used when the {\em router} should discover changes to a database underfoot so it need not be restarted to use new data. This is recommended on relations which use unordered, or ordered datasets (aliases, routes, ...), and especially if the system is configured to use {\tt mmap(2)} facility. Updating such databases should preferably use {\tt mv} command to move a new version of the database in place of the old one.
If the key exists in the database and the value is null or list, return the key as value. Otherwise return the value retrieved, if any.
Map all keys to uppercase before searching.
Specifies a search driver that allows searching for structured keys using special knowledge. The argument to this option must be a known driver. Currently the only known driver is {\tt pathalias} which will search a pathalias format database for an entry matching a domain name using the pathalias rules.
On systems with {\tt USE\_MMAP} the ordered and unordered databases are r/o mapped into memory, and for ordered case, a special line-index is generated for speeding up the binary search. (Makes less system calls that way.)
{\tt rest object-reference}
Pointer to copied lisp-object of object-reference's {\tt cdr} operation.
none
This command is synonymous to the {\tt cdr} command.
{\tt return lisp-object}
String contains a not ASCII digit character. (Returns a pointer to {\tt varcell}'s string.)
ASCII digit character. (Returns numeric value.)
Invalid lisp-object.
none
none
{\tt returns lisp-object}
none
none
{\tt rfc822 messagefile}
{\tt status}
none
This function controls the parsing and processing of the message file in RFC822/976 format. It is called by the {\tt process} function.
{\tt rfc822date}
none
Prints the current time in RFC822 format.
{\tt rfc822syntax address}
Error.
none
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 {\tt stdout} and the function returns a non-0 exit status.
{\tt runas user function [arguments...]}
none
Changes the current effective user id of the {\em 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).
{\tt sender}
Is a sender address.
Is not.
none
A boolean function that returns the value of the statement ``executing a header rewriting function and the address is a sender address in a message header''.
{\tt set [-a -e -f -h -n -t -u -v -x -L -C -P -S -k -] variable} Without parameters {\tt set} prints variable values.
Pointer to copied structure of {\tt car} operation.
Automatically export changed variables.
Exit on error exit status of any command.
Disable filename generation (no globbing).
Hash program locations.
Read commands but do not execute them.
Read and execute one command only.
Unset variables are error on substitution.
Print shell input lines as they are read.
Print commands as they are executed.
Trace LEXER processing (sslWalker).
Print branch and emit inputs (sslWalker).
Trace execution (sslWalker).
Print input buffers when used (sslWalker).
Not supported option.
Do nothing.
none
{\tt shift [number]}
Error.
none
Modifies caller's argument vector.
{\tt sleep number}
Error.
none
none
{\tt squirrel [-]event}
Error.
Set flag value to 0.
Set flag value to 1. The events are: \begin{itemize} \item {\tt breakin} \item {\tt badheader} \item {\tt illheader} \item {\tt nochannel} \item {\tt nosender} \end{itemize}
Sets the kinds of events that cause a message to be copied into the {\tt \$POSTOFFICE/postman/} directory. Whether or not a `{\tt -}' 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.
{\tt stability [on \verb/|/ off]}
none
Determines whether the {\em router} will process incoming messages in arrival order (when on), or in random order determined by position in the router directory. The {\em 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.
{\em see: ``['', ``test''}
{\tt times }
Error.
none
none
{\tt trace key1 ... keyN} Enables tracing of the specified items. The valid keywords are listed in the options below.
Error.
Turns on all tracing options. You only do this to test the I/O capabilities of your system.
Prints shell variable assignments.
Prints various information from the code that calls the DNS resolver.
Prints {\tt sift} statement pattern-selector comparisons.
Prints database lookups, including cache search and update information.
Prints the message envelope information after processing each message.
Prints shell function calls and return values, with nesting indicated by indentation.
Prints {\tt sift} statement pattern-selector matches.
Same as {\tt functions}.
Prints regular expression matching execution.
Turns on the {\tt RES\_DEBUG} flag in the {\tt BIND} resolver library, and prints various information from the code that calls the DNS resolver.
Prints the tokenized addresses sent through the message header address rewriting functions.
Prints the tokenized addresses sent through the {\tt router} function.
Prints the procedural steps taken during message processing.
Prints memory allocation information after each message.
{\tt trap [[script trap\_nro] ...]}
none
If no parameters are given, {\tt trap} prints all known traps.
{\tt type [command ...]}
none
none
{\tt uid2login uid}
Error.
none
Prints the first account name associated with a specified user id, if any, or {\tt uid\#uid} if no account exists with that user id. It has the same side-effects as the {\tt login2uid} function.
{\tt umask [octal-number-mask]}
Pointer to copied structure of {\tt car} operation.
none
Without parameters default mask is 077.
{\tt unset [variable ...]}
Error.
none
none
{\tt untrace key1 ... keyN} Disables tracing of the specified items.
Error.
See the {\tt trace} function for valid keywords.
{\tt user object-reference}
The next-address (3rd) component of and address quad.
none
none
{\tt wait [pid]}
{\tt retcode}
none
none