Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Messaging Server 6 2004Q2 Administration Guide 

Chapter 21
Troubleshooting the MTA

This chapter describes common tools, methods, and procedures for troubleshooting the Message Transfer Agent (MTA). It consists of the following sections:

A related topic, monitoring procedures can be found in Chapter 22, "Monitoring the Messaging Server"


Prior to reading this chapter, you should review Chapters 5 through 10 in this guide and the MTA configuration and command-line utility chapters in the Sun Java System Messaging Server Administration Reference.

Troubleshooting Overview

One of the first steps in troubleshooting the MTA is to determine where to begin the diagnosis. Depending on the problem, you might look for error messages in log files. In other situations, you might check all of the standard MTA processes, review the MTA configuration, or start and stop individual channels. Whatever approach you use, consider the following questions when troubleshooting the MTA:

This chapter will address these questions in the subsequent sections.

Standard MTA Troubleshooting Procedures

This section outlines standard troubleshooting procedures for the MTA. Follow these procedures if a problem does not generate an error message, if an error message does not provide enough diagnostic information, or if you want to perform general wellness checks, testing, and standard maintenance of the MTA.

Check the MTA Configuration

Test your address configuration by using the imsimta test -rewrite utility. With this utility, you can test the MTA’s address rewriting and channel mapping without actually having to send a message. Refer to the MTA Command-line Utilities chapter in the Sun Java System Messaging Server Administration Reference for more information.

The utility will normally show address rewriting that will be applied as well as the channel to which messages will be queued. However, syntax errors in the MTA configuration will cause the utility to issue an error message. If the output is not what you expect, you may need to correct your configuration.

Check the Message Queue Directories

Check if messages are present in the MTA message queue directory, typically msg_svr_base/data/queue/. Use command-line utilities like imsimta qm to check for the presence of expected message files under the MTA message queue directory. For more information on imsimta qm, refer to the MTA command-line utilities chapter in the Sun Java System Messaging Server Administration Reference and imsimta qm counters.

If the imsimta test -rewrite output looks correct, check that messages are actually being placed in the MTA message queue subdirectories. To do so, enable message logging (For more information on MTA logging, see PART 3: Service Logs (MTA)). You should then look at the mail.log_current file in the directory /msg_svr_base/log/. You can track a specific message by its message ID to ensure that it is being placed in the MTA message queue subdirectories. If you are unable to find the message, you may have a problem with file disk space or directory permissions.

Check the Ownership of Critical Files

You should have selected a mail server user account (nobody by default) when you installed Messaging Server. The following directories, subdirectories, and files should be owned by this account:


Commands, like the ones in the following UNIX system example, may be used to check the protection and ownership of these directories:

ls -l -p -d /opt/SUNWmsgsr/data/queue
drwx------ 6 nobody bin 512 Feb 7 09:32 /opt/SUNWmsgsr/data/queue

ls -l -p -d /opt/SUNWmsgsr/log/imta
drwx------ 2 nobody bin 1536 Mar 10 09:00 /opt/SUNWmsgsr/log/imta

ls -l -p -d /opt/SUNWmsgsr/imta/tmp
drwx------ 2 nobody bin 512 Feb 7 10:00 /opt/SUNWmsgsr/imta/tmp

Check that the files in /msg_svr_base/data/queue are owned by the MTA account by using commands like in the following UNIX system example:

ls -l -p -R /opt/SUNWmsgsr/data/queue

Check that the Job Controller and Dispatcher are Running

The MTA Job Controller handles the execution of the MTA processing jobs, including most outgoing (master) channel jobs.

Some MTA channels, such as the MTA’s multi-threaded SMTP channels, include resident server processes that process incoming messages. These servers handle the slave (incoming) direction for the channel. The MTA Dispatcher handles the creation of such MTA servers. Dispatcher configuration options control the availability of the servers, the number of created servers, and how many connections each server can handle.

To check that the Job Controller and Dispatcher are present, and to see if there are MTA servers and processing jobs running, use the command imsimta process. Under idle conditions the command should result in job_controller and dispatcher processes. For example:

imsimta process

USER     PID  S     VSZ     RSS    STIME      TIME     COMMAND
inetuser  9567  S   18416    9368   02:00:02    0:00     /opt/SUNWmsgsr/lib/tcp_smtp_server

inetuser  6573  S   18112    5720    Jul_13     0:00     /opt/SUNWmsgsr/lib/job_controller

inetuser  9568  S   18416    9432    02:00:02    0:00    /opt/SUNWmsgsr/lib/tcp_smtp_server

inetuser  6574  S   17848    5328    Jul_13     0:00    /opt/SUNWmsgsr/lib/dispatcher

If the Job Controller is not present, the files in the /msg_svr_base/data/queue directory will get backed up and messages will not be delivered. If you do not have a Dispatcher, then you will be unable to receive any SMTP connections.

For more information on imsimta process, refer to the Sun Java System Messaging Server Administration Reference.

If neither the Job Controller nor the Dispatcher is present, you should review the dispatcher.log-* or job_controller.log-* file in /msg_svr_base/data/log

