Chapter 3. External Configuration Files

ReportServer uses the Java Persistence API (JPA) to abstract from the actual database system when storing application data. The necessary configuration is made in the persistence.properties config file.

Example

hibernate.dialect=net.datenwerke.rs.utils.hibernate.MySQL5Dialect
hibernate.connection.driver_class=com.mysql.cj.jdbc.Driver
hibernate.connection.url=jdbc:mysql://localhost:3306/reportserver
hibernate.connection.username=rs
hibernate.connection.password=rs

Note that to configure the JPA/Hibernate settings, we are not editing the standard JPA configuration file (usually called persistence.xml) but a ReportServer properties file.

ReportServer supports all databases that are supported by Hibernate. A list of the database systems supported by Hibernate can be found on the hibernate webpages . We recommend to run ReportServer on one of the following databases for which we now give example configurations:

# MySQL 
hibernate.dialect=net.datenwerke.rs.utils.hibernate.MySQL5Dialect
hibernate.connection.driver_class=com.mysql.cj.jdbc.Driver
hibernate.connection.url=jdbc:mysql://localhost:3306/reportserver
hibernate.connection.username=rs
hibernate.connection.password=rs

Note the custom dialect net.datenwerke.rs.utils.hibernate.MySQL5Dialect.

Example config for MariaDB

# MariaDB
hibernate.dialect=net.datenwerke.rs.utils.hibernate.MariaDbDialect
hibernate.connection.driver_class=org.mariadb.jdbc.Driver
hibernate.connection.url=jdbc:mariadb://localhost:3306/reportserver
hibernate.connection.username=rs
hibernate.connection.password=rs

Example config for PostgreSQL

# PostgreSQL
hibernate.dialect=net.datenwerke.rs.utils.hibernate.PostgreSQLDialect
hibernate.connection.driver_class=org.postgresql.Driver
hibernate.connection.url=jdbc:postgresql://localhost/postgres
hibernate.connection.username=rs
hibernate.connection.password=rs
hibernate.connection.autocommit=false

Example config for Oracle

# Oracle
#
# Select ONE of the following dialects depending on your Oracle version
#
hibernate.dialect=net.datenwerke.rs.utils.hibernate.Oracle10gDialect
# 	hibernate.dialect=net.datenwerke.rs.utils.hibernate.Oracle12cDialect
#
hibernate.connection.driver_class=oracle.jdbc.driver.OracleDriver
hibernate.connection.url=jdbc:oracle:thin:@localhost:1521:MYDB
hibernate.connection.username=rs
hibernate.connection.password=rs
hibernate.connection.autocommit=false

Example config for SQL Server

# SQL Server
hibernate.dialect=net.datenwerke.rs.utils.hibernate.SQLServer2008Dialect
hibernate.connection.driver_class=com.microsoft.sqlserver.jdbc.SQLServerDriver
hibernate.connection.url=jdbc:sqlserver://localhost/sqlserver:1433;databaseName=mydb
hibernate.connection.username=rs
hibernate.connection.password=rs
hibernate.connection.autocommit=false

Note, that the JDBC driver corresponding to your database must be copied to the directory

path_to_webapps/reportserver/WEB-INF/lib or to your external-configuration directory.

Hibernate uses the C3P0 connection pool. The following properties allow to configure C3P0 as used by Hibernate. Note that this does not have any effect on the connection pool used by ReportServer for handling reporting.

hibernate.c3p0.acquire_increment=5
hibernate.c3p0.idle_test_period=60
hibernate.c3p0.timeout=3600
hibernate.c3p0.max_size=30
hibernate.c3p0.max_statements=0
hibernate.c3p0.min_size=5

See also http://www.mchange.com/projects/c3p0/index.html#configuration.

The most commonly used properties are:

The config file reportserver.properties contains settings which are needed at ReportServer startup time as well as settings concerning cryptographic functionality. All properties are stored as attribute value pairs.

Excerpt from the reportserver.properties file

	rs.crypto.pbe.passphrase = The Passphrase
	rs.crypto.pbe.keylength = 128

Passwords (such as, for example, datasource passwords ) that are stored in ReportServer will be encrypted. ReportServer uses AES and password based encryption. For this, you need to configure the following properties:

