PMDF System Manager's Guide
Previous Next Contents Index

38.6.5 Telling PMDF About Lotus Notes

Setting up the Lotus Notes channel in PMDF is best performed by running the PMDF-LAN configuration utility (see the appropriate edition of the PMDF Installation Guide for the use of the PMDF-LAN configuration utility) and editing the resulting files, if necessary, to perform any further customization necessary for your site. Each such file is described in detail in later sections:

  1. pmdf.cnf created by the PMDF configuration utility.
  2. lan.rules created by the PMDF-LAN configuration utility.
  3. lan.chans created by the PMDF-LAN configuration utility.
  4. ln_local_option created by the PMDF-LAN configuration utility.
  5. dispatcher_lan.cnf, created by the PMDF-LAN configuration utility.

38.6.5.1 Creating or Editing lan.chans

The first step in installing a Lotus Notes channel is to add the channel definition to the PMDF configuration file---or as is more commonly done, add the channel definition to a file lan.chans which is referenced by (read in to) the PMDF configuration file proper. The channel definition should appear as: 


ln_local slave defragment charset8 ibm850 
Lotus-Notes-RFC-822-domain-name
The slave keyword tells PMDF that this is a channel for which execution is not initiated nor controlled on the PMDF side; rather, for this channel the Lotus Notes server initiates execution of the channel (communicating with the PMDF Dispatcher). Note that a direct connection Lotus Notes channel is a slave channel, regardless of whether it is so marked; in particular, executing the procedures (OpenVMS) or the utilities (UNIX) has no effect for such channels.

The defragment keyword tells PMDF to reassemble any fragmented MIME messages before sending them to Lotus Notes.

The charset8 keyword controls the character set label that gets applied to text attachments containing eight bit characters coming from Lotus Notes, and tells PMDF what eight bit character can safely be decoded in headers of messages going to Lotus Notes. ibm850 is the standard eight bit PC character set used by most Lotus Notes configurations. In any case, however, the character set specified here should correspond to that configured in the Lotus Notes Server initialization file, as described in Section 38.6.4.3.

Lotus-Notes-RFC-822-domain-name should be a valid domain name that you have reserved for use by the Lotus Notes channel. One possible choice is to prepend the official local host name with "notesmail.". For example, in the domain example.com, a reasonable domain name for the Lotus Notes channel might be notesmail.example.com and the channel entry would then appear as 


ln_local slave defragment charset8 ibm850 
notesmail.example.com

38.6.5.2 Creating or Editing lan.rules

Rewrite rules are needed in the PMDF configuration file---or as is more commonly done, in a file lan.rules which is referenced by (read in to) the PMDF configuration file proper. Continuing the example.com example, a start at a set of appropriate rules would be: 


notesmail                $U%notesmail.example.com 
notesmail.example.com    $U@notesmail.example.com
The address user@notesmail.example.com maps to a Lotus Notes subscriber associated with the Lotus Notes domain of the Lotus Notes server running the PMDF Lotus Notes Server Add-in. The address user%domain@notesmail.example.com maps to a Lotus Notes subscriber associated with the domain Lotus Notes domain.

Although this addressing format is sufficient to access all available Lotus Notes domains, it is sometimes useful to associate additional RFC 822 domain names with other Lotus Notes domains. Such an RFC 822 domain name needs to follow the rules governing the naming conventions for domain names specified in RFC 952. For example, the domain name can not contain the underscore character although the Lotus Notes domain name can contain such characters. This can be handled with rewrite rules of the general form: 


lndomain                     $U%lndomain.example.com 
lndomain.example.com         $U%DOMAIN@notesmail.example.com$E$F 
lndomain.example.com         $U%lndomain.example.com@notesmail.example.com$Cln_local 
lndomain.example.com         $U%DOMAIN@notesmail.example.com
These rules associate the domain name lndomain.example.com with the Lotus Notes domain DOMAIN. Although these rules can look complex, their actions are reasonably straightforward: they ensure that the Lotus Notes name for the domain (DOMAIN) is used in the headers of messages queued to the Lotus Notes channel, while the RFC 822 domain name for the Lotus Notes domain (lndomain.example.com) is used in all other cases. Any number of similar rule sets can be used to associate additional domain names with more remote Lotus Notes domains.

