Convergence Administrative Tasks

Skip to end of metadata
Go to start of metadata

Convergence Administrative Tasks

Note
Unless otherwise specified, the instructions for these common Convergence administrative tasks are applicable to all Convergence versions.

Authentication

How do I set up Convergence user interface login for end users?

To set up Convergence UI login for end users, evaluate if you want to use:

  • UID (default), or
  • Email Address Login (LDAP mail attribute)

The procedures for setting up email address login which uses the LDAP mail attribute are the following:

Constructing a Filter for Email Address Login

In order to create a filter for email address login, you need the uid and mail attributes.

mail identifies the primary email address for a user, Calendar group, or Calendar resource. This is the email address retrieved and displayed by lookup applications.

The following variables are used in constructing the filter:

Variable Description
%U Name part of the login name (that is, everything before the login separator stored in the servers configuration)
%V Domain part of the login string
%o Original login ID entered by the user

For more information on LDAP attributes, specifically, inetDomainSearchFilter, see Messaging Server and Calendar Server LDAP Object Classes and Attributes.

Enabling Email Address Login on Convergence Server

To set up email address login, enable it on the Convergence Server:

See: Convergence Reference for information on ugldap.ugfilter.

Activating mailAlternateAddress (optional)

mailAlternateAddress is the alternate RFC 822 email address of this recipient. A filter similar to mail can be performed on mailalternateaddress:

How do I configure LDAP authentication in Convergence?

LDAP authentication is enabled by default when you configure Convergence. You can use separate LDAP servers to store authentication information and user preferences. By default, Convergence uses UG LDAP as the authentication LDAP server. You can enable LDAP authentication by using the following command line option:

iwcadmin -o auth.ldap.enable -v true

How do I configure Convergence to use separate Directory Server for user authentication and another to store User/Group information?

When LDAP authentication module is configured for authentication, the LDAP authentication module, by default, uses the UG LDAP for authentication. If you use separate LDAP servers for storing the authentication information and user preferences, the schema type and user trees should match in both the LDAP stores.

To enable your site to use a separate LDAP server for authentication, you must set the following configuration parameters.

  • auth.ldap.enable - Set this parameter to true.
  • auth.ldap.schemaversion - Set this parameter to the schema version that you are using for the UG LDAP. The schema versions for the UG LDAP and authentication LDAP must be the same.
  • auth.ldap.dcroot - DC (Domain Component) or user tree root node in the LDAP. This should be the same value as in the UG LDAP.
  • auth.ldap.host - Host name of the authentication LDAP server.
  • auth.ldap.enablessl - Set this parameter to true or false to enable or disable SSL.
  • auth.ldap.port - Port number that the LDAP server listens to. If the LDAP server is configured in SSL mode, you must provide the SSL port.
  • auth.ldap.minpool - Minimum number of connections that you want to have when the LDAP pool is initialized.
  • auth.ldap.maxpool - Maximum number of connections that you want to have when the LDAP pool is initialized.
  • auth.ldap.timeout - Set this to the maximum number seconds that the LDAP server should wait for returning search results before aborting the search.
  • auth.ldap.binddn - The Bind DN of the user. The LDAP server privilege user ID. For example, cn=DirectoryManager.
  • auth.ldap.bindpwd - The bind DN user password.

You can set the parameters in batch mode. See Running the iwcadmin command in Batch Mode.

The following configuration parameter can be set when the administrator needs to customize default values.

iwcadmin -o auth.ldap.ugfilter -v  <ugfilter>

This should result in unique user entry under given domain/organization. For example,(|(uid=%U)(mail=%o)) otherwise it will cause unexpected results. If not set (uid=%U) will be used as default value.

How to use LDAP in SSL mode?

If you use the same LDAP server, both for authentication and storing user preferences, you must set the ugldap.enablessl and ugldap.port configuration parameters by using the iwcadmin command-line utility.

iwcadmin -o ugldap.enablessl -v true
iwcadmin -o ugldap.port -v <user_group_ldap_port>

if your deployment uses an LDAP server other than the User/Group LDAP for authentication, you must set the following parameters by using the iwcadmin command-line utility:

iwcadmin -o auth.ldap.enablessl -v true
iwcadmin -o auth.ldap.port -v <ldapport>

How do I write a custom authentication module?

See Writing a Custom Authentication Module for Convergence.

Access Manager

Note
Access Manager can only be used with Convergence 2.x and earlier. See: Deprecated Support of Access Manager and Sun OpenSSO.
Note
A pre-requisite for the use of Access Manager for authentication and/or SSO is that either the Access Manager Server be deployed in the same web-container as Convergence or the Access Manager Client SDK has been correctly configured to access the remote Access Manager Server. For more information, see Communications Suite 6 Installation Scenario - Install Convergence.

How do I set up Access Manager authentication?

The Convergence configurator by default uses LDAP authentication for authentication mechanism. For authentication through Access Manager in Legacy mode, type the following command:

iwcadmin -o auth.am.enable -v true

To enable Access Manager in realm mode for authentication, set the auth.am.realmmode and auth.am.enable parameters to true. Type the following command:

iwcadmin -o auth.am.realmmode -v true
Note
To set up an authentication realm in Access Manager, you should also read the following example: Convergence Configuration Example - Creating an Authentication Realm in Access Manager in addition to reading this section.

How do I set up Access Manager SSO?

Access Manager Single Sign-On can be enabled by setting the following parameters:

  • sso.am.enable - Set this parameter to true.
  • sso.adminuid - Set this parameter to Access Manager's administrator user ID.
  • sso.adminpwd - Set this parameter to Access Manager's administrator password.
  • sso.enablerefreshsso - Set this parameter to true to enable Access Manager SSO refresh.
  • sso.refreshinterval - Set this to the Access Manager maximum session idle time (in percentage) after which the SSO token should be refreshed.
  • sso.enablesignoff - Set this parameter to true to enable single sign-off.
  • sso.loginpage - Set this parameter to redirect the user to login page.
    Note
    User is redirected to the page that is set using the sso.loginpage parameter when the user tries to access Convergence without authenticating with Access Manager or after session timeout. The valid entry for sso.loginpage parameter is Access Manager Login URL with goto URL to Convergence and it is used only when SSO is enabled.
    For example: sso.loginpage = "http://AccessManagerHost:Port/amserver/UI/Login?goto=http://ConvergenceHost:Port/iwc"

For example:

iwcadmin -o  sso.am.enable -v true
iwcadmin -o  sso.adminuid -v <adminuserid>
iwcadmin -o  sso.adminpwd -v <adminpassword>
iwcadmin -o  sso.enablerefreshsso -v true
iwcadmin -o  sso.refreshinterval -v 10
iwcadmin -o  sso.enablesignoff -v true
iwcadmin -o  sso.loginpage -v <login_page>

OpenSSO

Note
Open SSO is only supported on Convergence 2.x and earlier. See: Deprecated Support of Access Manager and Sun OpenSSO.

How do I set up OpenSSO SSO and Authentication in Convergence ?

See Configuring Convergence With OpenSSO Enterprise 8.0 for Authentication and SSO.

Basic Monitoring

