13.2. PKI Instance Execution Management

The act of starting, stopping, restarting, or obtaining the status of a PKI instance is known as execution management. Each PKI instance, separate or shared, is started, stopped, restarted, and has its status obtained separately. This section describes the execution management for any PKI instance.

13.2.1. Starting, Stopping, and Restarting a PKI Instance

A PKI instance is started, stopped, and restarted like other system programs, using systemd.
  1. Log in to the server machine as root.
  2. Run the systemctl command, specifying the action and the instance name:
    systemctl start|stop|restart pki-tomcatd@instance_name.service
    For example:
    systemctl restart pki-tomcatd@pki-tomcat.service

13.2.2. Restarting a PKI Instance after a Machine Restart

If a computer running one or more PKI instances is shut down unexpectedly, more services than just the PKI instances must be restarted, in the proper order, for the subsystem to be available both through the HTML services page and the administrative console.
  1. If the Directory Server instance used by the subsystem is installed on the local machine, restart the Administration Server and the Directory Server processes.
    systemctl start dirsrv-admin.service
    systemctl start dirsrv@instance_name.service
  2. Start the Certificate System subsystem instances.
    systemctl start pki-tomcatd@instance_name.service

13.2.3. Checking the PKI Instance Status

The systemctl command can be used to check the status of a process, showing whether it is running or stopped. For example:
systemctl -l status pki-tomcatd@pki-tomcat.service
pki-tomcatd@pki-tomcat.service - PKI Tomcat Server pki-tomcat
   Loaded: loaded (/lib/systemd/system/pki-tomcatd@.service; enabled)
   Active: inactive (dead) since Fri 2015-11-20 19:04:11 MST; 12s ago
  Process: 8728 ExecStop=/usr/libexec/tomcat/server stop (code=exited, status=0/SUCCESS)
  Process: 8465 ExecStart=/usr/libexec/tomcat/server start (code=exited, status=143)
  Process: 8316 ExecStartPre=/usr/bin/pkidaemon start tomcat %i (code=exited, status=0/SUCCESS)
 Main PID: 8465 (code=exited, status=143)

Nov 20 19:04:10 pki.example.com server[8728]: options used: -Dcatalina.base=/var/lib/pki/pki-tomcat -Dcatalina.home=/usr/share/tomcat -Djava.endorsed.dirs= -Djava.io.tmpdir=/var/lib/pki/pki-tomcat/temp -Djava.util.logging.config.file=/var/lib/pki/pki-tomcat/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
Nov 20 19:04:10 pki.example.com server[8728]: arguments used: stop
Nov 20 19:04:11 pki.example.com server[8465]: Nov 20, 2015 7:04:11 PM org.apache.catalina.core.StandardServer await
Nov 20 19:04:11 pki.example.com server[8465]: INFO: A valid shutdown command was received via the shutdown port. Stopping the Server instance.
Nov 20 19:04:11 pki.example.com server[8465]: PKIListener: org.apache.catalina.core.StandardServer[before_stop]
Nov 20 19:04:11 pki.example.com server[8465]: PKIListener: org.apache.catalina.core.StandardServer[stop]
Nov 20 19:04:11 pki.example.com server[8465]: PKIListener: org.apache.catalina.core.StandardServer[configure_stop]
Nov 20 19:04:11 pki.example.com server[8465]: Nov 20, 2015 7:04:11 PM org.apache.coyote.AbstractProtocol pause
Nov 20 19:04:11 pki.example.com server[8465]: INFO: Pausing ProtocolHandler ["http-bio-8080"]
Nov 20 19:04:11 pki.example.com systemd[1]: Stopped PKI Tomcat Server pki-tomcat.
If the instance is running, the status check returns information similar to the following example:
systemctl -l status pki-tomcatd@pki-tomcat.service
pki-tomcatd@pki-tomcat.service - PKI Tomcat Server pki-tomcat
   Loaded: loaded (/lib/systemd/system/pki-tomcatd@.service; enabled)
   Active: active (running) since Fri 2015-11-20 19:09:09 MST; 3s ago
  Process: 8728 ExecStop=/usr/libexec/tomcat/server stop (code=exited, status=0/SUCCESS)
  Process: 9154 ExecStartPre=/usr/bin/pkidaemon start tomcat %i (code=exited, status=0/SUCCESS)
 Main PID: 9293 (java)
   CGroup: /system.slice/system-pki\x2dtomcatd.slice/pki-tomcatd@pki-tomcat.service
           ������9293 java -DRESTEASY_LIB=/usr/share/java/resteasy-base -Djava.library.path=/usr/lib64/nuxwdog-jni -classpath /usr/share/tomcat/bin/bootstrap.jar:/usr/share/tomcat/bin/tomcat-juli.jar:/usr/share/java/commons-daemon.jar -Dcatalina.base=/var/lib/pki/pki-tomcat -Dcatalina.home=/usr/share/tomcat -Djava.endorsed.dirs= -Djava.io.tmpdir=/var/lib/pki/pki-tomcat/temp -Djava.util.logging.config.file=/var/lib/pki/pki-tomcat/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.security.manager -Djava.security.policy==/var/lib/pki/pki-tomcat/conf/catalina.policy org.apache.catalina.startup.Bootstrap start

