X-Road: System Parameters User Guide

Version: 2.85 Doc. ID: UG-SYSPAR

• License

• X-Road: System Parameters User Guide
  • Table of Contents
  • License
  • 1 Introduction
    • 1.1 Terms and abbreviations
    • 1.2 References
  • 2 Changing the System Parameter Values
    • 2.1 Changing the System Parameter Values in Configuration Files
    • 2.2 Changing the System Parameter Values in the Central Server Database
  • 3 Security Server System Parameters
    • 3.1 Common parameters : [common]
    • 3.2 Proxy parameters: [proxy]
    • 3.3 Proxy User Interface parameters: [proxy-ui]
    • 3.4 Signer parameters: [signer]
    • 3.5 Anti-DOS parameters: [anti-dos]
    • 3.6 Configuration Client parameters: [configuration-client]
    • 3.7 Message log add-on parameters: [message-log]
      • 3.7.1 Note on logged X-Road message headers
    • 3.8 Environmental monitoring add-on configuration parameters: [env-monitor]
    • 3.9 Management REST API parameters: [proxy-ui-api]
  • 4 Central Server System Parameters
    • 4.1 System Parameters in the Configuration File
      • 4.1.1 Common parameters: [common]
      • 4.1.2 Center parameters: [center]
      • 4.1.3 Center parameters: [admin-service]
      • 4.1.4 Signer parameters: [signer]
      • 4.1.5 Center parameters: [registration-service]
      • 4.1.6 Center parameters: [management-service]
    • 4.2 System Parameters in the Database
  • 5 Configuration Proxy System Parameters
    • 5.1 Configuration proxy module parameters: [configuration-proxy]
    • 5.2 Signer parameters: [signer]
  • 6 Adding command line arguments
    • 6.1 The configuration file
    • 6.2 Legacy configuration file support in X-Road v7

This document is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/.

This document describes the system parameters of the X-Road components – of the security server, the central server and the configuration proxy. Additionally, changing the default values of the system parameters are explained. Please note the term 'vanilla' in the documentation. In X-Road context vanilla means the X-Road without any of the country specific customizations, settings etc. The vanilla version of X-Road security server is installed with xroad-securityserver package. The country specific versions are installed with xroad-securityserver-XX where XX is the country code f.ex. FI or EE.

See X-Road terms and abbreviations documentation [TA-TERMS].

1. [INI] INI file, http://en.wikipedia.org/wiki/INI_file.
2. [CRON] Quartz Scheduler CRON expression, http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/tutorial-lesson-06.html.
3. [PR-MESS] X-Road Message Protocol v. 4.0.
4. [PR-TARGETSS] Security Server Targeting Extension for the X-Road Message Protocol.
5. [PR-SECTOKEN] Security Token Extension for the X-Road Message Protocol.
6. [TA-TERMS] X-Road Terms and Abbreviations.
7. [CRONMAN] http://linux.die.net/man/8/cron.
8. [CRONHOW] Cron format specifications https://help.ubuntu.com/community/CronHowto.
9. [PR-REST] X-Road Message Protocol for REST v. 1.0.
10. [IG-CSHA] X-Road 7. Central Server High Availability Installation Guide. Document ID: IG-CSHA
11. [UG-SS] X-Road 7. Security Server User Guide. Document ID: UG-SS

The system parameters specify various characteristics of the system, such as port numbers, timeouts and paths to files on disk. The system parameters of the X-Road components are mainly stored in configuration files. Additionally, X-Road central server stores some system parameters in the database.

Changing the values of the system parameters is strongly discouraged, since it may cause unexpected system behaviour.

The configuration files are INI files [INI], where each section contains parameters for a particular server component.

In order to override the default values of system parameters, create or edit the file

/etc/xroad/conf.d/local.ini

Each system parameter affects a specific server component. To change the value of a system parameter, a section for the affected component must be created in the INI file. The name-value pairs of the system parameters for that component are written under the section, one pair per line.

The following format is used for the sections:

[ServerComponent]
SystemParameterName1=Value1
SystemParameterName2=Value2

For example, to configure the parameter client-http-port for the proxy component, the following lines must be added to the configuration file:

[proxy]
client-http-port=1234

Multiple parameters can be configured under the same section:

[proxy]
client-http-port=1234
server-listen-port=20000

NB! Changing the parameter values in the configuration files requires restarting of the server.

WARNING! The value of the parameter is not validated, thus care must be taken when changing the value. For example, setting the port number to a non-numeric value in the configuration will cause the system to crash.

The central server database can be accessed with the psql utility using the following command (password is defined in /etc/xroad/db.properties):

psql -U centerui -h localhost centerui_production

The default value of a system parameter can be overridden by adding the parameter name and value to the system_parameters table:

INSERT INTO system_parameters (key, value, created_at, updated_at) VALUES ('parameter_name', 'parameter_value', (now() at time zone 'utc'), (now() at time zone 'utc'));

To edit the value of a system parameter already inserted into the system_parameters table:

UPDATE system_parameters SET value = '*parameter_value*', updated_at = (now() at time zone 'utc') WHERE key = 'parameter_name';

To restore the default value of a system parameter, delete the parameter from the system_parameters table:

DELETE FROM system_parameters WHERE key = 'parameter_name';

NB! Modifying or deleting system parameters other than the ones listed in section System Parameters in the Database will cause the system to crash.

This chapter describes the system parameters used by the components of the X-Road security server. For instructions on how to change the parameter values, see section Changing the System Parameter Values in Configuration Files.