Monitoring is the process of gathering run time data, exposing the data, and computing quality of service so that an administrator can assess the performance of the deployment. This section describes how to monitor Convergence. Convergence can be monitored using any JMX (Java Management Extension) compliant monitoring client.

What are the parameters that can be monitored in Convergence?

You can monitor the following components and modules:

  • Authentication LDAP
    • Hostname of the directory server from which the connections are being served
    • Number of free connections in the pool
    • Number of used connections in the pool
  • Calendar Service Connection
    • Total number of active sessions
    • Details of each active session. Including user ID, IP address, domain name, and the duration of this connection
    • Number of sessions since the start of the server
  • Mail Service Connection
    • Total number of active sessions
    • Details of each active session. Including user ID, IP address, domain name, and the duration of this connection
    • Number of sessions since the start of the server
  • Session
    • Total number of active sessions
    • Details of each active session
    • Number of sessions since the start of the server
  • User and Group LDAP
    • Host name of the directory server from which the connections are being served
    • Number of free connections in the pool
    • Number of used connections in the pool

You can also see the duration for which the server is active.

How do I monitor Convergence using Jconsole?

Jconsole is a JMX-compliant GUI tool that connects to a running JVM. The JMX management agent to monitor the server is not started on server startup by default. You can start the management agent by setting the admin.enablemonitoring attribute by using the iwcadmin command-line utility. To enable monitoring, type the following command:

iwcadmin -o admin.enablemonitoring -v true
Note
You must restart the Application Server for Convergence 1.x (or GlassFish Server starting with Convergence 2) if you make any configuration changes by using the iwcadmin command.