If the log files do not exist or do not indicate an error, start the processes by using the msg-start command. For more information, refer to the MTA command-line utilities chapter in the Sun Java System Messaging Server Administration Reference.


You should not see multiple instances of the Dispatcher or Job Controller when you run imsimta process.

Check the Log Files

If MTA processing jobs run properly but messages stay in the message queue directory, you can examine the log files to see what is happening. All MTA log files are created in the directory /msg_svr_base/log. Log file name formats for various MTA processing jobs are shown in Table 21-1.

Table 21-1  MTA Log Files

File Name

Log File Contents


Output of master program (usually client) for channel.


Output of slave program (usually server) for channel.


Dispatcher debugging. This log is created regardless if the Dispatcher DEBUG option is set. However, to get detailed debugging information, you should set the DEBUG option to a non-zero value.


ims-ms channel error messages when there is a problem in delivery.


Job controller logging. This log is created regardless if the Job Controller DEBUG option is set. However, to get detailed debugging information, you should set the DEBUG option to a non-zero value.


Debugging for the tcp_smtp_server. The information in this log is specific to the server, not to messages.


Debug output for the periodic MTA message bouncer job; this log file is created if the return_debug option is used in the option.dat


Each log file is created with a unique ID (uniqueid) to avoid overwriting an earlier log created by the same channel. To find a specific log file, you can use the imsimta view utility. You can also purge older log files by using the imsimta purge command. For more information, see the MTA command-line utilities chapter in the Sun Java System Messaging Server Administration Reference.

The channel_master.log-uniqueid and channel_slave.log-uniqueid log files will be created in any of the following situations:

For more information on debugging channel master and slave programs, see the Sun Java System Messaging Server Administration Reference.

Run a Channel Program Manually

When diagnosing an MTA delivery problem it is helpful to manually run an MTA delivery job, particularly after you enable debugging for one or more channels.

The command imsimta submit will notify the MTA Job Controller to run the channel. If debugging is enabled for the channel in question, imsimta submit will create a log file in directory /msg_svr_base/log as shown in Table 21-1.

The command imsimta run will perform outbound delivery for the channel under the currently active process, with output directed to your terminal. This may be more convenient than submitting a job, particularly if you suspect problems with job submission itself.


In order to manually run channels, the Job Controller must be running.

For information on syntax, options, parameters, examples of imsimta submit and imsimta run commands, refer to the MTA command-line utility chapter in the Sun Java System Messaging Server Administration Reference.

Starting and Stopping Individual Channels

In some cases, stopping and starting individual channels may make message queue problems easier to diagnose and debug. Stopping a message queue allows you to examine queued messages to determine the existence of loops or spam attacks.

To Stop Outbound Processing (dequeueing) for a Specific Channel

  1. Use the imsimta qm stop command to stop a specific channel. Doing so prevents you from having to stop the Job Controller and having to recompile the configuration. In the following example, the conversion channel is stopped:
  2. imsimta qm stop conversion

  3. To resume processing, use the imsimta qm start command to restart the channel. In the following example, the conversion channel is started:
  4. imsimta qm start conversion

For more information on the imsimta qm start and imsimta qm stop commands, see the chapter on MTA command-line utilities in the Sun Java System Messaging Server Administration Reference.

To Stop Inbound Processing from a Specific Domain or IP Address (enqueuing to a channel)

You can run one of the following processes if you want to stop inbound message processing for a specific domain or IP address, while returning temporary SMTP errors to client hosts. By doing so, messages will not be held on your system. Refer to the PART 1. MAPPING TABLES.

When you want to restart inbound processing from the domain or IP address, be sure to remove these rules from the mapping tables and recompile your configuration. In addition, you may want to create unique error messages for each mapping table. Doing so will enable you to determine which mapping table is being used.

An MTA Troubleshooting Example

This section explains how to troubleshoot a particular MTA problem step-by-step. In this example, a mail recipient did not receive an attachment to an email message. Note: In keeping with MIME protocol terminology, the “attachment” is referred to as a “message part” in this section. The aforementioned troubleshooting techniques are used to identify where and why the message part disappeared (See Standard MTA Troubleshooting Procedures). By using the following steps, you can determine the path the message took through the MTA. In addition, you can determine if the message part disappeared before or after the message entered the message queue. To do so, you will need to manually stop and run channels, capturing the relevant files.


The Job Controller must be running when you manually run messages through the channels.

Identify the Channels in the Message Path

