This chapter describes how to configure the TCPware SMTP (Simple Mail Transport Protocol) server to send and receive electronic mail.
The chapter also includes information about the Internet Message Access Protocol (IMAP) and the Post Office Protocol (POP).
If you are running PMDF or another mail system that provides its own SMTP support, refer to that mail system's documentation.
TCPware’s SMTP configuration is stored in the START_SMTP.COM and START_SMTP_LOCAL.COM startup command procedures. TCPware provides the MAIL-CONFIG utility for editing these files. You can invoke the utility with the TCPWARE CONFIGURE /MAIL command.
Configuring SMTP:
For detailed information on the following parameters, refer to the
TCPware for OpenVMS Management Guide.
Do you want to use the SMTP Mail Transfer Agent? [NO]: Y
One user on this system must act as the local postmaster. This person
will receive mail sent to the postmaster. The person's username must
always be valid while SMTP is operating.
Enter the username of the local postmaster [SYSTEM]: RETURN
Port for SMTP to use [25]? RETURN
Do you want to enable the SMTP RFC2789 MIB [No]? Y
Do you want to enable SMTP
accounting [No]? Y
Name of the host that will run the accounting collection program: BIGBOOTE.EXAMPLE.COM
Port number that accounting collection program listens on: 2222
For further configuration options, please see the procedure described in
the TCPware for OpenVMS Installation & Configuration Guide to configure
SMTP.
The last two questions are optional depending on the value of the one before them.
After using these configuration utilities, stop and restart the mail queues with @TCPWARE:START_SMTP.COM to update the OpenVMS cluster or with @TCPWARE:START_SMTP_LOCAL.COM to update the local host only.
If you have implemented virtual domains (that is, your system receives mail for multiple domain names), you must do the following:
· Create the file TCPWARE:SMTP_HOST_ALIASES. and specify, one per line, all the virtual domains for which this node serves as mail processor.
· Define the logical TCPWARE_SMTP_ALLOW_VIRTUAL_DOMAIN as a system-wide, executive-mode logical.
The file TCPWARE:SMTP_LOCAL_LOGICALS.COM can be created to define all local SMTP-related logicals. It executes each time SMTP starts. The available SMTP logicals are:
|
TCPWARE_LOCALDOMAIN |
Specifies the default local domain name to be used when building To: addresses on outgoing messages.
For example, to have messages sent to SMTP%“Joe@bigboote” to be delivered to SMTP%“Joe@bigboote.example.com”, TCPWARE_LOCALDOMAIN would be defined as bedrock.com. |
|
TCPWARE_NAMESERVERS |
List of IP addresses for DNS lookups. |
|
TCPWARE_SMTP_A1_NAME |
Used in forming the username portion of return addresses for ALL-IN-1 users. |
|
TCPWARE_SMTP_ACCEPT_UNIX_LF |
Tells the SMTP agents to accept lines sent by some UNIX systems that are terminated with a linefeed only (instead of the proper carriage-return, linefeed combination). |
|
TCPWARE_SMTP_ALLOW_USER_FROM |
Allows users
to override their From: address on outgoing mail by specifying |
|
TCPWARE_SMTP_ALLOW_VIRTUAL_DOMAIN |
Allows the use of virtual domains in TCPware SMTP environment. Without this logical defined, incoming aliases are assumed to be local addresses only. If your system supports multiple virtual domains and uses in the alias file to reroute traffic based on those domains, you must define this logical. |
|
TCPWARE_SMTP_AM_DOMAIN |
Domain name used when forming return addresses for ALL-IN-1 users. |
|
TCPWARE_SMTP_AM_NAME |
Used in forming the username portion of return addresses for ALL-IN-1 users. |
|
TCPWARE_SMTP_APPEND_FORWARDER_TO_MX |
Specifies that the default SMTP forwarder, if defined, is appended to the end of an MX list for a target host when delivering outgoing mail. |
|
TCPWARE_SMTP_BATCH_QUEUE |
Points to the TCPware SMTP queue. |
|
TCPWARE_SMTP_DECNET_DOMAIN |
Specifies a DECnet name used in the creation of return addresses. |
|
TCPWARE_SMTP_DELIVERY_RECEIPTS |
Enables or disables delivery receipts (value is TRUE or FALSE). |
|
TCPWARE_SMTP_DISABLE_DELIVERY_ RECEIPT_DISCLAIMER |
When deliver receipts are enabled, a disclaimer is included in all such receipts telling the sender that the message has been delivered, but not necessarily read. Defining this logical prevents the disclaimer from being included. |
|
TCPWARE_SMTP_DISABLE_FOLDER_ |
Disables TCPware SMTP's ability to deliver messages to user-defined folders in their VMS Mail files. |
|
TCPWARE_SMTP_DISABLE_OPTYPE_ SANITY_CHECK |
If this logical is defined then the SMTP symbiont will default to MAIL for the operation not specified in the files in the queue. |
|
TCPWARE_SMTP_DISABLE_PSIMAIL |
If defined, causes mail sent to PSI% users to be returned with NOSUCHUSER. |
|
TCPWARE_SMTP_ENVELOPE_FROM_ |
Specifies the host name to be used in the SMTP envelope MAIL FROM: line. If not defined, the default system host name is used. |
|
TCPWARE_SMTP_FORWARDER |
Specifies the domain name of the system to which all outgoing mail is forwarded for further delivery. |
|
TCPWARE_SMTP_FROM_HOST |
Specifies the local hostname used when forming From: address on outgoing messages. If this logical is not defined, the system host name is used. |
|
TCPWARE_SMTP_HEADER_ORG |
Specifies the text for an Organization: header in outgoing mail. |
|
TCPWARE_SMTP_HEADER_RETURN_ RECEIPT_TO |
Generates a
Return-Receipt-To: header in outgoing mail. Requires the TCPWARE_SMTP_RETURN_RECEIPT_ |
|
TCPWARE_SMTP_HEADER_SYS |
Specifies the text for a System: header in outgoing mail. |
|
TCPWARE_SMTP_HOST_ALIAS_FILE |
Points to the file containing a list of all the host names that should be considered local for this node for incoming mail delivery. |
|
TCPWARE_SMTP_HOST_NAME |
Specifies all the local host names for this node. Used to specify all virtual domains handled by this node. Alternatively, the node names can be stored in the file TCPWARE:SMTP_HOST_ALIASES. |
|
TCPWARE_SMTP_INCOMING_MSGSIZE_LIMIT |
This logical can be defined to cause the SMTP server to reject messages that are larger than a desired size. The defined values are: S - 1 MB M - 10 MB L - 100 MB X - 1000 MB
|
|
TCPWARE_SMTP_LOG |
Specifies the output filename. If not defined, the name defaults to TCPWARE:TCPWARE_SMTP_LOG.queuename. |
|
TCPWARE_SMTP_MAXIMUM_822_TO_LENGTH |
Sets the maximum length of the RFC822 To: header line when sending outgoing mail. The default is 1024. The range can be set from 256 to 65535. |
|
TCPWARE_SMTP_MRGATE_NAME |
Specifies the name of the Message Router gateway. |
|
TCPWARE_SMTP_NON_LOCAL_ |
Specifies the name of a forwarder system for non-local outgoing mail. |
|
TCPWARE_SMTP_NO_USER_REPLY_TO |
Disallows the use of user-defined Reply-To: headers in outgoing mail. |
|
TCPWARE_SMTP_POSTMASTER |
Specifies the address of the system-wide postmaster. |
|
TCPWARE_SMTP_REJECT_INVALID_DOMAINS |
Tells the SMTP server to reject mail from domains whose names and addresses cannot be resolved in a reverse lookup. |
|
TCPWARE_SMTP_REPLY_TO |
Specifies an address for a Reply-To: header in outgoing mail. |
|
TCPWARE_SMTP_RESENT_HEADERS |
Causes the inclusion of "Resent-*" headers in mail forwarded from a VMS Mail account using SET FORWARD in VMS Mail. |
|
TCPWARE_SMTP_RETRY_INTERVAL |
Specifies the retry interval for messages waiting for an attempted redelivery. The time is specified as a delta time. |
|
TCPWARE_SMTP_RETURN_INTERVAL |
Specifies the amount of time a given message delivery should be retried before giving up and bouncing the message back to the sender. The time is specified as a delta time. |
|
TCPWARE_SMTP_RETURN_MSG |
Specifies an input filename for the return message SMTP sends when a mail message bounces. |
|
TCPWARE_SMTP_RETURN_RECEIPT_TO_ HEADER_ENABLE |
Enables the
Return-Receipt-To: header if the TCPWARE_SMTP_HEADER_RETURN_ |
|
TCPWARE_SMTP_SEND_CLASS |
Specifies the VMS broadcast class for "New mail" notifications. The default is USER16. |
|
TCPWARE_SMTP_SERVER_DISABLE_VRFYEXPN |
Disables the VRFY and EXPN commands in
bitmask format to the SMTP server. |
|
TCPWARE_SMTP_SERVER_LOG |
Enables debug logs for the SMTP server. |
|
TCPWARE_SMTP_SERVER_RCPT_CHECK_HOST |
The host name to be used in checking for local host when passing messages through the reject rules. |
|
TCPWARE_SMTP_SERVER_REJECT_FILE |
Points to the file containing the rejection rules. |
|
TCPWARE_SMTP_SERVER_REJECT_INFO |
Specifies the level of OPCOM messages generated by the rejection rules for incoming SMTP mail. If not defined, no messages are generated. |
|
TCPWARE_SMTP_SUPPRESS_VENDOR |
Suppresses the vendor’s name in the SMTP server welcome banner. Define this logical to hide the fact that the system is a VMS system running TCPware. |
|
TCPWARE_SMTP_SYMBIONT_LOG |
Enables debug logs for the SMTP symbiont. |
|
TCPWARE_SMTP_SYMBIONT_PURGWS_TIMER |
Specifies how often the SMTP symbiont purges its working set to free up unneeded memory. The time is specified as a delta time. |
|
TCPWARE_SMTP_WINDOW_SIZE |
Specifies the window size used in TCP connections when delivering mail. |
|
TCPWARE_VMSMAIL_HEADER_CONTROL |
Specifies how many RFC822 headers are included in mail delivered to VMS Mail users. Values can be ALL, MAJOR, and NONE. |
|
TCPWARE_VMSMAIL_LOCASE_USERNAME |
Lowercases the username portion of outgoing addresses. |
|
TCPWARE_VMSMAIL_NO_EXQUOTA |
Delivers incoming mail to local VMS Mail users without using EXQUOTA. |
|
TCPWARE_VMSMAIL_REPLY_CONTROL |
Specifies which header to use to determine the sender of a message ("Reply-To:" or "From:"). |
|
TCPWARE_VMSMAIL_USE_RFC822_TO_HEADER |
Specifies that addresses in the RFC822 To: and CC: headers should make up the VMS Mail To: and CC: headers. |
The SMTP server supports mail delivery to folders other than the NEWMAIL folder. The folder names are restricted to UPPERCASE characters only, the pound sign (#), and the underscore (_). Use of the comma (,) in a folder name causes an error. Mail addressed to user+folder@host is delivered to the specified folder. You can disable this mechanism by defining the system-wide logical name TCPWARE_SMTP_DISABLE_FOLDER_DELIVERY.
The current release of SMTP supports alias file extensions that request mail delivery to a file or specify addresses in a separate file. You must use the SMTP aliases file, specified with TCPWARE CONFIG/MAIL, to list all of these new mail delivery mechanisms. The default is TCPWARE:SMTP_ALIASES. The syntax for these aliases follows the form of those described in Configuring Mail Aliases found later in this chapter. It is necessary to use the colon and semicolon in the command lines as shown in the examples.
|
<device:[directory]address.list |
Delivers mail to the list of addresses in the specified file.
alias1 : "<filespec" ; |
|
| device:[directory]procedure.com parameter(s) |
Submits the specified command procedure to the queue identified by the logical name TCPWARE_SMTP_BATCH_QUEUE, SYS$BATCH by default. The first parameter (P1), passed to the submitted procedure, is always the name of a temporary file containing the mail message that the procedure must delete. Any parameter(s) specified in the alias file are passed to the submitted procedure in a single string as its second parameter (P2).
alias2 : "|filespec p2 p3" ; |
|
>device:[directory]mail.file |
Appends mail to the specified file. If no filetype is specified, the default is .yyyy-mm (yyyy and mm are set to the current year and month, respectively).
alias3 : ">filespec" ; |
The SMTP server supports a set of rules for rejecting mail messages received by itself based on the mail header contents or any combination of MAIL FROM, RCPT TO, and source IP address values. Mail matching the criteria can be quietly ignored or rejected with a message to the SMTP client or delivered to an address rewritten according to the rule specification. This capability can be useful for controlling SPAM and preventing your system from being used as a mail relay.
The file TCPWARE:SMTP_SERVER_REJECT. contains the rejection and rewrite rules. You may specify an alternate file via the logical name TCPWARE_SMTP_SERVER_REJECT_FILE. A rejection file line of the form #include device:[directory]reject.file temporarily suspends processing of the current file and begins processing of the specified file. Rejection files can be nested to arbitrary depth. Comments may be included in rejection files by placing any of the characters ; or ! or # in the first column of a line.
The following is a sample rejection file:
!
! This is a sample reject file for the company EXAMPLE.COM.
!
! This file is processed sequentially. In other words, processing ends on
! the first rule that the message applies to. So if you have a wildcard
! accept at the top of this file, then no other rules will be processed.
!
! Entries can have one of the following formats:
!
! from_user [from_ip to_user action action-data]
!
! :rfc822 header
!
! Wildcards can be used in FROM_USER, FROM_IP, and TO_USER. ACTION is the
! reject action, which is one of:
!
! n Don't reject, but rewrite TO address to be ACTION-DATA.
! If ACTION-DATA is blank then we simply deliver to TO_USER.
!
! y Reject and use optional ACTION-FIELD as a rejection message
! format that can contain up to three %s formatting
! designators for mail from, mail to, and local domainname.
!
! q Reject quietly -- don't inform Sending SMTP Client that
! message will be discarded. If only FROM_USER is specified
! other fields default to FROM_IP=*, TO_USER=*, and ACTION=n.
!
! Don't rewrite or reject any mail to "postmaster*"
!
! * * postmaster* n
!
! Accept all messages with MAIL FROM:<> (bounce messages)
! This rule is commented out because you probably don't want it, although
! We're _supposed_ to always accept it. This is the main method relay
! attacks use, by always saying they are from <> to take advantage of
that
! RFC hole.
!
! <> * * n
!
! Reject anything with a Message-ID that appears to have originated from
! cyberpromo.com or nowhere.com
!
:Message-ID: <*@cyberpromo.com>
:Message-ID: <*@nowhere.com>
!
! Reject mail from well-known SPAM sites with sample non-standard error
! messages.
!
<*answerme.com> * * y "Spam from <%s> rejected"
<*cyberpromo.com> * * y "Spam from <%s> to <%s>
rejected"
<*pleaseread.com> * * y "Spam rejected;%.0s%.0s Contact
postmaster@%s"
!
! Disallow percent-hacks (e.g, joe%somewhere.com@example.com)
!
* * *@*@*example.com y "No forwarding-path relaying
allowed"
!
! Disallow "!" UUCP hacks (e.g. somewhere.com!joe@example.com)
!
* * *!* y "No UUCP relaying allowed"
!
! Rewrite all mail to webmaster to the postmaster
!
* * webmaster@*example.com n postmaster@example.com
!
!
! Disallow relaying through our mailer, and only allow users on our
! networks to claim to be from our company (example.com)
!
* * *@example.com n
* * *@daisy.example.com n
* * *@[10.0.0.1] n
!
<*example.com> 10.0.0.* * n
<*example.com> 10.115.140.* * n
<*example.com> 10.115.141.* * n
!
! Allow our internal systems to bounce mail out.
!
<> 10.0.0.* * n
<> 10.115.140.* * n
<> 10.115.141.* * n
!
! If a message has slipped through all the tests above, then we want to
! reject it, as they are either relaying through us or it's not a valid
! MAIL FROM.
!
*@* * *@* y "no relaying through this site"
* * *@* y "missing domain name in MAIL FROM"
!
!end of sample file
Mail rejection rules have two formats:
· :RFC822_header pattern
This format causes rejection of any mail in which a line with the specified header matches the given pattern. The following rejection message is sent to the client:
554 Message rejected due to header contents
|
Note: Use caution when rejecting mail based on header contents. No other criteria are considered during rejection processing.
|
· from_user ip_address to_user action action_data
This format causes rejection or alternate delivery of all messages that match all of the patterns specified. The action item can be as follows:
|
n |
Means do not reject the mail, but deliver it to the address specified as the action_data. If action_data is not specified, deliver the message to its intended recipient. |
|
y |
Means reject the mail, sending the action_data string to the SMTP client as a rejection message. The action_data item is used as a format string and may contain from one to three %s formatting designators to include the from_user, the to_user, and the SMTP server name, in that order. If action_data is missing, the default rejection message is
553-Mail to user not allowed; |
|
q |
Means reject the mail, but do not give the SMTP client any indication that it has been rejected. Use caution when rejecting messages quietly. |
Each of the pattern specifications pattern, from_user, ip_address, and to_user may contain the OpenVMS * and % wildcard characters.
You can represent from_addr expressions in the SMTP_SERVER_REJECT filter with the <> syntax. So, *@*domain.com and <*@*domain.com> are the same expression. To allow all bounce mail in without the filter rules being applied, add the following line to the top of your SMTP_SERVER_REJECT file:
<> * * n
(Accept any mail with a MAIL FROM: of <>)
When comparing the RCPT TO: address with the SMTP_SERVER_REJECT file expressions, any % signs in the RCPT TO: address are changed to @. You can write filter rules in the SMTP_SERVER_REJECT files that can match against forward-path relays. You can add the rule of
* * *@*@localdomain y “No forward-path relaying allowed”
to your SMTP_SERVER_REJECT file above the rules that accept mail with the destination of your domains. RCPT TO.: addresses will replace any % character with the @ character for matching purposes only so you can filter with *@*@*-type rules. So, RCPT TO.:<xxx%yyy@zzz> is changed to xxx@yyy@zzz. You can use the logical name TCPWARE_SMTP_SERVER_REJECT_INFO to control debug and informational OPCOM messages produced during rejection processing. You should define it to have some non-zero value to request OPCOM messages. The following values may be combined to control message quantity and content:
|
Values |
To show... |
|
1 |
mail rejected due to actiony |
|
2 |
rewritten addresses (actionn with action_data) |
|
4 |
the reject message sent to the remote system |
|
8 |
configuration file parsing |
|
16 |
non-written addresses (actionn and no action_data) |
|
32 |
mail rejected due to actionq |
|
64 |
mail rejected due to header rules |
The value 65 is appropriate for auditing rejection activity.
The remainder of this chapter describes the configuration tasks.
Partial support for RFC 2789 (Mail Monitoring MIB) has been added to SMTP. This feature can be enabled from @TCPWARE:CNFNET SMTP. Information is maintained only while the service is active. The following items from the Mail Monitoring MIB are available in the enterprises.105.3.25 MIB:
|
MtaReceivedMessages |
The number of messages received since Message Transfer Agent (MTA) initialization. (enterprises.105.3.25.1) |
|
MtaStoredMessages |
The total number of messages currently stored in the MTA. (enterprises.105.3.25.2) |
|
MtaTransmittedMessages |
The number of messages transmitted since MTA initialization. (enterprises.105.3.25.3) |
|
MtaReceivedVolume |
The total volume of messages received since MTA initialization, measured in kilo-octets. (enterprises.105.3.25.4) |
|
MtaStoredVolume |
The total volume of messages currently stored in the MTA, measured in kilo-octets. (enterprises.105.3.25.5) |
|
MtaTransmittedVolume |
The total volume of messages transmitted since MTA initialization, measured in kilo-octets. (enterprises.105.3.25.6) |
|
MtaReceivedRecipients |
The total number of recipients specified in all messages received since MTA initialization. (enterprises.105.3.25.7) |
|
MtaStoredRecipients |
The total number of recipients specified in all messages currently stored in the MTA. (enterprises.105.3.25.8) |
|
MtaTransmittedRecipients |
The total number of recipients specified in all messages transmitted since MTA initialization. (enterprises.105.3.25.9) |
|
MtaSuccessfulConvertedMessages |
The number of messages that have been successfully converted from one form to another since MTA initialization. (enterprises.105.3.25.10) |
|
MtaFailedConvertedMessages |
The number of messages for which an unsuccessful attempt was made to convert them from one form to another since MTA initialization. (enterprises.105.3.25.11) |
|
MtaLoopsDetected |
A message loop is defined as a situation where the MTA decides that a given message will never be delivered to one or more recipients and instead will continue to loop endlessly through one or more MTAs. This variable counts the number of times the MTA has detected such a situation since MTA initialization (enterprises.105.3.25.12) |
This information can be displayed with the NETCU SHOW SNMP MIB_VARIABLE command. See the SHOW SNMP command in the TCPware NETCU Command Reference.
This feature requires the SNMP Agent X functionality; to use this SNMP must be configured to have Agent X service enabled, and to allow 127.0.0.1 to be an AGENTX_PEER. See Chapter 7 for more information on SNMP and Agent X.
The file TCPWARE:SMTP_LOCAL_LOGICALS.COM can be created to define all local SMTP-related logicals. It executes each time SMTP starts.
TCPware can record accounting information from services that have been enabled. Currently this includes FTP and SMTP. The accounting information includes information about when a network session took place and how much data was transferred. The accounting facility is enabled from @TCPWARE:CNFNET ACCOUNTING and reads TCPWARE:ACCOUNTING.CONF for additional configuration information. The format of the accounting records is described in TCPWARE_ROOT:[TCPWARE.EXAMPLES]ACCOUNTING.H
A sample program using this is in TCPWARE_ROOT:[TCPWARE.EXAMPLES]ACC_DUMP.C
To configure session accounting, follow these steps:
1. Edit the accounting configuration file, as described in the next section.
2. Invoke the CNFNET procedure by entering the following command at the DCL prompt:
$ @TCPWARE:CNFNET ACCOUNTING
3. Restart TCPware or accounting.
The accounting configuration file is TCPWARE:ACCOUNTING.CONF. The accounting configuration file defines:
· The port the accounting program listens on. This should be an unused port, not the port for the service on which logging is being enabled.
· The name of the file used for accounting records. This file is opened shareable and new records are always appended to it. To start a new file stop the accounting program, delete (or rename) the existing file, and restart the accounting program.
· The IP addresses of systems that are allowed to write accounting records to this host.
|
Note: After editing the configuration, stop and restart the accounting program so that the changes can take effect.
|
Follow these guidelines when entering data in the Accounting configuration file:
· Allow one line for each item.
· Enter information in any order; in upper- or lowercase.
· Use a pound sign (#) or exclamation point (!) to denote comments. The accounting facility ignores all information following these characters.
The commands that can be in TCPWARE:ACCOUNTING.CONF are:
|
PORT port_number |
The TCP port that the accounting program should listen on. |
|
PEER ip-address |
The IP address of a host that is allowed to log records with the accounting software. |
|
FILENAME filename |
The name of the file that the accounting records will be written to. The TCPWARE: device is assumed if a device is not specified as part of the file specification. |
$ @TCPWARE:CNFNET ACCOUNTING
TCPware accounting consists of two components: The accounting record logger, which this procedure configures and controls, and the services that can use the accounting process.
This procedure controls the startup of the accounting record logger. The details such as the name of the accounting file, the port that the accounting record logger listens on, and the list of IP addresses that can use the accounting logger are controlled by TCPWARE:ACCOUNTING.CONF:
Do you want to activate the Accounting listener on this host [NO]: Y
To view accounting information, do the following:
$ TCPWARE ACCOUNTING/INPUT=data_file [/output=output file] -
_$ [/since=start_date] [/before=end_date] [/protocol={SMTP, FTP,
MAIL}] [/CSV]
· data_file is the name of the logging file you want to see.
· output file is the name of the file you want to call this information. If this field is omitted, the information displays to the terminal screen.
·
start_date is the beginning
date you want the command to start with. The date format is
[DD-MMM-YYYY [:]] [hh:mm:ss]cc]. If not specified, all records display up to the
end of the data found. The time is always in local time.
·
end_date is the ending date
you want the command to end with. The date format is
[DD-MMM-YYYY [:]] [hh:mm:ss]cc]. If not specified, all records display until the
end of the file.
· protocol is any combination of SMTP, FTP, or MAIL.
· /CSV generates Comma Separated Values, for input to products like Excel.
The accounting file is written using OpenVMS RMS records. The format of these records is defined in TCPWARE_ROOT:[TCPWARE.EXAMPLES]ACCOUNTING.H, and listed below:
struct accountingPDU {
char version;
char type; /* type of record */
/*
* FTP: C - Client
* S - Server
* SMTP: N - Network delivery (send)
* L - Local delivery (received)
* R - Rejected message
*/
char flags; /* not currently used */
char reserved; /* for future use */
int payload_length; /* length (in bytes) of data after header */
int port; /* IP port of reporting service - 25 SMTP, 21 - FTP
*/
int reporterIP; /* IP address of reporter */
};
struct FTPaccounting_data {
struct accountingPDU header;
int start_time[2]; /* VMS time that session started */
int end_time[2]; /* VMS time that session ended */
int datasent; /* KBytes of file data sent */
int datarecv; /* KBytes of file data received */
int filessent; /* Number of files sent */
int filesrecv; /* Number of files received */
int partnerIP; /* IP address of partner */
char user[12]; /* username that operations were done under */
};
struct SMTPaccounting_data {
struct accountingPDU header;
int date[2]; /* Time of activity */
int msg_size; /* size of message in bytes */
int from_str_size; /* size of From: string */
int to_str_size; /* size of To: string */
char from_to_str[1]; /* text of From & To string */
};
The parameters that control the operations of the TCPware mailer are described in the table at the beginning of this chapter.
To configure mail parameters with the MAIL-CONFIG utility:
1. Start MAIL-CONFIG with the TCPWARE CONFIGURE /MAIL command.
2. Use the SET parameter_name commands.
3. Save the configuration with the SAVE command.
4. Quit MAIL-CONFIG with the QUIT command.
The modified configuration takes effect the next time your system reboots or the queues are restarted.
The below table describes all the mail parameters you can set with the MAIL-CONFIG utility.
|
Parameter |
Description |
|
ALIAS-FILE |
File in which SMTP aliases are stored; see the Configuring Mail Aliases section. |
|
DECNET-DOMAIN |
Domain name for DECnet gateway function; see the Configuring the SMTP-DECnet Mail Gateway section. |
|
DELIVERY-RECEIPTS |
When TRUE, causes the SMTP processor to honor Delivery-Receipt-To: headers. |
|
DISABLE-PSIMAIL |
When TRUE, the SMTP symbiont looks for messages addressed through PSImail (usually of the form PSI%address::user) and returns messages with those addresses to the sender marked "user unknown." |
|
DISALLOW-USER-REPLY-TO |
When TRUE, prevents OpenVMS MAIL users from setting a Reply-To: header address with the logical name TCPWARE_SMTP_REPLY_TO. |
|
FORWARDER |
Identifies a host (known as a mail hub) to which mail should be forwarded if a host name cannot be resolved for an address. The specified name must resolve to an IP address; it must not resolve to an MX record. |
|
FORWARD-LOCAL-MAIL |
Forwards all mail designated for local users to the mail hub instead of delivering it locally. Can be overridden by entries in the SMTP_ALIASES file. |
|
FORWARD-REMOTE-MAIL |
Forwards all SMTP-delivered mail to the mail hub instead of directly to the destination host. Can be overridden by a GATEWAY or LOCAL-DOMAIN entry. |
|
HEADER-CONTROL |
Controls which RFC-822 headers appear in messages delivered to OpenVMS MAIL users. |
|
HOST-ALIAS-FILE |
Contains a list of host names considered aliases for the local host name. |
|
LOCAL-MAIL-FORWARDER |
Identifies a host to which mail should be forwarded when a local mail delivery fails because the username is unknown. |
|
POSTMASTER |
Identifies the username of the system postmaster. |
|
QUEUE-COUNT |
Specifies the number of mail processing queues to create on a particular system. |
|
REPLY-CONTROL |
Specifies how Internet mail headers should be mapped to the OpenVMS MAIL from header. Permitted values are FROM and REPLY-TO. You may specify both as a comma-separated list. |
|
RESENT-HEADERS |
When FALSE, the SMTP symbiont omits the Resent-From, Resent-To, and Resent-Date headers that are usually included when a message is forwarded using an OpenVMS MAIL forwarding address. |
|
RETRY-INTERVAL |
Specifies the amount of time (in minutes) that should elapse after a failed attempt before another attempt is made. |
|
RETURN-INTERVAL |
Specifies the amount of time (in hours) a message can remain in the processing queue before it is returned to sender. |
|
SEND-BROADCAST-CLASS |
Controls the OpenVMS broadcast class used by SMTP for SEND-type messages (which are sent to a terminal). |
|
SMTP -HOST-NAMES |
A list of up to 16 host names to consider as aliases for the local host. See the Specifying SMTP Host Aliases section. |
|
START-QUEUE-MANAGER |
Determines whether START_SMTP.COM starts the OpenVMS queue manager if it is not already running. |
The TCPware SMTP server accepts mail from remote hosts and delivers it to users' mailboxes.
By default, the SMTP server is enabled when you install TCPware.
TCPware provides a logical name to solve the problem of systems sending messages containing lines terminated by an LF character only instead of the proper CR/LF sequence. The following command tells TCPware to accept the bare LF as the end-of-line indicator:
$ DEFINE/SYSTEM/EXEC TCPWARE_SMTP_ACCEPT_UNIX_LF TRUE
TCPware lets you validate the contents of the envelope-from field by defining the system-wide logical name TCPWARE_SMTP_REJECT_INVALID_DOMAINS. Use the equivalence string STRICT to require the presence of a host in those addresses. For example, require MAIL FROM: user@host rather than MAIL FROM: user. The host specified in the MAIL FROM: address must exist in the DNS database.
TCPware lets users send mail to remote destinations by submitting outbound messages to mail queues that are processed by TCPware's SMTP symbiont.
You can configure the SMTP symbiont to:
· Control users' ability to specify their own REPLY-To: headers (see the Specifying the REPLY_TO Header section.)
· Provide more than one server queue for each cluster node. By default, TCPware provides one server queue for each cluster node running TCPware (see the Configuring Mail Queues section.).
· Forward mail through a central mail hub (see the Forwarding Mail through a Mail Hub section.)
· Use gateways to reach specific hosts, domains, or "virtual" domains (see the Configuring Mail Gateways section.)
· Use host aliases (see the Specifying SMTP Hosts Aliases section.)
· Use mail aliases (see the Configuring Mail Aliases section.)
You can also write your own SMTP dispatcher by modifying and compiling the SMTP user exit TCPWARE_ROOT:[TCPWARE.EXAMPLES]USER_SMTP_DISPATCH.C. Instructions for modifying the dispatcher are outside the scope of this manual.
For outbound mail, TCPware SMTP eases the 255-character limitation on RFC-822 To: and CC: header lengths. The limit of 255 characters was imposed because some mail applications cannot handle headers longer than 255 characters.
The default header length is 1024 characters. The maximum length is configurable by defining the logical name TCPWARE_SMTP_MAXIMUM_822_TO_LENGTH to be the maximum number of characters to allow in the header. If that maximum is exceeded, only as many addresses as will fit are put into the header. OpenVMS MAIL always creates X-VMSmail-To: and -CC: headers that contain all of the given addresses.
To automatically lower the case of usernames in outbound messages, define the logical name TCPWARE_VMSMAIL_LOCASE_USERNAME.
The TCPWARE_SMTP_REPLY_TO logical name lets you specify the value for the RFC822 REPLY-TO: header. For example, to set your Reply-To: header to FNORD@EXAMPLE.COM, use the command:
$ DEFINE TCPWARE_SMTP_REPLY_TO "FNORD@EXAMPLE.COM"
This logical name only affects mail agents that use the SMTP% interface (for example, OpenVMS and DECwindows mail). The system manager can disable the use of this logical name with the SET DISALLOW-USER-REPLY-TO command of the TCPWARE CONFIGURE /MAIL utility.
To disable VRFY and EXPN processing, use the logical name TCPWARE_SMTP_SERVER_DISABLE_VRFYEXPN. Define it to have some non-zero value to disable the requisite functions. The following values may be used to specify which function to disable:
|
Value |
Function |
|
1 |
to disable VRFY |
|
2 |
to disable EXPN |
|
3 |
to disable both VRFY and EXPN |
TCPware uses OpenVMS server queues for SMTP processing. Initially, TCPware configures each cluster node running TCPware with a server queue and configures a generic queue for the entire cluster. New messages are placed in the generic queue for processing, which distributes mail processing to the first available server queue.
For example, if three clustered nodes, Huey, Louey, and Dewey, are running TCPware, TCPware creates three server queues and one generic queue. The queue names are:
SMTP_HUEY [Execution queue]
SMTP_LOUEY [Execution queue]
SMTP_DEWEY [Execution queue]
TCPWARE_SMTP [Generic queue]
The following example lists the queues for node Huey:
$ SHOW QUEUE TCPWARE_SMTP/FULL
Generic server queue TCPWARE_SMTP
/GENERIC=(SMTP_HUEY,SMTP_LOUEY,SMTP_DEWEY) /OWNER=[SYSTEM]
/PROTECTION=(codes)
$ SHOW QUEUE SMTP_HUEY/FULL
Server queue SMTP_HUEY, idle, on HUEY::, mounted form DEFAULT
/BASE_PRIORITY=4 /DEFAULT=(FEED,FORM=DEFAULT) /OWNER=[SYSTEM]
/PROCESSOR=TCPWARE_SMTP_SYMBIONT /PROTECTION=(codes)
The queues SMTP_LOUEY and SMTP_DEWEY are also created, and are similar to the SMTP_HUEY queue shown. Note that a standalone (non-clustered machine) has two queues created by default; that is, one generic queue (TCPWARE_SMTP) and one execution queue (SMTP_nodename).
If mail traffic is heavy on your system, you can configure multiple server queues on one or more nodes using MAIL-CONFIG. To configure multiple queues with the MAIL-CONFIG utility:
1. Start MAIL-CONFIG with the TCPWARE CONFIGURE /MAIL command.
2. Use the SET QUEUE-COUNT command to specify the number of queues on the node.
3. Save the configuration with the SAVE command.
4. Quit MAIL-CONFIG with the QUIT command.
The modified configuration takes effect the next time your system reboots.
In heterogeneous cluster environments, you may need to partition mail processing by grouping homogeneous subsets of your cluster into queue groups using MAIL-CONFIG.
|
Note: Queue groupings can be displayed by starting MAIL-CONFIG and issuing the SHOW command.
|
To configure queue groups with the MAIL-CONFIG utility:
1. Start MAIL-CONFIG with the TCPWARE CONFIGURE /MAIL command.
2. Use the ADD QUEUE-GROUP and DELETE QUEUE-GROUP commands to add or delete queues.
3. Save the configuration with the SAVE command.
4. Quit MAIL-CONFIG with the QUIT command.
The modified configuration takes effect the next time your system reboots.
Many sites provide outbound e-mail access to the Internet through a single system known as a mail hub to deliver all outbound mail on behalf of the other hosts at the site. A mail hub typically implements a single-address scheme for e-mail users at the site, so that all users have addresses of the form username@sitename rather than username@hostname.sitename. Site administrators often configure mail hubs to provide Internet e-mail access to hosts that do not have direct access to the Internet. To forward mail through a mail hub:
1. Specify the host that will serve as a mail hub.
2. Specify the conditions under which TCPware forwards mail to the mail hub.
The following sections describe these procedures.
To specify the host that will serve as a mail hub for your TCPware host:
1. Start MAIL-CONFIG with the TCPWARE CONFIGURE /MAIL command.
2. Modify the FORWARDER parameter using the SET FORWARDER mailhub_hostname command.
3. If desired, set any of the following conditions for forwarding mail to the mail hub:
· Forward mail addressed to users on remote hosts (see the Forwarding Mail Addressed to Remote Hosts section.)
· Exclude hosts in specific domains from remote mail hub forwarding (see the Excluding Hosts in Specific Domains from Mail Forwarding section.)
· Forward mail addressed to users on the local host (see the Forwarding Local Mail section.)
· Exclude specific local users from mail hub forwarding (see the Excluding Specific Local Users from Mail Forwarding section.)
4. Save the configuration with the SAVE command.
5. Quit MAIL-CONFIG with the QUIT command.
6. Make the changes take effect immediately by stopping and restarting the mail queues. To update the OpenVMS cluster, use the @TCPWARE:START_SMTP.COM command. To update the local host only, use the @TCPWARE:START_SMTP_LOCAL.COM command. Otherwise, your changes take effect the next time you reboot your system.
To configure TCPware to forward mail addressed to remote users via a mail hub:
1. Make sure the FORWARDER parameter specifies the host you want to use as a mail hub (see the Specifying a Mail Hub section.).
2. Start MAIL-CONFIG with the TCPWARE CONFIGURE /MAIL command.
3. Modify the FORWARD-REMOTE-MAIL parameter using the SET FORWARD-REMOTE-MAIL TRUE command.
4. If desired, exclude hosts in specific domains from mail hub forwarding (see the Excluding Hosts in Specific Domains from Mail Forwarding section.).
5. If desired, specify other conditions under which TCPware forwards mail to the mail hub (see the Specifying a Mail Hub section.).
6. Save the configuration with the SAVE command.
7. Quit MAIL-CONFIG with the QUIT command.
8. Make the changes take effect immediately by stopping and restarting the mail queues with @TCPWARE:START_SMTP.COM to update the OpenVMS cluster or with @TCPWARE:START_SMTP_LOCAL.COM to update the local host only. Otherwise, your changes take effect the next time you reboot your system.
If you configure TCPware to forward mail addressed to remote users via a mail hub (see the Forwarding Local Mail section), you can exclude hosts in specific domains from the mail forwarding system by adding the domain to a list of "local domains." To modify the local domain list:
1. Make sure remote mail forwarding is enabled (see the Forwarding Mail Addressed to Remote Hosts section.).
2. Start MAIL-CONFIG with the TCPWARE CONFIGURE /MAIL command.
3. Add a domain to the list using the ADD LOCAL-DOMAIN domain_name command. If domain_name begins with a dot, it specifies a domain name. Otherwise, domain_name specifies a host name.
4. Delete a domain from the list using the DELETE LOCAL-DOMAIN domain_name command.
5. Save the configuration with the SAVE command.
6. Quit MAIL-CONFIG with the QUIT command.
7. Make the new configuration take effect immediately by stopping and restarting the mail queues with @TCPWARE:START_SMTP.COM to update the OpenVMS cluster or with @TCPWARE:START_SMTP_LOCAL.COM to update the local host only. Otherwise, your changes take effect the next time you reboot your system.
To configure TCPware to forward mail addressed to local users via a mail hub:
1. Make sure the FORWARDER parameter specifies the host you want to use as a mail hub (see the Specifying a Mail Hub section.).
2. Start MAIL-CONFIG (TCPWARE CONFIGURE /MAIL).
3. Modify the FORWARD-LOCAL-MAIL parameter using the SET FORWARD-LOCAL-MAIL TRUE command.
4. If desired, exclude specific local users from mail hub forwarding (see the Excluding Specific Local Users from Mail Forwarding section.).
5. If desired, specify other conditions under which TCPware forwards mail to the mail hub (see the Specifying a Mail Hub section.).
6. Save the configuration with the SAVE command.
7. Quit MAIL-CONFIG with the QUIT command.
8. Make the changes take effect immediately by stopping and restarting the mail queues with @TCPWARE:START_SMTP.COM to update the OpenVMS cluster or with @TCPWARE:START_SMTP_LOCAL.COM to update the local host only. Otherwise, your changes take effect the next time you restart your system.
If you configure TCPware to forward local mail via a mail hub (see the Forwarding Local Mail section), you can exclude specific local users from the mail forwarding system by creating mail aliases for them in the TCPWARE:SMTP_ALIASES file. Each users' alias must be in the following format: username: *;
For more information on configuring mail aliases, see the Configuring Mail Aliases section.
You can configure TCPware with gateways to particular hosts or domains to override the normal host lookup used by SMTP or to configure "virtual" domains not actually present on the network. You can use MAIL-CONFIG. To configure mail gateways with MAIL-CONFIG:
1. Start MAIL-CONFIG with the TCPWARE CONFIGURE /MAIL command.
2. Use the ADD GATEWAY and DELETE GATEWAY commands.
3. Save the configuration with the SAVE command.
4. Quit MAIL-CONFIG with the QUIT command.
The modified configuration takes effect the next time your system reboots.
If your system is a member of a OpenVMS cluster, you can define host aliases, which are host names interpreted by the mailer as aliases for the actual local host name. You can specify these aliases in return addresses for individual users.
TCPware relies on two logical names as parameters to obtain its list of host aliases:
|
SMTP-HOST-NAMES |
Is a comma-separated list of up to 16 host aliases. If defined, the first alias in the list is the name used for outgoing mail. Any aliases are names for which your host accepts incoming mail. |
|
HOST-ALIAS-FILE |
Is the complete file specification of a file containing an unlimited list of host alias entries (one entry per line). The HOST-ALIAS-FILE value defaults to TCPWARE:SMTP_HOST_ALIAS. |
To change your host aliases with MAIL-CONFIG:
1. Use the SET SMTP-HOST-NAMES command or the SET HOST-ALIAS-FILE command.
2. Save the modified configuration with the SAVE command.
3. Quit MAIL-CONFIG with the QUIT command.
The new configuration takes effect the next time you reboot the system or the queues are restarted.
The logical name TCPWARE_SMTP_FROM_HOST lets you change the host name that appears in your return address on outgoing mail.
Normally, the host name you choose must be a "local" host name; that is, it must be one of the registered SMTP host name aliases on the system (either from the SMTP-HOST-NAMES setting or the HOST-ALIAS-FILE). If it is not a known alias, the setting is ignored.
If you define the host name in executive mode, however, TCPWARE_SMTP_FROM_HOST can be any arbitrary host name. The name is not checked against the SMTP host name.
This feature lets users from different administrative entities within an organization have return addresses that reflect the names of those entities. To enable this feature:
1. Set up MX records in DNS so mail is routed to the local host for each separate host name. For information about MX records, see the discussion of zone files in Chapter 6.
2. Set up SMTP-HOST-NAMES or the HOST-ALIAS-FILE with a list of host names.
3. Define the logical name TCPWARE_SMTP_FROM_HOST for each user. Base the value for this logical name on some aspect of the department or organization to which the user belongs.
The TCPware SMTP system supports system-wide mail aliases, system-wide mailing lists, and per-user mail aliases. The default system-wide alias file is TCPWARE:SMTP_ALIASES. You can configure this name or specify a list of alias file names.
Per-user mail aliases are kept in the file SMTP_ALIASES in each user's login directory. The format for alias entries is: alias: real_address[,...];
· alias is an alphanumeric string.
· real_address is either a local or remote electronic mail address.
You can specify multiple addresses by separating them with commas; the alias definition may span multiple lines, if needed, and must always be terminated with a semicolon (;).
For example, a local user has the user name
"JB134A", but wants to receive SMTP mail sent to the address
"john". The system manager adds the following line to the system-wide
alias file:
john: jb134a;
You can both forward a mail message and deliver it to a local mailbox by adding the mailbox name, preceded by an underscore, to the TCPWARE:SMTP_ALIASES file.
The following example shows such an alias entry:
FNORD: FNORD@SOMEWHERE.EXAMPLE.COM, _FNORD;
The leading underscore on the second address (_FNORD), tells the SMTP symbiont to skip any further alias processing.
Mailing lists are a special form of mail alias and are supported only in the system-wide alias files. The format for specifying a mailing list is: list-name:: owner-address, file-spec;
· A double-colon (::) signifies that this alias is a mailing list.
· owner-address is the address of the mailing list owner. Messages sent to this mailing list go to each subscriber on the list with the return-path set to this address. The owner address can be an actual user's address or an alias, if desired.
· file-spec is the file specification for the file containing the subscribers to the mailing list. Specify a complete path name for this file, including the device and directory.
For example, you might want to set up a mailing list called OPERATIONS-STAFF for your operations staff, and have your operations manager, user OPER1, manage that list. You might set up the mailing list this way:
Operations-Staff:: Operations-Manager,
USERS:[OPER1]STAFF.LIST;
Operations-Manager: OPER1;
Mail sent to OPERATIONS-STAFF is forwarded to the addresses listed in USERS:[OPER1]STAFF.LIST. Because this file is in OPER1's area, the operations manager has control over who is included in the list. The list is set up in this example so the return-path on list messages is set to "Operations-Manager" instead of user OPER1; setting up the list owner as an alias makes it easier to change list owners later.
By default, the TCPware SMTP system obtains system-wide mail aliases from the TCPWARE:SMTP_ALIASES file. You can configure TCPware to use any other file, or to use multiple files. To change the SMTP aliases file with MAIL-CONFIG:
1. Use the SET ALIASES-FILE command.
2. Save the modified configuration with the SAVE command.
The new configuration takes effect the next time you reboot the system.
If you want aliases configured within the TCPware SMTP alias file to be accessible to local OpenVMS MAIL users (or those connected via DECnet), specify the address using the OpenVMS MAIL foreign mail protocol interface.
For example, a local user wanting to send mail to the "gcc-users" mailing list would specify the address SMTP%"gcc-users". Note that you can, however, define an OpenVMS MAIL alias containing the SMTP% specification.
To define the OpenVMS MAIL alias "Operations-Staff," use the OpenVMS MAIL SET FORWARD command:
MAIL> SET FORWARD "SMTP%""Operations-Staff-USERS""" /USER=Operations-Staff
TCPware SMTP uses the RFC-822 To: and CC: headers to provide the contents of the OpenVMS MAIL To: and CC: fields. To enable this processing, define the logical name TCPWARE_VMSMAIL_USE_RFC822_TO_HEADER.
The Internet Message Access Protocol (IMAP) server lets an IMAP-compliant client mail program access remote message storage as if the storage were local. TCPware's implementation is based on IMAP Version 4, Revision 1.
IMAP and the Post Office Protocol (POP3), described in the next section, operate differently. IMAP retains the message on the server, whereas POP3 retrieves the message and stores it "off-line" on the client, thereby deleting it from the mail server. IMAP does not delete the mail message and lets you access your mail from more than one client host at a time.
IMAP was designed to:
· Be fully compatible with Internet messaging standards, such as MIME.
· Allow message access and management from more than one computer.
· Allow access without relying on less efficient file access protocols.
· Provide support for "online," "offline," and "disconnected" access modes
· Support concurrent access to shared mailboxes.
· Eliminate the need for the client software to know about the server's file storage format.
The IMAP protocol includes operations for:
· Creating, deleting, and renaming mailboxes
· Checking for new messages
· Permanently removing messages
· Setting and clearing flags
· Server-based RFC-822 and MIME parsing and searching
· Selective fetching of message attributes, texts, and portions thereof, for efficiency
Use CNFNET, @TCPWARE:CNFNET IMAP to enable or disable the IMAP server.
CNFNET asks if you want to use the IMAP server, and if so, provides additional prompts:
· Enter the user (account) the IMAPD (daemon) process should execute as. The default is SYSTEM. Whatever user you choose must have SYSNAM, TMPMBX, NETMBX, SYSPRV, and BYPASS privileges.
· Do you want to enable full message caching? The default is NO.
The IMAP Server usually caches only the text of the last accessed message, in addition to the attributes of all messages in the currently selected folder. Enabling message caching causes the server to cache the text of all messages once seen and until the folder is closed. This can increase server performance but requires considerably more memory.
· What is the desired logging level? The options are:
o NONE - Does no error logging (the default)
o ERROR - Logs errors only
o INFO - Logs errors and informational messages
o DEBUG - Complete debug logging
TCPware creates a log file, TCPWARE_SPECIFIC:[TCPWARE]IMAPSERVER.LOG, when the server is started.
By default, the User Authorization File (UAF) record for the IMAP user is not affected by a user checking for mail. However, if you want the LAST-NON-INTERACTIVE-LOGIN-TIME field in the UAF record for each IMAP user to be updated with the current system date and time, the system administrator can define the following logical system-wide:
$ DEFINE/SYSTEM TCPWARE_IMAP_UDPATE_LOGIN_TIME 1
This update takes place at the time the authentication process is successfully completed.
In contrast to POP3, IMAP allows you to access server mail folders (message stores) other than INBOX. In OpenVMS MAIL, for example, if you create a NOTES folder, you can access mail in that folder via the client mail program. This NOTES folder can be in a mail file other than the default MAIL.MAI file. In fact, you can set a configuration parameter that determines the way mail folders are presented to the client so that you can use folders in these other mail files.
Your default mail directory includes a .IMAPRC file in which you can set certain configuration directives (described more fully in the IMAP Directives File section that follows). Among these directives is allow-subfolders. This directive specifies that folder names are comprised of a directory (optional), mail file, and folder. For example, the NOTES folder in MAIL.MAI is represented as mail/notes (as opposed to just notes if the directive were not set). This would distinguish it from another NOTES folder in the OLD.MAI mail file, for example, which would be named old/notes.
Each level beyond the second in this hierarchy represents a subdirectory of the default mail directory. For example, the NOTES folder in [.ARCHIVED]MAIL.MAI has the IMAP equivalent of archived/mail/notes.
Because of this folder syntax ambiguity, directory names, file names, and folders can overlap, such as the examples in the following table.
|
This mail file... |
Containing this folder... |
Has this IMAP equivalent... |
|
MAIL.MAI |
NOTES |
mail/notes |
|
[.MAIL]NOTES.MAI |
STUFF |
mail/notes/stuff |
|
[.MAIL.NOTES]STUFF.MAI |
BOBS |
mail/notes/stuff/bobs |
Entries in the syntax can at different times be mail files, directories, subdirectories, or folders. Because of this overlap, the server must keep an internal representation of the hierarchy and mark what each level of the folder name means. This information is critical when renaming or deleting folders. Mail file definitions do not have to match.
One restriction is that a first level folder (MAIL, for example) cannot be a message store, since it represents only a file and not a mail folder. INBOX, however, is a special case. INBOX is always INBOX, cannot be deleted or renamed (a rename moves messages to the renamed folder but does not delete INBOX), and never goes away. In IMAP, INBOX is mail/NEWMAIL by default, and is hidden to the user.
You can change the mail inbox from INBOX to another folder by defining the file-inbox-messages-to-folder directive in the .IMAPRC file. See the next section for details.
You can also access mail files in your login directory (SYS$LOGIN) by prefixing the folder name with a tilde (~). The ~ folder is reserved and cannot be used by other folders.
Users can set certain preferences by creating a file in their default mail directory called .IMAPRC and including directives. The following table lists these directives along with their meanings. Each directive must be on its own line and in lowercase.
|
This directive... |
Does the following... |
|
set allow-child-folders |
Enables or disables the use of subfolders and the way that folders are presented to the client. By default, this value is false. If you want to set the value to be true, put this line in the .IMAPRC file:
set allow-child-folders true
(See the previous section for details.) |
|
set autofile-messages-to-folder foldername |
Moves read messages from INBOX to the specified folder in the user's default mail file. By default, this option is disabled. |
|
set case-insensitive-folders |
Specifies that folder names are case-insensitive. Otherwise, two folders with the same name but with different cases could become inaccessible to the IMAP client. Newly created folders are created in uppercase on the server. By default, this value is false. If you want to set the value to be true, put this line in the .IMAPRC file:
|
|
set do-purge-reclaim |
Enables or disables purge-reclaim operations upon closing a folder. By default, this value is true. |
|
set folder-timer delta_time |
Specifies the frequency the IMAP server will check for externally created folders. By default, this value is 00:02:00 (2 minutes). |
|
set inbox-folder foldername |
Maps INBOX to the specified folder in the user's default mail file. By default, this value is NEWMAIL. |
|
set new-mail-timer delta_time |
Specifies, using OpenVMS delta time format, how often the server checks a folder for new mail. (Note that checking for new mail is time consuming for large folders.) The default is 0:0:30 (30 seconds). |
These options are valid in the global IMAPD.CONF file (TCPWARE:IMAPD.CONF) as shown in the below table:
|
This directive... |
Does the following... |
|
set decnet-address nodename namespace domainname |
Maps the specified DECnet node name and/or namespace to a given domain name. Use " " to represent either a blank node name or namespace. Multiple entries are allowed. By default, this option is disabled. Example:
set decnet-address knob " " door.com |
|
set enable-full-cache |
Enables or disables full message caching. By default, this value is false. |
|
set max-ping-count integer |
Specifies, in number of messages, the threshold at which the server will no longer attempt to check for new messages. By default, this value is 20000. |
|
set smtp-transport-prefix string |
Specifies the SMTP transport prefix. By default, this value is SMTP. If you want to change it to MX, put this line in the IMAPD.CONF:
|
|
set trailing-header-marker string |
Specifies a text string used to indicate the start of RFC822 message headers if the system does not place them at the start of the message. By default, this option is disabled. |
The IMAP server includes files created in the user's mail directory where it maintains state information, as shown in the following table.
|
This file... |
Stores... |
|
.MAILBOXLIST |
Folders to which the user subscribes. |
|
.NEWMAILBOXES |
List of folders known to be empty. OpenVMS MAIL deletes folders once it deletes the last message, so that the server must "remember" these folders. |
|
*.MAI-UID |
UIDVALIDITY information for folders in a mail file. Persistent UIDs allow clients to operate in “offline” and “disconnected” modes, and can improve performance if clients implement sensible caching schemes. |
|
mailfolder.foldernameuidvalidity |
For each folder, the UIDs for all the messages. The file name is composed of the folder name and its UIDVALIDITY code. For example:
MAIL.NEWMAIL3B3200E6
In the example, the folder name is NEWMAIL and the UID validity code is 3B3200E6. |
The Post Office Protocol Version 3 (POP3) is a multithreaded server that can handle up to 31 simultaneous client connections. It does not perform any mail delivery functions but simply allows clients (mostly PCs) to retrieve new mail from OpenVMS MAIL inboxes.
Use CNFNET, @TCPWARE:CNFNET POP3 to enable or disable the POP3 server.
CNFNET asks if you want to use the POP3 server, and if so, asks the following additional questions:
· What is the maximum number of new mail messages to return per connection? The default is 32.
· What is the desired logging level? The options are:
o ERROR - Logs errors only (the default)
o INFO - Logs errors and informational messages
o THREAD - Logs errors, informational messages, and detailed thread logging
o DEBUG - Complete debug logging
TCPware creates a log file, TCPWARE_SPECIFIC:[TCPWARE]POP3SERVER.LOG, when the server is started.
· Do you want to do a MAIL PURGE/RECLAIM operation for each mailbox after its use?
If TRUE, this not only purges (deletes all messages in) the wastebasket folder, but releases deleted message space back to RMS for reuse. The default is TRUE.
POP3 runs on the local mail server so that client software on a PC can check the server for incoming mail and display it on the PC. The POP3 server downloads the incoming mail on its machine to the PC, and deletes the original message. This is known as an “off-line” mail operation, where all message processing is local to the client and distinct from the server.
POP3 processes only new, incoming mail and does not manipulate folders other than INBOX.
The POP3 server first listens on TCP port 110 for a client request (in the form of a greeting) to download mail. The POP3 session then passes through the following three states:
AUTHORIZATION - The client identifies itself to the POP3 server and the server acquires resources associated with the client’s mail drop. By default, the User Authorization File (UAF) record for the POP3 user is not affected by a user checking for mail. However, if you want the LAST-NON-INTERACTIVE-LOGIN-TIME field in the UAF record for each POP3 user to be updated with the current system date and time, the system administrator can define the following logical system-wide:
$ DEFINE/SYSTEM TCPWARE_POP3_UDPATE_LOGIN_TIME 1
This update takes place at the time the authentication process is successfully completed.
TRANSACTION - The client acquires resources and signs off.
UPDATE - The POP3 server releases resources and signs off.
The client sends commands to the POP3 server in each state and the server responds with an affirmative +OK (or negative -ERR) status. TCPware’s POP3 server supports all the minimal commands described in RFC 1939 Post Office Protocol - Version 3 as well as the optional TOP command:
|
USER |
STAT |
DELE |
QUIT |
|
PASS |
LIST |
NOOP |
UIDL |
|
QUIT |
RETR (or TOP) |
RSET |
|
The APOP optional command is not supported. For more information on the POP3 commands, see RFC 1939.
The TCPware mailer supports users of HP's ALL-IN-1 office automation environment (often referred to as ALL-IN-1 IOS or ALL-IN-1 Classic) and ALL-IN-1 MAIL via an interface to Message Router, the backbone of HP's MAILbus product line. This interface allows both ALL-IN-1 IOS and ALL-IN-1 MAIL users to send and receive SMTP mail. Message Router V3.1 or later is required for this feature to function properly. For information on sending and receiving SMTP mail from within ALL-IN-1 IOS and ALL-IN-1 MAIL, see Chapter 10 in the User's Guide.
You must have Message Router V3.1 or later installed on your system before configuring the TCPware SMTP to Message Router (SMTP/MR) interface. If you want to support automated conversion of WPS and DX documents in ALL-IN-1 messages to ASCII, you must also have the Message Router OpenVMS MAIL Gateway (MRGATE) installation kit.
You do not need to install MRGATE on your system; however, certain object libraries in the MRGATE kit are needed to provide the necessary document conversion functions. The SMTP/MR gateway software functions even if the document conversion is not built. It does, however, cause all WPS and DX message body parts to be discarded as the ALL-IN-1 message passes through SMTP/MR.
The MR_CONFIGURE.COM command procedure in the TCPware: directory is used to configure the SMTP/MR gateway software. Execute this procedure with the DCL command:
$ @TCPWARE:MR_CONFIGURE
The command procedure presents a series of prompts. Enter a question mark (?) at any time to display more information about that prompt. The configuration command procedure prompts you for the following information:
1. Whether to display a detailed explanation before each question. It is recommended that you answer YES to this question the first time you run the configuration procedure.
2. The domain name of the gateway system. This is a domain-style host name used to refer to the gateway from the Internet. Be sure the name you choose is within a domain or subdomain over which you have administrative authority and is not currently being used for another host. If your local domain is EXAMPLE.COM, a reasonable choice for this domain name would be MR.EXAMPLE.COM. This name is largely for internal use and should not be needed to address mail to ALL-IN-1 users.
3. The domain name to be used for local ALL-IN-1 IOS users. This is a domain-style host name used to indicate to the TCPware mailer that it should pass the message to the Message Router for delivery to an ALL-IN-1 user. Be sure the name you choose is within a domain or subdomain over which you have administrative authority and is not currently being used for another host. If your local domain is EXAMPLE.COM, a reasonable choice for this domain name would be A1.EXAMPLE.COM. Note that if you are not running ALL-IN-1 IOS, you should specify NONE.
4. The domain name to use for local ALL-IN-1 MAIL users. This is a domain-style host name used to indicate to the TCPware mailer that it should pass the message to Message Router for delivery to an ALL-IN-1 user. Be sure the name you choose is within a domain or subdomain over which you have administrative authority and is not currently being used for another host. If your local domain is EXAMPLE.COM, a reasonable choice for this domain name would be AM.EXAMPLE.COM. Note that if you are not running ALL-IN-1 MAIL, you should specify NONE.
5. The Message Router mailbox name used for the gateway. This Message Router mailbox name is used by ALL-IN-1 users to send outbound SMTP mail. You are directed later to create this mailbox with the Message Router MRMAN utility. The default value of "SMTP" should be used.
Both ALL-IN-1 IOS and ALL-IN-1 MAIL users use the address form user@host@SMTP to specify remote SMTP recipients. Each ALL-IN-1 mail utility places this outbound mail in the Message Router mailbox named SMTP. The TCPware mailer "picks up" mail from this mailbox and sends it via the normal SMTP delivery mechanism.
The current version of TCPware allows both ALL-IN-1 IOS and ALL-IN-1 MAIL users to reply to messages imported with the V command or forwarded into ALL-IN-1 using an address of the form MRGATE:"A1::user" or MRGATE:"AM::user". Return addresses are translated from Message Router format to a more standard RFC-822 format in a fashion analogous to the DECnet to SMTP gateway conversion.
The following logical names can be used to customize the translation:
TCPWARE_SMTP_MRGATE-NAME - Change the name of the Message Router gateway mailbox. The default value is MRGATE.
TCPWARE_SMTP_A1_NAME - Change the name of the ALL-IN-1 IOS gateway mailbox. The default value is A1.
TCPWARE_SMTP_AM_NAME - Change the name of the ALL-IN-1 MAIL gateway mailbox. The default value is AM.
TCPWARE_SMTP_A1_DOMAIN - Specify the RFC-822 domain associated with the ALL-IN-1 IOS gateway. Use the domain you specified when configuring your SMTP/MR gateway.
TCPWARE_SMTP_AM_DOMAIN - Specify the RFC-822 domain associated with the ALL-IN-1 MAIL gateway. Use the domain you specified when configuring your SMTP/MR gateway.
6. The Message Router mailbox name used for delivery to ALL-IN-1 MAIL users. This Message Router mailbox is used to deliver inbound SMTP mail to ALL-IN-1 MAIL users. Normally this mailbox is named AM, but the name is configurable. If your site uses a name other than AM, enter that name.
7. The Message Router mailbox name used by default when mail is sent to the domain name of the gateway system (for example, MR.EXAMPLE.COM). Specify the default value, MRGATE, to indicate the Message Router OpenVMS MAIL Gateway mailbox.
8. The Message Router mailbox name for the local system. Specify the DECnet node name of the local system. SMTP/MR uses this name to generate addresses that are valid on remote systems.
9. The names of any null routes. Specify the name of the local DECnet node and any other nodes in a homogeneous OpenVMS cluster (including the cluster alias). Message Router routing information often includes local DECnet node names or a cluster alias which is superfluous in outbound SMTP mail. To determine the names of any null routes, use the MRMAN utility SHOW * command. Null routes have the general form:
nullname, Replace=
The names you specify at this point are automatically stripped from addresses passing through SMTP/MR, greatly simplifying them when they pass into the SMTP world. Use a blank entry to terminate the list.
10. The SMTP address of the local postmaster, which should be the full domain-style email address of the user who should receive error messages generated by SMTP/MR.
11. The password associated with this gateway's Message Router mailbox (SMTP by default). Message Router protects each mailbox with a password to ensure privacy of mail messages.
12. Whether you want to have messages with WPS and DX body parts automatically converted to ASCII. SMTP/MR can perform these conversions if it is linked against libraries provided as part of various Message Router products, notably MRGATE. If you intend to have messages in these special formats converted to ASCII, answer YES. If you answer NO, these body parts are not converted, and may be discarded.
13. You are then prompted for the names of several SMTP/MR configuration files. Accept the defaults for each of these file names.
14. You are then asked if you want to generate the configuration files. If you are satisfied with all of your responses, type YES.
In the following example, which shows an MR_CONFIGURE.COM session, the local host's DECnet node name is MIGUEL, while its TCP/IP host name is MIGUEL.EXAMPLE.COM. The DECnet cluster alias is IRISDN; and other hosts in the homogeneous VAXcluster are named WHARFIN, BIGBTE, and YAYA. The e-mail address of the local postmaster is POSTMASTER@EXAMPLE.COM.
$ @TCPWARE:MR_CONFIGURE
SMTP-MR Configuration Utility
This utility creates an
initial pair of databases for mapping SMTP
RFC 822-style addresses to Message Router X.400-style addresses and
back again. Only minimal mappings are created to support ALL-IN-1
users sending and receiving SMTP mail.
Important note: No changes
are made to existing SMTP-MR database
information until all questions have been answered. This utility can
be aborted at any prompt by entering a CTRL/Z. The files output by
this utility may optionally be redirected to a different location so
they will have no impact on the existing SMTP-MR databases.
Do you wish to continue [Y]?
Return
Do you wish to have a detailed explanation printed before each question [N]? Return
Domain name of the gateway: MR.EXAMPLE.COM
Domain name for local ALL-IN-1 IOS users [A1.EXAMPLE.COM]: Return
Domain name for local ALL-IN-1 MAIL users [AM.EXAMPLE.COM]: Return
Message Router mailbox name for the gateway [SMTP]: Return
ALL-IN-1 IOS mailbox known to Message Router [A1]: Return
ALL-IN-1 MAIL mailbox known to Message Router [AM]: Return
Message Router mailbox used by default [MRGATE]: Return
Local system's Message Router mailbox [MIGUEL]: Return
Local node name or other null routes [RETURN if no more]: MIGUEL
Local node name or other null routes [RETURN if no more]: WHRFIN
Local node name or other null routes [RETURN if no more]: BIGBTE
Local node name or other null routes [RETURN if no more]: YAYA
Local node name or other null routes [RETURN if no more]: IRISDN
Local node name or other null routes [RETURN if no more]: Return
RFC822 address of local PostMaster: postmaster@example.com
Password for the Message Router mailbox: example
Convert WPS-PLUS and DX messages to ASCII automatically [Y]? Return
SMTP to MR mapping text file [TCPWARE:TO_MR.]: Return
MR to SMTP mapping text file [TCPWARE:FROM_MR.]: Return
Gateway options file [TCPWARE:MR_OPTIONS.]: Return
SMTP-MR checklist file name [TCPWARE:SMTP-MR.CHECKLIST]: Return
All configuration questions have been answered.
Do you wish to generate the configuration files [Y]? Return
Generating SMTP to MR mapping text file...
SMTP to MR mapping text file is complete.
Generating MR to SMTP mapping text file...
MR to SMTP mapping text file is complete.
Generating the setup checklist...
Checklist file is complete.
Generating options file...
Options file is complete
***********************************************************************
* To complete your SMTP-MR configuration, carry out the steps
* detailed in the setup checklist TCPWARE:SMTP-MR.CHECKLIST.
***********************************************************************
$
The DCF document conversion utility is used by SMTP/MR to convert WPS and DX message body parts to ASCII text. This utility is built from document conversion library routines supplied as part of the Message Router OpenVMS MAIL Gateway (MRGATE) distribution kit. SMTP/MR can function without this utility, but cannot convert WPS and DX body parts to ASCII without it. Body parts in outbound SMTP mail that cannot be converted to ASCII are discarded.
The DCF utility is not supplied in executable form with SMTP/MR; it must be built after SMTP/MR is configured. The command procedure TCPWARE:DCF_BUILD.COM is provided to accomplish this. This procedure prompts for two items:
· The location of the save set from which to extract the necessary conversion libraries.
· The name of a directory into which the libraries should temporarily be placed while the utility is being linked.
You need not copy the saveset from the distribution media for DCF_BUILD.COM to work. For example, if you want to access the libraries on a TK50 containing MRGATE while on a VAXstation 3100, you would specify the saveset name as MKA500:MRGATE031.A.
The following example shows how to build the DCF utility from a saveset located in the SYS$MANAGER directory:
$ @TCPWARE:DCF_BUILD
Directory to put libraries in [SYS$SCRATCH:]: Return
File specification of save set from which to extract libraries:
SYS$MANAGER:MRGATE031.A
Extracting libraries...
%BACKUP-S-CREATED, created SYS$SYSROOT:[SYSMGR]KOALA.OLB;1
%BACKUP-S-CREATED, created SYS$SYSROOT:[SYSMGR]DCF_BASE.OLB;1
%BACKUP-S-CREATED, created SYS$SYSROOT:[SYSMGR]DCF_TRANSLATE.OLB;1
%BACKUP-S-CREATED, created SYS$SYSROOT:[SYSMGR]DCF_MAIL_CONVERSIONS.OLB;1
%BACKUP-S-CREATED, created SYS$SYSROOT:[SYSMGR]DCF_DSAF.OLB;1
%BACKUP-S-CREATED, created SYS$SYSROOT:[SYSMGR]WPADOC.OLB;1
%BACKUP-S-CREATED, created SYS$SYSROOT:[SYSMGR]WPABASE.OLB;1
%BACKUP-S-CREATED, created SYS$SYSROOT:[SYSMGR]XPORT.OLB;1
Linking DCF utility...
Cleaning up...
Done
$
The DCF utility is never invoked interactively. It is always invoked automatically by the SMTP/MR gateway whenever it has mail containing WPS or DX body parts it needs to send via SMTP.
|
Note: You must use the A save set from MRGATE V3.1 or V3.2 to build DCF. Versions V3.3 and later do not contain the object files needed to link to DCF. If you upgrade to MRGATE V3.3, save your V3.1 or V3.2 distribution media.
|
In addition to the SMTP/MR configuration data files, the file TCPWARE:SMTP-MR.CHECKLIST is created by the MR_CONFIGURE.COM command procedure. This file contains the steps needed to complete the SMTP/MR configuration, which include:
1. Adding the SMTP/MR gateway mailbox to your Message Router configuration. Run the MRMAN utility exactly as documented in the checklist file. The Message Router mailbox name and password must be exactly the same as you specified to MR_CONFIGURE.COM.
2. Building the WPS and DX document conversion utility. See the previous section for details on building this utility.
3. Configuring your Domain Name System (DNS) name server for SMTP/MR operation. You must add a Mail eXchanger (MX) record to your name server configuration for the following:
· The domain name of the gateway itself (MR.EXAMPLE.COM in the example in the Configuring SMTP/MR section)
· The domain name used to direct mail to your ALL-IN-1 IOS users (A1.EXAMPLE.COM in the example in the Configuring SMTP/MR section)
· The domain name used to direct mail to your ALL-IN-1 MAIL users (AM.EXAMPLE.COM in the example in the Configuring SMTP/MR section).
If the host running SMTP/MR is named MIGUEL.EXAMPLE.COM, the DNS Resource Records (RRs) you would use in the DNS configuration file for the domain EXAMPLE.COM are:
MR.EXAMPLE.COM. IN
MX 0 MIGUEL.EXAMPLE.COM.
A1.EXAMPLE.COM. IN MX 0 MIGUEL.EXAMPLE.COM.
AM.EXAMPLE.COM. IN MX 0 MIGUEL.EXAMPLE.COM.
For more detailed information on configuring a DNS name server, see Chapter 6, Host Tables and DNS.
4. If you are not running a DNS name server locally, you must add additional host records to the TCPWARE:HOSTS.LOCAL file for the host names of the gateway and your ALL-IN-1 users. Using the names from the above example, and assuming that the IP address for MIGUEL.EXAMPLE.COM is 128.0.0.1, you would add the following lines to TCPWARE:HOSTS.LOCAL:
HOST : 128.0.0.1 : MR.EXAMPLE.COM : : : :
HOST : 128.0.0.1 : A1.EXAMPLE.COM : : : :
HOST : 128.0.0.1 : AM.EXAMPLE.COM : : : :
Note that you should:
· Place these lines after the entry for MIGUEL.EXAMPLE.COM.
· Specify each name on a line by itself. Merging entries in the hosts file prevents the gateway from functioning properly.
· Recompile and re-install the host tables after adding the new entries.
For detailed information on adding entries to your host tables, see chapter 6.
5. Submitting the command procedure TCPWARE:MR_TO_TCPWARE.COM to the appropriate batch queue on your system. This command procedure runs periodically to transfer mail from the SMTP/MR Message Router mailbox (normally SMTP) to the TCPware mailer. Examine this command procedure before submitting it to ensure it runs in the batch queue and under the desired user name.
TCPware can be set up as a gateway to route mail between SMTP and DECnet-only hosts, with appropriate address translations to make the DECnet-style addresses easier for Internet hosts to interpret. To do this, you set the DECNET-DOMAIN mail parameter and add an appropriate MX record to the Domain Name Service. The addresses of DECnet mail sent out via SMTP will be rewritten such that the DECnet node name(s) appear under the DECNET-DOMAIN name in the host-part of the address. The addresses of incoming SMTP mail for hosts under the DECNET-DOMAIN are automatically converted into DECnet addresses and delivered to the DECnet-only hosts.
In the DECnet-to-SMTP direction, an OpenVMS MAIL user on a DECnet-only host sends SMTP mail by specifying an address of the form: node::SMTP%"user@host" where node is the DECnet node name of the system running TCPware.
TCPware recognizes that the mail originated in DECnet and, if the DECNET-DOMAIN parameter is set, rewrites the originating address in the form user@node.decnet-domain.
For example, EXAMPLE.COM has set up node HQ as a DECnet-SMTP gateway. A user named JOHN on DECnet-only node WHARFIN at EXAMPLE.COM addresses mail to the Info-TCPware mailing list as: HQ::SMTP%"Info-TCPWARE@LISTS.PROCESS.COM"
JOHN's DECnet return address, WHARFIN::JOHN, is rewritten by the gateway as:
JOHN@WHARFIN.DNET.EXAMPLE.COM
instead of:
"WHARFIN::JOHN"@HQ.EXAMPLE.COM
which some Internet mailers would have trouble parsing.
For the SMTP-DECnet gateway to work in the SMTP-to-DECnet direction, other hosts on your network must be told that mail for host names under the DECNET-DOMAIN should be sent to the gateway host. If you use Domain Name Service, the easiest way to do this is to set up a wildcard MX record for the DECNET-DOMAIN. In our example, the MX record looks like this:
*.DNET.EXAMPLE.COM. IN MX 0 HQ.EXAMPLE.COM.
This MX record causes other hosts on the Internet to send mail destined for any host under DNET.EXAMPLE.COM to node HQ. The gateway automatically recognizes the DECNET-DOMAIN in the host-name part of the address, rewrites the address to its DECnet form, and sends it through OpenVMS MAIL.
If you do not use DNS, you must add a fully qualified host name for each DECnet node to your host tables. In our example, a return message to user JOHN on node WHARFIN would be addressed to:
JOHN@WHARFIN.DNET.EXAMPLE.COM.
When HQ receives that message, it translates the address to its DECnet form:
WHARFIN::JOHN
and sends the message to that address using OpenVMS MAIL.