Skip to main content
Pentaho Documentation

Prepare JBOSS connections and web app servers

Parent article

If you are using JBoss, both JDBC and JNDI connection information must be specified.

This checklist for JBoss connection tasks will help you verify that you have completed all items needed before starting the Pentaho Server.

Audience: Only IT administrators who know where data is stored, how to connect to it, details about the computing environment, and how to use the command line to issue commands for Microsoft Windows or Linux. You should also know how to install a database and a web application server.

Install JDBC driver as a module in JBoss

In JBoss, JDBC driver information is stored in a module, which is an XML file that you create.

You must download the JDBC driver software component to the correct directory, then create module.xml files for each database.

The JDBC drivers reference has a list of supported drivers.

Step 1: Create module file for Pentaho Repository database

You need to create a file for the database that hosts the Pentaho Repository (either PostgreSQL, MySQL, or Oracle), as well as for HSQLDB.

  1. Locate the pentaho/server/pentaho-server/<your jboss installation directory>/modules/system/layers/base/org folder and create one of the following paths for the database on which you are hosting the Pentaho Repository.

    • PostgreSQL: postgresql/main
    • MySQL: mysql/main
    • Oracle: oracle/main
    • MS SQL Server: sqlserver/main
  2. Create these two paths in the same directory.

    • HSQLDB: hsqldb/main
    • H2: h2/main
  3. Download the supported JDBC driver for your Pentaho Repository database to the directory that you just created. The JDBC drivers reference has a list of supported drivers.

  4. Within that directory, perform the following steps.

    1. Use an editor to create a text file named module.xml.
    2. Copy the appropriate code into the module.xml file, then modify it so that the name of the JDBC driver you just downloaded appears.
    3. Save and close the module.xml file.
    Repository TypeModule code
    PostgreSQL
    <?xml version="1.0" encoding="UTF-8"?>
        <module xmlns="urn:jboss:module:1.0" name="org.postgresql">
            <resources>
                <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
            </resources>
            <dependencies><module name="javax.api"/></dependencies>
        </module>
    
    MySQL
    <?xml version="1.0" encoding="UTF-8"?>
        <module xmlns="urn:jboss:module:1.0" name="org.mysql">
            <resources>
                <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
            </resources>
            <dependencies><module name="javax.api"/></dependencies>
        </module>
    
    Oracle
    <?xml version="1.0" encoding="UTF-8"?>
        <module xmlns="urn:jboss:module:1.0" name="org.oracle">
            <resources>
                <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
            </resources>
            <dependencies><module name="javax.api"/></dependencies>
        </module>
    
    MS SQL Server
    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0"
    name="org.sqlserver">
    <resources>
    <resource-root path="[Name of JDBC
    Jar You Downloaded Here]"/>
    </resources>
    <dependencies><module name="javax.
    api"/></dependencies>
    </module>
    

Step 2: Create module file for HSQL database

You will need to create a module file for the HSQL database.

CautionThe version of HSQLDB used should be 2.3.2.

Procedure

  1. Download the supported JDBC driver for HSQLDB and place it in the hsqldb/main directory.

  2. In the hsqldb/main directory, create a text file named module.xml.

  3. Copy this code into the module.xml file, then modify it so that the name of the JDBC driver you just downloaded appears in the resource-root path.

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.hsqldb">
    <resources>
    <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
    </resources>
    <dependencies><module name="javax.api"/></dependencies>
    </module>
    
  4. Save and close the module.xml file.

Step 3: Create module file for H2 database

You need to create a module file for the H2 database.

  1. In the h2/main directory, create a text file named module.xml.

  2. Copy this code into the module.xml file, then modify it so that the name of the JDBC driver you just downloaded appears in the resource-root path.

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.h2">
    <resources>
    <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
    </resources>
    <dependencies><module name="javax.api"/></dependencies>
    </module>
  3. Save and close the module.xml file.

Step 4: Define JNDI database connection information in JBoss

JNDI is used to specify port, driver, user name, and password information for the Audit and Quartz databases that are housed on your Pentaho Repository database.

This section shows you how to define your JNDI database connection information.
CautionIf you have a different database than PostgreSQL, or if you are using a different port, password, user, driver class information, or IP address, make sure that you adjust the examples in this section to match the ones in your environment.

