Convergence Initial Configuration

Skip to end of metadata
Go to start of metadata

Convergence Initial Configuration
Version 2

After you install the Convergence software with the Communications Suite installer, you must configure 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.

Topics:

Gather Your Convergence Configuration Information

Convergence Components

You can configure the Convergence to communicate with the following back-end Communication Suite servers:

  • Messaging Server
  • Calendar Server (CALDAV)
  • Sun 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.

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). However, if you add a component to your deployment after running the Convergence configuration program, rerun the program so that Convergence will be able to communicate with the new component.

Alternatively, you can set up any additional installed components with Convergence by using the iwcadmin command-line interface. For example, to enable the CalDAV service with Convergence, see: Enabling CalDAV Service.

You do not have to configure Instant Messaging before you configure Convergence. However, to enable the Instant Messaging service, you must take the steps described in Configuring Components to Enable Communication with Instant Messaging Server.

Web Containers

The Convergence server must be deployed to a Web container. See Product Requirements for Convergence 2 for the list of supported web containers.

Configuration Worksheets

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

Configuring 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 Instant Messaging 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 Instant Messaging.

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

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 Instant Messaging 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.

Configuring Multiple Instances of Convergence with One Instant Messaging Server

If you are configuring multiple instances of Convergence to use one Instant Messaging 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 Instant Messaging server configuration (iim.conf) file must have three instances of httpbind component configuration:

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.httpbind.example.com
httpbind1.password=secret

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

! httpbind3 component (HTTP/XMPP Gateway)
! ======================================
iim_agent.httpbind3.enable="true"
httpbind3.jid=convergence3-jid.httpbind.example.com
httpbind3.password=secret

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

! avatar1 component
! =======================
iim_agent.avatar1.enable = "true"
avatar1.jid=convergence1-jid.avatar.example.com
avatar1.password=secret

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

! avatar3 component
! =======================
iim_agent.avatar3.enable = "true"
avatar3.jid=convergence3-jid.avatar.example.com
avatar3.password=secret

You must run the Convergence init-config script for each instance of Convergence. When you set the values for the Httpbind Component JID and Avatar 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. For details, see Run the Convergence Configuration Program.

To Configure the Instant Messaging Server Components

  1. Perform the initial configuration of Instant Messaging by running the Instant Messaging configure program.
    For details, see Instant Messaging Initial Configuration.
  2. Edit the im-svr-base/config/iim.conf file.
    By default, the im-svr-base is /opt/sun/comms/im on both Solaris OS and Red Hat Linux.
  3. Add the Avatar component to the im_server.components property.
    For example, the entry can look like this:
     im_server.components = "agent-calendar, httpbind, avatar"
    


  4. Set the iim_agent.enable property to true.
  5. Provide the Httpbind JID and password. For example:
    ! httpbind component (HTTP/XMPP Gateway)
    ! ======================================
    iim_agent.httpbind.enable="true"
    httpbind.jid="<httpbind.varrius.com>"
    httpbind.password="<password>"
    


  6. Add the following entries to configure the Avatar component:
    ! avatar component
    ! =============
    iim_agent.avatar.enable = "true"
    avatar.jid = "<avatar.varrius.com>"
    avatar.password = "<password>"
    
    

    If you are configuring more than one Convergence client to use this Instant Messaging Server host, add a unique httpbind and avatar.jid value for each instance of Convergence. For details, see Configuring Multiple Instances of Convergence with One Instant Messaging Server.

  7. Restart Instant Messaging Server.

Configuring Instant Messaging Server to Display Presence Information in Email

To enable Convergence to show presence information in email, you must configure Instant Messaging server. For information on how to do this, see How do I Configure Convergence so that Presence Information is Shown in my Email?

Run the Convergence Configuration Program

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

Before you Run the Configuration Program

Be sure that the back-end servers and the web container are up and running:

  • Directory Server
  • Messaging Server
  • Calendar Server
    A Note About GlassFish Server
    If you configured the web container with a CA or self-signed certificate, you must accept the certificate by running any of the GlassFish Server commands. See Convergence Installation Notes.

Verify that users are able to log in to the back-end servers correctly:

  • Messaging Server
  • Calendar Server

To Launch the Configuration Program

  1. Log in as (or become) root.
  2. Change to the iwc-base/sbin directory.
    For example, on Solaris OS and Red Hat Linux, change directories.
    cd /opt/sun/comms/iwc/sbin
    
  3. To launch the configuration program, type the one of the following commands:
    • GUI:
      ./init-config
      
    • CLI:
      ./init-config -nodisplay
      

      The configuration program starts, displaying the first panel. The sections that follow lead you through the configuration panels.

