Init-config utility

From Messaging Server Technical Reference Wiki
Jump to: navigation, search

The init-config utility initializes the system for use by Messaging Server and generates an initial product configuration.

Syntax

  init-config [switches]

Restrictions

Must have superuser privileges in order to use this utility. This is implemented as a Perl script, so a reasonably modern version of Perl must be installed on the system to run this. It is more convenient to use this tool if an LDAP server has been installed previously and the comms_dssetup tool has been used to initialize the LDAP server.

Parameters

None.

Description

The init-config tool prepares a system for use by Messaging Server and generates an initial configuration for the product. It can be run in an interactive mode or in a silent mode (when a state file is provided). By default, the initial configuration generated is designed for product evaluation purposes and enables the primary product services (MTA & Message Store) including a number of common channels and mappings. Alternatively, the tool can be used to generate a limited configuration appropriate as a starting point for a deployment by using the --recipes= (or -r) switch with a list of initial config recipes (this is new in Messaging Server 8.1). Note that in initial config recipe mode, statefile variables are limited to 1024 characters in length.

The following list summarizes the functions performed by init-config:

  1. Creates the Unix user and group for Messaging Server, if needed.
  2. If in evaluation or ldapinit mode, it creates LDAP server entries (or LDIF) for the default domain, administrative user and postmaster, along with access control lists.
  3. If in evaluation or ldapinit mode, it creates Directory Server entries (or LDIF) for an administrative group and user for the host where configure is run; this administrative group and user have limited write access to the directory. If in useldap mode, this account must already exist and be provided by prompt or state file.
  4. Creates DataRoot and ConfigRoot directories with correct permissions.
  5. Creates subdirectories of the DataRoot and ConfigRoot directories with correct permissions.
  6. Generates a random secret for authentication to local-only services, such as the job_controller and watcher.
  7. Prompts you with the minimum number of questions about your environment to create an initial Messaging Server configuration with correct permissions.
  8. Attempts to disable mail servers that come with the operating system, for example, Postfix and Sendmail.
  9. Prior to MS 8.0.2: runs the imsimta chbuild command to compile character set conversion tables. Starting with MS 8.0.2 a compiled table is bundled in the install package and used unless the customer overrides.
  10. Creates convenience symlinks from the install directory to the DataRoot, ConfigRoot, and log directories. Prior to MS 8.0.2, these symlinks were required for correct product functionality.

The following table describes the state file variables used by init-config. State file variables starting with an "ic" prefix are ignored if unrecognized; other state file variables will generate a warning if unrecognized.

