Show Table of Contents
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
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.cfgfile 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
Logging is covered in Chapter 15, Configuring Subsystem Logs.
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:
- 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. - Open the
/var/lib/pki/instance_name/confdirectory. - Open the
CS.cfgfile in a text editor. - Edit the parameters in the file, and save the changes.
- Start the subsystem instance.
systemctl start pki-tomcatd@instance_name.service
Where did the comment section go?
Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.