By identifying which channels are in the message path, you can apply the master_debug and slave_debug keywords to the appropriate channels. These keywords generate debugging output in the channels’ master and slave log files; in turn, the master and slave debugging information will assist in identifying the point where the message part disappeared.

  1. Add log_message_id=1 in the option.dat file in directory /msg_svr_base/config. With this parameter, you will see message ID: header lines in the mail.log_current file.
  2. Run imsimta cnbuild to recompile the configuration.
  3. Run imsimta restart dispatcher to restart the SMTP server.
  4. Have the end user resend the message with the message part.
  5. Determine the channels that the message passes through.
  6. While there are different approaches to identifying the channels, the following approach is recommended:

    1. On UNIX platforms, use the grep command to search for message ID: header lines in the mail.log_current file in directory /msg_svr_base/log.
    2. Once you find the message ID: header lines, look for the E (enqueue) and D (dequeue) records to determine the path of the message. Refer to MTA Log Entry Format for more information on logging entry codes. See the following E and D records for this example:

      29-Aug-2001 10:39:46.44 tcp_local conversion     E 2 ...

      29-Aug-2001 10:39:46.44 conversion tcp_intranet  E 2 ...

      29-Aug-2001 10:39:46.44 tcp_intranet             D 2 ...

    3. The channel on the left is the source channel, and the channel on the right is the destination channel. In this example, the E and D records indicate that the message’s path went from the tcp_local channel to the conversion channel and finally to the tcp_intranet channel.

Manually Start and Stop Channels to Gather Data

This section describes how to manually start and stop channels. See Starting and Stopping Individual Channels for more information. By manually starting and stopping the channels in the message’s path, you are able to save the message and log files at different stages in the MTA process. These files are later used to Identify the Point of Message Breakdown.

  1. Set the mm_debug=5 in the option.dat file in directory /msg_svr_base/config in order to provide substantial debugging information.
  2. Add the slave_debug and master_debug keywords to the appropriate channels in the imta.cnf file in directory /msg_svr_base/config.
    1. Use the slave_debug keyword on the inbound channel (or any channel where the message is switched to during the initial dialog) from the remote system that is sending the message with the message part. In this example, the slave_debug keyword is added to the tcp_local channel.
    2. Add the master_debug keyword to the other channels that the message passed through and were identified in Identify the Channels in the Message Path. In this example, the master_debug keyword would be added to the conversion and tcp_intranet channels.
    3. Run the command imsimta restart dispatcher to restart the SMTP server.
  3. Use the imsimta qm stop and imsimta qm start commands to manually start and stop specific channels. For more on information by using these keywords, see Starting and Stopping Individual Channels.
  4. To start the process of capturing the message files, have the end user resend the message with the message part.
  5. When the message enters a channel, the message will stop in the channel if it has been stopped with the imsimta qm stop command. For more information, see Step Step 3.
    1. Copy and rename the message file before you manually run the next channel in the message’s path. See the following UNIX platform example:
    2. # cp ZZ01K7LXW76T7O9TD0TB.00 ZZ01K7LXW76T7O9TD0TB.KEEP1

      The message file typically resides in directory similar to /msg_svr_base/data/queue/destination_channel/001. The destination_channel is the next channel that the message passes through (such as: tcp_intranet). If you want to create subdirectories (like 001, 002, and so on) in the destination_channel directory, add the subdirs keyword to the channels.

    3. It is recommended that you number the extensions of the message each time you trap and copy the message in order to identify the order in which the message is processed.
  6. Resume message processing in the channel and enqueue to the next destination channel in the message’s path. To do so, use the imsimta qm start command.
  7. Copy and save the corresponding channel log file (for example: tcp_intranet_master.log-*) located in directory /msg_svr_base/log. Choose the appropriate log file that has the data for the message you are tracking. Make sure that the file you copy matches the timestamp and the subject header for the message as it comes into the channel. In the example of the tcp_intranet_master.log-*, you might save the file as tcp_intranet_master.keep so the file is not deleted.
  8. Repeat steps 5 - 7 until the message has reached its final destination.
  9. The log files you copied in Step Step 7 should correlate to the message files that you copied in Step Step 5. If, for example, you stopped all of the channels in the missing message part scenario, you would save the conversion_master.log-* and the tcp_intranet_master.log-* files. You would also save the source channel log file tcp_local_slave.log-*. In addition, you would save a copy of the corresponding message file from each destination channel: ZZ01K7LXW76T7O9TD0TB.KEEP1 from the conversion channel and ZZ01K7LXW76T7O9TD0TB.KEEP2 from the tcp_intranet channel.

  10. Remove debugging options once the message and log files have been copied.
    1. Remove the slave_debug and the master_debug keywords from the appropriate channels in the imta.cnf file in directory /msg_svr_base/config.
    2. Reset the mm_debug=0, and remove log_message_id=1 in the option.dat file in directory /msg_svr_base/config.
    3. Recompile the configuration by using imsimta cnbuild.
    4. Run the command imsimta restart dispatcher to restart the SMTP server.

