Configuring Cloudmark with Sun Java System Messaging Server

This technical article describes how to install, configure, and verify Cloudmark Anti-Abuse Client (CAAC) with Sun Java System Messaging Server.

The component products covered by this technical article are:
* Sun Java System Messaging Server 6.3 and Sun Java System Messaging Server 6 2005Q4
* Cloudmark Anti-Abuse Client (CAAC) 1.3.1.4

This technical article contains the following sections:
{toc:minLevel=2|maxLevel=2}

h2. Overview of Cloudmark Anti-Abuse Client

The Cloudmark Anti-Abuse Client (CAAC) consists of the following two major components:
* {{cmae_server}}. Daemon that receives email messages and returns a score for each one. The score indicates whether the message is abusive or legitimate.
* CAAC client. A Messaging Server plug-in that passes messages from Messaging Server to the {{cmae_server}} daemon, then passes the resulting verdict from the {{cmae_server}} daemon to Messaging Server.

The high-level steps to install and configure Cloudmark for Messaging Server are:
# Obtaining the Cloudmark software
# Installing the Cloudmark server daemon
# Installing the Cloudmark client plug-in
# Choosing a per-channel optin or per-user optin configuration for Messaging Server
# (Optional) Changing the default Cloudmark server configuration
# (Optional) Changing the default Cloudmark client configuration
# Configuring Cloudmark micro-updates{anchor:gdxwy}

h2. Installing the Cloudmark Server and Client

Use the steps in this section to install the Cloudmark server and client software components.{anchor:gdxwa}