Procedure

  1. Copy the pentaho-style.war and pentaho.war files into the pentaho/server/pentaho-server/<your jboss installation directory>/standalone/deployment directory, or verify that the files are already there, as in PostgreSQL.

  2. Locate the pentaho/server/pentaho-server/<your jboss installation directory>/standalone/configuration/standalone.xml file and open it with a text editor.

  3. Insert these lines after the definition for ExampleDS data source.

    <datasource jndi-name="java:jboss/datasources/Hibernate" pool-name="hibpool" enabled="true" jta="true" use-java-context="true" use-ccm="true">
                            <connection-url>
                                jdbc:postgresql://localhost:5432/hibernate
                            </connection-url>
                            <driver-class>
                                org.postgresql.Driver
                            </driver-class>
                            <driver>
                                org.postgresql
                            </driver>
                            <pool>
                                <prefill>
                                    false
                                </prefill>
                                <use-strict-min>
                                    false
                                </use-strict-min>
                                <flush-strategy>
                                    FailingConnectionOnly
                                </flush-strategy>
                            </pool>
                            <security>
                                <user-name>
                                    hibuser
                                </user-name>
                                <password>
                                    password
                                </password>
                            </security>
                        </datasource>
                        <datasource jndi-name="java:jboss/datasources/Quartz" pool-name="quartzpool" enabled="true" jta="true" use-java-context="true" use-ccm="true">
                            <connection-url>
                                jdbc:postgresql://localhost:5432/quartz
                            </connection-url>
                            <driver-class>
                                org.postgresql.Driver
                            </driver-class>
                            <driver>
                                org.postgresql
                            </driver>
                            <pool>
                                <prefill>
                                    false
                                </prefill>
                                <use-strict-min>
                                    false
                                </use-strict-min>
                                <flush-strategy>
                                    FailingConnectionOnly
                                </flush-strategy>
                            </pool>
                            <security>
                                <user-name>
                                    pentaho_user
                                </user-name>
                                <password>
                                    password
                                </password>
                            </security>
                        </datasource>
                        <datasource jndi-name="java:jboss/datasources/Audit" pool-name="auditpool" enabled="true" jta="true" use-java-context="true" use-ccm="true">
                            <connection-url>
                                jdbc:postgresql://localhost:5432/hibernate
                            </connection-url>
                            <driver-class>
                                org.postgresql.Driver
                            </driver-class>
                            <driver>
                                org.postgresql
                            </driver>
                            <pool>
                                <prefill>
                                    false
                                </prefill>
                                <use-strict-min>
                                    false
                                </use-strict-min>
                                <flush-strategy>
                                    FailingConnectionOnly
                                </flush-strategy>
                            </pool>
                            <security>
                                <user-name>
                                    pentaho_user
                                </user-name>
                                <password>
                                    password
                                </password>
                            </security>
                        </datasource> 
                   
                        <datasource jndi-name="java:jboss/datasources/pentaho_operations_mart" pool-name="pentahooperationsmartpool" enabled="true" jta="true" use-java-context="true" use-ccm="true">
                             <connection-url>
                                 jdbc:postgresql://localhost:5432/hibernate
                             </connection-url>
                             <driver-class>
                            org.postgresql.Driver
                             </driver-class>
                             <driver>
                                 org.postgresql
                             </driver>
                             <pool>
                               <prefill>
                                false
                               </prefill>
                            <use-strict-min>
                                false
                            </use-strict-min>
                            <flush-strategy>
                                FailingConnectionOnly
                            </flush-strategy>
                        </pool>
                        <security>
                            <user-name>
                                hibuser
                            </user-name>
                            <password>
                                password
                            </password>
                        </security>
                    </datasource>
                        <datasource jndi-name="java:jboss/datasources/PDI_Operations_Mart" pool-name="PDI_Operations_Mart" enabled="true" jta="true" use-java-context="true" use-ccm="true">
                             <connection-url>
                                  jdbc:postgresql://localhost:5432/hibernate
                             </connection-url>
    					     <driver-class>
    					     org.postgresql.Driver
    					     </driver-class>
    					     <driver>
    					          org.postgresql
    					     </driver>
    					     <pool>
    						     <prefill>false</prefill>
    						     <use-strict-min>false</use-strict-min>
    						     <flush-strategy>FailingConnectionOnly</flush-strategy>
    					     </pool>
    					     <security>
    						     <user-name>hibuser</user-name>
    						     <password>password</password>
    					     </security>
    				</datasource> 
    
  4. Add the driver definition in the driver section of the file.

    Here is an example of the PostgreSQL driver definition. If you are using another database, modify the driver name, module, and data source class accordingly.
    <driver name="org.postgresql" module="org.postgresql"> 
    <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class> 
    </driver> 
    <driver name="org.hsqldb" module="org.hsqldb"> 
    <driver-class>org.hsqldb.jdbcDriver</driver-class> 
    </driver>
    
  5. Save and close the standalone.xml file.