Identify the Point of Message Breakdown

  1. By the time you have finished starting and stopping the channel programs, you should have the following files with which you can use to troubleshoot the problem:
    1. All copies of the message file (for example: ZZ01K7LXW76T7O9TD0TB.KEEP1) from each channel program
    2. A tcp_local_slave.log-* file
    3. A set of channel_master.log-* files for each destination channel
    4. A set of mail.log_current records that show the path of the message
    5. All files should have timestamps and message ID values that match the message ID: header lines in the mail.log_current records. Note that the exception is when messages are bounced back to the sender; these bounced messages will have a different message ID value than the original message.

  2. Examine the tcp_local_slave.log-* file to determine if the message had the message part when it entered the message queue.
  3. Look at the SMTP dialog and data to see what was sent from the client machine.

    If the message part did not appear in the tcp_local_slave.log-* file, then the problem occurred before the message entered the MTA. As a result, the message was enqueued without the message part. If this the case, the problem could have occurred on the sender’s remote SMTP server or in the sender’s client machine.

  4. Investigate the copies of the message files to see where the message part was altered or missing.
  5. If any message file showed that the message part was altered or missing, examine the previous channel’s log file. For example, you should look at the conversion_master.log-* file if the message part in the message entering the tcp_intranet channel was altered or missing.

  6. Look at the final destination of the message.
  7. If the message part looks unaltered in the tcp_local_slave.log, the message files (for example: ZZ01K7LXW76T7O9TD0TB.KEEP1), and the channel_master.log-* files, then the MTA did not alter the message and the message part is disappearing at the next step in the path to its final destination.

    If the final destination is the ims-ms channel (the Message Store), then you might download the message from the server to a client machine to determine if the message part is being dropped during or after this transfer. If the destination channel is a tcp_* channel, then you need to go to the MTA in the message’s path. Assuming it is an Messaging Server MTA, you will need to repeat the entire troubleshooting process (See Identify the Channels in the Message Path, Manually Start and Stop Channels to Gather Data, and this section). If the other MTA is not under your administration, then the user who reported the problem should contact that particular site.

Common MTA Problems and Solutions

This sections lists common problems and solutions for MTA configuration and operation.

TLS Problems

If, during smtp dialog, the STARTTLS command returns the following error:

454 4.7.1 TLS library initialization failure

and if you have certificates installed and working for pop/imap access, check the following:

After changing protections and installing certificates, you must run:

imsimta shutdown dispatcher
start-msg dispatcher

Restarting should work, but it is better to shut it down completely, install the certificates, and then start things back up.

Changes to Configuration Files or MTA Databases Do Not Take Effect

If changes to your configuration, mapping, conversion, security, option, or alias files are not taking effect, check to see if you have performed the following steps:

  1. Recompile the configuration (by running imsimta cnbuild).
  2. Restart the appropriate processes (like imsimta restart dispatcher).
  3. Re-establish any client connections.

The MTA Sends Outgoing Mail but Does Not Receive Incoming Mail

Most MTA channels depend upon a slave or channel program to receive incoming messages. For some transport protocols that are supported by the MTA (like TCP/IP and UUCP), you need to make sure that the transport protocol activates the MTA slave program rather than its standard server. Replacing the native sendmail SMTP server with the MTA SMTP server is performed as a part of the Messaging Server installation. Refer to the Sun ONE Messaging Server Installation Guide for more information.

For the multi-threaded SMTP server, the startup of the SMTP server is controlled by the Dispatcher. If the Dispatcher is configured to use a MIN_PROCS value greater than or equal to one for the SMTP service, then there should always be at least one SMTP server process running (and potentially more, according to the MAX_PROCS value for the SMTP service). The imsimta process command may be used to check for the presence of SMTP server processes. See the chapter on MTA command-line utilities in the Sun Java System Messaging Server Administration Reference for more information.

Dispatcher (SMTP Server) Won’t Start Up

If the dispatcher won’t start up, first check the dispatcher.log-* for relevant error messages. If the log indicates problems creating or accessing the /tmp/.SUNWmsgsr.dispatcher.socket file, then verify that the /tmp protections are set to 1777. This would show up in the permissions as follows:

drwxrwxrwt    8 root    sys          734  Sep 17 12:14      tmp/


Do not remove the .SUNWmsgsr.dispatcher.file and do not create it if it’s missing. The dispatcher will create the file. If protections are not set to 1777, the dispatcher will not start or restart because it won’t be able to create/access the socket file. In addition, there may be other problems occurring not related to the Messaging Server.

Timeouts on Incoming SMTP connections

Timeouts on incoming SMTP connections are most often related to system resources and their allocation. The following techniques can be used to identify the causes of timeouts on incoming SMTP connections:

  1. Check how many simultaneous incoming SMTP connections you allow. This is controlled by the MAX_PROCS and MAX_CONNS Dispatcher settings for the SMTP service; the number of simultaneous connections allowed is MAX_PROCS*MAX_CONNS. If you can afford the system resources, consider raising this number if it is too low for your usage.
  2. Another technique you can use is to open a TELNET session. In the following example, the user connects to port 25. Once connected, 220 banner is returned. For example:

    telnet 25
    Connected to
    Escape character is ’^]’.
    220 -- Server ESMTP (Sun Java System Messaging Server 6.1 (built May 7 2001))

  3. If you are connected and receive a 220 banner, but additional commands (like ehlo and mail from) do not illicit a response, then you should run imsimta test -rewrite to ensure that the configuration is correct.

  4. If the response time of the 220 banner is slow, and if running the pstack command on the SMTP server shows the following iii_res* functions (These functions indicate that a name resolution lookup is being performed.):

    febe2c04 iii_res_send (fb7f4564, 28, fb7f4de0, 400, fb7f458c, fb7f4564) + 142c
    febdfdcc iii_res_query (0, fb7f4564, c, fb7f4de0, 400, 7f) + 254

  5. then it is likely that the host has to do reverse name resolution lookups, even on a common pair like localhost/ To prevent such a performance slowdown, you should reorder your host’s lookups in the /etc/nsswitch.conf file. To do so, change the following line in the /etc/nsswitch.conf file from:

    hosts: dns nis [NOTFOUND=return] files


    hosts: files dns nis [NOTFOUND=return]

    Making this change in the /etc/nsswitch.conf file can improve performance. Fewer SMTP servers have to handle messages instead of multiple SMTP servers having to perform unnecessary lookups.

  6. You can also put the slave_debug keyword on the channels handling incoming SMTP over TCP/IP mail, usually tcp_local and tcp_intranet. After doing so, review the most recent tcp_local_slave.log-uniqueid files to identify any particular characteristics of the messages that time out. For example, if incoming messages with large numbers of recipients are timing out, consider using the expandlimit keyword on the channel.

