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

Once Certificate Management System is installed, it runs constantly, listening for and accepting requests. You can start Certificate Management System in several ways:

  • From iPlanet Console (locally and remotely)

  • From the command line (locally only)

  • On a Windows NT system, from the Windows NT Services panel


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

Here's how you can do it:

  1. Go to this directory: <server_root>/cert-<instance_id>/config

  2. Locate the pwcache.p12 file.

  3. Either rename or delete the file.

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

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

  2. Copy the file to the <server_root>/cert-<instance_id>/config directory.

  3. 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 server—it 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.


Caution

The instructions that follow explain how to configure Certificate Management System to start by reading the single sign-on password from a file. Note that the password is stored in a plain text file and you must use your operating system's security feature to secure this file. Failing to do so poses a security risk, as anyone who has access to the host system will be able to get hold of the single sign-on password.


To configure the server to start by reading the single sign-on password from a file:

  1. Create a file named pwfile.

  2. Put the single sign-on password in the file.

  3. Copy the file to this directory: <server_root>/cert-<instance_id>/config

  4. Edit the start-cert script.

    To edit the start-cert script in Unix, follow these steps:

    1. Open a command-line window.

    2. Go to the CMS-instance directory.

      For example, /usr/iplanet/servers/cert-testCA.

    3. Enter the following line at the prompt:

      cat start-cert

      You should see something similar to this:

      #!/bin/sh

      /usr/iplanet/servers/bin/cert/admin/bin/start -i testCA
      -r /usr/iplanet/servers -e -classpath

      /usr/iplanet/servers/bin/cert/classes:/usr/iplanet/
      servers/bin/cert/jars/jss.jar:/usr/iplanet/servers/bin/
      cert/jars/certsrv.jar:usr/iplanet/servers/java/
      ldapjdk.jar:/usr/iplanet/servers/bin/cert/jre/lib/
      rt.jar:/usr/iplanet/servers/bin/cert/jre/lib/i18n.jar:/
      usr/iplanet/servers/bin/cert/jars/jssjdk12.jar

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

    #!/bin/sh

    /usr/iplanet/servers/bin/cert/admin/bin/start -i testCA
    -f /usr/iplanet/servers/cert-testCA/config/pwfile -r
    /usr/iplanet/servers -e -classpath

    /usr/iplanet/servers/cert-testCA/classes/:/usr/iplanet/server
    s/bin/cert/classes/:/usr/iplanet/servers/bin/cert/jars/jss.ja
    r:/usr/iplanet/servers/bin/cert/jars/certsrv.jar:/usr/iplanet
    /servers/java/ldapjdk.jar:/usr/iplanet/servers/bin/cert/jre/l
    ib/rt.jar:/usr/iplanet/servers/bin/cert/jre/lib/i18n.jar:/usr
    /iplanet/servers/bin/cert/jars/jssjdk12.jar
    To edit the start-cert.bat script in Windows NT, follow these steps:

    1. Open a command-line window.

    2. Go to the CMS instance directory.

      For example, C:\iPlanet\server4\cert-testCA.

    3. Enter the following line at the prompt:

      type start-cert.bat

      You should see something similar to this:

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

      net start cert-testCA /fC:\iplanet\servers\cert-testCA\config\pwfile/cC:\iplanet\serve rs
      \cert-testCA\classes\;C:\iplanet\servers\bin\cert\classes\;C:
      \iplanet\servers\bin\cert\jars\jss.jar;C:\iplanet\servers\bin
      \cert\jars\certsrv.jar;C:\iplanet\servers\java\ldapjdk.jar;C:
      \iplanet\servers\bin\cert\jre\lib\rt.jar;C:\iplanet\servers\b
      in\cert\jre\lib\i18n.jar;C:\iplanet\server\bin\cert\jars\jssj
      dk12.jar;C:\iplanet\servers\java\swingall.jar

    5. Save your changes.

  5. Use your operating system's security feature to restrict access to the password file.

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

  1. Log in to iPlanet Console (see Logging In to iPlanet Console).

  2. In the Console tab, select the Server Group that contains the CMS instance you want to start.

  3. In the navigation tree, locate the CMS instance you want to start.

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

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

  1. Open a terminal window to your server.

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

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

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

iPlanet CMS (<instance_id>)

Figure 8-1    CMS service in the Windows NT Services panel


To start Certificate Management System from the Windows NT Services panel:

  1. Click the Start button on your desktop.

  2. Select Control Panel from Settings.

  3. In the Control Panel window that appears, click Services.

  4. Select the CMS instance and click Start.

    You are prompted to supply the single sign-on password for the server.

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

  • From iPlanet Console (locally and remotely)

  • From the command line (locally only)

  • On a Windows NT system, from the Windows NT Services panel

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:

  1. Log in to iPlanet Console (see Logging In to iPlanet Console).

  2. In the Console tab, select the Server Group that contains the CMS instance you want to stop.

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

    The server is stopped.


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:

  1. Open a terminal window to your server.

  2. In a Unix system, log in either as root or using the server's user account (if that is how you started the server).

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

  1. Click the Start button on your desktop.

  2. Select Control Panel from Settings.

  3. In the Control Panel window that appears, click Services.

  4. Select the CMS instance and click Stop.

  5. When prompted, click Yes.

    The server is stopped.



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:

  • From the CMS window (locally and remotely)

  • From the command line (locally only)


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:

  1. Log in to the CMS window (see Logging In to the CMS Window).

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

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

  1. Open a terminal window to your server.

  2. In a Unix system, log in either as root or using the server's user account (if that is how you started the server).

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

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

  1. Log in to iPlanet Console (see Logging In to iPlanet Console).

  2. In the Console tab, select the instance that corresponds to the CMS instance you want to check.

  3. In the right pane, check the Server Status field.

    If the selected instance of Certificate Management System is running, the status will be Started. Otherwise it will be Stopped or Unknown.



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 password—instead of multiple passwords—called 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 VM—the 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 server—the 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:

----- Password Cache -----

Internal LDAP Database : myIdbPwd
Internal Key Storage Token : myTokenPwd
Authentication : myPinAuthPwd
LDAP Publishing : myLdapPubPwd

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