JBoss 7 GA / JBoss EAP 6

JBoss 7 / EAP 6 are the official well tested platforms for EJBCA 6.x and the majority of the development is done against JBoss.

To run JBoss EAP 6 with Java 8 you will at least need EAP 6.4.1+ (OpenJDK 8) or EAP 6.3.4 (OracleJDK 8).

Note that JBoss AS 7.1.1.GA will not work with Java 8.

JBoss 7/EAP 6 General Notes

Version JBoss AS 7.1.1.Final and EAP 6.1-6.4 (and possibly later ones) have been tested with EJBCA and works. However, note the following:

  • Start and connect with the JBoss 7/EAP6 cli like this:

    ./jboss-cli.sh
    connect
  • If you are having problems with HornetQ start-up, try switching to Java NIO with the following commands in JBoss CLI administration tool:

    /subsystem=messaging/hornetq-server=default:write-attribute(name=journal-type,value=NIO)
    :reload
  • You don't need to start/stop JBoss 7, deployment is done with a live system (in fact you should have the JBoss 7 running at all times).

JBoss 7/EAP 6 JDBC Drivers and Data Sources

In JBoss 7/EAP6 it is not enough to just drop the JAR archive with a database JDBC driver into the deployments directory. Instead you will have to perform the following steps (for MySQL):

  1. Create the necessary directories (relative to JBoss 7 base directory):
    On JBoss 7.1.1 or EAP 6.0:

    mkdir -p modules/com/mysql/main/

    On JBoss 7.2 or EAP 6.1/6.2:

    mkdir -p modules/system/layers/base/com/mysql/main/

    Or for MariaDB, mariadb-java-client-1.2.0.jar:

    mkdir -p modules/org/mariadb/main/

    On JBoss 7.2 or EAP 6.1/6.2:

    mkdir -p modules/system/layers/base/org/mariadb/main/

  2. Place the mysql.jar or mariadb.jar file in the directory you just created.

  3. Create, in the created directory, the JDBC module configuration file module.xml with the following contents (replace mysql.jar with the full name of your jar file for example mysql-connector-java-5.1.18-bin.jar):

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="com.mysql">
    <resources>
    <resource-root path="mysql.jar"/>
    </resources>
    <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
    </dependencies>
    </module>

    Or for MariaDB, mariadb-java-client-1.2.0.jar:

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.mariadb">
    <resources>
    <resource-root path="mariadb-java-client-1.2.0.jar"/>
    </resources>
    <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
    <module name="org.slf4j"/>
    </dependencies>
    </module>
  4. Register the driver by running the following two commands in the JBoss 7 CLI administration tool:

    /subsystem=datasources/jdbc-driver=com.mysql.jdbc.Driver:add(driver-name=com.mysql.jdbc.Driver,driver-class-name=com.mysql.jdbc.Driver,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource)
    :reload

    Or for MariaDB, mariadb-java-client-1.2.0.jar:

    /subsystem=datasources/jdbc-driver=org.mariadb.jdbc.Driver:add(driver-name=org.mariadb.jdbc.Driver,driver-module-name=org.mariadb,driver-xa-datasource-class-name=org.mariadb.jdbc.MySQLDataSource)
    :reload

For PostgreSQL you would use the following values instead:

mkdir -p modules/system/layers/base/org/postgresql/main/
 
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="org.postgresql">
<resources>
<resource-root path="postgresql-9.1-903.jdbc4.jar"/>
</resources>
<dependencies>
<module name="javax.api"/>
<module name="javax.transaction.api"/>
</dependencies>
</module>
 