Remember that if your system is overloaded and overextended, timeouts will be difficult to avoid entirely.

Messages are Not Dequeued

Errors encountered during TCP/IP delivery are often transient; the MTA will generally retain messages when problems are encountered and retry them periodically. It is normal on large networks to experience periodic outages on certain hosts while other host connections work fine. To verify the problem, examine the log files for errors relating to delivery attempts. You may see error messages such as, “Fatal error from smtp_open.” Such errors are not uncommon and are usually associated with a transient network problem. To debug TCP/IP network problems, use utilities like PING, TRACEROUTE, and NSLOOKUP.

The following example shows the steps you might use to see why a message is sitting in the queue awaiting delivery to To determine why the message is not being dequeued, you can recreate the steps the MTA uses to deliver SMTP mail on TCP/IP.

% nslookup -query=mx (Step 1)


Non-authoritative answer:
XTEL.CO.UK  preference = 10, mail exchanger = (Step 2)

% telnet 25 (Step 3)
Trying... []
telnet: Unable to connect to remote host: Connection refused

  1. Use the NSLOOKUP utility to see what MX records, if any, exist for this host. If no MX records exist, then you should try connecting directly to the host. If MX records do exist, then you must connect to the designated MX relays. The MTA honors MX information preferentially, unless explicitly configured not to do so. See also TCP/IP MX Record Support.
  2. In this example, the DNS (Domain Name Service) returned the name of the designated MX relay for This is the host to which the MTA will actually connect. If more than one MX relay is listed, the MTA will try each MX record in succession, with the lowest preference value tried first.
  3. If you do have connectivity to the remote host, you should check if it is accepting inbound SMTP connections by using TELNET to the SMTP server port 25.


    If you use TELNET without specifying the port, you will discover that the remote host accepts normal TELNET connections. This does not indicate that it accepts SMTP connections; many systems accept regular TELNET connections but refuse SMTP connections and vice versa. Consequently, you should always do your testing against the SMTP port.

  4. In the previous example, the remote host is refusing connections to the SMTP port. This is why the MTA fails to deliver the message. The connection may be refused due to a misconfiguration of the remote host or some sort of resource exhaustion on the remote host. In this case, nothing can be done to locally to resolve the problem. Typically, you should let the MTA continue to retry the message.

If you are running Messaging Server on a TCP/IP network that does not use DNS, you can skip steps (Step 1) and (Step 2). Instead, you can use TELNET to directly access the host in question. Be careful to use the same host name that the MTA would use. Look at the relevant log file from the MTA’s last attempt to determine the host name. If you are using host files, you should make sure that the host name information is correct. It is strongly recommended that you use DNS instead of host names.

Note that if you test connectivity to a TCP/IP host and encounter no problems using interactive tests, it is quite likely that the problem has simply been resolved since the MTA last tried to deliver the message. You can re-run the imsimta submit tcp_channel on the appropriate channel to see if messages are being dequeued.

MTA Messages are Not Delivered

In addition to message transport problems, there are two common problems which can result in unprocessed messages in the message queues:

  1. The queue cache is not synchronized with the messages in the queue directories. Message files in the MTA queue subdirectories that are awaiting delivery are entered into an in-memory queue cache. When channel programs run, they consult this queue cache to determine which messages to deliver in their queues. There are circumstances where there are message files in the queue, but there is no corresponding queue cache entry.
    1. To check if a particular file is in the queue cache, you can use the imsimta cache -view utility; if the file is not in the queue cache, then the queue cache needs to be synchronized.
    2. The queue cache is normally synchronized every four hours. If required, you can manually resynchronize the cache by using the command imsimta cache -sync. Once synchronized, the channel programs will process the originally unprocessed messages after new messages are processed. If you want to change the default (4 hours), you should modify the job_controller.cnf file in directory /msg_svr_base/config by adding sync_time=timeperiod where timeperiod reflects how often the queue cache is synchronized. Note that the timeperiod must be greater than 30 minutes. In the following example, the queue cache synchronization is modified to 2 hours by adding the sync_time=02:00 to the global defaults section of the job_controller.cnf:

      ! VERSION=5.0
      !IMTA job controller configuration file
      !Global defaults

      You can run imsimta submit channel to clear out the backlog of messages after running imsimta cache -sync. It is important to note that clearing out the channel may take a long time if the backlog of messages is large (greater than 1000).

      For summarized queue cache information, run imsimta qm -maint dir -database -total.

    3. If after synchronizing the queue cache, messages are still not being delivered, you should restart the Job Controller. To do so, use the imsimta restart job_controller command.
    4. Restarting the Job Controller will cause the message data structure to be rebuilt from the message queues on disk.


      Restarting the Job Controller is a drastic step and should only be performed after all other avenues have been thoroughly exhausted.

  2. Channel processing programs fail to run because they cannot create their processing log file. Check the access permissions, disk space and quotas.

