| Previous Contents Index Next |
| iPlanet Portal Server Administration Guide |
Chapter 11 Maintaining iPlanet Portal Server
This chapter describes:
LDAP Backup and Restore
To save and/or restore the current LDAP database before or after re-installing the iPlanet Portal Server product, perform the following steps for both procedures as specified.
Note Use absolute path names to specify directory and file names.
From the command line, change the directory to the server installation directory:
cd /opt/netscape/directory4/slapd-<host name>
From the command line, change to directory to the server installation directory as shown in step 1 of "LDAP Backup - Procedure 1" on page 193.
Run the following command to restore the backed up LDAP database:
Setting Up Encrypted Communications Between Server and Gateway
SSL service is used for encrypted communication between the end user and the iPlanet Portal Server gateway, providing greater security for the flow of information between them.SSL service requires an SSL certificate, which authenticates the user or server. You can use the self-signed certificate created during installation, or you can request and obtain a signed certificate from a Certificate Authority. You then add this certificate to the rp.keystore file (the certificate database) on the iPlanet Portal Server gateway.
When you installed the iPlanet Portal Server software, the system created and installed a self-signed SSL server certificate with a default validity of 365 days. At some point after installation, you might want to generate a new self-signed certificate; for example, you might want to change the information for the certificate you entered during the original installation.
To Generate a Self-Signed SSL Certificate on the Gateway
Log in to the iPlanet Portal Server gateway as root.
Run the certadmin script on the iPlanet Portal Server gateway:
Type 1 to generate a self-signed certificate.
- The Certificate Administration menu appears.
:
Type the information for your organization and a pass phrase for the self-signed certificate.
- The Certificate Administration script prompts for specific information about your organization and a pass phrase for the self-signed certificate:
Stop and restart the reverse proxy server on the iPlanet Portal Server gateway for the certificate to take effect.
- The script generates a self-signed certificate with a validity of 365 days and adds it to the file /etc/opt/SUNWwt/rp.keystore on the iPS gateway.
Make a backup copy of the rp.keystore file.
- See the procedure To Restart a Gateway or Server.
Obtaining SSL Certificates From Vendors
After installation, you have the option to install SSL server certificates signed by vendors who provide official certificate authority (CA) services. iPlanet Portal Server software contains root certificates that can be used with SSL certificates from Verisign, Inc. If you decide to install an SSL certificate from a vendor other than Verisign, you must install a root certificate from that vendor first, and then install the web server certificate.If you want to use an SSL certificate from a certificate vendor after you have installed the iPlanet Portal Server software, you must run the certadmin script to generate an SSL certificate signing request (CSR). The CSR is used to get an SSL certificate from a vendor.
Certificates are stored in the rp.keystore file. Once you generate a CSR, make sure you keep a backup copy of the rp.keystore file. This file contains your private key, which is associated with the certificate that you purchase. If you lose the file, you cannot use the certificate that you bought.
To Install SSL Certificates From Verisign
Log in to the iPlanet Portal Server gateway as root.
Run the certadmin script on the iPlanet Portal Server gateway:
Type 2 on the Certificate Administration menu to generate a certificate signing request (CSR). Either of the following happens:
- The Certificate Administration menu appears:
:
If no self-signed certificate exists on this machine, the Certificate Administration script notifies you that you must create one.
If a self-signed certificate exists on this machine, the information from the certificate appears. The Certificate Administration script asks if the information is correct.
:
Is this information correct (y/n)? [n] Do the either of the following:
Type n if the information is not correct.
Type y if the information is correct.
- If you type n, the script prompts for information for a new self-signed certificate. Fill in the information as requested.
Type the name, the email address, and the telephone number of the administrator or web master for this server.
- The script prompts for the name, email address, and phone number of the Web master of the machine for which the certificate is being generated:
What is the name of the admin/webmaster for this server? []
What is the email address of the admin/webmaster for this server? []
What is the phone number of the admin/webmaster for this server? []
Type y if the information is correct, or n if it is not correct.
- The certadmin script displays the values you typed and asks if the values are correct:
Are these values correct (y/n)? [n]
If you type y, the program generates the CSR and stores it in the file /tmp/csr.hostname.
If you type n, the certadmin script asks you to type the values again.
Go to the certificate authority's web site and order your web server certificate.
Provide information from your CSR, as requested by the CA.
After you receive your certificate from the CA, save it in a file.Provide any other information as requested by the CA, such as a pass phrase.
Specify your web server type as: NES Webserver.
Run the certadmin script on the iPlanet Portal Server gateway:
- The certificate starts with the line:
- continues with the certificate itself, and concludes with the line:
- Make sure you include both lines with the certificate in the file.
Type 4 to install your certificate from the CA.
- The Certificate Administration menu appears:
Type the full path to the file containing the certificate from the CA.
- The Certificate Administration script asks for the path name of the file containing the certificate.
:
What is the name (including path) of the file that contains the certificate? []
Stop and restart the reverse proxy server on the iPlanet Portal Server gateway for the certificate to take effect.
- The program stores your certificate in the file /etc/opt/SUNWwt/rp.keystore.
Make a backup copy of the rp.keystore file for the iPlanet Portal Server gateway.
- See the procedure To Restart a Gateway or Server.
To Install SSL Root Certificates
- You must have already generated a self-signed certificate to install a root certificate.
Go to the Certificate Authority's web site and download its root certificate.
Become root on the gateway and run the certadmin script:
- The web site should contain instructions for downloading the certificate, usually as a file.
Type 3 to add a root certificate from the CA.
- The Certificate Administration menu appears:
Type the full path to the file containing the root certificate.
- The script asks for the path name of the file containing the root certificate you want to add to the database.
:
What is the name (including path) of the file that contains the root certificate that you would like to add to your database? []
Type y if the file is correct, or n if it is not.
- The file appears and the certadmin script asks if the information is correct.
:
Is this information correct (y/n)? [n]
If you type y, certadmin stores the root certificate in the /etc/opt/SUNWwt/rp.CAstore file.
To Install SSL Certificates From a Certificate Authority
Log in to the iPlanet Portal Server gateway as root.
Run the certadmin script on the iPlanet Portal Server gateway:
Type 4 on the Certificate Administration menu to install the certificate from the CA.
- The Certificate Administration menu appears:
Type the full path to the file containing the certificate.
- The Certificate Administration script asks for the path name of the file containing the certificate:
What is the name (including path) of the file that contains the certificate? []
Stop and restart the iPlanet Portal Server gateway for the certificate to take effect.
- The program adds your certificate to the /etc/opt/SUNWwt/rp.keystore file.
Make a backup copy of the .rppass, rp.CAstore, and rp.keystore files for the iPlanet Portal Server gateway. If you ever need to restore a certificate, you can copy these three files back to /etc/opt/SUNWwt.
Run the certadmin script on the iPlanet Portal Server gateway:
Type 5 on the Certificate Administration menu to display all CA certificates installed.
Configuring Encrypted Communications on the Server
Go to the NES administration console by typing the following URL:
Remember to configure the gateway as directed in the iPlanet Portal Server Installation Guide.
http://iPlanet Portal Server_server:8888 Type the appropriate administrative ID and password you used during installation in the popup window.
Click the Manage button in the frame on the right of the next window that appears.
- At this point, the system may warn you that the configuration has been manually edited and the resulting changes have not been loaded. If so:
Dismiss the warning window.
Select the Security tab.Click the Apply button in the upper right corner of the screen.
Choose Load configuration files.
- If you are asked to undo the changes, choose to undo them and click Apply again.
Click OK to dismiss this window.
- A popup window appears indicating that operation was successful.
Type a database password (twice), and click OK to create the database.
- The "Create a Trust Database" screen appears.
Select "Request a certificate" on the navigation bar on the left side of the screen
- A popup window appears indicating that operation was successful. Click OK to dismiss this window.
Type your email address in the "CA email address" field.
Type the same password In the Key Pair File Password field that you typed in step 5.
Type your name and telephone number and other data requested.
Type the fully qualified name of the iPlanet Portal Server server (such as ipsserver.eng.sun.com) in the Common Name field.
Click the OK button to generate a certificate signing request (CSR).
After you receive your certificate, click the Install Certificate button in the navigation frame
- At this point, the right frame contains your CSR. The CSR will also be mailed to the address you typed. You will need this CSR to request a certificate from the Certificate Authority (CA) you choose.
- NES has server CAs for most of the major vendors. You can view the installed server CAs, as well as any server certificates you have installed, by clicking on the Manage Certificates option in the navigation frame.
Type your SSL pass phrase in the Key Pair File Password field,
- The certificate begins with the following line:
- -----BEGIN CERTIFICATE----
- continues with the certificate itself, and ends as follows:
- -----END CERTIFICATE-----
- Make sure you include both of these lines with the certificate in the file.
Type the file name in the Message in This File: field.
- (Optional) If you have saved your certificate in a file, do either of the following:
Select the Message Text button and type the text in the text area.
Click the OK button to install the certificate.
Click the Add Server Certificate option when asked to confirm the addition of this certificate,
(Optional) Click Manage Certificates and verify that your certificate has been installed.
Dismiss the resulting popup window indicating the success of this operation.
Click the OK button to dismiss the warning window.
Click the Preferences tab.
- For now, ignore the warning about stopping and starting the server.
Click the Encryption On/Off option in the navigation frame on the left.
Type a port number in the Port Number field.
Note This will be 443 if you requested SSL, or 8080 otherwise, unless you have specifically picked another port number during the installation of the server.
Click the On button if you requested SSL to be used, during the install process.
Click the OK button to enable encryption on the web server.
- If a popup window asking for the server password appears, type anything for the password.
Choose the Save and Apply option when you see an error message confirming the changes to the configuration files
- Ignore the warning about stopping and restarting the server. The changes to the configuration are saved, but the server will not be restarted. The server need not be restarted here.
Go to a terminal window and type:
- At this point you see a message asking you to restart the web server. Do NOT restart from the administration console.
/etc/init.d/wtserver start [debug]
Verify that the port is correct and that it is running on a URL that starts https://.... You will see an error message if the port number or URL is incorrect.
- Include the optional debug argument to confirm that the platform server is not running. This allows you to see two messages from NES, one confirming the startup of the administration console and the other confirming startup of the web server.
Fixing Known Problems
Questions that arise during the installation, configuration, or operation of iPlanet Portal Server can include:
Browser issues involving the Netlet application
This section provides general guidelines and suggestions for these questions.
Browser Issues Involving the Netlet
After authenticating themselves, users occasionally receive the following message from the Netlet:
Netlet was unable to determine your browser proxy settings.
.
. See your network administrator for the correct setting.This message appears if the user's browser has a proxy.pac file specified as the Proxy setting in the Preferences window. The Netlet cannot run with this setting.
To correct the problem, have the users set the proxies manually. They cannot use the automatic setup for proxies along with the Netlet.
Setting Platform Debugging
As Super Administrator, you can turn on platform-wide debugging by using the command line interface to modify value wtdebug in the file /etc/opt/SUNWips/platform.conf. By default, this value is set to off.In order to see debugging on stdout, you must start the server with the command:
To see debugging on the gateway, you must start the gateway with the command:
Possible values for debug are:
- error=error debugging (bugs)
- warning=warning debugging (also error)
- message=message debugging (also error, warning for all applications)
on = all (error, warning, message) debugging to stdout (system.out)
off= debugging disabled
You can use wildcards for individual components only when output is to stdout. Debug levels are cumulative, warning displays error and warning, message displays error and warning message.
- iwtAuth* turns on auth debugging only
iwtNetlet* turns on Netlet config debugging
Troubleshooting Authentication Problems
If you do not see the module that you have added as a choice on the login page, return to the Administration Console and confirm your Authentication Module settings at the platform and domain level.
Modules with Helpers
The RADIUS, SafeWord, SecurID, S/Key, and UNIX authentication methods use both an iPlanet Portal Server Server authentication module and a separate helper process. These helpers communicate with their respective authentication modules over TCP ports. They accept connections originating only from the localhost, or the same system on which they are running. Once the helper successfully receives all its configuration information, it enters its normal authentication mode.To manually test these authentication helpers, first be sure that the helper is not already running. These helpers reside in /opt/SUNWips/bin. For full debug logging, make sure the helper's debug log file exists, then start the helper with the -v (verbose) flag. Use the -c (port number) flag if the helper's default configuration port conflicts with some other process running on the iPlanet Portal Server Server system.
The helper's debug files are located in /var/opt/SUNWips/debug/auth, and are named radius_client.debug, safeword_client.debug, securid_client.debug, skey_client.debug, and unix_client.debug. For example, an easy way to create the RADIUS debug file is as follows:
# touch /var/opt/SUNWips/debug/auth/radius_client.debug The SafeWord, RADIUS, UNIX, S/Key, and SecurID authentication modules also include a separate helper component with which the modules communicate over specified ports. At iPlanet Portal Server Server initialization, the helper components are brought up in listening mode on a configuration port. The respective authentication modules send configuration information retrieved from the Profile Server. After successfully receiving its configuration information, each helper component opens the port specified for its authentication requests.
Each of these authentication modules needs the following configuration attributes set before it can work properly:
Configuration port: where the helper receives configuration information (including the remaining attributes) from its respective authentication module
Other configuration information specific to each authentication method is passed during the configuration process.Authentication port: where the helper receives authentication requests
Session timeout: the maximum time in minutes that an authentication request may use for completion, from submission of the authentication parameters to resolution of the request (successful or unsuccessful)
Maximum number of concurrent authentication requests permitted for that authentication method
Except for the Windows NT Authentication module, which uses ASCII input, all authentication modules in iPlanet Portal Server are internationalized.
After completing debug sessions and returning to production mode, remove the "-v" flag from any script used to start the helpers.
Starting Debugging Using the SafeWord Helper
To start the SafeWord helper, follow these steps:
As root, enter the following:
The following messages are sent by the doSafeWord helper when authenticating to the SafeWord server:# touch /var/opt/SUNWips/debug/auth/safeword_client.debug
# /opt/SUNWips/bin/doSafeWord -v
In another terminal window, type
The doSafeWord helper then requests the following configuration information:
Enter SafeWord Helper Listen Port [7945]:
Enter SafeWord Helper Session Timeout [5]:
Enter SafeWord Helper Max Sessions [5]:
This domain has SafeWord enabled: [y]/n:
Enter SafeWord Helper Logging Level [0]:
Enter SafeWord Helper SafeWord Servername: <safeword_server_hostname>
Enter SafeWord Helper SafeWord Server Port [7482]:
Enter SafeWord Helper SafeWord System [STANDARD]:
Enter SafeWord Helper Log Path [/var/opt/SUNWips/logs/safehelper/log]:
More SafeWord Servers (y/[n]):
------end if no more servers------
get_config_info: doSafeWord configured successfully
The helper is now in normal authentication mode. It has opened port 7945 (the default) or whatever port you have specified, and is waiting for authentication requests. To test SafeWord authentication, type:
- Press the Enter key to accept the default value, shown in brackets, or enter the value you want to use. Default values are usually sufficient for debugging purposes. However, you must supply the Domain Name and the SafeWord Servername, which is the hostname of the system where the SafeWord server resides.
Enter iPlanet Portal Server Domain Name:
InputPrompt = Enter Gold/Platinum Password:
Authentication complete, user passed -- No problems
Authentication complete, user failed -- Failed authentication
The iPlanet Portal Server Domain Name is the name entered during configuration. If multiple SafeWord servers are configured to the helper, enter the correct corresponding domain name.
The prompt for m_UserID is the same as an iPlanet Portal Server prompt for your SafeWord userid.
Gold and Platinum Passwords refer to various levels of SafeWord tokens.
Starting Debugging Using the SecurID Helper
To start the SecurID helper, follow these steps:
As root, enter the following:
The following messages are sent by the doSecurID helper when authenticating to the SafeWord server:# touch /var/opt/SUNWips/debug/auth/securid_client.debug
# /opt/SUNWips/bin/doSecurid -v
In another terminal window, type:
The doSecurID helper then requests the following configuration information:
Enter SecurID Helper Listen Port [7943]:
Enter SecurID Helper Session Timeout [5]:
Enter SecurID Helper Max Sessions [5]:
This domain has SecurID enabled? [y]/n:
Enter Config Path for Server #0 [/opt/ace/data]:
Enter User Config Path for Server #0 [/opt/ace/prog]:
get_config_info: doSecurID configured successfully
The helper is now in normal authentication mode. It has opened port 7943 (the default) or whatever port you have specified, and is waiting for authentication requests. Return to local control by typing:
- Press the Enter key to accept the default value, shown in brackets, or enter the value you want to use. Default values are usually sufficient for debugging purposes.
- Since the doSecurID helper supports multiple ACE/Servers, you supply the directories where the corresponding sdconf.rec files are located. Although the User Config Path may not be used, it should be both specified and exist.
Enter iPlanet Portal Server domain name:
The "iPlanet Portal Server domain name to use" is the same as enforced for this domain combination during configuration.
Starting Debugging Using the RADIUS Helper
To start the RADIUS helper, follow these steps:
As root, enter the following:
or# touch /var/opt/SUNWips/debug/auth/radius_client.debug
# /opt/SUNWips/bin/doRadius -v
In another terminal window, type
The doRadius helper then requests the following configuration information (default values are shown in brackets):
Enter Radius Helper Listen Port [7944]:
Enter Radius Helper Session Timeout [5]:
Enter Radius Helper Max Sessions [5]:
get_config_info: doRadius configured successfully
The helper is now in normal authentication mode. It has opened port 7944 (the default) or whatever port you have specified, and is waiting for authentication requests. To test RADIUS authentication, type:
- You can press the Enter key at each prompt to use the default value, or you can supply your own values. The default values are usually sufficient for debugging purposes.
The doRadius helper sends the following messages when authenticating to a RADIUS server:
- You must supply the appropriate login, password, name for server 1, and shared secret. Supplying a name for server 2 is optional; press Enter to skip server 2. Note that if two RADIUS servers are specified, the shared secret is still the same. Press Return to use the default RADIUS server port (1645).
The doRadius helper sends the following messages when authenticating to a SafeWord RADIUS server:
orAccess challenge failed for userid ...
The doRadius helper sends the following messages when authenticating to an ACE/Server RADIUS server:
orThe doRadius helper sends the following messages when authenticating to an ACE/Server RADIUS server in an authentication session that includes "next token mode":
orCHALLENGE_MSG: (Wait for the tokencode to change, then enter the new tokencode)
Access challenge failed for userid ...
The doRadius helper sends the following messages when authenticating to an ACE/Server RADIUS server in an authentication session that includes "new PIN mode":
orCHALLENGE_MSG: A new PIN is required. Do you want the system to generate your new PIN? (y/n):
Enter Challenge Response: (enter N)
CHALLENGE_MSG: Enter a new PIN between 4 to 8 digits:
CHALLENGE_MSG: PIN accepted. Wait for the tokencode to change, then enter the new tokencode:
Access challenge failed for userid ...
The challenge messages for new PIN generation may vary, depending upon how the user is configured in the ACE/server.
Debugging Windows NT Primary Domain Controller
Configuring Windows NT Aliases
The iwtAuthNT-authAliases attribute is set on a per user basis through the Administration Console.
Manually Testing Windows NT Authentication
You can manually check if NT authentication is working from your iPlanet Portal Server by typing:#/opt/SUNWips/bin/smbclient -w <workgroup> -l <host> -u <username>
where you substitute the appropriate values for workgroup, host, username, and password. Make sure you have installed third party packages.
Starting Debugging Using the UNIX Helper
To start the UNIX helper, follow these steps:
As root, enter the following:
or# touch /var/opt/SUNWips/debug/auth/unix_client.debug
In another terminal window, type:
The doUNIX helper then requests the following configuration information (default values are shown in brackets):
Enter UNIX Helper Listen Port [7946]:
Enter UNIX Helper Session Timeout [5]:
Enter UNIX Helper Max Sessions [5]:
get_config_info: doUNIX configured successfully
The helper is now in normal authentication mode. It has opened port 7946 (the default) or whatever port you have specified, and is waiting for authentication requests. To test UNIX authentication, type:
- Press the Enter key at each prompt to use the default value, or supply your own values. The default values are usually sufficient for debugging purposes.
The following messages are sent by the doUNIX helper when authenticating to a UNIX server:
Access denied for userid xxx, return = dd
Starting Debugging Using the S/Key Helper
To start the S/Key helper, follow these steps:
As root, enter the following:
or# touch /var/opt/SUNWips/debug/auth/skey_client.debug
In another terminal window, type
The doS/Key helper then requests the following configuration information (default values are shown in brackets):
Enter S/Key Helper Listen Port [7947]:
Enter S/Key Helper Session Timeout [5]:
Enter S/Key Helper Max Sessions [5]:
get_config_info: doSKey configured successfully
The helper is now in normal authentication mode. It has opened port 7947 (the default) or whatever port you have specified, and is waiting for authentication requests. To test S/Key authentication, type:
- Press the Enter key at each prompt to use the default value, or supply your own values. The default values are usually sufficient for debugging purposes.
The following messages are sent by the doSKey helper when authenticating to a S/Key server:
Authentication unsuccessful for UUID xxxxx
Authentication failed (UUID or PIN does not match)
Remember that the passphrases are case-sensitive and always all uppercase.
Previous Contents Index Next
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated May 04, 2000