Messaging Server 7 Update 3 Initial Configuration

Skip to end of metadata
Go to start of metadata

Completing the Sun Java System Messaging Server 7 Update 3 Installation: Initial Configuration

This information describe the configuration and migration steps you must perform, after installation, before you can use Messaging Server. This information assumes that you have read the Communications Suite Deployment Planning Guide and installed Messaging Server software. Performing the following tasks should get you to a point where you have a functioning Messaging Server. You will still want to customize your deployment as well as provision and perhaps migrate users and groups. Provisioning is described in the Delegated Administrator Administration Guide.


Creating UNIX System Users and Groups

System users run specific server processes, and privileges need to be given to these users so that they have appropriate permissions for the processes they are running.

Set up a system user account and group for all Sun Java System servers, and set permissions for the directories and files owned by that user. To do so, use the following steps.

For security reasons, in some deployments it may be desirable to have different system administrators for different servers. This is done by creating different system users and groups per server. For example, the system user for Messaging Server would be different from the system user for Web Server, and system administrators administering Messaging Server would not be able to administer the Web Server.
To Create UNIX System Users and Groups
Creating UNIX system users and groups is optional.  The initial configuration script will do this if necessary.
  1. Log in as root.
  2. Create a group to which your system users will belong.
    In the following example, the mail group is created:
  3. Create the system user and associate it with the group you just created. In addition, set the password for that user.
    In the following example, the user mailsrv is created and associated with the mail group:
    The useradd and usermod commands are located in the /usr/sbin directory. See UNIX man pages for more information.
  4. You might also need to check the /etc/group and /etc/passwd files to be sure that the user has been added to the system group that you created.

    Should you decide not to set up UNIX system users and groups prior to installing Messaging Server, you will be able to specify them when you run the configuration script.

To Prepare Directory Server for Messaging Server Configuration

