Table of contents
This document discusses the changes needed to migrate to the next major version of X-Road. The upgrade is possible from version 6.26.0. Please read through the release notes of each version upgrade separately to gain an understanding of the potential breaking changes.
The changes listed under breaking changes require actions from the administrator. The changes listed under notable new features do not require direct action but enable an enhanced X-Road experience. features and bug fixes included in this release are not listed in this guide. They can be found in the X-Road 7.0.0 release notes instead.
2 Breaking changes
2.1 Service configuration changes
In the previous versions of X-Road, the service configuration overrides have been stored in /etc/xroad/services/local.conf. The file can contain environment variables and executable code which is a security problem.
In X-Road 7, the service configuration override mechanism is changed. The overrides are stored in non-executable /etc/xroad/services/local.properties. The file may only contain configuration overrides to predefined environment variables and everything else is ignored. Also, the format and the names of X-Road's environment variables will be different. Starting from version 7.0.0, all the variables are prefixed with XROAD_. For example, the difference in customizing memory allocation for proxy in X-Road 6 and X-Road 7:
PROXY_PARAMS="$PROXY_PARAMS -Xms200m -Xmx2000m "
Here's a list of the X-Road-related environment variables and their names in different X-Road versions.
Old name (X-Road 6)
New name (X-Road 7)
Despite the changes, when upgrading from version 6 to 7, all overrides defined in /etc/xroad/services/local.conf will continue to work as before, including the old environmental variable names. However, starting from X-Road 7.0.0, the backups no longer contain the /etc/xroad/services/local.conf file, but instead the /etc/xroad/services/local.properties file will be included. It means that in case a Central Server or Security Server is restored from a backup, all local configuration overrides defined in /etc/xroad/services/local.conf are lost. Security Server user interface and command-line scripts related to backups warn about this.
It is strongly recommended to migrate all configuration overrides to the new /etc/xroad/services/local.properties file when upgrading from version 6 to 7. There's no automation in the migration and therefore, migrating the configuration overrides must be done manually by the administrator.
Also, the new and old configuration files can co-exist side by side. When both local.conf and local.properties files exist, local.properties is applied first and local.conf second. However, local.properties can only append to the new variables (XROAD_*) while local.conf can change any parts of the configuration. As a result, values defined in local.conf overwrite values defined in local.properties in case the same property is defined in both files. However, non-overlapping values defined in local.properties are still applied. Also, in case both old and new variable names (e.g., SIGNER_PARAMS, XROAD_SIGNER_PARAMS) are used in local.conf, the new variable is applied. For example:
"$XROAD_SIGNER_PARAMS -Dprop1=oldValue1 -Dlegacy=false"
The resulting values for different XROAD_SIGNER_PARAMS related properties are:
In X-Road 7, the /etc/xroad/services/local.properties file must have one environment variable per line and the properties related to the variable cannot be splitted over multiple lines using "\".
2.1.2 Steps to migrate the service configuration
- After upgrading the Security Server to version 7.0.0, connect to the server using a command-line terminal. Check if there is a file /etc/xroad/services/local.conf. If not, there is nothing to migrate and you can skip the rest of the steps. If there is, check the file contents e.g. cat /etc/xroad/services/local.conf Example output follows.
SIGNER_PARAMS="$SIGNER_PARAMS -Xms50m -Xmx200m"
2. The first SIGNER_PARAMS can be easily migrated to the new properties file, see below. The second line with JAVA_HOME has to be handled outside the X-Road configuration files e.g. move it to an operating system environment variable.
3. After the variables have been migrated, delete the old configuration file e.g. rm /etc/xroad/services/local.conf, and restart the xroad-* services or the Security Server host server.
2.2 Old configuration backups not supported on the Security Server
The Security Server configuration backup format has changed to prevent the execution of arbitrary commands during restore. Permissions for all the restored files are set to safe constant values during the restore which means that permissions in the backup file are ignored.
. It means that backup files generated on X-Road 6 Security Server cannot be restored on X-Road 7 Security Server. However, the changes in the Central Server are backward compatible.
Before upgrading Security Server, take a backup using some other means. The method varies depending on your platform. For virtual machines, it is standard to have a possibility to take snapshots. Cloud-based servers usually have a method to snapshot the disk contents. If the security server upgrade fails for some reason, you have a way to restore the old state.
2.3 Message log archiving moved to a separate process
Security Server message log archiving has been moved to a separate process xroad-addon-messagelog.service that logs into /var/log/xroad/messagelog-archiver.log. Monitoring systems need to be configured to take into account the new service and the log file in addition to the old ones.
No separate action is needed due to this change for new installations. After upgrading to 7.0.0 on RHEL platform, the new service needs to enabled (systemctl enable xroad-addon-messagelog) and started (systemctl start xroad-addon-messagelog) separately.
3 Notable new features
3.1 Data encryption at rest
X-Road 7.0.0 will introduce new security features for protecting data at rest on the Security Server. The new features are:
- Encrypt backup files
- Verify integrity of backup files on backup file upload and before running restore
- Encrypted message payload in message log database
- Encrypted message log archives
- Group message log archives by member or subsystem
- Message logging can be fully disabled
Data exported and imported to/from Security Server can be encrypted and/or signed using GnuPG. Signing and encryption are optional - it is possible to configure the Security Server so that no encryption takes place.
Data encryption, signing, decrypting, and verification are performed by launching an external GnuPG process and interpreting the generated output. The database encryption is implemented in Java code instead.
The required keys are stored in GPG key rings. Security Server's internal keys that are used by default are generated automatically. Member-specific keys are manually managed by the administrator.
All the encryption-related configuration operations require shell access to the Security Server.
New encryption keys on the Security Server
1. Internal GPG key pair
- Created automatically during Security Server initialization process or version upgrade.
- The private key is used to:
- sign backup files
- sign message log archive files when message log archive encryption is enabled
- decrypt backup files during restore
- The public key is used to:
- encrypt backup files when backup encryption is enabled
- encrypt message log archive files when message log archive encryption is enabled and archives are not encrypted with a per-member key
- verify the integrity of a backup file during restore
- To externally verify backup or message log archive file integrity, the administrator has to manually export the public key
- Verification can then be done using any standard PGP tools
- Not included in the Security Server backups
2. Backup/restore GPG keys
- Created manually by the Security Server administrator
- The corresponding private keys:
- are managed externally by the Security Server administrator
- can be used to decrypt the backups outside of the Security Server, e.g., in case the Security Server's internal key pair is lost.
- Included in the Security Server backups by default
3. Database encryption key
- The encryption key that is used to encrypt message body in the message log database when database encryption is enabled
- Encrypted message body is stored in the new ciphermessage column and the message column is left empty
- Created manually by the Security Server administrator
- Included in the Security Server backups if stored under /etc/xroad, but not in /etc/xroad/gpghome
- The location is defined by the Security Server administrator when enabling database encryption
4. Archive GPG keys
- Additional per-member public keys that are used to encrypt message log archive files when message log archive encryption and grouping are enabled
- The keys are member-specific and they are used to encrypt archives owned by a specific member
- The corresponding private keys are managed externally by the Security Server administrator
- The private keys can be used to decrypt the message log archive files outside of the Security Server
- Not included in the Security Server backups by default.
3.1.1 Encrypt backup files and verify their integrity
Security Server configuration backups are always signed, but backup encryption is initially turned off. When encryption is enabled, backup files are encrypted when stored on disk encrypted. This applies to both automatically created and user-created backups. When it comes to user-created backups, the configuration applies to Security Server UI and REST management API.
Security Server verifies the backup archive consistency during the restore operation. The integrity verification requires that the original Security Server internal key pair is available. In case the internal key pair is lost, the restore operation can't be performed in the user interface or through the API, but has to be executed from the command line with appropriate options that enable skipping integrity verifications.
The backup encryption configuration is described in the Security Server User Guide.
3.1.2 Encrypted message payload in message log database
The message body can be optionally encrypted, but it is switched off by default. The encryption is fully transparent to all the external interfaces, e.g., the signed document download service.
There are two separate columns in the database for plain text (message) and encrypted (ciphermessage) message body. The message body is always stored in one of the two columns depending on the configuration. The other column is left empty. When message log database encryption is enabled/disabled, the change doesn't affect already existing records in the database. For example, when message log database encryption is enabled, all the records after the change will be encrypted and stored in the ciphermessage column. Instead, all the records stored before the change will remain in plain text in the message column.
During message log archiving, the message body is decrypted and it's written to the archive file in plain text. Message log archive file encryption is configured separately, and when it's enabled, the whole archive file is signed and encrypted.
Security Server User Guide.
3.1.3 Message log archive encryption and grouping
Message log archive encryption and grouping can be configured separately. By default, both are disabled. Grouping and encryption are enabled/disabled on a Security Server level - they are either enabled or disabled for all the members and subsystems. It's not possible to enable/disable neither of them for selected members or subsystems only.
Message grouping can be configured by member or subsystem. By default, grouping is disabled and all archive files go to the same default group. Message log archive files that belong to the same group are chained. However, chains may have holes in them in case grouping is turned on and off, or the grouping level (none/member/subsystem) is changed.
Encryption can be combined with grouping so that each member's messages are stored in separate files encrypted with separate member-specific keys.
When message log archive encryption is enabled, the signed document download service returns log records encrypted.
The message log archive encryption is described in the Security Server User Guide.
3.1.4 Message logging can be fully disabled
Security Server can now be installed with the message log addon disabled. When the message log addon is disabled, no messages are logged and no timestamping service is needed. This is an optional step during the installation, but default the addon is still installed.
Information on how to disable the addon is available at:
3.2 Update Central Server BDR support
X-Road 7 gives more control to the administrators over the Central Server installation/upgrade process. Although BDR is not a direct dependency of X-Road anymore, the changes enable using the latest versions of BDR to implement the Central Server's high availability.
3.2.1 Remove references to BDR1
X-Road 6.26.0 had some direct references to BDR version 1 making it difficult to use later BDR releases. The references have now been removed making the Central Server high-availability solution more technology agnostic.
3.2.3 Possibility to skip automatic database migrations and run them manually on the command line
When the Central Server is installed or upgraded, it's possible to skip the automatic database migrations performed by the installer. Additionally, the instructions guide how the migrations can be run manually when needed. See Central Server Installation Guide.
Starting from X-Road 7.0.0, it is possible to install a security server without a local PostgreSQL server. It has been possible to configure a security server to use a remote database earlier but the locally installed PostgreSQL database server remained installed in any case. This optimizes the security server's resource usage further.
Installing Security Server with a remote database is described in the installation guides for Ubuntu and RHEL.
3.4 Possibility to change PIN code on the Security Server
Security Server makes it possible to change the PIN code that was chosen during the initial configuration. The change needs to be performed on the command line using the signer-console tool.
3.5 Run security server on Java 11 by default
The security server now runs on Java 11 platform by default. To migrate an existing installation to Java 11, see the following steps described in X-Road Knowledge Base. Security Server 7.0.0 also displays the used Java version in the user interface's diagnostics view.
3.6 Improvements to diagnostics
The new Security Server improves the diagnostics view of the user interface.
- Diagnostics now shows Java version information
- Diagnostics status now shows whether TSA is able to process timestamping requests. Previously status only indicated whether TCP connections to TSA succeeded.
3.7 Version upgrade is possible only from the two previous versions
The official support policy for X-Road installations is that upgrades from the previous two versions are tested by the core development team and guaranteed to work. X-Road 7 enforces this policy in the installation packages so that upgrades over three or more versions are not directly allowed but have to be done in steps. For example, an upgrade from 6.24.0 to 7.0.0 does not work directly. The supported path is to first upgrade to 6.26.0 and from there to 7.0.0. There's more information about this in the installation guide.
Security Server's REST metadata services listMethods and allowedMethods have been updated to include more information in their responses. The responses now include also the REST API type (REST or OPENAPI) and the list of endpoints.