13.10. Running Self-Tests

The Certificate System has the added functionality to allow self-tests of the server. The self-tests are run at start up and can also be run on demand. The startup self-tests run when the server starts and keep the server from starting if a critical self-test fails. The on-demand self-tests are run by clicking the self-tests button in the subsystem console.

13.10.1. Running Self-Tests

The on-demand self-test for the CA, OCSP, KRA, or TKS subsystems are run from the console. The on-demand self-tests for the TPS system are run from the web services page. Running Self-Tests from the Console

  1. Log into the Console.
    pkiconsole https://server.example.com:admin_port/subsystem_type
  2. Select the subsystem name at the top of the left pane.
  3. Select the Self Tests tab.
  4. Click Run.
    The self-tests that are configured for the subsystem will run. If any critical self-tests fail, the server will stop.
  5. The On-Demand Self Tests Results window appears, showing the logged events for this run of the self-tests. Running TPS Self-Tests

To run TPS self-tests from the command-line interface (CLI):
  • pki tps-selftest-find
  • pki tps-selftest-run
  • pki tps-selftest-show

13.10.2. Self-Test Logging

A separate log, selftest.log, is added to the log directory that contains reports for both the start up self-tests and the on-demand self-tests. This log is configured by changing the setting for the log in the CS.cfg file. See Section 13.10.4, “Modifying Self-Test Configuration” for details.

13.10.3. Configuring Self-Tests

The self-tests feature and individual self-tests are registered and configured in the CS.cfg file. If a self-test is enabled, that self-test is listed for either on-demand or start up and is either empty or set as critical.
Critical self-tests have a colon and the word critical after the name of the self-test. Otherwise, nothing is in this place. The server shuts down when a critical self-test fails during on demand self-tests; the server will not start when a critical self-test fails during start up.
The implemented self-tests are automatically registered and configured when the instance was installed. The self-tests that are registered and configured are those associated with the subsystem type.
Self-tests are turned off or the criticality is changed by changing those setting in the CS.cfg file. To turn a self-test off, remove is from the list of self-tests.

13.10.4. Modifying Self-Test Configuration

To modify the configuration settings for self-tests:
  1. Stop the subsystem instance.
  2. Open the CS.cfg file located in the instance's conf/ directory.
  3. To edit the settings for the self-test log, edit the entries that begin with selftests.container.logger. These include the following parameters:
    • bufferSize — Specify the buffer size in kilobytes (KB) for the log. The default size is 512 KB. For more information, see Section, “Buffered and Unbuffered Logging”. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.
    • enable — Specify true to enable; false to disable. Only enabled logs actually record events.
    • fileName — Specify the full path, including the filename, to the file to write messages. The server must have read/write permission to the file.
    • flushInterval — Specify the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.
    • level — The default selection is 1; this log is not set up for any level beside 1.
    • maxFileSize — Specify the file size in kilobytes (KB) for the error log. The default size is 100 KB. The maxFileSize determines how large a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and a new log file is started. For more information, see Section, “Log File Rotation”.
    • register — If this variable is set to false (the default value), the self-test messages are only logged to the log file specified by selftests.container.logger.fileName. If this variable is set to true, then the self-test messages are written to both the log file specified by selftests.container.logger.fileName and the log file specified by log.instance.Transactions.fileName.
    • rolloverInterval — Specify the frequency at which the server rotates the active error log file. The choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly. For more information, see Section, “Log File Rotation”.
    • type — Set to transaction; do not change this.
  4. To edit the order in which the self-test are run, specify the order by listing any of the self-test as the value of the following parameters separated by a comma and a space.
    To mark a self-test critical, add a colon and the word critical to the name of the self-test in the list.
    To disable a self-test, remove it as the value of either the selftests.container.order.onDemand or selftests.container.order.startup parameters.
  5. Save the file.
  6. Start the subsystem.