Chapter 12. Basic Subsystem Management

This chapter discusses the Certificate System administrative console, the configuration files, and other basic administrative tasks such as starting and stopping the server, managing logs, changing port assignments, and changing the internal database.

12.1. Starting and Stopping Subsystem Instances

Each Certificate System subsystem instance is started, stopped, and restarted separately. This section describes how to start, stop, and restart a subsystem instance.

12.1.1. Starting and Stopping a Subsystem Server Instance

A subsystem instance is started, stopped, and restarted like other system programs, using native tools like service.

Log in to the server machine as root.
Run service, specifying the instance name and the action. For example:
```
service instance_name start|stop|restart
```

12.1.2. Restarting a Subsystem after a Machine Restart

If a computer running a subsystem is shut down unexpectedly, more services than just the subsystem must be restarted, in the proper order, for the subsystem to be available both through the HTML services page and the administrative console.

If the Directory Server instance used by the subsystem is installed on the local machine, then restart the Administration Server and the Directory Server processes.
```
service dirsrv-admin start
service dirsrv start
```
Start the Certificate System subsystem instance.
```
service instance_name start
```

12.1.3. Checking the Subsystem Instance Status

The service command can be used to check the status of a process, showing whether it is running, stopped, unconfigured, or in some other state. For example:

service pki-tps status
pki-tps is stopped

If the instance is running, then the status check returns all of the configured ports and URLs for the instance.

service pki-tps status
pki-tps (pid 8196) is running ...

    Unsecure Port              = http://server.example.com:7888/cgi-bin/so/enroll.cgi
                                 (ESC Security Officer Enrollment)
    Unsecure Port              = http://server.example.com:7888/cgi-bin/home/index.cgi
                                 (ESC Phone Home)
    Secure Clientauth Port     = http://server.example.com:7888/cgi-bin/sow/welcome.cgi
                                 (ESC Security Officer Workstation)
    Secure Clientauth Port     = https://server.example.com:7889/tus/
                                 (TPS Roles - Operator/Administrator/Agent)
    Secure Non-Clientauth Port = http://server.example.com:7889/cgi-bin/so/enroll.cgi
                                 (ESC Security Officer Enrollment)
    Secure Non-Clientauth Port = https://server.example.com:7890/cgi-bin/home/index.cgi
                                 (ESC Phone Home)

    PKI Instance Name:   pki-tps

    PKI Subsystem Type:  TPS

    Registered PKI Security Domain Information:
    ==========================================================================
    Name:  Example Domain
    URL:   https://server.example.com:9445
    ==========================================================================

12.1.4. Managing Subsystem Processes with chkconfig

Red Hat Enterprise Linux 5 has a tool called chkconfig which manages the automatic startup and shutdown settings for each process on the server. This means that when a system reboots, some services can be automatically restarted. chkconfig also defines startup settings for different run levels of the server. chkconfig is explained more in the Red Hat Enterprise Linux documentation, such as the Deployment Guide.

Certificate System subsystems can be managed by chkconfig, so this tool can set whether to restart subsystems automatically. By default, every Certificate System subsystem instance is turned off at every run level in the system, meaning instances must be started and stopped manually. This can be changed by resetting the configuration in chkconfig to on. For example, this automatically restarts Red Hat Administration Server, Directory Server, and the CA:

/sbin/chkconfig --level 2345 dirsrv-admin on
/sbin/chkconfig --level 2345 dirsrv on
/sbin/chkconfig --level 2345 pki-ca on

Make sure the subsystem is listed with the other services.

chkconfig --list | grep subsystem_name

To remove the subsystem from the start list, simply turn the level to off:

chkconfig --level 35 subsystem_name off

Red Hat Enterprise Linux also has a GUI console that can manage chkconfig settings.

Figure 12.1. chkconfig Settings

The start order of services is extremely important, or the subsystems will not function. For example, any local Administration Server and Directory Server instances used by the subsystems must be running before the subsystems can be started.

The default Certificate System chkconfig settings set a start and stop priority for all of the subsystems and their dependent services so that they start and stop in the proper order, as listed in Table 12.1, “Certificate System Processes and Their chkconfig Start Priority”. Processes with a low number for their start priority are started first, so Administration Server and Directory Server are started before any of the subsystem instances. Likewise, processes with a low number for their shutdown priority are shut down first, so the subsystem processes are stopped before the processes they depend on are stopped.

Table 12.1. Certificate System Processes and Their chkconfig Start Priority

Server	Process Name	Start Priority	Shutdown Priority
Administration Server	dirsrv-admin	21	79
Directory Server	dirsrv	21	79
Tomcat Server ^[a]	tomcat5	80	20
CA	pki-ca	81	19
DRM	pki-kra	82	18
OCSP	pki-ocsp	83	17
TKS	pki-tks	84	16
Apache^[a]	httpd	85	15
RA	pki-ra	86	14
TPS	pki-tps	87	13
^[a] This is a typical service example that is included for comparison with the subsystem chkconfig configuration. Web services in real deployments may have different settings.

12.1.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 Installation 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.

Edit the /etc/sudoers file; on Red Hat Enterprise Linux 5.6, this can be done using the visudo command:
```
# visudo
```

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: /sbin/service dirsrv *
%pkiadmin ALL = PASSWD: /sbin/service dirsrv-admin *

# For PKI instance management
%pkiadmin ALL = PASSWD: /usr/bin/pkicreate *
%pkiadmin ALL = PASSWD: /usr/bin/pkiremove *

# For PKI instance services
%pkiadmin ALL = PASSWD: /sbin/service CA_instance_name *
%pkiadmin ALL = PASSWD: /sbin/service DRM_instance_name *
%pkiadmin ALL = PASSWD: /sbin/service OCSP_instance_name *
%pkiadmin ALL = PASSWD: /sbin/service RA_instance_name *
%pkiadmin ALL = PASSWD: /sbin/service TKS_instance_name *
%pkiadmin ALL = PASSWD: /sbin/service TPS_instance_name *

IMPORTANT

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