Sun Convergence Administrative Tasks

{anchor:top}

h1. {anchor:GFPCF} Sun Convergence Administrative Tasks

{toc:minLevel=2|maxLevel=2}

h2. {anchor: authentication}Authentication

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor: ldap_authentication} 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:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o auth.ldap.enable -v true
{code}

h3. {anchor: multiple_ds_auth_ugattr} 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|http://wikis.sun.com/display/CommSuite/Overview+of+the+Convergence+Command-Line+Utility#OverviewoftheConvergenceCommand-LineUtility-iwcadminbatchmode].

The following configuration parameter can be set when the administrator needs to customize default values.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o auth.ldap.ugfilter -v <ugfilter>
{code}
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.

h3. {anchor:ldap_ssl_mode} 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.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o ugldap.enablessl -v true
iwcadmin -u <adminuserid> -w <adminpassword> -o ugldap.port -v <user_group_ldap_port>
{code}
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:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o auth.ldap.enablessl -v true
iwcadmin -u <adminuserid> -w <adminpassword> -o auth.ldap.port -v <ldapport>
{code}

h3. {anchor:custom_auth_module} How do I write a custom authentication module?

See [Writing a Custom Authentication Module for Convergence|http://wikis.sun.com/display/CommSuite/Writing+a+Custom+Authentication+Module+for+Convergence].
{toc-zone}
[Top|#top]

h2. {anchor: accessm_manager_support} Access Manager

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}
{info:title=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|CommSuite6:Communications Suite 6 Installation Scenario - Convergence].
{info}

h3. {anchor:am_setup_legacymode} 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:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o auth.am.enable -v true
{code}
To enable Access Manager in realm mode for authentication, set the {{auth.am.realmode}} and {{auth.am.enable}} parameters to {{true}}. Type the following command:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o auth.am.realmode -v true
{code}

h3. {anchor: am_setup_sso_legacymode} 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.


For example:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o sso.am.enable -v true
iwcadmin -u <adminuserid> -w <adminpassword> -o sso.adminuid -v <adminuserid>
iwcadmin -u <adminuserid> -w <adminpassword> -o sso.adminpwd -v <adminpassword>
iwcadmin -u <adminuserid> -w <adminpassword> -o sso.enablerefreshsso -v true
iwcadmin -u <adminuserid> -w <adminpassword> -o sso.refreshinterval -v 10
iwcadmin -u <adminuserid> -w <adminpassword> -o sso.enablesignoff -v true
{code}
{toc-zone}
[Top|#top]


h2. {anchor: opensso} OpenSSO

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor: am_setup_sso_legacymode} How do I set up OpenSSO SSO and Authentication in Convergence ?
See [Configuring Sun Convergence With Sun OpenSSO Enterprise 8.0 for Authentication and SSO|Configuring Sun Convergence With Sun OpenSSO Enterprise 8.0 for Authentication and SSO].
{toc-zone}
[Top|#top]
{excerpt}

h2. {anchor: basic_monitoring} 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.
{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor: monitor_parameters} 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
** 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

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

h3. {anchor: monitor_jconsole} 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:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o admin.enablemonitoring -v true
{code}
{info:title=Note}You must restart the application server if you make any configuration changes by using the {{iwcadmin}} command.
{info}
To monitor the various parameters in Convergence:
# Start Jconsole.
To start Jconsole, run the following command:
{code}
#\<JAVA_HOME\>/bin/jconsole
{code}
The Jconsole Connection Agent dialog box appears.
!CommSuite:Communications Suite Attachments^jconsole.gif|alt="Jconsole connection window"!
# Click the Advanced tab.
# In the JMX URL field type {{service:jmx:rmi://<hostname>:port/jndi/rmi://<hostname>:port/jmxrmi}}.
{info:title=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:
{code}
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 ]

{code}
{info}

# Enter the administrator userid and password.
# Click Connect.
# Expand the Monitoring node.
!CommSuite:Communications Suite Attachments^jconsole_monitoring_UI.gif|alt="Jconsole User Interface to monitor runtime data"!

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.
{toc-zone}
[Top|#top]

h2. {anchor: Logging} 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:
{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor:how_to_enable_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}}.
{code}
iwcadmin -w <password> -o log.ADDRESS_BOOK.level -v INFO
{code}

h3. {anchor:logging_levels} 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

h3. {anchor: logging_components}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?|#logging_levels]. To see the list of components for which logging can be enabled, use the following command:
{code}
iwcadmin -w <password> -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
{code}

h3. {anchor:log_file_location} 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:
{code}
iwcadmin -W /location/mypasswordfile -o log.location -v /data/logs/
{code}
To set the logging information for the administration logger, use the following command:
{code}
iwcadmin -W /location/mypasswordfile -o log.adminloglocation -v /data/logs/newadminlogfile.log
{code}

h3. {anchor: admin_log_app_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:
{code}
iwcadmin -W /location/mypasswordfile -o log.adminloglocation
{code}

h3. {anchor:enable_log_rotation} 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:
{code}
iwcadmin -W /location/mypasswordfile -o log.sizetriggerval -v 102400
{code}
This example shows how to set time based log rotation policy:
{code}
iwcadmin -W /location/mypasswordfile -o log.timetriggerval -v "'.'yyyy-MM"
{code}
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].

h3. {anchor:logging_ipaddress_session_tracking} 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:
{code}
iwcadmin -W /location/mypasswordfile -o log.pattern -v '%c: %p from %C Thread %t ipaddress=%X{ipaddress} sessionid=%X{sessionid} at %d{HH:mm:ss,SSS}- %m %n'
iwcadmin -W /location/mypasswordfile -o log.enableusertrace -v true
{code}
Modify the log-pattern to include the user IP address ({{%X\{ipaddress\}}}) and session id ({{%X\{sessionid\}}}) in the log messages.
{toc-zone}
[Top|#top]

h2. {anchor: user_features} User Options

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor:user_options_default} 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. 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|http://wikis.sun.com/display/CommSuite/Sun+Convergence+1.0+Reference#SunConvergence1.0Reference-userprefconfigproperties].

h3. {anchor:user_options_service_changes} How do I change the set of services available to users of Convergence?

See [CommSuite:Enabling Services for Convergence].
{toc-zone}
[Top|#top]

h2. {anchor:configure_ssl } SSL

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor:configure_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 and also set the {{base.sslport}} configuration parameters using the {{iwcadmin}} command-line utility.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o base.sslport -v <base_ssl_port>
{code}

h3. {anchor:auth_only_ssl} 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 SSL port value, and the {{base.enableauthonlyssl}} value using the {{iwcadmin}} command-line utility. For example:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o base.sslport -v <base_ssl_port>
iwcadmin -u <adminuserid> -w <adminpassword> -o base.enableauthonlyssl -v true
{code}

h3. {anchor: ssl_backend_servers} 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:

h4. {anchor: ssl_enable_mail_server} Enabling SSL for Mail Server

To enable SSL for mail server, set the {{mail.enable}} and {{mail.port}} configuration parameters.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o mail.enablessl -v true
iwcadmin -u <adminuserid> -w <adminpassword> -o mail.port -v <mail_port>
{code}
{note:title=Note}Mail server must be running in SSL mode on this port.
{note}

h4. {anchor: ssl_backend_calendar_server}Enabling SSL for Calendar Server

To enable SSL for Calendar server, set the {{cal.enablessl}} and {{cal.port}} configuration properties.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o cal.enablessl -v true
iwcadmin -u <adminuserid> -w <adminpassword> -o cal.port -v <calendar_port>
{code}
{note:title=Note}Calendar server must be running in SSL mode on this port.
{note}

h4. {anchor: ssl_enable_address_book_server}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.

h4. {anchor: ssl_instant_messaging}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.
{code}
iim_server.component.requiressl=true
{code}
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.
{code}
iim_server.usessl=true
{code}
Set the {{iim_server.sslkeystore}} parameter to point to the location of the SSL keystore file.
{code}
iim_server.sslkeystore=/opt/SUNWiim/config/<keystore_file_name>.jks
{code}
Set the {{iim_server.keystorepasswordfile}} parameter to the SSL password.
{code}
iim_server.keystorepasswordfile=/opt/SUNWiim/config/sslpassword.conf
{code}
{toc-zone}
[Top|#top]

h2. {anchor:address_book_maintainance} Address Book

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor:ab_ootb_setup} 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.

h3. {anchor:ab_horizontal_scalability} How do I configure horizontal scalability for personal address book?

See [Configuring Horizontal Scalability of Address Book|http://wikis.sun.com/display/CommSuite/Configuring+Horizontal+Scalability+for+Personal+Address+Book].

h3. {anchor:ab_other_ldap_setup} 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:
{code}
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
{code}
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:
{code}
iwcadmin -W /location/mypasswordfile -o ab.pstore.defaultserver -v psidentifier1
{code}

h3. {anchor:ab_corp_dir_setup} How to configure 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:
{code}
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
{code}
Corporate directory can be configured with multiple directory servers. In the above example {{default}} is used to identify corporate directory configuration for {{host.siroe.com}}.
{note:title=Note}For a single corporate directory configuration, you must use {{default}} as the identifier.
{note}

iwcadmin -u <adminuserid> -w <adminpassword> -o client.enablecorpabautocomplete -v true
{code}
{info:title=Note}The search results will appear in the Convergence client, after the first three characters of the name or email address are typed.{info}

h3. {anchor:ab_domain_based_setup} How to set up a domain based configuration for address book?

a) 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:
{code}
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
{code}
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:
{code}
iwcadmin -W /location/mypasswordfile -o ab.{somedomain.com}.pstore.lookthrulimit -v 2000.
{code}
To set up domain-based configuration for Corporate Directory, 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:
{code}
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
{code}
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}}.
{note:title=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.
{note}

h3. {anchor: ab_corpdir_searchfilter}How do I change the default Corporate Directory search filter in Address Book?

{info:title=Note}Convergence patch 137631-01 (Solaris Sparc), 137632-01 (Solaris x86), 137633-01 (Linux) or greater is required for this functionality to work as documented.
{info}
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:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o ab.corpdir.[default].searchattr \
-v entry/displayname,@uid,person/surname
iwcadmin -u <adminuserid> -w <adminpassword> -o ab.corpdir.[default].searchfilter \
-v '(&(&([filter])(|(objectClass=GROUPOFUNIQUENAMES)(objectClass=GROUPOFURLS)(objectClass=ICSCALENDARRESOURCE)(objectClass=INETORGPERSON)))(objectClass=*))'
{code}
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"_:
{noformat}
[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"
{noformat}

h3. {anchor: ab_corpdir_vlv} 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:
# Configure Directory Server with VLV. For more information on creating and managing browsing indexes in Directory Server:

* [How do I configure VLV (Virtual List View) browsing indexes for Directory Server?|#vlv_browsing_directoryserver].
* [Managing Browsing Indexes|http://docs.sun.com/app/docs/doc/819-0995/6n3cq3b03?a=view].

# Set the VLV filter and scope in the corporate directory.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o ab.corpdir.[default].vlvfilter -v "(&(mail=*)(cn=*))"
iwcadmin -u <adminuserid> -w <adminpassword> -o ab.corpdir.[default].vlvscope -v 2
{code}
# Enable the {{ab.corpdir.[default].vlvpaging}} configuration parameter to {{true}}.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o ab.corpdir.[default].vlvpaging -v true
{code}

h3. {anchor: ab_vcard_spport} What vCard standards does supported by Convergence?

Convergence supports the following vCard standards:
* vCard 2.1
* vCard 3.0

h3. {anchor: ab_vcard_character_support}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-KR
* SHIFT_JIS

h3. {anchor: ab_vcard_enable_import_export} 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-cn}} | {{ab.export.vcard.misc.zh-cn}} |
| Simplified Chinese | UTF-8 | {{ab.import.vcard.misc.zh-tw}} | {{ab.export.vcard.misc.zh-tw}} |
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?|#ab_vcard_character_support].

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:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o ab.import.vcard.misc.ja -v Shift_JIS
{code}
To set the character encoding to export vCard entries for the Japanese locale, type the following command:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o ab.export.vcard.misc.ja -v Shift_JIS
{code}
The vCard entries are imported or exported in the Shift_JIS encoding character set.
{note:title=Note}You must set the same character set encoding for both import and export for a locale.
{note}

h3. {anchor:ab_impexp_photo_setup} 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:
{code}
iwcadmin -W /location/mypasswordfile -o ab.exportphoto -v true
{code}
To import contacts with photo in Vcard 3.0 format, type the following command:
{code}
iwcadmin -W /location/mypasswordfile -o ab.importphoto -v true
{code}

h3. {anchor:ab_hide_admin_accounts} How do I hide the admin accounts from the Corporate Directory in the default domain?

{info:title=Note}Convergence patch 137631-01 (Solaris Sparc), 137632-01 (Solaris x86), 137633-01 (Linux) or greater is required for this functionality to work as documented.
{info}
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|http://wikis.sun.com/display/CommSuite/Sun+Convergence+Administrative+Tasks#SunConvergenceAdministrativeTasks-HowdoIchangethedefaultCorporateDirectorysearchfilterinAddressBook%3F] but an example of this can be the following :
{code}
iwcadmin -W /location/mypasswordfile -o ab.corpdir.[default].searchfilter -v \
"(&(&(&([filter])(|(objectClass=GROUPOFUNIQUENAMES)(objectClass=GROUPOFURLS)(objectClass=ICSCALENDARRESOURCE)(objectClass=INETORGPERSON)))(objectClass=*))(!(psIncludeInGAB=false)))"
{code}
{toc-zone}
[Top|#top]

h2. {anchor: single_signon} Single Sign-on

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor: trusted_circle_sso}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.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o sso.ms.enable -v true
{code}

h3. {anchor: single_sign_off} 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:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o sso.enablesignoff -v true
iwcadmin -u <adminuserid> -w <adminpassword> -o sso.notifyserviceimpl -v com.sun.comms.client.security.sso.impl.AMSSOTokenListener
{code}
If you have configured Convergence for Messaging SSO, type the following command to enable Single Sign-Off:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o sso.enablesignoff -v true
{code}

h3. {anchor: custom_sso_module} How do I write custom SSO module for convergence?

See [Writing a Pluggable SSO Module for Convergence |http://wikis.sun.com/display/CommSuite/Writing+a+Pluggable+SSO+Module+for+Convergence].
{toc-zone}
[Top|#top]

h2. {anchor: ldap_service}LDAP Service

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor: ldap_service_failover} How do I configure LDAP failover for Convergence?

To configure Convergence for LDAP failover, type the following command:
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o ugldap.host -v ldap1:port1,ldap2:port2
{code}
{{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.
{toc-zone}
[Top|#top]

h2. {anchor: configuration_management} Configuration Management

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor: enablessl_admin} 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:
# Enable SSL by using the {{iwcadmin}} command.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o admin.enablessl -v true
{code}
# Generate keystore and truststore using [keytool|http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html].
# Set the keystore password.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o admin.keystorepwd -v password
{code}
# Copy keystore to the configuration and data files directory. The default location of this directory is {{/var/opt/sun/comms/iwc/}}
# Restart the application server.

The following log message appears indicates that the SSL configuration is a successful:
{code}
RMI connector server in SSL mode started successfully.
{code}
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}}.
# Set the paramater {{secure}} to {{true}}. Optionally, you can use the \-s option in the {{iwcadmin}} command.
# Set the {{truststorepath}} parameter to the directory where you stored the truststore generated in the Step 2 in the above procedure.
# Set the password to truststorepasswd= \<truststorepassword\>

h3. {anchor: changepasswd_admin} How do I change Convergence administrator user password?

To change the Convergence administrator password, type the following command.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o admin.adminpwd -v <newpassword>
{code}
{toc-zone}
[Top|#top]

h2. Deployment Specific Customizable Client Options for Convergence

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor: dep_specific_customizable_client_options}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.
{code}
# iwcadmin -u <adminuserid> -w <adminpassword> -o client.{siroe.com}.loginpage -v "/iwc_static/layout/loginpage_siroe.html"
{code}
{toc-zone}
[Top|#top]

h2. {anchor: instant_messaging} Instant Messaging

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor: misc_instant_messaging} How to 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 {{hosted.example.com}}.

1. Run the Instant Messaging {{imadmin assign_services}} utility.
{code}
cd /opt/sun/comms/im/sbin/
bash-3.00# ./imadmin assign_services
Please enter base DN: o=Hosted Domain,dc=aus,dc=example,dc=com
{code}
2. Edit the {{httpbind.conf}} file to add the new domain to the {{default.domains}} attribute, for example:
{code}
default.domains=example.com hosted.example.com
{code}
For more information on hosted domain support in Instant Messaging, see [Configuring Hosted Domain Support|http://wikis.sun.com/display/CommSuite/Configuring+Hosted+Domain+Support]

h3. {anchor:instant_messaging_email_presence}How do I Configure Convergence so that Presence Information is Shown in my Email?
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}}

# Add the following lines in the {{iim.conf}} file.
{code}
iim_server.roster.extra = "true"
iim_server.roster.extra.attributes.mail = "mailalternateaddress, mail"
iim_ldap.user.attributes = "mailalternateaddress, mail"
{code}
# Restart the Instant Messaging server.
{code}
# im_svr_base/sbin/imadmin stop
# im_svr_base/sbin/imadmin start
{code}

{toc-zone}
[Top|#top]

h2. {anchor: anti_spam} Enabling Anti-Spam

{panel:|borderColor=#ccc|bgColor=#FFFFCE}If you are using Sun Convergence 1 Update 2, perform the steps documented in the section [I'm using Sun Convergence 1 Update 2. How do I Enable the Anti-Spam feature?|#configure_anti_spam_convergence1_update2]{panel}

h3. {anchor:configure_spam} 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

h4. {anchor: configuring_antispam_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.
{code}
# iwcadmin -u <adminuserid> -w <adminpassword> -o mail.spam.enableaction -v true
{code}
* {{mail.spam.folder}}: Set this parameter to the folder name into which spam messages should be moved.
{code}
# iwcadmin -u <adminuserid> -w <adminpassword> -o mail.spam.folder -v SpamFolder
{code}
{note:title=Note} You must restart the application server after making the configuration changes.{note}

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.

h4. {anchor: configuring_antispam_ms_and_convergence} 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|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.
{code}
configutil -o service.feedback.spam -v <email_address>
{code}
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.
{code}
configutil -o service.feedback.notspam -v <email_address>
{code}
{note:title=Note} You must restart Messaging Server after making these configuration changes.{note}
Set the the anti-spam related parameters in Convergence. See [Configuring Convergence for Anti-Spam Action|#configuring_antispam_convergence].

h3. {anchor:configure_anti_spam_convergence1_update2} I'm using Sun Convergence 1 Update 2. How do I Enable the Anti-Spam feature?
{panel:|borderColor=#ccc|bgColor=#FFFFCE}The feature documented in this section is applicable for Sun Convergence 1 Update 2 release.{panel}

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

{code}
configutil -o service.feedback.spam -v <email_address>
{code}

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.

{code}
configutil -o service.feedback.notspam -v <email_address>
{code}

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:title=Note} You must restart Messaging Server after making these configuration changes.{note}
[Top|#top]

h2. {anchor: iss} Sun Java Indexing and Search Service
{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}
h3. {anchor:indexing_search_service}How do I Configure Convergence with Sun Java Indexing and Search Service?
[Sun Java Indexing and Search Service|CommSuite:Sun Java Indexing and Search Service Documentation] (ISS) is a general-purpose indexing and searching server. Sun Convergence can be configured to use the indexing and search capabilities of ISS. See [Sun Convergence 1 Update 3 What's New Guide| CommSuite7:Communications Suite 7 What's New#CommunicationsSuite7What%27sNew-AttachmentSearch].

To configure Sun Java Indexing and Search Service with Convergence, you must have the ISS server installed and configured. To know more about how to do this, see [Sun Java Indexing and Search Service Documentation|CommSuite:Sun Java Indexing and Search Service Documentation].

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

# Enable the following ISS related parameters in Convergence:
** {{ISS.enable}} - Set this parameter to {{true}} to enable the search service.
{code}
# iwcadmin -u <adminuserid> -w <adminpassword> -o ISS.enable -v true
{code}
** {{ISS.host}} - Set this parameter to the hostname on which the ISS server installed.
{code}
# iwcadmin -u <adminuserid> -w <adminpassword> -o ISS.host -v siroe.com
{code}
** {{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}}.
{code}
# iwcadmin -u <adminuserid> -w <adminpassword> -o ISS.port -v <port_number>
{code}
{note:title=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.
{code}
# iwcadmin -u <adminuserid> -w <adminpassword> -o ISS.enablessl -v true
{code}
{note}
# Restart the application server on which Convergence is deployed.
{toc-zone}


h2. {anchor: miscellaneous_howtos} Miscellaneous

{toc-zone:minLevel=3|maxLevel=3|location=top|type=list}

h3. {anchor:misc_ce_mailfilters } 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.
{code}
iwcadmin -u <adminuserid> -w <adminpassword> -o mail.uwcsievecompatible -v true
{code}
{note:title=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|http://www.faqs.org/rfcs/rfc3028.html] (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.
{note}
The following example shows how the sieve filter appears when stored in the LDAP:
{code}
#RULE: $Name="Modified name" $Order=2 $Type="DEFAULT_TYPE"
require "fileinto";
#BEGINFILTER
if anyof (
header :contains ["From","Sender","Resent-from","Resent-sender","Return-path"] "JohnDoe" ){
fileinto "Inbox";
stop;
}
#ENDFILTER
{code}

h3. {anchor:misc_verify_passwrod} 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:
# Type the following command from the command-line prompt.
{code}
java -cp /var/opt/sun/comms/iwc/WEB-INF/lib/iwc-shared-util.jar com.sun.comms.shared.util.EncryptPwd
{code}
You will be prompted to provide the encryption key.
{note:title=Note} In the above command, {{/var/opt/sun/comms/iwc/WEB-INF}} refers to the default deploy directory to which Convergence is deployed.
{note}
# Type the encryption key. By default the encryption key is available in the file: {{/var/opt/sun/comms/iwc/config/.ngc_enc}}.
{code}
Enter the encryption key ( To generate a new key press Enter ):
{code}
You will be prompted to enter a string to encrypt.
# Type the password that you guess is the right password.
Here is an example.
{code}
Enter string to encrypt: admin123
{code}
The password you guess is encrypted and displayed at the prompt.
{code}
admin123 ---> rE9ZIq6H0r49RgsQrKHXsw==
{code}
# 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.
# If the encrypted password strings do not match you can provide another string, or type {{quit}} to exit.
{code}
Enter string to encrypt: quit
Bye...
{code}
h3. {anchor:convergence_ds_user}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}}.
{code}
# Sample for Schema 1
# Adding ACIs to DC Tree
dn: o=internet
changetype: modify
add: aci
aci: (targetattr="*") (version 3.0; acl "foo"; allow (read,search) userdn="ldap:///uid=convergenceAdminUser, ou=people, o=siroe.sun.com,dc=siroe,dc=sun,dc=com";)

# Adding ACIs to Organization Tree
dn: dc=siroe,dc=sun,dc=com
changetype: modify
add: aci
aci: (targetattr="*") (version 3.0; acl "foo"; allow (all) userdn="ldap:///uid=convergenceAdminUser, ou=people, o=siroe.sun.com,dc=siroe,dc=sun,dc=com";)

# Adding ACIs to Address Book BaseDN
dn: o=PiServerDb
changetype: modify
add: aci
aci: (targetattr="*") (version 3.0; acl "foo"; allow (all) userdn="ldap:///uid=convergenceAdminUser, ou=people, o=siroe.sun.com,dc=siroe,dc=sun,dc=com";)
{code}

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

{code}
# Sample for Schema 2
# Adding ACIs to Organization Tree
dn: dc=siroe,dc=sun,dc=com
changetype: modify
add: aci
aci: (targetattr="*") (version 3.0; acl "foo"; allow (all) userdn="ldap:///uid=convergenceAdminUser, ou=people, o=siroe.sun.com,dc=siroe,dc=sun,dc=com";)

# Adding ACIs to Address Book BaseDN
dn: o=PiServerDb
changetype: modify
add: aci
aci: (targetattr="*") (version 3.0; acl "foo"; allow (all) userdn="ldap:///uid=convergenceAdminUser, ou=people, o=siroe.sun.com,dc=siroe,dc=sun,dc=com";)
{code}


Using the LDAP modify command, create the user:
{code}
# ldapmodify -h <hostname> -p <portname> -D "cn=Directory Manager" -w password -f add_acis.ldif

modifying entry o=internet

modifying entry o=usergroup

modifying entry o=PiServerDb
{code}

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

{code}
# iwcadmin -u <adminuserid> -w <adminpassword> -o ugldap.binddn -v uid=convergenceAdminUser, ou=people, o=siroe.com,o=usergroup

# iwcadmin -u <adminuserid> -w <adminpassword> -o ugldap.bindpw -v <ugldap_bindpassword>
{code}


h3. {anchor:vlv_browsing_directoryserver} 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:title=Note}If you have multiple Directory Server backends that store user group information, you must create the indexes on all the instances.
{note}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:
{code}
dn: cn=isp,cn=ldbm database,cn=plugins,cn=config

objectClass: top
objectClass: extensibleObject
objectClass: nsBackendInstance
cn: isp
creatorsName: cn=directory manager
modifiersName: cn=directory manager
entrydn: cn=isp,cn=ldbm database,cn=plugins,cn=config
numSubordinates: 4
nsslapd-suffix: o=isp
nsslapd-cachesize: -1
nsslapd-cachememsize: 10485760
nsslapd-readonly: off
nsslapd-require-index: off
nsslapd-directory: /var/opt/SUNWdsee/dsins1/db/isp
{code}

h4. Applying the VLV Browsing Index Settings

Use the {{ldapmodify}} command to specify the Directory Server browsing search indexes. The following is an example:
{code}
# ldapmodify -h directory.aus.sun.com -p 389 -D "cn=Directory Manager"
dn: cn=Browsing isp,cn=isp,cn=ldbm database,cn=plugins,cn=config
changetype: add
objectClass: top
objectClass: vlvSearch
cn: Browsing isp
vlvbase: o=aus.sun.com,o=isp
vlvscope: 2
vlvfilter: (&(mail=*)(cn=*))
aci: (targetattr="*")(version 3.0; acl "VLV for Anonymous";
allow (read,search,compare) userdn="ldap:///anyone";)

dn: cn=Sort by cn,cn=Browsing isp,cn=isp,cn=ldbm database,cn=plugins,cn=config
changetype: add
objectClass: top
objectClass: vlvIndex
cn: Sort by cn
vlvSort: cn
{code}

h4. 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:
# Change directory to the directory server installation.
{{cd /opt/SUNWdsee/ds6/bin}}
# Stop the directory server instance.
{{./dsadm stop /var/opt/SUNWdsee/dsins1/}}
# 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"}}
# Start the directory server instance.
{{./dsadm start /var/opt/SUNWdsee/dsins1/}}
{toc-zone}
[Top|#top]