Setting up an X-Road Security Server

Security Server Installation, Registration and Configuration

Hardware requirements

  • 64-bit dual-core Intel, AMD or compatible CPU; AES instruction set support is highly recommended

  • 2 CPU

  • 4 GB RAM

  • 10 GB free disk space (OS partition) and 20-40 GB free disk space on the “/var” partition

  • 100 Mbps network interface card

Operating System Requirements

This guide assumes one of the following:

  • Red Hat Enterprise Linux

    • RHEL7.3+

    • RHEL8+

  • Ubuntu

    • 20.04 LTS

    • 22.04 LTS

Note: Installing and configuring an X-Road Security Server requires  sudo permissions on the host.

Running in a container

Running the X-Road Security Server in a container is outside the scope of this guide, but you can refer to the official Security Server Sidecar User Guide for guidance.

Network Configuration

Check the Network Configuration sub-page.

FQDN Requirements

The FQDN of a Security Server should easily identity the Tier and Owner:

EnvironmentTierFQDN Template



xroad-dev.<member's domain>.is


Testing / QA / UAT / Staging

xroad-test.<member's domain>.is



xroad-prod1.<member's domain>.is xroad-prod2.<member's domain>.is

Installing X-Road

Provision the xroad POSIX user

The X-Road Server should be run under a dedicated POSIX user, usually named xroad

Create this user by running the following command:

sudo useradd \
--system \
--home /var/lib/xroad \
--no-create-home \
--shell /bin/bash \
--user-group \
--comment "X-Road system user" \

If that user will be used for interactive SSH log-ins, then we must ensure that the Security Server PIN (see below) doesn't get cleared (even though auto-login is configured), by running the following command:

loginctl enable-linger xroad

Follow the installation guide

NIIS maintains a guide for setting up Security Servers on Ubuntu and RHEL inside their knowlegebase, which you can find here: How to Set Up a Security Server?

While following the guide above, take care to override the official documentation with specific steps for the Icelandic environment (Straumurinn), outlined at

Certificate generation

During installation, a dialog will appear asking for host and IP information for certificate generation. The latter set of the dialog will be for configuring certificates for the xroad-proxy-ui-api.

Here it may be desirable to change the value from the auto-detected machine host name to a domain name used for accessing the Admin UI:


Once a Security Server has been successfully installed, the Admin UI can be accessed by pointing a web browser at https://SECURITYSERVER:4000/ .

Required configuration for registration

Before being able to import a Configuration Anchor, the Security Server IP and FQDN must be whitelisted by the operator of the Straumurinn X-Road Central Services.

To register a Security Server into Straumurinn, the following configuration values are required:

1. Outgoing IP Address of the Security Server

The public outgoing IP address of the server can be found with with the following command from a Security Server terminal session:

$ curl

2. FQDN of the Security Server

Refer to the section about FQDN Requirements.

3. Member's Kennitala / SSN

Registration contact

To register, an email containing the values listed above the should be sent to the operator of the Straumurinn X-Road Central Server at

Example email for registering a Security Server to Central.

Post-registration steps

Have a look at the Security Server initial configuration guide from X-Road. Some of the next steps are derived from there.

Disable message payload logging

The xroad-securityserver-is variant has the message logging disabled by default, from X-Road version 6.24.0 onwards.

Software Token PIN

Keep the the PIN secret. Keep it safe.

During the Security Server initial configuration, we need to generate a password called the "software token PIN".

The PIN is a 12 digit, alpha-numeric password:

You will be asked to supply the PIN during Initial Configuraion (see below).

Configure Auto-Login PIN entry functionality

If Auto-Login is not configured, the server will require manual entry of the Soft Token PIN during startup / restart, which can have implications for the Security Server's reliability.

For the PIN to be entered automatically when starting X-Road services, refer to the X-Road: Autologin User Guide

Test auto-login PIN entry functionality

To verify that auto-login PIN entry works as expected, you can try stopping and starting all the X-Road services like this:

for i in xroad-confclient xroad-proxy xroad-signer xroad-monitor xroad-opmonitor xroad-proxy-ui-api ;\
do \
   echo "stopping $i"; \
   sudo service $i stop; \
sudo systemctl list-units "xroad*"
for i in xroad-confclient xroad-proxy xroad-signer xroad-monitor xroad-opmonitor xroad-proxy-ui-api; \
do \
   echo "starting $i"; \
   sudo service $i start; \

Ensure if all services are up and running

sudo systemctl list-units "xroad*"

Enable health check endpoint

Refer to the Health check service configuration for information on enabling the health check endpoints.

