path: root/base/deploy/man/man5/pki_default.cfg.5

.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH pki_default.cfg 5 "December 13, 2012" "version 1.0" "PKI Default Instance Configuration" Ade Lee
.\" Please adjust this date whenever revising the man page.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for man page specific macros, see man(7)
.SH NAME
pki_default.cfg \- Certificate Server instance default config file.

.SH LOCATION
/etc/pki/default.cfg

.SH DESCRIPTION
This file contains the default settings for a Certificate Server instance created using \fBpkispawn\fP.  This file should not be edited, as it can be modified when the Certificate Server packages are updated.  Rather, when setting up a Certificate Server instance, a user-provided configuration file can provide overrides to the defaults in /etc/pki/default.cfg.  See \fBpkispawn(8)\fR for details.

.SH SECTIONS
\fIdefault.cfg\fP is divided into subsystem-based sections ([DEFAULT] for general configuration and subsystem-type sections such as [CA] and [KRA]).  These sections are stacked, so that parameters read in earlier sections can be overwritten by parameters in later sections.  For the Java subsystems (CA, KRA, OCSP, and TKS), the sections read are [DEFAULT], [Tomcat] and the subsystem type section -- [CA], [KRA], [OCSP], and [TKS] -- in that order.  This allows the ability to specify parameters to be shared by all subsystems in [DEFAULT] or [Tomcat], and subsystem-specific upgrades in the other sections.
.PP
There are a small number of bootstrap parameters which are passed in the configuration file by \fBpkispawn\fP. Other parameter's values can be interpolated tokens rather than explicit values. For example:
.PP
\fBpki_ca_signing_nickname=caSigningCert cert-%(pki_instance_name)s CA\fP
.PP
This substitutes the value of pki_instance_name into the parameter value.  It is possible to interpolate any parameter within a section or in [DEFAULT]. Any parameter used in interpolation can \fBONLY\fP be overridden within the same section.  So, for example, pki_instance_name should only be overridden in [DEFAULT]; otherwise, interpolations can fail.

.SH GENERAL INSTANCE PARAMETERS
The parameters described below, as well as the parameters located in the following sections, can be customized as part of a deployment.  This list is not exhaustive.
.TP
.B pki_instance_name
.IP
Name of the instance. The instance is located at /var/lib/pki/<instance_name>.  For Java subsystems, the default is specified as pki-tomcat.
.TP
.B pki_https_port, pki_http_port
.IP
Secure and unsecure ports.  Defaults to standard Tomcat ports 8443 and 8080, respectively, for Java subsystems, and 443 and 80 for Apache subsystems.
.TP
.B pki_ajp_port, pki_tomcat_server_port
.IP
Ports for Tomcat subsystems.  Defaults to standard Tomcat ports of 8009 and 8005, respectively.
.TP
.B pki_proxy_http_port, pki_proxy_https_port, pki_enable_proxy
.IP
Ports for an Apache proxy server. Certificate Server instances can be run behind an Apache proxy server, which will communicate with the Tomcat instance through the AJP port.  See the Red Hat Certificate System documentation at https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System/ for details.
.TP
.B pki_user, pki_group, pki_audit_group
.IP
Specifies the default administrative user, group, and auditor group identities for PKI instances.  The default user and group are both specified as \fBpkiuser\fR, and the default audit group is specified as \fBpkiaudit\fR.
.TP
.B pki_token_name, pki_token_password
.IP
The token and password where this instance's system certificate and keys are stored.  Defaults to the NSS internal software token.

