PMDF System Manager's Guide
Previous Contents Index

26.5.1 Setting Up the Channel

There are two steps in setting up a pipe channel: (1) adding the channel to the PMDF configuration file, and (2) setting up the channel option file, pipe database or (UNIX only) profile database entries to specify particular commands for particular user or host addresses.

26.5.1.1 Adding the Channel to the Configuration File

Note
While you can configure multiple pipe channels, in general you only need to configure a single pipe channel.

A message to be processed by a pipe channel is usually routed to the channel via a combination of an alias and rewrite rules. For instance, the system example.com might want all mail for the addresses info-pmdf@example.com and gripes@example.com to be routed to a pipe channel. This could be accomplished with the alias file entries 


info-pmdf: info-pmdf@pipe.example.com 
gripes: gripes@pipe.example.com
where pipe.example.com is in turn a host name associated with a pipe channel via rewrite rules. For instance, 


pipe.example.com         $u%pipe.example.com@PIPE-DAEMON

So, to configure a pipe you need to determine the host names, pipe1.domain, pipe2.domain, ... which you want to use. Once you have determined these, add them to the rewrite rules section of your PMDF configuration file: 


pipe1.domain          $u%pipe1.domain@PIPE-DAEMON 
pipe2.domain          $u%pipe2.domain@PIPE-DAEMON 
...                   ...
Then, to the end of your PMDF configuration, add the definition of the pipe channel itself: 


 
pipe 
PIPE-DAEMON
Be sure to include a blank line before and after this channel definition.

On UNIX, the pipe channel normally runs as user pmdf. So on UNIX, if you want the pipe channel to run as some other user, you can use the user channel keyword to specify the desired username. Note that the argument to user is normally forced to lowercase, but original case will be preserved if the argument is quoted.

At this point, the pipe channel has been added to the configuration. However, it cannot be used until you create a channel option file, or a pipe database, or (UNIX only) define and set delivery methods for pipe channel addressees, as described next.

26.5.1.2 Profile Database Entries for Pipe Channel Addressees (UNIX only)

On UNIX, before looking in the channel database or option file, a pipe channel first queries the PMDF profile database checking whether there is a delivery method set for the addressee. Only if there is no such entry is the pipe database or pipe option file consulted.

A PMDF profile database delivery method entry for a pipe channel addressee is similar to that for a local (L) channel addressee, except that the pipe channel domain is used. For instance, 


# pmdf profile
profile> set delivery mailworks -user=jane.doe@pipe.example.com

26.5.1.3 Pipe Database

Rather than placing user or host addresses and corresponding commands in a pipe channel option file, described below in Section 26.5.1.4, or on UNIX using profile database entries for users, described above in Section 26.5.1.2, user or host entries can be placed in the PMDF pipe database. The pipe database can be particularly useful for sites with large numbers of entries (more efficiently stored in a database than in an option file), or for sites where the user addresses and command strings are rather long (in which case a "long" database created with the /LONG_RECORDS (OpenVMS) or -long_records qualifier (UNIX) can be used).

The pipe database is referenced via the PMDF_PIPE_DATABASE logical (OpenVMS) or PMDF tailor file option (UNIX), hence it is usually PMDF_TABLE:pipe.dat on OpenVMS or /pmdf/table/pipedb.* on UNIX. This database is a regular PMDF CRDB (OpenVMS) or pmdf crdb (UNIX) database created from a text input file.

The format of entries in the input text file should be: 


address1    command1
address2    command2
...                     ...
where the addresses, address1, address2, ..., can be either of the form user@host or host. PMDF probes first for user-specific entries and only if no user-specific entry is found, will PMDF then look for a host entry. See Section 26.5.2 below for an additional discussion of the order in which probes of various forms are made to the various possible entry sources.

On OpenVMS, such an input text file would be turned into a pipe database using the commands: 


$ PMDF CRDB input-file-spec pipe.tmp
$ RENAME pipe.tmp PMDF_PIPE_DATABASE
On UNIX, use the commands: 


# pmdf crdb input-file-spec PMDF_PIPE_DATABASE

26.5.1.4 Option Files

Unless you have a pipe database, or have established delivery methods for pipe channel addressees, each pipe channel must have an option file. If there are no delivery methods set in the PMDF profile database, and no option file nor pipe database, then the channel will not operate.

The commands to execute for each envelope recipient address presented to the channel are specified in the PMDF profile database, in the pipe database or in the pipe channel's option file. If an address does not appear in one of these locations, then an error notification is sent back to the message originator.

Pipe channel option files are stored in the PMDF table directory and have names of the form x_option, where x is the name of the pipe channel to which the option file applies. (In most instances, the file name will be pipe_option; i.e., PMDF_TABLE:pipe_option. on OpenVMS or /pmdf/table/pipe_option on UNIX.)

To process the address user@host, the pipe channel first probes the option file for an entry of the form 


user@host=command
If no matching entry is found, the channel next probes the option file for an entry of the form 


host=command

If still no matching entry is found, then the recipient address is deemed bad and an error notification is sent back to the message originator. See Section 26.5.2 below for an additional discussion of the order in which probes of various forms are made to the various possible entry sources.

If, however, a probe does find a matching entry, then the specified command, command, is executed. Prior to being executed, any occurrences of the phrase %s appearing in command are replaced with the name of the temporary file containing the message to be processed. It is important that the command to be executed neither delete nor otherwise alter the temporary message file as it can be needed for further pipe channel recipients of the same message. If disruption of the message file cannot be prevented, then mark the channel with the single channel keyword.

The command to be executed will be run by a subprocess of the process running the pipe channel. As such, it will be running with the privileges of the PMDF processing account (usually the SYSTEM account on OpenVMS or pmdf account on UNIX). See Section 26.5 for a description of the exit or completion codes with which the command should exit the subprocess.

Note
As with any PMDF option file, it is important that the option file not be world writable. This is especially true of pipe channel option files.

In addition to the command entries in the pipe channel option file, there is one additional general option available:

SHELL_TIMEOUT (integer; UNIX only)

The SHELL_TIMEOUT option can be used to control how long in seconds the channel will wait for a shell command to complete. Upon such time outs, the message will be returned back to the original sender with an error message along the lines of "Timeout waiting for ...'s shell command ... to complete". The default value is 600 (corresponding to 10 minutes).

Previous Next Contents Index