38.6.5.3 Lotus Notes Channel Option Files

An option file must be created to control various characteristics of the Lotus Notes channel.

There are two mandatory options:

Their significance and usage, as well as that of additional optional options, are described in Section 38.6.5.3.3. Before setting up the PMDF configuration files, you must know the correct values to specify for this mandatory option. Contact whoever does the Lotus Notes administration tasks at your local site. Impress upon them that if they unilaterally change the Lotus Notes configuration, it will break the mail gateway. Ask them to notify you before making those types of changes so that you can keep the PMDF configuration synchronized.

38.6.5.3.1 Location of the Option File

Option files are stored in the PMDF table directory (PMDF_TABLE: on OpenVMS or /pmdf/table) on UNIX and must have names of the form channelname_option with channelname the name of the channel for which this option file applies. Since the channel name for Lotus Notes is usually ln_local, the full file specification is usually PMDF_TABLE:ln_local_option. (OpenVMS) or /pmdf/table/ln_local_option (UNIX).

38.6.5.3.2 Format of the Option File

Option files consist of several lines. Each line contains the setting for one option. An option setting has the form: 


option=value
value can be either a string or an integer, depending on the option's requirements. If the option accepts an integer value, a base can be specified using notation of the form b%v, where b is the base expressed in base 10 and v is the actual value expressed in base b

Comments are allowed. Any line that begins with an exclamation point is considered to be a comment and is ignored. Blank lines are also ignored in any option file.

38.6.5.3.3 Contents of the Option File

The available options are:

ACCESS_METHOD (3)

This option must be specified and must be set to the value 3 to indicate that this is a direct connection Lotus Notes channel.

BINARY_ENCODING (string)

