Skip to main content
Pentaho Documentation

Pentaho Upgrade

Important: This guide describes how to upgrade the Pentaho Server from Pentaho version 7.0 or version 7.1 to Pentaho 8.0.

  • If you are currently using Pentaho 6.1.x with a BA Server and/or DI Server, use the Upgrade from 6.1.x to 8.0 upgrade instructions. 

Get Started with the 7.x to 8.0 Upgrade

Before you begin your upgrade to Pentaho 8.0 from Pentaho 7.0 or 7.1, you will need to know the following items:

  • How to access the Pentaho Server as an Administrator
  • Where your data is stored
  • How to connect to your data 

You also need to perform the following tasks:

Task Description
Verify Your Current Version of the Pentaho Suite and PDI Start with a working installation of Pentaho Server 7.0 or 7.1.

Verify Your System Components are Current

Make sure that your system components, such as web browsers or repository databases, are up-to-date for Pentaho.
Backup Your Databases

Create backups of all Pentaho databases.

  • hibernate
  • quartz
  • jackrabbit
Download and Configure Info-ZIP (Linux only) Download, install, and configure Info-ZIP open source compression utility using the Info-ZIP documentation. Info-ZIP is available at‐

The license is a BSD-style license and is provided for most Linux and Unix variants.

A Windows version of Info-ZIP is pre-configured and included in the Pentaho update package.

Verify That No Users Are Logged into the Server Perform this update during off-business hours to minimize impact to your day-to-day operations.

The following task is recommended, but not required, for the Pentaho 8.0 upgrade:

Task Description
Review Pentaho 8.0 System Updates

Get the Pentaho Upgrade and Utility Files 

Upgrade and utility files are available for download from the Pentaho Customer Support Portal

  1. On the Customer Portal home page, sign in using the Pentaho support user name and password provided in your Pentaho Welcome Packet. 
  2. Click Downloads, then click Pentaho 8.0 GA Release in the 8.x list. 
  3. On the bottom of the Pentaho 8.0 GA Release page, browse the folders in the Box widget to find the files you need, including the pentaho-server-ee-upgrade- 8.0.0 .zip file in the Utilities and Tools folder.

Available Update Files

The following files are required to perform a complete Pentaho 8.0 update:

Component File Name

Pentaho Server

The following upgrade and installation files are required for the Pentaho Server:

  • pentaho-server-ee-upgrade-8.0.x.yy-dist
  • pentaho-server-ee-8.0.x.yy-dist
DI Client pdi-ee-client-8.0.x.yy-dist
Pentaho Analyzer paz‐plugin‐ee‐8.0.x.yy-dist
Pentaho Dashboard Designer pdd‐plugin‐ee‐8.0.x.yy-dist
Pentaho Interactive Reporting pir‐plugin‐ee‐8.0.x.yy-dist
Report Designer prd‐ee‐8.0.x.yy-dist
Metadata Editor pme‐ee‐8.0.x.yy-dist
Schema Workbench psw‐ee‐8.0.x.yy-dist
Aggregation Designer pad‐ee‐8.0.x.yy-dist
License Files Pentaho [component] Enterprise Edition.lic

Unzip Distribution Files

The files include an End-User License Agreement. Accept the agreement to extract the files.

Perform the following steps to unzip the distribution files:

  1. Unzip the selected file.
  2. Execute the supplied install.bat or file.
  3. Agree to the end-user license agreement.
  4. Choose a location to store the extracted files.

You are now prepared to begin your 7.x to 8.0 upgrade. This process assumes you have completed either an archive or a manual installation of the 7.0 or 7.1 Pentaho Server and are upgrading to version 8.0. 

Upgrade the Pentaho Server

The following steps will guide you through the Pentaho Server 8.0 upgrade process:

  1. Backup Your Pentaho Server Configuration and Solutions Files
  2. Install the Pentaho Server 8.0
  3. Restore Your Server Configuration and Solutions Files
  4. Start Your Pentaho Server
  5. Test Your Server

Step 1: Backup Your Pentaho Server Configuration and Solutions Files

The backup utility copies your Pentaho configuration and solutions files, then stores the created .zip files in your user's home directory. You will need to merge your customizations if you have previously customized any of these things:

  • server.xml
  • startup and shutdown scripts
  • system listeners
  • security configuration files

