Skip to main content
Version Pentaho
Hitachi Vantara Lumada and Pentaho Documentation

Customize the Pentaho Server

  1. Last updated
  2. Save as PDF

You can change ports, directories, and other advanced settings.

Change the PDI Home Directory Location

The default location for the Pentaho Data Integration home directory is the .kettle directory in your system user's home directory.

  • Windows: C:\Documents and Settings\example_user\.kettle
  • Linux: ~/.kettle)

There will be a different .kettle directory, and therefore a different set of configuration files, for each system user that runs PDI.

The contents of this directory are listed in the following table:

File Purpose
kettle.properties Main PDI properties file; contains global variables for low-level PDI settings
shared.xml Shared objects file
db.cache The database cache for metadata
repositories.xml Connection details for PDI database or solution repositories
.spoonrc User interface settings, including the last opened transformation/job
.languageChoice Default language for the PDI client tool

Standalone PDI client tool deployments

You can specify a single, universal .kettle directory for all users by declaring a KETTLE_HOME environment variable in your operating system. When declaring the variable, leave out the .kettle portion of it; this is automatically added by PDI.

export KETTLE_HOME=/home/pentaho/examplepath/pdi

Pentaho Server deployments that run PDI content

If you followed a manual deployment or archive package installation path, you can set a system environment variable as explained above, but it must be declared before the Pentaho Server service starts. You can alternatively change the CATALINA_OPTS system variable to include the -D flag for KETTLE_HOME, or you can edit the script that runs the Pentaho Server and set the flag inline, as in this example from the start-pentaho.sh script:

export CATALINA_OPTS="--Xms2048m -Xmx2048m -XX:MaxPermSize=256m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000" -DKETTLE_HOME=/home/pentaho/examplepath/pdi

Windows service modification

If you used the graphical utility to install the Pentaho Server, then you must modify the Java options flag that runs the Pentaho Server Tomcat service. Here is an example command that will change the value of KETTLE_HOME to C:\<examplepath>\pdi\.kettle:

tomcat8.exe //US//pentahobiserver ++JvmOptions -DKETTLE_HOME=C:\examplepath\pdi

Change Ports and URLs

The Pentaho Server has associated default port numbers. You can change these port numbers to adjust the Pentaho Server to your system. Since the port number of the Pentaho Server is a part of its URL, you will also have to change that address.

List of Server Ports Used by PDI

The following port numbers must be available internally on the machine that runs the Pentaho Server:

Service Port Number
Pentaho Server 8080
H2 (SampleData) 9092
Embedded Pentaho Server (Jetty) 10000

The SampleData database is an exception. It is only for evaluation and demonstration purposes and is not necessary for production systems. 

The Embedded Pentaho Server (Jetty) server port is hard-coded in Pentaho Data Integration and cannot be changed. If port 10000 is unavailable, the system will increment by 1 until an available port is found.

Change Pentaho Server (Tomcat) Port Numbers

Edit the /pentaho/server/pentaho-server/tomcat/conf/server.xml file and change the port numbers as shown in the following example code:

<!-- A "Connector" represents an endpoint by which requests are received
         and responses are returned. Documentation at :
         Java HTTP Connector: /docs/config/http.html (blocking & non-blocking)
         Java AJP  Connector: /docs/config/ajp.html
         APR (HTTP/AJP) Connector: /docs/apr.html
         Define a non-SSL HTTP/1.1 Connector on port 8080
    -->
    <Connector URIEncoding="UTF-8" port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="9443" />
    <!-- A "Connector" using the shared thread pool-->
    <!--
    <Connector URIEncoding="UTF-8" executor="tomcatThreadPool"
               port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="9443" />

You may also have to change the SSL and SHUTDOWN ports in this file, depending on your configuration.

Next, follow the directions in Change the Pentaho Server URL to accommodate for the new port number.

Change the Pentaho Server URL

You can change the Pentaho Server hostname from localhost to a specific IP address, hostname, or domain name by following these instructions. This procedure is also a requirement if you are changing the Pentaho Server port number.

  1. Stop the Pentaho Server.
  2. Navigate to the pentaho/server/pentaho-server/pentaho-solutions/system directory and open the server.properties file with any text editor.
  3. Modify the value of the fully-qualified-server-url element appropriately. 
    fully-qualified-server-url=http://localhost:8080/pentaho/
  4. Save and close the file.
  5. Start the Pentaho Server.

The Pentaho Server is now configured to reference itself at the specified URL.

If you recently upgraded to Pentaho 6.x or higher from a version earlier than 6.0, you may need to remove the <context-param> entry for the fully-qualified-server-url from the /tomcat/webapps/pentaho/WEB-INF/web.xml. If so, restart the Pentaho Server after removing it.

 

