Introduction
After installing JasperReports Server version 7.8 on a machine in addition to versions 7.2.x and/or 7.5.x, the new installation or one of the previous instances may not function properly. This is caused by permissions on the keystore files needing to be different in recent releases, and slight differences in file contents. The issue affects only version 7.2.x and higher, earlier versions are not affected. This article describes how to recover from the situation so that all servers may run on the same host.
If you have not yet installed 7.8, and you wish to keep an instance of 7.2.x and/or 7.5.x, see Before Installing 7.8.
Important: Before you perform the steps on this page, please back up the .jrsksp and .jrsks files to a secure location. Make sure all backups are readable only by admin users.
These steps can also be applied to JasperReports Server 7.9.
Keystore Files
The cryptography keys used by the server to secure passwords in the server are stored in the .jrsks and .jrsksp files. During a new installation, these files are generated and stored in the installation user's home directory by default. The names of the .jrsks and .jrsksp files cannot be changed, but you can move them to a different location. The path is stored in the server's keystore.init.properties configuration files.
Because different versions of the server require different permissions on the keystore files, the solution is to create a copy of the keystore for each version of the server. Then, the contents of the keystore files must be modified for each version. Finally, each server must be reconfigured to use its specific keystore in the new location.
You must restart your servers after modifying the keystores.
Before Installing 7.8
If you wish to install JasperReports Server 7.8 on a host that also has an instance of 7.2.x and/or an instance of 7.5.x, there are two choices:
If you want all JasperReports Server instances to share import and export catalogs between them, you should install 7.8 first, then follow the instructions in If You Have Already Installed 7.8. Those instructions are longer overall, but they ensure that all servers will have copies of the same keys.
If your instance of 7.8 does not need to share import and export catalogs with the 7.2.x and/or 7.5.x instances, the steps in this section are simpler. The servers will have different keys.
To install keep installations of JasperReports Server 7.2.x and or 7.5.x and install version 7.8 with a different keystore, follow these steps:
On Windows, copy .jrsksp and .jrsks files from $HOME to some folder in the user’s home directory, for example $HOMEjrs75. If you move the files, your 7.8 server will not have the same keys and import-export with the older servers will not be possible without more configuration.
On Linux, copy the .jrsks and .jrsksp files from $HOME~/ to some folder in the user’s home directory. This ensures that 7.8 will still work when installed.
On Windows, set the security permissions on the original .jrsksp and .jrsks files so that LOCAL SERVICE has read permission.
Change buildomatic/keystore.init.properties of the existing instance to point to a new location.
Redeploy the WAR file. Alternatively, you may manually modify your deployed application in the file webappsjasperserver-proWEB-INFclasseskeystore.init.properties (7.8, 7.5) and restart the service.
Verify login on your existing server (7.2.x and/or 7.5.x) as well as command line import-export.
Repeat these steps for all 7.2.x and/or 7.5.x instances on the same host.
Install JasperReports Server 7.8 as the same user, and let the installer select the keystore in the default location:
For Windows: ($HOME)
For Linux/MacOS: ($HOME~/)
Back up all copies of the keystore files to a secure location.
These steps will preserve the keystore configuration for the existing versions, so the new installer will not modify it.
If You Have Already Installed 7.8
When version 7.2.x and/or 7.5.x already exist on the same host, installing version 7.8 will cause them to stop working, and under Windows, the 7.8 instance will not start. Refer to the procedures in the following sections to repair the keystore for all versions after installing version 7.8.
Manual Steps
The following sections are manual instructions for fixing versions 7.8.x, 7.5.x and 7.2.x installed previously.
Instructions for 7.8
Create the folders named jrs72 and/or jrs75 in the user home directory, depending on which servers you will run simultaneously. Copy the .jrsksp and .jrsks files to these directories.
- Linux:
cd ~ mkdir jrs72 cp .jrsks* ~/jrs72 mkdir jrs75 cp .jrsks* ~/jrs75
- Windows:
cd $HOME mkdir jrs72 cp .jrsks* ~/jrs72 mkdir jrs75 cp .jrsks* ~/jrs75
On Windows, set the security permissions on the original .jrsksp and .jrsks files so that LOCAL SERVICE has read permission. Version 7.8 will use these files ($HOME/.jrsksp and $HOME/.jrsks).
On Windows, restart the JasperReports Server 7.8, you should be able to log in now.
On Linux and OS X, JasperReports Server should already be running and not need to be restarted.
Instructions for 7.5.x
Stop the app server for your 7.5.x instance.
Go to the jrs75 folder created in step 1 of Instructions for 7.8.
Decode the .jrsksp file using Base64 Table 1 of RFC 2045, url unsafe, and padded. For example:
Linux:
cat .jrsksp | openssl base64 -d > <temp_file>
Windows:
certutil -decode .jrsksp temp.jrsksp
Edit the .jrsksp file and add the ksPath property with the path to the .jrsks file in the current folder. For example:
Linux:
~/jrs75/.jrsks/
Windows:
ksPath=$HOME\\jrs75\\.jrsks
In the decoded .jrsksp file, decode again the values of properties that end with .pwd, .keypass and ksPwd. For example:
Replace each encoded password with its decoded value. If the decoded password contains any :, =, &, or characters, they should be escaped with the character.
Linux:
echo <value> | openssl base64 -d cat <value> | openssl base64 -d
Windows:
certutil -decode <value>
Re-encode the .jrsksp file with the same Base64 settings, for example:
Linux:
base64 .jrsksp > ./temp.jrsksp mv temp.jrsksp .jrsksp
Note: mv is not required, but you should make sure that the original .jrsksp file does not exist (backed up). The command for this is:
base64 /path/to/file > .jrsksp
For example:
./temp.jrsksp > .jrsksp
Windows:
certutil a- encode temp.jrsksp tmp.b64 && findstr /v /c:tmp.b64 .jrsksp
Locate the buildomatic/keystore.init.properties server configuration file and edit it to modify the ks and ksp properties:
Linux:
ks=~/jrs75/ ksp=~/jrs75/
Windows:
ks=$HOME\\jrs75\\ ksp=$HOME\\jrs75\\
After modifying the buildomatic/keystore.init.properties file, use it to overwrite the same file in the following locations (depending on the release):
buildomatic/conf_source/ieCe/keystore.init.properties
buildomatic/conf_source/iePro/keystore.init.properties
buildomatic/build_conf/default/webapp/WEB-INF/classes/keystore.init.properties
apache-tomcat/webapps/jasperserver-pro/WEB-INF/classes/keystore.init.properties
Restart the service.
Instructions for 7.2.x
First check that JasperReports Server 7.2.x is working. If this version is working, you do not have to perform the manual steps. Otherwise, Release 7.2.x is not affected by the installation of version 7.8 unless the configuration in the default_master.properties file contains encrypt=true or encrypt.done=true. If this is the case, perform the following steps:
Stop the app server for your 7.2.x instance.
Go to the jrs72 folder created in step 1 of Instructions for 7.8.
Decode the .jrsksp file using Base64 Table 1 of RFC 2045, url unsafe, and padded. For example:
Linux:
cat .jrsksp | openssl base64 -d
Windows:
certutil -decode .jrsksp temp.jrsksp
Edit the .jrsksp file and add the ksPath property with the path to the .jrsks file in the current folder. For example:
Linux:
ksPath=~/.jrsks
Windows:
ksPath=$HOME\\jrs72\\.jrsks
In the decoded .jrsksp file, decode again the values of properties that end with .pwd, .keypass and ksPwd. For example:
Replace each encoded password with its decoded value. If the decoded password contains any :, =, &, or characters, they should be escaped with the character.
Linux:
echo <value> | openssl base64 -d
Windows:
certutil -decode <value>
Re-encode the .jrsksp file with the same Base64 settings, for example:
Linux:
base64 .jrsksp > ./temp.jrsksp mv temp.jrsksp .jrsksp
Windows:
certutil -encode temp.jrsksp tmp.b64 && findstr /v /c:-tmp.b64 > .jrsksp
Set the ksp property value in the following configuration files:
Linux:
ksp=~/.jrsksp
in
apache-tomcat/bin/setenv.sh
buildomatic/bin/do-js-setup.sh (before running ant)
buildomatic/bin/js-import-export.sh (before running java)
Windows:
ksp=$HOME\\jrs72\\.jrsksp
in
apache-tomcatbinsetenv.bat
buildomaticbindo-js-setup.bat (before running ant)
buildomaticbinjs-import.bat (before running java)
buildomaticbinjs-export.bat
On Windows, if tomcat was installed as a service by the installer, then open the Registry Editor and locate the following entry (may have a number at the end):
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\jasperreportsTomcat
Add the Environment property as follows:
Right-click on jasperreportsTomcat > New > Multi-String Value (Type REG_MULTI_SZ)
Give it the name Environment
Right-click on Environment and choose Modify…
Set KSP=$HOMEjrs72
Restart the service.
Managing Keystores
After running the commands for each instance, the location of each server's keystore is as follows, where ~ or $HOME is the home directory or folder of the user who installed the servers:
Linux:
7.2.x: ~/jrs72/.jrsks 7.5.x: ~/jrs75/.jrsks 7.8.0: ~/.jrsks
Windows:
7.2.x: $HOME\jrs72\.jrsks 7.5.x: $HOME\jrs75\.jrsks 7.8.0: $HOME\.jrsks
As a result, each of your servers runs with a separate copy of the keystore. Because the keystores are identical, you can export from one server and import to another server as needed. However, if you modify any of the keys or import a new key, it only applies to the server that performed the operation. You must then duplicate the operation on the other server or servers; for example, import the same key to each server.
For information about specifying keys during import and export operations, see the Import and Export chapter of the Administrator’s Guide. For information about importing keys, see Managing Keys for Import and Export in the Security Guide.
Appendix - Differences Between Versions
Permissions
The following shows the keystore file permissions expected by each affected version of JasperReports Server. Windows permissions can be found on the Security tab of the file Properties dialog.
Release 7.2.x
- Linux: 644:
6 - rw for owner 4 - r for group 4 - r for others
JasperReports Server is running as a service under user owner or tomcat.The tomcat user must be part of the same group as the owner.
Windows:
Full Control - SYSTEM group, owner (usually Administrator), Administrators group
JasperReports Server is running as a service under the LOCAL SYSTEM group.
Release 7.5.x
Linux: 640:
6 - rw for owner 4 - r for group 0 - no access for others
JasperReports Server is running as a service under user owner or tomcat. The tomcat user must be part of the same group as the owner.
Windows:
Read - SYSTEM group
Read - LOCAL SERVICE group
Special - for owner (usually Administrator)
Read - for Administrators group
JasperReports Server is running as a service under the LOCAL SYSTEM group.
Release 7.8.x
Linux: 640:
6 - rw for owner 4 - r for group 0 - no access for others
JasperReports Server is running as a service under user owner or tomcat. The tomcat user must be part of the same group as the owner.
Windows:
Read - SYSTEM group
Read - LOCAL SERVICE group
Special - for owner (usually Administrator)
Read - for Administrators group
Tomcat is running as a service under the LOCAL SERVICE group.
Keystore Files
The following shows how the format of the keystore files have changed between releases of JasperReports Server:
Release 7.2.x: Keystore introduced by default, used only at installation time for securing passwords in configuration files.
Release 7.5.x: Keystore is now required at runtime. Keys from XML configuration are stored in the keystore. Only new keys and properties are added.
Release 7.8.x: The ksPath property in .jrsksp (that specifies the full path of the .jrsks file) is removed.
Observed Behavior
If you install two or more versions of JasperReports Server on the same host, all WAR files might be separate, but the keystore files are shared and the newer versions will modify the files used by the older versions.
After installing 7.8 with an existing 7.2.x instance, the keystore files are updated to the new format, but keep their 7.2 permissions. Permissions are not modified by the installer in case they have been customized. As a result:
The 7.2.x instance fails to start if encryption was enabled (encrypt=true). The reason is because it can no longer access the keystore because the ksPath property was removed and the passwords were encoded.
The 7.8 instance on Windows fails to start because LOCAL SERVICE does not have permission to read the keystore files.
After installing 7.8 with an existing 7.5.x instance, keystore file permissions do not change, but the keystore files are updated to the new format. As a result:
The 7.5.x instance fails to start. The reason is because it can no longer access the keystore because the ksPath property was removed and the passwords were encoded.
If you have an existing 7.5.x instance and an existing 7.2.x instance, installing 7.8 will cause all three servers to fail under the conditions described above.
Recommended Comments
Create an account or sign in to comment
You need to be a member in order to leave a comment
Create an account
Sign up for a new account in our community. It's easy!
Register a new accountSign in
Already have an account? Sign in here.
Sign In Now