EJBCA - Open Source PKI Certificate Authority
Search ejbca.org on Google:
EJBCA 6.8.0 Enterprise (r26040)

EJBCA Installation

EJBCA is a fully functional Certificate Authority built in Java. Based on JEE6 technology it constitutes a robust, high performance and component based CA. Both flexible and platform independent, EJBCA can be used standalone or integrated in any JEE6 application.

The EJBCA Homepage can be found at https://www.ejbca.org. Information about contacting the EJBCA team, contributing to EJBCA, etc can be found through the Homepage.

EJBCA is completely written in Java and should as such run on any platform where a JEE server runs. Development and testing is performed on Linux and Windows platforms.

Definitions and conventions

In this document we use X_HOME to indicate the file system directory location of application X. For example EJBCA_HOME is the home directory of the unzipped EJBCA distribution. APPSRV_HOME is used interchangeably with for example JBOSS_HOME and is the home directory of the application server.

Security

Security is discussed below in the chapter about configuration in the User Guide and in Security.

Please take a minute to thoroughly consider the security implications and make sure you know what you are doing when you are setting up a CA.

Whether running on Linux or Windows, you should consider using multiple levels of firewalls. The first level of firewall could be a host based firewall such as IPTables in Linux, or a similar approach on Windows. See the Security document for information about ports that are used.

Don't forget to configure your application server for security! See security. Security is CRITICAL for a CA.

Upgrade

See EJBCA_HOME/doc/RELEASE_NOTES and UPGRADE for information about upgrading from an earlier version of EJBCA.

Ubuntu quick start

Note
The current installation procedures for JBoss 7 / EAP 6 uses the JBoss CLI to configure the application server. The JBoss CLI turns out not to be well suited for automated deploys however, so functions can break. For example if the machine has too few cores CLI connections will mysteriously terminate and report errors.

This section provides a fast way to get installed and running for a test using Ubuntu Linux. To get more information about configuration options etc (there are plenty), you should follow the regular Installation guide below.

This quick start guide assumes EJBCA 6.5, JBoss EAP 6.4 and Java 8, but other version should also be possible to use by just replacing the versions. We also assume installation is made in a user account with username "user". In your environment simply replace user with the username you are using.
Note that the quick install will create a H2 database as ~/ejbcadb. If you run this multiple times, delete this file in order to remove the old database.

Note
The quick start guide uses the JBoss built in database, H2. This is not a database you want to use in production, so don't use these quick start settings for a production installation.
  1. Install Ubuntu 16.04 server x64, default config, only OpenSSH server selected (or other Ubuntu of your choice, for example Ubuntu Desktop).
    • Add user with username 'user' during install. The path /home/user means the user's home directory below.
    • Make sure that networking and hostnames work correctly, i.e. hostname and ip are configured in /etc/hosts.
  2. Open a new terminal "ejbca".
  3. Install needed software from Ubuntu repositories.
    • sudo apt-get install default-jdk-headless ant ant-optional unzip
  4. Install software not in Ubuntu repositories, JBoss EAP 6.4 and EJBCA 6.5.0.
    • unzip jboss-eap-6.4.0.zip
    • unzip ejbca_ce_6_5_0.zip
  5. Configure EJBCA so it can find the application server (JBoss).
    • echo "appserver.home=/home/user/jboss-eap-6.4" >> ejbca_ce_6_5_0/conf/ejbca.properties
  6. Open new terminal "jboss" and start JBoss.
    • jboss-eap-6.4/bin/standalone.sh
  7. Build and deploy EJBCA to JBoss.
    • cd ejbca_ce_6_5_0
    • ant deploy (just press enter if questions show up)
    • (now wait a little for JBoss to reload)
  8. Run installation (in terminal "ejbca") to create initial Management CA and TLS keystores.
    • ant install (choose all default values)
    Note: If ant install fails with errors this is typically due to deployment or start of JBoss that did not complete successfully. You will need to look in the server logs to find out why it will not start correctly in your environment, See the Troubleshooting section for more information.
  9. Go back to terminal "jboss" and restart JBoss.
    • ctrl-c
    • jboss-eap-6.4/bin/standalone.sh
  10. Copy /home/user/ejbca_ce_6_5_0/p12/superadmin.p12 to admin desktop machine and import in web browser (keystore password is ejbca by default).
  11. Open URL https://server:8443/ejbca, where 'server' is the servers name/ip. You will see a warning that the server side TLS certificate is not trusted, but if you ignore this warning you are prompted to connect using your imported P12.

Done!

After installation do not forget to secure your installation as described in securing JBoss.

RedHat Enterprise Linux quick start

This section provides a fast way to get installed and running for a test using RedHat Enterprise Linux. To get more information a about configuration options etc (there are plenty), you should follow the regular Installation guide below.

This quick start guide makes the same assumptions and uses the same procedures as the Ubuntu quick start guide.

  1. Install RHEL 7.2 x86_64, this guide used a DVD install disk
    • In the graphical installation selection, under 'Software selection' choose 'Basic Server'
    • under 'Add-ons for the chosen environment' choose 'Java platform'
    • don't forget to 'Configure Network'
    • create a user (except root) to run JBoss, here we create a user called 'user'
  2. Log in as root to complete the installation
    • Enable EJBCA ports in the RHEL firewall, ports 8080, 8442 and 8443
    sudo firewall-cmd --add-port=8443/tcp --permanent
    sudo firewall-cmd --add-port=8442/tcp --permanent
    sudo firewall-cmd --add-port=8080/tcp --permanent
    
    • vi /etc/yum.repos.d/install_dvd.repo
    [INSTALL_DVD] 
    name=Installation DVD 
    baseurl=file:///media 
    enabled=1 
    gpgcheck=0 
    
    • mount /dev/cdrom /media/
    • yum install ant
    • umount /media/
    This will install OpenJDK and apache ant.
  3. Log out from root account and log in as 'user' in a new terminal 'ejbca'.
  4. After this follow the same steps, 4-11 as in the 'Ubuntu quick start' above.

