12.2. CS.cfg Files

The runtime properties of a Certificate System subsystem are governed by a set of configuration parameters. These parameters are stored in a file that is read by the server during startup, CS.cfg.
The CS.cfg, an ASCII file, is created and populated with the appropriate configuration parameters when a subsystem is first installed. The way the instance functions are modified is by making changes through the subsystem console, which is the recommended method. The changes made in the administrative console are reflected in the configuration file.
It is also possible to edit the CS.cfg configuration file directly, and in some cases this is the easiest way to manage the subsystem.

12.2.1. Locating the CS.cfg File

Each instance of a Certificate System subsystem has its own configuration file, CS.cfg. The contents of the file for each subsystem instance is different depending on the way the subsystem was configured, additional settings and configuration (like adding new profiles or enabling self-tests), and the type of subsystem.
The CS.cfg file is located in the configuration directory for the instance.
/var/lib/pki/instance_name/conf
For example:
/var/lib/pki/instance_name/conf/ca

12.2.2. Overview of the CS.cfg Configuration File

Each subsystem instances has its own main configuration file, CS.cfg, which contains all of the settings for the instance, such as plug-ins and Java classes for configuration. The parameters and specific settings are different depending on the type of subsystem, but, in a general sense, the CS.cfg file defines these parts of the subsystem instance:
  • Basic subsystem instance information, like its name, port assignments, instance directory, and hostname
  • Logging
  • Plug-ins and methods to authenticate to the instance's user directory (authorization)
  • The security domain to which the instance belongs
  • Subsystem certificates
  • Other subsystems used by the subsystem instance
  • Database types and instances used by the subsystem
  • Settings for PKI-related tasks, like the key profiles in the TKS, the certificate profiles in the CA, and the required agents for key recovery in the KRA