Step 5: Add JBoss Deployment Structure file to the WAR file

The jboss-deployment-structure.xml JDS file controls class loading. It prevents automatic dependencies from being added, adds dependencies, defines additional modules, changes isolated class loading behavior, and adds additional resource roots to a module.

You will need to create, then add a JBoss deployment structure file (jboss-deployment-structure.xml) to the pentaho.war file.
CautionIf you have a different database than PostgreSQL, adjust the module name information in this section to match the ones in your environment.

Procedure

  1. Use a text editor to create a new file named: jboss-deployment-structure.xml

  2. Copy the following code snippet to the jboss-deployment-structure.xml file.

    <jboss-deployment-structure>
    <deployment>
    <exclude-subsystems>
    <subsystem name="resteasy" />
    <subsystem name="jaxrs" />
    <subsystem name="webservices" />
    </exclude-subsystems>
    <dependencies>
    <module name="org.h2" />
    <module name="org.postgresql" />
    <module name="org.jboss.modules" />
    <module name="org.hsqldb" />
    </dependencies>
    </deployment>
    </jboss-deployment-structure>
    
  3. Save and close the file.

  4. Use a ZIP extraction utility (such as 7-Zip, Winzip, or Archive) to view the contents of the pentaho.war file. Do not unzip or extract the contents of the file.

  5. Navigate to the WEB-INF directory and add the jboss-deployment-structure.xml file that you just created to it.

  6. Close the pentaho.war file. The ZIP extraction utility that you used might show a prompt which asks whether you would like to update the file in the pentaho.wararchive. Confirm that you would like to update the file.

Step 6: Remove JNDI resource references in JBoss

Because JBoss has its own mechanism for referencing JNDI data sources, the resource-ref entries in the web.xml file located in the pentaho.war are not needed.

You must remove these resource-ref entries for the Pentaho Repositoryto operate properly.

Procedure

  1. Navigate to the pentaho/server/pentaho-server/<your jboss installation directory>/standalone/deployments directory.

  2. Use a ZIP extraction utility (such as 7-Zip, Winzip, or Archive) to view the contents of the pentaho.war file. Do not unzip or extract the contents of the file.

  3. Navigate to the WEB-INF directory and open the web.xml file in a text editor.

  4. Delete all <resource-ref> tagged entries including everything between the <resource-ref> and </resource ref> tags.

  5. Save and close the file.

  6. The ZIP extraction utility that you used might show a prompt that asks whether you would like to update the file in the pentaho.war archive. If this prompt appears, confirm that you would like to update the file.

Step 7: Update JNDI data source reference to conform to JBoss standards

Update these files so that referenced JNDI datasources conform to JBoss standards.

  1. Use a text editor to open the pentaho/server/pentaho-server/pentaho-solutions/system/quartz/quartz.properties file. Change the org.quartz.dataSource.myDS.jndiURL value to jboss/datasources/Quartz, then save and close the file.

  2. Use a text editor to open the pentaho/server/pentaho-server/pentaho-solutions/system/audit_sql.xml file. Change the JNDI value to jboss/datasources/Hibernate, then save and close the file.

  3. Use a text editor to open the pentaho/server/pentaho-server/pentaho-solutions/system/data-access/settings.xml file. Change the data-access-staging-jndi value to jboss/datasources/Hibernate, then save and close the file.

  4. Open the pentaho/server/pentaho-server/pentaho-solutions/system/audit/dialects/h2 directory, making sure to open the file from the correct folder.

    Use the text editor to open each file in the H2 directory and make the following changes:
    • Change <database>Audit</database> to <database>jboss/datasources/Audit</database>.
    • Change <database>Hibernate</database> to <database>jboss/datasources/Hibernate</database>.

Step 8: Enable JBoss classloader to load classes from Sun JDK

JBoss allows a specific set of packages from the JDK to load by default.

To configure the Pentaho platform in JBoss, add this list of packages.

Procedure

  1. Locate the pentaho/server/pentaho-server/<your jboss installation directory>/modules/system/layers/base/sun/jdk/main directory.

  2. Open the module.xml file with any text editor.

  3. Add these three lines below the list of packages in the module.xml.

    <path name="sun/net/www/protocol/jar"/>
    <path name="sun/net/www/protocol/jar/JarURLConnection"/>
    <path name="com/sun/org/apache/xerces/internal/jaxp/datatype"/>
    
  4. Save and close the module.xml file.

  5. Navigate to the ...modules/system/layers/base/sun/jdk/main/service-loader-resources/META-INF/services directory.

  6. Find and remove this driver: java.sql.Driver.driver