Done!

After installation do not forget to secure your installation as described in securing JBoss.

Installation guide

If you want to get started real quick, and you're using Ubuntu Linux, you can follow the Ubuntu or RedHat quick start guide above. This guide describes how to install on the most well supported application server JBoss AS. EJBCA might however also run on Glassfish and Weblogic, but your mileage may vary (see further below for details).

Prerequisites

Note
EJBCA makes use of strong crypto and keystore passwords longer than 7 characters. For this to work you must install the 'Unlimited Strength Jurisdiction Policy Files' for JDK. The policy files can be found at the same place as the JDK download at Oracle. The text "Using exportable cryptography" is shown on the first page in the Admin GUI if you fail to install this package. Further information on this can be found in the Oracle documentation on the JCE.

Needed to build and run are:

  • JDK 7 or 8, OpenJDK or Oracle JDK. If available OpenJDK is recommended.
  • Only if using OracleJDK - Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for your JDK.
  • JBoss Application Server 7.1.x or later or JBoss EAP 6 or later (download, note that the absolute latest may not always be tested). Or WildFly 9 or later.
  • Apache Ant 1.8 or later to build (download). Note that javascript support may be needed in ant for some components.

Windows/Unix: When we describe command line commands below we use unix notation, e.g. 'ejbca.sh' for the executable command files. The same command files are available for windows as cmd-files, e.g. 'ejbca.cmd.'

If you are unsure what version of EJBCA you are running, type 'ant ejbcaversion' in the EJBCA_HOME directory.

Configure

*** Configuration files ***

The configuration of EJBCA that can not be configured in the Admin GUI is located in properties files in the conf directory. All properties are documented in sample files and to configure an option you copy the sample file, for example copy conf/ejbca.properties.sample to conf/ejbca.properties and configure conf/ejbca.properties. You should at least familiarize your self with the options in conf/install.properties, conf/ejbca.properties and conf/cesecore.properties. Most options, except those in install.properties can be changed after installation.

*** EJBCA configuration ***

1) Copy conf/install.properties.sample to conf/install.properties, conf/ejbca.properties.sample to conf/ejbca.properties and conf/cesecore.properties.sample to conf/cesecore.properties Customize if needed. The default values works fine for a test installation.

You must configure 'appserver.home' in ejbca.properties to point to your application server directory. You find examples of how to do this in ejbca.properties.sample.
This makes libraries from the application server available to EJBCA during the build.

If you are only testing EJBCA at this stage and is not setting up a production environment, you can skip the rest of this step. There are default configuration options, that should work in a test environment, for everything.

  • Customize the CA properties in conf/ejbca.properties if you need to do so. For production use you need to do this, don't forget to edit passwords to be secure and secret. Keep conf/ejbca.properties as secret as possible. DO NOT forget the passwords, if you need to re-install the software sometime.
  • To use a hard ca token from start change ca.tokentype, ca.tokenpassword and ca.tokenproperties in install.properties. You also need to add the appropriate values to the ca.tokenproperties file for the HSM. Read the HSM documentation for the right values.
  • To put the initial superadmin certificate on a smartcard, set superadmin.batch=false in web.properties. Enroll from public web after the installation is complete, as you would with any other smartcard user. Username is "superadmin" and password is superadmin.password from web.properties.
  • If you are deploying on JBoss EAP you probably want to look at the property 'jboss.config' as well, since 'production' may be the default server to start on JBoss EAP (depends on your configuration).
Do the same with other configuration files that you might want to customize. The default values often works fine and is a safe bet if you are unsure. Most options are well documented in the sample files.
  • Customize the database in conf/database.properties if needed. But easiest thing is to keep the default as it is, it will use the JBoss embedded HSQLDB and everything will be easier for you. For production use you should use a real database instead of the embedded one.

*** Configure application server ***

Due to differences, and bugs, in different application servers you have to configure your application server with some settings, and EJBCA with server specific settings.
See the application servers section.

Note
On JBoss 7 or EAP 6 you need to enable logging in order to see anything in the log files. See JBoss 7 and EAP 6 logging for instructions.
*** Considerations ***

When everything is prepared, there are a few things to configure before starting your applications and running everything in a production environment.

In a production environment you should use something like the following structure:

  1. Go through the install process creating an ManagementCA. Use a simple DN. This CA should only used to issue the administrator certificates. Not published in LDAP. If you want to use an HSM for this CA, see the documentation in the configuration file conf/ejbca.properties.sample.
  2. Once installed, create all your REAL CAs using the admin-GUI. Now you can use the certificate profiles etc that you like. These certificates can be published in LDAP. See doc/howto/HOWTO-multiplecas.txt for example of a detailed configuration guide.

In a production environment you should use something else than the default Hypersonic database that comes with JBoss for the reasons:

  1. Hypersonic database is in-memory, which means that over time it will consume more memory. If a large number of certificates is issued, it will become an issue after a while.
  2. Hypersonic does not support full SQL, in particular ALTER statements. When a new version of EJBCA is released we can not create scripts that updates the database if some tables changed. This will make upgrades much much harder.

For information about installing JDBC drivers for other databases, see the document 'doc/howto/HOWTO-database.txt' in the distribution.

Install