The BINARY_ENCODING option is optional. This option controls the MIME transfer encoding used when binary Lotus Notes attachments are converted into MIME bodyparts. Possible values include BASE32, BASE64, COMPRESSED-BASE64, BASE85, BINHEX, BTOA, HEXADECIMAL, PATHWORKS, QUOTED-PRINTABLE, X-UUENCODE, and COMPRESSED-UUENCODE. The MIME standard encoding BASE64 is the default and is appropriate in most cases. When such a message is read from a non-MIME aware user agent such as VMS MAIL, you can extract the MIME bodyparts between the MIME boundary markers to a file and use the PMDF DECODE (OpenVMS) or pmdf decode (UNIX) utility to decode it. From a MIME aware user agent such as PMDF MAIL or Pine, just use the appropriate command to extract a message part and it will be automatically decoded (e.g., PMDF MAIL's EXTRACT/PART command). A different encoding can be appropriate when messages always go to another mail system which does not support MIME or the MIME encodings. See also Section 38.6.8.3, describing the LN-TO-MIME-ENCODINGS mapping table, which can be used to specify particular encodings to use on particular sorts of attachments.

DELETE_HEADERS (0 or 1)

Message headers are normally deleted once they have been successfully mapped into corresponding Lotus Notes information. The headers that remain after all conversions have been done can be saved using the SAVE_HEADERS option described below. However, under some circumstances it is useful to be able to skip the deletion step, preserving all header information. The DELETE_HEADERS option provides such a facility. Its normal default value is 1, which means that headers are deleted once converted. If this option is set to 0 converted headers will not be deleted. If the SAVE_HEADERS option is then set to 1, all headers will be saved as a separate text body part. If SAVE_HEADERS is set to 0, the DELETE_HEADERS option will have no discernable effect on message conversion. With DELETE_HEADERS=0 and SAVE_HEADERS=1, the actual headers saved can be further controlled via an optional channel-name_save_headers.opt file. The format of this file is the same as the regular channel header trimming file, as described in Section 2.3.4.59. Whereas regular channel header trimming, as specified in a channel-name_headers.opt file and described in Section 2.3.4.59, is applied when a message is first enqueued to a channel, and can thus have important effects on message handling, header trimming as specified in a channel-name_save_headers.opt is applied after all functional header conversions have been performed and is hence mostly of a cosmetic issue, affecting what headers are saved to the extra header attachment.

DOTS_SPECIAL (0 or 1)

By default, the Lotus Notes Server Add-in only extracts from Lotus Notes messages addressed to the Lotus Notes domain for PMDF. Setting DOTS_SPECIAL=1 causes the Add-in to accept and extract any messages addressed to a domain containing a dot (period)---hence presumably an Internet domain name. I.e,, cause the Lotus Notes Add-in to accept any user@something.something addresses as being directed to PMDF.

LN_DEFAULT_DOMAIN (string)

Required option which specifies a default Lotus Notes domain name to use when the Lotus Notes domain name is omitted from an address. This is usually the name of the Lotus Notes domain to which PMDF connects.

LN_FIRST_PART_ONLY (0 or 1)

The default is 1, which means leave the original message structure alone, as much as possible, on messages going to Lotus Notes. LN_FIRST_PART_ONLY=0 means that for messages without an initial text part, the first text attachment, if there is one, should be promoted to being the "message text".

LN_GATEWAY_DOMAIN (string)

Specifies the name that will be associated with PMDF (and hence with the entire world of RFC 822 addresses to which PMDF provides access). This domain name must be defined on the Lotus Notes server that runs the PNGATE program. In general, Lotus Notes users address mail to PMDF users with an address of the form: 


user@host @ PMDF-domain
where user@host is any normal PMDF address and PMDF-domain is the name of the domain associated with PMDF specified by this option. If no LN_GATEWAY_DOMAIN option is specified in the options file, a domain name of PMDF will be assumed.

LN_MASTER_DELETE (0 or 1)

Specify LN_MASTER_DELETE=0 if you are testing and do not want PMDF messages files to be deleted automatically from the PMDF channel queue by the Lotus Notes channel program. The default is 1. Lotus Notes users will receive an endless stream of duplicate messages if this option is set incorrectly.

LN_SLAVE_DELETE (0 or 1)

Specify LN_SLAVE_DELETE=0 if you are testing and do not want the Lotus Notes messages inbound to PMDF (e.g., the files in the PMDF_API_IN and PMDF_ATT_IN directories) to be deleted automatically by the Lotus Notes channel program. The default is 1. PMDF users will get an endless stream of duplicates messages if this option is set incorrectly.

LN_USE_RESTRICTED (0 or 1)

With LN_USE_RESTRICTED=1, the default, PMDF encodes special characters in addresses going to Lotus Notes using a restricted encoding, and decodes those characters in addresses coming back out of Lotus Notes. Setting this option to 0 disables this encoding.

MASTER_STACK_SIZE (integer)

Specify the stack size available when PMDF is processing messages bound for Lotus Notes. The default value is 524288.

SAVE_HEADERS (0 or 1)

The SAVE_HEADERS option is used to control whether or not RFC 822 headers are retained in an extra attachment for any messages sent to Lotus Notes. A value of 0 is the default, and specifies that no headers are to be retained. A value of 1 places the RFC 822 headers in a text attachment which then becomes the first attachment on the message with a name of HEADERS.TXT. Saved headers can optionally be trimmed as well. Create a header trimming option file in the PMDF table directory with a name of the form channel-name_save_headers.opt where channel-name is the name of the channel, usually ln_local; (hence on OpenVMS, the file is usually ln_locate_save_headers.opt or on UNIX, the file is usually /pmdf/table/ln_local_save_headers.opt This header trimming will be automatically applied as the text attachments containing the headers are written out. For more information on header trimming option files, see Section 2.3.7.2.

SLAVE_STACK_SIZE (integer)

Specify the stack size available when PMDF is processing messages coming from Lotus Notes. The default value is 524288.

SUPPRESS_DELIVERY_RECEIPTS (0 or 1)

The default is 0, meaning that delivery receipt requests will be passed through to Lotus Notes. When SUPPRESS_DELIVERY_RECEIPTS=1, PMDF does not pass delivery receipt requests through to Lotus Notes. Note that as Lotus Notes does not support read receipts, PMDF automatically downgrades read receipt requests to delivery receipt requests on messages going to Lotus Notes; this option applies to those receipt requests as well.

TIMEZONE (string)

Specifies the Lotus Notes time zone.

38.6.5.3.4 Example Option Files

This is an example option file for the ln_local channel. The file's name must be ln_local_option and the file must be stored in the PMDF table directory, i.e., PMDF_TABLE:ln_local_option. on OpenVMS or /pmdf/table/ln_local_option on UNIX. 


ACCESS_METHOD=3 
LN_GATEWAY_DOMAIN=PMDF 
LN_DEFAULT_DOMAIN=EXAMPLE

38.6.5.4 Dispatcher Configuration

The direct connection Lotus Notes channel operates under the control of the Lotus Notes Server, with the Lotus Notes server instructing PMDF, via the PMDF Dispatcher, when to run the channel. So the PMDF Dispatcher must be configured to handle this service, and a PORT_ACCESS mapping should be added ensuring that only the authorized Lotus Notes Server can connect.

Edit your PMDF Dispatcher configuration file, PMDF_TABLE:dispatcher.cnf (OpenVMS) or /pmdf/table/dispatcher.cnf (UNIX), and look for the reference to the file dispatcher_lan.cnf and remove the comment character from the first column. If there is no such reference, add the line on OpenVMS 


<PMDF_TABLE:dispatcher_lan.cnf
or on UNIX 


</pmdf/table/dispatcher_lan.cnf

The dispatcher_lan.cnf file, which was created by the PMDF-LAN configuration utility, on UNIX should look like: 


! 
[SERVICE=LN_LOCAL_SLAVE] 
PORT=slave-port
IMAGE=/pmdf/bin/lnplc_slave 
LOGFILE=/pmdf/log/ln_local_server_slave.log 
MIN_PROCS=1 
MAX_PROCS=1 
MIN_CONNS=1 
MAX_CONNS=1 
PARAMETER=channel=ln_local 
! 
[SERVICE=LN_LOCAL_MASTER] 
PORT=master-port
IMAGE=/pmdf/bin/lnplc_master 
LOGFILE=/pmdf/log/ln_local_server_master.log 
MIN_PROCS=1 
MAX_PROCS=1 
MIN_CONNS=1 
MAX_CONNS=1 
PARAMETER=channel=ln_local
or on OpenVMS should look like: 


! 
[SERVICE=LN_LOCAL_SLAVE] 
PORT=slave-port
IMAGE=PMDF_EXE:lnplc_slave.exe 
LOGFILE=PMDF_LOG:ln_local_server_slave.log 
MIN_PROCS=1 
MAX_PROCS=1 
MIN_CONNS=1 
MAX_CONNS=1 
PARAMETER=channel=ln_local 
! 
[SERVICE=LN_LOCAL_MASTER] 
PORT=master-port
IMAGE=PMDF_EXE:lnplc_master.exe 
LOGFILE=PMDF_LOG:ln_local_server_master.log 
MIN_PROCS=1 
MAX_PROCS=1 
MIN_CONNS=1 
MAX_CONNS=1 
PARAMETER=channel=ln_local
where the slave-port and master-port must match the values used in the Note initialization file, notes.ini file for the PNGateOutPort and PNGateInPort options, respectively, as described in Section 38.6.4.3. Note that MAX_CONNS and MAX_PROCS must be set to 1. Note that it is essential to set up a PORT_ACCESS mapping to control what systems can connect to the master-port and take messages destined for Lotus Notes users. Otherwise, if you do not set up such a mapping, you have a potential security problem; by default, any system can connect to the master-port and take messages destined for Lotus Notes users.

An overview of the PORT_ACCESS mapping can be found in Section 23.2.1; more generally, the PMDF mapping file itself is discussed in Chapter 5. To prohibit irregular access to the Lotus Notes channel ports, you will need to have entries such as 


PORT_ACCESS 
 
  TCP|*|master-port|notes-host-ip|*   $Y 
  TCP|*|slave-port|notes-host-ip|*    $Y 
  TCP|*|master-port|*|*               $N 
  TCP|*|slave-port|*|*                $N
where master_port and slave_port are the ports used by the Lotus Notes channel, and notes-host-ip is the TCP/IP address of the Notes server (in dotted decimal notation). This precludes any other system connecting to the PMDF server on these ports.

Previous Next Contents Index