To monitor the various parameters in Convergence:

  1. Start Jconsole.
    To start Jconsole, run the following command:
    #<JAVA_HOME>/bin/jconsole
    

    The Jconsole Connection Agent dialog box appears.
    Jconsole connection window

  2. Click the Advanced tab.
  3. In the JMX URL field type service:jmx:rmi://<hostname>:port/jndi/rmi://<hostname>:port/jmxrmi.
    Tip
    You can obtain this URL from the iwc.log file. The JMX console URL is written to the log file when Convergence server starts the admin server.
    Here is an example:
    CONFIG: INFO from com.sun.comms.client.admin.web.JMXAgent  Thread pool-1-thread-7 \\
    at 2009-02-23 21:55:31,981 - RMI connector server in non-SSL mode started successfully.
    CONFIG: INFO from com.sun.comms.client.admin.web.JMXAgent  Thread pool-1-thread-7 \\
    at 2009-02-23 21:55:31,983 - Service URL is: \\
    [ service:jmx:rmi://siroe.com:50005/jndi/rmi://siroe.com:50005/jmxrmi ]
    



  4. Enter the administrator userid and password.
  5. Click Connect.
  6. Expand the Monitoring node.

On the right hand side of the screen you will see the various components of JVM available in tabs. The leaves under the Monitoring node on the left hand side shows the various Instruments that can be used to monitor the JVM.

Logging

Convergence creates log files that records events, status of various software components, system errors, and other aspects of the server such as session, IP addresses and so on. By examining the log files, you can monitor the server's operation. This section provides information about logging:

How do I enable logging?

Communcation Center uses a set of loggers for various components of the server. You can enable and set log levels for each of the components by using the iwcadmin command.

For example, the following command sets the Address Book logging to the level INFO.

iwcadmin -o log.ADDRESS_BOOK.level -v INFO

What are the existing Log Levels?

Convergence uses Apache Log4j as its underlying logging framework. All the log levels that Log4j offers are available in Convergence. The following log levels are available:

  • OFF
  • ERROR
  • WARN
  • INFO
  • DEBUG

What are the components for which I can enable logging?

The following are the components of Convergence that you can set logging information.

  • Address Book
  • Administration
  • Authentication
  • Configuration
  • Default
  • Protocol
  • Proxy
  • Mail Proxy
  • SIEVE filters

For each of the above components, you can set a log level. The existing log levels are described in What are the Different Log Levels Available?. To see the list of components for which logging can be enabled, use the following command:

iwcadmin -l | grep log.*.level

log.ADDRESS_BOOK.level = INFO
log.ADMIN.level = INFO
log.AUTH.level = DEBUG
log.CONFIG.level = INFO
log.DEFAULT.level = INFO
log.PROTOCOL.level = INFO
log.PROXY_CAL.level = INFO
log.PROXY_MAIL.level = INFO
log.SIEVE.level = INFO

How do I specify a log file location?

You can specify the following log locations:

  • Application log location: All log information generated by the server are sent to the application log. This log file contains information about the behavior of the application.
  • Administration log location: All log information that is generated by the administration command-line utility, iwcadmin are sent to the administration log location.

To set log information for the application logger, type the following command:

iwcadmin -W  /location/mypasswordfile -o log.location -v /data/logs/

To set the logging information for the administration logger, use the following command:

iwcadmin  -W  /location/mypasswordfile -o log.adminloglocation -v /data/logs/newadminlogfile.log

Can the administration log file be separate from the application log file?

Yes, the administration log file is separate from the application log.

Type the following command to determine the administration log file location:

iwcadmin -W /location/mypasswordfile -o log.adminloglocation

What is log rotation and how do I enable rotation policy for logs?

Log rotation is an approach to manage log files by renaming the existing log file and creating a new log file. All the log messages generated after creating the new file is written in this new log file.

Convergence supports log rotation based on size or time. Size-based log rotation is triggered when the log file reaches a specified size in kb (kilobytes). Time based log rotation is triggered based on the date pattern specified by the administrator.

This example shows how to set size based log rotation:

iwcadmin -W /location/mypasswordfile -o log.sizetriggerval -v 102400

This example shows how to set time based log rotation policy:

iwcadmin -W /location/mypasswordfile -o log.timetriggerval -v "'.'yyyy-MM"

For more information about frequency patterns for time based log rotation, see http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/DailyRollingFileAppender.html.

How do I log the IP address and the session tracking information for a user?

To log IP address and session tracking information, you must modify the log pattern to include the IP address and session ID of a user so that these get added into the log file. Type the following command:

Modify the log-pattern to include the user IP address (%X{ipaddress}) and session id (%X{sessionid}) in the log messages.

Note
If the GlassFish Server hosting Convergence resides behind a front-end reverse proxy or load balancer (WebServer), this front-end's IP address is captured, not the browser's IP address. To overcome this situation, use the following command to set the authPassthroughEnabled parameter to true on the GlassFish Server.
./asadmin set <CLUSTER_NAME>-config.http-service.property.authPassthroughEnabled=true

In case you are using a reverse proxy in front of Convergence, you have to configure that reverse proxy to put the original client IP address into an HTTP Header that must be called proxy-ip.
GlassFish Load Balancer plugin automatically adds client original IP address to HTTP Header proxy-ip.


What does a typical Convergence logging session look like?

The following example shows a typical logging session:

PROTOCOL: DEBUG from com.sun.comms.client.web.IwcCookieManager Thread httpSSLWorkerThread-80-23 ipaddress=198.51.100.0 sessionid= at 23:08:31,920- cleaning client cookies: webmailcookiename is webmailsid
PROTOCOL: DEBUG from com.sun.comms.client.web.IwcCookieManager Thread httpSSLWorkerThread-80-23 ipaddress=198.51.100.0 sessionid= at 23:08:31,920- cleaning client cookies: webmailcookiepath is /
PROTOCOL: DEBUG from com.sun.comms.client.web.IwcCookieManager Thread httpSSLWorkerThread-80-23 ipaddress=198.51.100.0 sessionid= at 23:08:31,920-  Cookie sent by client : JSESSIONID value=687380a1199c738c5165692c4587 path=null comment=null domain=null version=0 isSecure? false maxAge=-1
PROTOCOL: DEBUG from com.sun.comms.client.web.IwcCookieManager Thread httpSSLWorkerThread-80-23 ipaddress=198.51.100.0 sessionid= at 23:08:31,921- Removing iwc client cookie JSESSIONID

These messages indicate that the user session has been invalidated by the server. There are a few reasons why a user session is invalidated:

  • a logout is issued from the browser.
  • a new login is initiated, but there is already active session in progress.
  • the Application Server is shutdown. All sessions are then invalidated.

User Options

How do I set end user option defaults for Convergence?

Convergence provides default values for user attributes. However, you can change these default values to suite your needs.

For Convergence 1.x: the default values can be changed by using the imadmin command-line utility. To see a list of all the user options, see User Preferences Configuration Properties for Convergence 1.x.

For Convergence 2 and later: the default values can be changed by using the iwcadmin command-line utility. To see a list of all the user options, see User Preferences Configuration Properties for Convergence 2 and later

How do I change the set of services available to users of Convergence?

See Enabling Services for Convergence.

SSL

How do I configure SSL in Convergence?

SSL provides a secure means of communication between the web-browser client and the server. You can enable SSL in Convergence in two ways:

  • At the time of configuring Convergence, or
  • By setting the SSL configuration parameters after configuration.

To enable Convergence to use SSL, you must enable SSL at the Application Server level for Convergence 1.x (or GlassFish Server for Convergence 2 and later) and also set the base.sslport configuration parameters using the iwcadmin command-line utility.

For base.sslport properties, refer to Global Configuration Properties.

iwcadmin -o base.sslport -v <base_ssl_port>

What is authentication only SSL and how do I configure it?

Authentication-Only SSL is a mechanism in which users are authenticated by using the HTTPS protocol which prevents user authentication details from being sent unencrypted. All other requests from the client are performed using the HTTP protocol. To configure Convergence to use Authentication only SSL, you must set both the base.sslport to the Application Server (or GlassFish Server for Convergence 2 and later) SSL port value, and the base.enableauthonlyssl value using the iwcadmin command-line utility. For example:

iwcadmin -o base.sslport -v <base_ssl_port>
iwcadmin -o base.enableauthonlyssl -v true

How do I enable SSL for back-end servers?

To enable SSL for back-end servers, you must set the SSL parameters for Mail and Calendar servers by using the iwcadmin command-line utility:

Enabling SSL for Mail Server

To enable SSL for mail server, set the mail.enable and mail.port configuration parameters.

iwcadmin -o mail.enablessl -v true
iwcadmin -o mail.port -v <mail_port>
Note
Mail server must be running in SSL mode on this port.

Enabling SSL for Calendar Server

To enable SSL for Calendar server, set the cal.enablessl and cal.port configuration properties.

iwcadmin -o cal.enablessl -v true
iwcadmin -o cal.port -v <calendar_port>
Note
Calendar server must be running in SSL mode on this port.

Enabling SSL for Address Book

Address book is a part of Convergence server. If you need to configure Address Book for SSL, Convergence should be configured for SSL. You can also configure Convergence to communicate with Directory in SSL mode.

Enabling SSL for Instant Messaging

In the case of Instant Messaging server, end to end (that is, Instant Messaging web client to Instant Messaging Back-end server) TLS/SSL is not supported. The reason being, whenever chat messages are sent to the instant messaging server, they pass through HTTP bind. HTTP bind in turn interprets these messages and sends them to the instant messaging server. Therefore, an SSL connection is not possible.

You can however configure HTTP bind and instant messaging server to communicate in TLS (Transport Layer Security) mode. Enable the following parameters in the iim.conf file. The iim.conf file is present in the /opt/sun/comms/im/config/ directory.

iim_server.component.requiressl=true

When this parameter is enabled, the server mandates that the communication from HTTP bind happens only by TLS. That is, the server will send and receive only enctypted data and messages.

Set the iim_server parameter to true to enable SSL.

iim_server.usessl=true

Set the iim_server.sslkeystore parameter to point to the location of the SSL keystore file.

iim_server.sslkeystore=/opt/SUNWiim/config/<keystore_file_name>.jks

Set the iim_server.keystorepasswordfile parameter to the SSL password.

iim_server.keystorepasswordfile=/opt/SUNWiim/config/sslpassword.conf

Address Book

Which data store is used by address book in an out of the box setup?

Address book uses user group directory server configuration for personal address book and corporate directory.

How do I configure horizontal scalability for personal address book?

See Configuring Horizontal Scalability of Address Book.

How to configure address book to use directory server other than user group directory server?

To configure Personal Address Book to use directory server other than user group directory server, set the following configuration parameters:

  • ab.pstore.[<identifier>].ldaphost - Set this parameter to the hostname of the LDAP server.
  • ab.pstore.[<identifier>].ldapport - Set this parameter to the port number on which the LDAP server listens.
  • ab.pstore.[<identifier>].ldapbinddn - Set this parameter to the LDAP binddn value of the LDAP server.
  • ab.pstore.[<identifier>].ldapbindcred - Set this parameter to the Bind credentials of the LDAP server.

The following example shows the configuration parameter settings:

iwcadmin -W /location/mypasswordfile -o ab.pstore.[psidentifier1].ldaphost -v host.siroe.com
iwcadmin -W /location/mypasswordfile -o ab.pstore.[psidentifier1].ldapport -v 400
iwcadmin -W /location/mypasswordfile -o ab.pstore.[psidentifier1].ldapbinddn -v "cn=Directory Manager"
iwcadmin -W /location/mypasswordfile -o ab.pstore.[psidentifier1].ldapbindcred -v dmcredentials

Personal store can be configured with multiple directory servers. In above example psidentifier1 is used to identify personal store configuration for siroe.com.

If the above configured directory server needs to act as the personal store's default server, then set the {ab.pstore.defaultserver}} configuration parameter. Here is an example:

iwcadmin -W /location/mypasswordfile -o ab.pstore.defaultserver -v psidentifier1

How do I configure the corporate directory?

To configure corporate directory to use directory server other than user group directory server, set the following configuration parameters:

  • ab.corpdir.[<identifier>].ldaphost
  • ab.corpdir.[<identifier>].ldapport
  • ab.corpdir.[<identifier>].ldapbinddn
  • ab.corpdir.[<identifier>].ldapbindcred

The following example has the configuration parameters settings:

iwcadmin  -W /location/mypasswordfile -o ab.corpdir.[default].ldaphost -v host.siroe.com
iwcadmin  -W /location/mypasswordfile -o ab.corpdir.[default].ldapport -v 400
iwcadmin  -W /location/mypasswordfile -o ab.corpdir.[default].ldapbinddn -v "cn=Directory Manager"
iwcadmin  -W /location/mypasswordfile -o ab.corpdir.[default].ldapbindcred -v xyzxyz

In the above example default is used to identify corporate directory configuration for host.siroe.com.

Note
For a single corporate directory configuration, you must use default as the identifier.

To configure and enable multiple corporate directories, see: Setting Up Multiple Corporate Directories in Convergence.

How do I enable autocompletion of address for Corporate Directory?

To enable auto completion of email address for Corporate Directory, you must set the client.enablecorpabautocomplete configuration parameter to true.

iwcadmin -o client.enablecorpabautocomplete -v true
Note
The search results will appear in the Convergence client, after the first three characters of the name or email address are typed.

How to set up a domain based configuration for address book?

You can set up a domain based configuration for Personal Address Book and Corporate Directory.

To set up domain-based configuration for Personal Address Book, set the following parameters by using the iwcadmin command-line utility:

  • ab.{<identifier>}.psrootpattern
  • ab.{<identifier>}.pstore.defaultserver
  • ab.{<identifier>}.pstore.[<identifier>].ldaphost
  • ab.{<identifier>}.pstore.[<identifier>].ldapport
  • ab.{<identifier>}.pstore.[<identifier>].ldapbinddn
  • ab.{<identifier>}.pstore.[<identifier>].ldapbindcred

The following example shows the configuration parameter settings:

iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.psrootpattern -v ldap:///piPStoreOwner=%U,o=%D,o=PiServerDb
iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.pstore.defaultserver -v domainid1
iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.pstore.[domainid1].ldaphost -v host.xyz.com
iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.pstore.[domainid1].ldapport -v 400
iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.pstore.[domainid1].ldapbinddn -v "cn=Directory Manager"
iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.pstore.[domainid1].ldapbindcred -v xyzcred

In the above example, somedomain.com is the domain (within curly braces).

All the above configuration data for the domain somedomain.com is grouped in to one logical set identified by using the identifier domainid1.

The example shows the minimum set of configuration parameters that you need to set for the domain based configuration for Personal Address Book. However, you can set other configuration parameters.

To set the lookthrulimit to 2000 for Personal Address Book in domain somedomain.com, type the following command:

iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.pstore.lookthrulimit -v 2000.

To set up domain-based configuration for Corporate Directory:

  1. Set the following configuration parameters:
    • ab.{<identifier>}.corpdir.[<identifier>].urlmatch
    • ab.{<identifier>}.corpdir.[<identifier>].searchattr
    • ab.{<identifier>}.corpdir.[<identifier>].lookthrulimit
    • ab.{<identifier>}.corpdir.[<identifier>].ldaphost
    • ab.{<identifier>}.corpdir.[<identifier>].ldapport
    • ab.{<identifier>}.corpdir.[<identifier>].ldapbinddn
    • ab.{<identifier>}.corpdir.[<identifier>].ldapbindcred
      The following example shows the configuration parameter settings:
      iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.corpdir.[corpdomainid1].urlmatch
      -v ldap://corp-directory1
      iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.corpdir.[corpdomainid1].searchattr
      -v entry/displayname,@uid
      iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.corpdir.[corpdomainid1].lookthrulimit
      -v 3000
      iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.corpdir.[corpdomainid1].ldaphost
      -v host.abc.com
      iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.corpdir.[corpdomainid1].ldapport
      -v 389
      iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.corpdir.[corpdomainid1].ldapbinddn
      -v "cn=Directory Manager"
      iwcadmin  -W /location/mypasswordfile -o ab.{somedomain.com}.corpdir.[corpdomainid1].ldapbindcred
      -v abcabc
      
      Note
      The value for the urlmatch configuration parameter must be unique.
      Format for urlmatch is ldap://<unique_value> or ldap://host:port/DN
      e.g. ldap://corp-directory1 ,ldap://corporatedirectory2, ldap://somehost:390/ou=people,o=ab.org etc.

      First time when user does address book operation (apart from login.wabp), corporate directory entry(under piPStoreOwner=<user>, o=<domain>, o=PiServerDb) with piRemotePiURL attribute value as urlmatch gets created . After this if urlmatch is changed, either delete such entries so that this entry gets created when first AB command is issued or update corporate directory entry for all users with new urlmatch value.


      In the above example, somedomain.com specifies the domain. All the above configuration data for the domain somedomain.com is grouped in to one logical set identified by using identifier corpdomainid1.

  2. Copy dictionary-<locale>.xml (for example: dictionary-en.xml) from convergence_srv_base/config/templates/ab/domain/defaultps to convergence_srv_base/config/templates/ab/domain/<domain-directory>. The dictionary-<locale>.xml file can be updated in order to change or to customize display name and description.

How do I disable the Corporate Directory in specific domains?

In some cases, you might want to disable your corporate directory in certain domains. To do so, follow these steps:

  1. Set both personal address book and Corporate Directory settings as described in How to set up a domain based configuration for address book?
  2. Disable the Corporate Directory for the specific domain:
  3. Restart GlassFish Server.
    Note
    You can ignore errors or exceptions in the log files.

How do I change the default Corporate Directory search filter in Address Book?

Note
In Convergence 1.x patch 137631-01 (Solaris Sparc), 137632-01 (Solaris x86), 137633-01 (Linux) or greater is required for this functionality to work as documented.

To change the default corporate directory search filter, you must set the ab.corpdir.[<identifier>].searchfilter configuration parameter with the search criteria you want to base your corporate directory searches on.

The following is an example of the usage of search customization:

iwcadmin -o ab.corpdir.[default].searchattr
-v entry/displayname,@uid,person/surname
iwcadmin -o ab.corpdir.[default].searchfilter
-v '(&(&([filter])(|(objectClass=GROUPOFUNIQUENAMES)(objectClass=GROUPOFURLS) \\
(objectClass=ICSCALENDARRESOURCE)(objectClass=INETORGPERSON)))(objectClass=*))'

