OpenVMS Notes: DELIVER
- The information presented here is intended for educational use by qualified OpenVMS technologists.
- The information presented here is provided free of charge, as-is, with no warranty of any kind.
Edit: 2009-10-03
DELIVER (introduction)
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.
DELIVER (how-to)
System Manager Actions (do once per system)
- download DELIVER from the HP OpenVMS freeware site:
http://h41379.www4.hpe.com/openvms/freeware/index.html- Freeware V4 supports both VAX and ALPHA
- Freeware V8 disc-1 supports VAX, ALPHA and Itanium
- unpack the DELIVER download; read the documentation; install it
User Action (each user wishing to use DELIVER must do this)
- each user must a create a file in their home directory (SYS$LOGIN) titled MAIL.DELIVERY
- enter VMS MAIL then forward your account to the DELIVER like so:
set forward DELIVER%JOE_HACKER (assumes your account name is "JOE_HACKER") - if something goes wrong, you can quickly disable forwarding like so:
set noforward
DELIVER Template
!------------------------------------------------------------------------------- ! 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
- if the subject field contains the phrase " FREE " then Quit (thus discarding the mail message; all subsequent tests are ignored)
- if the subject field contains the phrase "ON SALE" then Quit (thus discarding the mail message; all subsequent tests are ignored)
- if the from field begins with "FRED " then Quit (thus discarding the mail message; all subsequent tests are ignored)
- if the from field begins with "JIM " then Append the mail message to the file JIM.LOG then continuing processing MAIL.DELIVER
- if the subject field contains the phase "MOOSES" then Append the mail message to the file MOOSE.LOG (then continue processing MAIL.DELIVER)
- if all tests fired (and they would because of three wildcards) but no previous rule-lines have fired, then append the message to file OTHER.LOG
- If we get here (we have never Quit) then Always Deliver this message normally (to the user's NEWMAIL folder)
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)
DELIVER Plain-text docs for user file: MAIL.DELIVERY (1994)
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 (ned@ymir.bitnet)
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
munroe@dmc.com
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
External Links
- http://h41379.www4.hpe.com/openvms/freeware/index.html
- http://www.process.com/openvms/ (more freeware links)
- ftp://ftp.process.com/vms-freeware/fileserv/
- ftp://ftp.process.com/vms-freeware/fileserv/deliver.zip (this version only supports VAX and Alpha)
Back to HomeNeil Rieck
Waterloo, Ontario, Canada.