pki_default.cfg(5)					PKI Default Instance Configuration					pki_default.cfg(5)

NAME

       pki_default.cfg - Certificate Server instance default config file.

LOCATION

       /etc/pki/default.cfg

DESCRIPTION

       This  file  contains  the default settings for a Certificate Server instance created using pkispawn.  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 pkispawn(8) for details.

SECTIONS

       default.cfg  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.

       There  are  a  small number of bootstrap parameters which are passed in the configuration file by pkispawn. Other parameter's values can be
       interpolated tokens rather than explicit values. For example:

       pki_ca_signing_nickname=caSigningCert cert-%(pki_instance_name)s CA

       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 ONLY be overridden within the same section.	So, for example, pki_instance_name
       should only be overridden in [DEFAULT]; otherwise, interpolations can fail.

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.

       pki_instance_name

	      Name  of	the  instance.	The instance is located at /var/lib/pki/<instance_name>.  For Java subsystems, the default is specified as
	      pki-tomcat.

       pki_https_port, pki_http_port

	      Secure and unsecure ports.  Defaults to standard Tomcat ports 8443 and 8080, respectively, for Java subsystems, and 443 and  80  for
	      Apache subsystems.

       pki_ajp_port, pki_tomcat_server_port

	      Ports for Tomcat subsystems.  Defaults to standard Tomcat ports of 8009 and 8005, respectively.

       pki_proxy_http_port, pki_proxy_https_port, pki_enable_proxy

	      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/knowl-
	      edge/docs/Red_Hat_Certificate_System/ for details.

       pki_user, pki_group, pki_audit_group

	      Specifies  the  default  administrative user, group, and auditor group identities for PKI instances.  The default user and group are
	      both specified as pkiuser, and the default audit group is specified as pkiaudit.

       pki_token_name, pki_token_password

	      The token and password where this instance's system certificate and keys are stored.  Defaults to the NSS internal software token.

   SYSTEM CERTIFICATE PARAMETERS
       pkispawn 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:

	      * signing certificate ("signing").  Used to sign other certificates.  Required for CA.

	      * OCSP signing certificate ("ocsp_signing" in CA, "signing" in OCSP).  Used to sign CRLs.  Required for OCSP and CA.

	      * storage certificate ("storage").  Used to encrypt keys for storage in KRA.  Required for KRA only.

	      * transport certificate ("transport").  Used to encrypt keys in transport to the KRA.  Required for KRA only.

	      *  subsystem  certificate ("subsystem").	Used to communicate between subsystems within the security domain.  Issued by the security
	      domain CA.  Required for all subsystems.

	      * server certificate ("sslserver").  Used for communication with the server.  One server certificate is required for  each  Certifi-
	      cate Server instance.

	      * audit signing certificate ("audit_signing").  Used to sign audit logs.	Required for all subsystems except the RA.

       Each system certificate can be customized using the parameters below:

       pki_<tag>_key_type, pki_<type>_keysize, pki_<tag>_key_algorithm

	      Characteristics  of  the	private  key.  See  the  Red  Hat  Certificate	System	documentation  at https://access.redhat.com/knowl-
	      edge/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.

       pki_<tag>_signing_algorithm

	      For signing certificates, the algorithm used for signing.  Defaults to SHA256withRSA.

       pki_<tag>_token

	      Location where the certificate and private key are stored.  Defaults to the internal software NSS token database.

       pki_<tag>_nickname

	      Nickname for the certificate in the token database.

       pki_<tag>_subject_dn

	      Subject DN for the certificate.  The subject DN for the SSL Server certificate must include CN=<hostname>.

   ADMIN USER PARAMETERS
       pkispawn  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 pki_client_dir, and can be imported into a browser
       to administer the system.

       pki_admin_name, pki_admin_uid

	      Name and UID of this administrative user.  Defaults to caadmin for CA, kraadmin for KRA, etc.

       pki_admin_password

	      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.

       pki_admin_email

	      Email address for the admin user.

       pki_admin_dualkey, pki_admin_keysize, pki_admin_keytype

	      Settings for the administrator certificate and keys.

       pki_admin_subject_dn

	      Subject	DN   for   the	 administrator	certificate.   Defaults  to  cn=PKI  Administrator,  e=%(pki_admin_email)s,  o=%(pki_secu-
	      rity_domain_name)s.

       pki_admin_nickname
	      Nickname for the administrator certificate.

       pki_import_admin_cert

	      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 pki_client_dir.

	      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.

       pki_client_admin_cert_p12

	      Location for the PKCS  #12  file	containing  the  administrative  user's  certificate  and  keys.   For	a  CA,	this  defaults	to
	      ca_admin_cert.p12 in the pki_client_dir directory.

   BACKUP PARAMETERS
       pki_backup_keys, pki_backup_password

	      Set   to	 True	to  back  up  the  subsystem  certificates  and  keys  to  a  PKCS  #12  file.	 This  file  will  be  located	in
	      /var/lib/pki/<instance_name>/alias.  pki_backup_password is the password of the PKCS#12 file.

   CLIENT DIRECTORY PARAMETERS
       pki_client_dir

	      This is the location where all client data used during the installation is stored.  At the end of the invocation	of  pkispawn,  the
	      administrative user's certificate and keys are stored in a PKCS #12 file in this location.

       pki_client_database_dir, pki_client_database_password

	      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 pki_client_dir.

       pki_client_database_purge

	      Set to True to remove pki_client_database_dir at the end of the installation.  Defaults to True.

   INTERNAL DATABASE PARAMETERS

       pki_ds_hostname, pki_ds_ldap_port, pki_ds_ldaps_port

	      Hostname and ports for the internal database.  Defaults to localhost, 389, and 636, respectively.

       pki_ds_bind_dn, pki_ds_password

	      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 authen-
	      tication connections to the database.  Some additional configuration is required, including setting up the directory server  to  use
	      SSL.  See the documentation for details.

       pki_ds_secure_connection

	      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.

       pki_ds_remove_data

	      Sets whether to remove any data from the base DN before starting the installation.  Defaults to True.

       pki_ds_base_dn

	      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 pkispawn.  For a cloned subsystem, the base DN for the clone
	      subsystem MUST be the same as for the master subsystem.

       pki_ds_database

	      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 pkispawn.

   ISSUING CA PARAMETERS

       pki_issuing_ca_hostname, pki_issuing_ca_https_port, pki_issuing_ca_uri

	      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 subsys-
	      tem within the same instance.  The URI has the format https://<ca_hostname>:<ca_https_port>.

   MISCELLANEOUS PARAMETERS

       pki_restart_configured_instance

	      Sets whether to restart the instance after configuration is complete.  Defaults to True.

       pki_skip_configuration

	      Sets  whether  to  execute the configuration steps when running pkispawn.  If this is true, then the process is analogous to running
	      pkicreate, 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.

       pki_skip_installation

	      Sets  whether  to  skip  the  installation steps.  With pki_skip_configuration set to False, this is analogous to running pkisilent.
	      Defaults to False.

       pki_enable_java_debugger

	      Sets whether to attach a Java debugger such as Eclipse to the instance for troubleshooting.  Defaults to False.

       pki_security_manager

	      Enables the Java security manager policies provided by the JDK to be used with the instance.  Defaults to True.

   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 Certifi-
       cate System documentation at https://access.redhat.com/knowledge/docs/Red_Hat_Certificate_System/.

       pki_security_domain_hostname, pki_security_domain_https_port

	      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.

       pki_security_domain_user, pki_security_domain_password

	      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).

       pki_security_domain_name

	      The name of the security domain. This is required for the security domain CA.

   CLONE PARAMETERS
       pki_clone

	      Installs a clone, rather than original, subsystem.

       pki_clone_pkcs12_password, pki_clone_pkcs12_path

	      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 /var/lib/pki/<instance_name>/alias.

       pki_clone_replication_master_port, pki_clone_replication_clone_port

	      Ports  on  which	replication occurs.  These are the ports on the master and clone databases respectively.  Defaults to the internal
	      database port.

       pki_clone_repicate_schema

	      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.

       pki_clone_replication_security

	      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.

       pki_clone_uri

	      A pointer to the subsystem being cloned.	The format is https://<master_hostname>:<master_https_port>.

   EXTERNAL CA CERTIFICATE PARAMETERS

       pki_external

	      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 certifi-
	      cate chain are provided to the pkispawn utility to complete the installation.  Defaults to False.

       pki_external_csr_path

	      Required in the first step of the external CA signing process.  The CSR will be printed to the screen and stored in this location.

       pki_external_step_two

	      Specifies that this is the second step of the external CA process.  Defaults to False.

       pki_external_cert_path, pki_external_cert_chain_path

	      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.

   SUBORDINATE CA CERTIFICATE PARAMETERS

       pki_subordinate

	      Specifies  whether the new CA which will be a subordinate of another CA.	The master CA is specified by pki_issuing_ca.  Defaults to
	      False.

AUTHORS

       Ade Lee <alee@redhat.com>.  pkispawn was written by the Dogtag project.

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 avail-
       able at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.

SEE ALSO

       pkispawn(8)

version 1.0							 December 13, 2012						pki_default.cfg(5)