Complete the following steps to back up your Quartz, Hibernate, and Jackrabbit databases before continuing with the upgrade process:

  1. Stop the Pentaho Server.
  2. Download the file from the Pentaho Customer Support Portal.
    1. On the Customer Portal home page, sign in using the Pentaho support user name and password provided in your Pentaho Welcome Packet. 
    2. Click Downloads, then click Pentaho 8.0 GA Release in the 8.x list. 
    3. On the bottom of the Pentaho 8.0 GA Release page, browse the folders in the Box widget to find the files you need, including the pentaho-server-ee-upgrade- 8.0.0 .zip file in the Utilities and Tools folder.
  3. Extract the files to a directory.
  4. Open a command line terminal and navigate to the unzipped directory of the pentaho-server-ee-upgrade.
  5. At the prompt, run the correct PentahoServerConfigAndSolutionsBackup utility for your operating system. You can also add an optional version parameter here. If a valid version is not automatically found during back-up, the process will be aborted. You will then be prompted to provide the version information as an argument to the utility.


PentahoServerConfigAndSolutionsBackup.bat "<path to your 7.x pentaho server>"


./ <path to your 7.x pentaho server>

The next step is to install a new instance of the Pentaho 8.0 software. 

Step 2: Install the Pentaho Server 8.0

Now that you have completed Step 1, you are ready to create a new archive installation of the Pentaho Server 8.0 package. 

Make sure to install the new instance of Pentaho on the same server.

Verify, and if necessary, complete the following tasks from the Prepare Your Environment (Windows or Linux) section of the installation guide. Make sure that you leave your Pentaho 7.x instance "as is" and unpack Pentaho 8.0 into a new directory. 



If you are using custom port numbers and a custom fully-qualified URL, refer to the Change the Port and URLs article for the required settings.

Step 3: Restore Your Server Configuration and Solutions Files

After you have unpacked your Pentaho 8.0 bundle, restore your Pentaho files to your 8.0 instance with the restore utility. Use the following steps to apply the PentahoServerConfigAndSolutionsRestore utility:

  1. Delete the content in the Pentaho Server 8.0 pentaho-solutions/system/default-content directory.  
  2. Open a command line terminal and navigate to the unzipped directory of the pentaho-server-ee-upgrade.
  3. In the prompt, run the PentahoServerConfigAndSolutionsRestore utility to restore your data from the .zip files located in your user home directory. 


    PentahoServerConfigAndSolutionsRestore.bat "<path to 8.0 pentaho server>"


    ./ <path to 8.0 pentaho server>

Step 4: Previous Version Upgrades

Complete these steps if you are upgrading from Pentaho version 7.x.

  1. Review the database connection information in the jackrabbit/repository.xml file to ensure that the database connection information is properly carried over from your 7.x version of the repository file into the 8.0 version of the file.
  2. Update the path to the pentaho.log file in the tomcat/webapps/pentaho/WEB-INF/classes/log4j.xml file.
  3. Remove the following directories and their contents. These plugins are not available in version 8.0.
Plugin Path
Mobile Pentaho/server/pentaho-server/pentaho-solutions/system/pentaho-mobile-plugin
Sparkl Pentaho/server/pentaho-server/pentaho-solutions/system/sparkl
  1. (Optional) Only add the authenticationEventPublisher  property (substeps 4 a. through 4 d.) when upgrading from Pentaho 7.0, as the property already exists in version 7.1.

Add the authenticationEventPublisher property to the applicationContext-spring-security.xml file by completing the following steps:

  1. Navigate to the pentaho-solutions/system/applicationContext-spring-security.xml file and open it with any text editor.
  2. Locate the section that contains the following lines:
    <bean id="authenticationManager" ...>
  3. Add the following property within the authenticationManager bean:
    <property name="authenticationEventPublisher">
        <bean class="" />
  4. Save and close the file.
  1. (Optional) Update the connection pool parameter. The following change to the connection pool parameter is required only if you are upgrading from a previous version BA or DI server.
    1. Navigate to the pentaho-server/tomcat/webapps/pentaho/META-INF directory and open the context.xml file with any file editor.
    2. Locate the section that contains the following line:
    3. Replace it with this line:
    4. Save and close the context.xml file.

For troubleshooting issues, refer to the Installation and Upgrade Issues article.

Step 5: Start the Pentaho Server

You are now ready to Start the Pentaho Server.

Do not interrupt the server the first time you start it after restoring your data.

Step 6: Test Your Server

Before you begin testing, clear your web browser cache.

The Pentaho Server installs all the Karaf features when it initializes. The system waits for these features to be installed before timing out. The default wait time before timing out is two minutes. If you modify any Karaf feature, you should consider changing the Karaf startup timeout setting