Note about database-properties file: Management REST API module uses the same database-properties file, but limits the configuration parameters usage:

• hibernate.dialect cannot be changed, it is fixed to a custom PostgreSQL dialect.
• out of hibernate.connection.* parameters, only url, username and password can be configured.

This in practice limits configurability to different kinds of PostgreSQL database configurations, and it is not possible to use for example MySQL as a data store for REST API module.

Proxy-ui has been removed in version 6.24 and it's parameters are not used anymore.

proxy-ui-api parameters replace the old [proxy-ui] parameters.

If the messagelog add-on has the message body logging disabled, only a preconfigured set of the SOAP headers and/or REST HTTP headers will be included in the message log.

SOAP

The logged SOAP headers are the X-Road message headers listed in Chapter 2.2 of the X-Road Message Protocol document [PR-MESS], as well as the representedParty extension of the X-Road protocol described in the extension's XML schema. The security server targeting extension for the X-Road message protocol [PR-TARGETSS] or the Security Token Extension [PR-SECTOKEN] will not be included in the message log.

REST

The logged HTTP headers are the X-Road HTTP headers listed in Chapter 4.3 of the X-Road Message Protocol for REST document [PR-REST], including the security server targeting extension for the X-Road message protocol [PR-TARGETSS]. All other HTTP headers are excluded from the message log.

NOTE: strict-identifier-checks default value is true for new installations starting from version 7.3.0. It is set to false in local.ini during upgrade process if version installed before upgrade is less than 7.3.0.

Configurable SSL connection parameters are those Spring Boot's common application properties that start with server.ssl.

ssl.properties can be used to override any server.ssl.* property, also those that do not have default values. However, the result of merging default properties and overridden / new properties needs to be a functional combination.

Default values for the SSL properties are

Management REST API module uses database-properties configuration from the proxy parameters, with some additional limitations on configurability (see details in proxy chapter).

The system parameters described in this chapter are used by the X-Road central server, except for the parameters ocspFreshnessSeconds and timeStampingIntervalSeconds.

The values of ocspFreshnessSeconds and timeStampingIntervalSeconds are distributed to the security servers via the global configuration. These parameters determine the interval of calling OCSP responder services and time-stamping services (respectively) by the security servers.

For instructions on how to change the parameter values, see section Changing the System Parameter Values in Configuration Files.

NOTE: strict-identifier-checks default value is true for new installations starting from version 7.3.0. It is set to false in local.ini during upgrade process if version installed before upgrade is less than 7.3.0.

This section describes the system parameters used by the X-Road central server. For instructions on how to change the parameter values, see section Changing the System Parameter Values in the Central Server Database.

This chapter describes the system parameters used by the X-Road configuration proxy.

[1] Default value for proxy.client-tls-ciphers.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_DHE_RSA_WITH_AES_128_GCM_SHA256, TLS_DHE_RSA_WITH_AES_128_CBC_SHA256, TLS_DHE_RSA_WITH_AES_256_CBC_SHA256, TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

[2] Default value for proxy.xroad-tls-ciphers.

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_DHE_RSA_WITH_AES_256_CBC_SHA256

(see https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider for possible values)

Note. OpenJDK 8 on RHEL 7 supports ECDHE key agreement protocol starting from RHEL 7.3. In RHEL 7 versions prior to RHEL 7.3 only DHE cipher suites are supported.

Sometimes you may need to provide command line arguments for Security Server, Central Server or Configuration Proxy, in order to override some parameters. For example if you wish to increase Java's maximum heap size, you can do it with the properties file /etc/xroad/services/local.properties. The file is also included in the backup archive file when taking a configuration backup of either Central Server or Security Server.

The file /etc/xroad/services/local.properties replaces the file /etc/xroad/services/local.conf starting from X-Road version 7.

The local.properties file's contents consists of key-value pairs such as XROAD_SIGNER_PARAMS=-XX:MaxMetaspaceSize=100m. Notice that you cannot use quotes in the values. If you have multiple values for one key, use space to separate the values e.g. XROAD_SIGNER_PARAMS=-Xmx100m -XX:MaxMetaspaceSize=100m. Also notice that with local.properties you can only add new parameters and override old ones – you cannot remove existing default parameters.

Example of /etc/xroad/services/local.properties with modifications that override the default Java memory parameters for Security Server:

XROAD_PROXY_PARAMS=-Xms200m -Xmx1024m

Example of /etc/xroad/services/local.properties with modifications that override the default Java memory parameters for Central Server:

XROAD_CS_ADMIN_SERVICE_PARAMS=-Xms200m -Xmx1024m

Example of /etc/xroad/services/local.properties with modifications that override the default Spring Boot parameter for Central Servers management API:

XROAD_CS_ADMIN_SERVICE_PARAMS=-Dserver.forward-headers-strategy=NONE

All possible properties to adjust in this file:

If you have upgraded from X-Road version 6 to version 7, you might still be using local.conf script file with legacy parameters (non XROAD_ prefixed parameters), which is considered deprecated in X-Road version 7. The legacy file local.conf will not be included in the configuration backups anymore – the new file local.properties will be included instead, therefore it is strongly recommended migrating to the new local.properties file.

The legacy file local.conf will still be supported along with the legacy parameters. It is possible for both files to exist side-by-side. In this case the values from local.properties are appended first and then the local.conf file gets executed as a script afterwards. Notice that if your local.conf script contains new XROAD_ prefixed parameters and old legacy parameters, the new XROAD_ prefixed parameters will always be preferred.