In the above command, [filter] is replaced with the search generated by the ab.corpdir.[<identifier>].searchattr configuration option.

The above example produced the following LDAP output in the corporate LDAP directory access logs when an end-user searched for "bob":

[13/Oct/2008:11:51:54 +1100] conn=686404 op=30 msgId=576 - SRCH base="o=sun.com,o=isp" scope=2
filter="(&(&(|(|(cn=bob*)(uid=bob*))(sn=bob*))(|(objectClass=GROUPOFUNIQUENAMES)(objectClass=GROUPOFURLS)
(objectClass=ICSCALENDARRESOURCE)(objectClass=INETORGPERSON)))(objectClass=*))"
attrs="objectClass createTimestamp cn uid description mail multiLineDescription modifyTimestamp"

How do I configure Convergence to make use of Virtual List View (VLV) for Corporate Directory?

Follow these steps to configure Convergence to make use of VLV:

  1. Configure Directory Server with VLV. For more information on creating and managing browsing indexes in Directory Server:
  2. Set the VLV filter and scope in the corporate directory.
    iwcadmin -o ab.corpdir.[default].vlvfilter -v "(&(mail=*)(cn=*))"
    iwcadmin -o ab.corpdir.[default].vlvscope -v 2
    
  3. Enable the ab.corpdir.[default].vlvpaging configuration parameter to true.
    iwcadmin -o ab.corpdir.[default].vlvpaging -v true
    