.SS SYSTEM CERTIFICATE PARAMETERS
\fBpkispawn\fP sets up a number of system certificates for each subsystem.  The system certificates which are required differ between subsystems.  Each system certificate is denoted by a tag, as noted below.  The different system certificates are:
.IP
* signing certificate ("signing").  Used to sign other certificates.  Required for CA.
.IP
* OCSP signing certificate ("ocsp_signing" in CA, "signing" in OCSP).  Used to sign CRLs.  Required for OCSP and CA.
.IP
* storage certificate ("storage").  Used to encrypt keys for storage in KRA.  Required for KRA only.
.IP
* transport certificate ("transport").  Used to encrypt keys in transport to the KRA.  Required for KRA only.
.IP
* subsystem certificate ("subsystem").  Used to communicate between subsystems within the security domain.  Issued by the security domain CA.  Required for all subsystems.
.IP
* server certificate ("sslserver").  Used for communication with the server.  One server certificate is required for each Certificate Server instance.
.IP
* audit signing certificate ("audit_signing").  Used to sign audit logs.  Required for all subsystems except the RA.
.PP
Each system certificate can be customized using the parameters below:
.TP
.B pki_<tag>_key_type, pki_<type>_keysize, pki_<tag>_key_algorithm
.IP
Characteristics of the private key. See the Red Hat Certificate System documentation at https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System/ for possible options.  The defaults are RSA for the type, 2048 bits for the key size, and SHA256withRSA for the algorithm.
.TP 
.B pki_<tag>_signing_algorithm
.IP
For signing certificates, the algorithm used for signing.  Defaults to SHA256withRSA.
.TP
.B pki_<tag>_token
.IP
Location where the certificate and private key are stored.  Defaults to the internal software NSS token database.
.TP
.B pki_<tag>_nickname
.IP
Nickname for the certificate in the token database.
.TP
.B pki_<tag>_subject_dn
.IP
Subject DN for the certificate.  The subject DN for the SSL Server certificate must include CN=<hostname>.
.SS ADMIN USER PARAMETERS
\fBpkispawn\fP creates a bootstrap administrative user that is a member of all the necessary groups to administer the installed subsystem.  On a security domain CA, the CA administrative user is also a member of the groups required to register a new subsystem on the security domain.  The certificate and keys for this administrative user are stored in a PKCS #12 file in \fBpki_client_dir\fP, and can be imported into a browser to administer the system.
.TP
.B pki_admin_name, pki_admin_uid
.IP
Name and UID of this administrative user.  Defaults to caadmin for CA, kraadmin for KRA, etc.
.TP
.B pki_admin_password
.IP
Password for the admin user.  This password is used to log into the pki-console (unless client authentication is enabled), as well as log into the security domain CA.
.TP
.B pki_admin_email
.IP
Email address for the admin user.
.TP
.B pki_admin_dualkey, pki_admin_keysize, pki_admin_keytype
.IP
Settings for the administrator certificate and keys.
.TP
.B pki_admin_subject_dn
.IP
Subject DN for the administrator certificate.  Defaults to \fBcn=PKI Administrator, e=%(pki_admin_email)s, o=%(pki_security_domain_name)s\fP.
.TP
.B pki_admin_nickname
Nickname for the administrator certificate.
.TP
.B pki_import_admin_cert
.IP
Set to True to import an existing admin certificate for the admin user, rather than generating a new one.  A subsystem-specific administrator will still be created within the subsystem's LDAP tree.  This is useful to allow multiple subsystems within the same instance to be more easily administered from the same browser by using a single certificate.

By default, this is set to False for CA subsystems and true for KRA, OCSP, and TKS subsystems.  In this case, the admin certificate is read from the file ca_admin.cert in \fBpki_client_dir\fP.

Note that cloned subsystems do not create a new administrative user.  The administrative user of the master subsystem is used instead, and the details of this master user are replicated during the install.
.TP
.B pki_client_admin_cert_p12
.IP
Location for the PKCS #12 file containing the administrative user's certificate and keys.  For a CA, this defaults to \fIca_admin_cert.p12\fP in the \fBpki_client_dir\fP directory.
.SS BACKUP PARAMETERS
.TP
.B pki_backup_keys, pki_backup_password
.IP
Set to True to back up the subsystem certificates and keys to a PKCS #12 file.  This file will be located in \fI/var/lib/pki/<instance_name>/alias\fP.  pki_backup_password is the password of the PKCS#12 file.
  
.SS CLIENT DIRECTORY PARAMETERS
.TP
.B pki_client_dir
.IP
This is the location where all client data used during the installation is stored.  At the end of the invocation of \fBpkispawn\fP, the administrative user's certificate and keys are stored in a PKCS #12 file in this location.
.TP
.B pki_client_database_dir,  pki_client_database_password
.IP
Location where an NSS token database is created in order to generate a key for the administrative user.  Usually, the data in this location is removed at the end of the installation, as the keys and certificates are stored in a PKCS #12 file in \fBpki_client_dir\fP.
.TP
.B pki_client_database_purge
.IP
Set to True to remove \fBpki_client_database_dir\fP at the end of the installation.  Defaults to True.
.SS INTERNAL DATABASE PARAMETERS
\x'-1'\fBpki_ds_hostname, pki_ds_ldap_port, pki_ds_ldaps_port\fR
.IP
Hostname and ports for the internal database.  Defaults to localhost, 389, and 636, respectively.
.PP
.B pki_ds_bind_dn, pki_ds_password
.IP
Credentials to connect to the database during installation.  Directory Manager-level access is required during installation to set up the relevant schema and database.  During the installation, a more restricted Certificate Server user is set up to client authentication connections to the database.  Some additional configuration is required, including setting up the directory server to use SSL.  See the documentation for details. 
.PP
.B pki_ds_secure_connection
.IP
Sets whether to require connections to the Directory Server using LDAPS.  This requires SSL to be set up on the Directory Server first.  Defaults to false.
.PP
.B pki_ds_remove_data
.IP
Sets whether to remove any data from the base DN before starting the installation.  Defaults to True.
.PP
.B pki_ds_base_dn
.IP
The base DN for the internal database.  It is advised that the Certificate Server have its own base DN for its internal database.  If the base DN does not exist, it will be created during the running of \fBpkispawn\fP.  For a cloned subsystem, the base DN for the clone subsystem MUST be the same as for the master subsystem.
.PP
.B pki_ds_database
.IP
Name of the back-end database.  It is advised that the Certificate Server have its own base DN for its internal database.  If the back-end does not exist, it will be created during the running of \fBpkispawn\fP.
.SS ISSUING CA PARAMETERS
\x'-1'\fBpki_issuing_ca_hostname, pki_issuing_ca_https_port, pki_issuing_ca_uri\fR
.IP
Hostname and port, or URI of the issuing CA.  Required for installations of subordinate CA and non-CA subsystems.  This should point to the CA that will issue the relevant system certificates for the subsystem.  In a default install, this defaults to the CA subsystem within the same instance.  The URI has the format https://<ca_hostname>:<ca_https_port>.