Note that the installation must be done with a user with privileges to write to APPSRV_HOME and sub directories. Running the deploy and install commands as described will also configure the application server with data sources and web configuration automatically. If deploying on WildFly, you should instead follow that guide to manually configure data sources and web.

1) Set the property 'appserver.home' in conf/ejbca.properties to where your JBoss is installed, examples:

appserver.home=/opt/jboss-7.1.1.Final

Also make sure the right java tools (javac/keytool) are available in your system PATH, ie. /usr/local/jdk1.7.0_25/bin.

2) Open a console (terminal) and start JBoss. You can start JBoss with the normal command 'standalone.sh' (JBoss 7/EAP 6/WildFly) from APPSRV_HOME/bin. You should see JBoss picking up everything and deploying the ear without errors.

3) Open a console and type:

ant deploy

it will compile and build EJBCA and deploy it to JBoss, as well as automagically create data sources and mail service. You will be prompted to enter the value for database.password if it has not already been defined in database.properties.

4) Type:

ant install

The command will generate all certificates, keys, etc needed to run with an initial CA, and configure TLS in the servlet container to use the generated keystore and truststore files (which are also copied in the process). You will find admin keys in ${ejbca.home}/p12. (do not delete those files!)
The command 'ant install' is only run once, when the CA is first installed. It creates lots of things in the database, and can not be run again (it will give an error if you try).

  • tomcat.jks is for the Servlet container (don't bother with it)
  • truststore.jks is for the Servlet container (don't bother with it)
  • superadmin.p12 should be imported in your browser, that's your administration certificate.

Note
Instead of creating an initial Admin CA and issuing administrator certificates from that, you can install using administrator certificates from an already existing external CA. See Administrators issued by external CAs for more information. This would replace step 4-8, but instead require other steps.

5) Restart JBoss (Ctrl+C if you run JBoss in the foreground in a terminal)

6) Import the certificate from EJBCA_HOME/p12/superadmin.p12 in your web browser. This is the super administrators certificate used to access the admin GUI. Other administrators with specific privileges can be created later on. The default password for superadmin.p12 is ejbca, and is configured in web.properties.

7) Go to https://localhost:8443/ejbca/ to access the Admin GUI, or http://localhost:8080/ejbca for the public web pages.

If you create other CAs that you want to add as acceptable CAs in the SSL server configuration, or if you renew the CA certificate, you can install any CA certificate in the SSL server configuration afterwards with the following command:

ant -Dca.name="My CA Name" javatruststore

What this does in the background is that it adds the CA certificate to p12/truststore.jks and copies this file to JBOSS_HOME/server/default/conf/keystore, where the SSL keystores are located.

You must stop and start JBoss after doing this.

Upgrade and reconfigure

When upgrading EJBCA, read doc/UPGRADE for instructions related to different versions, and upgrading between them. Upgrading withing patch verson (i.e. 6.0.3->6.04) are usually plug-in upgrades (you have to transfer your configuration though).

When you upgrade, or simply change a configuration setting in properties files, you do not need to fully re-install EJBCA, or re-configure the application server. You simply want to deploy a new EJBCA application (ejbca.ear) to the application server. This is done with a simple command:

ant clean deployear

No need to run a full 'ant deploy'. This command cleans previous build and builds a new ejbca.ear file that is deployed (to JBoss). No re-configuration of the application server (datasource, TLS etc) is done.

For easy upgrades, keeping personal configuration between versions, you should consider using the ejbca-custom feature.

Application servers

EJBCA should run on any on any JEE5 compliant application server in theory. In reality it doesn't, because different application servers have different tweaks for the standard. It is not enough to pass JEE validation in order to run on all application servers.

  1. JBoss 7.1.1.Final / JBoss EAP 6: Works well.
  2. WildFly 10 / JBoss EAP 7: Works well.
  3. WildFly 8, 9: Works well.
  4. JBoss 5.1.0.GA / JBoss EAP 5.1: JEE5, only supported in older version of EJBCA.
  5. Glassfish 3.1.1: Not supported yet.
  6. Glassfish 2.1.1: Works with older versions of EJBCA (before v6).
  7. WebLogic: Does not work. Used to work with earlier versions of EJBCA.
  8. WebSphere: Does not work. Has worked with one version of EJBCA in the past.
  9. Geronimo: Not supported yet.
  10. JoNaS: Not supported yet.
  11. TomEE+: Not tested yet.
  12. Payara: Not tested yet.

JBoss 7 GA / JBoss EAP 6

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

To be able to run JBoss EAP 6 with Java 8 you will at least EAP 6.4.1+ (OpenJDK 8) or EAP 6.3.4 (OracleJDK 8). 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, EAP 6.1-6.4 (and possibly later ones) has been tested with EJBCA, and it should work. There's a couple of caveats and notes you should be aware of:

  • Start and connect with the JBoss 7/EAP6 cli like this:
    ./jboss-cli.sh
    connect
    
  • If you're having problem 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;"