Step 9: Update the security file

The default configuration of the Pentaho suite includes an extra layer of protection which prevents certain types of session fixation vulnerabilities. This feature can only be enabled on application servers which support the Java Servlet standard 3.1 and later.

Because versions of the JBoss web application server prior to JBoss 7.0 do not support this standard, the following changes are required.

In the applicationContext-spring-security.xml file, remove the following beans so Pentaho starts correctly.

Procedure

  1. Navigate to the pentaho-server/pentaho-solution/system folder and open the applicationContext-spring-security.xml file with a text editor.

  2. Find and remove all occurrences of the following string (including the comma):

    sessionMgmtFilter,
  3. Find and remove the following code:

    <bean id="sas" class="org.springframework.security.web.authentication.session.ChangeSessionIdAuthenticationStrategy" />
  4. Find and remove the following code:

    <property name="sessionAuthenticationStrategy" ref="sas" />
  5. Find and remove the following code:

    <bean id="httpSessionSecurityContextRepository" class="org.springframework.security.web.context.HttpSessionSecurityContextRepository"/>
  6. Find and remove the following block of code:

    <bean id="sessionMgmtFilter" class="org.springframework.security.web.session.SessionManagementFilter"> 
    <constructor-arg ref="httpSessionSecurityContextRepository"/> 
    <constructor-arg ref="sas"/> 
    </bean>
  7. Save and close the file.

Prepare JBoss web application servers

If you have installed the JBoss web application server, you must manually complete several configuration tasks.

These sections will guide you through the steps for getting your JBoss web application servers ready:

  1. Increase the Amount of Time JBoss Allows for Pentaho Server Deployment
  2. Disable the JBoss RESTEasy Scan
  3. Set the Location of the Solutions Directory
  4. Configure JBoss Settings
  5. Configure Pentaho Settings for JBoss

Step 1: Increase the amount of time JBoss allows for Pentaho Server deployment

By default, JBoss allows up to one minute for a web application to be deployed; otherwise, an error occurs. Because the Pentaho Server deployment requires more than one minute, manually edit the standalone.xml file to increase the deployment time.

  1. Use a text editor to open the <your jboss installation directory>/standalone/configuration/standalone.xml file

  2. Find the deployment-scanner tag, add the deployment-timeout attribute, then set the attribute equal to 3600.

    NoteIf you are installing the Pentaho Server on a VM, you might want to increase the deployment-timeout attribute's value to give the Pentaho Server more time to deploy.
    <deployment-scanner scan-interval="5000" relative-to="jboss.server.base.dir" path="deployments" scan-enabled="true" deployment-timeout="3600"/>
  3. Save and close the file.

Step 2: Disable the JBoss RESTEasy scan

To load Pentaho REST services correctly, the RESTEasy scan in JBoss must be disabled.

This task explains how to disable the RESTEasy scan in JBoss.

Procedure

  1. Use a ZIP extraction utility such as 7-Zip, Winzip, or Archive to view the contents of the <your jboss installation directory>/standalone/deployments/pentaho.war file. Do not unzip the pentaho.war file, just view its contents.

  2. Navigate to the WEB-INF directory in the pentaho.war file and open the web.xml file in a text editor.

  3. At the end of the <context-param> tags, add this code.

    <context-param>
                 <param-name>resteasy.scan</param-name>
                 <param-value>false</param-value>
            </context-param>
            <context-param>
                 <param-name>resteasy.scan.resources</param-name>
                 <param-value>false</param-value>
            </context-param>
            <context-param>
                 <param-name>resteasy.scan.providers</param-name>
                 <param-value>false</param-value>
    </context-param>
    
  4. Save the changes and close the file.

  5. The ZIP extraction utility that you used might show a prompt that asks whether you would like to update the file in the pentaho.war archive. If this happens, confirm that you would like to do this.

Step 3: Set the location of the solutions directory

To deploy JBoss correctly, Pentaho recommends that you define the location of the pentaho-solutions directory in the web.xml file.

Perform the following steps to define the location.