To ensure that your content has been restored to the 8.0 Pentaho Server, navigate to your Pentaho URL (the default URL is http://localhost:8080/Pentaho) and verify the following items:

  • The login screen appears.
  • Log on to PUC and try to run your old BA content.
  • Your schedules exist and are working properly.
  • Your Pentaho plugins are installed and functional by performing the following tasks:
    • Open a report that requires no user prompts and a parameterized report.
    • Create a test report for Interactive Reporting and one for Analyzer, as appropriate.
    • Open a dashboard in Dashboard Designer.
    • Publish a report in Report Designer.
    • Publish an analysis schema from the PDI Client (Spoon), if you have installed the Agile BI plugin available in the marketplace. (If not, you can publish an analysis schema using the Publish Model job entry.)
  • Check your application server log.

If you have upgraded to 8.0 from an earlier DI Server, navigate to your Pentaho DI URL (the default URL is http://localhost:9080/pentaho-di) and verify the following items:

Step 7: (Optional) Configuration File Changes

This section includes optional configuration changes you may wish to implement. 

Password Encoding

Pentaho version 8.0 changes the password encoding from previous versions. If you wish to use the current 8.0 version of password encoding, make the change explained here:

If you are using your own password encoding, do not make this update. 

  1. Navigate to the \Pentaho\server\pentaho-server\pentaho-solutions\system directory and open the pentahoObjects.spring.xml file with any text editor.
  2. Locate the line that contains: bean id="IPasswordService"
  3. Verify or modify the class= value with the following value:
bean id="IPasswordService" class="org.pentaho.platform.util.KettlePasswordService" scope="singleton"/>
  1. Save and close the file.
  2. If you modified the class= value in Step 3, you must make the following modification to encrypt the Pentaho Admin password. In the same \Pentaho\server\pentaho-server\pentaho-solutions\system directory, open the file with any text editor.
  3. Locate the following lines:
  1. Replace the values in these lines with the following values:
defaultAdminUserPassword=Encrypted 2be98afc86aa7f2e4bb18bd63c99dbdde
defaultNonAdminUserPassword=Encrypted 2be98afc86aa7f2e4bb18bd63c99dbdde
  1. Save and close the file. 

Documentation Version Link

The default URL of the online Pentaho documentation changes with each release. When upgrading, this URL parameter may need to be updated in the pentaho.xml file.

  1. Navigate to the \Pentaho\server\pentaho-server\pentaho-solutions\system directory and open the pentaho.xml file with any text editor.
  2. Modify the following <documentation-url> line and replace the previous documentation value with the current documentation value:
  1. Save and close the file. 

CORS - Embedding CTools

If your Pentaho deployment requires the ability to embed CTools, you can modify the following settings.

  1. Navigate to the \Pentaho\server\pentaho-server\pentaho-solutions\system directory and open the pentaho.xml file with any text editor.
  2. Modify or add the following CORS lines:
Flag indicating if cross-origin requests are allowed or not.
accepted values are: true | false


Comma separated list of domains allowed to do cross-origin requests to the server.
Example:, http://localhost:1337

<cors-requests-allowed-domains><!-- allowed domains here --></cors-requests-allowed-domains>
  1. If you are embedding CTools, add the following line (as shown above) and set the value to: true 
  1. Save and close the file. 

Update Your Design Tools

Now that you have completed the upgrade to 8.0, perform the following steps to upgrade your Pentaho design tools on your workstations.

  1. Exit any of the design tools, if any are currently running.
  2. Backup all the 7.x existing directories in the Pentaho/design-tools directory to a temporary directory. 
  3. Browse to the location where you downloaded the following -dist files in the Available Update Files section:
  • pdi-ee-client-8.0.x.yy-dist
  • prd-ee-8.0.x.yy-dist
  • pme-ee-8.0.x.yy-dist
  • psw-ee-8.0.x.yy-dist
  • pad-ee-8.0.x.yy-dist
  1.  Unzip and copy all the new design tools directories into your existing Pentaho/design-tools directory.
  2. Restart to verify that your design tools were upgraded.

You have now completed your Pentaho upgrade from 7.x to 8.0.

For Customers Using Analyzer

Analyzer can be upgraded from Visualization API 2.0 to Visualization API 3.0 . Before upgrading, please review the following information for more details:

For Customers Using DI Ops Mart

Now that you have completed the upgrade to 8.0, you can reinstall the DI Ops Mart. For further instructions, see Install DI Ops Mart