(note that 'select 1' must be different for DB2 and Oracle)
(note that for JBoss EAP 6 you need to add --enabled=true to the commands above, or else the datasource will not 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. 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.

*** 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 configurations 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 ofmemory 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.

WildFly 10 / JBoss EAP 7

EJBCA 6.x compiles, deploys and runs with WildFly 10 (release following 6.3.1.1). JBoss EAP 7 is based on Wildfly 10 and these instructions applies for EAP 7 as well. Note that JDK 8 is required.

For WildFly, deploy and install does not automagically configure the Application server for you, instead we supply configuration instructions for the Application server for you to follow. This makes your configuration robust, and possible to script on your own.

Note
Run your installation without mixing root and user accounts as this may lead to root privileges being set on files, which later WildFly is unable to read. Therefore the advice is to run everything as your "wildfly" user.
*** Add database driver ***

Add MariaDB database driver by hot-deploying it into the Deployment directory. This will be picked up by WildFly and deployed so we can create a datasource straight away. You can use a generic name, without version number, in order to get a generic 'driver-name' for the data source command.

>cp mariadb-java-client-1.2.0.jar wildfly_home/standalone/deployments/mariadb-java-client.jar

If you are using another type of database, copy the JDBC driver to the deployments-directory and make note of the driver class and driver-name shown in the server log and for later use when adding the DataSource. E.g.

... INFO  [org.jboss.as.connector.deployers.jdbc] (...) WFLYJCA0005: Deploying non-JDBC-compliant driver class org.postgresql.Driver (version 9.2)
... INFO  [org.jboss.as.connector.deployers.jdbc] (...) WFLYJCA0018: Started Driver service with driver-name = postgresql-jdbc3.jar
*** Increase allowed memory usage ***

By default, only 512MiB of heap is allowed. Edit wildfly_home/bin/standalone.conf to increase this to a more suitable value, e.g.

   JAVA_OPTS="-Xms2048m -Xmx2048m -Djava.net.preferIPv4Stack=true"
*** Create database ***

Before creating the datasource in the following step, create your database. In MariaDB the command to create the database, matching the datasource in the next step, and add privileges to connect to the database is:

 
$ mysqladmin -u root -p create ejbca
$ mysql -u root -p
mysql> CREATE DATABASE ejbca CHARACTER SET utf8 COLLATE utf8_general_ci;
mysql> GRANT ALL PRIVILEGES ON ejbca.* TO 'ejbca'@'localhost' IDENTIFIED BY 'ejbca';

You should define secure passwords for your database in production. You can also improve the security by limiting access to tables. See for Database privileges for more information about that.

Note
If you don't set utf8 as character set EJBCA may not start because of index limitations if using the default charset 'utf8mb4' in some configurations of MariaDB/MySQL. It will result in an error 'Specified key was too long; max key length is 767 bytes'.
Note
For InnoDB in some configurations the "binlog_format" defaults to "statement". Running EJBCA requires is to be set to "row". binlog_format=row
*** Add datasource ***

Add data source for EJBCA to use.

Start JBoss and run two commands in JBoss CLI. Note that "-jindi-name" is linked to the database.properties value (default value in this example).

> wildfly_home/bin/jboss-cli.sh -c
> data-source add --name=ejbcads --driver-name="mariadb-java-client.jar" --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;"
> :reload

If you are using another type of database, adapt the statement above with the correct driver-name, connection-url, driver-class and check-valid-connection-sql.

*** Configure WildFly Remoting ***

EJBCA needs to use JBoss Remoting for the EJBCA CLI to work. We configure it to use a separate port (start by removing any old configuration if it exists).

/subsystem=remoting/http-connector=http-remoting-connector:remove
/subsystem=remoting/http-connector=http-remoting-connector:add(connector-ref="remoting",security-realm="ApplicationRealm")
/socket-binding-group=standard-sockets/socket-binding=remoting:add(port="4447")
/subsystem=undertow/server=default-server/http-listener=remoting:add(socket-binding=remoting)
:reload
*** Configure logging ***

Configure logging in JBoss, to be able to dynamically change logging (DEBUG enabled in this example).

/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)
*** Remove existing TLS and HTTP configuration ***

Run the following commands in JBoss CLI to remove existing TLS and HTTP configuration (just to be safe).

/subsystem=undertow/server=default-server/http-listener=default:remove
/subsystem=undertow/server=default-server/https-listener=https:remove
/socket-binding-group=standard-sockets/socket-binding=http:remove
/socket-binding-group=standard-sockets/socket-binding=https:remove
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

*** Deploy EJBCA ***

Finally build and deploy the EJBCA (application ear file) to WildFly, without touching any WildFly configuration, by running the following EJBCA command.

Before running deployear below, don't forget to point to your application server by setting APPSRV_HOME, and configure your database in conf/database.properties.

Run the following commands at the regular command prompt in EJBCA_HOME.

ant clean deployear
*** Run install ***

Run installation part of EJBCA creating the initial Management CA (for TLS and Super administrator), as well as TLS and Superadmin keystores.

Note
If you are moving an existing installation that already have TLS keystores available, this step is not needed.

ant runinstall
*** Deploy TLS keystores to WildFly ***

After the install, TLS keystores have been created. Run this command to copy them to wildfly_home/standarlone/config/keystore.

ant deploy-keystore
*** Configure TLS ***
Note
Make sure the passwords in this section are correct, or the commands will fail. In production the passwords should be changed to "real" passwords.

The run the following commands in JBoss CLI (jboss-cli.sh -c) to configure TLS.

Add interfaces, using 0.0.0.0 to make it available for the world:

/interface=http:add(inet-address="0.0.0.0")
/interface=httpspub:add(inet-address="0.0.0.0")
/interface=httpspriv:add(inet-address="0.0.0.0")
/socket-binding-group=standard-sockets/socket-binding=http:add(port="8080",interface="http")
/subsystem=undertow/server=default-server/http-listener=http:add(socket-binding=http)
/subsystem=undertow/server=default-server/http-listener=http:write-attribute(name=redirect-socket, value="httpspriv")
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

Configure identities and socket bindings:

Update the keystore alias to match httpsserver.hostname in web.properties. Also, update the keystore-password for keystore.jks to match httpsserver.password and the keystore-password for truststore.jks to match java.truststore in web.properties.

