home *** CD-ROM | disk | FTP | other *** search
Subject: v25i021: Ease 3.5 - high-level sendmail.cf language, Part05/06 Newsgroups: comp.sources.unix Approved: vixie@pa.dec.com Submitted-by: Bruce G. Barnett <barnett@crdgw1.ge.com> Posting-number: Volume 25, Issue 21 Archive-name: ease3.5/part05 #! /bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh <file", e.g.. If this archive is complete, you # will see the following message at the end: # "End of archive 5 (of 6)." # Contents: doc/ease.paper # Wrapped by vixie@cognition.pa.dec.com on Tue Dec 10 08:45:58 1991 PATH=/bin:/usr/bin:/usr/ucb ; export PATH if test -f 'doc/ease.paper' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/ease.paper'\" else echo shar: Extracting \"'doc/ease.paper'\" \(32946 characters\) sed "s/^X//" >'doc/ease.paper' <<'END_OF_FILE' X... X... $Header: /tmp_mnt/home/kreskin/u0/barnett/Src/Ease/ease/doc/RCS/ease.paper,v 3.3 1991/09/09 16:36:05 barnett Exp $ X... X... $Log: ease.paper,v $ X... Revision 3.3 1991/09/09 16:36:05 barnett X... minor bug fixes X... X... Revision 2.0 1990/01/30 12:50:44 jeff X... Baseline version, corresponding to netwide release 2.0. X... X... Revision 1.6 88/06/15 10:12:36 root X... Some editorial cleanup, added Acknowledgements section. X... X... Revision 1.5 88/01/21 17:19:35 root X... Several editorial changes. ADR. X... X... Revision 1.4 87/12/23 11:30:47 root X... Updated list of authors. Documented extended canon() capability. X... Integrated fluke changes in a little better. ADR. X... X... Revision 1.3 87/11/04 11:33:45 root X... Documented new keyword "while" which is equivalent to "if". ADR. X... X... Revision 1.2 87/08/13 17:08:05 root X... Changes from Jeff Stearns, fluke!jeff, for Sun. ADR. X... X... Revision 1.1 87/08/13 17:05:00 root X... Initial revision X... X... X.LP X.TL XEase: A Configuration Language for Sendmail X.AU James S. Schoner X.AI Purdue University Computing Center West Lafayette, Indiana 47907 X.AU Jeff P. Stearns X.AI John Fluke Manufacturing Company XEverett, Washington 98206 X.AU Arnold D. Robbins X.AI XEmory University Computing Center Atlanta, Georgia 30322 X.AU Bruce G. Barnett X.AI General Electric Corporate Research and Development Schenectady, NY 12301 X.sp 2 X.I X.ce ABSTRACT X.R X.PP The rapid expansion of computer networks and ensuing variation among mailing address formats have made address interpretation an increasingly complex task. In the UNIX* 4.2BSD operating system, a program named X\fIsendmail\fR was introduced which provided a general internetwork mail routing facility. This facility has significantly diminished the complexity of handling address interpretation. X.PP X\fISendmail\fR's address interpretation is based on a rewriting system composed of a number of rewriting rules (or productions) arranged as part of a configuration file. Unfortunately, the syntactical format of a configuration file for \fIsendmail\fR is both terse and rigid, making it rather difficult to modify. The standard format certainly serves its purpose, but, as the need to change these configurations increases in frequency, a more readable format (i.e., one that is similar to the format of modern programming languages) is required to permit reasonably quick modifications to the configuration. As a solution to this problem, X\fBEase\fR provides a level of abstraction which eliminates most of the current syntactic hindrances faced by programmers who must reconfigure \fIsendmail\fR's address parsing scheme. X.PP As a high-level specification format, \fBEase\fR is proving to be an excellent alternative to \fIsendmail\fR's cryptic configuration file syntax. The syntactic structures of \fBEase\fR are patterned after modern language constructs, making the language easy to learn and easy to remember. The format of the address rewriting rule is perhaps the most significant syntactical improvement. It was undoubtedly the most needed improvement. Nevertheless, every element of a configuration file is structurally enhanced through the use of \fBEase\fR. X.FS X* UNIX is a registered trademark of AT&T. X.FE X.sp 2 X.NH Introduction X.PP The \fBEase\fR language is a high-level specification format for \fIsendmail\fR's configuration file. The motivation for its development was to fulfill a goal of providing a readable and easily modifiable X\fIsendmail\fR configuration file format. \fBEase\fR fulfills this goal by shielding the programmer from the cryptic configuration specification required by \fIsendmail\fR and providing a high-level language with which the programmer may specify all modifications to a configuration file. The development of Ease coincided with the development of an \fBEase\fR translator, \fIet\fR, which translates a configuration file written in \fBEase\fR to an equivalent file of the standard format accepted by \fIsendmail\fR. X.NH XEase in Profile X.PP As will be seen in the next section, the syntax of \fBEase\fR is quite readable and easy to learn. In order to acquire a relevant perspective on this issue, the reader is advised to examine a raw configuration file for \fIsendmail\fR (the output of the \fBEase\fR translator, \fIet\fR, will do nicely). The raw syntax, while quite fitting for quick translation, can prove to be a programmer's nightmare. X.PP It is recommended that you learn \fBEase\fP by converting your current configuration file into \fBEase\fP format by using the program X\fIcfc\fP written by Arnold Robbins and modified by Bruce G. Barnett. X.PP Undoubtedly, one of the more prominent features of \fBEase\fR is the ability to attach names to address fields. When address field names are well-chosen, a distinct, self-documenting quality becomes a visible part of the address rewriting rules. Ostensibly, address field names provide a new level of semantic abstraction. A brief comparison of the formats can be accomplished by examining the following equivalent representations of an address pattern: X.DS X user_path@host_name (\fBEase\fR format) X $+@$- (raw format) X.DE In the above, \*Quser_path\*U represents a field of one or more address tokens, and \*Qhost_name\*U represents one address token exactly. These token fields are represented by \*Q$+\*U and \*Q$-\*U in the raw format. Clearly, the \fBEase\fR format is preferable, not only for increased readability, but structural comprehension as well. X.PP Other features of \fBEase\fR include ruleset naming, long identifiers for macros and classes, flow-of-control structures, and free formatting. In addition, it supports C language preprocessor (cpp) commands, which can be used for file inclusion and conditionally defined code constructs. The next section describes the \fBEase\fR language in complete detail. X.NH XEase Syntax* X.FS X* \fINo attempt is made to describe the complete semantic meaning associated with all of the constructs of a sendmail configuration file. Items not covered in this document include the semantic distinction among rulesets, the special uses of pre-defined macros, and the method of building configuration files. To obtain this information, the reader is advised to refer to the Sendmail Installation and Operation Guide (SMM:7 in the 4.3 BSD UNIX System Manager's Manual), by Eric Allman.\fR X.FE X.PP At its highest level, \fBEase\fR can be viewed as a collection of block-structures, where each block begins with a keyword and is followed by zero or more related definitions and/or declarations. There are ten distinct block types. The following is a list containing all ten block keywords and the block type it denotes. X.TS center; l l . X\fIbind\fR -ruleset identifier bindings X\fImacro\fR -macro definitions X\fIclass\fR -class definitions X\fIoptions\fR -\fIsendmail\fR option definitions X\fIprecedence\fR -precedence definitions X\fItrusted\fR -trusted users X\fIheader\fR -mail header definitions X\fImailer\fR -mailer definitions X\fIfield\fR -address field definitions X\fIruleset\fR -address rewriting rules X.TE X.sp 1 In general, X.TS center ; l . X X* Letters are distinguished by case, X T{ X* An \fBEase\fR identifier is defined to be a letter, followed by zero or more letters, digits, underscores (_), or dashes (-), T} X T{ X* A literal newline or double quotation (") character may be included in any quoted string by preceding the character with a backslash (\\\\\), and T} X T{ X* \fBEase\fR source is preprocessed by the C language preprocessor (cpp) if the program is executed with an option understood by cpp. Thus source comments (i.e., text enclosed by \*Q/*\*U and \*Q*/\*U) may appear anywhere as part of \fBEase\fR whitespace. T} X.TE X.PP XFor notational convenience, this document specifies all reserved words of the \fBEase\fR language in italics. In addition, quantities enclosed in angle brackets (<..>) represent arbitrary identifiers, strings, or numbers. X.NH 2 Ruleset Identifier Bindings X.PP A ruleset (a set of rewriting rules) is identified solely by an integer in \fIsendmail\fR's configuration file. \fBEase\fR, however, allows each ruleset to be named with a meaningful identifier. Since a special numeric association for each ruleset is required by the address parsing scheme of \fIsendmail\fR, a \fIbind\fR block must be present in any \fBEase\fR file which defines one or more rulesets. A X\fIbind\fR block consists of the keyword \fIbind\fR, followed by zero or more statements of the form: X.TS center box; l . X<ruleset-id> = \fIruleset\fR <ruleset-number> ; X.TE The following example, X.sp 1 X\fIbind\fR X.PP XFINAL_RW = \fIruleset\fR 4; X.sp 1 specifies that FINAL_RW, the final rewriting ruleset, is \fIsendmail\fR's ruleset number 4. X.NH 2 Macro Definitions X.PP A macro is an identifier which, when referenced in the text of a program, is replaced by its value, a string of zero or more characters. The value of a macro may include references to other macros, but not itself! \fISendmail\fR allows a maximum of 26 user-declared macros in its configuration file. In addition, there are a number of pre-declared macros which have special meaning to \fIsendmail\fR (see Appendix A). \fBEase\fR macros are defined in X\fImacro\fR blocks. \fBEase\fR allows any macro to be declared X(which is equivalent to simply referencing it) before it is defined. A macro identifier is replaced by its value when it is preceded by the character X\*Q$\*U. In addition, a macro reference inside a quoted string must always include braces ({}) around the macro identifier (for delimiting purposes). X.PP A \fImacro\fR block consists of the keyword \fImacro\fR, followed by zero or more statements taking either of the following forms: X.TS center box; l . X<macro-identifier> = "<macro-value>" ; X<macro-identifier> = \fBconditional-expression\fR ; X.TE The \fBconditional-expression\fR format will be discussed later. X.sp 1 The following example, X.sp 1 X\fImacro\fR X.PP first_name = "James"; X.PP last_name = "Schoner"; X.PP whole_name = "${first_name} ${last_name}"; X.sp 1 defines the macros first_name, last_name, and whole_name, where whole_name is the string, "James Schoner". X.NH 2 Class definitions X.PP A class is denoted by an identifier representing a logical grouping of zero or more names. Classes are used to represent the range of values a token may assume in the pattern matching of an address. Further discussion on the use of classes will be deferred until address fields are described. X.PP One identifier may be used to distinctly represent both a macro and class (i.e., the set of macro identifiers and the set of class identifiers may form a non-empty intersection). A name, or class element, may be an identifier or any quoted word. X.PP A \fIclass\fR block consists of the keyword \fIclass\fR, followed by zero or more statements taking any of the following forms: X.TS center box; l . X<class-identifier> = { <name1>, <name2>, <name3>, ... } ; X<class-identifier> = \fIreadclass\fR ( "<file-name>" ) ; X<class-identifier> = \fIreadclass\fR ( "<file-name>", "<read-format>" ) ; X.TE The second and third forms cause \fIsendmail\fR to read the names of the class from the named file. The third form contains a read format, which should be a \fIscanf\fR(3) pattern yielding a single string. X.sp 1 The following example, X.sp 1 X\fIclass\fR X.PP campus_hosts = { statistics, engineering, chemistry, physics, physics-2 } ; X.PP versions = { "1.0", "1.1", "4.0", "4.2", latest-and-greatest } ; X.PP phone_hosts = \fIreadclass\fR ( "/tmp/phonenet.list" ) ; X.sp 1 defines the classes campus_hosts, versions, and phone_hosts. X.NH 2 Sendmail option definitions X.PP A number of options to the \fIsendmail\fR program may be specified in an \fIoptions\fR block. For a description of the various \fIsendmail\fR options and their values, see Appendix B. X.PP An X\fIoptions\fR block consists of the keyword \fIoptions\fR, followed by zero or more statements taking any of the following forms: X.TS center box; l l . X<option-identifier> = "<option-value>" ; X\fIo_delivery\fR = \fBspecial-value\fR ; X\fIo_handling\fR = \fBspecial-value\fR ; X.TE All but two options (\fIo_delivery\fR and \fIo_handling\fR) use the first form. To specify an option without a value, simply assign to it the null string (""). The \fBspecial-value\fR field of the second and third form refers to special values (non-quoted) which are specified in Appendix B. X.sp 1 The following example, X.sp 1 X\fIoptions\fR X.PP X\fIo_alias\fR = "/usr/lib/aliases" ; X.PP X\fIo_tmode\fR = "0600" ; X.PP X\fIo_delivery\fR = \fId_background\fR ; X.sp 1 sets the options \fIo_alias\fR, \fIo_tmode\fR, and \fIo_delivery\fR. X.NH 2 Precedence definitions X.PP Message headers may contain a \*QPrecedence:\*U field describing the precedence of the message class. Identifiers which may appear in the precedence field of a message are given precedence values in a configuration file \fIprecedence\fR definition. This association will be illustrated below in an example. X.PP A \fIprecedence\fR block consists of the keyword \fIprecedence\fR, followed by zero or more statements of the form: X.KS X.TS center box; l . X<precedence-identifier> = <precedence-integer> ; X.TE X.KE The following example, X.sp 1 X\fIprecedence\fR X.PP special-delivery = 100; X.PP junk = -100; X.sp 1 defines the precedence level for the names \*Qspecial-delivery\*U and X\*Qjunk\*U. Thus, whenever the name \*Qjunk\*U appears in a \*QPrecedence:\*U field, the corresponding message class will be set to -100. X.NH 2 Trusted users X.PP X\fISendmail\fR's \fB\-f\fR flag allows trusted users to override the sender's machine address. Trusted users are listed in \fItrusted\fR blocks. A X\fItrusted\fR block consists of the keyword \fItrusted\fR, followed by zero or more sets of users taking the form: X.TS center box; l . X{ <user1>, <user2>, <user3>, ... } ; X.TE The following example, X.sp 1 X\fItrusted\fR X.PP X{ root, uucp, network } ; X.PP X{ acu, kcs, jss } ; X.sp 1 specifies that the users root, uucp, network, acu, kcs, and jss can be trusted to use the \fIsendmail\fR flag, \fB\-f\fR. X.NH 2 Mail header definitions X.PP The format of the message headers inserted by \fIsendmail\fR is defined in one or more \fIheader\fR blocks in the configuration file. A \fIheader\fR block consists of the keyword \fIheader\fR, followed by zero or more statements taking any of the following forms: X.TS center box; l l l l l l l l l l l . X\fIfor\fR ( <mailer-flag1>, <mailer-flag2>, ... ) X \fIdefine\fR ( "<header-title>" , \fBheader-value\fR ) ; X X\fIfor\fR ( <mailer-flag1>, <mailer-flag2>, ... ) { X \fIdefine\fR ( "<header-title>" , \fBheader-value\fR ) ; X \fIdefine\fR ( "<header-title>" , \fBheader-value\fR ) ; X . X . X} ; X X\fIdefine\fR ( "<header-title>" , \fBheader-value\fR ) ; X.TE The first form is used to define one header for one or more mailer flags. The second form differs from the first in that more than one header may be defined for a given set of flags. The third form is used to define a header, regardless of mailer flags. Refer to Appendix C for a list of \fBEase\fR identifiers representing mailer flags. The header title is a simple string of characters (no macro references), whereas the \fBheader-value\fR is a series of one or more strings and X\fBconditional-expressions\fP (discussed later). Concatenation is implicit (as in \fIawk\fP). X.sp 1 The following example, X.DS X\fIheader\fR X X \fIdefine\fR ( "Subject:", "") ; X X \fIfor\fR ( \fIf_return\fR ) X \fIdefine\fR ( "Return-Path:", "<${\fIm_sreladdr\fR}>" ) ; X X \fIfor\fR ( \fIf_date\fR ) { X \fIdefine\fR ( "Resent-Date:", "${\fIm_odate\fR}" ) ; X \fIdefine\fR ( "Date:", "${\fIm_odate\fR}" ); X } ; X.DE defines a \*QSubject\*U field for all mailers, regardless of their flags, a X\*QReturn-Path\*U field for mailers whose definition specifies the flag, \fIf_return\fR, and the headers, \*QResent-Date\*U and \*QDate\*U, for mailers whose definition specifies the flag, \fIf_date\fR. X.NH 2 Mailer Definitions X.PP X\fISendmail\fR's definition of a mailer (or an interface to one) occurs in a X\fImailer\fR block. A \fImailer\fR block consists of the keyword \fImailer\fR, followed by zero or more statements of the form: X.TS center box; l . X<mailer-identifier> { \fBmailer-spec\fR } ; X.TE The field, \fBmailer-spec\fR, is a list of zero or more of the following attribute assignments (where successive assignment statements are separated by commas): X.TS center ; l l l l l l l l l l l l l l . X\fIPath\fR = \fBstring-attribute\fR X\fIArgv\fR = \fBstring-attribute\fR X\fIEol\fR = \fBstring-attribute\fR X\fIMaxsize\fR = \fBstring-attribute\fR X\fIFlags\fR = { <mailer-flag1>, <mailer-flag2>, ... } X\fISender\fR = <sender-ruleset-id> X\fIRecipient\fR = <recipient-ruleset-id> X.TE The \fBstring-attribute\fR value can take the form of a quoted string X(possibly containing macro references) or a \fBconditional-expression\fR X(discussed later). X.sp 1 The following example, X.sp 1 X\fImailer\fR X.DS X local { X \fIPath\fR = "/bin/mail", X \fIFlags\fR = { \fIf_from\fR, \fIf_locm\fR }, X \fISender\fR = Sender_RW, X \fIRecipient\fR = Recip_RW, X \fIArgv\fR = "mail -d ${\fIm_ruser\fR}", X \fIMaxsize\fR = "200000" X } ; X.DE defines a mailer named \*Qlocal\*U. X.NH 2 Address field definitions X.PP X\fISendmail\fR's address parsing scheme treats an address as a group of tokens X(an address token is precisely defined in the Arpanet protocol RFC822). In general, \fIsendmail\fR divides an address into tokens based on a list of characters assigned as a string to the special macro \fIm_addrops\fR. These characters will individually be considered as tokens and will separate tokens when parsing is performed. X.PP XFor the \fBEase\fR language, there is a distinct set of address tokens (defined below) which are used in combination to represent generic forms of addresses. In addition to literal address tokens, the pattern to be matched in a rewriting rule (often referred to as the LHS) may include field identifiers which match one of five possibilities: X.DS X - zero or more tokens X - one or more tokens X - one token exactly X - one token which is an element of an arbitrary class \fBX\fR X - one token which is not an element of an arbitrary class \fBX\fR X.DE A particular field type may be assigned to one or more identifiers. Each field identifier is associated with (or defined to be) a field type in a \fIfield\fR declarations block. A \fIfield\fR declarations block consists of the keyword \fIfield\fR, followed by zero or more field definitions of the form: X.TS center box; l . X\fBfield-id-list\fR : \fBfield-type\fR ; X.TE A \fBfield-id-list\fR is a list of one or more identifiers, each separated by a comma. A \fBfield-type\fR, on the other hand, is a representation of one of the five fields described above. The syntax for each of the five forms follows: X.DS X \fImatch\fR ( 0* ) X \fImatch\fR ( 1* ) X \fImatch\fR ( 1 ) X \fImatch\fR ( 1 ) \fIin\fR <class-X> X \fImatch\fR ( 0 ) \fIin\fR <class-X> X.DE The star in the first two forms means: "or more". Thus, the first form would read: "match zero or more tokens". The fourth form describes a field where one token is matched from an arbitrary class (class-X), whereas the fifth form describes a field where one token is matched if it is not of the given class (class-X). X.sp 1 In addition, the Sun release 3.0 version of \fIsendmail\fR supports several new pattern matching operations represented by the following forms: X.DS X \fImatch\fR ( 0 ) \fImap\fR <macro-identifier-X> X \fImatch\fR ( 1 ) \fImap\fR <macro-identifier-X> X \fImatch host\fR X.DE The macro \*Qmacro-identifier-X\*U should be assigned the name of the relevant YP map. X.sp 1 The following example, X.sp 1 X.DS X\fIfield\fR X anypath : \fImatch\fR ( 0* ); X recipient_host : \fImatch\fR ( 1 ); X local_site : \fImatch\fR ( 1 ) \fIin m_sitename\fR; X remote_site : \fImatch\fR ( 0 ) \fIin m_sitename\fR; X.DE defines the fields anypath, recipient_host, local_site, and remote_site. X.NH 2 Address rewriting rules X.PP Address rewriting rules are grouped according to the function they perform. For example, it is desirable to form a distinct group for those rewriting rules which perform transformations on recipient addresses. X.PP Sets of rewriting rules are defined in \fIruleset\fR blocks. A \fIruleset\fR block consists of the keyword \fIruleset\fR, followed by zero or more ruleset definitions of the form: X.TS center box; l . X<ruleset-id> { <rewriting-rule1> <rewriting-rule2> ... } X.TE The ruleset identifier, ruleset-id, must be defined in a \fIbind\fR block, as described earlier. The rewriting rules have the form: X.DS X \fIif\fR ( <match-pattern> ) X <match-action> ( <rewriting-pattern> ) ; X.DE where match-pattern, rewriting-pattern, and match-action are described below. An alternative form is available: X.DS X \fIwhile\fR ( <match-pattern> ) X <match-action> ( <rewriting-pattern> ) ; X.DE which is somewhat more useful when the \*Qmatch-action\*U is \fIretry\fP X(see below). X.NH 3 Match-patterns X.PP A match-pattern is a sequence of Ease address elements representing an address format. If the address being rewritten matches the pattern X\*Qmatch-pattern\*U, then the address is reformatted using the pattern \*Qrewriting-pattern\*U, and the corresponding action (\*Qmatch-action\*U) is performed. The five distinct Ease address elements which may constitute a match-pattern are as follows: X.TS center ; l . X1. Field Identifiers (refer to previous section) T{ X2. Non-alphanumeric characters (the exception is the case for literal double quotes, which must be preceded by a backslash (\\\\\) T} X3. Macro references X4. Quoted strings ("...") X5. \fBConditional-expressions\fR (discussed later) X.TE Below are two sample match-patterns, each describing the same address format: X.DS X user-id @ hostname . $arpa_suffix X user-id @ hostname ".ARPA" X.DE where user-id and hostname are field identifiers, and arpa_suffix is a user-defined macro with the value \*QARPA\*U. X.NH 3 Rewriting-patterns X.PP A rewriting-pattern specifies the form in which to rewrite a matched address. The seven distinct elements which may be used to form a rewriting-pattern are as follows: X.TS center ; l . X T{ X1. Non-alphanumeric characters (the exception is the case for literal double quotes, left parentheses, or right parentheses, each of which must be preceded by a backslash (\\\\\). T} X T{ X2. A call to another ruleset. This is used to perform rewrites on a suffix of the rewriting-pattern. The proper use of this feature will be demonstrated by example below. T} X X3. Quoted strings ("..."). X X4. \fBConditional-expressions\fR (discussed later). X X5. A macro reference. X T{ X6. A positional reference in the matched address. A positional reference takes the form: $<integer-position>. For example, X$3 references the value of the third \fBEase\fR address element in the matched address. T} X T{ X7. Canonicalized host names of the form \fIcanon\fR (<id-token-list>), where \*Qid-token-list\*U is a list of one or more \*Qid-tokens.\*U An \*Qid-token\*U is a regular identifier, a quoted identifier (with double quotes), a macro reference yielding an identifier, a numeric internet specification (see below), a literal character (such as a \*Q.\*U or a \*Q[\*U), or a positional reference in the matched address. The canonicalization of a host name is simply a mapping to its canonical (or official) form. T} X X.TE Below are two sample rewriting-patterns: X.DS X $1 % $2 < @ $3 ".ARPA" > X OLDSTYLE_RW ( $1 ) X.DE The first form specifies an address such as a%b<@c.ARPA>, where a, b, and c represent matched identifiers or paths. The second form specifies a call to the ruleset \*QOLDSTYLE_RW\*U, for old-style rewriting on the parameter X$1, which probably references the entire matched address. This will become clear in later examples. X.NH 3 Match-actions X.PP When a ruleset is called, the address to be rewritten is compared (or matched) sequentially against the match-address of each rewriting rule. When a match-address describes the address \fIsendmail\fR is attempting to rewrite, the address is rewritten (or reformatted) using the rule's rewriting-pattern. Following this rewrite, the corresponding match-action is performed. There are four match-actions: X.TS center ; l l . X\fIretry\fR T{ X-a standard action which causes the rewritten address to be again compared to the match-address of the current rule. T} X X\fInext\fR T{ X-an action which causes the rewritten address to be compared to the match-address of the next rewriting rule of the current ruleset. If the end of the list is reached, the ruleset returns the rewritten address. T} X X\fIreturn\fR T{ X-an action which causes an immediate return of the ruleset with the current rewritten address. T} X X\fIresolve\fR T{ X-an action which specifies that the address has been completely resolved (i.e., no further rewriting is necessary). The X\fIresolve\fR action is described in more detail below. T} X.TE X.PP The match-action, \fIresolve\fR, is special in that it terminates the address rewriting altogether. The semantic structure of \fIsendmail\fR's rewriting scheme requires that a \fIresolve\fR action appear only in the ruleset whose numerical binding is to the number zero. The \fIresolve\fR action must specify three parameters: \fImailer\fR, \fIhost\fR, and \fIuser\fR. If the \fImailer\fR is local, the \fIhost\fR parameter may be omitted. The X\fImailer\fR argument must be specified as a single word, macro, or positional reference in the matched address. The \fIhost\fR argument may be specified as a single word or as an expression which expands to a single word (e.g., X\fIhost\fR ($1 ".ARPA")). In addition, the \fIhost\fR argument may be a canonicalization (as described above) or a numeric internet specification. The keyword \fIhostnum\fR is used for numeric internet specifications, as in X\fIhostnum\fR ("128.61.1.1") or \fIhostnum\fR ( $2 ). The \fIuser\fR specification is a rewriting-pattern, as described above. X.PP In general, the format of a \fIresolve\fR action will be as follows: X.DS X \fIresolve\fR ( \fImailer\fR ( <mailer-name> ), X \fIhost\fR ( <host-name> ), X \fIuser\fR ( <user-address>) ); X.DE XExamples of the match-action statement are shown below: X.DS X\fIfield\fR X anypath : \fImatch\fR (0*); X usr, path : \fImatch\fR (1*); X hostname : \fImatch\fR (1); X phone_host : \fImatch\fR (1) \fIin\fR phonehosts; X.DE X.DS X\fIruleset\fR X X EXAMPLE_RW { X X \fIif\fR ( anypath < path > anypath ) /* basic RFC821/822 parse */ X \fIretry\fR ( $2 ); X \fIif\fR ( usr " at " path ) /* \*Qat\*U -> \*Q@\*U */ X \fInext\fR ( $1 @ $2 ); X \fIif\fR ( @path: usr ) X \fIreturn\fR ( LOCAL_RW ( < @$1 > : $2 ) ); X \fIif\fR ( anypath < @phone_host".ARPA" > anypath ) X \fIresolve\fR ( \fImailer\fR ( tcp ), X \fIhost\fR ( relay.cs.net ), X \fIuser\fR ( $1 % $2 < @"relay.cs.net" > $3 ) ); X } X.DE X.PP The example above defines the ruleset \*QEXAMPLE_RW\*U, which contains four rewriting rules. The first rewriting rule discards all tokens of an address which lie on either side of a pair of angle brackets (<>), thereby rewriting the address as the sequence of tokens contained within the angle brackets ($2). Following the address rewrite, the rule is applied again (\fIretry\fR). When the first rule fails to match the address being rewritten, the second rule is applied. X.PP The second rule simply replaces the word \*Qat\*U by the symbol \*Q@\*U. The \*Q\fInext\fR\*U action specifies that if a match is made, a rewrite is performed and matching continues at the next (or following) rule. X.PP The third rule illustrates the use of the \*Q\fIreturn\fR\*U action, which is executed if the pattern \*Q@path: usr\*U describes the current format of the address being rewritten. In this example, the \fIreturn\fR action returns the result of a call to ruleset \*QLOCAL_RW\*U, which rewrites the address \*Q<@$1>:$2\*U, where $1 and $2 are substituted with the token(s) matched respectively by \*Qpath\*U and \*Qusr\*U. X.PP The fourth (and final) rule signals a resolution (and termination) of the rewriting process if the given pattern is matched. The resolution specifies that the mailer \*Qtcp\*U will be used to deliver the message to the host X\*Qrelay.cs.net\*U. The \fIuser\fR parameter specifies the final form of the address which \fIsendmail\fR has just resolved. X.sp 2 X.PP The \fBEase\fR construct which remains to be examined is the X\fBconditional-expression\fR. The \fBconditional-expression\fR provides a method for constructing strings based on the condition that some test macro is (or is not) set. The general form begins with the concatenation of a string and a X\fBstring-conditional\fR: X.DS X \fIconcat\fR ( <quoted-string>, \fBstring-conditional\fR ) X \fIconcat\fR ( \fBstring-conditional\fR, <quoted-string> ) X.DE A \fBstring-conditional\fR assumes either of the following forms: X.DS X \fIifset\fR ( <macro-name>, <ifset-string> ) X \fIifset\fR ( <macro-name>, <ifset-string>, <notset-string> ) X.DE A \fBstring-conditional\fR of the first form evaluates to \*Qifset-string\*U if the macro \*Qmacro-name\*U has been assigned a value; otherwise it evaluates to the null string. The second form behaves similarly, except that the \fBstring-conditional\fR evaluates to \*Qnotset-string\*U, instead of the null string, if the macro \*Qmacro-name\*U has no value. X.sp 1 The following \fBconditional-expression\fR, X.DS X \fIconcat\fR ( "New ", \fIifset\fR ( city, "York", "Jersey" ) ) X.DE evaluates to the string "New York", if the macro \*Qcity\*U is set. Otherwise, the \fBconditional-expression\fR evaluates to the string "New Jersey". X.NH 2 Latest Changes The first two releases of \fBEase\fP provided a good starting point for managing \fIsendmail\fP files. However, the translation wasn't perfect. Some editing needed to be done before \fBEase\fB could be used. Bruce G. Barnett made modifications to Arnold Robbin's \fBEase\fP to sendmail convertor \fIcfc\fP and tested these changes to verify a X\fIsendmail\fP configuration fle could be translated into \fBEase\fP and back with no errors: at least for the more common versions of X\fIsendmail\fP. In case this translation is not perfect, \fBEase\fP version 3 supports the \fIasm("...")\fP command, which passes the contents of the string directly to the \fIsendmail.cf\fP file. Also - support for SunOS and Ultrix sendmail were added. New options and flags were added, and well as the \fIypmap\fP (SunOS), X\fIypalias\fP and \fIyppasswd\fP (Ultrix) functions. X.NH XEase Translation X.PP It is important to note that \fBEase\fR is translated by a stand-alone translator to the raw configuration file format. No modifications were made to the \fIsendmail\fR program itself. As a result, syntactical verification of a configuration file can be performed without invoking \fIsendmail\fR. X.PP The \fBEase\fR language is translated by invoking the \fBEase\fR translator (\fIet\fR). If the command line options include a flag understood by the C language preprocessor (cpp), \fIet\fP automatically pipes input through \fIcpp\fP. The \fBEase\fR translator may be invoked on the command line in one of four ways: X.TS center box ; l l . X\fIet\fR <options> <input-file> <output-file> [read from a file, write to a file] X\fIet\fR <options> <input-file> [read from a file, write to standard output] X\fIet\fR <options> - <output-file> [read from standard input, write to a file] X\fIet\fR <options> [read from standard input, write to standard output] X.TE X.NH Conclusion X.PP X\fBEase\fR is [ed - this information is old] currently in use at the Purdue University Computing Center. Source code for the \fBEase\fR translator (\fIet\fR) may be obtained on request by writing to: X.DS U.S. Mail: X James S. Schoner X c/o Kevin S. Braunsdorf X Purdue University Computing Center X Purdue University X West Lafayette, Indiana 47907 X XElectronic Mail: X ksb@j.cc.purdue.edu X.DE X.PP Much of the success of this project is attributable to the constant support and insight offered by Mark Shoemaker. To him, I owe a debt of gratitude. In addition, I would like to thank Kevin Smallwood, Paul Albitz, and Rich Kulawiec for their many notable suggestions and valuable insight. X.NH Acknowledgements X.PP Arnold Robbins would like to acknowledge contributions from Stephen Schaefer of Bowling Green State University, Jeff Stearns of John Fluke Manufacturing Company, Raymond A. Schnitzler of Bellcore, Andrew Partan of the Corporation for Open Systems, and Bruce G. Barnett, of General Electric. The good intentions of Rich Salz, of Bolt Beranak, and Newman, are also acknowledged. X.PP The most up to date version of \fBEase\fR should be gotten from the nearest USENET \fBcomp.sources.unix\fR archive site. X# Local variables: X# mode: nroff X# end: END_OF_FILE if test 32946 -ne `wc -c <'doc/ease.paper'`; then echo shar: \"'doc/ease.paper'\" unpacked with wrong size! fi # end of 'doc/ease.paper' fi echo shar: End of archive 5 \(of 6\). cp /dev/null ark5isdone MISSING="" for I in 1 2 3 4 5 6 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked all 6 archives. rm -f ark[1-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0 