Initial Configuration

Configuration Anchors

Start by acquiring the Configuration Anchor for the X-Road network, found here:

Next, point your browser at the Security Server, on port 4000 and log in.

Upload the environment's configuration anchor.

After anchor has been uploaded, it needs to be confirmed.

Ensure that the "Hash Generated" corresponds to the information on the Central Server.

Click [CONFIRM].

The Configuration Anchor has now been configured and should show you something like the following:

Owner Member

In the initial configuration screen input the values as follows.

Software Token PIN

  • PIN - the password that protects the security server's secret keys.

  • Repeat PIN - repeat the above PIN.

Keep the PIN secret. Keep it safe.

The initial configuration was saved successfully.

CSR certificates

The security server asks for PIN code.

Click the Please enter soft token PIN link.

Clicking the link navigates to Keys and Certificates page.

  • Click [LOG IN] on the softToken Service.

  • Enter PIN Code

  • Click [LOG IN] in the modal window.

The red error message bar should now disappear.

Final steps

Configure Timestamping Services

Go to: Settings > Timestamping Services and click [ADD]

Pick a time-stamping service from the list and click [OK.]

The message "Timestamping message added" should appear.

Configure SIGN and AUTH Keys



Click [ADD KEY]

Enter ”sign” for the "Key Label" and click [NEXT]

Fill out the form with the following values:

  • Usage: SIGNING

  • Client: Select the relevant Client from the dropdown.

  • CSR Format: PEM


Click [DONE]

The CSR should be downloaded to browser's download folder.

The AUTH key

If you are not already there, start by navigating to "KEYS AND CERTIFICATES"->"SIGN AND AUTH KEYS" of the Admin UI (see above).

Click [ADD KEY]

Enter “auth” and click [NEXT]

Choose AUTHENTICATON and change CSR Format to PEM

Fill out the form with the following values:


  • Certification Service: Select the appropriate certification service (there should only be 1)

  • CSR Format: PEM

Enter your Server DNS name (CN)


The certificate request is downloaded to browser's download folder.

Now you can see that there are two keys in the overview, Sign and Auth.

The certificate request should be sent to

Import Certificates


Import the AUTH Certificate

Navigate to and select the .pem file containing your certificate.

Activate auth signed certificate

Click the name of the certificate ( and press Activate


Import the SIGN Certificate

Finally press Register on the auth certificate and enter inn the FQDN of the server and press ADD

Confirm communication between two security servers

curl --insecure -H "X-Road-Client: IS-TEST/COM/5302922079/Origo-client" "


Í to Skatturinn:

curl -H "X-Road-Client: IS-DEV/GOV/10000/island-is-client" "http://localhost:8080/r1/IS-DEV/GOV/10006/Skatturinn-Protected/APIS-v1/company?name=skatturinn"


Í to Skatturinn:

curl -H "X-Road-Client: IS-TEST/GOV/5501692829/island-is-client" "http://localhost:8080/r1/IS-TEST/GOV/5402696029/Skatturinn-Protected/APIS-v1/company?name=skatturinn"

Removal of Security Server



set -x
sudo apt-get purge xroad-base
sudo apt-get autoremove
sudo rm -rf /etc/xroad
sudo rm -rf /usr/share/xroad
sudo rm -rf /var/lib/xroad
sudo rm -rf /var/log/xroad
sudo rm -rf /var/tmp/xroad
sudo apt-get purge nginx
sudo -u postgres dropdb messagelog
sudo -u postgres dropdb serverconf
sudo -u postgres dropdb op-monitor
sudo -u postgres psql -c "drop user serverconf"
sudo -u postgres psql -c "drop user messagelog"
sudo -u postgres psql -c "drop user opmonitor"
sudo -u postgres psql -c "drop user serverconf_admin"
sudo -u postgres psql -c "drop user messagelog_admin"
sudo -u postgres psql -c "drop user opmonitor_admin"
sudo apt-get --purge remove postgresql\*
sudo rm -rf /etc/postgresql/
sudo rm -rf /var/lib/postgresql
sudo userdel -r postgres



set -x

sudo yum remove xroad-base
sudo rm -rf /etc/xroad
sudo rm -rf /usr/share/xroad
sudo rm -rf /var/lib/xroad
sudo rm -rf /var/log/xroad
sudo rm -rf /var/tmp/xroad
sudo yum remove nginx
sudo -u postgres dropdb messagelog
sudo -u postgres dropdb serverconf
sudo -u postgres psql -c "drop user serverconf"
sudo yum remove postgresql

Last updated