Messages are Looping

If the MTA detects that a message is looping, that message will be sidelined as a .HELD file. See Diagnosing and Cleaning up .HELD Messages. Certain cases can lead to message loops which the MTA can not detect.

The first step is to determine why the messages are looping. You should look at a copy of the problem message file while it is in the MTA queue area, MTA mail log entries (if you have the logging channel keyword enabled in your MTA configuration file for the channels in question) relating to the problem message, and MTA channel debug log files for the channels in question. Determining the From: and To: addresses for the problem message, seeing the Received: header lines, and seeing the message structure (type of encapsulation of the message contents), can all help pinpoint which sort of message loop case you are encountering.

Some of the more common cases include:

  1. A postmaster address is broken.
  2. The MTA requires that the postmaster address be a functioning address that can receive email. If a message to the postmaster is looping, check that your configuration has a proper postmaster address pointing to an account that can receive messages.

  3. Stripping of Received: header lines is preventing the MTA from detecting the message loop.
  4. Normal detection of message loops is based on Received: header lines. If Received: header lines are being stripped (either explicitly on the MTA system itself, or on another system like a firewall), it can interfere with proper detection of message loops. In these scenarios, check that no undesired stripping of Received: header lines is occurring. Also, check for the underlying reason why the messages are looping. Possible reasons include: a problem in the assignment of system names or a system not configured to recognize a variant of its own name, a DNS problem, a lack of authoritative addressing information on the system in question, or a user address forwarding error.

  5. Incorrect handling of notification messages by other messaging systems are generating reencapsulated messages in response to notification messages.
  6. Internet standards require that notification messages (reports of messages being delivered, or messages bouncing) have an empty envelope From: address to prevent message loops. However, some messaging systems do not correctly handle such notification messages. When forwarding or bouncing notification messages, these messaging systems may insert a new envelope From: address. This can then lead to message loops. The solution is to fix the messaging system that is incorrectly handling the notification messages.

Diagnosing and Cleaning up .HELD Messages

If the MTA detects that messages are bouncing between servers or channels, delivery is halted and the messages are stored in a file with the suffix .HELD in /msg_svr_base/data/queue/channel. Typically, a message loop occurs because each server or channel thinks the other is responsible for delivery of the message.

For example, an end user may set an option to forward messages on two separate mail hosts to one another. On his account, the end-user enables mail forwarding to his account. And, forgetting that he has enabled this setting, he sets mail forwarding on his account to his account.

A loop can also occur with a faulty MTA configuration. For example, MTA Host X thinks that messages for go to Host Y. However, Host Y thinks that Host X should handle messages for; as a result, Host Y returns the mail to Host X.

In these cases, the message is ignored by the MTA and no further delivery is attempted. When such a problem occurs, look at the header lines in the message to determine which server or channel is bouncing the message. Fix the entry as needed.

You can also retry the .HELD message by following these steps:

  1. Rename the .HELD extension to any 2 digit number other than 00. For example, .HELD to .06.


    Before renaming the .HELD file, be sure that the message has stopped looping.

  2. Run imsimta cache -sync. Running this command will update the cache.
  3. Run imsimta submit channel or imsimta run channel.

It may be necessary to perform these steps multiple times, since the message may again be marked as .HELD, because the Received: header lines accumulate.

Received Message is Encoded

Messages sent by the MTA are received in an encoded format. For example:

Date: Wed, 04 Jul 2001 11:59:56 -0700 (PDT)
From: "Desdemona Vilalobos" <>
Subject: test message with 8bit data
MIME-Version: 1.0
Content-type: TEXT/PLAIN; CHARSET=ISO-8859-1
Content-transfer-encoding: QUOTED-PRINTABLE

2=00So are the Bo=F6tes Void and the Coal Sack the same?=

These messages appear unencoded when read with the MTA decoder command imsimta decode. Refer to the Sun Java System Messaging Server Administration Reference for more information.

The SMTP protocol only allows the transmission of ASCII characters (a seven-bit character set) as set forth by RFC 821. In fact, the unnegotiated transmission of eight-bit characters is illegal via SMTP, and it is known to cause a variety of problems with some SMTP servers. For example, SMTP servers can go into compute bound loops. Messages are sent over and over again. Eight-bit characters can crash SMTP servers. Finally, eight-bit character sets can wreak havoc with browsers and mailboxes that cannot handle eight-bit data.

