Chapter 2
Administering iPlanet Instant Messaging Server and Multiplexor
This chapter describes how to administer the iPlanet Instant Messaging server and multiplexor, and perform other administrative tasks, such as changing configuration parameters and managing user privileges. This chapter also describes administration tasks for iPlanet Portal Server deployments.
This chapter contains these sections:
Administration Overview
Administering iPlanet Instant Messaging Server consists of:
Starting, stopping, and refreshing the server and/or multiplexor with the iimadmin command
Changing configuration parameters, such as host names, LDAP search filters, and so on, by manually editing the iim.conf file
Managing server and multiplexor log files
Managing user privileges (Access Control files)
Configuring communications between multiple iPlanet Instant Messaging servers
Setting up and using Secure Sockets Layer (SSL)
Backing up and restoring iIM Server files
User Administration
iPlanet Instant Messaging Server does not provide user administration tools. If you choose, you can install iPlanet Delegated Administrator to perform that role, or use the site provisioning tools for your directory server.
There are no iPlanet Instant Messaging Server specific commands to add, modify, or delete an iPlanet Instant Messenger user. Because users exist in the directory, use your site provisioning tools to perform these operations.
Likewise, you cannot disable an iPlanet Instant Messenger user. The only way to prevent users from using iPlanet Instant Messaging Server is to delete them from the directory.
|
Note
|
If you deny users the privilege to set up watches on other users—by editing the sysWatch.acl file—they will not be able to display iPlanet Instant Messenger's Main window, effectively denying them the ability to send instant messages. However, users would still be able to see alerts and news channels.
|
Stopping and Starting the Server and Multiplexor
The iimadmin command enables you to:
Start and stop the iPlanet Instant Messaging server and multiplexor
Start and stop just the multiplexor
Refresh the iPlanet Instant Messaging server and multiplexor
Refresh just the multiplexor
The iimadmin command-line utility should be executed only by the user who has administration rights to the system(s) on which the iPlanet Instant Messaging server and multiplexor are running. This user is typically the identity that the server runs as, which was designated during installation, such as iimuser on Solaris, or the user with full administration privileges on Windows NT, such as administrator.
The iimadmin command-line utility is located in the following directories:
Starting the iPlanet Instant Messaging server enables iPlanet Instant Messenger clients to connect. After the server starts, iPlanet Instant Messaging server enables any waiting coservers to connect and attempts to connect to any coservers set in the configuration. Stopping the iPlanet Instant Messaging server closes all connections and disconnects all iIM clients.
If needed, you can start and stop the multiplexor separately, for example, if you have changed a configuration parameter which only affects the multiplexor, or if you have a multiplexor only installation.
|
Note
|
When starting and stopping (or refreshing) the server, you must also stop and start each multiplexor instance. If the multiplexors reside on the same host as the iPlanet Instant Messaging server, running the iimadmin stop, iimadmin start, and iimadmin refresh commands acts on both the server and multiplexors. In configurations consisting of multiplexor instances on different (remote) hosts, you must log into each of those hosts to stop and start the multiplexors separately.
|
To Start the Instant Messaging Server and Multiplexor
|
Note
|
if necessary, you can start the multiplexor separately. Be sure to do this on multiplexor only installations. See "To Start the Multiplexor" below.
|
Use the iimadmin command to start the iPlanet Instant Messaging server and multiplexor, as shown in the following example:
iimadmin start iim
This command first starts the iPlanet Instant Messaging server then starts the multiplexor.
To Stop the Instant Messaging Server and Multiplexor
|
Note
|
if necessary, you can stop the multiplexor separately. Be sure to do this on multiplexor only installations. See "To Stop the Multiplexor".
|
Use the iimadmin command to stop the iPlanet Instant Messaging server and multiplexor, as shown in the following example:
iimadmin stop iim
This command stops the server and multiplexor, terminates all user connections, and disconnects any configured inbound and outbound servers.
To Start the Multiplexor
Use the iimadmin command with the iim_mux parameter to start just the multiplexor, as shown in the following example:
iimadmin start iim_mux
To Stop the Multiplexor
Use the iimadmin command with the iim_mux parameter to stop just the multiplexor, as shown in the following example:
iimadmin stop iim_mux
To Start and Stop the Instant Messaging Server and Multiplexor (Windows NT Only)
On Windows NT, open the Services dialog box from the Control Panel to start and stop the iPlanet Instant Messaging server and multiplexor. Refer to the documentation provided with the operating system for instructions.
To Refresh the Configuration (Instant Messaging Server and Multiplexor)
Use the iimadmin command with the refresh parameter to cause the server configuration to be reread, as shown in the following example:
iimadmin refresh iim
This command stops both the multiplexor and server then restarts them.
You need to refresh the configuration whenever you change a configuration parameter in the iim.conf file.
To Refresh the Configuration (Multiplexor Only)
Use the iimadmin command with the refresh iim_mux parameter to cause the multiplexor configuration to be reread, as shown in the following example:
iimadmin refresh iim_mux
This command stops then restarts the multiplexor.
Changing iPlanet Instant Messaging Server and Multiplexor Configuration Parameters
iPlanet Instant Messaging Server stores configuration parameters in the iim.conf file. For a list of all configuration parameters, see Appendix A "iPlanet Instant Messaging Server Configuration Parameters."
To change configuration parameters, manually edit the configuration parameters and values, then refresh the iIM server configuration. If you change a multiplexor parameter, you only need to refresh the multiplexor.
To Change Configuration Parameters
See Appendix A "iPlanet Instant Messaging Server Configuration Parameters" for a complete list of parameters and values.
Change to the config directory. For example, on Solaris:
-
cd /etc/opt/SUNWiim/default/config
Edit the iim.conf file, for example:
-
vi iim.conf
|
Note
|
The iim.conf file should be owned by the iIM Server account you created during installation. If the iim.conf file becomes unreadable by the iIM Server account, the iPlanet Instant Messaging server and multiplexor would be unable to read the configuration. Additionally, you might lose the ability to edit the iim.conf file to make configuration changes.
|
Save your changes.
Refresh the configuration.
-
See "To Refresh the Configuration (Instant Messaging Server and Multiplexor)".
|
Caution
|
If you change the multiplexor listen port (iim_mux.listenport) or the multiplexor host itself, update the iim.html and iim.jnlp files accordingly. Failure to do so results in iPlanet Instant Messenger clients being unable to connect. See Chapter 3 "Managing iPlanet Instant Messenger" for more information.
|
Managing Logging
iPlanet Instant Messaging Server creates log files that record events, related status of various software components, system errors, and other aspects of the server and multiplexor. By examining the log files, you can monitor many aspects of the server's operation.
You configure the level of logging for both the iPlanet Instant Messaging server and multiplexor by specifying parameters in the iim.conf file. See "To Change Configuration Parameters" for information on updating the iim.conf file.
During the iPlanet Instant Messaging Server installation, you specified where the log files are maintained:
On Solaris, the default is:
-
/var/opt/SUNWiim/default/log
On Windows NT, the default is:
-
c:\Program Files\iplanet\InstantMessaging\log
As part of regular iIM Server system maintenance, periodically review and trim log files to prevent running out of disk space. iIM Server itself does not perform this action.
Logging Levels
The level, or priority, of logging defines how detailed, or verbose, the logging activity is to be. A higher priority level means less detail; it means that only events of high priority (high severity) are logged. A lower level means greater detail; it means that more events are recorded in the log file.
You can set the logging level separately for the iPlanet Instant Messaging server and multiplexor. Table 2-1 describes the available levels. These logging levels are a subset of those defined by the UNIX syslog facility.
Table 2-1 Logging Levels for iPlanet Instant Messaging Server and Multiplexor
|
Level
|
Description
|
|
FATAL
|
The minimum logging detail. An event is written to the log whenever a severe problem or critical condition occurs. If a FATAL problem occurs, the software might stop functioning soon, if it hasn't done so already.
|
|
ERROR
|
An event is written to the log whenever an error condition occurs, such as a connection attempt to a client or another server failing.
|
|
WARNING
|
An event is written to the log whenever a warning condition occurs, such as when the server cannot understand a communication sent to it by a client.
|
|
NOTICE
|
A periodic event is written to the logs to report the status of the server, including state (running), number of clients connected, number of inbound and outbound servers connected, and so on.
|
|
INFO
|
An event is written to the log with every significant action that takes place, such as when a user successfully logs on or off.
|
|
DEBUG
|
The most verbose logging. Useful only for debugging purposes. Events are written to the log at individual steps within each process or task, to pinpoint problems.
|
When you select a particular logging level, events corresponding to that level and to all higher (less verbose) levels are logged. The default level for both server and multiplexor logs is NOTICE.
|
Note
|
The more verbose the logging you specify, the more disk space your log files will occupy. Be sure to monitor and trim your log files to prevent running out of disk space.
|
To Set Log File Levels
Managing User Privileges
You determine the availability of the client communication modes by assigning privileges to users. In some cases, a minimal number of privileges can be assigned. For example, a user can be configured to initiate alerts to others but not to add conference rooms. Privileges give users access to needed utilities and views. Almost all features of iIM Server are controlled by a privilege system that limits what a user can see or do.
You set user privileges by editing the following access control (ACL) files, located in the config/acls directory:
Administrator privileges - sysAdmin.acl
Privilege to change client user settings - sysSaveUserSettings.acl
Privilege to add and delete news channels - sysTopicsAdd.acl
Privilege to add and delete conference rooms - sysRoomsAdd.acl
Privilege to send and forward alerts - sysSendAlerts.acl
Privilege to set up watches on other users - sysWatch.acl
By default, the absence of a file indicates that particular privilege is denied to everybody.
|
Note
|
Anybody who has administrator privilege has all other privileges even without being explicitly set in the other ACL files.
|
The roomname.acl and news channelname.acl files, located in the db/acls directory, set privileges on each conference room and news channel created through iPlanet Instant Messenger. You should not edit these files manually; updates occur to them as you use iPlanet Instant Messenger to manage conference rooms and news channels.
Access Control File Format
Access control files can have a series of entries that define privileges. Each entry starts with a tag as follows:
d: - default
u: - user
g: - group
|
Note
|
The d: tag must be the last entry in an access control file. iIM Server ignores all entries after a d: tag. If the d: tag is True, then all other lines are also ignored. You cannot set the d:tag to True and selectively disallow users that privilege.
|
The tag is followed by a colon (:) then in case of the default tag by True or False. The user and group tags are followed by the user or group name. Multiple users and groups are specified by having multiple u and g lines. If default is set to True, all other entries are redundant. If default is set to False, only the users and groups specified in the file will have that particular privilege.
The defaults for a fresh installation are:
sysAdmin.acl - Contains d:false
sysTopicsAdd.acl - Contains d:false
sysRoomsAdd.acl - Contains d:false
sysSaveUserSettings.acl - Contains d:True
sysSendAlerts.acl - Contains d:True
sysWatch.acl - Contains d:True
Access Control File Examples
This section contains example ACL files that show privileges set at the system level (sysTopicsAdd.acl) and at the conference room/news channel level (newschannel.acl).
sysTopicsAdd.acl File
In the following example sysTopicsAdd.acl file, the default is False, so Add and Delete news channels privileges are then accorded to the users and groups that appear before the default, namely user1, user2, and the sales group.
|
# Example sysTopicsAdd.acl file
u:user1
u:user2
g:sales
d:False
|
|
Room and News Channels ACL Files
The format of the roomname.acl and news channelname.acl files is slightly different than the system level ACL files. The roomname.acl and news channelname.acl files contain an additional number entry after the user or group entry that defines the access level. The levels are:
1 - None
2- Read
6 - Write
14 - Manage
In the following news channel ACL example, the default access is Read, with Manage access given to user1, Write access given to user2, and an access of None for user3. Note that the first line, v:3.0.1, which is new for 3.0.1, tells the server how to interpret the values. If this line is not included, the server will interpret a value of 2 to be the old version-3.0 Join, rather than Read, and it will not understand the value 6.
|
# Example newschannel.acl file
v:3.0.1
u:user1:14
u:user2:6
u:user3:1
d:2
|
|
|
Note
|
Do not edit the roomname.acl and news channelname.acl files manually; updates occur to them as you use iPlanet Instant Messenger to manage conference rooms and news channels. Because the iPlanet Instant Messaging server reads and writes these files when users change access using iPlanet Instant Messenger, you might lose your change, or users would lose their changes if the files are edited by hand while the server is running.
|
To Change User Privileges
Change to the config/acls directory. For example, on Solaris:
-
cd /etc/opt/SUNWiim/default/config/acls
Edit the appropriate ACL file, for example:
-
vi sysTopicsAdd.acl
-
The ACL files are:
sysAdmin.acl - Administrator privileges
sysSaveUserSettings.acl - Privilege to change client user settings
sysTopicsAdd.acl - Privilege to add news channels
sysRoomsAdd.acl - Privilege to add conference rooms
sysSendAlerts.acl - Privilege to send and forward alerts
sysWatch.acl - Privilege to set up watches on other users
Save your changes.
Users need to retry the iPlanet Instant Messenger window or function to see changes that affect them.
Configuring Communication Between iPlanet Instant Messaging Servers
For communication between multiple iPlanet Instant Messaging servers in your network, you need to configure your server to identify itself to the other servers, and to identify each coserver, or cooperating server, which will have a connection to your server. The coserver identifies itself with its iIM domain name, host and port number, serverID, and password.
You assign each cooperating server a symbolic name, which is a string consisting of letters and digits, for example, coserver1. In this way you can specify multiple servers.
When iPlanet Instant Messaging servers are configured in this manner, you form a larger instant messaging community. Users on each server can communicate with users on every other server, use conferences rooms on other servers, and subscribe to news channels on other servers (subject to access privileges).
See "iPlanet Instant Messaging Server Configurations" for more information on supported configurations.
To Configure Communication Between iPlanet Instant Messaging Servers
This procedure describes how to enable communication between two iPlanet Instant Messaging servers, iim.company22.com and iim.i-zed.com.
Prerequisite: Determine the following information.
Table 2-2 Configuration Information for Server-to-Server Communication
|
Parameter in iim.conf File
|
Value for Server iim.company22.com
|
Value for Server iim.i-zed.com
|
|
iim_server.serverid
|
Iamcompany22
|
Iami-zed
|
|
iim_server.password
|
secretforcompany22
|
secret4i-zed
|
|
iim_server.coservers
|
coserver1
|
coserver1
|
|
iim_server.coserver1.host
|
iim-ized.com:9919
|
iim-company22.com:9919
|
|
iim_server.coserver1.serverid
|
Iami-zed
|
Iamcompany22
|
|
iim_server.coserver1.password
|
secret4i-zed
|
secretforcompany22
|
-
See Appendix A "iPlanet Instant Messaging Server Configuration Parameters" for more information.
|
Note
|
You can configure your server to communicate with multiple other servers. For each server to communicate with, add a symbolic name for that server to the iim_server.coservers parameter, which is a comma separated list of server names.
|
Change to the config directory on server iim.company22.com. For example, on Solaris:
-
cd /etc/opt/SUNWiim/default/config
Edit the iim.conf file, for example:
-
vi iim.conf
|
Note
|
The iim.conf file should be owned by the iIM Server account you created during installation. If the iim.conf file becomes unreadable by the iIM Server account, the iPlanet Instant Messaging server and multiplexor would be unable to read the configuration. Additionally, you might lose the ability to edit the iim.conf file to make configuration changes.
|
-
The following example shows that portion of the iim.conf file on iim.company22.com pertaining to server-to-server communications that you change:
|
iim_server.serverid=Iamcompany22
iim_server.password=secretforcompany22
iim_server.coservers=coserver1
iim_server.coserver1.host=iim.i-zed.com:9919
iim_server.coserver1.serverid=Iami-zed
iim_server.coserver1.password=secret4-ized
|
|
Follow Step 2 through Step 3 for the iim.conf file on server iim.i-zed.com.
-
The following example shows that portion of the iim.conf file on iim.i-zed.com pertaining to server-to-server communications that you change:
|
iim_server.serverid=Iami-zed
iim_server.password=secret4i-zed
iim_server.coservers=coserver1
iim_server.coserver1.host=iim.company22.com:9919
iim_server.coserver1.serverid=Iamcompany22
iim_server.coserver1.password=secretforcompany22
|
|
Save the changes and refresh the configurations on both servers.
-
See "To Refresh the Configuration (Instant Messaging Server and Multiplexor)" for more information.
Configuring SSL
This section describes how to set up the Secure Sockets Layer (SSL) security protocol for use between iPlanet Instant Messaging servers. Before following the procedures in this section, become familiar with public-key cryptography concepts. For example, see the iPlanet Console and Administration Server 5.0 Server Management Guide:
http://docs.iplanet.com/docs/manuals/console/50/10_ssl.htm
The high-level steps to configure SSL for iPlanet Instant Messaging Server are:
Generating a self-signed certificate.
Generating a Certificate Signing Request.
Sending a Certificate Signing Request to a Certificate Authority (CA) and getting back a signed certificate.
Installing the Certificate on the iIM server, and the CA's certificate on other servers; which means you also have to install the other server's CA certificate on your system. (This is much easier when you have the same CA.)
Activating SSL
To configure SSL, iPlanet Instant Messaging Server requires a key file that contains the public and private key installed in a directory that you specify by using the iim.conf parameter, iim_server.sslkeystore. Most installations should use the config directory.
An iPlanet Instant Messenger server uses keys stored in the nlcacerts file in its Java install directory (on Solaris, Javahome/lib/security/; on Windows NT, Javahome\lib\security\) to verify certificates.
You need to create this file by putting the CA's certificate in it if your CA is not in the cacerts file already (on Solaris, Javahome/lib/security/cacerts; on Windows NT, Javahome\lib\security\cacerts). If this file does not exist then cacerts is used, which is created by the Java install.
When enabling SSL for use with iPlanet Instant Messaging Server, choose one of the following methods:
Using a self-signed certificate - Put your self-signed certificate in the iimkeys file (on Solaris, im30_install_dir/config/iimkeys; on Windows NT, im30_install_dir\config\iimkeys)and also export it to other iPlanet Instant Messaging servers so they can put it in their nlcacerts file.
Using a certificate signed by a CA that is not already in cacerts - Put your certificate and your signing CA's certificate in the iimkeys file (on Solaris, im30_install_dir/config/iimkeys; on Windows NT, im30_install_dir\config\iimkeys). Also, export your signing CA's certificate to the other servers so they can put it in their nlcacerts file.
Using a certificate signed by a CA already in cacerts - Put your certificate in the iimkeys file only (on Solaris, im30_install_dir/config/iimkeys; on Windows NT, im30_install_dir\config\iimkeys), and the other servers already have your signing CA in their cacerts file.
|
Note
|
You can run the following command to show all the CAs in your cacerts file:
Javahome/keytool -list -keystore cacerts
Run this command from the directory that contains the cacerts file. Press Return when prompted for password.
|
In all cases, remember that your iPlanet Instant Messaging server is the "client" of the other server, so you might have to import the CA's certificate for that server.
To Generate a Self-Signed Certificate
Run the following command on the iIM server from its config directory. For example, on Solaris:
-
Javahome/bin/keytool -genkey -alias iim -keypass value -keystore iimkeys -storepass value -validity 365
-
Substitute your own values for value.
When prompted, enter the information to create a distinguished name.
-
This creates a keystore entry containing a private key and a self-signed certificate for the public key. (That is, the certificate is signed using the corresponding private key.)
|
Note
|
If you will be using the self-signed certificate for your iPlanet Instant Messaging server, then this is also the certificate you will put in the nlcacerts file (on Solaris, Javahome/lib/security/nlcacerts; on Windows NT, Javahome\lib\security\nlcacerts). Skip the next section on getting your self-signed certificate signed by a certificate authority.
|
To Get Your Self-Signed Certificate Signed by a Certificate Authority and Install It
Getting the iPlanet Instant Messaging Server certificate signed by a Certificate Authority enables other iIM servers to verify the iPlanet Instant Messaging Server certificate. This occurs because the servers' trusted CA keystore (on Solaris, Javahome/lib/security/cacerts; on Windows NT, Javahome\lib\security\cacerts) already has the certificates from the major Verisign and Thawte Certificate Authorities.
Follow these steps to send the certificate information to the CA and install it:
Generate a Certificate Signing Request (CSR) to send to a Certificate Authority (CA). For example, on Solaris:
-
Javahome/bin/keytool -certreq -keystore iimkeys -alias iim -file iim.csr
Submit the iim.csr file to your chosen CA.
-
You can email your iim.csr file, or cut and paste it in a browser window, if the CA, such as Thawte, allows it.
|
Note
|
Once you have emailed your request, you must wait for the CA to respond with your certificate. Response time for your request varies. For example, if your CA is internal to your company, it might only take a day or two to respond to your request. If your selected CA is external to your company, it could take several weeks to respond to your request.
|
When the CA sends a response, be sure to save the information in a text file (for example, a file named careplyfile). You will need the data when you install the certificate.
-
You should also back up the certificate data in a safe location. If your system ever loses the certificate data, you can reinstall the certificate using your backup file.
-
Once you receive your certificate, you are ready to install it in your iIM server's certificate database.
Import the Certificate Reply from the CA.
-
This might require that you import the certificate of the CA that signed your certificate first as a "trusted certificate."
|
Caution
|
Ensure that the CA's certificate is valid prior to importing it as a "trusted" certificate. View it first (by using the keytool -printcert command or the keytool -import command without the -noprompt option), and make sure that the displayed certificate fingerprint(s) match the expected ones. You can contact the person who sent the certificate and compare the fingerprint(s) that you see with the ones that they show or that a secure public key repository shows. Only if the fingerprints are equal is it guaranteed that the certificate has not been replaced in transit with someone else's (for example, an attacker's) certificate. If such an attack took place and you did not check the certificate before you imported it, you would end up trusting anything the attacker has signed.
|
-
If you trust that the certificate is valid, you can add it to your keystore.
-
This can be done with the following command, assuming the CA's certificate is in a file called myfavca.cert. Run this command on the iIM server in the config directory.
-
keytool -import -alias myfavca -file myfavca.cert -keystore iimkeys
-
Then import your new certificate on the iIM server to replace your self-signed certificate. Run this command on the iIM server in the config directory:
-
keytool -import -trustcacerts -keystore iimkeys -alias iim -file careplyfile
Your server is now ready for SSL activation. See"To Activate SSL."
To Export a Public Key Certificate and Import on Other iPlanet Instant Messaging Servers
Use this procedure if you are using a self-signed certificate or a certificate that is signed by a CA that is not in the default trusted CA keystore (on Solaris, Javahome/lib/security/cacerts; on Windows NT, Javahome\lib\security\cacerts). This file is used by Java to verify code signing but can also be used for SSL. If the nlcacerts file (on Solaris, Javahome/lib/security/nlcacerts; on Windows NT, Javahome\lib\security\nlcacerts) exists then that will be used by the iPlanet Instant Messaging server.
Export the Public Key Certificate.
-
If you are self-signed, export your self-signed certificate. For example, run the following command on the iIM server, in the config directory:
-
keytool -export -keystore iimkeys -alias iim -file export.cert
-
If your certificate is signed by a CA not in the existing cacerts file on the other server, then export your signing CA's certificate to the other server. For example, run the following command on the iIM server, in the config directory:
-
keytool -export -keystore iimkeys -alias myfavca -file export.cert
-
Then copy over the export.cert file to the other server, in the Javahome/lib/security directory.
Import the Public Key Certificate as trusted on every other iIM server that will talk SSL to this server by creating the Javahome/lib/security/nlcacerts file with the command:
-
keytool -import -keystore nlcacerts -alias iimca -file export.cert
-
Enter a password when prompted.
-
For more information see the complete documentation for keytool at:
-
http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/keytool.html
-
http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html
Your server is now ready for SSL activation. See "To Activate SSL."
To Activate SSL
Before you can activate SSL, you must create a certificate database, obtain and install a server certificate, and trust the CA's certificate as described earlier.
Set these iim.conf parameters:
iim_server.usesslport=true
iim_server.sslport=9910
-
This parameter should already be in the iim.conf file.
Set the server-to-server configurations as described in "Configuring Communication Between iPlanet Instant Messaging Servers", adding the following:
iim_server.coserver1.usessl=true
-
and change the port number of the following:
iim_server.coserver1.host=hostname:9910
-
The port number should be the SSL port of the other server.
-
Following is a portion of an example iim.conf file with the pertinent SSL configuration:
|
! Server to server communication port.
iim_server.port = "9919"
! Should the server listen on the server to server communication port
iim_server.useport = "True"
! Should this server listen for server-to-server communication using ssl port
iim_server.usesslport = "True"
iim_server.sslport=9910
iim_server.sslkeystore=/opt/SUNWiim/config/iimkeys
iim_server.sslkeystorepassphrase=somepassword
iim_server.coservers=coserver1
iim_server.coserver1.serverid=Iamcompany22
iim_server.coserver1.password=secretforcompany22
iim_server.coserver1.usessl=true
iim_server.coserver1.host=iim.i-zed.com:9910
iim_server.serverid=Iami-zed
iim_server.password=secret4i-zed
|
|
Managing LDAP with iPlanet Instant Messaging Server
iPlanet Instant Messaging Server requires a directory server. A standalone deployment must use an external LDAP directory, whereas in a portal deployment, you can choose between external LDAP or iPlanet Portal Server's internal directory.
When installed in a standalone or portal deployment and using an external LDAP directory, iIM Server uses the directory to perform user authentication and to search for users. When installed in a portal deployment and using iPlanet Portal Server's internal directory, iIM Server uses that internal directory for user search only, not user authentication. In this case, the iPlanet Portal Server itself performs the authentication.
|
Note
|
iPlanet Portal Server supports many authentication mechanisms, such as Radius, Unix, Membership, and LDAP. When you are using an external LDAP directory in your iIM Server deployment, the uids of your users must reside in the external LDAP directory, regardless of the authentication mechanism used. Otherwise, users will not be able to log on to iIM Server.
|
If you use an external LDAP directory to maintain your user namespace, the default configuration makes the following assumptions regarding the schema used by this directory:
User entries are identified by the inetOrgPerson object class.
Group entries are identified by the groupOfUniqueNames object class.
The iPlanet Instant Messenger user ID attribute of a user is provided by the uid attribute (from inetOrgPerson objectclass).
The email address of a user is provided by the mail attribute.
The display name of a user or group is provided by the cn attribute.
The list of members of a group is provided by the uniqueMember attribute (groupOfUniqueNames object class).
You can change these default settings by editing the iim.conf file.
Searching the Directory and Anonymous Users
iPlanet Instant Messaging Server needs to be able to search the directory to function correctly. If your directory is configured to be searchable by anonymous users, iIM Server has the capability it needs. If the directory is not readable by anonymous users, you must take additional steps to configure the iim.conf file with the credentials of a user ID that has at least read access to the directory.
These credentials consist of:
You need to modify the iim.conf file, if:
The external LDAP directory server does not allow anonymous bind, or
You are using iPlanet Portal Server's internal directory, because the internal directory server in general does not allow anonymous bind.
To Enable iIM Server to Conduct Directory Searches as a Specific User (Not Anonymous)
Identify values for the following parameters in the iim.conf file:
iim_ldap.usergroupbinddn - Specifies the distinguished name (dn) to use to bind to the directory for searches.
iim_ldap.usergroupbindcred - Specifies the password to use with the iim_ldap.usergroupbinddn distinguished name for directory searches.
-
For example:
-
iim_ldap.usergroupbinddn="cn=iim server,o=i-zed.com"
-
iim_ldap.usergroupbindcred=secret
In a portal deployment, the iPlanet Portal Server Profile service's directory is in general not accessible by anonymous users. When configured to use the Profile service's internal directory, (as opposed to an external LDAP directory), use the following values:
-
where
|
bind dn
|
Specifies the value of java.naming.security.principal from /etc/opt/SUNWips/properties.file.
|
|
ldap credentials/password
|
Specifies the value of java.naming.security.credentials from /etc/opt/SUNWips/properties.file.
|
-
For example, if the pertinent information from the properties.file file is:
-
java.naming.security.principal=uid=ipsadmin,ou=Directory Administrators,o=i-zed.com
java.naming.security.credentials=password
-
the entries in the iim.conf file would be:
-
iim_ldap.usergroupbinddn="uid=ipsadmin,ou=Directory Administrators,o=i-zed.com"
iim_ldap.usergroupbindcred=password
|
Note
|
You do not necessarily need to use administrator-level credentials with write level access, as all that is necessary is read access to the domain tree. Thus, if there is an LDAP user with read level access, use its credentials instead. This is a safer alternative in the sense that it does not force you to disseminate the all powerful administrator-level credentials.
|
Edit the iim.conf file.
-
See "To Change Configuration Parameters" for instructions on editing the iim.conf file.
-
If the iim_ldap.usergroupbinddn and iim_ldap.usergroupbindcred parameters do not appear in the iim.conf file, you can add them anywhere in the file.
Backing Up iPlanet Instant Messaging Server
iPlanet Instant Messaging Server does not come with any disaster recovery tools. Use your site's backup system to back up the configuration and database directories periodically, to use in case of disasters. These directories are:
Solaris: /etc/opt/SUNWiim/default/config and /var/opt/SUNWiim/default/db
Windows NT: im30_install_dir\config and im30_install_dir\var\db
(Optional) If you customized any of the files mentioned in "Customizing iPlanet Instant Messenger", back them up.
Administering iPlanet Instant Messaging Server in the iPlanet Portal Server Environment
This section describes what you need to know about administering iIM Server when it is installed as an application channel in iPlanet Portal Server, including:
Installing iIM Server in iPlanet Portal Server
Uninstalling iIM Server from iPlanet Portal Server
Enabling and disabling secure mode for iPlanet Instant Messenger
Adding the iIM Server Netlet rule to iPlanet Portal Server
For overview information on how iIM Server functions in the iPlanet Portal Server environment, see "Portal Deployment Overview".
|
Note
|
Currently, a portal deployment of iPlanet Instant Messaging Server runs only on the Solaris platform. Thus, the procedures in this section are Solaris-specific.
|
To Install iPlanet Instant Messaging Server in iPlanet Portal Server
If, during the iPlanet Instant Messaging Server installation, you chose not to run iPlanet Instant Messenger within the iPlanet Portal Server environment as an application channel, you can do so later by running the im30_install_dir/SUNWiim/sbin/iimipsadmin script.
Follow these steps to run the iimipsadmin script:
Make sure you are root or the user specified during the iPlanet Portal Server installation.
Change to the sbin directory. For example:
-
cd /opt/SUNWiim/sbin
Run the iimipsadmin script:
-
iimipsadmin install [ -p clientport ] [ -s ]
-
Use the -p clientport option if you want to specify the client port to use for defining Netlet rules. If you do not specify a client port, iimipsadmin uses the default value of 9917. Use the -s option to install the iIM Server links in iPlanet Portal Server that enable iPlanet Instant Messenger to communicate in secure mode through Netlet.
|
Note
|
You can install iIM Server in secure mode only if the iPlanet Portal Server gateway is configured. If the gateway is not configured, then you cannot run in secure mode.
|
-
See Appendix B "iPlanet Instant Messaging Server Reference," for more information on the iimipsadmin script.
To Uninstall iPlanet Instant Messaging Server from iPlanet Portal Server
Make sure you are root or the user specified during the iPlanet Portal Server installation.
Change to the sbin directory. For example:
-
cd /opt/SUNWiim/sbin
Run the iimipsadmin script:
-
iimipsadmin uninstall [ -p clientport ]
-
Use the -p clientport option if you specified a client port to use for defining Netlet rules. If you did not specify a client port at the time of installation, or when running the iimipsadmin script later, you do not need to use the -p clientport option.
-
See Appendix B "iPlanet Instant Messaging Server Reference," for more information on the iimipsadmin script.
To Enable Secure Mode for iPlanet Instant Messenger in iPlanet Portal Server
If you are running iPlanet Instant Messaging Server in the iPlanet Portal Server environment in non-secure mode—that is, without using Netlet for encryption—you can switch to secure mode as follows.
|
Note
|
You can install iIM Server in secure mode only if the iPlanet Portal Server gateway is configured. If the gateway is not configured, then you cannot run in secure mode.
|
Make sure you are root or the user specified during the installation iPlanet Portal Server.
Change to the sbin directory. For example:
-
cd /opt/SUNWiim/sbin
Run the iimipsadmin script:
-
iimipsadmin securemode
-
See Appendix B "iPlanet Instant Messaging Server Reference," for more information on the iimipsadmin script.
When users run iPlanet Instant Messenger, a lock icon appears in the status area, indicating they are now running in secure mode. Currently logged-in users need to log out then log on to receive this change.
To Disable Secure Mode for iPlanet Instant Messenger in iPlanet Portal Server
If you are running iPlanet Instant Messaging Server in the iPlanet Portal Server environment in secure mode—that is, using Netlet for encryption—you can switch to non-secure mode as follows.
Make sure you are root or the user specified during the iPlanet Portal Server installation.
Change to the sbin directory. For example:
-
cd /opt/SUNWiim/sbin
Run the iimipsadmin script:
-
iimipsadmin unsecuremode
-
See Appendix B "iPlanet Instant Messaging Server Reference," for more information on the iimipsadmin script.
Currently logged-in users need to log out then log on to receive this change.
To Add Netlet Rules to iPlanet Portal Server for iPlanet Instant Messenger
The iPlanet Portal Server Netlet is a Java applet that enables applications, such as iPlanet Instant Messenger, to set up an encrypted connection with the iPlanet Instant Messaging server. You use Netlet to enable iPlanet Instant Messenger to run in secure mode.
The Netlet rules that are configured on the profile pages of the iPlanet Portal Server Administration Console define Netlet behavior. Netlet rules can be configured for domains, roles, or users.
The iPlanet Instant Messaging Server iimipsadmin script adds the Netlet rules at the component level in iwtNetletComponent that enable you to run iPlanet Instant Messenger in secure (encrypted) mode. However, iimipsadmin cannot add the necessary Netlet rules to any domain which has customized Netlet rules.
Follow these steps to add the iPlanet Instant Messenger Netlet rule to an iPlanet Portal Server domain:
In iPlanet Portal Server, access the Administration Console.
Click Manage Domains under "Roles and Users."
-
The Portal Server Domains page is displayed.
Click the link for the domain for which you want to configure the Netlet.
-
The Domain, Role, and User Profiles page is displayed.
Click the icon to the left of Applications to expand the list of Applications profiles.
Click the Netlet link to display the Netlet profile for the domain.
-
All default Netlet rules already active for the domain are shown in the Netlet Rules attribute box.
Scroll down to the field below the listed Netlet rules.
Add the iPlanet Instant Messenger Netlet rule by typing the following in this field and pressing Add.
-
iIM|null|false|CLIENT_PORT|MUX_HOST|MUX_PORT
-
In this rule:
|
CLIENT_PORT
|
Specifies the port on the localhost on which Netlet will run. The default is 9917.
|
|
MUX_HOST
|
Specifies the name of the host running the iPlanet Instant Messaging server.
|
|
MUX_PORT
|
Specifies the multiplexor port on the iPlanet Instant Messaging server. The default is 9909.
|
-
For example, the following Netlet rule specifies a localhost port of 9917 for iPlanet Instant Messaging server i-zed.com and a multiplexor port of 9909.
-
iIM|null|false|9917|i-zed.com|9909
(Optional) You can also change the defaults for other attributes in the Domain Netlet profile, depending on your site's needs. These attributes are:
Warning Popup for Connections: This attribute pops up a message on the user's desktop warning that someone is trying to connect to the desktop through the listen port. The message comes up when the user runs the application over the Netlet, but also when an intruder tries to gain access to the desktop through the listen port.
Default Loopback Port: This attribute specifies the port on the client to be used when applets are downloaded through the Netlet. The default value of 8000 is used unless it is overridden in the Netlet rules.
Apply changes to subroles: The default is to not apply changes to subroles. To propagate all changes to the Netlet profile down the role tree, select this attribute. If any child of the current entity has customized a field which is currently changed in the HTML form, then those customized fields will be removed from the children.
Click Submit to register these changes.
Go to "To Set Permissions for the Netlet".
To Set Permissions for the Netlet
In iPlanet Portal Server, you assign permissions for the Netlet rules to each level of the role tree. Permissions are inherited relative to the level of the profile being set: Domain, Role, or User.
|
Note
|
The iPlanet Instant Messenger rule needs a minimum of Read permission by the user.
|
Scroll to the top of the Netlet profile page.
Click the Show Read/Write Permissions button to enable viewing of the default permissions.
Scroll down to the Netlet Rules attribute to view the permissions set for each relevant attribute in the profile.
-
Change the following default permissions to suit your site's needs.
Admin indicates the permissions granted to the Domain Administrator for access to the attributes in this profile. The default permissions allow the Domain Administrator to both view and change the attributes. If only Read were selected, the Domain Administrator could view the attribute but not change it.
|
Note
|
The Super Administrator always has read and write permissions for all attributes in the role tree.
|
User indicates the permissions granted to the application run by the client. By default, the application can read the attribute, for example, the Netlet rule, but cannot change it. If both Read and Write were selected, the application could both read and change the Netlet Rule attribute, for example.
Press Submit to activate your changes.
-
A confirmation message appears.
Press Continue to return to the Netlet profile.
To Add iPlanet Instant Messenger as an iPlanet Portal Server Application Channel
When installing iPlanet Instant Messaging Server in the iPlanet Portal Server environment, the installer inserts the following three links in the Applications channel of the iPlanet Portal Server desktop:
iPlanetTM Portal Server: Instant Messenger Quick Reference (Launches the iPlanet Instant Messaging Server Quick Reference)
Launch iPlanetTM Instant Messenger using the Java plug-in (Launches iPlanet Instant Messenger using the Java Plug-in)
Launch iPlanetTM Instant Messenger using Java Web Start (Launches iPlanet Instant Messenger using Java Web Start)
These links are displayed to users in their iPlanet Portal Server Desktop Applications channel only if they have not customized the iwtAppProvider component. If users do not automatically receive the iPlanet Instant Messenger links, then they must add them manually from the available Applications channel.
To manually add applications to the Applications channel:
In the iPlanet Portal Server Desktop, click Edit on the Applications toolbar.
Select the iPlanet Instant Messenger applications you want displayed in the Applications channel.
Click Finished to return to the iPlanet Portal Server Desktop.