What vCard standards does supported by Convergence?

Convergence supports the following vCard standards:

  • vCard 2.1
  • vCard 3.0

What character formats does the Convergence Address Book support for importing and exporting vCard?

Convergence supports the following encoding formats:

  • UTF-8
  • ISO-8859-1
  • BIG5
  • EUC-CN
  • EUC-JP
  • EUC-KR
  • SHIFT_JIS

How do I change the character set for a locale to import or export vCard entries?

Convergence supports the following locales:

  • English
  • Japanese
  • French
  • German
  • Spanish
  • Korean
  • Traditional Chinese
  • Simplified Chinese

For each locale, configuration parameters for import and export exist in the Convergence server. By default, these configuration parameters are assigned a character encoding when you install Convergence.

The following table shows the default encoding formats for locales when Convergence is installed. The table also lists the configuration parameters that are assigned for storing the import and export preference for the locale.

Locale Encoding Configuration Parameter for Import Configuration Parameter for Export
English UTF-8 ab.import.vcard.misc.en ab.export.vcard.misc.en
Japanese UTF_8 ab.import.vcard.misc.ja ab.export.vcard.misc.ja
French UTF-8 ab.import.vcard.misc.fr ab.export.vcard.misc.fr
German UTF-8 ab.import.vcard.misc.de ab.export.vcard.misc.de
Korean UTF-8 ab.import.vcard.misc.ko ab.export.vcard.misc.ko
Traditional Chinese UTF-8 ab.import.vcard.misc.zh-tw ab.export.vcard.misc.zh-tw
Simplified Chinese UTF-8 ab.import.vcard.misc.zh-cn ab.export.vcard.misc.zh-cn

In the previous table, the character encoding for English is set to UTF-8. This setting means that when you import or export vCard contacts to or from the Convergence client, the vCard entries are imported or exported in the UTF-8 format character set. In this case, UTF-8 is the default setting for English users.

To enable the Convergence client to import or export vCard entries to other character sets, set the address book vCard configuration parameter in the Convergence server. To learn more about the character sets supported by Convergence, see What character sets does Convergence Address Book support for importing and exporting vCard?.

Type the iwcadmin command to set the import and export character set preferences for the configuration parameters of the locale. This command enables you to change the character set encoding for importing or exporting vCard entries.

To change the character encoding for the Japanese user vCard from UTF-8 to Shift_JIS for example, set the corresponding configuration parameters for import and export.

To set the character encoding to import vCard entries for the Japanese locale, type the following command:

iwcadmin -o ab.import.vcard.misc.ja -v Shift_JIS

To set the character encoding to export vCard entries for the Japanese locale, type the following command:

iwcadmin -o ab.export.vcard.misc.ja -v Shift_JIS

The vCard entries are imported or exported in the Shift_JIS encoding character set.

Note
You must set the same character set encoding for both import and export for a locale.

How to enable export and import of contacts with photo in vCard 3.0?

Convergence supports Vcard 3.0. Vcard 3.0 enables users to include photos in their contacts. By default, Convergence does not import or export photos of your contacts. If you want photos to be imported or exported, you must enable the ab.exportphoto and ab.importphoto configuration parameters.

To enable exporting of contacts with photo in Vcard 3.0 format, type the following command:

iwcadmin -W /location/mypasswordfile -o ab.exportphoto -v true

To import contacts with photo in Vcard 3.0 format, type the following command:

iwcadmin -W /location/mypasswordfile -o ab.importphoto -v true

How do I hide the admin accounts from the Corporate Directory in the default domain?

Note
Convergence 1.x patch 137631-01 (Solaris Sparc), 137632-01 (Solaris x86), 137633-01 (Linux) or greater is required for this functionality to work as documented.

When looking in the Corporate Directory of the default domain all the administrative accounts are being displayed. These can be hidden by using psIncludeInGAB attribute in the ldap server. The default value of this attribute is true.

If you want to hide users in the Corporate Directory, set in a first step the psIncludeInGAB attribute to false for these users.
Next, the corporate directory search filter needs to exclude these users with their psIncludeInGAB attribute set to false. Changing the search filter is documented here but an example of this can be the following :

iwcadmin -W /location/mypasswordfile -o ab.corpdir.[default].searchfilter  -v
"(&(&(&([filter])(|(objectClass=GROUPOFUNIQUENAMES)(objectClass=GROUPOFURLS) \\
(objectClass=ICSCALENDARRESOURCE) (objectClass=INETORGPERSON)))(objectClass=*))(!(psIncludeInGAB=false)))"

How do I remove personal address books of deleted users?

See: How Do You Remove the Personal Address Books of Deleted Users?

What does Convergence do with personal address book contacts that have been deleted by the end user?

If a contact has been deleted by the end user, Convergence determines what do to with that information based on how you set the ab.pstore.deleteperm configuration parameter. If you set the parameter to true, the contact is deleted from the user's personal address book entries on Directory Server. If, however, you set ab.ps.deleteperm to false, the following attribute/value pair is added to the deleted contact in Directory Server:

The contact no longer displays in the Convergence UI as if it were permanently deleted from the Directory Server.

This task can be particularly useful when you are synchronizing deleted contact entries in Microsoft Outlook and Convergence when using Connector for Microsoft Outlook.

Single Sign-on

How do I configure Convergence for trusted circle SSO?

To configure Convergence to use Trusted Circle SSO, you must enable the sso.ms.enable configuration parameter.

iwcadmin -o sso.ms.enable -v true

How do I configure Convergence for Single Sign-Off?

Enabling SSO, by default enables Single Sign-Off. If you have configured Convergence for Access Manager SSO, execute these commands to enable Single Sign-Off:

iwcadmin -o sso.enablesignoff -v true
iwcadmin -o sso.notifyserviceimpl -v com.sun.comms.client.security.sso.impl.AMSSOTokenListener

If you have configured Convergence for Messaging SSO, type the following command to enable Single Sign-Off:

iwcadmin -o sso.enablesignoff -v true
Note
As of Communications Suite 7 Update 1, support for Access Manager has been deprecated. See: Deprecated Support of Access Manager and Sun OpenSSO.

How do I write custom SSO module for convergence?

See Writing a Pluggable SSO Module for Convergence .

LDAP Service

How do I configure LDAP failover for Convergence?

To configure Convergence for LDAP failover, type the following command:

iwcadmin -o ugldap.host -v ldap1:port1,ldap2:port2

ldap1:port1 and ldap2:port2 are the LDAP servers that are a part of the failover.

If your LDAP hosts are configured for SSL, all the failover LDAP servers in the failover mechanism are also in SSL mode. Each host does not have a separate SSL flag. All the LDAP servers should have the same privileged userid and password. All the LDAP servers should run in Master-Master replication mode.

