Chapter 12. Troubleshooting Installation and Cloning

This chapter covers some of the more common installation and migration issues that are encountered when installing Certificate System.
12.1. Installation
Q: I cannot see any Certificate System packages or updates.
Q: The init script returned an OK status, but my CA instance does not respond. Why?
Q: I want to customize the subject name for the CA signing certificate, but do not see a way to do this using the pkispawn interactive install mode.
Q: I want to set different certificate validity periods and extensions for my root certificate authority — but I do not see a way to set it using pkispawn.
Q: I am seeing an HTTP 500 error code when I try to connect to the web services pages after configuring my subsystem instance.
12.2. Java Console
Q: I cannot open the pkiconsole and I am seeing Java exceptions in stdout.
Q: I tried to run pkiconsole, and I got Socket exceptions in stdout. Why?
Q: I attempt to start the console, and the system prompts me for my user name and password. After I enter these credentials, the console fails to appear.

12.1. Installation

Q:
I cannot see any Certificate System packages or updates.
A:
Verify that your system is correctly registered to the Red Hat subscription management service, a valid subscription is assigned, and the Certificate System repository is enabled. For details, see Section 6.6, “Attaching a Red Hat Subscription and Enabling the Certificate System Package Repository”.
Q:
The init script returned an OK status, but my CA instance does not respond. Why?
A:
This should not happen. Usually (but not always), this indicates a listener problem with the CA, but it can have many different causes. To see what errors have occurred, examine the journal log by running the following command:
journalctl -u pki-tomcatd@instance_name.service
Alternatively, examine the debug log files at /var/log/pki/instance_name/subsystem_type/debug.
One situation is when there is a PID for the CA, indicating the process is running, but that no listeners have been opened for the server. This would return Java invocation class errors in the catalina.out file:
Oct 29, 2010 4:15:44 PM org.apache.coyote.http11.Http11Protocol init
INFO: Initializing Coyote HTTP/1.1 on http-9080
java.lang.reflect.InvocationTargetException
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at
sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:64)
        at
sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:615)
        at org.apache.catalina.startup.Bootstrap.load(Bootstrap.java:243)
        at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:408)
Caused by: java.lang.UnsatisfiedLinkError: jss4
This could mean that you have the wrong version of JSS or NSS. The process requires libnss3.so in the path. Check this with this command:
ldd /usr/lib64/libjss4.so
If libnss3.so is not found, set the correct classpath in the /etc/sysconfig/instance_name configuration file. Then restart the CA using the systemctl restart pki-tomcatd@instance_name.service command.
Q:
I want to customize the subject name for the CA signing certificate, but do not see a way to do this using the pkispawn interactive install mode.
A:
To do this, a configuration file representing delta links to the /etc/pki/default.cfg file is required. See the pkispawn(8) and pki_default.cfg(5) man pages.
Q:
I want to set different certificate validity periods and extensions for my root certificate authority — but I do not see a way to set it using pkispawn.
A:
You cannot currently do this using pkispawn. However, there is a way to edit the certificate profiles used by pkispawn to generate the root CA certificates.

Important

