12.4. Using the Certificate System Watchdog Service

In Certificate System, the watchdog service is used to start services which require passwords to access the security database in order to start. In case that there is a requirement not to store the unencrypted passwords on the system, the watchdog service:
  • prompts for the relevant passwords during server startup and caches them.
  • uses cached passwords in case of a failure when the server is automatically restarted due to a crash.
For further details, see the corresponding section in the Certificate System Planning, Installation, and Deployment Guide.

12.4.1. Enabling the Watchdog Service

To enable the watchdog service:
  1. Backup the server.xml and password.conf files from the /var/lib/pki/instance_name/conf/ directory. For example: 
    # cp -p /var/lib/pki/instance_name/conf/server.xml /root/
# cp -p /var/lib/pki/instance_name/conf/password.conf /root/
  2. Stop and disable the Certificate System instance's service: 
    # systemctl stop pki-tomcatd@instance_name.service
# systemctl disable pki-tomcatd@instance_name.service
  3. If you use a Hardware Security Module (HSM), enable the watchdog service to prompt for the password of the hardware token:
    1. Display the name of the hardware token: 
      # egrep "^hardware-" /var/lib/pki/instance_name/conf/password.conf
hardware-HSM_token_name=password
      The highlighted string in the previous example is the hardware token name.
    2. Add the cms.tokenList parameter to the /var/lib/pki/instance_name/conf/ca/CS.cfg file and set it to the name of the hardware token. For example: 
      cms.tokenList=HMS_token_name
  4. Enable the watchdog configuration for the instance: 
    # pki-server instance-nuxwdog-enable instance_name
    For further details, see the pki-server-nuxwdog(8) man page.
  5. Optionally, to start the instance as the pkiuser user instead of root:
    1. Copy the watchdog systemd unit file of the instance to the /etc/systemd/system/ directory: 
      # cp -p /usr/lib/systemd/system/instance_name-nuxwdog@.service /etc/systemd/system/

      Note

      Unit files in the /etc/systemd/system/ directory have a higher priority and are not replaced during updates.
    2. Add the following entries to the [Service] section in the /etc/systemd/system/instance_name-nuxwdog@.service file: 
      User=pkiuser
Group=pkiuser
    3. Reload the systemd configuration: 
      # systemctl daemon-reload
  6. Enable the Certificate System service that uses the watchdog: 
    # systemctl enable pki-tomcatd-nuxwdog@instance_name.service
  7. Optionally: See Section 12.4.2, “Verifying That the Certificate System Watchdog Service is Enabled”.
  8. Start the Certificate System instance: 
    # systemctl start pki-tomcatd-nuxwdog@instance_name.service

12.4.2. Verifying That the Certificate System Watchdog Service is Enabled

To verify that the watchdog service is enabled:
  1. Verify that the pki-tomcatd-nuxwdog service is enabled: 
    # systemctl is-enabled pki-tomcatd-nuxwdog@instance_name.service
enabled
  2. Verify that the pki-tomcatd service is disabled: 
    # systemctl is-disabled pki-tomcatd@instance_name.service
disabled
  3. In the /etc/pki/instance_name/server.xml file:
    1. verify that the passwordFile parameter refers to the CS.cfg file. For example: 
      passwordFile="/etc/pki/instance_name/ca/CS.cfg"
    2. verify that the passwordClass parameter is set to com.netscape.cms.tomcat.NuxwdogPasswordStore: 
      passwordClass="com.netscape.cms.tomcat.NuxwdogPasswordStore"

12.4.3. Disabling the Watchdog Service

To disable the watchdog service:
  1. Stop and disable the Certificate System instance's service that uses the watchdog: 
    # systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl disable pki-tomcatd-nuxwdog@instance_name.service
  2. Enable the regular service without watch dog for the instance: 
    # pki-server instance-nuxwdog-disable instance_name
  3. Disable the watchdog configuration for the instance: 
    # systemctl enable pki-tomcatd@instance_name.service
    For further details, see the pki-server-nuxwdog(8) man page.
  4. Start the Certificate System instance: 
    # systemctl start pki-tomcatd@instance_name.service