State File variables for initial configuration
Variable Name Related Configuration Description
Fqdn.TextField base.hostname Fully qualified local hostname. Mandatory.
msg.DataPath N/A Use a non-default DataRoot (not recommended).
iMS.UserId user in restricted.cnf Specifies the Unix user identity for server processes. Mandatory.
iMS.GroupId N/A Specifies the primary Unix group of the Unix user if user creation is needed.
UGDIR_URL multiple An ldap or ldaps URL for the LDAP server.
UGDIR_BINDDN N/A Specifies the LDAP administrator user (required for evaluation or ldapinit modes).
UGDIR_BINDPW N/A Specifies the LDAP administrator password (required for evaluation or ldapinit modes). This password is obfuscated using a ROT-13 variant.
Postmaster.TextField alias MTAs require a postmaster for error reports. This option is used directly as an alais value by the mta initial config recipe, or to initialize a Postmaster group by evaluation or ldapinit modes.
admin.password base.proxyadminpass, etc. Password for the store administrative user primarily used for proxy login between servers. This password is base64-encoded for obfuscation.
EmailDomain.TextField base.defaultdomain Default email domain.
OrgName.TextField N/A Default organization DN, only used by evaluation or ldapinit modes.
InternalIPlist INTERNAL_IP mapping table Specifies IP address information, in comma-delimited form, for systems permitted to relay mail without authentication. Note: when used in initial config recipe mode, all statefile variables have a length limit of 1024 characters. As a result, additional statefile variables ic.iplist2, ic.iplist3, ... can be used to provide additional values for this setting.
ic.iplist2, ic.iplistn INTERNAL_IP mapping table In initial config recipe mode, this specifies IP addresses for systems permitted to relay in addition to the ones in the InternalIPlist. Each of these values is limited to 1024 characters. These are read in order, starting with InternalIPlist, then ic.iplist2, ic.iplist3, ic.iplist4, ... stopping when no value is found in the statefile. The values are sorted before producing the INTERNAL_IP mapping table.
XMLCONFIG N/A Starting in Messaging Server 8.1, this option is ignored and Unified Configuration is always used. For previous versions, when set to 1 this creates a Unified Configuration and when set to 0, creates a legacy configuration. The --xml and --noxml command options override what is specified in the statefile.
cassandra store.dbtype, isc.enable When set to 1, use a Cassandra message store rather than a classic message store. New in Messaging Server 8.0.2.
dssetup.ugsuffix base.ugldapbasedn Specifies the user/group suffix. Unless --noldap is specified, the default comes from LDAP cn=CommsServers,o=comms-config.
dssetup.dcsuffix base.dcroot Specifies the domain suffix. Unless --noldap is specified, the default comes from LDAP cn=CommsServers,o=comms-config.
dssetup.schematype base.ldap_schemalevel Specifies the schema type. Unless --noldap is specified, the default comes from LDAP cn=CommsServers,o=comms-config.
admin.user store.admins, base.proxyadmin Administrative user for proxy authentication and store administration. Defaults to "admin". New in Messaging Server 8.0.2.3.
ugldap.hostlist base.ugldaphost LDAP server (a space-delimited failover server is permitted). When present, this overrides UGDIR_URL. New in Messaging Server 8.0.2.3.
ugldap.port base.ugldapport LDAP server default port. When present, this overrides UGDIR_URL. New in Messaging Server 8.0.2.3.
ugldap.usessl base.ugldapusessl When to require SSL for LDAP. When present, this overrides UGDIR_URL. New in Messaging Server 8.0.2.3.
ugldap.binddn base.ugldapbinddn LDAP administrative user for server operations. This user should be able to read all user entries but should have limited write access to the directory. Such a user is created by evaluation or ldapinit modes. New in Messaging Server 8.0.2.3.
ugldap.bindcred base.ugldapbindcred Password for server operations. This password is base64-encoded for obfuscation. New in Messaging Server 8.0.2.3.
ic_lmtp_ipmask_list LMTP_ACCESS mapping Used only by lmtpserver initial config recipe. This specifies IP address information, in comma-delimited form, for systems permitted to deliver mail to the LMTP server without authentication. The LMTP_ACCESS mapping table works the same way as the INTERNAL_IP mapping table. New in Messaging Server 8.1.
icmmpimap_enable mmp.enable, etc. Used only by proxy initial config recipe. When set to 1, this enables the MMP and settings for an MMP IMAP proxy. New in Messaging Server 8.1.
icmmppop_enable mmp.enable, etc. Used only by proxy initial config recipe. When set to 1, this enables the MMP and settings for an MMP POP proxy. New in Messaging Server 8.1.
icmshttpd_enable http.enable, etc. Used only by proxy initial config recipe. When set to 1, this enables the Convergence mshttpd proxy and settings for submission proxy via mshttpd. New in Messaging Server 8.1.
icsubmithost alarm.noticehost, http.smtphost Required by the proxy initial config recipe. This specifies the hostname of a submission server used for mail from the alarm subsystem and Convergence mshttpd (if enabled). New in Messaging Server 8.1.
icsubmitport http.smtpport Used only by proxy initial config recipe. This specifies the port of a submission server used for mail from Convergence mshttpd (if enabled). This defaults to 587; however use of 465 for SSL-encrypted submission should be considered. New in Messaging Server 8.1.

Switches

--cassandra

Configure use of the Cassandra Message Store rather than classic Message Store.

--dataroot=dataroot

Specifies an alternate location for the data root directory where read/write product configuration and operational data will be stored. The default location for the data root directory is /var/server-root where server-root is the installation directory. Use of a non-default dataroot is not recommended.