The remainder of this section describes how to run the configuration program in GUI mode.

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 and Worksheet 1-2 as you run the program.

  1. Welcome
    The first panel in the configuration program is a copyright page. Click Next.
  2. 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 OS and Red Hat Linux: /var/opt/sun/comms/iwc
      This directory should be separate from the iwc-base directory. (On both Solaris OS and Red Hat 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.
  3. 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.
  4. 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.

  5. GlassFish Server 2.1.1 Configuration Details

    Installation directory. Enter the GlassFish Server installation directory. By default, on Solaris OS, this directory is /opt/SUNWappserver.

    Domain directory. Enter the GlassFish Server domain directory. By default, on Solaris OS, this directory is /opt/SUNWappserver/domains/domain1.

    Document root directory. Enter the GlassFish Server document root directory. By default, on Solaris OS, this directory is /opt/SUNWappserver/domains/domain1/docroot.

    You can browse to select any of these directories.

    Server Target Name. Enter the GlassFish Server target name. For example: server.

    Virtual Server Identifier. Enter the GlassFish Server virtual server identifier. For example: server.

    Server Instance HTTP port. Enter the GlassFish Server 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 GlassFish Server 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 GlassFish Server configuration values.
  6. GlassFish Server 2.1.1: 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.

    Specify whether the HTTP access to the Administration Server instance is secure (HTTPS) or not (HTTP).
    By default, the Secure Administration Server Instance box shown in this panel is checked. If your HTTP access is not secure, uncheck the box.

    Click Next.

    The configuration program checks if a GlassFish Server Administration 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 GlassFish Server configuration values.

    Next, the configuration program checks if the credentials are valid. An Information dialog box is displayed with GlassFish Server's Administration Instance running in normal or secure mode.

  7. Enter the URI path where Convergence will be deployed.

    For example, enter /iwc.

    Click Next.
  8. Specify whether or not you want hosted domain support

    Select this option if you want to support for hosted domains in the current Convergence deployment.
    If you enable or disable this option, ensure that the same settings are applied at the following back-end servers:
  9. Specify the LDAP User/Group configuration details.

    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.

  10. 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.

  11. 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.

  12. 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.

  13. Select Calendar Server Version.

    This screen appears only if you selected Calendar Server in the Select Components to Be Configured screen.

    Choose "CS7 and up" for Calendar Server 7.x or "CS6.3" for Calendar Server 6.3.

    If you plan to enable Calendar Server 7 at a later time, follow instructions in Enabling CalDAV Service.

    Click Next.

  14. 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 Communication Center and Calendar Server in secure mode. Make sure that Calendar Server Port Number provided above is SSL port if you select this option.

    Service URI. Enter the URI path where the WCAP servlet is deployed for Calendar Server 7. (Default Service URI is /davserver/wcap). If you selected CS 6.3 in the previous screen, you will not see the Service URI field.

    Calendar Server Admin User ID. Enter the Calendar Server administrator user ID. For example: calmaster
    Note
    Add the davcore.scheduling.localuserattr value (usually davStore) to the administrative user's entry in LDAP to prevent a calmaster DavException.


    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.


  15. 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.

    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.


    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.
  16. 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
  17. 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.
  18. 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.


  19. 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 OS and Red Hat 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.

Enabling Indexing and Search Service

If you also installed Indexing and Search Service, you need to enable Indexing and Search Service related parameters in Convergence. See Enabling Indexing and Search Service (This page also covers how to enable ISS Proxy Authentication with Convergence).

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.

The silent installation saveState file is stored in the da-base/data/setup/commda-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:

iwc-base-dir/sbin/init-config -nodisplay -noconsole -state  fullpath/saveState

The fullpath variable is the full directory path of where the saveState file is located.

Configuring Certificate Based Authentication

For information on how to configure certificate based authentication for Convergence see
Certificate Based Authentication for Oracle Communications Unified Communications Suite

Labels:
convergence convergence Delete
guide guide Delete
configuring configuring Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Oct 06, 2010

    Assume I've run Convergence 2 configuration program with Messaging only and after 1 month I want to add Calendar.

    Does the note "Configure Messaging Server and Calendar Server First" mean I have to uninstall Convergence and then I have to re-run configuration program with Messaging and Calendar ? If so, what is the procedure to uninstall Convergence 2 ? What are the risks to run the command "init-config" a second time (without to uninstall Convergence) ?

    Many thanks in advance.

  2. Oct 06, 2010

    Dear Gigibigi,

    According to our development team, you do not need to uninstall Convergence. Just relaunch the init-config program and select both Mail Service and Calendar Service. Reenter the mail information and enter the new calendar information in the Configuration Program Panels.

    Kind regards,
    Shami

  3. Oct 07, 2010

    Dear Gigibigi,

    Based on add'l feedback, I've added a documentation link to enable CalDAV service with Convergence after initial configuration. This is another method to achieve the same result: in this case, you don't have to rerun init-config. Instead, you can use iwcadmin to enable calendar service to an existing mail service in Convergence by configuring a set of options documented in the provided link.

    Kind regards,
    Shami

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.