How do I change the Convergence display name to map to the LDAP displayName?

See: Administering Convergence Display Name to Map to LDAP displayName.

Configuration Management

How do I configure Convergence to use SSL for configuration management?

To configure Convergence for SSL, you must first configure the Convergence server to accept SSL requests. Additionally, you must also configure the client utility: the iwcadmin command to communicate to the Convergence server in SSL mode.

To configure Convergence server administration for SSL:

  1. Enable SSL by using the iwcadmin command.
    iwcadmin -o admin.enablessl -v true
    
  2. Generate keystore and truststore using keytool.
  3. Set the keystore password.
    iwcadmin -o admin.keystorepwd -v password
    
  4. Copy keystore to the configuration and data files directory. The default location of this directory is /var/opt/sun/comms/iwc/
  5. Restart Application Server for Convergence 1.x (or GlassFish Server starting with Convergence 2 and later).

The following log message appears indicates that the SSL configuration is a successful:

RMI connector server in SSL mode started successfully.

Set up the client to securely connect to Convergence. To do this, modify the following parameters in the iwcadmin.properties file. This file is available in the configuration and data files directory. The default path is: /var/opt/sun/comms/iwc.

  1. Set the paramater secure to true. Optionally, you can use the -s option in the iwcadmin command.
  2. Set the truststorepath parameter to the directory where you stored the truststore generated in the Step 2 in the above procedure.
  3. Set the password to truststorepasswd= <truststorepassword>

How do I change Convergence administrator user password?

To change the Convergence administrator password, type the following command.

iwcadmin -o admin.adminpwd -v <newpassword>

Deployment Specific Customizable Client Options for Convergence

How do I customize the Login page based on the domain name in the URL to access the Convergence client?

Convergence enables you to configure multiple domains in a deployment. Users can login to a domain by typing the URL and suffix the domain name to the user name. For example, user1@siroe.com. On successful authentication, the domain information is extracted from the login name and the user is logged into the specific domain.

Convergence provides an alternative way for users to log in to a specific domain. For example, you can configure Convergence to display a customized login page based on the domain information. The Convergence server displays the login page by extracting the domain name from the URL and determining if it contains a known domain and presents the domain specific login screen for the domain. The user can then type the user name and password and login to the domain. Note that in this case the user will not have to suffix the domain name to the user name.

Consider an example where siroe.com is a configured domain for a Convergence deployment. When users access Convergence by typing the URL http://webmail.siroe.com/, the server presents a customized login page for the domain siroe.com. Convergence server determines this based on the value of the client.{domain-name}.loginpage property. To set a customized login page for a domain, set the client.{domain-name}.loginpage configuration property by typing the following command.

How do I set the auto logout time?

Convergence enables you to set a time in minutes to automatically log out of the application in case of user inactivity in client and also when the user closes the application without logging out. By default, the time is set to zero and is disabled. To set a time and enable the automatic logout option, set the client.autologouttime configuration property by typing the following command.

Note
Convergence 1.x patch 13 or greater is required for the automatic logout feature to work.

How do I remove the option to compose messages using Rich Text Formatting?

Convergence enables you to remove the Rich Text Formatting option for composing messages. To do so, set the client.enablertfcompose configuration property to false. By default, this parameter is set to true. For example:

See: Deployment Specific Customizable Client Options for the Convergence Interface Reference.

Instant Messaging

How Do I Configure Multiple Domains for Instant Messaging?

After creating a new non default domain (by using the Delegated Administrator GUI for example), you need to perform the following steps to enable Instant Messaging for users in a new domain:

In this example the user or group base is dc=example,dc=com. The new domain is called Hosted Domain and it has a DNS domain name of other.hosteddomain.com.

1. Run the Instant Messaging imadmin assign_services utility.

2. Edit the Convergence httpbind.conf file to to include both default domain and hosted domains to the default.domains attribute, for example:

You should then be able to log in to Convergence as user@hosteddomain. The default domain user can log in with just the UID.

For more information on hosted domain support in Instant Messaging, see Configuring Hosted Domain Support.

How Do I Configure Convergence so that Presence Information is Shown in my Email?

Configuring Convergence with Instant Messaging 8

To enable Convergence to show presence information in email, you must edit the iim.conf file. The iim.conf file is available at im-svr-base/config/iim.conf

  1. Add the following lines in the iim.conf file.
  2. Restart the Instant Messaging server.

Configuring Convergence with Instant Messaging 9

To enable Convergence to show presence information in email, use the imconfutil command to modify the iim.conf.xml file. The iim.conf.xml file is available at im-svr-base/config/iim.conf.xml

  1. Run imconfutil to set the following properties in the iim.conf.xml file.

    Note
    Beginning with Instant Messaging 9 Patch 1, mailalternateaddress, mailequivalentaddress, and mail are default Instant Messaging presence statuses for iim_server.roster.extra.attributes.mail.
  2. Restart the Instant Messaging server.

Enabling Anti-Spam

Note
If you are using Sun Convergence 1 Update 2, perform the steps documented in the section I'm using Convergence 1 Update 2. How do I Enable the Anti-Spam feature?

How do I Enable the Anti-Spam feature?

You can configure Convergence to take action against spam messages in the following ways:

  • By setting the anti-spam related parameters in Convergence
  • By integrating a spam filter in Messaging Server in addition to setting the anti-spam related parameters in Convergence

Configuring Convergence for Anti-Spam Action

Set the following parameters in Convergence:

  • mail.spam.enableaction: Set this parameter to true to enable the anti-spam functionality. Setting this parameter will enable users to take action against spam messages.
  • mail.spam.folder: Set this parameter to the folder name into which spam messages should be moved.
    Note
    You must restart Application Server for Convergence 1.x (or GlassFish Server starting with Convergence 2 and later) after making the configuration changes.

When you set the above parameters, the following spam related functionality will be available in the Convergence client:

  • A system folder is made available as the designated spam folder. This is based on the value set for the mail.spam.folder parameter assigned by the administrator.
  • Users will be able to mark messages as spam or not spam. Messages marked as spam are moved into the designated spam folder and messages that are marked as not spam are moved into the Inbox.

Configuring Messaging Server in Addition to Configuring Convergence for Anti-Spam Action

A more effective way to counter spam messages is to deploy a spam filer at the back-end Messaging Server in addition to enabling the anti-spam functionality in Convergence. For information on how to integrate a spam filter with the Messaging Server, see Integrating Spam and Virus Filtering Programs Into Messaging Server.

After integrating the spam filter, set the value of the service.feedback.spam parameter in Messaging Server to the email address at which spam reports are accepted.

When you set this parameter, the following spam related functionality will be available to the Convergence client.

  • Users will be able to mark messages as spam. When users mark a message as spam, the message is flagged in the message store, and forwarded to the email address set for the service.feedback.spam configuration utility option. The spam messages are marked in the message list and displayed with a warning in the message viewer.
  • Users will be able to mark messages incorrectly identified as spam, as not spam. When the user marks incorrectly identified spam messages as not spam, the flag is removed from the message in the message store.

If Messaging Server is configured with a spam filter that accepts reports of messages that are incorrectly identified as spam, set the value of the parameter service.feedback.notspam to the email address at which Convergence will forward the messages marked as not a spam.