.SS MISCELLANEOUS PARAMETERS
\x'-1'\fBpki_restart_configured_instance\fR
.IP
Sets whether to restart the instance after configuration is complete.  Defaults to True.
.PP
.B pki_skip_configuration
.IP
Sets whether to execute the configuration steps when running \fBpkispawn\fP.  If this is true, then the process is analogous to running \fBpkicreate\fP, when the configuration was performed separately from the instance creation.  A configuration URL will be provided.  This URL can be used as a starting point for the browser-based configuration panels.  Defaults to False.
.PP
.B pki_skip_installation
.IP
Sets whether to skip the installation steps.  With pki_skip_configuration set to False, this is analogous to running pkisilent.  Defaults to False.
.PP
.B pki_enable_java_debugger
.IP
Sets whether to attach a Java debugger such as Eclipse to the instance for troubleshooting.  Defaults to False.
.PP
.B pki_security_manager
.IP
Enables the Java security manager policies provided by the JDK to be used with the instance.  Defaults to True.
.PP
.SS SECURITY DOMAIN PARAMETERS
The security domain is a component that facilitates communication between subsystems.  The first CA installed hosts this component and is used to register subsequent subsystems with the security domain.  These subsystems can communicate with each other using their subsystem certificate, which is issued by the security domain CA.  For more information about the security domain component, see the Red Hat Certificate System documentation at https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System/.
.TP
.B pki_security_domain_hostname, pki_security_domain_https_port
.IP
Location of the security domain.  Required for KRA, OCSP, and TKS subsystems and for CA subsystems joining a security domain.  Defaults to the location of the CA subsystem within the same instance.
.TP
.B pki_security_domain_user, pki_security_domain_password
.IP
Administrative user of the security domain.  Required for KRA, OCSP, and TKS subsystems, and for CA subsystems joining a security domain.  Defaults to the administrative user for the CA subsystem within the same instance (caadmin).
.TP
.B pki_security_domain_name
.IP
The name of the security domain. This is required for the security domain CA.

.SS CLONE PARAMETERS
.TP
.B pki_clone
.IP
Installs a clone, rather than original, subsystem.
.TP
.B pki_clone_pkcs12_password, pki_clone_pkcs12_path
.IP
Location and password of the PKCS #12 file containing the system certificates for the master subsystem being cloned.  This file should be readable by the user that the Certificate Server is running as (default of pkiuser), and have the correct selinux context (pki_tomcat_cert_t).  This can be achieved by placing the file in \fI/var/lib/pki/<instance_name>/alias\fP.
.TP
.B pki_clone_replication_master_port, pki_clone_replication_clone_port
.IP
Ports on which replication occurs.  These are the ports on the master and clone databases respectively.  Defaults to the internal database port. 
.TP
.B pki_clone_repicate_schema
.IP
Replicate schema when the replication agreement is set up and the new instance (consumer) is initialized.  Otherwise, the schema must be installed in the clone as a separate step beforehand.  This does not usually have to be changed.  Defaults to True.
.TP
.B pki_clone_replication_security
.IP
The type of security used for the replication data.  This can be set to SSL (using LDAPS), TLS, or None.  Defaults to None.  For SSL and TLS, SSL must be set up for the database instances beforehand.
.TP
.B pki_clone_uri
.IP
A pointer to the subsystem being cloned.  The format is https://<master_hostname>:<master_https_port>.

.SS EXTERNAL CA CERTIFICATE PARAMETERS
\x'-1'\fBpki_external\fR
.IP
Sets whether the new CA will have a signing certificate that will be issued by an external CA.  This is a two step process.  In the first step, a CSR to be presented to the external CA is generated.  In the second step, the issued signing certificate and certificate chain are provided to the \fBpkispawn\fP utility to complete the installation.  Defaults to False.
.PP
.B pki_external_csr_path
.IP
Required in the first step of the external CA signing process.  The CSR will be printed to the screen and stored in this location.
.PP
.B pki_external_step_two
.IP
Specifies that this is the second step of the external CA process.  Defaults to False.
.PP
.B pki_external_cert_path, pki_external_cert_chain_path
.IP
Required for the second step of the external CA signing process.  This is the location of the CA signing cert (as issued by the external CA) and the external CA's certificate chain.
.SS SUBORDINATE CA CERTIFICATE PARAMETERS
\x'-1'\fBpki_subordinate\fR
.IP
Specifies whether the new CA which will be a subordinate of another CA.  The master CA is specified by \fBpki_issuing_ca\fP.  Defaults to False.

.SH AUTHORS
Ade Lee <alee@redhat.com>.  \fBpkispawn\fP was written by the Dogtag project.

.SH COPYRIGHT
Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.

.SH SEE ALSO
.BR pkispawn(8)