/core-service=management/security-realm=SSLRealm:add()
/core-service=management/security-realm=SSLRealm/server-identity=ssl:add(keystore-path="${jboss.server.config.dir}/keystore/keystore.jks", keystore-password="serverpwd", alias="localhost")
/core-service=management/security-realm=SSLRealm/authentication=truststore:add(keystore-path="${jboss.server.config.dir}/keystore/truststore.jks", keystore-password="changeit")
/socket-binding-group=standard-sockets/socket-binding=httpspriv:add(port="8443",interface="httpspriv")
/socket-binding-group=standard-sockets/socket-binding=httpspub:add(port="8442", interface="httpspub")

Restart the application server completely. Wait for it to finish start up by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

/subsystem=undertow/server=default-server/https-listener=httpspriv:add(socket-binding=httpspriv, security-realm="SSLRealm", verify-client=REQUIRED)
/subsystem=undertow/server=default-server/https-listener=httpspub:add(socket-binding=httpspub, security-realm="SSLRealm")
:reload

Finalize Wildfly configurations

/system-property=org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH:add(value=true)
/system-property=org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH:add(value=true)
/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)
/subsystem=webservices:write-attribute(name=wsdl-host, value=jbossws.undefined.host)
/subsystem=webservices:write-attribute(name=modify-wsdl-address, value=true)
:reload

If you are using OCSP GET requests, setting URI encoding and allowing encoding for Query and backslash above is needed.

Note
WildFly will most likely get confused at this step, and will need a restart with ":shutdown(restart=true)".
*** Optional: Enable AJP connector ***

Only needed if you run an Apache front-end in front of WildFly.

/subsystem=undertow/server=default-server/ajp-listener=ajp-listener:add(socket-binding=ajp, scheme=https, enabled=true)
*** Optional: Add support for PKCS#11 (HSMs) ***

WildFly by default isolates away most sun classes. EJBCA configures JBoss/WildFly to expose these classes (sun/security/pkcs11/wrapper) by using a jboss-deployment-structure.xml. This makes configuration in modules/system/layers/base/sun/jdk/main/module.xml not needed.

*** Optional: Add support for sending email ***

If you need support for sending email (smtp) you can configure EjbcaMail with:

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=ejbca-mail-smtp:add(port="993", host="my.mail.server")
/subsystem=mail/mail-session="java:/EjbcaMail":add(jndi-name=java:/EjbcaMail, from=noreply@mymail)
/subsystem=mail/mail-session="java:/EjbcaMail"/server=smtp:add(outbound-socket-binding-ref=ejbca-mail-smtp, tls=true, username=smtpuser, password=smtppassword)
:reload

WildFly 8

EJBCA 6.x compiles, deploys and runs with WildFly 8 and WildFly 9 (release following 6.3.1.1).

For WildFly deploy and install does not automagically configure the Application server for you, instead we supply configuration instructions for the Application server for you to follow.

*** Add database driver ***

Add MariaDB database driver by hot-deploying it into the Deployment directory. This will be picked up by WildFly and deployed so we can create a datasource straight away. You can use a generic name, without version number, in order to get a generic 'driver-name' for the data source command.

>cp mariadb-java-client-1.2.0.jar wildfly_home/standalone/deployments/mariadb-java-client.jar
*** Increase allowed memory usage ***

By default, only 512MiB of heap and 256MiB perm gen space is allowed. Edit wildfly_home/bin/standalone.conf to increase this to a more suitable value, e.g.

   JAVA_OPTS="-Xms2048m -Xmx2048m -XX:MaxPermSize=384m -Djava.net.preferIPv4Stack=true"
*** Add datasource ***

Add data source for EJBCA to use.

Start JBoss and run two commands in JBoss CLI.

> wildfly_home/bin/jboss-cli.sh -c
> data-source add --name=ejbcads --driver-name="mariadb-java-client.jar" --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;"
*** Configure JBoss Remoting ***

EJBCA needs to use JBoss Remoting for the EJBCA CLI to work. We configure it to use a separate port (start by removing any old configuration if it exists).

/socket-binding-group=standard-sockets/socket-binding=remoting:remove
/subsystem=undertow/server=default-server/http-listener=remoting:remove
/subsystem=remoting/http-connector=http-remoting-connector:remove

/subsystem=remoting/http-connector=http-remoting-connector:add(connector-ref="remoting",security-realm="ApplicationRealm")
/socket-binding-group=standard-sockets/socket-binding=remoting:add(port="4447")
/subsystem=undertow/server=default-server/http-listener=remoting:add(socket-binding=remoting)
:reload
*** Configure logging ***

Configure logging in JBoss, to be able to dynamically change logging (DEBUG enabled in this example).

/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)
*** Remove existing TLS and HTTP configuration ***

Run the following commands in JBoss CLI to remove existing TLS and HTTP configuration (just to be safe).

/core-service=management/security-realm=SSLRealm/authentication=truststore:remove
/core-service=management/security-realm=SSLRealm/server-identity=ssl:remove
/core-service=management/security-realm=SSLRealm:remove
/socket-binding-group=standard-sockets/socket-binding=httpspub:remove
/subsystem=undertow/server=default-server/https-listener=httpspub:remove
/socket-binding-group=standard-sockets/socket-binding=httpspriv:remove
/subsystem=undertow/server=default-server/https-listener=httpspriv:remove
/socket-binding-group=standard-sockets/socket-binding=http:remove
/subsystem=undertow/server=default-server/http-listener=http:remove
/subsystem=undertow/server=default-server/http-listener=default:remove
/system-property=org.apache.catalina.connector.URI_ENCODING:remove
/system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:remove
/interfaces=/interface=http:remove
/interfaces=/interface=httpspub:remove
/interfaces=/interface=httpspriv:remove
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