Change the Location of the Server Log File

For Windows:

If you used the install wizard to install, the pentaho.log is written to the C:/WINDOWS/system32 directory. To change the location of the pentaho.log file, you must edit log4j.xml in /pentaho-server/tomcat/webapps/pentaho/WEB-INF/classes/.

Modify the location as shown in the sample below, using the appropriate path to your installation:

<param name="File" value="C:/Program Files/pentaho/server/pentaho-server/logs/pentaho.log"/> 
<param name="Append" value="true"/>

For Linux:

If you are using Linux, the log4j.xml file is found in /pentaho-server/tomcat/webapps/pentaho/WEB-INF/classes/.

Modify the location as shown in the sample below, using the appropriate path to your installation:

<param name="File" value="home/pentaho/server/pentaho-server/logs/pentaho.log"/> 
<param name="Append" value="true"/>

Change the Quartz Misfire Threshold

With Quartz, sometimes scheduled jobs, transformations, or reports might try to run several times when they are manually stopped and restarted, instead of running only once. This is typically caused by the misfireThreshold property in Quartz being set at too high of a number.

These steps show how to reset the misfireThreshold to a lower numerical value.

  1. Stop the Pentaho Server.
  2. Locate the /pentaho-server/pentaho-solutions/system/quartz directory.
  3. Open the quartz.properties file with any text editor.
  4. Find the property shown below and change the default to a smaller number, such as 5000. The default value represents the number of milliseconds. 
    org.quartz.jobStore.misfireThreshold = 60000
  5. Save and close the quartz.properties file.
  6. Restart the Pentaho Server.

Set System Max Row Limit for Interactive Reports

You can prevent too many resources from hitting your database server at once by setting a system-wide maximum row-limit for Pentaho Interactive Reports. Your users can still define their own design-time row limits in PIR, but they will never be able to go over the maximum number of rows that you have specified while designing their reports.

  1. Shut down the Pentaho Server.
  2. Locate the /pentaho-server/pentaho-solutions/system/pentaho-interactive-reporting directory.
  3. Open the settings.xml file with any text editor.
  4. Find the <query-limit> tag and change the default number of 100000 within the tags to the maximum number of rows desired. 
    <!-- The maximum number of rows that will be rendered in a report on PIR edit and
view mode. A zero value means no limit. -->
<query-limit>100000</query-limit>
  5. Save and close the settings.xml file.
  6. Start the Pentaho Server.

If you are migrating content from a previous version, you will need to add the <query-limit> tag to your settings.xml for PIR.

Roll Back System Max Row Limit

These instructions show you how to return the system maximum row limit to the Pentaho 5.3 settings.

  1. Shut down the Pentaho Server.
  2. Locate the /pentaho-server/pentaho-solutions/system/pentaho-interactive-reporting directory.
  3. Open the settings.xml file with any text editor.
    1. To change the maximum number of rows that will be rendered in a Pentaho Interactive Report in edit or view mode, find the <design-query-limit> tag and change the default number of 500 back to 25.

      FROM:

      <design-query-limit>500</design-query-limit>

      TO:

      <design-query-limit>25</design-query-limit>
    2. To turn the design-query-limit to be OFF by default, find the <design-query-limit-enabled> tags and change the value to false. 
      <design-query-limit-enabled>false</design-query-limit-enabled>
  4. Save and close the settings.xml file.
  5. Restart the server.

Increase the CSV File Upload Limit

You may find that you need to increase the size of the upload limit for your CSV files. These steps guide you through this process.

  1. Go to /pentaho-server/pentaho-solutions/system and open the pentaho.xml file.
  2. Edit the XML as needed (sizes are measured in bytes): 
    <file-upload-defaults>
      <relative-path>/system/metadata/csvfiles/</relative-path>

      <!-- max-file-limit is the maximum file size, in bytes, to allow to be uploaded to the server -->
      <max-file-limit>10000000</max-file-limit>

      <!-- max-folder-limit is the maximum combined size of all files in the upload folder, in bytes. -->
      <max-folder-limit>500000000</max-folder-limit>

</file-upload-defaults>
  3. Save your changes to the file.
  4. In the User Console, go to Tools > Refresh System Settings to ensure that the change is implemented.
  5. Restart the User Console.

Change the Staging Database for CSV Files

Hibernate is the default staging database for CSV files. Follow these instructions if you want to change the staging database.

  1. Go to /pentaho-solutions/system/data-access and open the settings.xml file with any text editor.
  2. Edit the settings.xml file as needed. The default value is shown in the sample below. 
    <!-- settings for Agile Data Access -->
<data-access-staging-jndi>hibernate</data-access-staging-jndi>
    This value can be a JNDI name or the name of a Pentaho Database Connection.
  3. Save and close the file.
  4. Restart the User Console.