Note
You must restart Messaging Server after making these configuration changes.

Set the the anti-spam related parameters in Convergence. See Configuring Convergence for Anti-Spam Action.

I'm using Convergence 1 Update 2. How do I Enable the Anti-Spam feature?

Note
The feature documented in this section is applicable for Convergence 1 Update 2 release.

To use the spam feature in the Convergence client, you must deploy a spam filer in the backend Messaging Server. For information on how to integrate a spam filter with the Messaging Server, see Integrating Spam and Virus Filtering Programs Into Messaging Server.

To enable marking of spam messages in the Convergence client, set the value of the service.feedback.spam parameter in Messaging Server to the email address at which the spam filter accepts spam reports.

When you set this parameter, the following spam related functionality will be available to the Convergence client.

  • Users will be able to mark messages as spam. When users mark a message as spam, the message is flagged in the message store, and forwarded to the spam filter. The spam messages are marked in the message list and displayed with a warning in the message viewer.
  • Users will be able to mark messages incorrectly identified as spam as not spam. When the user marks incorrectly identified spam messages as not spam, the flag is removed from the message in the message store.

If Messaging Server is configured with a spam filter that accepts reports of messages that are incorrectly identified as spam, set the value of the parameter service.feedback.notspam to the email address at which the spam filter accepts such reports.

When you set the service.feedback.notspam parameter, in addition to the functionality described above, the Convergence client also forwards the messages that should not be flagged as spam to the spam filter.

Note
You must restart Messaging Server after making these configuration changes.

Enabling Indexing and Search Service

Indexing and Search Service (ISS) is a general-purpose indexing and searching server. Convergence can be configured to use the indexing and search capabilities of ISS.

To configure Indexing and Search Service with Convergence, you must have the ISS server installed and configured. To know more about how to do this, see Indexing and Search Service Documentation.

To enable Convergence to work with ISS, perform the following steps:

  1. Enable the following ISS related parameters in Convergence:
    • ISS.enable - Set this parameter to true to enable the search service.
    • ISS.host - Set this parameter to the hostname on which the ISS server installed.
    • ISS.port - Set this parameter to the web component port number on which ISS is deployed. This should be the same as the port number for appserver.web.port in the ISS configuration file: jiss.conf.
      Note
      If you want a secure connection between Convergence and ISS, set the ISS.enablessl parameter to true. Correspondingly, you must also set the port number (ISS.port) to the SSL port number.
      Note
      Beginning with Convergence 2, set the following parameters:
    • ISS.proxyadminid - Set this parameter to the proxy admin ID for ISS. This should be the same as the Store Admin Username specified during ISS configuration (the value of mail.imap.admin.username in the jiss.conf file).
    • ISS.proxyadminpwd - Set this parameter to the proxy admin password for ISS. This should be same as the password specified for the Store Admin during ISS configuration.
      Note
      To enable attachment search, mail.proxyseparator in jiss.conf should be set to ;(semicolon), which is the default setting.
  2. Restart GlassFish Server.

Deploying Convergence and Index and Search Service on the Same Instance of Application Server

If Convergence and ISS are deployed on the same instance of application server, the application server becomes unresponsive when users switch between the Attachments folder and Inbox.

To fix this, perform the following steps:

  1. Set number of request processing threads to double the number of CPUs in the system. This can be done by setting the server.http-service.request-processing.thread-count parameter in application server using the asadmin command.
    Here is an example:
  2. Restart GlassFish Server.

Enabling CalDAV Service

To configure CalDAV Service with Convergence, you must have the CalDAV server installed and configured.

To enable Convergence to work with CalDAV, perform the following steps:

  1. Enable the following CalDAV related parameters in Convergence:
    • caldav.enable - Set this parameter to true to enable the search service.
    • caldav.host - Set this parameter to the hostname on which the CalDAV server installed.
    • caldav.port - Set this parameter to the web component port number on which CalDAV is deployed. This should be same as the port number specified for Server Instance HTTP Port in the Application Server Configuration Details panel during the Calendar Server 7 Initial Configuration.
    • caldav.proxyadminid - Set this parameter to the proxy admin id on which CalDAV is deployed. This should be same as the Administrator User Id specified during Calendar Server 7 Initial Configuration.
    • caldav.proxyadminpwd - Set this parameter to the proxy admin password on which CalDAV is deployed. This should be same as the Administrator password specified during Calendar Server 7 Initial Configuration.
    • caldav.serviceuri - Set this parameter to the serviceuri on which CalDAV is deployed. This should be same as the URI Path where the Calendar Server 7 is deployed and should be suffixed with /wcap. For example,if the URI path where Calendar Server 7 is deployed is /caldav, then this parameter should be set to /caldav/wcap.
      Note
      Convergence can be configured to enable calendar service using both CS 6.x and CalDAV backend servers and it is called co-existence mode. In this mode of configuration some users may be using CS 6.x server and others might have been migrated to CalDAV server.
      You need to set the caldav.davuserattr paramerter to an LDAP attribute used in the user entry to indicate that the user has been migrated to CalDAV. The default value of this attribute is davStore (defined as part of davEntity ObjectClass). If this attribute is not present in user LDAP entry then it indicates that you are a CS 6.x user and not a CalDAV user.
  2. Restart Application Server for Convergence 1.x (or GlassFish Server starting with Convergence 2).

Enabling SMS Calendar Notifications in Convergence

See How Do I Turn on SMS Notifications for Calendar Event Reminders in Convergence?

Miscellaneous

How to enable Communications Express Compatibility for Mail Filters?

If you want your deployment to coexist with Convergence and Communications Express, you must enable the compatibility for sieve. Communications Express sends raw sieve filters to the server. The server then parses the sieve filters and stores them in LDAP. In cases where Convergence and Communications Express coexist, you must enable the mail.uwcsievecompatible configuration parameter so that sieve filters are managed appropriately.

Note
The storage mechanism and data format to store sieve rules for Convergence and Communications Express is the same. The sieve rules are stored in the mailSieveRuleSource LDAP attribute in the user's LDAP. This format is in compliance with RFC 3028 (base Sieve specification) format and not with XML.
Communications Express requires metadata for sieve rules, such as rule name, priority, enable/disable to manage sieve filters. This meta data is not a part of RFC 3028. The data is stored in the form of sieve comments.
The mail.uwcsievecompatible configuration parameter determines whether Convergence should use the metadata to create or manage the sieve rules that are compatible with Communications Express.

The following example shows how the sieve filter appears when stored in the LDAP:

How do I verify passwords in Convergence?

Convergence allows you to verify the administration passwords. Convergence stores all passwords in encrypted format during configuration. You can verify if the password you have set while configuring Convergence is correct by using the EncryptPwd utility. The utility takes the password that you want to verify, as the input, and provides an encrypted string. To verify the password, you must compare this encrypted string with the encrypted password string stored in the Convergence configuration file.

