Convergence 1.0 Initial Configuration

h1. Completing the Sun Convergence Installation: Initial Configuration

After you install the Convergence software with the Communications Suite installer, you must configure the Convergence to complete the installation. You perform this initial runtime configuration by running the Convergence configuration program, {{init-config}}.

After you configure Convergence the first time, you can change the configuration settings and property values by using the Convergence command-line interface, {{iwcadmin}}. For more information about ongoing administration of Convergence, see [Convergence Administration Guide|CommSuite:Convergence Administration Guide].

This chapter describes the following topics:
{toc:minLevel=2|maxLevel=2}

h2. {anchor:gfvbz} Gather Your Convergence Configuration Information

h3. {anchor:gfvat} Convergence Components

You can configure the Convergence to communicate with the following back-end Communication Suite servers:
* Messaging Server
* Calendar Server
* Instant Messaging Server

You can choose to configure any or all of these components. Only the configured components will appear in the Convergence user interface and be available to all Convergence users.

{note:title=Configure Messaging Server and Calendar Server First}
Before you run the Convergence configuration program, you must install and configure Messaging Server and Calendar Server (if you want to use these services in Convergence).

You do not have to configure IM before you configure Convergence. However, to enable IM service, you must take the steps described in [Configure IM Components to Enable Communication with Instant Messaging Server|#configimbackend]. {note}

h3. {anchor:gfvaq} Web Containers

The Convergence server must be deployed to a Web container. You can configure Convergence on

* Sun Java ^TM^ System Application Server 9.1 Update 1

h3. Configuration Worksheets

Before you run the configuration program, you should gather configuration information by filling out the [Convergence Configuration Worksheets|Configuration Worksheets - Convergence].

h2. {anchor:configimbackend} Configure IM Components to Enable Communication with the Instant Messaging Server

To enable Convergence to communicate with Instant Messaging Server, you must configure values for the following IM Server features before you run the Convergence configuration program:

* Httpbind Component JID
* Httpbind Component Password
* Avatar Component JID
* Avatar Component Password

You need to configure these components manually, after you install and configure IM.

{note:title=A Note About Configuring the IM Server}
When you are configuring the Instant Messaging Server (with the IM {{configure}} utility), be sure that the XMPP/HTTP Gateway Deployment parameter is set {{false}}. The XMPP/HTTP Gateway is deployed through the Convergence server; its value is set when you configure Convergence.
{note}

h4. About the Httpbind Component JID and Avatar Component JID

The Httpbind JID and Avatar JID can be any string. These values do not have to identify a particular IM host and domain name. However, these values should be meaningful. For example, a good practice might be to include the host and domain name in these JIDs to make the identifiers easy to recognize.

The passwords for Httpbind JID and Avatar JID can be unique. They do not have to match any other password used for IM or another back-end service.

The JIDs and passwords that you configure in the {{iim.conf}} file must match the Httpbind and Avatar JIDs that you will configure when you configure Convergence with the {{init-config}} program.

{anchor:multipleconvergenceinstanceswithoneimserver}
h4. Configuring Multiple Instances of Convergence with One IM Server

If you are configuring multiple instances of Convergence to use one IM server, you must add a unique httpbind and avatar.jid value for each instance of Convergence. For example, if you configure three instances of Convergence, the IM server configuration ({{iim.conf}}) file must have three instances of httpbind component configuration:

{noformat}
iim_server.components=agent-calendar,httpbind1,httpbind2,httpbind3,avatar1,avatar2,avatar3

! httpbind1 component (HTTP/XMPP Gateway)
! ======================================
iim_agent.httpbind1.enable="true"
httpbind1.jid=convergence1-jid
httpbind1.password=secret

! httpbind2 component (HTTP/XMPP Gateway)
! ======================================
iim_agent.httpbind2.enable="true"
httpbind2.jid=convergence2-jid
httpbind2.password=secret

! httpbind3 component (HTTP/XMPP Gateway)
! ======================================
iim_agent.httpbind3.enable="true"
httpbind3.jid=convergence3-jid
httpbind3.password=secret
{noformat}

Similarly, in this example, the IM server configuration ({{iim.conf}}) file must have three instances of avatar component configuration:

{noformat}
! avatar1 component
! =======================
iim_agent.avatar1.enable = "true"
avatar1.jid=convergence1-jid
avatar1.password=secret

! avatar2 component
! =======================
iim_agent.avatar2.enable = "true"
avatar2.jid=convergence2-jid
avatar2.password=secret

! avatar3 component
! =======================
iim_agent.avatar3.enable = "true"
avatar3.jid=convergence3-jid
avatar3.password=secret
{noformat}

You must run the Convergence {{init-config}} script for each instance of Convergence. For details, see [Run the Convergence Configuration Program|#gfvbr]. When you set the values for the Httpbind Component JID and Aavatar Component JID, be sure that these values correspond to the values you have set for this particular instance of Convergence in the iim.conf file.

h4. To configure the IM Server components

# Perform the initial configuration of Instant Messaging by running the IM {{configure}} program. For details, see [Completing the Instant Messaging 7.3 Installation: Initial Configuration|Instant Messaging 7.3 Initial Configuration].
\\
# Edit the _im-svr-base_{{/config/iim.conf}} file.\\
\\
By default, the _im-svr-base_ is {{/opt/sun/comms/im}} on Solaris and Linux systems.\\
# Add the Avatar component to the {{im_server.components}} property. For example, this entry can look like this:\\
{noformat}
im_server.components = "agent-calendar, httpbind, avatar"
{noformat}\\
# Set the {{iim_agent.enable}} property to {{true}}.\\
\\
# Provide the Httpbind JID and password. For example:\\
{noformat}
httpbind.varrius.com
{noformat}\\
# Add the following entries to configure the Avatar component:\\
{noformat}

! avatar component
! =============
iim_agent.avatar.enable = "true"
avatar.jid = "<avatar.varrius.com>"
avatar.password = "<password>"

{noformat}\\
If you are configuring more than one Convergence client to use this IM server, add a unique httpbind and avatar.jid value for each instance of Convergence. For details, see [Configuring Multiple Instances of Convergence with One IM Server|#multipleconvergenceinstanceswithoneimserver].\\
\\
# Restart IM Server.

h2. {anchor:gfvbr} Run the Convergence Configuration Program

The steps described in this section walk you through configuring Convergence by using the configuration program, {{init-config}}.

h4. Before you run the configuration program

Be sure that the back-end servers and web container are up and running:\\
* Directory Server\\
* Messaging Server\\
* Calendar Server\\
* Application Server 9.1 Update 1\\
\\
Verify whether users are able to log in to the back-end servers correctly:
* Messaging Server\\
* Calendar Server\\
\\

h4. {anchor:GFVAY} To launch the configuration program

# Log in as (or become) root.
# Go to the _iwc-base{_}{{/sbin}} directory.
\\
\\
For example, on Solaris and Linux, go to:
{panel}
{{*\# cd /opt/sun/comms/iwc/sbin{*}}}
{panel}
# Enter the command:
{panel}
{{*\# ./init-config{*}}}
{panel}
The configuration program starts, displaying the first panel. The sections that follow lead you through the configuration panels.
\\
\\
This chapter describes how to run the configuration program in GUI mode.
\\
\\
To invoke the configuration program in command-line (non-GUI) mode, enter the command:
{panel}
{{*\# ./init-config \-nodisplay{*}}}
{panel}

h4. {anchor:gfvby} To enter information in the configuration program panels

The following steps lead you sequentially through the panels displayed by the {{init-config}} program.

If you'd rather read a list than a task-based procedure, you can refer instead to the configuration values shown in [Worksheet 1-1|Configuration Worksheets - Convergence#gfnuo] and [Worksheet 1-2|Configuration Worksheets - Convergence#gfnvm] as you run the program.
\\
# *Welcome*
\\
The first panel in the configuration program is a copyright page. Click {{{*}Next{*}}}.
# *Select the directory to store configuration and data files*
\\
\\
Select the directory where you want to store the Convergence configuration and data files. The default configuration and data directory is located here:
#* Solaris and Linux: {{/var/opt/sun/comms/iwc}}
This directory should be separate from the _iwc-base_ directory. (On Solaris and Linux, this is {{/opt/sun/comms/iwc}} by default.)
\\
\\
Enter the name of the directory, or keep the default, and click {{{*}Next{*}}}.
\\
\\
If the directory does not exist, a dialog appears asking if you want to create the directory or choose a new directory. Click {{{*}Create Directory{*}}} to create the directory or {{{*}Choose New{*}}} to enter a new directory.
\\
\\
A dialog appears indicating that the components are being loaded. This may take a few minutes.
\\
# *Select Services to configure*
\\
\\
Select the service or services you want to configure:
#* *Mail Service*---the Convergence servlets that communicate with Messaging Server and GUI components that provide end-user access to mail service.
#* *Calendar Service*---the Convergence servlets that communicate with Calendar Server and GUI components that provide end-user access to calendar service.
#* *Instant Messaging Service*---the Convergence servlets that communicate with Instant Messaging Server and GUI components that provide end-user access to Instant Messaging service.\\
*Note:* To configure the Instant Messaging Service, you must also select either Mail Service or Calendar Service (or both). You cannot select Instant Messaging Service only.
Click {{{*}Next{*}}}.
\\
# *Convergence server host name and DNS domain name*
\\
\\
Enter the host name of the machine on which Convergence is being configured.
\\
\\
For example: {{mymachine}}\\
\\
Enter the DNS domain name of the Convergence host machine.
\\
\\
For example: {{siroe.com}}\\
\\
Click {{{*}Next{*}}}.
\\
\\
# *Application Server 9.1 Update 1 Configuration Details*
\\
\\ *Installation directory.* Enter the Application Server 9.1 installation directory. By default, on Solaris this directory is {{/opt/SUNWappserver}}.
\\
\\ *Domain directory.* Enter the Application Server 9.1 domain directory. By default, on Solaris this directory is {{/opt/SUNWappserver/domains/domain1}}.
\\
\\ *Document root directory.* Enter the Application Server 9.1 document root directory. By default, on Solaris this directory is {{/opt/SUNWappserver/domains/domain1/docroot}}.
\\
\\
You can browse to select any of these directories.
\\
\\ *Server Target Name.* Enter the Application Server 9.1 target name. For example: {{server}}.
\\
\\ *Virtual Server Identifier.* Enter the Application Server 9.1 virtual server identifier. For example: {{server}}.
\\
\\ *Server Instance HTTP port.* Enter the Application Server 9.1 target HTTP port number. Default port is {{8080}}.
\\
\\
Click {{{*}Next{*}}}.
\\
\\
The configuration program checks if the directories you specified are valid. If a directory is invalid or does not exist, a dialog box tells you to choose a new directory.
\\
\\
Next, the configuration program checks if an Application Server 9.1 target connection is alive. If not, a dialog box warns you that the configuration program could not connect to the specified target and your configuration may not be completed. You can accept the specified values or choose new Application Server 9.1 configuration values.
\\
# *Application Server: Administration Instance Details*
\\
\\ *Administration Server Port.* Enter the Administration Server port number. For example: {{4848}}\\
\\ *Administrator User ID.* Enter the Administration Server administrator user ID. For example: {{admin}}\\
\\ *Administrator Password.* Enter the administrator user password.
\\
\\
If you are using a Secure Administration Server Instance, check the _Secure Administration Server Instance_ box. If you are not, leave the box unchecked.
\\
\\
Click {{{*}Next{*}}}.
\\
\\
The configuration program checks if an Application Server 9.1 Adminstration Instance is alive. If not, a dialog box warns you that the configuration program could not connect to the specified target and your configuration may not be completed. You can accept the specified values or choose new Application Server 9.1 configuration values.
\\
\\
Next, the configuration program checks if the credentials are valid. An Information dialog box is displayed with Application Server's Administration Instance running in normal or secure mode.
\\
\\
# *Enter the URI path where Convergence will be deployed.*
\\
\\
For example, enter {{*/iwc{*}}}.
\\
\\
Click {{{*}Next{*}}}.
\\
# *Specify whether or not you want hosted domain support*

\\
\\
The Communications Suite servers (Messaging Server, Calendar Server, Instant Messaging) store user and group data in an LDAP directory. This screen asks you to supply configuration information that enables the Convergence server to connect to the Directory Server managing this data.
\\
\\ *User/Group LDAP URL*. Enter the LDAP host and port where the User/Group is located. The URL should be in the format: {{ldap://_LDAP host name_:_LDAP port number_.}}
\\
\\
For example: {{ldap://siroe.com:389}}\\
\\ *Bind DN*. Enter the LDAP distinguished name (DN) of the administrator used to bind to the Directory Server. This administrator should have appropriate privileges to manage the User/Group data.
\\
\\
For example {{cn=Directory Manager}}.
\\
\\ *Bind Password*. Enter the password for the Bind DN.
\\
\\
Click {{{*}Next{*}}}.
\\
\\
The configuration program checks if the LDAP connection is alive and the credentials are valid. If not, an error box tells you that the configuration program could not connect to the specified target. You need to provide valid User/Group LDAP details.
\\
\\
# *Confirm the base distinguished name (DN) of the DC Tree suffix.*
\\
For example: {{o=isp}}\\
\\
The Convergence configuration program retrieves this base DN from the Directory Server and displays it. Use the displayed value, or change it if your configuration uses another base DN. \\
\\
This base DN is used to perform domain lookups. If the Communications Suite servers are using Schema 1, this configuration setting specifies the DN of the DC Tree suffix. If the Communications Suite servers are using Schema 2, this setting specifies the DN of the root suffix under which the User/Group tree is located. You must enter (confirm) a value for this item whether you are using Schema 1 or Schema 2.
\\
\\
In a Schema 1 directory layout, Convergence uses the DC Tree suffix to search for domain information. In a Schema 2 directory layout, there is only one root suffix; both domain and user/group data are located under this one suffix.
\\
\\
Click {{{*}Next{*}}}.
\\
\\
# *Enter the default domain name.*
\\
\\
When a user logs into Convergence without including a mail domain component in the user name, this domain is used by default to supply the fully qualified domain name. The default domain name is used when a domain name is required but not provided explicitly during login/authentication.
\\
\\
For example: {{sesta.com}}\\
\\
In this example, if a user logs in as {{fred}}, the user name is qualified as {{fred@sesta.com}}.
\\
\\
# *Specify the Mail Service configuration details.*
\\
\\
This screen appears only if you selected Messaging Service in the Select Components to Be Configured screen.
\\
\\ *Webmail Host Name*. Enter the name of the machine where Messaging Server is installed. For example: {{ms.sesta.com}}\\
\\ *Webmail Server Port Number*. Enter the Messaging Server HTTP ({{mshttpd}}) port number. For example, the default is: {{8990}}\\
\\ *Access in SSL mode*. Select this option if you want a connection between Convergence and Messaging Server in secure mode. If you select this option, make sure that the Messaging Server Port Number provided above is an SSL port.
\\
\\
\\ *Webmail Server Admin UserID*. Enter the Messaging Server administrator user ID. For example: {{admin}}\\
\\
By default, the Messaging Server administrator user ID is {{admin}}. This value is chosen during Messaging Server configuration.
\\
\\ *Webmail Server Admin Password*. Enter the Messaging Server administrator user password.
\\
\\
Click {{{*}Next{*}}}.
\\
\\
The configuration program checks if Messaging Server connection is alive and Credentials are valid. If not, a warning box displayed that the configuration program could not connect to the specified target.
\\
\\
# *Specify the Calendar Service configuration details.*
\\
\\
This screen appears only if you selected Calendar Server in the Select Components to Be Configured screen.
\\
\\ *Calendar Server Host Name*. Enter the name of the machine where Calendar Server is installed. For example: {{cs.siroe.com}}\\
\\ *Calendar Server Port Number*. Enter the Calendar Server HTTP port number. For example: {{80}} (Default Calendar Server port is {{80}}.) \\
\\ *Access in SSL mode*. Select this option if you want connection between Commnucation Center and Calendar Server in secure mode, Make sure that Calendar Server Port Numebr provided above is SSL port if you select this option.
\\
\\
\\ *Calendar Server Admin User ID*. Enter the Calendar Server administrator user ID. For example: {{calmaster}}\\
\\ *Calendar Server Admin Password*. Enter the Calendar Server administrator user password.
\\
\\
Click {{{*}Next{*}}}.
\\
\\
The configuration program checks if the Calendar Server connection is alive and Credentials are valid. If not, a warning box is displayed, stating that the configuration program could not connect to the specified target.
\\
\\
# *Specify the Instant Messaging Service configuration details.*
\\
\\
This screen appears only if you selected Instant Messaging Service in the Select Components to Be Configured screen.\\
\\
*Note:* You must configure the Httpbind Component JID, Httpbind Component Password, Avatar Component JID, and Avatar Component Password in the IM Server before you enter these values in the Convergence configuration program. For details, see [Configure IM Components to Enable Communication with the Instant Messaging Server|#configimbackend].
\\
\\ *Server Domain Name*. Enter the domain name of the Instant Messaging server. For example: {{varrius.com}}. If multiple domains need to be supported, enter the domain names separated by spaces.
\\ *Server Host Name*. Enter the name of the machine where Instant Messaging is installed. For example: {{im.varrius.com}}
\\
\\ *Server Port Number*. Enter the Instant Messaging Server HTTP port number. For example: {{5269}} ((Default Instant Messaging Server port is {{5269}}.)\\
\\
*Note:* The following items, Httpbind Component JID, Httpbind Component Password, Avatar Component JID, and Avatar Component Password, must match the JID values and passwords that you configured in the {{iim.conf}} file for the IM Server. If multiple instances of Convergence use one IM server, these items must match the JID values in the {{iim.conf}} file configured for this particular instance of Convergence. For details, see [Configuring Multiple Instances of Convergence with One IM Server|#multipleconvergenceinstanceswithoneimserver].\\
\\
\\ *Httpbind Component JID*. Enter Instant Messaging Server httpbind component JID. This value must match the JID you configured in the {{iim.conf}} file. For example: {{httpbind.varrius.com}}
\\ *Httpbind Component Password*. Enter the Instant Messaging Server httpbind component password
\\ *Avatar Component JID*. Enter Instant Messaging Server avatar component jid. For example: {{avatar.varrius.com}}
\\ *Avatar Component Password*. Enter Instant Messaging Server avatar component password.
\\
\\
Click {{{*}Next{*}}}.
\\
# *Specify the Convergence Administrator details*
\\
\\
The Administrator username and password are needed for ongoing administration of Convergence, implemented by using the Administration Utility {{iwcadmin}}. The user details for the Convergence Administrator are stored in the Convergence configuration files, not in the Directory Server. This administrator user is not tied to any back-end server administrator accounts.
\\
\\ *Username*. Enter the administrator username. For example {{admin}}\\
\\ *Password*. Enter the password, make sure that password is more than 6 charactors
\\ *Password Again*. Enter the password again to confirm
\\
# *Ready to Configure*
\\
\\
The verification panel displays the items that will be configured.
\\
\\
Click {{{*}Configure Now{*}}} to begin the configuration.
\\
\\
To change information on a previous panel, click {{{*}Back{*}}}.
\\
# *Task Sequence*
\\
\\
The Task Sequence Panel displays a sequence of tasks being performed. The actual configuration takes place as these tasks are displayed.
\\
\\
When the panel displays "All Tasks Passed," you can click {{{*}Next{*}}} to continue or {{{*}Cancel{*}}} stop the tasks from being performed and exit.
\\
\\
\\
# *Installation Summary*
\\
\\
The Installation Summary panel displays the product installed and a {{{*}Details...*}} button that displays more information about this configuration.
\\
\\
A log file for the {{init-config}} program is created in the _iwc-base{_}{{/install}} directory. (On Solaris and Linux, the default path is {{/opt/sun/comms/iwc/install}}.) The name of the log file is {{Iwc-config\-}}{_}YYYYMMDDHHMMSS{_}{{.log}}, where _YYYYMMDDHHMMSS_ identifies the 4-digit year, month, date, hour, minute, and second of the configuration.
\\
\\
Click {{{*}Close{*}}} to complete the configuration.


h2. {anchor:gfvcq} Perform Silent Installation

The Convergence initial runtime configuration program automatically creates a silent installation state file (called {{saveState}}). This file contains internal information about the configuration program and is used for running silent installations.
\\
\\
The silent installation {{saveState}} file is stored in the {{/opt/sun/comms/iwc/data/setup/Iwc-config\-}}{_}YYYYMMDDHHMMSS{_}{{/}} directory, where _YYYYMMDDHHMMSS_ identifies the 4-digit year, month, date, hour, minute, and second of the {{saveState}} file.
\\
\\
For example, once you have run the {{init-config}} program once, you can run it in silent install mode:
{noformat}
_iwc-base_/sbin/init-config -nodisplay -noconsole -state
_fullpath_/saveState
{noformat}
The _fullpath_ variable is the full directory path of where the {{saveState}} file is located.