*** Deploy EJBCA ***

Finally build and deploy the EJBCA (application ear file) to WildFly, without touching any WildFly configuration, by running the following EJBCA command.

ant clean deployear
*** Run install ***

Run installation part of EJBCA creating the initial Management CA (for TLS and Super administrator), as well as TLS and Superadmin keystores.

Note
If you are moving an existing installation that already have TLS keystores available, this step is not needed.

ant runinstall
*** Configure TLS ***

Copy keystores to WildFly:

ant deploy-keystore

The run the following commands in JBoss CLI to configure TLS (again removing any old configuration first just to be safe).

/interfaces=/interface=http:add(inet-address="0.0.0.0")
/interfaces=/interface=httpspub:add(inet-address="0.0.0.0")
/interfaces=/interface=httpspriv:add(inet-address="0.0.0.0")
/socket-binding-group=standard-sockets/socket-binding=http:add(port="8080",interface="http")
/subsystem=undertow/server=default-server/http-listener=http:add(socket-binding=http)
/subsystem=undertow/server=default-server/http-listener=http:write-attribute(name=redirect-socket, value="httpspriv")
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

/core-service=management/security-realm=SSLRealm:add()
/core-service=management/security-realm=SSLRealm/server-identity=ssl:add(keystore-path="${jboss.server.config.dir}/keystore/keystore.jks", keystore-password="serverpwd", alias="localhost")
/core-service=management/security-realm=SSLRealm/authentication=truststore:add(keystore-path="${jboss.server.config.dir}/keystore/truststore.jks", keystore-password="changeit")
/socket-binding-group=standard-sockets/socket-binding=httpspriv:add(port="8443",interface="httpspriv")
/subsystem=undertow/server=default-server/https-listener=httpspriv:add(socket-binding=httpspriv, security-realm="SSLRealm", verify-client=REQUIRED)
/socket-binding-group=standard-sockets/socket-binding=httpspub:add(port="8442", interface="httpspub")
/subsystem=undertow/server=default-server/https-listener=httpspub:add(socket-binding=httpspub, security-realm="SSLRealm")
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

/system-property=org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH:add(value=true)
/system-property=org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH:add(value=true)
/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)
/subsystem=webservices:write-attribute(name=wsdl-host, value=jbossws.undefined.host)
/subsystem=webservices:write-attribute(name=modify-wsdl-address, value=true)
:reload

If you are using OCSP GET requests, setting URI encoding and allowing encoding for Query and backslash above is needed.

Note
WildFly will most likely get confused at this step, and will need a restart with ":shutdown(restart=true)".
*** Optional: Enable AJP connector ***

Only needed if you run an Apache front-end in front of WildFly.

/subsystem=undertow/server=default-server/ajp-listener=ajp-listener:add(socket-binding=ajp, scheme=https, enabled=true)
*** Optional: Add support for PKCS#11 (HSMs) ***

WildFly by default isolates away most sun classes. EJBCA configures JBoss/WildFly to expose these classes (sun/security/pkcs11/wrapper) by using a jboss-deployment-structure.xml. This makes configuration in modules/system/layers/base/sun/jdk/main/module.xml not needed.

WildFly 9

USing WildFly 9 instead of WildFly 8 you only have to replace the sections 'Remove existing TLS and HTTP configuration' and 'Configure TLS' with the below section.

*** Remove existing TLS and HTTP configuration ***

Run the following commands in JBoss CLI to remove existing TLS and HTTP configuration (just to be safe).

/core-service=management/security-realm=SSLRealm/authentication=truststore:remove
/core-service=management/security-realm=SSLRealm/server-identity=ssl:remove
/core-service=management/security-realm=SSLRealm:remove
/socket-binding-group=standard-sockets/socket-binding=httpspub:remove
/subsystem=undertow/server=default-server/https-listener=httpspub:remove
/socket-binding-group=standard-sockets/socket-binding=httpspriv:remove
/subsystem=undertow/server=default-server/https-listener=httpspriv:remove
/socket-binding-group=standard-sockets/socket-binding=http:remove
/subsystem=undertow/server=default-server/http-listener=http:remove
/subsystem=undertow/server=default-server/http-listener=default:remove
/system-property=org.apache.catalina.connector.URI_ENCODING:remove
/system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:remove
/interface=http:remove
/interface=httpspub:remove
/interface=httpspriv:remove
:reload
*** Configure TLS ***

Copy keystores to WildFly:

ant deploy-keystore

The run the following commands in JBoss CLI to configure TLS (again removing any old configuration first just to be safe).

/interface=http:add(inet-address="0.0.0.0")
/interface=httpspub:add(inet-address="0.0.0.0")
/interface=httpspriv:add(inet-address="0.0.0.0")
/socket-binding-group=standard-sockets/socket-binding=http:add(port="8080",interface="http")
/subsystem=undertow/server=default-server/http-listener=http:add(socket-binding=http)
/subsystem=undertow/server=default-server/http-listener=http:write-attribute(name=redirect-socket, value="httpspriv")
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

/core-service=management/security-realm=SSLRealm:add()
/core-service=management/security-realm=SSLRealm/server-identity=ssl:add(keystore-path="${jboss.server.config.dir}/keystore/keystore.jks", keystore-password="serverpwd", alias="localhost")
/core-service=management/security-realm=SSLRealm/authentication=truststore:add(keystore-path="${jboss.server.config.dir}/keystore/truststore.jks", keystore-password="changeit")
/socket-binding-group=standard-sockets/socket-binding=httpspriv:add(port="8443",interface="httpspriv")
/subsystem=undertow/server=default-server/https-listener=httpspriv:add(socket-binding=httpspriv, security-realm="SSLRealm", verify-client=REQUIRED)
/socket-binding-group=standard-sockets/socket-binding=httpspub:add(port="8442", interface="httpspub")
/subsystem=undertow/server=default-server/https-listener=httpspub:add(socket-binding=httpspub, security-realm="SSLRealm")
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