An SMTP client used to only have three options when handling a message containing eight-bit data: return the message to the sender as undeliverable, encode the message, or send it in direct violation of RFC 821. But with the advent of MIME and the SMTP extensions, there are now standard encodings which may be used to encode eight-bit data by using the ASCII character set.

In the previous example, the recipient received an encoded message with a MIME content type of TEXT/PLAIN. The remote SMTP server (to which the MTA SMTP client transferred the message) did not support the transfer of eight-bit data. Since the original message contained eight-bit characters, the MTA had to encode the message.

Server-Side Rules (SSR) Are Not Working

A filter consists of one or more conditional actions to apply to a mail message. Since the filters are stored and evaluated on the server, they are often referred to as server-side rules (SSR).

This section includes information on the following SSR topics:

Testing Your SSR Rules

Common Syntax Problems

General Error Messages

When the MTA fails to start, general error messages appear at the command line. In this section, common general error messages will be described and diagnosed.


To diagnose your own MTA configuration, use the imsimta test -rewrite -debug utility to examine your MTA’s address rewriting and channel mapping process. By using this utility allows you to check the configuration without actually sending a message. See Check the MTA Configuration.

MTA subcomponents might also issue other error messages that are not described in this chapter. You should refer to the chapters on MTA command-line utilities and configuration in the Sun Java System Messaging Server Administration Reference and chapters 5 through 10 for more information on each subcomponent. This section includes the following types of errors:

Errors in mm_init

An error in mm_init generally indicates an MTA configuration problem. If you run the imsimta test -rewrite utility, these errors will be displayed. Other utilities like imsimta cnbuild, a channel, a server, or a browser might also return such an error.

Commonly encountered mm_init errors include:

bad equivalence for alias. . .

The right hand side of an alias file entry is improperly formatted.

cannot open alias include file. . .

A file included into the alias file cannot be opened.

duplicate aliases found. . .

Two alias file entries have the same left hand side. You will need to find and eliminate the duplication. Look for an error message that says error line #XXX where XXX is a line number. You can fix the duplicated alias on the line.

duplicate host in channel table. . .

This error message indicates that you have two channel definitions in the MTA configuration that both have the same official host name.

Note that an extraneous blank line in the rewrite rules (upper portion) of your MTA configuration file (imta.cnf) causes the MTA to interpret the remainder of the configuration file as channel definitions. Make sure that the very first line of the file is not a blank. Since there are often multiple rewrite rules with the same pattern (left-hand side), this then causes MTA to interpret them as channel definitions with non-unique official host names. Check your MTA configuration for any channel definitions with duplicate official host names and for any improper blank lines in the upper (rewrite rules) portion of the file.

duplicate mapping name found. . .

This message indicates that two mapping tables have the same name, and one of the duplicate mapping tables needs to be removed. However, formatting errors in the mapping file may cause the MTA to wrongly interpret something as a mapping table name. For example, failure to properly indent a mapping table entry will cause the MTA to think that the left hand side of the entry is actually a mapping table name. Check your mapping file for general form and check the mapping table names.


A blank line should precede and follow any line with a mapping table name. However, no blank lines should be interspersed among the entries of a mapping table.

mapping name is too long. . .

This error means that a mapping table name is too long and needs to be shortened. Formatting errors in the mapping file may cause the MTA to wrongly interpret something as a mapping table name. For example, failure to properly indent a mapping table entry will cause the MTA to think that the left hand side of the entry is actually a mapping table name. Check your mapping file and mapping table names.

error initializing ch_ facility: compiled character set version mismatch

If you see this message, you need to recompile and reinstall your compiled character set tables through the command imsimta chbuild. See the Sun Java System Messaging Server Administration Reference for more information.

error initializing ch_ facility: no room in. . .

This error message generally means that you need to resize your MTA character set internal tables and then rebuild the compiled character set tables with the following commands:

imsimta chbuild -noimage -maximum -option
imsimta chbuild

Verify that nothing else needs to be recompiled or restarted before making this change. Refer to the MTA command-line utilities chapter in the Sun Java System Messaging Server Administration Reference for more information on imsimta chbuild.

local host alias or proper name too long for system. . .

This error indicates that a local host alias or proper name is too long (the optional right hand side in the second or subsequent names in a channel block). However, certain syntax errors earlier in the MTA configuration file (an extraneous blank line in the rewrite rules, for instance) may cause MTA to wrongly interpret something as a channel definition. Aside from checking the indicated line of the configuration file, also check above that line for other syntax errors. In particular, if the line in which MTA issues this error is intended as a rewrite rule, then be sure to check for extraneous blank lines above it.

no equivalence addresses for alias. . .

An entry in the alias file is missing a right hand side (translation value).

no official host name for channel. . .

