Skip to main content
Pentaho Documentation

Customize the Pentaho Server

Parent article

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:

FilePurpose
kettle.propertiesMain PDI properties file; contains global variables for low-level PDI settings
shared.xmlShared objects file
db.cacheThe database cache for metadata
repositories.xmlConnection details for PDI database or solution repositories
.spoonrcUser interface settings, including the last opened transformation/job
.languageChoiceDefault 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:
ServicePort Number
Pentaho Server8080
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.

NoteThe 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" />
NoteYou 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.

Procedure

  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.

Results

The Pentaho Server is now configured to reference itself at the specified URL.
NoteIf 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 misfireThresholdto a lower numerical value.

Procedure

  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. Start the Pentaho Server.

Set default SELECT DISTINCT for Interactive Reports

By default, Interactive Reports queries data with the SQL SELECT DISTINCT statement to return only distinct (different) data values, which may require an extensive sorting operation in the database. If you want to reduce the cost of a system-wide sorting operation, you can set new reports to open with the Select Distinct option cleared.

Perform the following steps to change the default setting of the Select Distinct option in the Query Setting dialog box of new Interactive Reports:

Procedure

  1. Stop the Pentaho Server.

  2. Locate the server/pentaho-server/pentaho-solutions/system/pentaho-interactive-reporting directory.

  3. Open the settings.xml file with any text editor.

  4. Find the <default-select-distinct> tag and change it to the desired setting.

    If you want the Select Distinct option cleared as the default, set the <default-select-distinct> tag to false as shown in the following example code:
    <!--  default select-distinct setting for a new report -->
    <default-select-distinct>false</default-select-distinct>
  5. Save and close the settings.xml file.

  6. Start 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 Interactive Reports, but they will never be able to go over the maximum number of rows that you have specified while designing their reports.

Procedure

  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.

Next steps

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

Roll back system max row limit

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

Procedure

  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 Pentaho Interactive Reports 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.

Procedure

  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.

Procedure

  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. See Define data connections for more information on database connections.
  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: 120000 (milliseconds - about 2 minutes).

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

Procedure

  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:

Procedure

  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.

Next steps

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 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.

Procedure

  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.

Procedure

  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.