Path: utzoo!utgpu!cs.utexas.edu!uunet!crdgw1!barnett From: barnett@grymoire.crd.ge.com (Bruce Barnett) Newsgroups: alt.sources Subject: Ease 3.0: High Level Language for Sendmail (Part 5 of 6) Message-ID: Date: 23 Feb 91 07:18:15 GMT Sender: news@crdgw1.crd.ge.com Reply-To: barnett@crdgw1.ge.com Distribution: alt Organization: GE Corp. R & D, Schenectady, NY Lines: 948 #! /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 doc/ease.paper <<'END_OF_doc/ease.paper' X... X... $Header: /home/kreskin/u0/barnett/Src/Ease/ease/doc/RCS/ease.paper,v 2.0 1990/01/30 12:50:44 jeff Exp barnett $ X... X... $Log: ease.paper,v $ 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 Xfor Sendmail X.AU XJames S. Schoner X.AI XPurdue University Computing Center XWest Lafayette, Indiana 47907 X.AU XJeff P. Stearns X.AI XJohn Fluke Manufacturing Company XEverett, Washington 98206 X.AU XArnold D. Robbins X.AI XEmory University Computing Center XAtlanta, Georgia 30322 X.AU XBruce G. Barnett X.AI XGeneral Electric Corporate Research and Development XSchenectady, NY 12301 X.sp 2 X.I X.ce XABSTRACT X.R X.PP XThe rapid expansion of computer networks and ensuing variation among mailing Xaddress formats have made address interpretation an increasingly Xcomplex task. In the UNIX* 4.2BSD operating system, a program named X\fIsendmail\fR was introduced which provided a Xgeneral internetwork mail routing facility. This facility has significantly Xdiminished the complexity of handling address interpretation. X.PP X\fISendmail\fR's address interpretation is based on a rewriting Xsystem composed of Xa number of rewriting rules (or productions) arranged as part of a Xconfiguration file. Unfortunately, the syntactical format of a Xconfiguration file for \fIsendmail\fR is both terse and rigid, making it Xrather difficult to modify. The standard format certainly serves its Xpurpose, but, as Xthe need to change these configurations increases in frequency, a more Xreadable format (i.e., one that is similar to the format Xof modern programming languages) is required to permit reasonably Xquick modifications to the configuration. As a solution to this problem, X\fBEase\fR Xprovides a level of abstraction which eliminates most of the current Xsyntactic hindrances Xfaced by programmers who must reconfigure \fIsendmail\fR's Xaddress parsing scheme. X.PP XAs a high-level specification format, \fBEase\fR is proving to be an Xexcellent alternative to \fIsendmail\fR's cryptic Xconfiguration file syntax. The syntactic structures of \fBEase\fR Xare patterned after modern language constructs, making the language Xeasy to learn and easy to remember. The format of the address rewriting Xrule is perhaps the most significant syntactical improvement. It was Xundoubtedly Xthe most needed improvement. Nevertheless, every element of a configuration Xfile 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 XIntroduction X.PP XThe \fBEase\fR language is a high-level specification format for \fIsendmail\fR's Xconfiguration file. The motivation for its development Xwas to fulfill a goal of providing a readable and easily modifiable X\fIsendmail\fR configuration file format. \fBEase\fR fulfills this goal by Xshielding the programmer from the cryptic configuration specification required Xby \fIsendmail\fR and providing a high-level language with which the programmer Xmay specify all modifications to a configuration file. The development Xof Ease coincided with Xthe development of an \fBEase\fR translator, \fIet\fR, Xwhich translates a configuration file written Xin \fBEase\fR to an Xequivalent file of the standard format accepted by \fIsendmail\fR. X.NH XEase in Profile X.PP XAs will be seen in the next section, the syntax of \fBEase\fR is quite Xreadable and easy to learn. XIn order to acquire a relevant perspective Xon this issue, Xthe reader is advised to examine a raw configuration file for \fIsendmail\fR (the Xoutput Xof the \fBEase\fR translator, \fIet\fR, will do nicely). The raw syntax, while Xquite fitting for quick translation, can prove to be a programmer's nightmare. X.PP XIt is recommended that you learn \fBEase\fP by converting your current Xconfiguration file into \fBEase\fP format by using the program X\fIcfc\fP written by Arnold Robbins and modified by Bruce G. Barnett. X.PP XUndoubtedly, one of the more prominent features of \fBEase\fR is the ability Xto attach Xnames to address fields. When address field names are well-chosen, a distinct, Xself-documenting quality becomes a visible part of the address rewriting Xrules. Ostensibly, address field names provide a new level of semantic Xabstraction. A brief comparison of the formats can be accomplished by examining Xthe following equivalent representations of an address pattern: X.DS X user_path@host_name (\fBEase\fR format) X $+@$- (raw format) X.DE XIn the above, \*Quser_path\*U represents a field of one or more address Xtokens, and \*Qhost_name\*U represents one address token exactly. These Xtoken fields are represented by \*Q$+\*U and \*Q$-\*U in the raw format. Clearly, Xthe \fBEase\fR format is preferable, not only for increased readability, but Xstructural comprehension as well. X.PP XOther features of \fBEase\fR include ruleset naming, long identifiers for Xmacros and classes, flow-of-control structures, and free formatting. In Xaddition, it supports C language preprocessor (cpp) commands, which can be used for file inclusion Xand conditionally defined code constructs. The next section describes Xthe \fBEase\fR language in complete detail. X.NH XEase Syntax* X.FS X* \fINo attempt is made to describe the complete semantic meaning Xassociated with all of the constructs of a sendmail configuration file. Items Xnot covered in this document include the semantic distinction among rulesets, Xthe special uses of Xpre-defined macros, and the method of building configuration files. To Xobtain this information, the reader is advised to refer to Xthe Sendmail Installation and Operation Guide (SMM:7 in the 4.3 BSD XUNIX System Manager's Manual), Xby Eric Allman.\fR X.FE X.PP XAt its highest level, \fBEase\fR can be viewed as a collection of Xblock-structures, where each block begins with a keyword and is followed by Xzero or more related definitions and/or declarations. There are ten distinct Xblock types. The following is Xa list containing all ten block keywords and the block type it denotes. X.TS Xcenter; Xl 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 XIn general, X.TS Xcenter ; Xl . X X* Letters are distinguished by case, X XT{ X* An \fBEase\fR identifier is defined to be a letter, followed by zero or Xmore letters, digits, underscores (_), or dashes (-), XT} X XT{ X* A literal newline or double quotation (") character may be included in Xany quoted string by preceding the character with a backslash (\\\\\), and XT} X XT{ X* \fBEase\fR source is preprocessed by the C language preprocessor (cpp) Xif the program is executed with an option understood by cpp. XThus source comments (i.e., text enclosed by \*Q/*\*U and \*Q*/\*U) may appear Xanywhere as part of \fBEase\fR whitespace. XT} X.TE X.PP XFor notational convenience, this document specifies all reserved Xwords of the \fBEase\fR language in italics. In addition, quantities Xenclosed in angle brackets (<..>) represent arbitrary Xidentifiers, strings, or numbers. X.NH 2 XRuleset Identifier Bindings X.PP XA ruleset (a set of rewriting rules) is identified solely by an integer Xin \fIsendmail\fR's Xconfiguration file. \fBEase\fR, however, allows each ruleset to be named with Xa meaningful identifier. Since a special numeric association for each Xruleset is required by the address parsing scheme of \fIsendmail\fR, a \fIbind\fR Xblock must be present in any \fBEase\fR file which defines one or more Xrulesets. A X\fIbind\fR block consists of the keyword \fIbind\fR, followed by zero or more Xstatements of the form: X.TS Xcenter box; Xl . X = \fIruleset\fR ; X.TE XThe following example, X.sp 1 X\fIbind\fR X.PP XFINAL_RW = \fIruleset\fR 4; X.sp 1 Xspecifies that FINAL_RW, the final rewriting ruleset, is \fIsendmail\fR's ruleset Xnumber 4. X.NH 2 XMacro Definitions X.PP XA macro is an identifier which, when referenced in the text of a program, Xis replaced by its value, a string of zero or more characters. The value Xof a macro may include references to other macros, but not itself! \fISendmail\fR Xallows a maximum of 26 user-declared macros in its configuration file. In Xaddition, there are a number of pre-declared macros which have special meaning Xto \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 Xidentifier 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 Xinclude braces ({}) around the macro identifier (for delimiting purposes). X.PP XA \fImacro\fR block consists of the keyword \fImacro\fR, followed by zero Xor more statements taking either of the following forms: X.TS Xcenter box; Xl . X = "" ; X = \fBconditional-expression\fR ; X.TE XThe \fBconditional-expression\fR format will be discussed Xlater. X.sp 1 XThe following example, X.sp 1 X\fImacro\fR X.PP Xfirst_name = "James"; X.PP Xlast_name = "Schoner"; X.PP Xwhole_name = "${first_name} ${last_name}"; X.sp 1 Xdefines the macros first_name, last_name, and whole_name, where whole_name Xis the string, "James Schoner". X.NH 2 XClass definitions X.PP XA class is denoted by an identifier representing a logical grouping of zero Xor more names. Classes are used to represent the range of values a token Xmay assume in the pattern matching of an address. Further discussion on the Xuse of classes will be deferred until address fields are described. X.PP XOne identifier may be used to distinctly represent both a macro Xand class (i.e., the set of macro identifiers and the set of class identifiers Xmay form a non-empty intersection). A name, or class element, may Xbe an identifier or any quoted word. X.PP XA \fIclass\fR block consists of the keyword \fIclass\fR, followed by zero Xor more statements taking any of the following forms: X.TS Xcenter box; Xl . X = { , , , ... } ; X = \fIreadclass\fR ( "" ) ; X = \fIreadclass\fR ( "", "" ) ; X.TE XThe second and third forms cause \fIsendmail\fR to read the names of the class Xfrom the named Xfile. The third form contains a read format, which should be a \fIscanf\fR(3) Xpattern yielding a single string. X.sp 1 XThe following example, X.sp 1 X\fIclass\fR X.PP Xcampus_hosts = { statistics, engineering, chemistry, physics, physics-2 } ; X.PP Xversions = { "1.0", "1.1", "4.0", "4.2", latest-and-greatest } ; X.PP Xphone_hosts = \fIreadclass\fR ( "/tmp/phonenet.list" ) ; X.sp 1 Xdefines the classes campus_hosts, versions, and phone_hosts. X.NH 2 XSendmail option definitions X.PP XA number of options to the \fIsendmail\fR program may be specified in Xan \fIoptions\fR Xblock. For a description of the various \fIsendmail\fR options and their Xvalues, see Appendix B. X.PP XAn X\fIoptions\fR block consists of the keyword \fIoptions\fR, followed by zero Xor more statements taking any of the following forms: X.TS Xcenter box; Xl l . X = "" ; X\fIo_delivery\fR = \fBspecial-value\fR ; X\fIo_handling\fR = \fBspecial-value\fR ; X.TE XAll but two options (\fIo_delivery\fR and \fIo_handling\fR) use the first Xform. To specify an option without a value, simply assign to it the null Xstring (""). The \fBspecial-value\fR field of the second and third form Xrefers to special values (non-quoted) which are specified in Appendix B. X.sp 1 XThe 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 Xsets the options \fIo_alias\fR, \fIo_tmode\fR, and \fIo_delivery\fR. X.NH 2 XPrecedence definitions X.PP XMessage headers may contain a \*QPrecedence:\*U field describing the precedence Xof the message class. Identifiers which may appear in the precedence field of Xa message are given precedence values in a configuration file \fIprecedence\fR Xdefinition. This association will be illustrated below in an example. X.PP XA \fIprecedence\fR block consists of the keyword \fIprecedence\fR, followed Xby zero or more statements of the form: X.KS X.TS Xcenter box; Xl . X = ; X.TE X.KE XThe following example, X.sp 1 X\fIprecedence\fR X.PP Xspecial-delivery = 100; X.PP Xjunk = -100; X.sp 1 Xdefines the precedence level for the names \*Qspecial-delivery\*U and X\*Qjunk\*U. Thus, whenever the name \*Qjunk\*U appears in Xa \*QPrecedence:\*U field, the corresponding message class will be set to -100. X.NH 2 XTrusted users X.PP X\fISendmail\fR's \fB\-f\fR flag allows trusted users to override the sender's Xmachine address. Trusted users are listed in \fItrusted\fR blocks. A X\fItrusted\fR block consists of the keyword \fItrusted\fR, followed Xby zero or more sets of users taking the form: X.TS Xcenter box; Xl . X{ , , , ... } ; X.TE XThe following example, X.sp 1 X\fItrusted\fR X.PP X{ root, uucp, network } ; X.PP X{ acu, kcs, jss } ; X.sp 1 Xspecifies that the users root, uucp, network, acu, kcs, and jss can be trusted Xto use the \fIsendmail\fR flag, \fB\-f\fR. X.NH 2 XMail header definitions X.PP XThe format of the message headers inserted by \fIsendmail\fR is defined in one Xor more \fIheader\fR blocks in the configuration file. A \fIheader\fR block Xconsists of the keyword \fIheader\fR, followed by zero or more statements Xtaking any of the following forms: X.TS Xcenter box; Xl Xl Xl Xl Xl Xl Xl Xl Xl Xl Xl . X\fIfor\fR ( , , ... ) X \fIdefine\fR ( "" , \fBheader-value\fR ) ; X X\fIfor\fR ( , , ... ) { X \fIdefine\fR ( "" , \fBheader-value\fR ) ; X \fIdefine\fR ( "" , \fBheader-value\fR ) ; X . X . X} ; X X\fIdefine\fR ( "" , \fBheader-value\fR ) ; X.TE XThe first form is used to define one header for one or more mailer Xflags. The second form differs from the first in that more than one Xheader may be defined for a given set of flags. The third form is used to Xdefine a header, Xregardless of mailer flags. Refer to Appendix C for a list of \fBEase\fR Xidentifiers representing mailer flags. The header title is a simple Xstring of characters (no macro references), whereas the \fBheader-value\fR Xis a series of one or more strings and X\fBconditional-expressions\fP (discussed later). XConcatenation is implicit (as in \fIawk\fP). X.sp 1 XThe 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 Xdefines a \*QSubject\*U field for all mailers, regardless of their flags, a X\*QReturn-Path\*U field for mailers whose definition specifies Xthe flag, \fIf_return\fR, and the headers, \*QResent-Date\*U and \*QDate\*U, Xfor mailers whose definition specifies the flag, \fIf_date\fR. X.NH 2 XMailer 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, Xfollowed by zero or more statements of the form: X.TS Xcenter box; Xl . X { \fBmailer-spec\fR } ; X.TE XThe field, \fBmailer-spec\fR, is a list of zero or more of the Xfollowing attribute assignments (where successive assignment statements are Xseparated by commas): X.TS Xcenter ; Xl l Xl l Xl l Xl l Xl l Xl l Xl 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 = { , , ... } X\fISender\fR = X\fIRecipient\fR = X.TE XThe \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 XThe 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 Xdefines a mailer named \*Qlocal\*U. X.NH 2 XAddress 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 Xgeneral, \fIsendmail\fR divides an address into tokens based on a list of Xcharacters assigned as a string to the special macro \fIm_addrops\fR. These Xcharacters will individually be considered as tokens and will separate tokens Xwhen parsing is performed. X.PP XFor Xthe \fBEase\fR language, there is a distinct set of address tokens (defined Xbelow) which are used in combination to represent generic forms of Xaddresses. In Xaddition to literal address tokens, the pattern to be matched in a rewriting Xrule (often referred to as the LHS) may Xinclude 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 XA particular field type may be assigned to one or more identifiers. Each Xfield identifier is associated with (or defined to be) a field type in Xa \fIfield\fR declarations block. A \fIfield\fR declarations block consists Xof the keyword \fIfield\fR, followed by zero or more field definitions of Xthe form: X.TS Xcenter box; Xl . X\fBfield-id-list\fR : \fBfield-type\fR ; X.TE XA \fBfield-id-list\fR is a list of one or more identifiers, each separated by Xa comma. A \fBfield-type\fR, on the other hand, is a representation of Xone of the five fields Xdescribed 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 X \fImatch\fR ( 0 ) \fIin\fR X.DE XThe star in the first two forms means: "or more". Thus, the first Xform would read: "match zero or more tokens". The fourth form describes Xa field where one token is matched from an arbitrary class (class-X), whereas Xthe fifth form describes a field where one token is matched if it is not of the Xgiven class (class-X). X.sp 1 XIn addition, the Sun release 3.0 version of \fIsendmail\fR supports several Xnew pattern matching operations represented by the following forms: X.DS X \fImatch\fR ( 0 ) \fImap\fR X \fImatch\fR ( 1 ) \fImap\fR X \fImatch host\fR X.DE XThe macro \*Qmacro-identifier-X\*U should be assigned the name of the Xrelevant YP map. X.sp 1 XThe 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 Xdefines the fields anypath, recipient_host, local_site, and remote_site. X.NH 2 XAddress rewriting rules X.PP XAddress rewriting rules are grouped according to the function they perform. For Xexample, it is desirable to form a distinct group for those rewriting rules Xwhich perform transformations on recipient addresses. X.PP XSets of rewriting rules are defined in \fIruleset\fR blocks. A \fIruleset\fR Xblock consists of the keyword \fIruleset\fR, followed by zero or more Xruleset definitions of the form: X.TS Xcenter box; Xl . X { ... } X.TE XThe ruleset identifier, ruleset-id, must be defined in a \fIbind\fR block, as Xdescribed earlier. The rewriting rules have the form: X.DS X \fIif\fR ( ) X ( ) ; X.DE Xwhere match-pattern, rewriting-pattern, and match-action are described below. XAn alternative form is available: X.DS X \fIwhile\fR ( ) X ( ) ; X.DE Xwhich is somewhat more useful when the \*Qmatch-action\*U is \fIretry\fP X(see below). X.NH 3 XMatch-patterns X.PP XA match-pattern is a sequence of Ease address elements representing an Xaddress format. If the address being rewritten matches the pattern X\*Qmatch-pattern\*U, Xthen the address is reformatted using the pattern \*Qrewriting-pattern\*U, and Xthe corresponding Xaction (\*Qmatch-action\*U) is performed. The five distinct Ease address Xelements which may constitute a match-pattern are as follows: X.TS Xcenter ; Xl . X1. Field Identifiers (refer to previous section) XT{ X2. Non-alphanumeric characters (the exception is the case for literal Xdouble quotes, which must be preceded by a backslash (\\\\\) XT} X3. Macro references X4. Quoted strings ("...") X5. \fBConditional-expressions\fR (discussed later) X.TE XBelow 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 Xwhere user-id and hostname are field identifiers, and arpa_suffix is a Xuser-defined macro with the value \*QARPA\*U. X.NH 3 XRewriting-patterns X.PP XA rewriting-pattern specifies the form in which to rewrite a matched Xaddress. The seven distinct elements which may be used to form Xa rewriting-pattern are as follows: X.TS Xcenter ; Xl . X XT{ X1. Non-alphanumeric characters (the exception is the case for literal Xdouble quotes, left parentheses, or right parentheses, each of which Xmust be preceded by a backslash (\\\\\). XT} X XT{ X2. A call to another ruleset. This is used to perform rewrites Xon a suffix of the rewriting-pattern. The proper use of this Xfeature will be demonstrated by example below. XT} X X3. Quoted strings ("..."). X X4. \fBConditional-expressions\fR (discussed later). X X5. A macro reference. X XT{ X6. A positional reference in the matched address. A positional Xreference takes the form: $. For example, X$3 references the value of the third \fBEase\fR address Xelement in the matched address. XT} X XT{ X7. Canonicalized host names of the form \fIcanon\fR (), Xwhere \*Qid-token-list\*U is a list of one or more \*Qid-tokens.\*U XAn \*Qid-token\*U is a regular identifier, a quoted identifier (with Xdouble quotes), a macro reference yielding an identifier, Xa numeric internet specification (see below), Xa literal character (such as a \*Q.\*U or a \*Q[\*U), or a Xpositional reference in the matched address. The canonicalization of Xa host name is simply a mapping to its canonical (or official) form. XT} X X.TE XBelow are two sample rewriting-patterns: X.DS X $1 % $2 < @ $3 ".ARPA" > X OLDSTYLE_RW ( $1 ) X.DE XThe first form specifies an address such as a%b<@c.ARPA>, where a, b, and c Xrepresent matched identifiers or paths. The second form specifies a call to Xthe ruleset \*QOLDSTYLE_RW\*U, for old-style rewriting on the parameter X$1, which probably references the entire matched address. This will become Xclear in later examples. X.NH 3 XMatch-actions X.PP XWhen a ruleset is called, the address to be rewritten is compared (or matched) Xsequentially against the match-address of each rewriting rule. When a Xmatch-address describes the address \fIsendmail\fR is attempting to rewrite, the Xaddress is rewritten (or reformatted) using the rule's Xrewriting-pattern. Following this rewrite, the corresponding match-action Xis performed. There are four match-actions: X.TS Xcenter ; Xl l . X\fIretry\fR T{ X-a standard action which causes the rewritten address Xto be again compared to the match-address of the current rule. XT} X X\fInext\fR T{ X-an action which causes the rewritten address to be Xcompared to the match-address of the next rewriting rule of the current Xruleset. If the end of the list is reached, the ruleset returns the Xrewritten address. XT} X X\fIreturn\fR T{ X-an action which causes an immediate return of the Xruleset with the current rewritten address. XT} X X\fIresolve\fR T{ X-an action which specifies that the address has been Xcompletely resolved (i.e., no further rewriting is necessary). The X\fIresolve\fR action is described in more detail below. XT} X.TE X.PP XThe match-action, \fIresolve\fR, is special in that it terminates Xthe address rewriting altogether. The semantic structure of \fIsendmail\fR's Xrewriting scheme requires that a \fIresolve\fR action appear only in the Xruleset whose numerical binding is to the number zero. The \fIresolve\fR action Xmust specify three parameters: \fImailer\fR, \fIhost\fR, and \fIuser\fR. If Xthe \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 Xreference in the matched address. The \fIhost\fR argument may be specified as Xa 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 Xcanonicalization (as described above) or a numeric internet specification. The Xkeyword \fIhostnum\fR is used for numeric internet specifications, as in X\fIhostnum\fR ("128.61.1.1") or \fIhostnum\fR ( $2 ). The \fIuser\fR Xspecification is a rewriting-pattern, as described above. X.PP XIn general, the format of a \fIresolve\fR action will be as follows: X.DS X \fIresolve\fR ( \fImailer\fR ( ), X \fIhost\fR ( ), X \fIuser\fR ( ) ); 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 XThe example above defines the ruleset \*QEXAMPLE_RW\*U, which contains four Xrewriting rules. The first rewriting rule discards all tokens of an address Xwhich lie on either side of a pair of angle brackets (<>), thereby Xrewriting the address as Xthe sequence of tokens contained within the angle brackets ($2). Following the Xaddress rewrite, the rule is applied again (\fIretry\fR). When the first rule Xfails to match the address being rewritten, the second rule is applied. X.PP XThe second Xrule simply replaces the word \*Qat\*U by the symbol \*Q@\*U. The \*Q\fInext\fR\*U Xaction specifies that if a match is made, a rewrite is performed and Xmatching continues at the next (or following) rule. X.PP XThe third rule illustrates Xthe use of the \*Q\fIreturn\fR\*U action, which is executed if the Xpattern \*Q@path: usr\*U Xdescribes the current format of the address being rewritten. In this example, Xthe \fIreturn\fR action returns the result of a call to ruleset \*QLOCAL_RW\*U, Xwhich rewrites the address \*Q<@$1>:$2\*U, where $1 and $2 are substituted Xwith the token(s) matched respectively by \*Qpath\*U and \*Qusr\*U. X.PP XThe fourth (and final) rule signals a resolution (and termination) of the Xrewriting process if the given pattern is matched. The resolution specifies Xthat the mailer \*Qtcp\*U will be used to deliver the message to the host X\*Qrelay.cs.net\*U. XThe \fIuser\fR parameter specifies the final form of the address Xwhich \fIsendmail\fR has just resolved. X.sp 2 X.PP XThe \fBEase\fR construct which remains to be examined is the X\fBconditional-expression\fR. The \fBconditional-expression\fR provides a Xmethod for Xconstructing strings based on the condition that some test macro is (or is not) Xset. The general form begins with the concatenation of a string and a X\fBstring-conditional\fR: X.DS X \fIconcat\fR ( , \fBstring-conditional\fR ) X \fIconcat\fR ( \fBstring-conditional\fR, ) X.DE XA \fBstring-conditional\fR assumes either of the following forms: X.DS X \fIifset\fR ( , ) X \fIifset\fR ( , , ) X.DE XA \fBstring-conditional\fR of the first form evaluates to \*Qifset-string\*U Xif the macro \*Qmacro-name\*U has been assigned a value; otherwise it Xevaluates to the null string. The second form behaves similarly, except Xthat the \fBstring-conditional\fR evaluates to \*Qnotset-string\*U, instead Xof the null string, if the macro \*Qmacro-name\*U has no value. X.sp 1 XThe following \fBconditional-expression\fR, X.DS X \fIconcat\fR ( "New ", \fIifset\fR ( city, "York", "Jersey" ) ) X.DE Xevaluates to the string "New York", if the macro \*Qcity\*U is set. Otherwise, Xthe \fBconditional-expression\fR evaluates to the string "New Jersey". X.NH 2 XLatest Changes XThe first two releases of \fBEase\fP provided a good starting point Xfor managing \fIsendmail\fP files. However, the translation wasn't Xperfect. Some editing needed to be done before \fBEase\fB could be Xused. XBruce G. Barnett made modifications to Arnold Robbin's \fBEase\fP to Xsendmail convertor \fIcfc\fP and tested these changes to verify a X\fIsendmail\fP configuration fle could be translated into \fBEase\fP Xand back with no errors: at least for the more common versions of X\fIsendmail\fP. XIn case this translation is not perfect, \fBEase\fP version 3 supports Xthe \fIasm("...")\fP command, which passes the contents of the string Xdirectly to the \fIsendmail.cf\fP file. XAlso - support for SunOS and Ultrix sendmail were added. XNew 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 XIt is important to note that \fBEase\fR is translated by a stand-alone Xtranslator to the raw configuration file format. No modifications were Xmade to the \fIsendmail\fR program itself. As a result, syntactical verification Xof a configuration file can be performed without invoking \fIsendmail\fR. X.PP XThe \fBEase\fR language is translated by invoking Xthe \fBEase\fR translator (\fIet\fR). If the command line options include a flag understood by the C language preprocessor (cpp), \fIet\fP automatically Xpipes input through \fIcpp\fP. XThe \fBEase\fR Xtranslator may be invoked on the command line in one of four ways: X.TS Xcenter box ; Xl l . X\fIet\fR [read from a file, write to a file] X\fIet\fR [read from a file, write to standard output] X\fIet\fR - [read from standard input, write to a file] X\fIet\fR [read from standard input, write to standard output] X.TE X.NH XConclusion X.PP X\fBEase\fR is [ed - this information is old] currently in use at the XPurdue University Computing Center. Source code for the \fBEase\fR Xtranslator (\fIet\fR) may be obtained on request by writing to: X.DS XU.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 XMuch of the success of this project is attributable to the constant support Xand insight offered by Mark Shoemaker. To him, I owe a debt of gratitude. In Xaddition, I would like to thank Kevin Smallwood, Paul Albitz, and Rich Kulawiec Xfor their many notable suggestions and valuable insight. X.NH XAcknowledgements X.PP XArnold Robbins would like to acknowledge contributions from XStephen Schaefer of Bowling Green State University, XJeff Stearns of John Fluke Manufacturing Company, XRaymond A. Schnitzler of Bellcore, XAndrew Partan of the Corporation for Open Systems, Xand XBruce G. Barnett, of General Electric. XThe good intentions of Rich Salz, of Bolt Beranak, and Newman, Xare also acknowledged. X.PP XThe most up to date version of \fBEase\fR should be gotten from the Xnearest USENET \fBcomp.sources.unix\fR archive site. X# Local variables: X# mode: nroff X# end: END_OF_doc/ease.paper if test 32871 -ne `wc -c