/subsystem=datasources/jdbc-driver=org.postgresql.Driver:add(driver-name=org.postgresql.Driver,driver-module-name=org.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
:reload

Datasources are normally created automatically by EJBCA during deployment and installation. Here we describe how to create a datasource in JBoss7/EAP6 for reference. The examples are for installing a MariaDB datasource using the jboss-cli with the driver installed as described above.

A normal datasource:

data-source add --name=ejbcads --driver-name="org.mariadb.jdbc.Driver" --connection-url="jdbc:mysql://127.0.0.1:3306/ejbca" --jndi-name="java:/EjbcaDS" --use-ccm=true --driver-class="org.mariadb.jdbc.Driver" --user-name="ejbca" --password="ejbca" --validate-on-match=true --background-validation=false --prepared-statements-cache-size=50 --share-prepared-statements=true --min-pool-size=5 --max-pool-size=150 --pool-prefill=true --transaction-isolation=TRANSACTION_READ_COMMITTED --check-valid-connection-sql="select 1;"

A no-tx / jta="false" datasource (OCSP publisher and Unid):

data-source add --name=unidds --jta=false --driver-name="org.mariadb.jdbc.Driver" --connection-url="jdbc:mysql://127.0.0.1:3306/unid" --jndi-name="java:/UnidDS" --use-ccm=true --driver-class="org.mariadb.jdbc.Driver" --user-name="uniduser" --password="unidpass" --validate-on-match=true --background-validation=false --prepared-statements-cache-size=50 --share-prepared-statements=true --min-pool-size=5 --max-pool-size=150 --pool-prefill=true --transaction-isolation=TRANSACTION_READ_COMMITTED --check-valid-connection-sql="select 1"

images/s/en_GB/7202/8bb4a7d7a43e6723fe7875221f32b3124c55e6e1/_/images/icons/emoticons/warning.png Note that select 1 must be different for DB2 and Oracle.

images/s/en_GB/7202/8bb4a7d7a43e6723fe7875221f32b3124c55e6e1/_/images/icons/emoticons/warning.png For JBoss EAP 6, you need to add --enabled=true to the commands above in order for the datasource to be enabled.

JBoss 7 and EAP 6 Logging

Logging can be configured using the CLI:

/system-property=org.jboss.as.logging.per-deployment:add(value=false) /subsystem=logging/logger=org.ejbca:add /subsystem=logging/logger=org.ejbca:write-attribute(name=level, value=DEBUG) /subsystem=logging/logger=org.cesecore:add /subsystem=logging/logger=org.cesecore:write-attribute(name=level, value=DEBUG)

The per-deployment feature was added in EAP 6.0.0 and is not present in GA 7.1.

In JBoss EAP 6 you can also configure a completely custom Log4J configuration by:

  • Do _not_ set 'org.jboss.as.logging.per-deployment' to false above, by default it's value is true, but you can also set it manually to true.

  • Create a $EJBCA_HOME/conf/log4j-jbosseap6.xml, you can use log4j-jbosseap6.xml.sample as a template. Set paths to the desired log files.

  • Redeploy with 'ant clean deployear'.

JBoss 7/EAP 6 PKCS11

JBoss 7/EAP 6 by default isolates away most sun classes. As of version 6.6.3, EJBCA configures JBoss to expose these classes (sun/security/pkcs11/wrapper) by using a jboss-deployment-structure.xml. This makes configuration in modules/sun/jdk/main/module.xml (JBoss 7.1/EAP6.0) or modules/system/layers/base/sun/jdk/main/module.xml (JBoss EAP 6.1 and later and WildFly) not needed. For previous versions of EJBCA, refer to the documentation for the respective release

JBoss 7/EAP 6 CMP TCP

Note that the TCP transport of the CMP protocol is deprecated in the standard draft. TCP transport may be removed in future EJBCA releases.

JBoss 7/EAP 6 isolates away most sun classes. This means that the CMP TCP library is not able to get system properties. The needed classes can be made available by editing the file modules/sun/jdk/main/module.xml (JBoss 7.1/EAP6.0) or modules/system/layers/base/sun/jdk/main/module.xml (JBoss 7.2/EAP6.1)) and adding the following package to the list of system export paths:

<path name="sun/security/action"/>

JBoss 7/EAP 6 URI Encoding and WSDL Location

This section is a reference section, the configuration here are done automatically in JBoss 7 by the ant deploy command in EJBCA.

The following configuration is recommended to be able to use international characters during certificate and CRL download:

/system-property=org.apache.catalina.connector.URI_ENCODING:add(value=UTF-8)
/system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:add(value=true)

On JBoss 7.1.x (and EAP 6.0.x) the WSDL location gets incorrectly generated by default (JBoss bind address, plain http). This will cause the WS client to not work. This can be corrected using the JBoss CLI (the change requires a reload of JBoss server):

/subsystem=webservices:write-attribute(name=wsdl-host, value=jbossws.undefined.host)
:reload

to force the location to be generated with info from the WSDL request. If this is not done you will get SSL errors about missing client certificate, or "HTTP 302 Moved Temporarily" errors when running the WS client.

JBoss Mail TLS Configuration

There are at least two ways to use TLS for SMTP connection:

  • SMTP STARTTLS

  • TLS required

The first method can be configured with the setting mail.smtp.starttls.enable in conf/mail.properties. Since mail configuration is done differently in different versions of JBoss we only provide guidance for the second version. There are two options that might be needed:

  • mail.smtp.ssl.enable=true
  • mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

For JBoss 7/EAP 6 they should be set using the JBoss command line admin tool.

JBoss Service Timer Persistence

EJBCA uses EJB timers to run services regularly (if you have services configured). By default JBoss persists timers in an internal, in memory, database. If you run services very often this can under some circumstances fill up the memory causing the server to be non-operational due to out of memory errors.

EJBCA does not need persistent timers since they are initialized during startup. Therefore it is recommended to run JBoss with non-persistent timers, something that can be configured.

JBoss 7/EAP6 configuration:

JBoss 7 does not use the in memory database to persist timers, but instead stores them in jboss/standalone/data/timer-service-data/ejbca.ejbca-ejb.ServiceSessionBean. This is supposed to ensure that it will not fill up the memory as it did in JBoss 5.
If persisted timers needs to be removed in JBoss 7 the directory jboss/standalone/data/timer-service-data can simply be deleted.

JBoss7/EAP6 Deployment Timeout

In the case the deployment fails to complete within 60 seconds it will fail. You can increase this timeout with:

/subsystem=deployment-scanner/scanner=default:write-attribute(name=deployment-timeout,value=300)

Unless there is a clear reason why this takes longer than 60 seconds (for example an HSM waiting for human input, or a very slow server, check that database indexes are applied and that your network and any used DNS server is fully operational.

JBoss 7 and Oracle JDK BC Issues

In EJBCA 6.0.4 ECA-3371 solved the issue of deploying with OracleJDK.