Version 5.4 |
||||||||||||||||||||||||||||||||
|
|
The CommuniGate Pro PIPE module creates the Submitted folder inside the CommuniGate Pro base folder.
The PIPE module scans this folder periodically, and processes the files with the .sub file name extension. When such a file is found, the module copies it into a message queue file and submits that file to the Server kernel for processing.
The .sub text files should contain messages in the RFC822 format. The module uses the data in the RFC822 header fields to compose the message envelope.
If processing of a .sub file fails (for example, if the file does not have any recipient address), the module places a record into the System Log, and changes the file extension to .bad.
If a .sub file is submitted successfully, the file is deleted from the Submitted folder.
Because of the way the PIPE module processes the Submitted folder, it is recommended to compose messages in a different file directory and then move the composed .sub files to the Submitted folder, or to compose messages in the Submitted folder, in files with the .tmp file name extension, and then change the file name extension to .sub.
Messages submitted via the PIPE module are marked as "received from a trusted source", so they can be relayed without restrictions.
The Submitted folder is used for Legacy Mail Emulation.
The PIPE module accepts all messages directed to the pipe domain.
The local part of the message address specifies the external application to launch. The part can contain parameters, and can be enclosed into the quotation marks.
To limit the set of applications that can be started via the PIPE module, the external application directory is specified as one of the PIPE module settings. The application names specified in message addresses can not include the slash (/) or the backslash (\\) symbols, and they cannot start with the dot (.) symbol, and it specified the name of the application (program) file in the external application directory.
The message text (including the message headers and the message body) is passed to the
external application as its standard input.
Note: the application must read the entire stdin data stream, otherwise
message processing fails.
When the external application completes, the PIPE module reads and discards the application standard output. Make sure that your application does not write anything to its standard output, so it is not blocked when the communication channel (pipe) buffer between the application and the Server is full.
When the external application completes, the PIPE module reads its standard error channel. If it is not empty, the message delivery fails, and the text written to standard error is sent as an error report to the message sender.
In order to allow several PIPE processors to deliver messages simultaneously,
the PIPE module creates a separate queue for each message it has to deliver. If you want to
serialize processing, you can use the following form of the PIPE address:
"queue[name] application parameters"@pipe
All messages directed to these addresses will be placed into the name queue, and
a single PIPE processor will send the enqueued messages to the application(s) specified
in those addresses. You can use any alphanumeric string as a queue name, and you can
specify as many queues as you need.
For PIPE addresses that do not have the queue[name] prefix, the PIPE module creates separate queues with numeric names.
The message text (the header and the body) is sent to the task as that task standard input (stdin).
An application name can be prefixed with the [FILE] tag:Note: The beginning of a Queue file contains the service information (envelope, options, etc.). The application should ignore this information skipping the file data till the first empty line. The message itself starts after that first empty line in the Queue file.
Note: Header fields added to the message by Server-wide and Cluster-wide Rules are not stored in the message Queue file, they are sent via the task standard input.
Note: this prefix should not be used on MS Windows and IBM OS/2 platforms, as the Server keeps the message file open, making it impossible for an external Task to read the file.
An application name can be prefixed with the [RETPATH] tag:An application name can be prefixed with the [STDERR] tag (see below).
An application name can have several prefix strings, and they can be specified in any order. If several of [FILE], [RETPATH], and [RCPT] prefix strings are specified, the -f flag and its parameter are added first, followed with the -p flag and its parameter, followed with the -r flag and its parameter.
If the [STDERR] prefix is specified and the external application completes sending some data to its standard error channel, the standard error data is used to compose the error report text.
Use the WebAdmin Interface to configure the PIPE module. Open the Queue pages in the Settings realm, then open the PIPE page.
In emergency situations you may need to process an additional Queue directory without stopping your server. These situations include a server hardware failure when the rescued Queue files should be processed with some other, already running server.
To process an additional Queue directory, move it to the base directory of a running server as the ForeignQueue directory. If you prefer to use symbolic links, make sure that the Queue and ForeignQueue directories are created on the same file system.
Every 3 minutes the PIPE module checks if the ForeignQueue directory exists in the server base directory. If the ForeignQueue directory is found, the module moves all .msg files from the ForeignQueue to the Queue directory (it can rename the files in the process), and deletes all .tmp files found in the ForeignQueue directory. Files with other extensions are left in the ForeignQueue directory.
All moved .msg files are submitted to the Server kernel, into the ENQUEUER queue, and the Server starts to process them in the same way it processes all submitted messages.
When the scanning process is completed, the ForeignQueue directory can be removed from the base directory.