For more information on directory preparation and the directory preparation script, see Communications Suite Directory Server Setup Script ( The script prepares the Directory Server by setting up new schema, index, and data in your Directory Server. It must be run for new installations of Messaging Server, Convergence, and Communications Express. The latest version of should also be run if you are upgrading any of the component products that depend on Directory Server.

Creating the Initial Messaging Server Runtime Configuration

The initial runtime configuration program provides a configuration to get your Messaging Server up and running. It is meant to create an initial runtime configuration to setup a generic functional messaging server configuration. Thus it gives you a base working configuration from which you can make your specific customizations. The program is only meant to be run once. Subsequent running of this program will result in your configuration being overwritten. To modify your initial runtime configuration, use the configuration utilities described here and in the Messaging Server Administration Reference.

Messaging Server Prerequisites

Before running the initial runtime configuration program, you must:

Messaging Server Configuration Checklist

When you run the Messaging Server initial runtime configuration program, record your parameters in Installation Worksheets - Directory Server. To answer certain questions, refer to your Directory Server installation checklists in Configuration Worksheets - Messaging Server.

To Run the Configure Program

This procedure walks you through configuring the Messaging Server initial runtime configuration.

  1. Ensure in your setup that DNS is properly configured and that it is clearly specified how to route to hosts that are not on the local subnet.
    • The /etc/defaultrouter file should contain the IP address of the gateway system. This address must be on a local subnet.
    • The /etc/resolv.conf file exists and contains the proper entries for reachable DNS servers and domain suffixes.
    • In the /etc/nsswitch.conf file, the hosts: and ipnodes: line has the files, dns and nis keywords added. The keyword files must precede dns and nis. So if the lines look like this:
      They should be changed to this:
    • Make sure that the FQDN is the first host name in the /etc/hosts file.
      If your Internet host table in your /etc/hosts file looks like this:
      Change it so that there is only one line for the IP address of the host. Be sure the first host name is a fully qualified domain name. For example:
    • You can verify that the lines are read correctly by running the following commands:
      If the lines are read correctly, you should see the IP address followed by the FQDN and then the other values. For example:
  2. Invoke the Messaging Server initial runtime configuration with the following command:
    The following table describes options you can set with the configure program:
    Option Description
    --ldapport [ldapport] Specifies an LDAP port other than the default port 389.
    Causes configure to run without modifying the directory and instead generate an ldif file (msg-svr-base/data/install/configure.ldif) which the admin can apply to the directory after initial configuration.  This is needed if the person doing the installation does not have directory admin rights.
    --saveState [statefile] Specifies a location other than the default location (mentioned below) to save a state file.
    --state [statefile] Uses a silent installation file. See To Perform a Silent Installation.
    --debug Provides general debug info.
  3. The welcome text appears.
    The configure program displays the following when run:
  4. Select the directory where you want to store the Messaging Server configuration and data files. Symbolic links will be created under msg-svr-base to the configuration and data directory. For more information on these symbolic links, see Post-Installation Directory Layout.
    Make sure you have large enough disk space set aside for these files.
  5. Overwrite the existing configuration:
    This question only appears if you have an existing configuration. To accept the default of yes, press Enter. Otherwise, press n to exit the configuration utility.
  6. Select the user name for server processes:
    To accept the default user name mailsrv, press Enter. Otherwise, type in the user name for the server processes.
  7. Select the group name for server processes:
    To accept the default group name mail, press Enter. Otherwise, type in the group name for the server processes. This question only appears only if the UNIX user name has not yet been created.
  8. Select the fully-qualified local host name:
    This is the machine on which Messaging Server will operate. When you installed the server, you might have specified the physical host name. However, if you are installing a cluster environment, use the logical hostname. Here is the chance to change what you originally specified.
  9. Select the hostname for the LDAP Directory Server:
  10. Select the LDAP administrator login:

    The Directory Manager has overall administrator privileges on the Directory Server and all Sun Java System servers that make use of the Directory Server (for example, the Messaging Server) and has full administration access to all entries in the Directory Server. The default and recommended Distinguished Name (DN) is cn=Directory Manager and is set during Directory Server configuration
    If you are installing against a replicated Directory Server instance, you must specify the credentials of the replica, not the master directory.

  11. Type the LDAP administrator password:

    You will see

  12. Type a postmaster email address:
    Select an address that your administrator actively monitors. For example, for a postmaster on the siroe domain. This address cannot begin with "Postmaster."
    The user of the email address is not automatically created (although the default "admin" user is automatically created). Therefore, you need create it later by using a provisioning tool.
  13. Type the password for administrator accounts:

    Type an initial password that will be used for service administrator, server, user/group administrator, end user administrator privileges as well as PAB administrator and SSL passwords.
    After the initial runtime configuration, you might change this password for individual administrator accounts. For more information, see To Modify Your Passwords.

  14. Verify the password for administration:

    Retype the administration password.

  15. You will see output similar to the following:

To start Messaging Server, use the following command:

To Perform a Silent Installation

The Messaging Server initial runtime configuration program automatically creates a silent installation state file (called saveState) that can be used to quickly configure additional Messaging Server instances in your deployment where the Messaging Server packages have been installed. All of your responses to the configuration prompts are recorded in that file.

By running the silent installation, you instruct the configure program to read the silent installation state file. The configure program uses the responses in this file rather than ask the same installation questions again for subsequent initial runtime configurations of Messaging Server. When you use the state file in a new installation, you are not asked any questions. Instead, all of the state file responses are automatically applied as the new installation parameters.

The silent installation saveState statefile file is stored in the msg-svr-base/data/setup/ directory.

To use the silent installation statefile to configure another Messaging Server instance on another machine in the deployment, follow these steps:

  1. Copy the silent installation statefile to a temporary area on the machine where you are performing the new installation.
  2. Review and edit the silent installation statefile as necessary.
    You will probably want to change some of the parameters and specifications in the statefile. For example, the default email domain for the new installation might be different than the default email domain recorded in the statefile. Remember that the parameters listed in the statefile are automatically applied to this installation. It will almost always be desirable to change the hostname (Fqdn.TextField).  The UGDIR_BINDPW and admin.password fields are obfuscated but still need to be kept private.
  3. Run the following command to configure other machines with the silent installation file:
    where statefile is file name of the saveState file, including the full path to the file. (See Step 1 of this section).
    After running the silent installation program, a new statefile is created from the silent installation in the msg-svr-base/data/setup/ directory.

Installing Messaging Server Against a Directory Server Replica

The following conditions might prevent you from installing Messaging Server against a Directory Server master:

  • You do not have Directory Server master credentials.
  • Messaging Server cannot communicate directly with the Directory Server master.
To Install Messaging Server Against a Directory Server Replica

The Directory Server team does not recommend doing this with current releases of Directory Server.  Instead, they recommend installing against a master in a multi-master deployment.

Installing Messaging Server Provisioning Tools

The following sections provide a summary of install information about the supported provisioning tools:

Understanding Schema and Provisioning Options

To learn more about the schema and provisioning options for Messaging Server and Communications Suite, see Understanding Schema and Provisioning Options, in the Sun Java Communications Suite Deployment Planning Guide.

LDAP Provisioning Tools

Sun LDAP Schema 1 users and groups can be provisioned using the LDAP Directory tools (Schema 2 is not supported).

To Install Schema 1 LDAP Provisioning Tools
  1. If Directory Server is not already installed, be sure to install and configure it.
    For more information, refer to the Sun Java Enterprise System 5 Installation Guide for UNIX.
  2. Configure Access Manager to recognize data in your Directory Server.
    Before Access Manager can recognize the data in your LDAP directory, you must add special object classes to entries for all organizations, groups and users that will be managed by Access Manager. If you have not done this already, do it before you start provisioning new accounts. Sample scripts are bundled in the Access Manager product to help you automatically add these object classes to your directory. For more information on these post-installation steps, see the Sun Java System Access Manager Migration Guide.
  3. Install and configure Messaging Server with help from this guide.
    Messaging Server detects which Sun Java System LDAP Schema you are using, depending on whether or not Access Manager is installed.
  4. Install and configure Sun Java System Web Server to enable mail filtering in Messenger Express.
    For more information on enabling mail filtering, see Configuring Messenger Express and Communications Express Mail Filters.
    Though mail filtering is not a provisioning tool, its functionality existed in the previous GUI version of Delegated Administrator for Messaging.
  5. Refer to the Sun Java System Messaging Server documentation to perform LDAP provisioning.
    See Communications Suite Schema Reference, which contains object classes and attributes for both Sun LDAP Schema.

SMTP Relay Blocking

By default, Messaging Server is configured to block attempted SMTP relays; that is, it rejects attempted message submissions to external addresses from unauthenticated external sources (external systems are any other system than the host on which the server itself resides). This default configuration is quite aggressive in blocking SMTP relaying in that it considers all other systems to be external systems.

After installation, it is important to manually modify your configuration to match the needs of your site. Specifically, your messaging server should recognize its own internal systems and subnets from which SMTP relaying should always be accepted. If you do not update this configuration, you might encounter problems when testing your MTA configuration.

IMAP and POP clients that attempt to submit messages via Messaging Server system's SMTP server destined for external addresses, and which do not authenticate using SMTP AUTH (SASL), will find their submission attempts rejected. Which systems and subnets are recognized as internal is typically controlled by the INTERNAL_IP mapping table, which may be found in the msg-svr-base/config/mappings file.

For instance, on a Messaging Server system whose IP address is, the default INTERNAL_IP mapping table would appear as follows:

The initial entry, using the $(IP-pattern/significant-prefix-bits) syntax, is specifying that any IP address that matches the full 32 bits of should match and be considered internal. The second entry recognizes the loopback IP address as internal. The final entry specifies that all other IP addresses should not be considered internal.

You can add additional entries by specifying additional IP addresses or subnets before the final $N entry. These entries must specify an IP address or subnet (using the $(.../...) syntax to specify a subnet) on the left side and $Y on the right side. Or you can modify the existing $(.../...) entry to accept a more general subnet.

For instance, if this same sample site has a class C network, that is, it owns all of the subnet, then the site would want to modify the initial entry so that the mapping table appears as follows:

Or if the site owns only those IP addresses in the range, then the site would want to use:

Note that the msg-svr-base/bin/imsimta -test-match utility can be useful for checking whether an IP address matches a particular $(.../...) test condition. The imsimta test -mapping utility can be more generally useful in checking that your INTERNAL_IP mapping table returns the desired results for various IP address inputs.

After modifying your INTERNAL_IP mapping table, be sure to issue the msg-svr-base/bin/imsimta cnbuild (if you are using a compiled configuration) and the msg-svr-base/bin/imsimta restart utilities so that the changes take effect.

Further information on the mapping file and general mapping table format, as well as information on imsimta command line utilities, can be found in Message Transfer Agent Command-line Utilities. In addition, information on the INTERNAL_IP mapping table can be found in To Add SMTP Relaying.

Enabling Startup After a Reboot

You can enable Messaging Server startup after system reboots by using the bootup script: msg-svr-base/data/install/Sun_MsgSvr for Linux.  For Solaris 10, you should use the Service Management Framework. That is, by default, Messaging Server will not restart after a system reboot unless you run this script. In addition, this script can also start up your MMP, if enabled.

To Enable Messaging Server After a Reboot
  1. Copy the msg-svr-base/data/install/Sun_MsgSvr script into the /etc/init.d directory.
  2. Change the following ownerships and access modes of the Sun_MsgSvr script:
    Ownership (chown(1M)) Group Ownership (chgrp(1M)) Access Mode (chmod(1M))
    root (superuser) sys 0744
  3. Go to the /etc/rc2.d directory and create the following link:
  4. Go to the /etc/rc0.d directory and create the following link:

Performance and Tuning

Refer to Performance Tuning Considerations for a Messaging Server Architecture in the Sun Java Communications Suite 5 Deployment Planning Guide.

Post-Installation Directory Layout

After installing the Sun Java System Messaging Server, its directories and files are arranged in the organization described in the following table. The table is not exhaustive; it shows only those directories and files of most interest for typical server administration tasks.

Post-Installation Directories and Files
Directory Default Location and Description
Messaging Server Base

/opt/sun/comms/messaging/ or /opt/sun/comms/messaging64/

(default location)

The directory on the Messaging Server machine dedicated to holding the server program, configuration, maintenance, and information files.

Only one Messaging Server Base directory per machine is permitted.


Contains all of the Messaging Server configuration files such as the imta.cnf and the msg.conf files.

This directory is symbolically linked to the config subdirectory of the data and configuration directory (default: /var/opt/sun/comms/messaging/ or /var/opt/sun/comms/messaging64/) that you specified in the initial runtime configuration.


A convenience symbolic link to msg_svr_base/data/log which contains the Messaging Server log files like the mail.log_current file.


(required location)

Contains databases, configuration, log files, site-programs, queues, store and message files.

The data directory includes the config and log directories.

This directory is by default symbolically linked (on UNIX platforms) to the data and configuration directory (default: /var/opt/sun/comms/messaging/ or /var/opt/sun/comms/messaging64) that you specified in the initial runtime configuration.
System Administrator Programs


(required location)

Contains the Messaging Server system administrator executable programs and scripts such as imsimta, configutil, stop-msg, start-msg, and uninstaller.


(required location)

Contains shared libraries, private executable programs and scripts, daemons, and non-customizable content data files. For example: imapd and qm_maint.hlp.
SDK Include Files


(required location)

Contains Messaging header files for Software Development Kits (SDK).


(required location)

Contains the examples for various SDKs.
Installation Data

msg_svr_base/data/install/ and msg_svr_base/data/setup/

(required location)

Contains installation-related data files such as installation log files, silent installation files, factory default configuration files, and the initial runtime configuration log files.

Post-Installation Port Numbers

In the installation and initial runtime configuration programs, port numbers will be chosen for various services. These port numbers can be any number from 1 to 65535. The following table lists the port numbers that are designated after installation.

Port Numbers Designated During Installation
Change Port
Enable/Disable Service
Message Store (1)
  IMAP Server 143 service.imap.port service.imap.enable (1)
  POP Server
service.pop.enable (1)
  IMAPS Server
service.imap.enablesslport (0)
  POPS Server
service.pop.enablesslport (0)
  LMTP Server
dispatcher.cnf (disabled)
    local.imta.enable (1)
  SMTP Relay
dispatcher.cnf dispatcher.cnf (enabled)
  SMTP Submit
dispatcher.cnf dispatcher.cnf (enabled)
  SMTPS Submit
dispatcher.cnf dispatcher.cnf (disabled)
  http mail proxy
local.http.enable (1)
  https mail proxy
service.http.enablesslport (0)
    local.mmp.enable (0)
  IMAP Proxy
Aservice.cfg (0)
  POP Proxy
Aservice.cfg Aservice.cfg (0)
  Submit Proxy
Aservice.cfg Aservice.cfg (0)
  IMAPS Proxy
Aservice.cfg and ImapProxyAService.cfg
Aservice.cfg and ImapProxyAService.cfg (disabled)
  POPS Proxy
Aservice.cfg and PopProxyAService.cfg Aservice.cfg and PopProxyAService.cfg (disabled)
  Submits Proxy
Aservice.cfg and SmtpProxyAService.cfg Aservice.cfg and SmtpProxyAService.cfg (0)
Internal Servers
local.watcher.enable (1)
local.imta.enable (1)
local.ens.enable (0)

JMQ Notification

Messaging Server can use Sun Java System Message Queue, a standards-based messaging service, to send event notifications. Message Queue is provided as a shared component when you install Messaging Server or other Communications Suite products.

For More Information
See JMQ Notification Overview for information on integrating JMQ and Messaging Server.

configuring configuring Delete
messagingserver messagingserver Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Oct 19, 2009


    I installed directory server and comm_dssetup on one host, and installed messaging server 7 on another host. I came across a couple of issues in the messaging configure script

    1. Missing libraries:

    I had to scp the following libs from my directory server sparcv9/lib folder into the messaging server lib folder:,,,

    (If you are using 32bit, don't use the sparcv9 libs.)

    2. LDAP Port is not prompted for:
    I had to change the configure script to set the default port from 389 to my port 1389

    1. Oct 20, 2009

      The LDAP port can be specified on the CLI:

       configure --ldapport=1389

      However, the problem you are having with the missing libraries should not happen.  Please open a support ticket.


  2. Oct 23, 2009

    I had that problem too (with the

    However, it's just because I was installing messaging server under a zone and that there was some shared components missing.

    If you run pkgadd -d <path_to_comm_suite_7>SunOS_sparc/LDAPCSDK6_TOOLS/Packages it solves this particular problem. In fact, I had to install multiples shared components by hand like that since the install in the global zone did'nt work properly.

Sign up or Log in to add a comment or watch this page.

The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.