Previous Contents Index Next |
iPlanet Certificate Management System Installation and Setup Guide |
Chapter 8 Starting and Stopping CMS Instances
This chapter describes how to start, stop, and restart iPlanet Certificate Management Server (CMS) and how to check its current status. The chapter also explains the CMS watchdog process, a native bootstrapping program that enables Certificate Management System to start up with a single password instead of multiple ones.
The chapter has the following sections:
Starting Certificate Management System
Stopping Certificate Management System
Restarting Certificate Management System
Attending to an Unresponsive Server
Note You can use the CMS window only when the appropriate Administration Server is running. Be sure to start Administration Server at the port you specified during CMS installation. To minimize security risks, shut down Administration Server when you have finished using iPlanet Console. For instructions on starting and shutting down Administration Server, see iPlanet Administration Server.
Starting Certificate Management System
Once Certificate Management System is installed, it runs constantly, listening for and accepting requests. You can start Certificate Management System in several ways:
Required Start-up Information
When you start Certificate Management System, you are prompted to enter the single sign-on password you specified during installation. This password enables the CMS watchdog (see CMS Watchdog Process) to retrieve all the passwords required by the server to start. These include the following:
Passwords for the internal or external (if any are currently installed) tokens; these tokens contain certificates and corresponding public and private key pairs for the server.
The bind password used by Certificate Management System to access and update the internal database.
The bind password used by Certificate Management System to access and remove PINs from the authentication directory, if you've configured Certificate Management System to remove PINs from the authentication directory. (See the description for the ldap.ldapauthbindDN and ldap.ldapauth.bindPWPrompt parameters of the UidPwdPinDirAuth plug-in module, which explained in the CMS Plug-Ins Guide).
The bind password used by Certificate Management System to access and create/modify user entries in the directory used for portal registration, if you've configured Certificate Management System for portal enrollment. (See the description for the ldap.ldapauthbindDN and ldap.ldapauth.bindPWPrompt parameters of the PortalEnroll plug-in module, which explained in the CMS Plug-Ins Guide).
The bind password used by Certificate Management System to access and update the LDAP directory; this is required only if you have configured Certificate Management System for publishing certificates and CRLs to an LDAP-compliant directory. You first specified these passwords when you installed Certificate Management System. Keep in mind that the passwords you provide for the tokens unlock a combination of the following private keys:
If you have installed a Certificate Manager in the currently selected CMS instance, the token password unlocks the private keys for the Certificate Manager's CA signing and SSL server certificates.
If you have installed a Registration Manager in the currently selected CMS instance, the token password unlocks the private keys for the Registration Manager's signing and SSL server certificates.
If you have installed a Data Recovery Manager in the currently selected CMS instance, the token password unlocks the private keys for the Data Recovery Manager's storage keys and transport and SSL server certificates.
If you have installed a Online Certificate Status Manager in the currently selected CMS instance, the token password unlocks the private keys for the Online Certificate Status Manager's signing and SSL server certificates. For more information about the CMS keys and certificates, see Chapter 14 "Managing CMS Keys and Certificates."
Note that during CMS installation, the watchdog stores all the passwords, required by the server for starting up, in a password cache. The cache is maintained in a file encrypted using the single sign-on password you specify during installation. When you change any of the required passwords or provide new passwords, you must start the server from the command-line (see Starting From the Command Line) so that the watchdog can prompt you for the new passwords in order to update the cache.
The single sign-on password eliminates the need for you to enter the various password when starting up Certificate Management System. As a security measure, you should consider changing the single sign-on password periodically. For instructions, see Password Cache.
Also note that all passwords used in Certificate Management System are checked by a built-in password-quality checker; for details, see Password-Quality Checker.
Configuring the Server to Start Without the Single Sign-On Password
If you prefer to start up Certificate Management System by entering all the required passwords, instead of just the single sign-on password, you can do so by either deleting or renaming the password cache file, pwcache.p12 (notice the .p12 extension).
Go to this directory: <server_root>/cert-<instance_id>/config
Either rename or delete the file.
Start the server from the command line; see Starting From the Command Line.
You are prompted for all the required passwords.
Later, if you want to revert back to starting the server using the single sign-on password:
Create a password cache and then create entries for all the required passwords.
For instructions on creating a new password cache and adding new entries to the password cache, see Chapter 2, "Password Cache Utility" of CMS Command-Line Tools Guide.
Copy the file to the <server_root>/cert-<instance_id>/config directory.
Start the server from the command line; see Starting From the Command Line.
You are prompted for the single sign-on password.
Configuring the Server to Read the Single Sign-on Password From a File
Every time you start Certificate Management System, you are required to enter either the single sign-on password or all the passwords required by the server to startup (see Required Start-up Informationand Configuring the Server to Start Without the Single Sign-On Password). By default, there is no way to start Certificate Management System non-interactively; the startcert script requires you to enter a password.
If it is inconvenient for you to start the server this way, you can store the single sign-on password in a file and edit the startcert script to use this file to start without any prompts. Configuring the server this way eliminates the need for you to enter the single sign-on password every time you start the serverit can be useful on UNIX machines to have the server automatically started if the machine reboots for any reason, and it can be useful on Windows NT to be able to start the server without having to be at the system console. Note that there is no way to make the edited startcert script a service that is automatically started by Windows NT at startup, so if the machine reboots due to a power failure, Certificate Management System will not start automatically.
To configure the server to start by reading the single sign-on password from a file:
Create a file named pwfile.
Put the single sign-on password in the file.
Copy the file to this directory: <server_root>/cert-<instance_id>/config
To edit the start-cert script in Unix, follow these steps:
Open a command-line window.
Go to the CMS-instance directory.
For example, /usr/iplanet/servers/cert-testCA.
Enter the following line at the prompt:
cat start-cert
You should see something similar to this:
Edit the script to include the file path to the pwfile file: to the end of the line that begins $NETSITE_ROOT/bin/cert/admin/bin/cert add
-f $NETSITE_ROOT/cert-<instance_id>/config/pwfile.
Be sure to include the file path as shown (in bold) in the example.
Open a command-line window.
Go to the CMS instance directory.
For example, C:\iPlanet\server4\cert-testCA.
Enter the following line at the prompt:
type start-cert.bat
You should see something similar to this:
iplaneterversEdit the script to include the file path to the pwfile file: to the end of the line that begins net start cert-<instance_id> add
/fC:%NETSITE_ROOT%\cert-<instance_id>\config\pwfile.
Be sure to include the file path as shown in the example (shown in bold).
Save your changes.
Use your operating system's security feature to restrict access to the password file.
Restart the server from the command line; see Starting From the Command Line.
It should start without prompting for the single sign-on password.
Starting From iPlanet Console
You can use iPlanet Console to start an instance of Certificate Management System running on a local or remote host.
To start Certificate Management System from iPlanet Console:
Log in to iPlanet Console (see Logging In to iPlanet Console).
In the Console tab, select the Server Group that contains the CMS instance you want to start.
In the navigation tree, locate the CMS instance you want to start.
Select the instance, right-click, and select the Start Server option from the pop-up menu.
When you start Certificate Management System, you are prompted to supply the single sign-on password for the server.
Type the single sign-on password you specified during installation and click OK.
Certificate Management System won't start until you provide this password. For more information, see Required Start-up Information.
Starting From the Command Line
To start Certificate Management System from the command line:
Open a terminal window to your server.
In a Unix system, log in as root if the server runs on ports less than 1024; otherwise, log in either as root or with the server's user account.
At the command-line prompt, enter the following line:
<server_root>/cert-<instance_id>/start-cert[.bat]
.bat specifies the file extension; this is required only when running the utility on a Windows NT system.
<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.
<instance_id> is the ID for this instance of Certificate Management System. You first specified this when you installed this server.
When prompted, enter the single sign-on password.
Certificate Management System won't start until you provide this password. For more information, see Required Start-up Information.
Note If Certificate Management System is already running, the start-up command fails. Stop the server first using the stop-cert command, then use the start-cert command.
Starting From the Windows NT Services Panel
If you have installed Certificate Management System on a Windows NT system, you can start the server (as a service) from the Windows NT Services panel (see Figure 8-1). The CMS service has the following name:
Figure 8-1    CMS service in the Windows NT Services panel
To start Certificate Management System from the Windows NT Services panel:
Click the Start button on your desktop.
Select Control Panel from Settings.
In the Control Panel window that appears, click Services.
Select the CMS instance and click Start.
Enter the single sign-on password you specified during installation and click OK.
Certificate Management System won't start until you provide this password. For more information, see Required Start-up Information.
Stopping Certificate Management System
You can stop Certificate Management System in several ways:
Stopping Certificate Management System shuts down all the subsystems completely, interrupting service until the server is started again. If your machine crashes or is taken offline, the server stops, and any requests it was servicing are lost. You need to start the server again to restore service.
Stopping From iPlanet Console
You can use iPlanet Console to stop an instance of Certificate Management System running on a local or remote host.
To stop Certificate Management System from iPlanet Console:
Log in to iPlanet Console (see Logging In to iPlanet Console).
In the Console tab, select the Server Group that contains the CMS instance you want to stop.
In the navigation tree, select the CMS instance you want to stop, right-click, and select the Stop Server option from the pop-up menu.
Stopping From the Command Line
You can stop a CMS instance running on a local host by entering the appropriate command at the command prompt.
To stop a Certificate Management System from the command line:
Open a terminal window to your server.
In a Unix system, log in either as root or using the server's user account (if that is how you started the server).
At the command-line prompt, enter the following line:
<server_root>/cert-<instance_id>/stop-cert[.bat]
.bat specifies the file extension; this is required only when running the utility on a Windows NT system.
<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.
<instance_id> is the ID for this instance of Certificate Management System. You first specified this when you installed this server.
Stopping From the Windows NT Services Panel
You can stop a CMS instance running on a local host by stopping the corresponding service; it is identified by the following in the Windows NT Services panel (see Figure 8-1 on page 329):
iPlanet Certificate Management Server (cert-<instance_id>)
To stop Certificate Management System from the Windows NT Services panel:
Click the Start button on your desktop.
Select Control Panel from Settings.
In the Control Panel window that appears, click Services.
Select the CMS instance and click Stop.
Restarting Certificate Management System
Whenever you change the CMS configuration, you must save your changes (by clicking the Save button) for the changes to take effect. Some configuration changes also require that you restart the server after you save the changes. If restarting is required, the server prompts you accordingly.
You can restart the server in two ways:
Restarting From the CMS Window
You can use the CMS window to restart an instance of Certificate Management System on a local or remote host.
To restart Certificate Management System from the CMS window:
Log in to the CMS window (see Logging In to the CMS Window).
In the Tasks tab, click Restart the Server.
When you restart Certificate Management System, you are prompted to supply the single sign-on password for the server.
Type the single sign-on password you specified during installation and click OK.
Certificate Management System won't restart until you provide this password. For more information, see Required Start-up Information.
Restarting From the Command Line
To restart Certificate Management System from the command line:
Open a terminal window to your server.
In a Unix system, log in either as root or using the server's user account (if that is how you started the server).
At the command-line prompt, enter the following line:
<server_root>/cert-<instance_id>/restart-cert[.bat]
.bat specifies the file extension; this is required only when running the utility on a Windows NT system.
<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.
<instance_id> is the ID for this instance of Certificate Management System. You first specified this when you installed this server.
When prompted, enter the single sign-on password.
Certificate Management System won't restart until you provide this password. For more information, see Required Start-up Information.
Checking System Status
You can use iPlanet Console to find out whether a particular instance of Certificate Management System is running.
Log in to iPlanet Console (see Logging In to iPlanet Console).
In the Console tab, select the instance that corresponds to the CMS instance you want to check.
In the right pane, check the Server Status field.
Attending to an Unresponsive Server
If an error causes Certificate Management System to become unresponsive, and all attempts to stop it from iPlanet Console fail, it may be necessary to kill the server processes manually. For this purpose, Certificate Management System provides a command-line tool killproc, which is explained in CMS Command-Line Tools Guide.
CMS Watchdog Process
The CMS watchdog is a native bootstrapping program that provides specific native functions. It works with Certificate Management System to enable it to start up using a single passwordinstead of multiple passwordscalled the single sign-on password. In addition, it manages the start-up, stop, and restart states of Certificate Management System.
The watchdog process (identified as cms_watchdog) implements the following operations:
Starts Certificate Management System and the Virtual Java Machine, or Java VMthe watchdog allows you to start Certificate Management System by using a single password instead of the multiple passwords that would otherwise be required. For details, see Required Start-up Information. (During CMS installation the watchdog stores all the passwords required by the server for starting up in a password cache, which is explained in Password Cache.)
Stops Certificate Management System.
Restarts Certificate Management System (after configuration changes).
Detects Certificate Management System crashes and restarts the serverthe watchdog monitors Certificate Management System and the Java VM, restarting the server in the case of a failure.
In the Unix version of Certificate Management System, the watchdog records the server process ID (pid) and sets the user ID (uid) of the process.
Password Cache
During CMS installation, the installation program creates a password cache which the CMS watchdog uses to store all the passwords required by the server during start up (see Required Start-up Information). For example, when you specify the cryptographic token password and the bind password for the internal directory during installation, the watchdog adds these passwords into the password cache; similarly, when you configure the server for LDAP publishing from iPlanet Console, the watchdog adds the corresponding password to the cache.
The password cache is maintained in a triple-DES encrypted file named pwcache.p12, which is located here:
<server_root>/cert-<instance_id>/config
The file is protected using the single sign-on password you specify during installation. In the cache, passwords are stored along with a name, a string describing the usage of the password, which is used by Certificate Management System to index into the cache. For example, the contents of the password cache could look like this:
Note that in the above example
The string Internal LDAP Database is the default value assigned to the internaldb.ldapauth.bindPWPrompt parameter in the CMS configuration file; it provides a descriptive usage for the password Certificate Management System uses to bind to the internal database.
The string Internal Key Storage Token is hardcoded and it refers to the Netscape Software Cryptographic Service provider; you cannot change it. You can only change the corresponding password. Other entries may appear in the password cache. For example, if you set up PIN-based authentication with the remove PIN option, you will see an entry for the password Certificate Management System uses to bind to the authentication directory to remove a PIN after a user successfully authenticates; for details, see UidPwdPinDirAuth plug-in module in CMS Plug-Ins Guide. Similarly, if you enable LDAP publishing with basic authentication, you will also see an entry for the password Certificate Management System will use to bind to the publishing directory; for details, see Step 5. Identify the Publishing Directory.
Except for the string Internal LDAP Database, you can change any of the above prompts by modifying the corresponding value in the configuration file and then replacing (delete the old item and add the new item) the current entry in the password cache with the new prompt and the password using the PasswordCache utility explained in the CMS Command-Line Tools Guide.
When various modules in the server, such as authentication and LDAP publishing, initialize, they query the password cache for the password. The password cache returns the password if it has it, or else it prompts the user for one. Note that this prompting happens only at server startup time, which means whenever you change any of the required passwords or provide new passwords, you must restart the server from the command-line (see Starting From the Command Line) so that the watchdog can prompt you for the new passwords in order to update the cache.
Password-Quality Checker
Certificate Management System comes with a plugin, called password-quality checker, to monitor the quality of passwords set within the CMS system. All passwords used in Certificate Management System are checked by the password-quality checker, which by default checks that the length of a password is at least 8 characters long; there are no checks regarding which characters are valid or invalid. If you use a password that doesn't meet the quality rules, you will get an error message indicating that the password didn't meet the password-quality rules.
Note that Certificate Management System enforces password quality on only those passwords that it strictly creates and manages. Passwords you enter for LDAP directory access are not subjected to quality checks. The reason for this is, the password quality is handled by the system that creates and manages the password. In an LDAP directory access, the remote directory that you authenticate to enforces the password quality of the password you use because it is created and managed by the directory.
To enable you to customize password quality, the plugin for the password-quality checker is included in the CMS samples package; for example, you can change the default rule to ensure that all CMS passwords are constructed with certain types of characters such as numbers, symbols, capital letters, and so on. The samples package is located here: <server_root>/cms_sdk/cms_jdk/samples
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated October 07, 2002