WildFly 12 / JBoss EAP 7.1
For WildFly, deploy and install does not automatically configure the application server for you. Configure the application server according to instructions in the following sections.
For the oracle-specific parts in this guide we assume you have installed Oracle XE version 11g release 2 (can be downloaded from Oracle Database) on your machine and configured it to listen on port 1521
It is highly inadvisable to run your application using a root user due to risk of privilege escalation. Running your installation as root may lead root privileges being set on files which later WildFly is unable to read. It is instead recommended to run the installation with the same user as is running your application server.
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-2.2.3.jar wildfly_home/standalone/deployments/mariadb-java-client.jarIf you are using another type of database, copy the JDBC driver to the deployment directory and make note of the driver class and driver-name shown in the server log for later use when adding the DataSource. For example:
... INFO [org.jboss.as.connector.deployers.jdbc] (...) WFLYJCA0005: Deploying non-JDBC-compliant driver class org.postgresql.Driver (version 42.2)... INFO [org.jboss.as.connector.deployers.jdbc] (...) WFLYJCA0018: Started Driver service with driver-name = postgresql-jdbc3.jarIncrease 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, for example:
JAVA_OPTS="-Xms2048m -Xmx2048m -XX:MetaspaceSize=192M -XX:MaxMetaspaceSize=256m -Djava.net.preferIPv4Stack=true"Add DataSource
To add a data source for EJBCA to use, start JBoss (with bin/standalone.sh) and run the commands in JBoss CLI according to the examples below.
MariaDB/MySQL
For MariaDB/MySQL, run the following:
> 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;"> :reloadIf 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.
Oracle XE version 11g Release 2
For Oracle XE, run the following:
> wildfly_home/bin/jboss-cli.sh -c> data-source add --name=ejbcads --driver-name="ojdbc8.jar" --connection-url="jdbc:oracle:thin:@127.0.0.1:1521:XE" --jndi-name="java:/EjbcaDS" --use-ccm=true --driver-class="oracle.jdbc.driver.OracleDriver" --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 from dual"> :reloadConfigure WildFly Remoting
EJBCA needs to use JBoss Remoting for the EJBCA CLI to work. We configure it to use a separate port 4447 and remove any other dependency on remoting except for what EJBCA needs.
$ wildfly-12.0.0.Final/bin/jboss-cli.sh --connect/subsystem=remoting/http-connector=http-remoting-connector:write-attribute(name=connector-ref,value=remoting)/socket-binding-group=standard-sockets/socket-binding=remoting:add(port=4447,interface=management)/subsystem=undertow/server=default-server/http-listener=remoting:add(socket-binding=remoting,enable-http2=true)/subsystem=infinispan/cache-container=ejb:remove()/subsystem=infinispan/cache-container=server:remove()/subsystem=infinispan/cache-container=web:remove()/subsystem=ejb3/cache=distributable:remove()/subsystem=ejb3/passivation-store=infinispan:remove():reload()
Wait for the reload to complete by checking the server log or the result of :read-attribute(name=server-state) before continuing.
Configure Logging
Configure logging in JBoss to be able to dynamically change logging. For production systems, INFO log level is recommended:
/subsystem=logging/logger=org.ejbca:add(level=INFO)/subsystem=logging/logger=org.cesecore:add(level=INFO)To later enable DEBUG log level, if needed, use the following:
/subsystem=logging/logger=org.ejbca:write-attribute(name=level, value=DEBUG)/subsystem=logging/logger=org.cesecore:write-attribute(name=level, value=DEBUG)HTTP(S) Listener Configuration with 3-port Separation
The following covers HTTP(S) listener configuration with 3-port separation.
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 the reload to complete by checking the server log or the result of :read-attribute(name=server-state) before continuing.
Add New Interfaces and Sockets
To add new interfaces and sockets:
/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")/socket-binding-group=standard-sockets/socket-binding=httpspub:add(port="8442",interface="httpspub")/socket-binding-group=standard-sockets/socket-binding=httpspriv:add(port="8443",interface="httpspriv")Configure TLS
Configure TLS according to the following instructions.
Make sure the passwords in this section are correct, in order for the commands not to fail. In production the passwords should be changed to "real" passwords.
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:
/subsystem=elytron/key-store=httpsKS:add(path="keystore/keystore.jks",relative-to=jboss.server.config.dir,credential-reference={clear-text="serverpwd"},type=JKS)/subsystem=elytron/key-store=httpsTS:add(path="keystore/truststore.jks",relative-to=jboss.server.config.dir,credential-reference={clear-text="changeit"},type=JKS)/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,algorithm="SunX509",credential-reference={clear-text="serverpwd"})/subsystem=elytron/trust-manager=httpsTM:add(key-store=httpsTS)/subsystem=elytron/server-ssl-context=httpspub:add(key-manager=httpsKM,protocols=["TLSv1.2"])/subsystem=elytron/server-ssl-context=httpspriv:add(key-manager=httpsKM,protocols=["TLSv1.2"],trust-manager=httpsTM,need-client-auth=true,authentication-optional=false,want-client-auth=trueOptionally the "httpspriv" context can be configured with optional client certificate authentication using "need-client-auth=false,authentication-optional=true" instead.
Add HTTP(S) Listeners
To add HTTP(S) listeners:
/subsystem=undertow/server=default-server/http-listener=http:add(socket-binding="http", redirect-socket="httpspriv")/subsystem=undertow/server=default-server/https-listener=httpspub:add(socket-binding="httpspub", ssl-context="httpspub", max-parameters=2048)/subsystem=undertow/server=default-server/https-listener=httpspriv:add(socket-binding="httpspriv", ssl-context="httpspriv", max-parameters=2048):reload()HTTP Protocol Behavior Configuration
The following shows an example HTTP Protocol Behavior Configuration.
/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 are needed.
This will also ensure that the address in the EJBCA WS WSDL will match the hostname and port that the client used to access the server.
Optional Configurations
Remove Welcome Content and x-powered-by Header
/subsystem=undertow/server=default-server/host=default-host/location="\/":remove()/subsystem=undertow/server=default-server/host=default-host/filter-ref=server-header:remove()/subsystem=undertow/server=default-server/host=default-host/filter-ref=x-powered-by-header:remove()/subsystem=undertow/configuration=handler/file=welcome-content:remove()/subsystem=undertow/configuration=filter/response-header=server-header:remove()/subsystem=undertow/configuration=filter/response-header=x-powered-by-header:remove():reload()Redirect to Application for Unknown URLs
Known URLs starts with /ejbca/, /crls, /certificates or /.well-known/ (EST) for EJBCA according to the following example:
/subsystem=undertow/configuration=filter/rewrite=redirect-to-app:add(redirect=true,target="/ejbca/")/subsystem=undertow/server=default-server/host=default-host/filter-ref=redirect-to-app:add(predicate="method(GET) and not path-prefix(/ejbca/,'/crls','/certificates',/.well-known/)"):reload()Remove the ExampleDS DataSource
To optionally remove the ExampleDS DataSource:
/subsystem=ee/service=default-bindings:remove()data-source remove --name=ExampleDS:reload()Enable AJP Connector
Enabling the AJP connector is 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), as of EJBCA 6.6.3, 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
To add support for sending email (smtp), 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)