Many of the configuration parameters (aside from the ones for PKI tasks) are very much the same between the CA, OCSP, KRA, and TKS because they all use a Java-based console, so configuration settings which can be managed in the console have similar parameters.
The CS.cfg file a basic parameter=value format.
#comment
parameter=value
In the CS.cfg file, many of the parameter blocks have descriptive comments, commented out with a pound (#) character. Comments, blank lines, unknown parameters, or misspelled parameters are ignored by the server.

Note

A bug in the TPS prevents it from ignoring lines which are commented out in the CS.cfg file. Rather than commenting out lines in the TPS CS.cfg file, simply delete those lines.
Parameters that configure the same area of the instance tend to be grouped together into the same block.

Example 12.1. Logging Settings in the CS.cfg File

log.instance.System._000=##
log.instance.System._001=## System Logging
log.instance.System._002=##
log.instance.System.bufferSize=512
log.instance.System.enable=true
log.instance.System.expirationTime=0
log.instance.System.fileName=/var/lib/pki-ca/logs/system
log.instance.System.flushInterval=5
log.instance.System.level=3
log.instance.System.maxFileSize=2000
log.instance.System.pluginName=file
log.instance.System.rolloverInterval=2592000
log.instance.System.type=system
Some areas of functionality are implemented through plug-ins, such as self-tests, jobs, and authorization to access the subsystem. For those parameters, the plug-in instance has a unique identifier (since there can be multiple instances of even the same plug-in called for a subsystem), the implementation plug-in name, and the Java class.

Example 12.2. Subsystem Authorization Settings

authz.impl._000=##
authz.impl._001=## authorization manager implementations
authz.impl._002=##
authz.impl.BasicAclAuthz.class=com.netscape.cms.authorization.BasicAclAuthz
authz.instance.BasicAclAuthz.pluginName=BasicAclAuthz

Note

The values for configuration parameters must be properly formatted, so they must obey two rules:
  • The values that need to be localized must be in UTF8 characters.
  • The CS.cfg file supports forward slashes (/) in parameter values. If a back slash (\) is required in a value, it must be escaped with a back slash, meaning that two back slashes in a row must be used.
The following sections are snapshots of CS.cfg file settings and parameters. These are not exhaustive references or examples of CS.cfg file parameters. Also, the parameters available and used in each subsystem configuration file is very different, although there are similarities.

12.2.2.1. Basic Subsystem Settings

Basic settings are specific to the instance itself, without directly relating to the functionality or behavior of the subsystem. This includes settings for the instance name, root directory, the user ID for the process, and port numbers. Many of the settings assigned when the instance is first installed or configured are prefaced with pkicreate.

Example 12.3. Basic Instance Parameters for the CA

authType=pwd
installDate=Mon Jul 13 08:13:39 2009
instanceId=pki-ca
instanceRoot=/var/lib/pki-ca
machineName=server.example.com
multiroles=true
passwordClass=com.netscape.cmsutil.password.PlainPasswordFile
passwordFile=/var/lib/pki-ca/conf/password.conf
...
admin.interface.uri=ca/admin/console/config/wizard
agent.interface.uri=ca/agent/ca
...
os.userid=dirsrv
pkicreate.admin_secure_port=9445
pkicreate.agent_secure_port=9443
pkicreate.ee_secure_port=9444
pkicreate.pki_instance_name=pki-ca
pkicreate.pki_instance_root=/var/lib
pkicreate.secure_port=9443
pkicreate.subsystem_type=ca
pkicreate.tomcat_server_port=9701
pkicreate.unsecure_port=9180
pkicreate.user=pkiuser
pkicreate.arg11.group=pkiuser
Many of these configuration options are covered in Chapter 13, Basic Subsystem Management.

Important

While information like the port settings is included in the CS.cfg file, it is not set in the CS.cfg. The server configuration for the CA, OCSP, TKS, and KRA is set in the server.xml file.

12.2.2.2. Logging Settings

There are several different types of logs that can be configured, depending on the type of subsystem. Each type of log has its own configuration entry in the CS.cfg file.
For example, the CA has this entry for transaction logs, which allows log rotation, buffered logging, and log levels, among other settings:
log.instance.Transactions._000=##
log.instance.Transactions._001=## Transaction Logging
log.instance.Transactions._002=##
log.instance.Transactions.bufferSize=512
log.instance.Transactions.enable=true
log.instance.Transactions.expirationTime=0
log.instance.Transactions.fileName=/var/lib/pki/pki-tomcat/ca/logs/transactions
log.instance.Transactions.flushInterval=5
log.instance.Transactions.level=1
log.instance.Transactions.maxFileSize=2000
log.instance.Transactions.pluginName=file
log.instance.Transactions.rolloverInterval=2592000
log.instance.Transactions.type=transaction

12.2.2.3. Authorization and Authentication Settings

The CS.cfg file sets how users are approved to access a subsystem instance (authorization) and how requests to a subsystem are approved (authentication).
The CA, OCSP, TKS, and KRA use authorization plug-ins to define the settings for logging into the subsystem. For some authorization settings, that is all that is required. It is also possible to select an authorization method that uses an LDAP database to store user entries, in which case the database settings are configured along with the plug-in.
authz.impl.DirAclAuthz.class=com.netscape.cms.authorization.DirAclAuthz
authz.instance.DirAclAuthz.ldap=internaldb
authz.instance.DirAclAuthz.pluginName=DirAclAuthz
authz.instance.DirAclAuthz.ldap._000=##
authz.instance.DirAclAuthz.ldap._001=## Internal Database
authz.instance.DirAclAuthz.ldap._002=##
authz.instance.DirAclAuthz.ldap.basedn=dc=server.example.com-pki-ca
authz.instance.DirAclAuthz.ldap.database=server.example.com-pki-ca
authz.instance.DirAclAuthz.ldap.maxConns=15
authz.instance.DirAclAuthz.ldap.minConns=3
authz.instance.DirAclAuthz.ldap.ldapauth.authtype=BasicAuth
authz.instance.DirAclAuthz.ldap.ldapauth.bindDN=cn=Directory Manager
authz.instance.DirAclAuthz.ldap.ldapauth.bindPWPrompt=Internal LDAP Database
authz.instance.DirAclAuthz.ldap.ldapauth.clientCertNickname=
authz.instance.DirAclAuthz.ldap.ldapconn.host=localhost
authz.instance.DirAclAuthz.ldap.ldapconn.port=389
authz.instance.DirAclAuthz.ldap.ldapconn.secureConn=false
authz.instance.DirAclAuthz.ldap.multipleSuffix.enable=false
The TPS, for example, uses the auth.instance settings to configure the user directory it uses to authenticate users who try to access the TPS.
auth.instance.0.SSLOn=false
auth.instance.0.attributes=mail,cn,uid
auth.instance.0.attributes._001=##############################################
auth.instance.0.attributes._002=# attributes will be available
auth.instance.0.attributes._003=# as $auth.<attribute>$
auth.instance.0.attributes._004=##############################################
auth.instance.0.authId=ldap1
auth.instance.0.baseDN=dc=example,dc=com
auth.instance.0.hostport=localhost:389
auth.instance.0.libraryFactory=GetAuthentication
auth.instance.0.libraryName=/usr/lib64/libldapauth.so
auth.instance.0.retries=1
auth.instance.0.retryConnect=3
auth.instance.0.ssl=false
auth.instance.0.type=LDAP_Authentication
auth.instance.0.ui.description.en=This authenticates user against the LDAP directory.
auth.instance.0.ui.id.PASSWORD.description.en=LDAP Password
auth.instance.0.ui.id.PASSWORD.name.en=LDAP Password
auth.instance.0.ui.id.UID.description.en=LDAP User ID
auth.instance.0.ui.id.UID.name.en=LDAP User ID
auth.instance.0.ui.title.en=LDAP Authentication
The CA also has to have a mechanism for approving user requests. As with configuring authorization, this is done by identifying the appropriate authentication plug-in and configuring an instance for it:
auths.impl.AgentCertAuth.class=com.netscape.cms.authentication.AgentCertAuthentication
auths.instance.AgentCertAuth.agentGroup=Certificate Manager Agents
auths.instance.AgentCertAuth.pluginName=AgentCertAuth

12.2.2.4. Security Domain Settings

Every instance must belong to a security domain, so every instance has a securitydomain definition block.
securitydomain.flushinterval=86400000
securitydomain.host=server.example.com
securitydomain.httpport=9180
securitydomain.httpsadminport=9445
securitydomain.httpsagentport=9443
securitydomain.httpseeport=9444
securitydomain.name=Example Domain
securitydomain.select=new
securitydomain.store=ldap
For the CA hosting the domain, that is the only configuration necessary. All subsystems which belong to the security domain also have a setting block for the security domain URLs.
config.sdomainAdminURL=https://server.example.com:8443
config.sdomainAgentURL=https://server.example.com:8443
config.sdomainEEURL=https://server.example.com:9443
config.sdomainHttpURL=https://server.example.com:8443

12.2.2.5. Subsystem Certificate Settings

Several of the subsystems have entries for each subsystem certificate in the configuration file.
ca.sslserver.cert=MIIDmDCCAoCgAwIBAgIBAzANBgkqhkiG9w0BAQUFADBAMR4wHAYDVQQKExVSZWR...
ca.sslserver.certreq=MIICizCCAXMCAQAwRjEeMBwGA1UEChMVUmVkYnVkY29tcHV0ZXIgRG9tYWluMSQwIgYDV...
ca.sslserver.nickname=Server-Cert cert-pki-ca
ca.sslserver.tokenname=Internal Key Storage Token

12.2.2.6. Settings for Required Subsystems

At a minimum, each subsystem depends on a CA, which means that the CA (and any other required subsystem) has to be configured in the subsystem's settings. Any connection to another subsystem is prefaced by conn. and then the subsystem type and number.
conn.ca1.clientNickname=subsystemCert cert-pki-tps
conn.ca1.hostadminport=server.example.com:8443
conn.ca1.hostagentport=server.example.com:8443
conn.ca1.hostport=server.example.com:9443
conn.ca1.keepAlive=true
conn.ca1.retryConnect=3
conn.ca1.servlet.enrollment=/ca/ee/ca/profileSubmitSSLClient
conn.ca1.servlet.renewal=/ca/ee/ca/profileSubmitSSLClient
conn.ca1.servlet.revoke=/ca/subsystem/ca/doRevoke
conn.ca1.servlet.unrevoke=/ca/subsystem/ca/doUnrevoke
conn.ca1.timeout=100

12.2.2.7. Database Settings

All of the subsystems use an LDAP directory to store their information. This internal database is configured in the internaldb parameters, except for the TPS which configured it in the tokendb parameters with a lot of other configuration settings.
internaldb._000=##
internaldb._001=## Internal Database
internaldb._002=##
internaldb.basedn=dc=server.example.com-pki-ca
internaldb.database=server.example.com-pki-ca
internaldb.maxConns=15
internaldb.minConns=3
internaldb.ldapauth.authtype=BasicAuth
internaldb.ldapauth.bindDN=cn=Directory Manager
internaldb.ldapauth.bindPWPrompt=Internal LDAP Database
internaldb.ldapauth.clientCertNickname=
internaldb.ldapconn.host=localhost
internaldb.ldapconn.port=389
internaldb.ldapconn.secureConn=false
internaldb.multipleSuffix.enable=false

12.2.2.8. Settings for PKI Tasks

The CS.cfg file is used to configure the PKI tasks for every subsystem. The parameters are different for every single subsystem, without any overlap.
For example, the KRA has settings for storing and recovering keys
kra.keySplitting=false
kra.noOfRequiredRecoveryAgents=1
Review the CS.cfg file for each subsystem to become familiar with its PKI task settings; the comments in the file are a decent guide for learning what the different parameters are.
  • The CA configuration file lists all of the certificate profiles and policy settings, as well as rules for generating CRLs.
  • The TPS configures different token operations.
  • The TKS lists profiles for deriving keys from different key types.
  • The OCSP sets key information for different key sets.

12.2.3. Editing the Configuration File

Warning

Do not edit the configuration file directly without being familiar with the configuration parameters or without being sure that the changes are acceptable to the server. The Certificate System fails to start if the configuration file is modified incorrectly. Incorrect configuration can also result in data loss.
To modify the CS.cfg file:
  1. Stop the subsystem instance.
    systemctl stop pki-tomcatd@instance_name.service
    The configuration file is stored in the cache when the instance is started. Any changes made to the instance through the Console are changed in the cached version of the file. When the server is stopped or restarted, the configuration file stored in the cache is written to disk. Stop the server before editing the configuration file or the changes will be overwritten by the cached version when the server is stopped.
  2. Open the /var/lib/pki/instance_name/conf directory.
  3. Open the CS.cfg file in a text editor.
  4. Edit the parameters in the file, and save the changes.
  5. Start the subsystem instance.
    systemctl start pki-tomcatd@instance_name.service