Running Your Programs

Creating a custom channel

Channel programs written with the Sun Internet Mail SDK will in general be used to create custom channel's which serve a site-specific need not covered by the default SIMS product. This section briefly explains how to create and configure a custom channel. These operations are described in the SIMS Reference Manual. Please refer to it for a precise syntax definition.
In /etc/opt/SUNWmail/imta/imta.cnf, define the channel in the second half of the file. For example, consider a new channel called custom.
	!
	! custom channel built with SDK
	custom logging charset7 US-ASCII charset8 ISO-8859-1
	custom-daemon
	[blank-line]
The logging keyword allows the logging of each message enqueued and dequeued from this channel in the log file (/var/opt/SUNWmail/imta/log/mail.log_current). The charset7 and charset8 keywords will add a Content-type:TEXT/PLAIN header line if no content-type is defined in the message. They also add a MIME Version: 1.0 header if it doesn't exist. See the SIMS Reference Guide for more details about channel keywords.
In the first half of the configuration file, create a rewrite rule associated with the custom channel. Example:
	!
	! rewrite rules associated with custom channel
	xyz.com  $E$U%custom.xyz.com@custom-daemon
	!
After the configuration file is changed, the MTA must be restarted to load the changes: # imta restart At this point, messages addressed to user@xyz.com will be routed to the custom channel and dequeued by the master program associated with this channel. The next section explains how to register channel programs.






Configuring channel programs to be run automatically


The SIMS IMTA job controller daemon automatically invokes 
the master program of a channel whenever a message is enqueued
to this channel.

It's possible to configure the job controller to invoke your 
program custom_master whenever a message is enqueued
to the channel custom.  To do this, edit 
/etc/opt/SUNWmail/imta/job_controller.cnf and append 
the following block:

	!
	! declaration of custom's master program.
	[CHANNEL=custom]
	master_command=/opt/SUNWmail/imta/lib/custom_master


For an exact definition of the syntax of this configuration file, 
please refer to the SIMS reference guide.





Associating local users with a custom channel


In SIMS, the user LDAP attribute maildeliveryoption defines the
list of delivery mechanisms this user is using to receive mail, e.g.
message store delivery (mailbox), 
pipe delivery program (program), etc.  
In other words, the maildeliveryoption
value mailbox causes mail addressed to this email user to be
enqueued to the message store channel, and the value program
causes his/her mail to be enqueued to the pipe channel.

As well as a mail delivery option, the routing of messages towards a
channel involves one or more rewrite rules.  In the case of the 
message store channel (sims-ms), 
the mail delivery option mailbox gives the user
the internal address:
	user@sims-ms.mailhost


This address is then matched by the rewrite rule
	sims-ms.mailhost  $E$U@sims-ms-daemon


and the message is enqueued to the message store channel (sims-ms).

A similar thing can be done with your own custom channel;
setting the maildeliveryoption attribute to
 
	C:custom
 
gives the user
the internal an internal address equal to:
	user@custom.mailhost


And to enqueue mail for this user to the custom channel,
an equivalent to the following rewrite rule has to be created:
	custom.mailhost  $E$U@custom-daemon






Running privileges


Not surprisingly, the use of the Sun Internet Mail SDK
requires specific privileges. 
Indeed, were these privileges not required, then anyone could read messages out
 of SIMS's message queues and send fraudulent mail messages. 
Unpriviledged programs should exit immediately, and possibly restart as a
privileged user. 

A program which will be enqueuing or dequeuing messages from or to the SIMS IMTA 
message queues must be run by the SIMS administrator's UNIX account (inetmail by default). 
If the program is to be run by users other than this one, 
then it must have the setuid attribute. 

Note that if the master program is invoked by the IMTA job controller,
it will automatically be run with the right priviledges.





 Debugging


The Sun Internet Mail SDK provides debugging facilities which may help 
in tracking down unusual behavior.  A debugging trace may be generated
by using 
imta_debug.

Debugging can by turned on by editing the configuration.  The channel keywords
master_debug and slave_debug 
shall be used to turn on debugging
on the dequeue side or enqueue sidfe respectively.  Additional
debugging information may be obtain by setting the MM_DEBUG and
DEQUEUE_DEBUG options in 
/etc/opt/SUNWmail/imta/option.dat.
Please consult the SIMS Reference Guide for more info.

Alternatively, the function
imta_set_debug
may be called to enable debugging output for either enqueuing or dequeuing 
operations.  In programs using the Message Dequeue API, 
imta_set_debug
should be called after 
immd_init.

The debugging information generated from both the calling code and the 
library is output into
the channel debug output file, which is created in 
/var/opt/SUNWmail/imta/log/. 

The file name syntax is as follows:
	channel_direction.log_XXXXXXXXXXX

where channel is the name of the channel, direction is the "master" for a master program and "slave" for a slave program, and the X's are a random string. 





 Environment variables


The Sun Internet Mail SDK uses internally the 
environment variable PMDF_CHANNEL.
Therefore, it must not be used
by programs using the Sun Internet Mail SDK.  Doing so 
would cause channel programs not to work properly.










Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.