Change the Karaf Startup Timeout Setting

Upon start up, the system waits for Karaf to install all of its features before timing out. If you modify Karaf and it now takes longer to install during start up, you may need to extend the default timeout setting to allow Karaf more time to install. The current default timeout is 2 minutes (120000 milliseconds).

You can change this default timeout by editing the server.properties file.

  1. Stop the Pentaho Server.
  2. Navigate to the /pentaho-server/pentaho-solutions/system directory.
  3. Open the server.properties file with any text editor, and search for the karafWaitForBoot parameter.
  4. Uncomment the line containing the parameter and set it to your desired wait time in milliseconds. 
    # This sets the amount of time the system will wait for karaf to install all of
# it's features before timing out.  The default value is 2 minutes but can be
# overridden here.
#karafWaitForBoot = 120000
  5. Save and close the file.
  6. Restart the Pentaho Server.

Change the Port Numbers for the Pentaho Server

Follow the instructions below to change the port through which the Pentaho Server runs:

  1. Stop the Pentaho Server.
  2. Navigate to the /pentaho-server/tomcat/conf/ directory.
  3. Open the server.xml file with any text editor, and search for the value for Define a non-SSL HTTP/1.1 Connector. Change the port number in the connector port element below from 8080 to your preferred port number. 
    <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
    <Connector port="8080" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               connectionTimeout="20000" disableUploadTimeout="true" />
  4. Save and close the server.xml file.
  5. Navigate to the /pentaho-server/pentaho-solutions/system directory and open the server.properties file with any text editor.
  6. Change the fully-qualified-server-url entry to match the new port number you specified in server.xml. 
    fully-qualified-server-url=http://localhost:8080/pentaho/
  7. Save and close the file.
  8. Restart the Pentaho Server.

If you recently upgraded to Pentaho 6.0, you may need to remove the <context-param> entry for the fully-qualified-server-url from the /tomcat/webapps/pentaho/WEB-INF/web.xml. If so, restart the Pentaho Server after removing it.

Change the Web Application Name or Port

The Pentaho Pentaho Server and web application default port number is 8080. The default web application name is pentaho, which is the name of the .war file archive, the name of the directory that your application server creates, and also part of the URL structure for all content in the User Console.

If you need to change the User Console application name to something else, or if your Web application server is running on a port other than 8080, follow these instructions for either JBoss or Tomcat.

Change the Web Application Name on Tomcat

These instructions only work on Tomcat servers that are configured to accept context.xml overrides built into deployed .war files. Some Tomcat deployments may not have this feature turned on. You can change the Tomcat configuration on your own, or consult your Tomcat documentation to learn about other methods of changing a web application context. Use the XML snippet in these instructions in whichever configuration file you end up creating or modifying.

Follow these instructions to change the web application context for a Pentaho .war file that you deployed to a Tomcat server. While the example below uses 'sample' as the context name, you can use whatever context name you choose.

  1. Stop the server.
  2. Open the pentaho/server/pentaho-server/tomcat/webapps/pentaho/META-INF/context.xml file in a text editor, and change the pentaho references in the context path tag to your preferred context name. For example, to specify a context name of 'sample', modify context path as follows. 
    <context path="/sample" docbase="webapps/sample/">
  3. Save and close the file.
  4. Navigate to the pentaho/server/pentaho-server/tomcat/webapps folder, and rename the pentaho folder to your preferred context name. In this example, rename the pentaho folder to sample.
  5. Edit the pentaho/server/pentaho-server/tomcat/webapps/ROOT/index.jsp file to change the pentaho reference in the URL property to your preferred context name. In this example, use the following line of code to specify 'sample' as the new context name: 
    <meta http-equiv="refresh" content="0;URL=/sample">
  6. Edit the pentaho/server/pentaho-server/pentaho-solutions/system/server.properties file to change pentaho in the value of the fully-qualified-server-url setting to your preferred context name. In this example, set the fully-qualified-server-url as follows. 
    fully-qualified-server-url=http://localhost:8080/sample/
  7. Start the server.

Change the Web Application Name on JBoss

Follow these instructions to change the Web application context for a Pentaho.war file that you deployed to a JBoss server.

  1. After deployment is successful, delete the original pentaho.xml file.
  2. Open the jboss-web.xml file with any text editor.
  3. Add the following text inside of the jboss-web section, replacing example with your new context name: 
    <context-root>example</context-root>
  4. Save and close that file, then open the web.xml file and modify the fully-qualified-server-url entry to match your new context name and port number. 
    <context-param>
    <param-name>fully-qualified-server-url</param-name>
    <param-value>http://localhost:5150/example/</param-value>
</context-param>
  5. Save and close the file.