X-Road 7 will be backward compatible on the interface level with X-Road 6 since there are no changes in the Message Protocol for SOAP and the Message Protocol for REST. Upgrading the Security Server software is enough, and no changes to the connected information systems are required. However, the Service Metadata Protocol for REST and the Security Server REST management API have some changes that might not be fully backward compatible depending on the client application. Also, some Security Server's configuration changes are not backward compatible, and manual actions may be necessary depending on the current configuration. This blog post provides more information about the backward-incompatible changes in the configuration.

A new configuration file for overrides

X-Road 7 will change how some configuration overrides are handled by X-Road system services, e.g., proxy, signer, etc. The changes make the configuration more secure and more consistent. Besides the Security Server, the changes affect the Central Server and Configuration Proxy too.

In version 6, the "/etc/xroad/services/local.conf" file is used to override the environment variables for X-Road system services, e.g., memory allocation for proxy and signer. The problem with the implementation is that the configuration file is an executable that may also contain scripts and code in addition to the configuration overrides. Since the file is executed during restore, it enables code execution as a part of the restore process.

In X-Road 7, the configuration override mechanism will be changed to define the overrides in a non-executable properties file. Starting from X-Road 7.0.0., the properties file "/etc/xroad/services/local.properties" is used to override X-Road's environment variables. The file may contain configuration overrides only to predefined environment variables, and everything else is ignored.

Changes in environment variable names

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 customising memory allocation for proxy in X-Road 6 and X-Road 7:

X-Road 6

File "/etc/xroad/services/local.conf":

PROXY_PARAMS="$PROXY_PARAMS -Xms200m -Xmx2000m "

X-Road 7

File "/etc/xroad/services/local.properties":

XROAD_PROXY_PARAMS=-Xms200m -Xmx2000m

Here's a list of the X-Road-related environment variables and their names in different X-Road versions.

  
    X-Road 6
    X-Road 7
  
    XROAD_PARAMS
    XROAD_PARAMS
  
    SIGNER_PARAMS
    XROAD_SIGNER_PARAMS
  
    ADDON_PARAMS
    XROAD_ADDON_PARAMS
  
    CONFCLIENT_PARAMS
    XROAD_CONFCLIENT_PARAMS
  
    CONFPROXY_PARAMS
    XROAD_CONFPROXY_PARAMS
  
    JETTY_PARAMS
    XROAD_JETTY_PARAMS
  
    MONITOR_PARAMS
    XROAD_MONITOR_PARAMS
  
    OPMON_PARAMS
    XROAD_OPMON_PARAMS
  
    PROXY_PARAMS
    XROAD_PROXY_PARAMS
  
    PROXY_UI_API_PARAMS
    XROAD_PROXY_UI_API_PARAMS
  
    SIGNER_CONSOLE_PARAMS
    XROAD_SIGNER_CONSOLE_PARAMS

Other changes that affect configuration

In addition, there are some changes in the backup and restore features that affect the configuration too. Permissions for all the restored files are set to safe, constant values during a restore which means that permissions in the backup file are ignored. Also, the Security Server database backup format has changed, and the new format prevents the execution of arbitrary commands during restore. All the changes related to the Security Server backup encryption will be covered in a separate blog post together with other new encryption features.

What happens when I upgrade to X-Road 7?

Unfortunately, the changes on the Security Server are backward incompatible. It means that backup files generated on X-Road 6 Security Server cannot be restored on X-Road 7 Security Server. However, the changes on the Central Server are backward compatible.

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.

Also, in version 7, the backups no longer contain other ".conf" files located in the "/etc/xroad/services" directory. Those files are system configuration files that should never be manually modified since X-Road version upgrades always overwrite them. In case they're lost or corrupted, it's enough to re-install the X-Road packages. However, if the files have been manually modified, all the modifications are lost in case of restore.

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. However, if the "/etc/xroad/services/local.conf" configuration file isn't used in X-Road 6, no actions are required.The migration includes changing the variable names to the new "XROAD_" prefixed format and updating the values according to the new properties format. In case the old "/etc/xroad/services/local.conf" configuration file contains something other than modifications to X-Road-related environmental variables, the changes must be handled in some other way. The new configuration override mechanism doesn't support additional configuration changes.

When both old and new configuration files exist

Also, the new and old configuration files can coexist side by side. When both "local.conf" and "local.properties" files exist, "local.properties" is applied first, and "local.conf" is applied 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" if 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:

When "/etc/xroad/services/local.properties" contains:

XROAD_SIGNER_PARAMS=-Dprop1=newValue1 -Dprop2=newValue2

And "/etc/xroad/services/local.conf" contains:

SIGNER_PARAMS="$SIGNER_PARAMS -Dlegacy=true"

XROAD_SIGNER_PARAMS="$XROAD_SIGNER_PARAMS -Dprop1=oldValue1   -Dlegacy=false"

The resulting values for different "XROAD_SIGNER_PARAMS" related properties are:

prop1=oldValue1
prop2=newValue2
legacy=false

More detailed instructions for the migration are provided in the X-Road 7 Migration Guide.