Procedure

  1. If you have not done so already, use a ZIP extraction utility such as 7-Zip, Winzip, or Archive to view the contents of the <your jboss installation directory>/standalone/deployments/pentaho.war file. Do not unzip the pentaho.war file; just view its contents.

  2. Navigate to the WEB-INF directory in the pentaho.war file and open the web.xml file in a text editor.

  3. Locate the following <context-param> tags.

    <context-param>
          <param-name>solution-path</param-name>
          <param-value></param-value>
     </context-param>
  4. Set the parameter value of the solution-path to the pentaho-solutions path. An example of the code is below.

    <context-param>
         <param-name>solution-path</param-name>
         <param-value>/home/pentaho/server/pentaho-server/pentaho-solutions</param-value>
     </context-param>
    
  5. Save the changes and close the file

Step 4: Configure JBoss settings

The JBoss startup script needs to be modified to match the Pentaho Server's memory resource requirements.

If this step is not performed, the Pentaho Server will not start. Besides matching memory resources, the Tomcat connector must also be updated for UTF-8 encoding.
CautionWe recommend increasing the time-outs even further than shown here if you have a large database and you are upgrading from 5.x.

Procedure

  1. Use a text editor to open the standalone configuration file.

    The file you open depends on your operating system.
    • Windows: <your JBoss installation directory>\bin\standalone.conf.bat
    • Linux: <your JBoss installation directory>/bin/standalone.conf
  2. Find the section for JVM memory allocation, then locate the line for JAVA_OPTS, and replace it with the following line of code:

    Windows:

    "JAVA_OPTS=-Xms4096m -Xmx6144m -DDI_HOME=%DI_HOME% -Dpentaho.installed.licenses.file=%PENTAHO_INSTALLED_LICENSE_PATH% -Djboss.as.management.blocking.timeout=3600"
    

    Linux:

    JAVA_OPTS="-Xms4096m –Xmx6144m -Djava.net.preferIPv4Stack=true" -DDI_HOME=$DI_HOME -Dpentaho.installed.licenses.file=$PENTAHO_INSTALLED_LICENSE_PATH -Djboss.as.management.blocking.timeout=3600" 
    
    NoteThe DI_HOME variable is defined in a separate step. See Starting the Pentaho Server.
  3. Save the changes and close the file.

  4. Use a text editor to open the standalone.xml file in the <your JBoss installation directory>/standalone/configuration folder.

  5. Set the org.apache.catalina.connector.URL_ENCODING and org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING system properties by adding the following lines of code to the standalone.xml file:

    <system-properties>
      <property name="org.apache.catalina.connector.URI_ENCODING" value="UTF-8"/>
      <property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true"/>
    </system-properties>
    
  6. Save the changes and close the file.

Step 5: Configure Pentaho settings for JBoss

Before you deploy the Pentaho Server, update the Pentaho configuration settings for JBoss.

  1. Edit /pentaho-solutions/system/karaf/etc/config.properties to add __redirect to the bootdelegation property, as shown in the following example:

    org.osgi.framework.bootdelegation=__redirected...
  2. Edit /pentaho-solutions/system/karaf/etc/custom.properties to change org.apache.xerces.*; version\=”2.9.1” to: org.apache.xerces.*; version\=”2.11.0”

  3. Optionally, you can add JBoss logging.

    We recommend completing the steps in the Add JBoss logging article, and then running the appropriate script for starting your server.

Step 6: Complete the JBoss checklist

Verify that you have completed all JBoss associated tasks before starting the Pentaho Server.

Use the Verification checklist for JBoss connection tasks to help ensure that you have completed all JBoss associated tasks.

Starting the Pentaho Server

After you have completed the JBoss tasks, you are ready to start the Pentaho Server.

Complete the JBoss tasks before attempting to start the Pentaho Server using this procedure. If you want to add the optional JBoss logging, do that first and then run the appropriate script for starting your server.

Procedure

  1. Define the DI_HOME environment variable.

    The default path for Windows and Linux is shown below:
    • Windows: PENTAHO_INSTALLATION_FOLDER\pentaho-server\pentaho-solutions\system\kettle
    • Linux: PENTAHO_INSTALLATION_FOLDER/pentaho-server/pentaho-solutions/system/kettle
  2. Run the startup script for your web application server by launching one of these files in the JBoss bin directory:

    • Windows JBoss: Launch the standalone.bat file.
    • Linux JBoss: Launch the standalone.sh file.
  3. Open a web browser and enter this URL: http://local:8080/pentaho

    The User Console Log On window appears.
    NoteYou will be prompted to install a license. Information about license installation can be found in Manage Pentaho Server licenses using the User Console,