Nov 20 19:09:10 pki.example.com server[9293]: Nov 20, 2015 7:09:10 PM org.apache.catalina.core.StandardService startInternal
Nov 20 19:09:10 pki.example.com server[9293]: INFO: Starting service Catalina
Nov 20 19:09:10 pki.example.com server[9293]: Nov 20, 2015 7:09:10 PM org.apache.catalina.core.StandardEngine startInternal
Nov 20 19:09:10 pki.example.com server[9293]: INFO: Starting Servlet Engine: Apache Tomcat/7.0.54
Nov 20 19:09:10 pki.example.com server[9293]: Nov 20, 2015 7:09:10 PM org.apache.catalina.startup.HostConfig deployDescriptor
Nov 20 19:09:10 pki.example.com server[9293]: INFO: Deploying configuration descriptor /etc/pki/pki-tomcat/Catalina/localhost/ROOT.xml
Nov 20 19:09:12 pki.example.com server[9293]: Nov 20, 2015 7:09:12 PM org.apache.catalina.startup.HostConfig deployDescriptor
Nov 20 19:09:12 pki.example.com server[9293]: INFO: Deployment of configuration descriptor /etc/pki/pki-tomcat/Catalina/localhost/ROOT.xml has finished in 2,071 ms
Nov 20 19:09:12 pki.example.com server[9293]: Nov 20, 2015 7:09:12 PM org.apache.catalina.startup.HostConfig deployDescriptor
Nov 20 19:09:12 pki.example.com server[9293]: INFO: Deploying configuration descriptor /etc/pki/pki-tomcat/Catalina/localhost/pki#admin.xml

13.2.4. Configuring a PKI Instance to Automatically Start Upon Reboot

The systemctl command can be used to automatically start instances upon reboot. For example, the following commands automatically start the Red Hat Administration Server, Directory Server, and a CA upon reboot:
# systemctl enable dirsrv-admin.service
# systemctl enable dirsrv.target
# systemctl enable pki-tomcatd@pki-tomcat.service

Note

The default PKI instance installation and configuration using the pkispawn command automatically enables the instance to start upon reboot.
To disable this behavior (that is, to prevent PKI instances from automatically starting upon reboot), issue the following commands:
# systemctl disable pki-tomcatd@pki-tomcat.service
# systemctl disable dirsrv.target
# systemctl disable dirsrv-admin.service

13.2.5. Setting sudo Permissions for Certificate System Services

For both simplicity of administration and security, the Certificate System and Directory Server processes can be configured so that PKI administrators (instead of only root) can start and stop the services.
A recommended option when setting up subsystems is to use a pkiadmin system group. (Details are in the Red Hat Certificate System 9 Planning, Installation, and Deployment Guide.) All of the operating system users which will be Certificate System administrators are then added to this group. If this pkiadmin system group exists, then it can be granted sudo access to perform certain tasks.
  1. Edit the /etc/sudoers file; on Red Hat Enterprise Linux 5.6, this can be done using the visudo command:
    # visudo
  2. Depending on what is installed on the machine, add a line for the Directory Server, the Administration Server, PKI management tools, and each PKI subsystem instance, granting sudo rights to the pkiadmin group:
    # For Directory Server services
    %pkiadmin ALL = PASSWD: /usr/bin/systemctl * dirsrv.target
    %pkiadmin ALL = PASSWD: /usr/bin/systemctl * dirsrv-admin.service
    
    # For PKI instance management
    %pkiadmin ALL = PASSWD: /usr/sbin/pkispawn *
    %pkiadmin ALL = PASSWD: /usr/sbin/pkidestroy *
    
    # For PKI instance services
    %pkiadmin ALL = PASSWD: /usr/bin/systemctl * pki-tomcatd@instance_name.service
    

Important

Make sure to set sudo permissions for every Certificate System, Directory Server, and Administration Server on the machine — and only for those instances on the machine. There could be multiple instances of the same subsystem type on a machine or no instance of a subsystem type. It depends on the deployment.