/system-property=org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH:add(value=true)
/system-property=org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH:add(value=true)
/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)
/subsystem=webservices:write-attribute(name=wsdl-host, value=jbossws.undefined.host)
/subsystem=webservices:write-attribute(name=modify-wsdl-address, value=true)
:reload

If you are using OCSP GET requests, setting URI encoding and allowing encoding for Query and backslash above is needed.

Note
WildFly will most likely get confused at this step, and will need a restart with ":shutdown(restart=true)".
*** Optional: Add support for sending email ***

If you need support for sending email (smtp) you can configure EjbcaMail with:

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=ejbca-mail-smtp:add(port="993", host="my.mail.server")
/subsystem=mail/mail-session="java:/EjbcaMail":add(jndi-name=java:/EjbcaMail, from=noreply@mymail)
/subsystem=mail/mail-session="java:/EjbcaMail"/server=smtp:add(outbound-socket-binding-ref=ejbca-mail-smtp, tls=true, username=smtpuser, password=smtppassword)
:reload

Glassfish

Note
EJBCA 6.x has never been officially deployed on Glassfish yet. The below notes can work as hints for anyone interested working on Glassfish support.

EJBCA 4.x has been tested with Glassfish v2.1.1.

Don't forget to install 'Unlimited Strength Jurisdiction Policy Files' for Java.

*** Using Derby database (Glassfish built in) ***

  1. Start JavaDB and create the database instance.
      cd $APPSRV_HOME
      bin/asadmin start-database
      export DERBY_HOME=$APPSRV_HOME/javadb
      javadb/bin/ij   
      ij> connect 'jdbc:derby://localhost:1527/ejbca;create=true';
      ij> quit;
    
  2. Start the application server:
    bin/asadmin start-domain
    
    The default user/password for the web console is admin/adminadmin.
    Access the Glassfish admin console at http://127.0.0.1:4848/.

  3. Create a connection pool for your database. In the admin console this is done in Resources->JDBC->Connection Pools.
    When adding a Derby Pool use values: Name=EjbcaPool, Type=javax.sql.DataSource, Vendor=JavaDB.
    Properties: user=APP, password=APP, DatabaseName=ejbca
    Save and use the Ping-button for the pool. If you get 'Parameter wrong for this method : off', go to Additional Properties and delete 'Ssl'.
    Command line alternative:
        bin/asadmin create-jdbc-connection-pool --datasourceclassname org.apache.derby.jdbc.ClientDataSource --property user=APP:password=APP:DatabaseName=ejbca:ServerName=localhost:port=1527 EjbcaPool
        
  4. Create a datasource called jdbc/EjbcaDS, in the admin console this is done in Resources->JDBC->JDBC Resources. Use the connection pool you just created.
    Command line alternative:
        bin/asadmin create-jdbc-resource --connectionpoolid EjbcaPool jdbc/EjbcaDS
        
    If security is enabled you have to add "--user admin --passwordfile pwd.txt" as command line parameters where pwd.txt contains 'AS_ADMIN_PASSWORD=adminadmin'.

