European Union / European Regional Development Fund / Investing in your future

Security Server Installation Guide for Ubuntu


Version: 2.19
Doc. ID: IG-SS

Version history

Date Version Description Author
01.12.2014 1.0 Initial version
19.01.2015 1.1 License information added
18.03.2015 1.2 Meta-package for security server added. Legacy securelog module removed
02.04.2015 1.3 “sdsb” change to “xroad”
27.05.2015 1.4 Some typos fixed
30.06.2015 1.5 Minor corrections done
06.07.2015 1.6 New repository address
18.09.2015 1.7 Reference data in 3.2 updated
18.09.2015 2.0 Editorial changes made
13.10.2015 2.1 Editorial changes made
10.12.2015 2.2 Updated the installing of the support for hardware tokens (2.7)
17.12.2015 2.3 Added xroad-addon-wsdlvalidator package
19.05.2016 2.4 Merged changes from xtee6-doc repo. Updated table 2.2 with p 1.12, added chapter 2.8 and updated 3.2.
30.09.2016 2.5 Added chapter „Different versions of xroad-* package after successful upgrade“.
07.12.2016 2.6 Added operational data monitoring packages. 2 GB RAM -> 3 GB RAM
23.02.2017 2.7 Converted to Github flavoured Markdown, added license text, adjusted tables for better output in PDF Toomas Mölder
13.04.2017 2.8 Added token ID formatting Cybernetica AS
22.01.2018 2.8.1 Added NEE and NGO member classes Jürgen Šuvalov
25.08.2017 2.9 Update environmental monitoring installation information Ilkka Seppälä
15.09.2017 2.10 Added package with configuration specific to Estonia xroad-securityserver-ee Cybernetica AS
05.03.2018 2.11 Added terms and abbreviations reference and document links Tatu Repo
10.04.2018 2.12 Updated chapter "Installing the Support for Hardware Tokens" with configurable parameters described in the configuration file 'devices.ini' Cybernetica AS
07.06.2018 2.12.1 Updated repository information with domain Jürgen Šuvalov
03.07.2018 2.12.2 Added network diagram and reference data for monitoring servers Jürgen Šuvalov
08.08.2018 2.12.3 Editorial changes Jan Raik
13.08.2018 2.12.4 Package name fix Taavi Meinberg
14.10.2018 2.13 Update package repository address Petteri Kivimäki
25.10.2018 2.14 Add RHEL7 as supported platform, update section 2.2 Reference data Petteri Kivimäki
15.11.2018 2.15 Add Ubuntu 18 installation instructions Jarkko Hyöty
12.12.2018 2.12.5 Added managment security servers' IPs Jan Raik
03.01.2019 2.12.6 Updated repository key Jan Raik
28.01.2019 2.16 Update port 2080 documentation Petteri Kivimäki
30.05.2019 2.17 Added package installation instructions on chapter "2.4 Preparing OS" Raul Martinez
11.09.2019 2.18 Remove Ubuntu 14.04 from supported platforms Jarkko Hyöty
20.09.2019 2.19 Add instructions for using remote databases Ilkka Seppälä

Table of Contents


This document is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit

1 Introduction

1.1 Target Audience

The intended audience of this Installation Guide are X-Road Security server system administrators responsible for installing and using X-Road software. The daily operation and maintenance of the security server is covered by its User Guide [UG-SS].

The document is intended for readers with a moderate knowledge of Linux server management, computer networks, and the X-Road working principles.

1.2 Terms and abbreviations

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

1.3 References

  1. [UG-SS] Cybernetica AS. X-Road 6. Security Server User Guide. Document ID: UG-SS

  2. [TA-TERMS] X-Road Terms and Abbreviations. Document ID: TA-TERMS.

2 Installation

2.1 Supported Platforms

The security server runs on the *Ubuntu Server 18.04 Long-Term Support (LTS) operating system on a 64-bit platform. The Estonian version of the security server software is distributed as .deb packages through the official X-tee repository at

The software can be installed both on physical and virtualized hardware (of the latter, Xen and Oracle VirtualBox have been tested).

2.2 Reference Data