You must do this before running pkispawn to create a new CA instance.
  1. Back up the original CA certificate profile used by pkispawn.
    cp -p /usr/share/pki/ca/conf/caCert.profile /usr/share/pki/ca/conf/caCert.profile.orig
  2. Open the CA certificate profile used by the configuration wizard.
    vim /usr/share/pki/ca/conf/caCert.profile
  3. Reset the validity period in the Validity Default to whatever you want. For example, to change the period to two years:
    2.default.class=com.netscape.cms.profile.def.ValidityDefault
    2.default.name=Validity Default
    2.default.params.range=7200
  4. Add any extensions by creating a new default entry in the profile and adding it to the list. For example, to add the Basic Constraint Extension, add the default (which, in this example, is default #9):
    9.default.class=com.netscape.cms.profile.def.BasicConstraintsExtDefault
    9.default.name=Basic Constraint Extension Constraint
    9.default.params.basicConstraintsCritical=true
    9.default.params.basicConstraintsIsCA=true
    9.default.params.basicConstraintsPathLen=2
    Then, add the default number to the list of defaults to use the new default:
    list=2,4,5,6,7,8,9
  5. Once the new profile is set up, then run pkispawn to create the new CA instance and go through the configuration wizard.
Q:
I am seeing an HTTP 500 error code when I try to connect to the web services pages after configuring my subsystem instance.
A:
This is an unexpected generic error which can have many different causes. Check in the journal, system, and debug log files for the instance to see what errors have occurred. This lists a couple of common errors, but there are many other possibilities.

Error #1: The LDAP database is not running.

If the Red Hat Directory Server instance use for the internal database is not running, then you cannot connect to the instance. This will be apparent in exceptions in the journal file that the instance is not ready:
java.io.IOException: CS server is not ready to serve.
        com.netscape.cms.servlet.base.CMSServlet.service(CMSServlet.java:409)
        javax.servlet.http.HttpServlet.service(HttpServlet.java:688)
The Tomcat logs will specifically identify the problem with the LDAP connection:
5558.main - [29/Oct/2010:11:13:40 PDT] [8] [3] In Ldap (bound) connection pool
to host ca1 port 389, Cannot connect to LDAP server. Error:
netscape.ldap.LDAPException: failed to connect to server
ldap://ca1.example.com:389 (91)
As will the instance's debug log:
[29/Oct/2010:11:39:10][main]: CMS:Caught EBaseException
Internal Database Error encountered: Could not connect to LDAP server host
ca1 port 389 Error netscape.ldap.LDAPException: failed to connect to
server ldap://ca1:389 (91)
        at com.netscape.cmscore.dbs.DBSubsystem.init(DBSubsystem.java:262)

Error #2: A VPN is blocking access.

Another possibility is that you are connecting to the subsystem over a VPN. The VPN must have a configuration option like Use this connection only for resources on its network enabled. If that option is not enabled, then the journal log file for the instance's Tomcat service shows a series of connection errors that result in the HTTP 500 error:
May 26, 2010 7:09:48 PM org.apache.catalina.core.StandardWrapperValve invoke
SEVERE: Servlet.service() for servlet services threw exception
java.io.IOException: CS server is not ready to serve.
        at com.netscape.cms.servlet.base.CMSServlet.service(CMSServlet.java:441)
        at javax.servlet.http.HttpServlet.service(HttpServlet.java:803)
        at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:269)
        at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:188)
        at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:210)
        at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:172)
        at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:127)
        at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:117)
        at org.apache.catalina.valves.AccessLogValve.invoke(AccessLogValve.java:542)
        at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:108)
        at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:151)
        at org.apache.coyote.http11.Http11Processor.process(Http11Processor.java:870)
        at org.apache.coyote.http11.Http11BaseProtocol$Http11ConnectionHandler.processConnection(Http11BaseProtocol.java:665)
        at org.apache.tomcat.util.net.PoolTcpEndpoint.processSocket(PoolTcpEndpoint.java:528)
        at org.apache.tomcat.util.net.LeaderFollowerWorkerThread.runIt(LeaderFollowerWorkerThread.java:81)
        at org.apache.tomcat.util.threads.ThreadPool$ControlRunnable.run(ThreadPool.java:685)
	at java.lang.Thread.run(Thread.java:636)

12.2. Java Console

Q:
I cannot open the pkiconsole and I am seeing Java exceptions in stdout.
A:
This probably means that you have the wrong JRE installed or the wrong JRE set as the default. Run alternatives --config java to see what JRE is selected. Red Hat Certificate System requires OpenJDK 1.7.
Q:
I tried to run pkiconsole, and I got Socket exceptions in stdout. Why?
A:
This means that there is a port problem. Either there are incorrect SSL/TLS settings for the administrative port (meaning there is bad configuration in the server.xml) or the wrong port was given to access the admin interface.
Port errors will look like the following:
NSS Cipher Supported '0xff04'
java.io.IOException: SocketException cannot read on socket
        at org.mozilla.jss.ssl.SSLSocket.read(SSLSocket.java:1006)
        at org.mozilla.jss.ssl.SSLInputStream.read(SSLInputStream.java:70)
        at
com.netscape.admin.certsrv.misc.HttpInputStream.fill(HttpInputStream.java:303)
        at
com.netscape.admin.certsrv.misc.HttpInputStream.readLine(HttpInputStream.java:224)
        at
com.netscape.admin.certsrv.connection.JSSConnection.readHeader(JSSConnection.java:439)
        at
com.netscape.admin.certsrv.connection.JSSConnection.initReadResponse(JSSConnection.java:430)
        at
com.netscape.admin.certsrv.connection.JSSConnection.sendRequest(JSSConnection.java:344)
        at
com.netscape.admin.certsrv.connection.AdminConnection.processRequest(AdminConnection.java:714)
        at
com.netscape.admin.certsrv.connection.AdminConnection.sendRequest(AdminConnection.java:623)
        at
com.netscape.admin.certsrv.connection.AdminConnection.sendRequest(AdminConnection.java:590)
        at
com.netscape.admin.certsrv.connection.AdminConnection.authType(AdminConnection.java:323)
        at
com.netscape.admin.certsrv.CMSServerInfo.getAuthType(CMSServerInfo.java:113)
        at com.netscape.admin.certsrv.CMSAdmin.run(CMSAdmin.java:499)
        at com.netscape.admin.certsrv.CMSAdmin.run(CMSAdmin.java:548)
        at com.netscape.admin.certsrv.Console.main(Console.java:1655)
Q:
I attempt to start the console, and the system prompts me for my user name and password. After I enter these credentials, the console fails to appear.
A:
Make sure the user name and password you entered are valid. If so, enable the debug output and examine it.
To enable the debug output, open the /usr/bin/pkiconsole file, and add the following lines:
============================================
${JAVA} ${JAVA_OPTIONS} -cp ${CP} -Djava.util.prefs.systemRoot=/tmp/.java -Djava.util.prefs.userRoot=/tmp/java com.netscape.admin.certsrv.Console -s instanceID -D 9:all -a $1
----------
note: "-D 9:all" is for verbose output on the console.
============================================