*** Using MySQL database ***

  1. Start the database and create the MySQL database "ejbca". Grant privileges to the "ejbca" user with password "ejbca_pwd" (don't use this password in production!)
  2. Copy the MySQL JDBC JAR to APPSRV_HOME/lib/
  3. Start the application server:
    asadmin start-domain
    
  4. Add the Connection Pool and DataSource from the Glassfish Admin Console (see "Derby") or use command line:
    asadmin create-jdbc-connection-pool --datasourceclassname com.mysql.jdbc.jdbc2.optional.MysqlDataSource --property user=ejbca:password=ejbca_pwd:DatabaseName=ejbca:ServerName=localhost:port=3306 EjbcaPool
    asadmin create-jdbc-resource --connectionpoolid EjbcaPool jdbc/EjbcaDS
    

*** Configure EJBCA ***

  1. Edit conf/ejbca.properties, you should at least set appserver.home
  2. Edit conf/log4j-glassfish.xml, to configure EJBCA logging.
  3. Edit conf/database.properties, you should at least set the database settings for your chosen database. Derby and MySQL has been tested with Glassfish.
  4. Edit conf/web.properties, you should set desired values and also the http/s ports (default 8080 and 8181) for your installation.

*** Deploy and setup ***

  1. If your appserver does not requires a password for deployment (asadmin deploy) you can build and deploy EJBCA with
    ant clean
    ant bootstrap
    
    or otherwise with an additional step.
    ant clean
    ant
    asadmin deploy --precompilejsp $EJBCA_HOME/dist/ejbca.ear
    
    You can check that everything was ok in APPSRV_HOME/domains/domain1/logs/server.log.

  2. Install EJBCA
    ant runinstall
    
  3. Configure SSL in Glassfish
    Configuration->HTTP Service->HTTP Listeners->http-listener-2, SSL tab
    • Client Authentication: Enabled
    • Certificate Nickname: s1as (get alias name by running 'keytool -list -v -keystore $APPSRV_HOME/domains/domain1/config/keystore.jks', password changeit)
    • SSL3: Enabled
    • Ciphers Suite: All
    Add CA certificate to cacerts file:
             cd $EJBCA_HOME
             keytool -exportcert -keystore p12/truststore.jks -file p12/managementca.der -storepass changeit -alias managementca
             
    Install the CA certificate in the application servers truststore.
    On Glassfish open source:
             keytool -delete -keystore  $APPSRV_HOME/domains/domain1/config/cacerts.jks -alias managementca -storepass changeit
                 (will fail if this hasn't been done before)
             keytool -importcert -keystore $APPSRV_HOME/domains/domain1/config/cacerts.jks -file p12/managementca.der -alias managementca -storepass changeit
             
    On Glassfish Enterprise:
    • cd $APPSRV_HOME/domains/domain1/config
    • /usr/sfw/bin/certutil -A -n managementca -t "p,p,p" -i p12/managementca.der -d .
    • verify that managementca has been added to the store with '/usr/sfw/bin/certutil -L -d .'.

  4. (Optional) Replace the SSL keystore and truststore with default passwords.
    In a production environment you probably want to change the keystore passwords, to do this you must edit both the http-listener and the IIOP-listeners.
        cd $EJBCA_HOME
        cp p12/tomcat.jks p12/keystore.jks
        keytool -list -keystore p12/keystore.jks -storepass serverpwd
            Read the alias for the "PrivateKeyEntry" e.g. 'localhost'.
        keytool -keypasswd -keystore p12/keystore.jks -alias localhost -storepass serverpwd -keypass serverpwd -new changeit
        keytool -storepasswd -keystore p12/keystore.jks -storepass serverpwd -new changeit
        keytool -changealias -keystore p12/keystore.jks -alias localhost -destalias s1as -keypass changeit -storepass changeit
        cp p12/keystore.jks $APPSRV_HOME/domains/domain1/config/keystore.jks
        
  5. Restart server
        asadmin stop-domain
        asadmin start-domain
        
  6. Access protected EJBCA pages
    Import $EJBCA_HOME/p12/superadmin.p12 in your browser and go to url:
    https://127.0.0.1:8181/ejbca/
    You can now click "Administration" to get to the admin-GUI.

  7. (Optional) Change how often an EJBCA Service can run: Configuration -> EJB Container -> EJB Timer Service -> Minimum Delivery Interval: 1000. Restart application server.
    This can also be changed using the "minimum-delivery-interval-in-millis" attribute in the domain.xml-file when the appserver isn't running.
  8. (Optional) Apply workaround to enable redeployment without application server restart: See ECA-1887.

*** Glassfish Ubuntu package ***

The above instructions are tested on the official release from Glassfish's homepage. We had this report from a user of the glassfish package on ubuntu.

I had to modify the following to make it work with the Ubuntu 9.04 glassfish package.

1. Modify /usr/bin/asadmin
   #GF_DOMAIN_DIR=$HOME/glassfishv2
   GF_DOMAIN_DIR=/var/lib/glassfishv2/domains
2. Set APPSRV_HOME to /usr/share/glassfishv2
The Ubuntu package has the domains and binaries separated. When following the install instructions, when you do anything with the domain you have to point to /var/lib/glassfishv2/[directory] instead of $APPSRV_HOME/[directory].

JBoss 7 and EAP 6 debug logging

Debug logging for EJBCA can be configured dynamically using the jboss-cli. One of the benefits of using the jboss-cli to configure logging is that debug logging can be enable and disabled dynamically while running. If you have not configured logging in standalone.xml manually, and not configured custom logging, you can easily enable debug logging for EJBCA with the following commands:

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

Once this is done you can easily switch between INFO and DEBUG logging by setting the appropriate level:

/subsystem=logging/logger=org.ejbca:write-attribute(name=level, value=INFO)
/subsystem=logging/logger=org.cesecore:write-attribute(name=level, value=INFO)

Transaction timeouts

In some cases, either if you have a slow machine or very large data sets, some common operations can take a long time to complete. The default transaction timout of the application servers may then not be enough.

Normally CRL generation and other known long running operation already have larger transaction timout from configuration in

modules/cesecore-ejb/src/META-INF/jboss-ejb3.xml
modules/ejbca-ejb/resources/jboss-ejb3.xml

JBoss 7 / EAP 6

/subsystem=transactions/:write-attribute(name=default-timeout,value=600)

Deployment reference

Ant target shortlist

To deploy and install EJBCA the first time (from clean database):

  • ant deploy
  • ant install

To upgrade EJBCA, i.e. just deploy a new ejbca.ear file:

  • ant deployear

To (re)configure TLS, i.e. configure TLS ports and deploy TLS keystores:

  • ant web-configure
  • ant deploy-keystore

To (re)configure database, i.e. deploy EjbcaDS datasource:

  • ant deploy-datasource

Files deployed

Here we describe shortly which files/functions are copied/touched during various ant targets that are called. These targets only modifies files automatically on platforms where auto-configure is supported, but it will give an indication as well for other platforms what configuration steps are needed.

Below shows JBoss (configuration) files updated. For JBoss 7/EAP6 there is only one unified configuration file and all configuration is done using the JBoss 7 command line interface.

ant deploy

  • ant deploy-datasource
    • standalone/configuration/standalone.xml
  • ant deploy-service
    • standalone/configuration/standalone.xml
  • ant deployear
    • deploy/ejbca.ear

ant install

  • ant runinstall (creates initial Management CA and web keystores)
  • ant web-configure
  • ant deploy-keystore

ant web-configure

  • standalone/configuration/standalone.xml

ant deploy-keystore

  • conf/keystore/tomcat.jks
  • conf/keystore/truststore.jks

ant deploy-datasource

  • standalone/configuration/standalone.xml
  • standalone/configuration/standalone.xml

ant deploy-service

  • standalone/configuration/standalone.xml