This error indicates that a channel definition block is missing the required second line (the official host name line). See the chapters on MTA configuration and command-line utilities in the Sun Java System Messaging Server Administration Reference and Chapter 12, "Configuring Channel Definitions" for more information on channel definition blocks. A blank line is required before and after each channel definition block, but a blank line must not be present between the channel name and official host name lines of the channel definition. Also note that blank lines are not permitted in the rewrite rules portion of the MTA configuration file.

official host name is too long

The official host name for a channel (second line of the channel definition block) is limited to forty octets in length. If you are trying to use a longer official host name on a channel, shorten it to a place holder name, and then use a rewrite rule to match the longer name to the short official host name. You may see this scenario if you work with the l (local) channel host name. For example:

Original l Channel:
!delivery channel to local /var/mail store
l subdirs 20 viaaliasrequired maxjobs 7 pool LOCAL_POOL

Create Place Holder:
!delivery channel to local /var/mail store
l subdirs 20 viaaliasrequired maxjobs 7 pool LOCAL_POOL

Create Rewrite Rule:   $U%$D@newt

Note that when using the l (local) channel, you will need to use a REVERSE mapping table. Refer to the MTA configuration chapter in the Sun Java System Messaging Server Administration Reference for information on usage and syntax.

Certain syntax errors earlier in the MTA configuration file (for example, an extraneous blank line in the rewrite rules) may cause the MTA to wrongly interpret something as a channel definition. This could result in an intended rewrite rule being interpreted as an official host name. Besides checking the indicated line of the configuration file, also check above that line for other syntax errors. In particular, if the line on which the MTA issues this error is intended as a rewrite rule, be sure to check for extraneous blank lines above it.

Compiled Configuration Version Mismatch

One of the functions of the imsimta cnbuild utility is to compile MTA configuration information into an image that can be quickly loaded. The compiled format is quite rigidly defined and often changes substantially between different versions of the MTA. Minor changes might occur as part of patch releases.

When such changes occur, an internal version field is also changed so that incompatible formats can be detected. The MTA components will halt with the above error when an incompatible format is detected. The solution to this problem is to generate a new, compiled configuration with the command imsimta cnbuild.

It is also a good idea to use the imsimta restart command to restart any resident MTA server processes, so they can obtain updated configuration information.

Swap Space Errors

To ensure proper operation, it is important to configure enough swap space on your messaging system. The amount of required swap space will vary depending on your configuration. A general tuning recommendation is that the amount of swap space should be at least three times the amount of main memory.

An error message such as the following indicates a lack of swap space:

jbc_channels: chan_execute [1]: fork failed: Not enough space

You might see this error in the Job Controller log file. Other swap space errors will vary depending on your configuration.

Use the following commands to determine how much swap space you have left and determine how much you have used:

File open or create errors

In order to send a message, the MTA reads configuration files and creates message files in the MTA message queue directories. Configuration files must be readable by the MTA or any program written against the MTA’s SDKs. During installation, proper permissions are assigned to these files. The MTA utilities and procedures which create configuration files also assign permissions. If the files are protected by the system manager, other privileged user, or through some site-specific procedure, the MTA may not be able to read configuration information. This will result in “File open” errors or unpredictable behavior. The imsimta test -rewrite utility reports additional information when it encounters problems reading configuration files. See the imsimta test -rewrite documentation in the MTA chapters of the Sun Java System Messaging Server Administration Reference.

If the MTA appears to function from privileged accounts but not from unprivileged accounts, then file permissions in the MTA table directory are likely the cause of the problem. Check the permissions on configuration files and their directories. See Check the Ownership of Critical Files.

“File create” errors usually indicate a problem while creating a message file in an MTA message queue directory. See Check the Message Queue Directories to diagnose file creation problems.

Illegal Host/Domain Errors

You may see this error when an address is provided to the MTA through a browser. Or, the error may be deferred and returned as part of an error return mail message. In both cases, this error message indicates that the MTA is not able to deliver mail to the specified host. To determine why the mail is not being sent to the specified host, you should follow these troubleshooting procedures:

Errors in SMTP channels: os_smtp_* errors

Errors such as the following are not necessarily MTA errors: os_smtp_* errors like os_smtp_open, os_smtp_read, and os_smtp_write errors. These errors are generated when the MTA reports a problem encountered at the network layer. For example, an os_smtp_open error means that the network connection to the remote side could not be opened. The MTA may be configured to connect to an invalid system because of addressing errors or channel configuration errors. The os_smtp_* errors are commonly due to DNS or network connectivity problems, particularly if this was a previously working channel or address. os_smtp_read or os_smtp_write errors are usually an indication that the connection was aborted by the other side or due to network problems.

Network and DNS problems are often transient in nature. The occasional os_smtp_* error is usually nothing to be concerned about. However, if you are consistently seeing these errors, it may be an indication of an underlying network problem.

To obtain more information about a particular os_smtp_* error, enable debugging on the channel in question. Investigate the debug channel log file that will show details of the attempted SMTP dialogue. In particular, look at the timing of when a network problem occurred during the SMTP dialogue. The timing may suggest the type of network or remote side issue. In some cases, you may also want to perform network level debugging (for example, TCP/IP packet tracing) to determine what was sent or received.

Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.