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:
pmdf.cnfcreated by the PMDF configuration utility.
lan.rulescreated by the PMDF-LAN configuration utility.
lan.chanscreated by the PMDF-LAN configuration utility.
ln_local_optioncreated by the PMDF-LAN configuration utility.
dispatcher_lan.cnf, created by the PMDF-LAN configuration utility.
126.96.36.199 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
slavekeyword 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.
defragment keyword tells PMDF to reassemble any
fragmented MIME messages before sending them to Lotus Notes.
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 188.8.131.52.
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
184.108.40.206 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
firstname.lastname@example.org 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
email@example.com to a Lotus Notes subscriber associated with the
domainLotus 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 $Ufirstname.lastname@example.org$Cln_local lndomain.example.com $U%DOMAIN@notesmail.example.com
220.127.116.11 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:
18.104.22.168.1 Location of the Option File
Option files are stored in the PMDF table directory
PMDF_TABLE: on OpenVMS or
UNIX and must have names of the form
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
22.214.171.124.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:
valuecan 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
bis the base expressed in base 10 and
vis the actual value expressed in base
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.
126.96.36.199.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 188.8.131.52, 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.optfile. The format of this file is the same as the regular channel header trimming file, as described in Section 184.108.40.206. Whereas regular channel header trimming, as specified in a
channel-name_headers.optfile and described in Section 220.127.116.11, 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.optis 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 email@example.com 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
user@hostis any normal PMDF address and
PMDF-domainis 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
PMDFwill 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-nameis the name of the channel, usually ln_local; (hence on OpenVMS, the file is usually
ln_locate_save_headers.optor on UNIX, the file is usually
/pmdf/table/ln_local_save_headers.optThis 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 18.104.22.168.
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.
22.214.171.124.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
126.96.36.199 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
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
! [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
master-portmust match the values used in the Note initialization file,
notes.inifile for the PNGateOutPort and PNGateInPort options, respectively, as described in Section 188.8.131.52. 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-portand 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-portand 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
slave_portare the ports used by the Lotus Notes channel, and
notes-host-ipis 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.