In an nutshell, DELIVER is a freeware utility which can be used to pre-scan inbound VMS MAIL on a user-by-user basis. If you've got a VMS platform on the public internet, this might be to only way to de-SPAM your postmaster account.
!------------------------------------------------------------------------------- ! file: MAIL.DELIVERY ! ! notes: ! 1) lines beginning with an exclamation are ignored ! 2) each line must contain 5 or 6 phrases ! 3) phrases containing whitespace must be quoted ! 4) tests are case-insensitive ! 5) VMS wildcard characters (* and %) are supported ! 6) here are the phrase-field meanings: ! 1 2 3 4 5 6 ! <from-pattern> <to-pattern> <subject-pattern> <accept> <action> <parameter> !------------------------------------------------------------------------------- * * "* FREE *" T Q * * "*ON SALE*" T Q "FRED *" * * T Q "JIM *" * * T A JIM.LOG * * *mooses* T A MOOSE.LOG * * * O A OTHER.LOG * * * A D !-------------------------------------------------------------------------------
Line-by-Line Rule Explanations
Caveat: coded this was, if JIM sends a message containing the phrase MOOSE in the subject field, the message will be copied to two files (JIM.LOG and MOOSE.LOG)
1 DELIVER - A Programmable Message Delivery System for VMS MAIL Overview Overview 1 Overview DELIVER is an adjunct to VMS MAIL which makes it possible for incoming mail messages to be handled and processed automatically based on information provided in a user-supplied file. Different actions can be taken based on a message's address, subject or contents. These actions include delivering the message, forwarding the message or even invoking a DCL command script to perform some complex operation. Any actions taken occur immediately upon receipt of the message; the user does not need to log in for DELIVER to operate. DELIVER is modelled after the MAILDELIVERY facility of the MMDF mail system. DELIVER is, however, completely distinct from MMDF and the formats of .MAILDELIVERY files for MMDF and MAIL.DELIVERY files for DELIVER are dissimiliar. This document assumes that the reader is familiar with the VMS MAIL facility. Setting up DELIVER 2 Setting up DELIVER Users can set up DELIVER to handle their incoming mail by doing just two things: (a) Create a MAIL.DELIVERY file in their accounts' initial default directory (SYS$LOGIN). For security reasons this file MUST be located in the initial default directory -- it cannot be stored anyplace else. The format of a MAIL.DELIVERY file is described below. (b) Set their mail forwarding address for the account to "DELIVER%user", where "user" is the username associated with the user's account. The MAIL command to change or set a forwarding address is SET FORWARD. Specifying another user's name in conjunction with "DELIVER%" will perform no useful function -- mail will simply be forwarded and handled by that user's MAIL.DELIVERY file, assuming one exists. Once these two steps have been taken, DELIVER will be invoked automatically to handle all mail as it is delivered. For example, suppose user BOB wants to tell DELIVER to handle incoming messages. BOB should create a MAIL.DELIVERY file and then type: $ MAIL MAIL> SET FORWARD DELIVER%BOB MAIL> MAIL.DELIVERY file format 3 MAIL.DELIVERY file format The MAIL.DELIVERY file controls DELIVER and tells it how to handle each message. A MAIL.DELIVERY file consists of a series of directives with one directive on each line of the file. Each directive specifies how a certain kind of message is to be handled. A particular directive may or may not apply to a given message. An attempt is made to apply every directive in the MAIL.DELIVERY file to each message, thus more than one directive may apply to (and more than one action may be the result of) a single message. Any line in the file which begins with a semicolon or an exclamation point is considered to be a comment and is ignored. 2 DELIVER - A Programmable Message Delivery System for VMS MAIL MAIL.DELIVERY file format A directive line consists of the following items in order from left to right: <from-pat> <to-pat> <subject-pat> <accept> <action> <parameter> Items must be delimited by one or more spaces or tabs. Quoted strings (use double quotes, not single quotes) are allowed as single items; the quotes are removed from the items as they are read. A double quote can be obtained by using two double quotes with no space between them. This form of quote handling is consistent with that of VMS DCL. Directive applicability 3.1 Directive applicability The <from-pat>, <to-pat>, <subject-pat> and <accept> items determine whether or not the directive applies to a particular message. A string comparison is performed between the patterns <from-pat>, <to-pat> and <subject-pat> and the "From:", "To:" and "Subject:" fields of the message header respectively. The comparison is not case sensitive. The usual VMS wildcard characters ("*" and "%") can be used in the patterns. The pattern "*" will match anything. Once the comparisons have been performed, the <accept> item determines if the directive should be applied to the message. Only the first character of <accept> is significant. It should be one of the following: A - always apply this directive; ignore the results of the comparisons. X - never apply this directive; ignore the results of the comparisons. T - apply this directive if the patterns all matched. F - apply this directive if the patterns did not all match. O - apply this directive if the patterns all matched and no previous directive has been applied to the message. B - apply this directive if a pattern did not match and no previous directive has been applied to the message. E - this directive applies if all the patterns matched OR no other directive has been applied so far. Any character whatsoever is legal: Y is the same as T, N is the same as F, question mark is the same as O, Q is the same as B and all other characters are the same as X. Directives are tested in the order they appear in the MAIL.DELIVERY file. For example, suppose JIM sends a message to BOB. The subject line of the message is "Re: Mooses". BOB's MAIL.DELIVERY file contains the following lines (the function of the last two columns of each line, the <action> and <parameter> items, is described later): "FRED *" * * T Q "JIM *" * * T A JIM.LOG * * *mooses* T A MOOSE.LOG * * * O A OTHER.LOG * * * A D The first directive in the file does not apply since the message is not from FRED. The second and third directives both apply since JIM is the sender and the subject line contains the string "mooses". The fourth directive's patterns all apply, but a preceeding directive has applied, so it does not apply. The final directive applies since it would apply to 3 DELIVER - A Programmable Message Delivery System for VMS MAIL MAIL.DELIVERY file format any message. The result is that three directives apply to this message, and thus three separate actions are taken in processing the message. Note: The patterns "FRED *" and "JIM *" are useful since VMS MAIL lets users set up personal name fields which become part of the "From:" field of the message -- the personal name is enclosed in quotes and appended to the user name. Depending on personal name fields for message handling is not a good idea since some users have a tendency to change personal names frequently and without warning. The use of the space followed by an asterisk will match any personal name field a user sets up; the result is a MAIL.DELIVERY file which is insensitive to personal names. If none of the directives in the file are found to apply to the message, the message is just delivered normally. In effect, each MAIL.DELIVERY file implicitly ends with the directive: * * * O D Actions 3.2 Actions The <action> and <parameter> items specify what action is taken when a directive is applied to a message. The first character of <action> specifies what type of action to take. The legal characters for <action> and what they do are: A - append the body (or contents) of the message to a file. The <parameter> item specifies the file name. The file must already exist and the recipient must have write access to the file; DELIVER grants the user no special file access privileges. C - copy the body of the message to a file whose name is <parameter>. Write access to the directory where the file is to be created is required. D - deliver the message normally. The message is placed in the user's NEWMAIL folder. <parameter> is ignored. V - deliver the message normally using system privileges. This action is identical to action "D" above except that the "From:" field of the message header is set to match the name of the original sender instead of the name of the user. This action makes use of the DELIVER foreign mail interface in incoming mode which in turn requires that the user be fully privileged. General users should use action "D" instead. This form of delivery requires the account delivering the message to have BYPASS privilege. E - execute the specified command. The DCL command specified by <parameter> is executed. The command is executed in the environment of the recipient's own account. Any noninteractive DCL command is valid, including an indirect command file specification. Several DCL symbols can be used in the command to facilitate message processing: FROM - the message's "From:" address. TO - the message's "To:" address. SUBJECT - the message's "Subject:". CC - the message's "Cc:". QFROM - "From:" with quotes doubled. QQFROM - "From:" with quotes quadrupled. QTO - "To:" with quotes doubled. 4 DELIVER - A Programmable Message Delivery System for VMS MAIL MAIL.DELIVERY file format QQTO - "To:" with quotes quadrupled. QSUBJECT - "Subject:" with quotes doubled. QQSUBJECT - "Subject:" with quotes quadrupled. QCC - "Cc:" with quotes doubled. QQCC - "Cc:" with quotes quadrupled. MESSAGE_FILE - the name of the file containing the body of the message. MESSAGE_FILE is always fully qualified. MESSAGE_DELETE - initially set to "YES", if this symbol is set to "NO" no attempt will be made to delete MESSAGE_FILE after all actions are complete. The M <action> sets MESSAGE_DELETE to "NO" as well. The "Q" forms are useful if the symbol must be expanded inside a quoted string. The MESSAGE_DELETE flag is useful if MESSAGE_FILE has to be queued for further processing at a later time, or if one of the actions has already deleted it. F - forward the message. The message is forwarded to the address specified by <parameter>. W - forward the message using system privileges. This action is identical to action "F" above except that the "From:" field of the message header is set to match the name of the original sender instead of the name of the user. This action makes use of the DELIVER foreign mail interface in incoming mode which in turn requires that the user be fully privileged. General users should use action "F" instead. This form of delivery requires the account delivering the message to have BYPASS privilege. Q - quit; take no action and abort. If this action is taken DELIVER stops scanning the MAIL.DELIVERY file at this point. No subsequent directives will apply after this one. Use this directive with care; it is very easy to lose messages when this action is employed. K - save the command file after execution. Normally the command file created on behalf of the user is deleted automatically after execution. This action, if used inhibits this automatic deletion. L - save the batch log of the DCL commands executed by DELIVER for each message processed in the file <parameter> in the user's login directory. This option is useful for debugging MAIL.DELIVERY files and command scripts. If more than one L <action> is triggered only the last one has any effect. M - save the message file after execution of the batch job. The message file is normally deleted as the last step of processing by the batch job. This action suppresses the automatic deletion; the same effect can be obtained by setting the MESSAGE_DELETE flag to "NO". For example, suppose that BOB sends JIM a message. JIM has the following (rather complex) MAIL.DELIVERY file: ! Messages with subject "Loopback" are returned to sender "JIM *" * "Loopback" T D * * "Loopback" O F """''F$ELEMENT(0,"" "",QFROM)'""" * * "Loopback" T Q ! All other messages are logged * * * A E @LOGALL.COM 5 DELIVER - A Programmable Message Delivery System for VMS MAIL MAIL.DELIVERY file format ! Just log messages from TERRY "TERRY *" * * T Q ! Just log archive messages from myself "JIM *" * "Archives" T Q ! Save messages from BOB in a special file "BOB *" * * T A BOB.LOG ! Then deliver anything that gets this far * * * A D JIM's LOGALL.COM contains the following commands: $ from == "From: " + from $ to == "To: " + to $ subject == "Subject: " + subject $ open/append/error=make_one x message.log $ next: $ write x "" $ write x from $ write x to $ write x subject $ write x "" $ close x $ append 'message_file' message.log $ exit $ ! $ make_one: $ create message.log $ open/append x message.log $ goto next If the subject line of BOB's message is not the string "Loopback", the message will be logged with a header in the file MESSAGE.LOG (located in JIM's SYS$LOGIN directory), appended to the file BOB.LOG without any header and delivered to JIM's NEWMAIL folder. If subject line is the string "Loopback", JIM's MAIL.DELIVERY file will bounce the message right back to BOB. As another example, if TERRY sends a message to BOB, the message is logged only in BOB's MESSAGE.LOG file; BOB never receives any notification that the message arrived. Apparently TERRY never says anything of importance to BOB. It is clear that the ability to execute an arbitrary set of DCL commands in response to a message is a very powerful tool. It must, however, be used with care, since processing is initiated whenever a message is received and operates in a completely unattended environment. Implementation 4 Implementation Warning: The details in this section are technical in nature and are probably of interest only to system managers or programers. DELIVER is implemented as foreign interface to VMS MAIL. DELIVER is activated when a message addressed to "DELIVER%user" is sent. MAIL invokes DELIVER by loading the DELIVER_MAILSHR shareable image and calling a set of routines DELIVER provides to interface to MAIL. DELIVER does the following: 6 DELIVER - A Programmable Message Delivery System for VMS MAIL Implementation (1) The $GETUAI system service is used to validate the address. DELIVER will signal an error if an attempt is made to deliver mail to someone who does not exist. The recipient's default directory is retrieved to use when opening the recipient's MAIL.DELIVERY file. (2) DELIVER checks to see that the recipient has a MAIL.DELIVERY file in his or her home directory. If this file does not exist DELIVER signals an error. If the file exists it is read and parsed. (3) DELIVER writes the body of the message to a temporary file in the recipient's home directory. (4) A command file is constructed to complete the delivery process. This file is also created in the recipient's home directory. The directives previously read from the MAIL.DELIVERY file are compared with the message. Any directories that match cause commands to be written to the command file that implement the requested action. (5) After the list of directives is exhausted DELIVER checks to see that at least one directive caused an action to be taken. If none did, DELIVER writes a default action command to deliver the message normally into the command file. Commands to delete the message file (unless the MESSAGE_DELETE flag is set to "NO" by one of the actions) and the command file itself are written to the command file and the command file is closed. (6) The command file is queued to the batch queue DELIVER_BATCH for processing. (SYS$BATCH is used if DELIVER_BATCH does not exist.) The file is queued so that it will execute just as if the recipient had submitted it for processing from his or her own account. (Note: This requires CMKRNL privilege.) Once the command file is submitted DELIVER tidies up, deallocating any storage allocated for directive lists, and returns control to MAIL. The other half - using DELIVER to send messages 5 The other half - using DELIVER to send messages Every foreign protocol interface to VMS MAIL has two parts -- one which deals with received messages (the outgoing part) and another which transfers messages to VMS MAIL (the incoming part). All the functions of DELIVER described up to this point are part of the outgoing part. Rather than include a null incoming handler in DELIVER, it was decided to add a general-purpose message queueing system that might be useful both as a simple interface to VMS MAIL and as an example of how this part of a foreign protocol interface is constructed. The message enqueueing part of DELIVER can be used only by fully privileged users since it allows arbitrary settings of "From:" addresses and so could violate MAIL security in the hands of general users. Thus, this mechanism is of little interest to most users. A message is sent via DELIVER to VMS MAIL with a command of the form: $ MAIL/PROTOCOL=DELIVER_MAILSHR - /SUBJECT="subject" message-file to-list where "subject" is the subject line for the message, "message-file" is the name of a file containing the text of the message and to-list is a list of user names (delimited by commas) the message is to be sent to. The "From:" address for the message is not specified as part of the command line; it is obtained instead by translating the DCL symbol DELIVER_FROM. No checking is done on the validity of the translation. This mode of MAIL 7 DELIVER - A Programmable Message Delivery System for VMS MAIL The other half - using DELIVER to send messages operation roughly corresponds to the "trusted submit" mode available in MMDF-II. The CC: line is obtained from the translation of the DCL symbol DELIVER_CC. No CC: line is used if this symbol is not defined. DELIVER sets two DCL symbols to indicate the success or failure of its attempt to deliver the message. The symbol DELIVER_STATUS will contain the status code of the last error that occurs while the message is being sent. If DELIVER_STATUS indicates that some sort of failure occurred, the symbol DELIVER_MESSAGE will contain the text form of the error message. In the event of multiple errors while sending (e.g. two addresses in the "to-list" are illegal) only the more recent error status information will be returned. This interface is somewhat crude but should prove adequate for most applications. The incoming side of DELIVER is used by the outgoing side to process the "V" and "W" actions, which correspond to "privileged deliver" and "privileged forward" operations respectively. Installation 6 Installation If you have received DELIVER as part of PMDF, it will be installed as part of the PMDF installation procedure. If you received DELIVER as a separate piece of software, you can install it as follows: (1) Unpack the various files that comprise DELIVER into an otherwise empty directory. (2) Build DELIVER using the BUILD.COM procedure provided with the distribution. This should produce two executable files, DELIVER_MAILSHR_V4.EXE and DELIVER_MAILSHR_V5.EXE. (3) Move the DELIVER executables to whatever directory they will be run from. (4) Edit the file DELIVER_STARTUP.COM to point at the directory you've chosen for the DELIVER executables. This file should then be copied to SYS$COMMON:[SYSMGR] and set up to be run at system boot time. You should also execute this command file by hand to start up DELIVER. (5) Set up a batch queue DELIVER_BATCH for DELIVER to use. This step is optional -- DELIVER will use the default batch queue SYS$BATCH if DELIVER_BATCH does not exist. If you like, you can define DELIVER_BATCH as a system logical name to point at some other queue for DELIVER to use. (6) DELIVER should now be ready to use. 8 DELIVER - A Programmable Message Delivery System for VMS MAIL Availability Availability 7 Availability DELIVER is distributed as part of the PMDF-822, the Pascal Memo Distribution Facility. PMDF-822 can also be obtained from: Ned Freed (email@example.com) The PMDF Project Computing Services Harvey Mudd College Claremont, CA 91711 (714) 621-8006 The latest version of DELIVER may be obtained independently from: Dick Munroe Doyle, Munroe Consultants, Inc. 267 Cox St. Hudson, Ma. 01749 (508) 568-1618 (FAX) (508) 562-1133 firstname.lastname@example.org or from a VMSNET.SOURCES archive site near you. Please write, call or send e-mail for more information. Documentation 8 Documentation The file DELIVER.RNO contains the only documentation for DELIVER. (You are reading a version of it right now.) DELIVER.RNO can be used either to produce a printed document or a VMS help file entry. Use the command $ RUNOFF/NOBOLD/NOUNDER/OUT=DELIVER.HLP DELIVER.RNO to create the online help entry. DELIVER.HLP can be inserted into any VMS help library. Use the command $ RUNOFF/OUT=DELIVER.MEM/VAR=MANUAL DELIVER.RNO to create a document for printing. Bugs 9 Bugs There are no known bugs in DELIVER at this time. However, there are a few minor nuisances which users should be aware of: (1) DELIVER changes the "From:" address of any message it delivers or forwards to the address of the owner of the MAIL.DELIVERY file. The original "From:" address is not lost entirely -- it is merged into the subject line of the message. This problem arises due to VMS MAIL's lack of distinction between a transport address and a header address -- DELIVER has to set the "From:" address to itself so that authorization code in other mailers will see it. Privileged users can circumvent this restriction by using the "V" and "W" actions, but no such mechanism is available to general users. (2) It is difficult to debug MAIL.DELIVERY files since there is no way to watch deliver process the file except by enabling debug code in DELIVER (which is not an option normal users can exercise). However, the "L" <action> can be used to create a log file of the DCL commands DELIVER executes on behalf of the user 9 DELIVER - A Programmable Message Delivery System for VMS MAIL Bugs when processing a message: ! Log commands executed in a file unconditionally * * * A L DELIVER.LOG * * * A E @DO_SOMETHING.COM Such log files are always placed in the user's home directory. Also note that output from command files invoked by DELIVER can be captured in a file by using the /OUTPUT qualfier: ! Execute a command file with logging * * * A E @DO_SOMETHING.COM/OUTPUT=DO_SOMETHING.LOG DELIVER does watch for users sending messages to themselves and then tries to be somewhat more informative than is usual about any errors it finds in MAIL.DELIVERY files. (3) It is possible to enable debugging code within DELIVER by defining either or both of these logical names: DELIVER_DEBUG_IN which enables debugging output for mail input processing and DELIVER_DEBUG_OUT which enable debugging output for mail output processing. This allows you to observe the inner workings of DELIVER interactively. (4) Enabling the COPY_SELF feature in MAIL while DELIVER is also set to send messages to the user's mailbox may send MAIL into an infinite loop. The COPY_SELF facility should not follow forwarding addresses; unfortunately it does do this in the present implementation. Thus a message is sent by DELIVER to the user's mailbox, which in turn re-activates DELIVER, which sends the message to the user's mailbox, and so on. (5) Lines in all files processed by DELIVER are limited to, at most, 256 characters. Individual directive items as well as message "From:", "To:" and "Subject:" lines are also limited to 256 characters. DELIVER truncates these lines to this length. This limit can be changed by altering the constant PARAMETER_SIZE in DELIVER.PAS. However, these lines will still be truncated in the DCL DELIVER produces since DCL is also limited to lines containing no more than 256 characters. 10