h3. To Install the Cloudmark Server
# Obtain the latest Cloudmark software release from the following location:
\\
[http://www.cloudmark.com/serviceproviders/authority/sunjms/]
# Install the server software to a new directory on the Messaging Server host where Cloudmark is to be deployed.
For example:
{code}
CLOUDMARK_SERVER_HOME=/opt/CloudmarkAA-server-_n.n.n.n_
{code}
# Install the SpamDNA package by untarring the {{SpamDNA\-}}_version_{{\-SunOS\-}}_arch_-{{101112.tar.gz}} file within the {{$CLOUDMARK_SERVER_HOME}} directory.
# Run the {{setup_server}} script.
{code}
$CLOUDMARK_SERVER_HOME/bin/setup_server root
{code}
\\
The script performs the following actions:
* Sets file permissions and file ownership to prevent the MTA SDK from giving errors about unsafe ownership or execution privileges
* Copies the {{*.sample}} files into their correction location (if the {{cartridge.cfg}} or {{whitelist.cfg}} files are not present)
* Creates a new {{cmaed}} script in the {{$CLOUDMARK_SERVER_HOME/bin}} directory
\\
The {{cmaed}} script is an {{init.d}} type of start and stop script. You can copy the script to any convenient location. In the script, the {{CMAE_HOME}} variable is set to {{/}}_path_{{/}}_to_{{/CloudmarkAA-server}}_.n.n.n.n_.
{info:title=Note}
You cannot move the server installation after you execute the {{setup_server}} script. To relocate the server installation, run the {{setup_server}} script in the new location.{anchor:gdxvs}
{info}

h3. To Start and Stop the Cloudmark Server

Use the following commands to start and stop the server. You can copy the {{cmaed}} script to {{/etc/init.d/cmaed}} then create the appropriate links from within {{/etc/rc.3}} to automatically start or stop the {{cmae_server}} whenever the Messaging Server host restarts.
# To start the Cloudmark server:
{code}
$CLOUDMARK_SERVER_HOME/bin/cmaed start
{code}
# To stop the Cloudmark server:
{code}
$CLOUDMARK_SERVER_HOME/bin/cmaed stop
{code}
{info:title=Note}
Make sure that the {{CMAE_HOME}} variable is set to {{/}}_path_{{/}}_to_{{/CloudmarkAA-server}}_.n.n.n.n_.
{info}

h3. To Install the Cloudmark Client
# Install the client software ({{CloudmakrAA-...tar.gz}}) file to a new directory on the Messaging Server host where it is to be deployed.
For example:
{code}
CLOUDMARK_CLIENT_HOME=/opt/CloudmarkAA-SunJMSbmi-_n.n.n.n_
{code}
# Edit the {{$CLOUDMARK_CLIENT_HOME/bin/setup}} script and set the value of {{SUNJMS_HOME}} to the location of your Messaging Server installation.
For example, set {{SUNJMS_Home}} to the {{/opt/SUNWmsgsr}} directory if you used the default Messaging Server directory for installation.
{info:title=Note}
Incorrectly setting this value causes the plug-in to not load correctly.
{info}
# {anchor:gdxyv} Run the {{bin/setup}} script.
{code}
$CLOUDMARK_CLIENT_HOME/bin/setup
{code}
The script places some necessary symlinks in the {{$SUNJMS_HOME/lib}} directory that refer to the necessary libraries in the {{$CLOUDMARK_CLIENT_HOME/lib}} directory:
{code}
/opt/SUNWmsgsr/lib/libcmae.so.2.0 ->
/opt/SUNWmsgsr/CloudmarkAA-SunJMSbmi-client-n.n.n.n/lib/libcmae.so.2.0
/opt/SUNWmsgsr/lib/libcmaeclient.so.2.0 ->
/opt/SUNWmsgsr/CloudmarkAA-SunJMSbmi-client-n.n.n.n/lib/libcmaeclient.so.2.0
{code}
# Verify that these links are formed correctly. If not, make sure that the setup script contains the correct value for {{$SUNJMS_HOME}} then run the script.
# Edit the {{$SUNJMS_HOME/config/option.dat}} file.
This file indicates to the server how to find the Cloudmark plug-in and what action to take given a legit or spam verdict.
{code}
!
! Enabling the system to find the cloudmark configuration file and plugin
spamfilter1_config_file=/path/to/cloudmarkaa.cfg
spamfilter1_library=/path/to/libcloudmarkaa.so
spamfilter1_optional=1
spamfilter1_null_action=data:,discard
spamfilter1_null_optin=nofilter
ldap_optin1=_name of LDAP opt-in attr_
{code}
{info:title=Note}
The {{spamfilter1_null_optin}} parameter specifies that the plug-in does not filter mail for any user with a value of {{*nofilter*}} for your installation's _optinAttribute_. If your installation uses a different value for this, change the value of {{spamfilter1_null_optin}} accordingly.
{info}
# Choose a per-channel opt-in or per-user opt-in configuration:
#* Per-user opt-in: Edit the {{$SUNJMS_HOME/config/option.dat}} file as follows:
\\
{{LDAP_optin1=}}_optinAttribute_
\\
Replace _optinAttribute_ with the LDAP opt-in attribute you want to use to enable filtering in your Messaging Server deployment. Make sure that it is the same attribute used by your Messaging Server deployment.
#* Per-channel opt-in: Edit the {{$SUNJMS_HOME/config/imta.cnf}} file and add {{*destinationspamfilter1optin spam*}} to the {{ims-ms}} configuration line. This enables filtering for all users.
\\
For example:
{code}
! ims-ms
ims-ms defragment subdirs 20 notices 1 7 14 21 28 backoff
"pt5m" "pt10m" "pt30m" "pt1h" "pt2h" "pt4h" maxjobs 2 pool I
MS_POOL fileinto $U+$S@$D destinationspamfilter1optin spam
{code}
# Recompile the Messaging Server configuration:
{code}
imsimta cnbuild
{code}
# Restart the following Messaging Server processes:
{code}
imsimta restart job_controller
imsimta restart dispatcher
{code}
# In a pre-production or test environment, you can run the following command to combine Step 7 and Step 8:
{code}
imsimta refresh
{code}{anchor:gdxwe}

h2. Configuring Cloudmark Anti-Abuse Client

You configure the {{cmae_server}} and the plug-in client through directives contained in configuration files.{anchor:ggfin}

h3. Configuration Directives

The following two tables list the Cloudmark server and client directives.

h5. {anchor:ggfbi} Table 1 cmae_server.cfg Configuration Directives
||Directive ||Description ||Default Value ||
|address |IP address or host name on which to listen |{{all}} |
|port |Port number on which to listen |{{2703}} |
|workers |Number of worker threads; set the number of worker threads to be approximately equal to the number of CPU cores that are available |{{4}} |
|max clients |Maximum number of simultaneous client connections |{{0}} (no limit) |
|max message size |Maximum size of message to accept from the client |{{0}} (no limit) |
|idle timeout |Number of seconds of inactivity, after which the server disconnects from the client |{{0}} (no timeout) |
|server log priority |Minimum event priority to log |{{NOTICE}} |
|server log file |File name of the server log |{{null}} (log to syslog) |
|server syslog facility |Syslog facility |{{daemon}} |
|cartridge code dir |Cartridge code directory |{{.}} |
|cartridge config dir |Cartridge configuration directory |{{.}} |


h5. {anchor:ggfby} Table 2 cloudmarkaa.cfg Configuration Directives
||Directive ||Description ||Default Value ||
|HOST |Load balancing can be provided between the Cloudmark plug-in and the back-end filtering servers. This value can be either the host name or the dotted quad IP address of the server or the load balancer. It might be more efficient to use the dotted quad IP address rather than the host name, depending on the resolver library. |N/A |
|PORT |This is the port number that the load balancer forwards to the back-end CMAE servers. Note: This directive is ignored in release 1.1.0.3. |{{2703}} |
|LOG_DEST |Set the destination to which logging information from the plug-in is written:
* {{= <empty>}}
\\
Write everything to {{tcp_local_slave.log-*}}. This creates one file per email.
* {{= stdout}}
\\
Write everything to {{tcp_smtp_server.log-*}}. All of the logs appear in the same file, but the writing is heavily buffered.
* {{=}} _/path/to/file.log_
\\
Write to named file. The output buffer is flushed after every write so there is no delay in logging. |{{= <empty>}} |
|LOG_FORMAT |After successful filtering, a single INFO summary is appended to the log. This line can consist of arbitrary text plus the tokens listed in [Substitution Tokens|#ggfkb]. |{{score=%p cat=%c subcat=%s ip=%I ((subject=%H)) ((analysis=%a))}} |
|LOG_LEVEL |Set the log level at your discretion:\\1 FATAL\\2 ERROR\\3 WARNING\\4 INFO\\5 DEBUG (Least detailed debug logging)\\6 DEBUG2\\7 DEBUG3\\8 DEBUG4\\9 DEBUG5 (most detailed debug logging) |{{info}} |
|SPAM_THRESHOLD |Set this to 80. The plug-in internally generates scores between 0 and 100 inclusive. Any score greater than or equal to 80 should be considered spam. |{{80}} |
|MAX_SESSIONS |The number of simultaneous client sessions to keep open between the host process and the {{cmae_server}} daemon. The {{tcp_smtp_server}} that hosts the plug-in can create up to ten replicas of itself, where each replica has MAX_SESSIONS connections. Depending on traffic, set this to a value between 10 and 100. |{{10}} |
|MAX_SESSION_MAILS |Maximum number of email messages processed per session. Restart when this number is reached. This allows the load balancer to find a new machine if the load is becoming unbalanced. |{{1000}} |
|MAX_SESSION_LIFE |Maximum number of seconds per session. Restart when this many seconds have elapsed. Again, this allows the load balancer to rebalance the traffic. |{{300}} |
|MAX_MESSAGE_SIZE |The maximum number of bytes of the message, including headers and body, that the {{cmae_server}} accepts.When this parameter is set to zero (0), the client sends the number of bytes specified in the {{cmae_server}} “max message size” parameter. However, it is more efficient to configure an upper limit on the client side. |{{512000}} |
|CONNECT_TIMEOUT |Seconds to wait for the filter to connect to the back-end server.The specified value must be in the range 0–100. When the value is set to 0, the client uses the default TCP timeout. |{{10}} |
|VIRUS_CATEGORIES |You must specify the list of Cloudmark categories that should be mapped to a virus. This must be a comma or space separate list of category numbers. Consult the {{*.cats}} file within the {{cmae_server}} {{etc/micro_updates}} directory. |{{7}} |
|SPAM_VERDICT |This is the verdict that is returned in the event that an email is determined to be spam. This string may contain substitution tokens listed in [Substitution Tokens|#ggfkb]. If this string is unspecified, the plug-in will return a null value |<empty> |
|LEGIT_VERDICT |This is the verdict string that returned in the event that an email is determined to be legitimate. If this parameter is undefined, the return value is the default destination. This string may contain substitution tokens listed in [Substitution Tokens|#ggfkb]. |<empty> |
|VIRUS_VERDICT |This is the verdict that is returned in the event that an email is determined to be a virus. This string may contain substitution tokens listed in [Substitution Tokens|#ggfkb]. If this string is unspecified, the plug-in will return a null value. |<empty> |
{anchor:ggfkb}

h3. Substitution Tokens

The following two tables list the substitution tokens.

The SPAM_VERDICT, LEGIT_VERDICT, and VIRUS_VERDICT configuration keys can include the following substitution tokens.

h5. {anchor:ggfhx} Table 3 Verdict Substitution Tokens
||Token ||Description ||
|{{%p}} |Percent score on range \[0–100\] |
|{{%a}} |Analysis string |
|{{%c}} |Category number |
|{{%C}} |Category name |
|{{%s}} |Sub-category number |
|{{%S}} |Sub-category name |
|{{%r}} |Rescan flag (set to {{1}} if it would benefit from rescan) |


The LOG_FORMAT configuration key can use the following substitution tokens.

h5. {anchor:ggfis} Table 4 Log Format Substitution Tokens
||Token ||Description ||
|{{%p}} |The percentage score of the email (0–100) |
|{{%r}} |Rescan flag (set to {{1}} if it would benefit from rescan) |
|{{%a}} |Analysis string |
|{{%c}} |Cloudmark category number |
|{{%C}} |Cloudmark category name |
|{{%s}} |Cloudmark sub-category number |
|{{%S}} |Cloudmark sub-category name |
|{{%x}} |Bytes of message sent to {{cmae_server}} |
|{{%l}} |Latency of request to the {{cmae_server}} (milliseconds) |
|{{%F}} |Address in the From field |
|{{%R}} |Comma-separated recipient list |
|{{%I}} |Connecting IP address |
|{{%H}} |Contents of the Subject field |
|{{%M}} |Message ID, if supplied. Messaging Server might strip this header, making it unavailable to the plug-in. |
{anchor:gdxwl}

h3. To Configure the Cloudmark Server
# The default configuration file for {{cmae_server}} is {{cmae_server.cfg.}} Make any necessary changes for your deployment to this file.
\\
See [Table 1|#ggfbi] for a list of directives that you can edit.
# Check the number of file descriptors available to a process:
#* bash/sh: {{ulimit}} {{-n}}
#* csh/tcsh: {{limit descriptors}}
# If not already set to 32768, change the file descriptors to 32768:
#* bash/sh: {{ulimit}} {{-n}}{{32768}}
#* csh/tcsh: {{limit descriptors 32768}}
\\
If the number of clients attempting to connect to the server is greater than the number of available file descriptors, the performance of the {{cmae_server}} daemon is affected.{anchor:ggevk}

h3. To Configure the Cloudmark Client
# The configuration file for the Cloudmark client is {{etc/cloudmarkaa.cfg}}. Make any necessary changes for your deployment to this file.
\\
See [Table 2|#ggfby] for a list of directives that you can edit.
# Use the following equation to approximate the upper limit on MAX_SESSSIONS.
{code}
server_max_clients x N_cmae_hosts / N_smtp_replicas x N_client_hosts
{code}
\\
where:
#* {{server_max_clients}} is the value of “max clients” server configuration directive. See [Table 1|#ggfbi] for more information.
#* {{N_cmae_server_hosts}} is the number of server hosts running CMAE.
#* {{N_smtp_replicas}} is the number of instances of active SMTP servers per host.
#* {{N_client_hosts}} is the number of hosts running the CMAE client plug-in.{anchor:gdxwt}

h3. To Configure Micro-updates

Micro-updates are small, incremental updates to the Cloudmark Cartridge, which provides current data from the Cloudmark network. Micro-updates are automatically downloaded at an interval defined by Cloudmark to provide effective filtering of the latest spam, phishing, and virus attacks.

You must configure the location of the Cloudmark Cartridge with the {{cartridge code dir}} and {{cartridge config dir}} configuration keys. See [To Configure the Cloudmark Server|#gdxwl].

To configure the Cartridge itself, see the _Cloudmark Cartridge Installation and Administration Guide_.
* The configuration file for the micro-updates settings, {{catridge.cfg}} includes the following directives. If the {{cartridge.cfg}} file is not available, the default settings are applied. Make any necessary changes for your deployment.
||Directive ||Description ||Default Value ||
|micro-update hostname |Specifies the host name to connect to when downloading micro-updates; downloads over port 80 or 25. |{{micro-updates.cloudmark.com}} |
|micro-update interval |Specifies how frequently (in hours) to check for the latest micro-update; if set to {{auto}}, the software checks for deltas on a periodic basis. |{{auto}} |
|micro-update timeout |Specifies the timeout period (in seconds) for HTTP requests used when checking for micro-updates. |{{60}} |
|enable micro-updates |Enables ({{yes}}) or disables ({{no}}) the download of micro-updates over the network from the micro-update host name. |{{yes}} |
|http proxy |Specifies the host name or IP address of the HTTP proxy for connecting to the Cloudmark micro-updates services. |n/a |
|micro-update cache path |Specifies the path to the directory that micro-updates data files are stored in on the local server. |_path_{{/micro-updates}} |
{anchor:gdxxa}

h2. Troubleshooting the Cloudmark Installation

Use this section if you encounter problems with your Cloudmark installation.{anchor:gdxvm}

h3. Troubleshooting the Cloudmark Client

Use the following tips to troubleshoot your client installation:
* If Messaging Server is not installed in the default location, make sure the setup script includes the corrected definition for {{SUNJMS_HOME}}.
* Verify that the setup script correctly created the symlinks to the dependency libraries. See [Step 3|#gdxyv].
* If the plug-in seems to start but does not filter messages properly, increase {{LOG_LEVEL}} to {{*7*}} in the {{etc/cloudmarkaa.cfg}} file. Examine the log file (based on the {{LOG_DEST}} configuration key) for information.{anchor:gdxvt}

h3. Troubleshooting the Cloudmark Server

Use the following tips to troubleshoot your server installation:
* Make sure that you ran the {{setup_server}} script.
* Verify that the value of {{CMAE_HOME}} is set correctly in the {{cmaed}} script. The value must be the full path to the {{CloudmarkAA-SunJMSbmi-server-1.x.y.z}} directory.
* Verify that the following parameters are set correctly in the {{cmae_server.cfg}} file:
{code}
server log file = /full/path/to/CloudmarkAA-SunJMSbmi-server-n.n.n.n/log/server.log
cartridge code dir = /full/path/to/CloudmarkAA-SunJMSbmi-server-n.n.n.n/lib
cartridge config dir = /full/path/to/CloudmarkAA-SunJMSbmi-server-n.n.n.n/etc
{code}