JBoss EAP 6 notes

  1. how to add / configure management users
  2. In JBoss EAP 6, a management user is a user who can connect to the JBoss administrative console and, e.g., manage deployments or view information about the pool usage of the various datasources.

    In JBoss EAP 6, coming from a fresh install, there is no default management user. You need to add one manually by invoking the script

    If you create the new user to be an "Management User" (I've never used "Application User"), the above will result in a row being added in file:
    … containing the username and the hashed password.

    The path to the file mgmt-users.properties is actually given in file

    in the management/security-realsm element.

    I typically maintain the admin passwords for the JBoss servers I install in path codes/cfa-my-servers.

    To remove a management user see this SO answer.

  3. some examples of the management CLI DSL used to apply overlays to deployed WARs
  4. deployment-overlay --name=foo --content=WEB-INF/web.xml=cxcaccount-web.xml --deployments=cxcaccount.war --action=add
    deployment-overlay --name=foo --action=remove
  5. how to configure TLS
  6. source #1, source #2, source #3, source #4, old but nice encyclopaedic description of the keytool, very thorough article on TLS/SSL and X.509 certificates (also saved as a PDF).

    Configuring TLS on JBoss consists of two steps:

    To create a public-private key pair and wrap the public key into an X.509 self-signed certificate you need to use a single incantation of the keytool. Here's an excerpt from a Makefile I used:

    	keytool -genkeypair -alias testkey \
                                -keyalg RSA \
                                -keysize 2048 \
                                -dname "CN=mperdikeas-jboss-server, OU=mperdikeas-laptop, O=mperdikeas, L=planet Earth, ST=N/A, C=N/A" \
                                -keypass changeit \
                                -validity 10000 \
                                -storetype JKS \
                                -keystore $(KEYSTORE_FILE) \
                                -storepass $(PASSWORD)
    NB:A gotcha is that for some reason, the keypass and the keystore password must be the same. This limitation stems not from the keytool but rather from a bug in the way JBoss uses the configuration options (discussed below). See here and here.

    Effectively, what the above incantation does is to create a JKS format keystore (the standard keystore format used by Java) and create (and name with an alias) an entry in that keystore consisting of a private key, a public key, and a self-signed certificate, (i.e. one in which the issuer is the same as the subject). Essentially, the public key is wrapped in a self-signed certificate and so the certificate chain contains only a single element (and this is why the browser will warn the user that this is an untrusted connection later on).

    Once the keystore file is created (with the above incantation), copy it to some location accessible from JBoss and change the web subsystem element to include an https connector. The connector references all three of: the keystore file, the key pair alias and the password (which as noted above is the same for both the store as a whole and the particular key). If you configured different store and key passwords browsers won't be able to connect to JBoss.

    <subsystem xmlns="urn:jboss:domain:web:1.5" default-virtual-server="default-host" native="false">
        <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http" max-post-size="0"/>
        <connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" enable-lookups="false" secure="true">
            <ssl name="ssl"
        <virtual-server name="default-host" enable-welcome-root="true">
            <alias name="localhost"/>
            <alias name="example.com"/>
            <access-log pattern="%h %l %u %t %r %s %b %{Referer}i %{User-Agent}i %S %T"/>

    Following the above, I was able to connect to my JBoss server via https. I had to connect to port 8445 as I had (in my socket-binding-group element in tne standalone-full.xml file) the following attribute:

    Also, since the self-signed certificate is obviously not considered secure I was presented with the usual warnings about this being unsecure.

  7. how to enable access logging
  8. source

    To enable access logging I recently had to add the following line:

    <access-log pattern="%h %l %u %t %r %s %b %{Referer}i %{User-Agent}i %S %T"/>
    … in the web submodule settings for the virtual host:
    <subsystem xmlns="urn:jboss:domain:web:1.5" default-virtual-server="default-host" native="false">
        <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http" max-post-size="0"/>
        <virtual-server name="default-host" enable-welcome-root="true">
            <alias name="localhost"/>
            <alias name="example.com"/>
            <access-log pattern="%h %l %u %t %r %s %b %{Referer}i %{User-Agent}i %S %T"/>

    By default, access logging is output under ${jboss.server.log.dir}/default-host i.e. under $JBOSS_HOME/standalone/log/default-home

  9. datasource max-pool-size and a database's max connections
  10. how to create a new user
  11. Go to the bin directory and execute script add-user.sh.

    … you will then observe a new or modified file mgmt-users.properties in the standalone/configuration directory containing the username and the hashed password.

  12. connection pool timeout parameters
  13. source

    Of the timeout parameters that appear below, the following are of particular importance:

    … alongside of course with the min-pool-size, max-pool-size which are confiugred for each pool.

    Also, prefill and use-strict-min may in some cases affect things. According to this paywalled link:

    When use-strict-min is set to true, the idle connection scan will not mark for closure any further connections once the min-pool-size (in-use + available connections) has been reached.
    In another article we read:
    By default, datasource connection pools are filled lazily. Set the value for the attribute to true to fill the pool with <min-pool-size> connections (defaults to 0) at start-up.

    Timeout parameters

    Parameter Description
    use-try-lock Uses tryLock() instead of lock(). This attempts to obtain the lock for the configured number of seconds, before timing out, rather than failing immediately if the lock is unavailable. Defaults to 60 seconds. As an example, to set a timeout of 5 minutes, set <use-try-lock>300</use-try-lock>.
    blocking-timeout-millis The maximum time, in milliseconds, to block while waiting for a connection. After this time is exceeded, an exception is thrown. This blocks only while waiting for a permit for a connection, and does not throw an exception if creating a new connection takes a long time. Defaults to 30000, which is 30 seconds.
    idle-timeout-minutes The maximum time, in minutes, before an idle connection is closed. The actual maximum time depends upon the idleRemover scan time, which is half of the smallest idle-timeout-minutes of any pool.
    set-tx-query-timeout Whether to set the query timeout based on the time remaining until transaction timeout. Any configured query timeout is used if no transaction exists. Defaults to false.
    query-timeout Timeout for queries, in seconds. The default is no timeout.
    allocation-retry The number of times to retry allocating a connection before throwing an exception. The default is 0, so an exception is thrown upon the first failure.
    allocation-retry-wait-millis How long, in milliseconds, to wait before retrying to allocate a connection. The default is 5000, which is 5 seconds.
    xa-resource-timeout If non-zero, this value is passed to method XAResource.setTransactionTimeout.

  14. configuring maximum POST size in JBoss EAP 6.2
  15. All web servers provide a way to limit the maximum post size as a plausible defence against DoS attacks. In the JBoss family of servers this is usually done in the configuration of the HTTP connector using an attribute named max-post-size (or maxPostSize in some older versions).

    E.g. I stumbled upon this web page that describes the configuration of the HTTP Connector FOR JBossWeb 7.0. Among the many attributes listed one finds max-post-size (a different, likely older, version of JBoss Web had this as maxPostSize). I tried both variants in JBoss EAP 6.2 and it was the max-post-size one that worked. JBoss EAP 6.2 is solid enough that if an unrecognized attribute is configured in the HTTP Connector, it helpfully explodes spectacularly during launch (rather than silently and insidiously ignoring the attribute).

    Finally, setting the value of this attribute to 0 translates to no limit at all (proceed at thy own risk). E.g. in my JBoss EAP 6.2 test server I have in my standalone-full.xml file:

          <subsystem xmlns="urn:jboss:domain:web:1.5" default-virtual-server="default-host" native="false">
            <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http" max-post-size="0"/>
            <virtual-server name="default-host" enable-welcome-root="true">
              <alias name="localhost"/>
              <alias name="example.com"/>

  16. JSP compilation problem when EAP 6.2 is run with a Java 8 interpreter
  17. I got a JSP compilation problem when running EAP 6.2 with a Java 8 runtime. This is what it looks like:

    The problem is treacherous as it occurs, not upon deployment of the WAR but rather when the JSP page is accessed (at which point JBoss attempts to compile it). It is further compounded by the fact that it may not show up if a compiled version of the JSP page happens to exist in JBoss cache (e.g. from a time when JBoss was run with a different, compatible, version of Java). In the latter case, to trigger the problem you will have to delete the standalone/tmp directory of JBoss.

    In my environment the default Java version was 1.8 hence I had this problem. To solve the problem you need to ensure that your JBoss is launched with Java 1.7. There's two ways to accomplish this:

    This compilation problem should not come as a total surprise as JBoss does not list Java 1.8 as a supported configuration for EAP 6.2 (see here).

  18. EAP 6.2 supported Java versions
  19. source

    As can be seen by the following table JBoss EAP 6.2 effectively does not support Java 8:
    Java Virtual Machine Version
    OpenJDK [2] 1.6
    1.8 ** support only with 6.4.1 update and above
    Oracle JDK 1.6
    1.8 ** support only with 6.3.3 update and above
    IBM JDK 1.6
    1.8 ** support only with 6.3.3 update and above
    HP JDK [3] 1.7
    Azul Zing JDK 1.6
    Azul Zulu 1.7

  20. how to gracefully shutdown EAP 6.2
  21. Execute the following in the bin directory:
    ./jboss-cli.sh --connect command=:shutdown
  22. how to verify or change the password for the management user in JBoss EAP 6.2
  23. a slightly different (but comprehensive) process on how to setup JBoss EAP 6.2
  24. configure JBoss EAP 6.2 to use OpenJDK 1.7 (instead of Oracle 1.8)
  25. groking logging in JBoss EAP 6.2 (and how to configure it)
  26. Writeup of what I did January 2017 in order to configure logging in JBoss EAP 6.2
  27. how to install a JDBC driver and configure a datasource
  28. Writeup of what I did December 2016 in order to configure a datasource in JBoss EAP 6
  29. basic sequence of actions for setting up clusting in JBoss EAP 6.0.0
    1. follow the instructions in Chapters 13.x and 14.1.9 of the JBoss Administration and Configuration guide (available from the official JBoss site
    2. setup JBoss EAP in two hosts (or virtual hosts) and declare one to be the master and the other to be the slave
    3. add a user, obtain 'secret' and configure it in the 'server identities' of that EAP instance (or the other?)
    4. do some stuff in JMS so that they can see each other
    5. establish that they can indeed see each other by looking at the logs