Note: The information in empty cells should be determined before the server’s installation, by the person performing the installation.

Caution: Data necessary for the functioning of the operating system is not included.

Ref Explanation
1.0 Ubuntu 18.04, 64-bit
3 GB RAM, 3 GB free disk space
Minimum requirements
1.1 X-Road stable package repository X-Road test package repository
1.2 The repository key
1.3 Account name in the user interface
1.4 INBOUND PORTS FROM EXTERNAL NETWORK Ports for inbound connections (from the external network to the security server)
  TCP 5500 Message exchange between security servers. Recommended to use IP filtering (whitelisting only RIA IP's and partners).
  TCP 5577 Querying of OCSP responses between security servers. Recommended to use IP filtering (whitelisting only RIA IP's and partners)
1.5 OUTBOUND PORTS TO EXTERNAL NETWORK Ports for outbound connections (from the security server to the external network)
  TCP 5500 Message exchange between security servers
  TCP 5577 Querying of OCSP responses between security servers
  TCP 4001 Communication with the central server
  TCP 80 Downloading global configuration from central server.
  TCP 80,443 Most common OCSP and time-stamping services.
1.6 INBOUND PORTS FROM INTERNAL NETWORK Ports for inbound connections (from the internal network to the security server)
  TCP 4000 User interface (local network). Must not be accessible from the Internet!
  TCP 80, 443 Information system access points (in the local network)
Must not be accessible from the Internet without strong authentication!
  TCP 9011 Operational data monitoring daemon JMX listening port
  TCP 9999 Environmental monitoring daemon JMX listening port
1.7 OUTBOUND PORTS TO INTERNAL NETWORK Ports for outbound connections (from the security server to the internal network)
  TCP 80, 443 Producer information system endpoints
  TCP 2080 Message exchange between security server and operational data monitoring daemon (by default on localhost)
1.8 Security server internal IP address(es) and hostname(s)
1.9 Security server public IP address, NAT address
1.10 <by default, the server’s IP addresses and names are added to the certificate’s Distinguished Name (DN) field> Information about the user interface TLS certificate
1.11 <by default, the server’s IP addresses and names are added to the certificate’s Distinguished Name (DN) field> Information about the services TLS certificate

2.3 Network Diagram

The following network diagram is an example of a simple stand-alone Security Server setup. Attention should be paid when configuring the firewall of your Security Server, as misconfigurations (e.g. exposing port 80/tcp to the public internet) can leave your server vulnerable.

Allowing incoming connections from the Monitoring Security Server on ports 5500/tcp and 5577/tcp (monitoring server IP's) is necessary for the X-Road Center to be able to monitor the ecosystem and provide statistics and support for Members.

Caution: The enabling of auxiliary services which are necessary for the functioning and management of the operating system (such as DNS, NTP, and SSH) stay outside the scope of this guide.

network diagram

2.3.1 RIA IP's for Whitelisting

Type EE - production ee-test ee-dev
Central Server
Central Monitoring Server
Management Security Server

2.4 Requirements for the Security Server

Minimum recommended hardware parameters:

Requirements to software and settings:

2.5 Preparing OS

2.6 Installation

To install the X-Road security server software, follow these steps.

  1. Add to /etc/apt/sources.list.d/xroad.list the address of X-Road package repository (reference data: 1.1) and the nginx repository:

    deb bionic main
  2. Add the X-Road repository’s signing key to the list of trusted keys (reference data: 1.2):

    curl | sudo apt-key add -
  3. (Optional step) If you want to use remote database server instead of the default locally installed one, you need to pre-create a configuration file containing the database administrator master password. This can be done by performing the following steps:

     sudo touch /etc/
     sudo chown root:root /etc/
     sudo chmod 600 /etc/

    Edit /etc/ contents. See the example below. Replace parameter values with your own.

     postgres.connection.password = 54F46A19E50C11DA8631468CF09BE5DB
  4. Issue the following commands to install the security server packages (use package xroad-securityserver-ee to include configuration specific to Estonia; use package xroad-securityserver-fi to include configuration specific to Finland):

    sudo apt-get update
    sudo apt-get install postgresql
    sudo apt-get install xroad-securityserver-ee

Upon the first installation of the packages, the system asks for the following information.

The meta-package xroad-securityserver-ee also installs metaservices module xroad-addon-metaservices, messagelog module xroad-addon-messagelog, operational data monitoring modules xroad-addon-opmonitoring, xroad-opmonitor and WSDL validator module xroad-addon-wsdlvalidator.

2.7 Post-Installation Checks

The installation is successful if system services are started and the user interface is responding.

2.8 Installing the Support for Hardware Tokens

To configure support for hardware security tokens (smartcard, USB token, Hardware Security Module), act as follows.

  1. Install the hardware token support module using the following command:

    sudo apt-get install xroad-addon-hwtokens
  2. Install and configure a PKCS#11 driver for the hardware token according to the manufacturer's instructions.

  3. Add the path to the PKCS#11 driver to the file /etc/xroad/devices.ini (as described in the example given in the file).

  4. After installing and configuring the driver, the xroad-signer service must be restarted:

    sudo service xroad-signer restart

If you are running a high availability (HA) hardware token setup (such as a cluster with replicated tokens) then you may need to constrain the token identifier format such that the token replicas can be seen as the same token. The token identifier format can be changed in /etc/xroad/devices.ini via the token_id_format property (default value: {moduleType}{slotIndex}{serialNumber}{label}). Removing certain parts of the identifier will allow the HA setup to work correctly when one of the tokens goes down and is replaced by a replica. For example, if the token replicas are reported to be on different slots the {slotIndex} part should be removed from the identifier format.

Depending on the hardware token there may be a need for more additional configuration. All possible configurable parameters in the /etc/xroad/devices.ini are described in the next table.

Parameter Type Default Value Explanation
enabled BOOLEAN true Indicates whether this device is enabled.
library STRING The path to the pkcs#11 library of the device driver.
library_cant_create_os_threads BOOLEAN false Indicates whether application threads, which are executing calls to the pkcs#11 library, may not use native operating system calls to spawn new threads (in other words, the library’s code may not create its own threads).
os_locking_ok BOOLEAN false Indicates whether the pkcs#11 library may use the native operation system threading model for locking.
sign_verify_pin BOOLEAN false Indicates whether the PIN should be entered per signing operation.
token_id_format STRING {moduleType}{slotIndex}{serialNumber}{label} Specifies the identifier format used to uniquely identify a token. In certain high availability setups may need be constrained to support replicated tokens (eg. by removing the slot index part which may be diffirent for the token replicas).
sign_mechanism STRING CKM_RSA_PKCS Specifies the signing mechanism. Supported values: CKM_RSA_PKCS, CKM_RSA_PKCS_PSS.
pub_key_attribute_encrypt BOOLEAN true Indicates whether public key can be used for encryption.
pub_key_attribute_verify BOOLEAN true Indicates whether public key can be used for verification.
pub_key_attribute_wrap BOOLEAN Indicates whether public key can be used for wrapping other keys.
pub_key_attribute_allowed_mechanisms STRING LIST Specifies public key allowed mechanisms. Supported values: CKM_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, and CKM_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, CKM_SHA512_RSA_PKCS_PSS.
priv_key_attribute_sensitive BOOLEAN true Indicates whether private key is sensitive.
priv_key_attribute_decrypt BOOLEAN true Indicates whether private key can be used for encryption.
priv_key_attribute_sign BOOLEAN true Indicates whether private key can be used for signing.
priv_key_attribute_unwrap BOOLEAN Indicates whether private key can be used for unwrapping wrapped keys.
priv_key_attribute_allowed_mechanisms STRING LIST Specifies private key allowed mechanisms. Supported values: CKM_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, and CKM_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, CKM_SHA512_RSA_PKCS_PSS.

Note 1: Only parameter library is mandatory, all the others are optional.
Note 2: The item separator of the type STRING LIST is ",".

2.9 Installing the Support for Environmental Monitoring

The support for environmental monitoring functionality on a security server is provided by package xroad-monitor that is installed by default. The package installs and starts the xroad-monitor process that will gather and make available the monitoring information.

2.10 Remote Database Post-Installation Tasks

Local PostgreSQL is always installed with Security Server. When remote database host is used, the local PostgreSQL can be stopped and disabled after the installation.

To stop the local PostgreSQL server

systemctl stop postgresql

To disable the local PostgreSQL server so that it does not start automatically when the server is rebooted.

systemctl mask postgresql

3 Security Server Initial Configuration

During the security server initial configuration, the server’s X-Road membership information and the software token’s PIN are set.

3.1 Prerequisites

Configuring the security server assumes that the security server owner is a member of the X-Road.

3.2 Reference Data

ATTENTION: Reference items 2.1 - 2.3 in the reference data are provided to the security server owner by the X-Road central’s administrator.

The security server code and the software token’s PIN will be determined during the installation at the latest, by the person performing the installation.

Ref Explanation
2.1<anchor file>
ee-dev - development environment
ee-test - test environment
EE - production environment
Global configuration anchor file
2.2 GOV - government
COM - commercial
NGO - non-profit
NEE - not Estonian
Member class of the security server's owner
2.3 <security server owner register code> Member code of the security server's owner
2.4 <choose security server identificator name> Security server's code
2.5 <choose PIN for software token> Software token’s PIN

3.3 Configuration

To perform the initial configuration, open the address


in a Web browser (reference data: 1.8; 1.6). To log in, use the account name chosen during the installation (reference data: 1.3).

Upon first log-in, the system asks for the following information.

If the configuration is successfully downloaded, the system asks for the following information.

4 Installation Error handling

4.1 Cannot Set LC_ALL to Default Locale

If running the locale command results in the error message

locale: Cannot set LC_ALL to default locale: No such file or directory,

then the support for this particular language has not been installed. To install it, run the command (the example uses the English language):

sudo apt-get install language-pack-en

Then, to update the system’s locale files, run the following commands (the example uses the US locale):

sudo locale-gen en_US.UTF-8
sudo update-locale en_US.UTF-8

Set operating system locale. Add following line to /etc/environment file:


After updating the system’s locale settings, it is recommended to restart the operating system.

4.2 PostgreSQL Is Not UTF8 Compatible

If the security server installation is aborted with the error message

postgreSQL is not UTF8 compatible,

then the PostgreSQL package is installed with a wrong locale. One way to resolve it is to remove the data store created upon the PostgreSQL installation and recreate it with the correct encoding.

WARNING: All data in the database will be erased!

sudo pg_dropcluster --stop 9.3 main
LC_ALL="en_US.UTF-8" sudo pg_createcluster --start 9.3 main

To complete the interrupted installation, run the command

sudo apt-get -f install

4.3 Could Not Create Default Cluster

If the following error message is displayed during PostgreSQL installation:

Error: The locale requested by the environment is invalid.
Error: could not create default cluster. Please create it manually with pg_createcluster 9.3 main –start,

use the following command to create the PostgreSQL data cluster:

LC_ALL="en_US.UTF-8" sudo pg_createcluster --start 9.3 main

The interrupted installation can be finished using

sudo apt-get -f install

4.4 Is Postgres Running On Port 5432?

If the following error message appears during installation

Is postgres running on port 5432 ?
Aborting installation! please fix issues and rerun with apt-get -f install,

check if any of the following errors occurred during the installation of PostgreSQL.

The interrupted installation can be finished using

sudo apt-get -f install

4.5 Different versions of xroad-* packages after successful upgrade

Sometimes, after using sudo apt-get upgrade command, some of the packages are not upgraded. In the following example xroad-securityserver package version is still 6.8.3 although other packages are upgraded to 6.8.5:

# sudo dpkg -l | grep xroad-
ii xroad-addon-messagelog
ii xroad-addon-metaservices
ii xroad-addon-wsdlvalidator
ii xroad-common
ii xroad-jetty9
ii xroad-proxy
ii xroad-securityserver 6.8.3-3-201605131138

apt-get upgrade command doesn’t install new packages - in this particular case new packages xroad-monitor and xroad-addon-proxymonitor installation is needed for upgrade of xroad-securityserver package.

To be sure that packages are installed correctly please use sudo apt upgrade or sudo apt full-upgrade commands.