To verify a password:

  1. Type the following command from the command-line prompt.

    You will be prompted to provide the encryption key.

    Note
    In the above command, /var/opt/sun/comms/iwc/WEB-INF refers to the default deploy directory to which Convergence is deployed.
  2. Type the encryption key. By default the encryption key is available in the file: /var/opt/sun/comms/iwc/config/.ngc_enc.

    You will be prompted to enter a string to encrypt.

  3. Type the password that you guess is the right password.
    Here is an example.

    The password you guess is encrypted and displayed at the prompt.

  4. Compare the encrypted password (rE9ZIq6H0r49RgsQrKHXsw==) with the encrypted password available in the configuration file to verify if the password you provided is correct. If the encrypted password strings match, the password you guessed is correct.
  5. If the encrypted password strings do not match you can provide another string, or type quit to exit.

I do not want to manage Convergence using the cn=Directory Manager user. How do I create a Directory Server user in LDAP with the required privileges to manage a Convergence Installation?

A user must have a minimum set of LDAP privileges to manage the LDAP tasks for a Convergence deployment. Instead of using cn=Directory Manager, create an administrator user with a set of privileges that can enable him to manage a Convergence installation. The following privileges must be available for the user:

  • Read
  • Write
  • Search
  • Add
  • Delete
  • Update

The following LDIF file contains the ACIs assignments for Schema 1 for a user named convergenceAdminUser.

The following LDIF file contains the ACIs assignments for Schema 2 for a user named convergenceAdminUser:

Using the LDAP modify command, create the user:

Additionally, you must also set the ugldap.binddn and ugldap.bindpwd parameters in Convergence to reflect the user credentials:

How do I configure VLV (Virtual List View) browsing indexes for Directory Server?

Directory Server provides a mechanism to create indexes. These indexes improve the turnaround time at the time of searching for entries in the directory server instance. You must set the following parameters to enable VLV indexes in Directory Server.

  • search_base
  • vlv_search_filter
  • vlv_sort_attribute
  • vlv_scope
Note
If you have multiple Directory Server backends that store user group information, you must create the indexes on all the instances.

Before setting the VLV Browsing indexes, you must have information about the directory server settings. The directory server settings are available in the dse.ldif file under the <directory_server_root>/config directory. Specifically, you would need the value of the cn attribute. The following is an example of the dse.ldif file:

Applying the VLV Browsing Index Settings

Use the ldapmodify command to specify the Directory Server browsing search indexes. The following is an example:

Generate the Indexes

In the previous section, we provided the information about the search indexes that we want to create for your search base. For the settings to take effect, the indexes must be generated. It is recommended that these steps should be performed during during a scheduled change window. This is because the Directory Server needs to be restarted.

The following commands describes the steps to create the indexes:

  1. Change directory to the directory server installation.
    cd /opt/SUNWdsee/ds6/bin
  2. Stop the directory server instance.
    ./dsadm stop /var/opt/SUNWdsee/dsins1/
  3. Populate the index entries by using the dsadm reindex command. The reindex option requires you to provide the vlv_sort_attribute, the path to the directory server instance, and the value of the user group base.
    ./dsadm reindex -l -t "Sort by cn" /var/opt/SUNWdsee/dsins1/ "o=isp"
  4. Start the directory server instance.
    ./dsadm start /var/opt/SUNWdsee/dsins1/

How Do I Handle Invalid Session Redirects in Convergence?

The Convergence client sends AJAX requests to communicate with the server. If these requests are redirected for any reason, you must take special care with the redirects. With AJAX requests, redirects are automatically handled by the browser. The contents of the redirected page are handed over as the AJAX response. But, when you look at the response headers, you cannot determine if the request was successful or if the request was redirected. If the request is redirected, then the application may not understand the response. As a result, you must configure Convergence to understand the contents of a redirected page.

SSO Agent in Convergence

When there is a security agent in between the Convergence client and server, problems occur when the agent intercepts every request while looking for a valid session. If the session is invalid, the request is redirected to a login page configured in security agent. Because Convergence does not understand the contents of the login page, it displays a response parsing error, such as a syntax error. To get around this problem, the security agent should redirect to a page that Convergence is able to understand, instead of redirecting to a custom login page.

Convergence expects session time out error messages to be in specific format. When the agent encounters session time out, it needs to redirect the request to a page that generates this error message instead of its login page. Sample error messages are provided in Table: Requests that are Redirected, URL Patterns, and Error Responses and can be copied to the policy agents deployment location.

Convergence uses different protocols for each service. For Mail: the wmap protocol, for Calendar: the wcap protocol, for Address book: wabp protocol, and for Options: the iwcp protocol.

The agent should be configured to differentiate between the kinds of requests it receives and correspondingly send the error response specific to that service.

For example, if the agent receives /iwc/svc/wmap/* request, the error response should be as mentioned in $Convergence_Deployment_Directory/jsp/samplefiles/MailServiceErrorJSON.jsp.

The following table lists the requests that are redirected, the URL patterns, and appropriate error responses:

Note
The error responses come from sample files in the $Convergence_Deployment_Directory/jsp/samplefiles directory that, at this time, can only be found in the Convergence 1.x product. If you have access to the Convergence 1.x product, you can use those sample files with Convergence 2 and later. If you don't have access to the Convergence 1.x error response sample files, contact Oracle Support.

Once you have the sample JSP files, move them to your docroot directory. Decode the redirect by determining if it is a mail, calendar, address book, or Convergence server request. Redirect the URL to the corresponding JSP page. Within each JSP page, set the URL location.

Note
In each sample file, replace any occurrence of http://host.domain.com/loginpage with the URL of the application login page to which the user has to be redirected to login to the application.


Table: Requests that are Redirected, URL Patterns, and Error Responses

Service Request URL Pattern Redirect to File
Mail /iwc/svc/wmap/* MailServiceErrorJSON.jsp
Calendar /iwc/svc/wcap/* CalServiceErrorJSON.jsp
Address Book /iwc/svc/wabp/* If the expected response type is JSON: AddressBookErrorJSON.jsp; If the expected response type is XML: AddressBookErrorXML.jsp
Options /iwc/svc/iwcp/ IwcProtocolErrorJSON.jsp
Labels:
convergence convergence Delete
deprecatedam/opensso deprecatedam/opensso Delete
administering administering Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Dec 25, 2009

    Dear colleagues,

    How can I change default admin's name and password ("admin/adminpass") by one operation (through GUI or CLI interface) for each JCS corresponding module?
    Or I have to do it step by step for DA, ApplServer etc separately? If yes then could you tell me order of needed actions for it, please? Or where can I read about it (because I could not find this information in existing admin guides).

    Thank you in advance.

  2. Sep 15, 2012

    Hello,

    I want to disable Corporate Directory just for two domains (including the default one) and leave it on for the thousands of others. I had various attempts but still couldn't manage to do it.

    Does such parameter exists: "ab.{somedomain.com}.corpdir.[default].enable"? What is the recommended method to disable Corporate Directory within a specific domain (in CommSuite 7u2)?

    Greetings,
    Ivan

    1. Sep 17, 2012

      Ivan,

      "ab.{somedomain.com}.corpdir.[default].enable" set to false should disable the corporate directory for the specific domains. Will investigate an answer for you.

      Best,
      Shami

    2. Sep 21, 2012

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.