-- rs.crypto.pbe.salt

the salt that is used on key generation by the password based encryption method. This value should be set to a long random string.

-- rs.crypto.pbe.keylength

The key size used. Keep in mind that key sizes over 128 require the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. For more information, see http://www.oracle.com/technetwork/java/javase/downloads/index.html.

For secure storage of user passwords ReportServer uses the salted HMAC construction.

-- rs.crypto.passwordhasher.hmac.passphrase

Defines the static part of the salt for the salted HMAC construction. This value should be set to a long random string.

ReportServer supports several methods for user authentication. The different methods can also be combined.

-- rs.authenticator.pams

This parameter defines which authentication methods are to be used. The individual values are separated by a colon.

Note that the default PAMs usually come in two variants, one being called Authoritative, e.g. UserPasswordPAMAuthoritative, or LdapPAMAuthoritative. The difference between the two variants (the non-authoritative and the authoritative variant) is how they handle the case where they cannot find the necessary information within the provided list of tokens. The authoritative version then denies access, while the non-authoritative version opts for letting someone else decide (can't tell, let another PAM in the list decide). More details on this can be found in the Script Guide.

The following authenticator modules are available

net.datenwerke.rs.authenticator.service.pam.UserPasswordPAM

This is the standard mechanism and allows users to authenticate using a username and password. Note: with this authentication method username and password are sent to the server in the clear. Thus, this method should only be used over a secure channel (such as TLS/SSL). If you are not in a secured environment choose the ChallengeResponsePAM instead.

net.datenwerke.rs.authenticator.service.pam.IPRestrictionPAM

With this method you can restrict the set of IP addresses that can access ReportServer. The allowed address ranges are configured in rs.authenticator.iprestriction.addresses. The individual values are separated by a colon. Example: rs.authenticator.iprestriction.addresses = 127.0.0.1/32:192.168.1.0/24

net.datenwerke.rs.authenticator.service.pam.EveryoneIsRootPAM

This method will disable authentication and log in all users as root.

net.datenwerke.rs.authenticator.cr.service.pam.ChallengeResponsePAM

This method is similar to the UserPasswordPAM but the password is transmitted securely to the server. In cases where the connection is not secured via SSL this is the recommended authentication method. Note though, that this requires the client browser to perform cryptographic tasks which may be slow on non-up-to-date browsers.

net.datenwerke.rs.authenticator.service.pam.ClientCertificateMatchEmailPAM

If your organization uses x509 certificates, you can use this method to allow users to log in with their client certificates.

net.datenwerke.rs.ldap.service.ldap.pam.LdapPAM

If your organization uses LDAP and you want to allow LDAP authentication, you can use this method to allow users to log in with their LDAP credentials. Note that you previously have to import your LDAP users as described in the Admin Guide: https://reportserver.net/en/guides/admin/chapters/Integrating-ReportServer-with-an-Active-Directory-using-LDAP/

rs.authenticator.pam.ClientCertificateMatchEmailPAM.debug

This parameter allows to enable debug mode for client certificate authentication.

-- rs.authenticator.blockroot

Setting this to true disables direct access using the root user. This is recommended for production environments. Note that you can switch to the root user using sudo if you need to perform administrative tasks (and you have the corresponding privileges). Further information on sudo can be found in the administration guide.

rs.install.basedata

Setting this to true installs base data if the database is empty, i.e. during a first run. This includes the audit log and other data.

rs.scripting.disable

If this property is set to true, scripting is completely disabled, so no scripts are run, including the onlogin and onstartup scripts. Thus, should you find yourself locked out of ReportServer, you can disable any scripts via this property. Since no scripts will be executed you can then login correctly to ReportServer.

rs.scheduler.disable

You can completely disable the scheduler by setting this property to true. If the property is set to true both in reportserver.properties and the analogous property is also set to true in /fileserver/etc/scheduler/scheduler.cf, the property set in reportserver.properties is taken into account, while the one set in /fileserver/etc/scheduler/scheduler.cf is ignored. This allows you to completely avoid running scheduled jobs if you don't have the possibility to log in and disable the scheduler quickly enough before any jobs are being executed.