--debug

Requests additional debugging information while generating initial configuration; this primarily impacts LDAP operations.

--help, -?

Display command usage summary.

--ignoreSendmail

Ignore the presence of Sendmail or Postfix on the system. By default, the initial configuration tool attempts to avoid port conflicts by disabling Sendmail or Postfix if those tools are enabled.

--ldapport=ldapPort

Use a non-default LDAP port to communicate with the LDAP server.

--ldif

Treat the LDAP directory as read-only and generate an LDIF file in a DataRoot/install/configure.ldif file for any desired changes to the directory. The administrator must apply the LDIF file to the directory after initial configuration but before starting the Messaging Server product. This is helpful if the person doing the Messaging Server installation does not have directory administrative rights.

--list-recipes

Displays the available initial configuration recipes and exits.

--noldap

Create a full evaluation installation without an LDAP server present. This is used in combination with the --state=statefile and --ldif switches to configure Messaging Server when the LDAP server is not available at the time initial configuration is generated. Normally the answers provided to comms_dssetup questions are read from the LDAP server by this tool; but when this switch is used, those values should be provided in the state file. Note that it's possible to both configure and use a routing-only MTA without LDAP; use of the --recipes switch (new in Messaging Server 8.1) is the recommended way of doing that.

--novalidate

Skip most validation of user input and state file variables. This may result in a non-functional configuration. This is provided primarily as a mechanism to work around possible bugs in the init-config tool's validation logic.

--noxml

Generate an initial legacy configuration rather than an initial Unified Configuration (XML based). This option is not supported starting with Messaging Server 8.0.2, and no longer works starting with Messaging Server 8.1.

--preserveCritical

When initializing the LDAP server for use by Messaging Server, this prevents certain critical attributes from being overwritten with different values, even if new values are provided. See the installation guide for a more in-depth discussion of critical LDAP attributes.

--quiet, -q

Suppress most non-error console output (a logfile is still created containing necessary information to diagnose issues).

--recipes=recipe-list, -r recipe-list

Generate a minimal configuration for a particular deployment function as  determined by a list of initial configuration recipes. LDAP will not be  involved unless ldapinit or useldap is included  in the recipe list.  

--saveState=statefile

Specifies the location to save a state file. The default location is DataRoot/setup/saveState.

--ssl

Require SSL when communicating with the LDAP server. Any necessary SSL certificates and configuration must be manually set up prior to using this option.

--state=statefile

Use a silent installation file and do not prompt the administrator for information.

--version, -V

Displays the product version and exits.

--xml

Force use of Unified Configuration, even if the statefile specifies use of legacy configuration. Starting with Messaging Server 8.1, this is the default behavior so this switch has no effect.

Examples

To configure an evaluation installation of Messaging Server when an LDAP server is present (interactive).


# init-config

To initialize LDAP server and configure the first classic Message Store in a multi-system deployment (interactive).


# init-config -r ldapinit,store,lmtpserver

To configure an additional classic Message Store in a multi-system deployment (interactive).


# init-config -r useldap,store,lmtpserver

To add an MTA with submission service to a Messaging Server multi-system deployment (interactive).


# init-config -r useldap,mta,submit

To add an MMP and/or mshttpd service to a Messaging Server multi-system deployment (interactive).


# init-config -r useldap,proxy

To configurate a routing-only MTA without LDAP (interactive).


# init-config -r mta

To configurate using a state file (non-interactive).


# init-config --state=/path/to/statefile

To list available initial configuration recipes.


# init-config --list-recipes
Available Initial Configuration Recipes:
 ldapinit        Initialize LDAP directory for use by Messaging Server
 lmtpserver      LMTP server (used by initial configuration)
 mta             Configure an MTA (used by initial configuration)
 none            Minimal configuration with external services disabled
 proxy           Proxy configuration (MMP, Convergence mshttpd)
 store           Configure a message store (used by initial configuration)
 submit          Add submission service to an MTA (initial configuration)
 useldap         Enable support for LDAP users (doesn't initialize LDAP)

See also: