X-Road 7.2.0
GitHub X-Road Community NIIS

Central Server User Guide

X-Road: Central Server User Guide

Version: 2.24 Doc. ID: UG-CS

Version history

Table of Contents

License

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/.

1. Introduction

1.1 Target Audience

The intended audience of this User Guide are X-Road central server administrators who are responsible for everyday management of the X-Road central server.

Instructions for the installation and initial configuration of the central server can be found in the Central Server Installation Guide CSI. Instructions for installing the central server in a cluster for achieving high availability can be found in the Central Server High Availability Installation Guide IG-CSHA.

1.2 Terms and abbreviations

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

1.3 References

  1. [CSI] Cybernetica AS. X-Road 7. Central Server Installation Guide. Document ID: IG-CS

  2. [IG-CSHA] Cybernetica AS. X-Road 7. Central Server High Availability Installation Guide. Document ID: IG-CSHA

  3. [JSON] Introducing JSON, http://json.org/

  4. [SPEC-AL] Cybernetica AS. X-Road: Audit log events. Document ID: SPEC-AL

  5. [SSI] Cybernetica AS. X-Road 7. Security Server Installation Guide. Document ID: IG-SS

  6. [IG-CS] Cybernetica AS. X-Road 7. Central Server Installation Guide. Document ID: IG-CS

  7. [UC-GCONF] Cybernetica AS. X-Road 7: Use Case Model for Global Configuration Distribution. Document ID: UC-GCONF

  8. [RFC-OCSP] Online Certificate Status Protocol – OCSP, https://tools.ietf.org/html/rfc6960

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

2. User and Role Management

2.1 User Roles

The central server supports the following user roles:

  • Registration Officer (xroad-registration-officer) is responsible for handling the information about X-Road members.

  • System Administrator (xroad-system-administrator) is responsible for the installation, configuration, and maintenance of the central server.

  • Security Officer (xroad-security-officer) is responsible for the application of the security policy and security requirements.

One user can have multiple roles, and multiple users can fulfill the same role. Each role has a corresponding system group, created upon the installation of the system. The system user names are used for logging in to the user interface of the central server.

The document indicates in sections similar to the following example, which user role is required for performing a particular action in the user interface. For example

Access rights: System Administrator

Caution: If the logged-in user does not have a permission to carry out a task, the button that initiates the action is hidden (and neither is it possible to run the task using its corresponding keyboard combinations or mouse actions). Only the permitted information and actions are visible and available to the user.

2.2 Managing the Users

During the installation, a super user equipped with all the roles is created. You can create additional users that have restricted rights. User management is carried out in root user's permissions using the command line.

To add a new user, issue the command:

adduser username

To grant permissions to the user you created, add it to the corresponding system groups, for example:

adduser username xroad-registration-officer adduser username xroad-system-administrator adduser username xroad-security-officer

To remove a user’s permission, remove the user from the corresponding system group, for example:

deluser username xroad-registration-officer

To remove a user, enter:

deluser username

2.3 Managing API Keys

API keys are used to authenticate API calls to Central Server's management REST API. API keys are associated with roles that define the permissions granted to the API key. If an API key is lost, it can be revoked.

In addition to the user roles, an API key can be added to the Management Services role. The Management Services role is used for registration and management services to authenticate and successfully communicate with the management REST API. Registration and management services are automatically configured with valid API keys during installation.

Access rights: System Administrator

To create API key, follow these steps.

  1. In the Navigation tabs, select Settings --> API Keys, click Create API key.

  2. In the window that opens, check selected roles checkbox and then click Next.

  3. In the next window click Create Key.

  4. Copy and save the API key in a secure place. The API key is visible only at the time of key generation. It will not be presented again and cannot be retrieved later.

  5. Click Finish.

To edit API key related roles, follow these steps.

  1. In the Navigation tabs, select Settings --> API Keys.

  2. Select a API key and click Edit.

  3. In the window that opens, check selected roles checkbox and click Save.

To revoke API key from roles, follow these steps.

  1. In the Navigation tabs, select Settings --> API Keys.

  2. Select a API key and click Revoke key.

  3. Confirm the revoking by clicking Yes.

3. Standalone and High-Availability Systems

The central server can be installed and configured in several ways:

  • A standalone server with local database

  • A standalone server with remote database

  • A cluster of central servers (nodes) using a remote database. The system continues to function if one or more of the central server nodes are experiencing problems or are down for maintenance. If the database is highly available (e.g using hot-standby with automatic fail-over or multi-master replication), the system can also recover from database problems with minimal downtime.

When the system is configured with the most basic option standalone server with local database, there is no high-availability support. If either the web server or the database server break, the system goes down.

In the case of an HA setup, the central servers share configuration via an optionally highly-available database. While most of the system settings described in this document apply to the whole cluster, some have a meaning that is local to each node. In addition, all the configuration signing keys are local to each node and must be generated separately. This distinction will be stated explicitly throughout this document, where necessary.

In an HA setup, if the system is configured using different nodes in parallel, the effect will be similar to several people updating the configuration of a standalone server at the same time.

3.1 Detecting the Type of Deployment in the User Interface

In order to detect the type of deployment and the name of the node in the cluster in the case of HA setup, the logged-in user should check the instance identifier displayed in the left upper corner of the user interface. In the case of an HA setup, the name of the node is displayed in the right upper corner of the user interface.

3.2 Checking the Status of the Nodes of the Cluster

In order to check the status of the nodes in an HA setup, execute the following command on the central server node's command line:

curl -k https://localhost:4000/public_system_status/check_ha_cluster_status

4. System Settings

4.1 Managing the Member Classes

Access rights: Security Officer

To add a member class, follow these steps.

  1. In the Navigation tabs, select Settings --> System Settings.

  2. Locate the Member Classes section and click Add.

  3. In the window that opens, enter the member class code and description. Click Save.

To edit the description of a member class, follow these steps.

  1. In the Navigation tabs, select Settings --> System Settings.

  2. Locate the Member Classes section, select a member class and click Edit.

  3. In the window that opens, enter the member class description and click Save.

To delete a member class, follow these steps.

  1. In the Navigation tabs, select Settings --> System Settings.

  2. Locate the Member Classes section, select a member class and click Yes.

Only the member classes that are used by none of the X-Road members can be deleted.

4.2 Configuring the Management Service Provider

The central server provides management services to the security servers that are part of the (local) X-Road infrastructure (see Chapter 6).

A subsystem of an X-Road member acting as a service provider for the management services must be appointed in the central server (see 4.2.1), registered as a client of the management services’ security server (see 4.2.2) and configured to provide the services in the management services’ security server (see 4.2.3).

The management services’ security server must be installed and registered in the central server before the management service provider can be registered as a client of the security server and the management services can be configured (see SSI).

4.2.1 Appointing the Management Service Provider

Access rights: Security Officer

To appoint the management service provider in the central server, follow these steps.

  1. In the Navigation tabs, select Settings --> System Settings.

  2. Locate the Management Services section and click Edit on the Service Provider Identifier field.

  3. In the window that opens, find the subsystem of an X-Road member to be appointed as the management service provider and check the subsystem checkbox and then click Select.

4.2.2 Registering the Management Service Provider as a Security Server Client

The management service provider can be registered as a security server client as described in this section only if the management service provider is not registered as a client of any security servers. In case the management service provider is already a client of a security server then the Edit button is not shown next to the identifier of the Management Services' Security Server.

To register the appointed management service provider as a security server client to the management services’ security server, follow these steps.

  1. In the Navigation tabs, select Settings --> System Settings.

  2. Locate the Management Services section and click Edit button next to the identifier of the Management Services' Security Server.

  3. In the window that opens, find the security server that will be used as the management services’ security server and check checkbox.

  4. Click Select button to submit the registration request.

On successful registration the identifier of the management services’ security server is displayed and Edit button should hide.

4.2.3 Configuring the Management Services in the Management Services’ Security Server

Access rights: Security server’s Service Administrator

The data necessary for configuring the management services in the security server can be found at the central server Settings tab -> System Settings -> Management Services section.

To configure management services in the management services’ security server, follow these steps.

  1. In the Clients tab of the security server, select the client who will provide the management services. On the details view click Services sub-tab.

  2. Click Add WSDL, enter the management services WSDL address in the window that opens and click Add.

  3. Expand the WSDL, by clicking the > icon, select a service by click Service Code.

  4. In the window that opens, enter the management services address. If necessary, edit other service parameters. Check the Apply to All in WSDL checkbox and click Save. Ensure that the parameters of all the management services have changed.

  5. Activate the management service’s WSDL by selecting the row of the WSDL and clicking Enable.

  6. Navigate to the Service Clients tab.

  7. Click Add subject and search for the global group security-server-owners. Select the group and click Next.

  8. In the window that opens, check management services checkboxes (authCertDeletion, clientDeletion, clientReg, ownerChange) and click Add Selected to add the security-server-owners group’s access rights list.

4.3 Configuring the Central Server Address

Access rights: Security Officer

In the System Settings view (Settings tab --> System Settings), the central server's public DNS name or its external IP address is displayed. This address is used by the security servers to access the services provided by the central server (configuration download, management services).

ATTENTION! When the central server address is changed,

  • the management services address in the management services’ security server needs to be reconfigured,

  • the internal configuration anchor need to be redistributed to the security server administrators and

  • the external configuration anchor needs to be redistributed to the federation partners.

The services provided by the central server must be available from both the new and old address, until all servers using the services have uploaded the configuration anchor containing the new address.

4.3.1 Notes on HA Setup

In an HA setup, the address of the central server is local to the node that is being configured.

In an HA setup, internal and external configuration anchors contain information about each central server that is part of the cluster. If the address of one of the servers is changed, configuration anchors will be re-generated automatically on all the nodes.

4.3.2 Changing the Central Server Address

To change the central server address, follow these steps.

  1. In the Navigation tabs, select Settings --> System Settings.

  2. Locate the System Parameters section and click Edit.

  3. Enter the central server’s address and click Save. When the address is changed, the system:

  • changes the management services WSDL address,

  • changes the management services address,

  • changes the configuration source addresses,

  • generates new configuration anchors for the internal and external configuration sources.

  1. After the central server address is changed, act as follows.

  • Download the internal configuration source anchor and distribute the anchor along with the anchor’s hash value to the security server administrators of the local X-Road infrastructure.

  • In case of federated X-Road systems, download the external configuration source anchor and distribute the anchor along with the anchor’s hash value to the federation partners.

  • Reconfigure the management services addresses in the management service security server.

5. Configuration Management

5.1 Viewing the Configuration Settings

Access rights: Security Officer, System Administrator

The Global Configuration view consists of three sub-tabs.

  • The Internal Configuration view. The internal configuration is distributed by the central server to the security servers of the local X-Road infrastructure. The information needed to download and verify the internal configuration is included in the internal configuration anchor, which must be distributed to the security server administrators and uploaded to the security servers. Along with the internal configuration anchor, the anchor file hash value must be distributed. The hash value is used by the security server administrators to verify the integrity of the anchor file.

  • The External Configuration view. The external configuration is distributed by the central server to the federation partners (either to the security servers directly or through a configuration proxy). The information needed to download and verify the external configuration is included in the external configuration anchor, which must be distributed to the federation partner’s central server (or configuration proxy) administrators and uploaded to the central server (or configuration proxy). Along with the external configuration anchor, the anchor file hash value must be distributed. The hash value is used by the federation partners to verify the integrity of the anchor file.

  • The Trusted Anchors view. A trusted anchor is the configuration anchor of the configuration source(s) distributing the external configuration of a federation partner. Upon loading the trusted anchor into the central server, the anchor is included into the internal configuration, allowing the security servers to download the external configuration of a federation partner as well as the internal configuration of the local X-Road infrastructure.

5.2 Downloading the Configuration Anchor

Access rights: Security Officer

To download a configuration anchor, follow these steps.

  1. In the Navigation tabs, select Global Configuration and select either the Internal Configuration or External Configuration sub-tab, as appropriate.

  2. In the Anchor section, click Download and save the prompted file.

5.3 Re-Creating the Configuration Anchor

Access rights: Security Officer

Normally, the configuration anchors are generated (and in an HA setup, distributed to every node) automatically by the system upon changes in the data included in the anchor (one or more central server addresses, signing keys). The re-creation of an anchor is necessary only for recovering from error situations.

To re-create an anchor, follow these steps.

  1. In the Navigation tabs, select Global Configuration and select either the Internal Configuration or External Configuration sub-tab, as appropriate.

  2. In the Anchor section, click Re-create.

5.4 Changing the Configuration Signing Keys

Access rights: Security Officer

Key change can be either

  • regular change – the key is changed periodically (for example, annually) to minimize the risk of exposure;

  • emergency change – the key and all its back-ups have been destroyed or the key has been exposed.

As the key change must be carried out efficiently without disrupting the operation of X-Road, the procedure is completed in two stages, wherein the old key and the new key can exist in parallel.

Note that in an HA setup, each node has its own set of configuration signing keys. The old and new key can exist in parallel on each node. Regular key change should cover all the nodes in a cluster and the new configuration anchor should be distributed after the keys have been changed on each node.

The steps of key change are as follows:

  • First, a new key is generated (on each node in HA setups) and the configuration anchor containing the public key part(s) of the key(s) is distributed to X-Road participants. Until all participants have received the public key(s), the old (i.e. current) key(s) is/are used for signing configuration.

  • Then, after all participants have received and uploaded the new public key(s), the old key(s) is/are removed and the new key(s) is/are used to sign configuration.

To perform a regular key change, follow these steps.

  1. Generate, but do not activate a new configuration signing key (see 5.4.1) (in an HA setup, for each node). The system uses the old (active) key(s) to sign the configuration. Upon the generation of a new key, the system generates a new anchor for the corresponding configuration sources.

  2. Download the anchor (see 5.2) containing the public key part(s) of the new signing key(s) and distribute the anchor along with the anchor file hash value either to the security server administrators (in case of internal configuration anchor) or to the federation partners (in case of external configuration anchor).

  3. Activate the new signing key(s) (see 5.4.2). The new signing key(s) should only be activated after all the affected server administrators have received and uploaded the distributed anchor. The central servers use the active key to sign configuration. If a server administrator has not uploaded the configuration anchor containing the public key part of the new key before the new key is activated, the verification of the downloaded configuration in the security servers will fail and the services exchange with the X-Road participants described in the configuration will be discontinued.

  4. Delete the old signing key (in an HA setup, delete the old keys on all the nodes) (see 5.4.3). Upon the deletion of a key, the system generates a new configuration anchor.

  5. Download the generated anchor (it does not contain the public key part(s) of the old signing key(s)) and distribute the anchor along with the anchor file hash value either to the security server administrators (in case of internal configuration anchor) or to the federation partners (in case of external configuration anchor).

To perform an emergency key change, the new key must be activated and the old key deleted immediately after the generation of the new key (in the steps described above, step 2 is skipped). The configuration anchor distributed to the security server administrators (in case of internal configuration anchor) or to the federation partners (in case of external configuration anchor) must only contain the public key part of the new signing key.

5.4.1 Generating a Configuration Signing Key

Access rights: Security Officer

To generate a configuration signing key, follow these steps.

  1. In the Navigation tabs, select Global Configuration and select either the Internal Configuration or External Configuration sub-tab, as appropriate.

  2. In the Signing Keys section, expand the token's information by clicking the caret next to the token name and then click Add key.

  3. In a window that opens, insert signing key friendly name, and click Add.

  4. Add key button is only active when the token has been logged in to.

The system will automatically generate the corresponding configuration anchor containing the public key part of the generated key. If the generated key is the only signing key for the configuration source, the key will automatically be set as active.

5.4.2 Activating a Configuration Signing Key

Access rights: Security Officer

To activate a configuration signing key, follow these steps.

  1. In the Navigation tabs, select Global Configuration and select either the Internal Configuration or External Configuration sub-tab, as appropriate.

  2. In the Signing Keys section, expand the token's information by clicking the caret next to the token name and select an inactive key (only for an inactive key are the Activate and Delete buttons displayed) and click Activate.

5.4.3 Deleting a Configuration Signing Key

Access rights: Security Officer

To delete a configuration signing key, follow these steps.

  1. In the Navigation tabs, select Global Configuration and select either the Internal Configuration or External Configuration sub-tab, as appropriate.

  2. In the Signing Keys section,expand the token's information by clicking the caret next to the token name and select an inactive key (only for an inactive key are the Activate and Delete buttons displayed) and click Delete.

  3. Confirm the deletion by clicking Confirm.

5.5 Managing the Contents of a Configuration Part

Access rights: Security Officer, System Administrator

The contents of a configuration part can be viewed by downloading the configuration part file. Also, configuration file can be uploaded.

To download or upload a configuration file, follow these steps.

  1. In the Navigation tabs, select Global Configuration and select either the Internal Configuration or External Configuration sub-tab, as appropriate

  2. In the Configuration Parts section, select a configuration part file and click Download or Upload

5.6 Uploading a Trusted Anchor

Access rights: Security Officer

To upload a trusted anchor, follow these steps.

  1. In the Navigation tabs, select Global Configuration and select the Trusted Anchors sub-tab.

  2. Click Upload button, find the external configuration anchor received from a federation partner and click Open.

  3. Verify the integrity of the anchor file by comparing the displayed anchor file hash value with the hash value provided by the federation partner and confirm the anchor upload by clicking Confirm.

In case a previous anchor from the same federation partner has been uploaded to the system, the new anchor will replace the old one.

5.7 Viewing the Contents of a Trusted Anchor

Access rights: Security Officer, System Administrator

The contents of a trusted anchor can be viewed by downloading the anchor file. To download an anchor file, follow these steps.

  1. In the Navigation tabs, select Global Configuration and select the Trusted Anchors sub-tab.

  2. In an anchor section, click Download.

  3. Save or open the prompted file.

5.8 Deleting a Trusted Anchor

Access rights: Security Officer

To delete an anchor file, follow these steps.

  1. In the Navigation tabs, select Global Configuration and select the Trusted Anchors sub-tab.

  2. In the anchor section, click Delete.

  3. Confirm the deletion by clicking Yes.

6. The Management Requests System

6.1 Registration Requests

As the registration of associations in the X-Road governing authority is security-critical, the following measures are applied to increase security by default:

  • The registration request must be submitted to the X-Road central server through the security server. Manual approval is still required by default.

  • The association must be approved by the X-Road governing authority.

There are three types of registration requests:

  • authentication certificate registration request (see Sections 7.4 and 8.3);

  • security server client registration request (see Section 7.5);

  • security server owner change request (see Section 7.7)

It is possible to streamline the registration process of authentication certificates and security server clients by enabling automatic approval.

  • authentication certificate registration requests

    • When automatic approval is enabled, it is enough to submit an authentication certificate registration request to the X-Road central server through the security server, and the request will be automatically approved immediately.

    • Automatic approval is applied to existing members only.

    • By default, automatic approval of authentication certificate registration requests is disabled. It can be enabled by setting the auto-approve-auth-cert-reg-requests property value to true on central server.

  • security server client registration requests

    • When automatic approval is enabled, it is enough to submit a security server client registration request to the X-Road central server through the security server, and the request will be automatically approved immediately.

    • Automatic approval is applied to existing members only. In addition, automatic approval is applied only if the client registration request has been signed by the member owning the subsystem to be registered as a security server client.

    • By default, automatic approval of security server client registration requests is disabled. It can be enabled by setting the auto-approve-client-reg-requests property value to true on central server.

  • security server owner change requests

    • When automatic approval is enabled, it is enough to submit a security server owner change request to the X-Road central server through the security server, and the request will be automatically approved immediately.

    • Automatic approval is applied to existing members only.

    • By default, automatic approval of security server owner change requests is disabled. It can be enabled by setting the auto-approve-owner-change-requests property value to true on central server.

6.1.1 State Model for Registration Requests

A registration request can be in one of the following states. See Figure 1 for the state diagram.

Figure 1. State diagram for registration requests

Pending – a registration request has been submitted from a security server. From this state, the request can move to the following states.

  • “Approved”, if the registration request is approved in the central server (see 7.4, 7.5 and 8.3). The association between the objects of the registration request has been created.

  • “Rejected”, if the registration request is declined in the central server (see 7.4, 7.5 and 8.3).

  • “Revoked”.

    • Registration request received from a security server are automatically revoked by deletion requests sent from the security server for the same object that was submitted for registration with the registration request.

If automatic approval of authentication certificate registration requests, security server client registration requests and/or security server owner change requests is enabled, the request is approved automatically. Therefore, the request moves directly to Approved state.

6.2 Deletion Requests

Deleted requests is submitted through a security server or formalized in the central server.

Deletion requests are

  • authentication certificate deletion request (see Section 8.4);

  • security server client deletion request (see Section 7.6).

6.3 Viewing the Management Request Details

Access rights: Registration Officer

To open the detail view, follow these steps.

  1. In the Management Requests tab.

  2. Select from the table a request and click Id field.

  3. Uncheck "Show only pending requests" checkbox, if you want to see all requests.

There are three data sections in the view.

  1. Information about the request.

  • Request ID – the identifier of the request;

  • Received – the date and time of saving the request in the central server;

  • Source – the source of the request. The request can be either submitted through a security server (SECURITY_SERVER) or automatically generated in the central server (CENTER);

  • Status (only for registration requests) – the state of the request, see Figure 1;

  • Comments – the source event for the automatic generation of the request. For example, when a security server is deleted from the central server, deletion requests are automatically generated for all the clients and authentication certificates registered for this security server. In the "Comments" field of the generated requests, a comment with the server identifier is added in such case. This field is left empty for requests that are not automatically generated by the central server.

  1. Information about the security server associated with the request.

  • Owner Name – the name of the security server owner (X-Road member);

  • Owner Class – the member class of the security server owner;

  • Owner Code – the member code of the security server owner;

  • Server Code – the code of the security server;

  • Address – the address of the security server. The field is filled only for authentication certificate registration requests.

  1. Information about the request object – that is, the client or the authentication certificate being registered or deleted.

For the authentication certificate:

  • CA – the name of the certification authority that issued the certificate;

  • Serial Number – the serial number of the certificate;

  • Subject – all attributes of the certificate's Subject field;

  • Expires – the expiration date of the certificate;

For the security server client:

  • Name – the name of the X-Road member managing the subsystem;

  • Class – the member class of the X-Road member managing the subsystem;

  • Code – the member code of the X-Road member managing the subsystem;

  • Subsystem – the code of the subsystem.

7 Managing the X-Road Members

7.1 Adding a Member

Access rights: Registration Officer

To add a new X-Road member, follow these steps.

  1. In the Members tab, click Add member.

  2. In the window that opens, enter the member's information and click Add. The new member appears in the list of members.

7.2 Viewing the Member Details

Access rights: Registration Officer

To open the detail view, follow these steps.

  1. In the Members tab.

  2. Select from the table an X-Road member and click members name.

The view consists of five sections and a tab Subsystems.

  1. "Member name"

  2. "Member class"

  3. "Member code"

  4. "Owned Servers" – displays the codes of servers owned by this member.

  5. "Global Groups" – displays information about the group membership of the member or its subsystems.

  6. "Subsystems" tab – displays a list of member's subsystems. If a subsystem is not a client of any security servers, then subsystem status is UNREGISTERED.

7.3 Adding a Subsystem to an X-Road Member

Access rights: Registration Officer

To add a subsystem to an X-Road member, follow these steps.

  1. In the Members tab, select the member to whom you wish to add a subsystem and click members name.

  2. In the view that opens, locate the Subsystems tab and click Add new subsystem to database.

  3. Enter the code of the subsystem and click Add.

7.4 Registering a Member's Security Server

Access rights: Registration Officer

The actions required to register an X-Road member's security server depend on whether automatic approval of authentication certificate registration requests is enabled or disabled (default).

When automatic approval of authentication certificate registration requests is enabled, the following action must be taken:

  • An authentication certificate registration request must be sent from the security server to the central server by the security server administrator.

Automatic approval of authentication certificate registration requests is disabled by default. In that case, to register an X-Road member's security server, the following actions must be taken.

  • An authentication certificate registration request must be sent from the security server to the central server by the security server administrator;

  • The requests must be approved or declined by the central server administrator.

To approve a request, it can be done either through in the Management request view list or in the Management request details view.

On the approval of the request

  • the request moves to the "Approved" state;

  • the registered security server appears both in the "Owned Servers" section of its owner’s detail view and in the list of security servers (in the Security Servers tab);

  • the security server's owner is added to the global "security-server-owners" group.

To decline a request, it can be done either through in the Management request view list or in the Management request details view. On the decline of the request

  • the request moves to the "Rejected" state.

7.5 Registering a Client to a Security Server

Access rights: Registration Officer

The actions required to register a subsystem of an X-Road member as a security server client depend on whether automatic approval of security server client registration requests is enabled or disabled (default).

When automatic approval of security server client registration requests is enabled, the following action must be taken:

  • A security server client registration request must be sent from the security server to the central server by the security server administrator.

Automatic approval of security server client registration requests is disabled by default. In that case, to register a subsystem of an X-Road member as a security server client, the following actions must be taken.

  • A security server client registration request must be sent from the security server to the central server by the security server administrator;

  • The requests must be approved or declined by the central server administrator.

To approve a request, it can be done either through in the Management request view list or in the Management request details view.

On the approval of the request, follow these steps.

  • The request moves to the "Approved" state.

  • The client's information is displayed in the "Clients" section of the detailed view of the security server to which the client was registered.

To decline a request, it can be done either through in the Management request view list or in the Management request details view. On the decline of the request

  • the request moves to the "Rejected" state.

7.6 Removing a Client from a Security Server

Access rights: Registration Officer

The association between an X-Road member and a security server is deleted by the corresponding security server's client deletion request. The request can be submitted through the security server or in the central server.

The association between the security server's owner and the security server cannot be deleted.

Removing a client from the security server clients can be carried out through a member's detail view.

To submit a security server client deletion request through a member's detail view, follow these steps.

  1. In the Members tab, select the member whose subsystem is to be removed from a security server and click members name.

  2. In the window that opens, select Subsystems tab and select the client subsystem, and click Unregister.

  3. Review the information displayed on the client deletion request and click Delete to submit the request.

7.7 Changing the Owner of Security Server

Access rights: Registration Officer

The actions required to change a security server's owner depend on whether automatic approval of security server owner change requests is enabled or disabled (default).

When automatic approval of security server owner change requests is enabled, the following action must be taken:

  • A security server owner change request must be sent from the security server to the central server by the security server administrator.

Automatic approval of security server owner change requests is disabled by default. In that case, to change the owner of a security server, the following action must be taken.

  • A security server owner change request must be sent from the security server to the central server by the security server administrator.

  • The requests must be approved or declined by the central server administrator.

To approve/decline a request, it can be done either through in the Management request view list or in the Management request details view.

7.8 Deleting a Subsystem

Access rights: Registration Officer

In the central server, the X-Road member's subsystem can be deleted only if the subsystem is not associated with any security servers, that is, not registered as a client of any security servers.

To delete an X-Road member's subsystem, follow these steps.

  1. In the Members tab, select the member whose subsystem you wish to delete and click members name.

  2. In the window that opens, select Subsystems tab and select the client subsystem, and click Delete. Note: The "Delete" button is displayed only if the subsystem is not a client of any security servers.

7.9 Deleting an X-Road Member

Access rights: Registration Officer

When an X-Road member is deleted, information about all security servers in its ownership will be deleted as well.

To delete an X-Road member, follow these steps.

  1. In the Members tab, select a member that you wish to delete, and click members name.

  2. In the view that opens, click Delete member "<member name>". In the confirmation window that opens, enter member code and click Delete.

8. Managing the Security Servers

8.1 Viewing the Security Server Details

Access rights: Registration Officer

To open the detail view, follow these steps. In the Members tab, select a member that you wish to delete, and click members name.

  1. In the Security Servers tab.

  2. Choose from the table a security server and click server code.

The view contains three sections.

  • "Details" – information about the server and its owner.

  • "Clients" – information about clients registered for this security server. Hint: Click a client's member name to open the client's detail view.

  • "Authentication Certificates" – information about the security server's registered authentication certificates. Hint: Click a certificate's certification authority to open the certificate's detail view.

8.2 Changing the Security Server Address

Access rights: Registration Officer

By default, the security server's address is provided in the registration request of the authentication certificate sent from the security server. The address must be changed if it was not set when the request was submitted or if it is no longer valid.

There are several reasons why setting the security server’s address matters.

  • The services that are relayed through a security server become available once the security server’s address is set.

  • By registering the addresses of security servers, the service clients are certain to receive a response to their queries in a reasonable time, even if the relaying security server is overloaded with service requests (e.g., the requests from addresses belonging to registered security servers are served before requests coming from unknown addresses).

To change the security server address, follow these steps.

  1. In the Security Servers tab, select the security server whose address you wish to change and click server code.

  2. In the view that opens, locate the "Address" section and click Edit adjacent to the "Address" field.

  3. Enter the security server's address and click Save.

8.3 Registering a Security Server's Authentication Certificate

Access rights: Registration Officer

The actions required to register a security server's authentication certificate depend on whether automatic approval of authentication certificate registration requests is enabled or disabled (default).

When automatic approval of authentication certificate registration requests is enabled, the following action must be taken:

  • An authentication certificate registration request must be sent from the security server to the central server by the security server administrator.

Automatic approval of authentication certificate registration requests is disabled by default. In that case, to register a security server's authentication certificate, the following actions must be taken.

  • An authentication certificate registration request must be sent from the security server to the central server by the security server administrator;

  • The requests must be approved or declined by the central server administrator.

To approve/decline a request, it can be done either through in the Management request view list or in the Management request details view.

Upon approving the request

  • the request moves to the "Approved" state;

  • the registered authentication certificate appears in the security server's detail view, in the "Authentication Certificates" section.

To decline the request

  • the request moves to the "Rejected" state;

8.4 Deleting a Security Server's Authentication Certificate

Access rights: Registration Officer

The authentication certificate registered for a security server is deleted when an authentication certificate deletion request is received for that certificate. The request can be submitted through the security server or in the central server.

To submit an authentication certificate deletion request in the central server, follow these steps.

  1. In the Security Servers tab, select the security server whose certificate you wish to delete and click server code.

  2. In the view that opens, locate the Authentication Certificates section, find the correct authentication certificate and click Delete.

  3. Review the information displayed on the deletion request and enter security server code and click Delete to submit the request.

  4. The submitted request appears in the management requests view (Management Requests tab).

8.5 Deleting a Security Server

Access rights: Registration Officer

To delete a security server, follow these steps.

  1. In the Security Servers tab, select the security server that you wish to delete and click server code.

  2. In the view that opens, on the bottom left, click Delete Security Server "<server code>". Confirm the action by entering security server code and clicking Delete.

If the security server being deleted has registered clients or authentication certificates, deletion requests for those associations are automatically generated.

9. Managing the Global Groups

9.1 Adding a Global Group

Access rights: Registration Officer

To add a new global group, follow these steps.

  1. In the Navigation tabs, select Settings --> Global Resources and click Add Global Group.

  2. In the window that opens, enter the new group's code and description, and click Add. The new group is added to the list of global groups.

9.2 Viewing the Global Group Details

Access rights: Registration Officer

To see the details of a global group, follow these steps.

  1. In the Navigation tabs, select Settings --> Global Resources.

  2. Select a global group from the table and click code.

In the global group detail view, a list of the group's members is displayed. The detail view allows you to change the group's description, delete the group, and add or remove its members.

9.3 Changing the Description of a Global Group

Access rights: Registration Officer

To change the description of a global group, follow these steps.

  1. In the Navigation tabs, select Settings --> Global Resources.

  2. Select a global group from the table and click its Code.

  3. In the view that opens, click Edit, change the group’s description and click Save.

9.4 Changing the Members of a Global Group

Access rights: Registration Officer

Note that the members of the global group security-server-owners are managed automatically by the central server and cannot be added or removed manually.

To add subsystems of X-Road members to a global group, follow these steps.

  1. In the Navigation tabs, select Settings --> Global Resources.

  2. Select a global group from the table and click its Code.

  3. In the view that opens, click Add Members.

  4. Select one or more subsystems from the list and click Add. Or filter a selection of subsystems with the search function.

To remove members from a group, follow these steps.

  1. In the Navigation tabs, select Settings --> Global Resources.

  2. Select a global group from the table and click its Code.

  3. Click Remove button on the selected subsystem row.

  4. In the confirmation window that opens, enter the member code and then click Delete.

9.5 Deleting a Global Group

Access rights: Registration Officer

To delete a global group, follow these steps.

  1. In the Navigation tabs, select Settings --> Global Resources.

  2. Select a global group from the table and click its Code.

  3. In the view that opens, click Delete Group and in the confirmation window click Yes.

10. Managing the Approved Certification Services

10.1 Adding an Approved Certification Service

Access rights: System Administrator

To add a certification service, follow these steps.

  1. In the Trust Services tab, click Add certification service

  2. Locate the certification service CA certificate file and click Upload.

  3. Set the certification service settings as follows.

  • If the certification service issues only authentication certificates, check the This CA can only be used for TLS authentication checkbox. However, if the certification service issues additionally or only signing certificates, leave the checkbox empty.

  • Enter the fully qualified class name that implements the ee.ria.xroad.common.certificateprofile.CertificateProfileInfo interface to the field Certificate profile info (for example: ee.ria.xroad.common.certificateprofile.impl.SkKlass3CertificateProfileInfoProvider).

  • If the CA certificate contains the certification service CA’s OCSP service information, and the PKI does not have intermediate CAs, the procedure is complete.

  1. If necessary, enter the certification service CA’s OCSP service URL and certificate in the OCSP Responders tab by clicking Add.

  2. Information about intermediate CAs can be added in the Intermediate CAs tab. To add a new intermediate CA

  • click Add;

  • in the window that opens, locate the certificate file of the intermediate CA and click Save;

  • to add OCSP service information to the new intermediate CA, click on the added intermediate CA, in the window that opens, locate OCSP Responders tab and click Add.

10.2 Changing an Approved Certification Service

Access rights: System Administrator

While it is not possible to change the certification service's CA certificate, it is possible to

  • change the service settings;

  • add, change, and delete the certificate service CA’s OCSP services;

  • add, change, and delete the certificates and OCSP service information of intermediate CAs.

To edit a certification service, follow these steps.

  1. In the Trust Services tab, select Certification Services.

  2. Select from the list the certification service you want to edit and click on the approved certification service field.

10.3 Deleting an Approved Certification Service

Access rights: System Administrator

To delete a certification service from the list of approved services, follow these steps.

  1. In the Trust Services tab, select Certification Services.

  2. Select from the list the approved certification service you wish to remove and click on the approved certification service field.

  3. In the window that opens, click Delete trust service "<certification service name>" and in the confirmation window click Yes.

11. Managing the Approved Timestamping Services

11.1 Adding an Approved Timestamping Service

Access rights: System Administrator

To add an approved timestamping service, follow these steps.

  1. In the Trust Services tab, click Add timestamping service.

  2. In the window that opens, enter the timestamping service URL and locate the certificate file of the timestamping service and click Add.

  3. Information about the new timestamping service appears in the list.

11.2 Changing an Approved Timestamping Service

Access rights: System Administrator

To change the timestamping service, follow these steps.

  1. In the Trust Services tab, select Timestamping Services, select a timestamping service from the list and click Edit.

  2. In the window that opens, edit the URL and/or upload new certificate. Click Save.

11.3 Deleting an Approved Timestamping Service

Access rights: System Administrator

To remove a timestamping service, follow these steps.

  1. In the Trust Services tab, select Timestamping Services, select a timestamping service from the list and click Delete.

  2. In the window that opens, click Yes.

12. Configuration Backup and Restore

Access rights: System Administrator

The central server backs up the database (excluding the schema_migrations table and the database schema) and the directories /etc/xroad/ and /etc/nginx/sites-enabled/.

Backups contain sensitive information that must be kept secret (for example, private keys and database credentials). In other words, leaking this information could easily lead to full compromise of central server. Therefore, it is highly recommended that backup archives are encrypted and stored securely. Should the information still leak for whatever reason the central server should be considered as compromised and reinstalled from scratch.

Central server backups are signed and optionally encrypted. The GNU Privacy Guard [GnuPG] is used for encryption and signing. Central server's backup encryption key is generated during central server initialisation. In addition to the automatically generated backup encryption key, additional public keys can be used to encrypt backups.

12.1 Backing Up the System Configuration

To back up the configuration, follow these steps.

  1. In the Settings tab, select Back Up and Restore sub-tab.

  2. Click Back up config. to start the backup process.

  3. When done, the configuration backup file appears in the list of configuration backup files.

12.2 Restoring the System Configuration in the User Interface

To restore configuration, follow these steps.

  1. In the Settings tab, select Back Up and Restore sub-tab.

  2. Select a file from the list of configuration backup files and click Restore.

  3. Confirm to proceed.

  4. A popup notification shows after the restore whether the restoring was successful or not.

If something goes wrong while restoring the configuration it is possible to revert back to the old configuration. Central Server stores so called pre-restore configuration automatically to /var/lib/xroad/conf_prerestore_backup.tar. Move it to /var/lib/xroad/backup/ folder and use the command line interface described in the next chapter (some specific switches with the restore command is required).

12.3 Restoring the Configuration from the Command Line

To restore configuration from the command line, the following data must be available:

  • the instance ID of the central server and,

  • in HA setup, the node name of the central server.

It is expected that the restore command is run by the xroad user.

Use the following command to restore configuration in non-HA setup:

/usr/share/xroad/scripts/restore_xroad_center_configuration.sh -i <instance_ID> -f <path + filename> [-P -N]

In HA setup, this command has an additional mandatory parameter, the node name:

/usr/share/xroad/scripts/restore_xroad_center_configuration.sh -i <instance_ID> -n <node_name> -f <path + filename> [-P -N]

For example (all in one line, non-HA setup):

/usr/share/xroad/scripts/restore_xroad_center_configuration.sh -i EE -f /var/lib/xroad/backup/conf_backup_20230515-114736.gpg

For example (all in one line, HA setup):

/usr/share/xroad/scripts/restore_xroad_center_configuration.sh -i EE -n node_0 -f /var/lib/xroad/backup/conf_backup_20230515-114736.gpg

In case original backup encryption and signing key is lost additional parameters can be specified to skip decryption and/or signature verification. Use -P command line switch when backup archive is already decrypted externally and -N switch to skip checking archive signature.

If a backup is restored on a new uninitialized (the initial configuration hasn't been completed) central server, the central server's gpg key must be manually created before restoring the backup:

/usr/share/xroad/scripts/generate_gpg_keypair.sh /etc/xroad/gpghome <instance_ID>

If it is absolutely necessary to restore the system from a backup made on a different central server, the forced mode of the restore command can be used with the –F option. For example:

/usr/share/xroad/scripts/restore_xroad_center_configuration.sh -F -P -f /var/lib/xroad/backup/conf_backup_20230515-114736.tar

In case backup archives were encrypted they have to be first unencrypted in external safe environment and then securely transported to central server filesystem.

It is possible to restore the configuration while skipping the database restoration by appending the -S switch, e.g.

/usr/share/xroad/scripts/restore_xroad_center_configuration.sh -i <instance_ID> -f <path + filename> -S

To see all the possible parameters use the -h switch, e.g.

/usr/share/xroad/scripts/restore_xroad_center_configuration.sh -h

12.4 Downloading, Uploading and Deleting Configuration Backup Files

The following actions can be performed in the Backup And Restore view.

To save the configuration backup file locally:

  • click Download on the respective row and save the prompted file.

To delete the configuration backup file:

  • click Delete on the respective row and confirm the action by clicking Yes.

To upload a configuration file from the local file system to the central server:

  • click Upload backup, select a file to be uploaded and click Open. The uploaded configuration file appears in the list of configuration files.

12.5 Automatic Backups

By default the Central Server backs up its configuration automatically once every day. Backups older than 30 days are automatically removed from the server. If needed, the automatic backup policies can be adjusted by editing the /etc/cron.d/xroad-center file.

12.6 Backup Encryption Configuration

Backups are always signed, but backup encryption is initially turned off. To turn encryption on, please override the default configuration in the file /etc/xroad/conf.d/local.ini, in the [center] section (add or edit this section).

[center]

backup-encryption-enabled = true
backup-encryption-keyids = <keyid1>, <keyid2>, ...

To turn backup encryption on, change the backup-encryption-enabled property to true. Additional encryption keys can be imported in the /etc/xroad/gpghome keyring and key identifiers listed using the backup-encryption-keyids parameter. It is recommended to set up at least one additional key, otherwise the backups will be unusable in case central server private key is lost. It is up to central server administrator to check that keys used are sufficiently strong, there are no automatic checks.

Warning. All keys listed in backup-encryption-keyids must be present in the gpg keyring or backup fails.

Additional keys for backup encryption should be generated and stored outside central server in a secure environment. After gpg keypair has been generated, public key can be exported to a file (backupadmin@example.org is the name of the key being exported) using this command:

gpg --output backupadmin.publickey --armor --export backupadmin@example.org

Resulting file backupadmin.publickey should be moved to central server and imported to back up gpg keyring. Administrator should make sure that the key has not been changed during transfer, for example by validating the key fingerprint.

Private keys corresponding to additional backup encryption public keys must be handled safely and kept in secret. Any of them can be used to decrypt backups and thus mount attacks on the central servers.

Configuration example

Generate a keypair for encryption with defaults and no expiration and export the public key:

gpg [--homedir <admin gpghome>] --quick-generate-key backupadmin@example.org default default never
gpg [--homedir <admin gpghome>] --export backupadmin@example.org >backupadmin@example.org.pgp

Import the public key to the gpg keyring in /etc/xroad/gpghome directory and take note of the key id.

gpg --homedir /etc/xroad/gpghome --import backupadmin@example.org.pgp

Edit the key and add ultimate trust.

gpg --homedir /etc/xroad/gpghome/ --edit-key <key id>

At the gpg> prompt, type trust, then type 5 for ultimate trust, then y to confirm, then quit.

Add the key id to /etc/xroad/conf.d/local.ini file (editing the file requires restarting X-Road services), e.g.:

[center]
backup-encryption-enabled = true
backup-encryption-keyids = 87268CC66939CFF3

To decrypt the encrypted backups, use the following syntax:

gpg --homedir /etc/xroad/gpghome --output <output file name> --decrypt <backup name>

12.7 Verifying Backup Archive Consistency

During restore central server verifies consistency of backup archives automatically, archives are not checked during upload. Also, it is possible to verify the consistency of the archives externally. For verifying the consistency externally, central server's public key is needed. When backups are encrypted, then a private key for decrypting archive is also needed. GPG uses "sign then encrypt" scheme, so it is not possible to verify encrypted archives without decrypting them.

Automatic backup verification is only possible when original central server keypair is available. Should keypair on the central server be lost for whatever reason, automatic verification is no longer possible. Therefore, it is recommended to export backup encryption public key and import it into separate secure environment. If backups are encrypted, central server public key should be imported to keyrings holding additional encryption keys, so that backups can be decrypted and verified in these separate environments.

To export central servers backup encryption public key use the following command:

gpg --homedir /etc/xroad/gpghome --armor --output server-public-key.gpg --export <instanceId>

where <instanceId> is the central server instance id, for example, EE.

Resulting file (server-public-key.gpg) should then be exported from central server and imported to GPG keystore used for backup archive consistency verification.

13. Audit Log

The central server keeps an audit log of the events performed by the central server administrator. The audit log events are generated by the user interface when the user changes the system’s state or configuration. The user actions are logged regardless of whether the outcome of the action was a success or a failure. The complete list of the audit log events is described in SPEC-AL.

Actions that change the system’s state or configuration but are not carried out using the user interface are not logged (for example, X-Road software installation and upgrade, user creation and permission granting, and changing of the configuration files in the file system).

An audit log record contains correlation-id, which can be used to link the record to other log messages about the same request.

An audit log record contains

  • the description of the user action,

  • the date and time of the event,

  • the username of the user that performed the action,

  • the authentication type used for this request (Session, ApiKey or HttpBasicPam)

    • Session – session based authentication (web application)

    • ApiKey - direct API call using API key authentication

    • HttpBasicPam – HTTP basic authentication with PAM login (for api key management API operations),

  • the API url for this request,

  • the IP address of the user, and

  • the data related to the event.

For example, adding a new member in the central server produces the following log record:

2023-05-21T16:20:06+03:00 my-central-server-host correlation-id: [655a2150c4688558] INFO [X-Road Central Server Admin Service] 2023-05-21T16:20:06.267+03:00 - {"event":"Add member","user":"xrd","ipaddress":"192.0.2.1","auth":"Session","url":"/api/v1/members","data":{"memberName":"SS2 OWNER","memberClass":"TEST","memberCode":"SS2_OWNER"}}

The event is present in JSON JSON format, in order to ensure machine processability. The field event represents the description of the event, the field user represents the user name of the performer, and the field data represents data related with the event. The failed action event record contains an additional field reason for the error message. For example:

2023-05-21T12:16:11+03:00 my-central-server-host correlation-id: [f9ee1a7bdf3e3d19] INFO [X-Road Central Server Admin Service] 2023-05-21T12:16:11.232+03:00 - {"event":"Log in to token failed","user":"xrd","ipaddress":"192.0.2.1","reason":"Token action not possible","warning":false,"auth":"Session","url":"/api/v1/tokens/0/login","data":{"tokenId":"0","tokenSerialNumber":null,"tokenFriendlyName":"softToken-0"}}

By default, audit log is located in the file

/var/log/xroad/audit.log

13.1 Changing the Configuration of the Audit Log

The X-Road software writes the audit log to the syslog (rsyslog) using UDP interface (default port is 514). Corresponding configuration is located in the file

/etc/rsyslog.d/90-udp.conf

The audit log records are written with level INFO and facility LOCAL0. By default, log records of that level and facility are saved to the X-Road audit log file

/var/log/xroad/audit.log

The default behavior can be changed by editing the rsyslog configuration file

/etc/rsyslog.d/40-xroad.conf

Restart the rsyslog service to apply the changes made to the configuration file

service rsyslog restart

The audit log is rotated monthly by logrotate. To configure the audit log rotation, edit the logrotate configuration file

/etc/logrotate.d/xroad-center

13.2 Archiving the Audit Log

In order to save hard disk space and avoid loss of the audit log records during central server crash, it is recommended to archive the audit log files periodically to an external storage or a log server.

The X-Road software does not offer special tools for archiving the audit log. The rsyslog can be configured to redirect the audit log to an external location.

14. Monitoring

Monitoring is taken to use by installing the monitoring support (see IG-CS and appointing the central monitoring client as specified below.

Identity of central monitoring client (if any) is configured using central server's admin user interface. Configuration is done by updating a specific optional configuration file (see UC-GCONF) monitoring-params.xml. This configuration file is distributed to all security servers through the global configuration distribution process (see UC-GCONF).

<tns:conf xmlns:id="http://x-road.eu/xsd/identifiers" xmlns:tns="http://x-road.eu/xsd/xroad.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://x-road.eu/xsd/xroad.xsd">
    <monitoringClient>
        <monitoringClientId id:objectType="SUBSYSTEM">
            <id:xRoadInstance>fdev</id:xRoadInstance>
            <id:memberClass>GOV</id:memberClass>
            <id:memberCode>1710128-9</id:memberCode>
            <id:subsystemCode>LIPPIS</id:subsystemCode>
        </monitoringClientId>
    </monitoringClient>
</tns:conf>

One can configure either one member or a member's subsystem to be the central monitoring client. Permission to execute monitoring queries is strictly limited to that single member or subsystem - defining one subsystem to be a monitoring client does not grant the corresponding member access to querying monitoring data (and vice versa).

To disable central monitoring client altogether, update configuration to one which has no client:

<tns:conf xmlns:id="http://x-road.eu/xsd/identifiers" xmlns:tns="http://x-road.eu/xsd/xroad.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://x-road.eu/xsd/xroad.xsd">
    <monitoringClient>
    </monitoringClient>
</tns:conf>

15. Additional configuration options

15.1 Verify next update

For additional robustness the OCSP RFC-OCSP response verifier can be configured to skip checking of nextUpdate parameter. By default the checking is turned on and to turn it off the user has to take action.

Configuration is done by updating a specific optional configuration file (see UC-GCONF) nextupdate-params.xml. This configuration file is distributed to all security servers through the global configuration distribution process (see UC-GCONF).

<xro:conf xmlns:xro="http://x-road.eu/xsd/xroad.xsd">
  <verifyNextUpdate>true</verifyNextUpdate>
</xro:conf>

With verifyNextUpdate element value “false” the nextUpdate parameter checking is switched off.

15.2 OCSP fetch interval

The xroad-signer component has a specific interval how often it downloads new OCSP RFC-OCSP responses. By default the fetch interval is configured to 1200 seconds. To use something else than the default value a global configuration extension part (see UC-GCONF) of specific format can be uploaded to central server.

<xro:conf xmlns:xro="http://x-road.eu/xsd/xroad.xsd">
    <ocspFetchInterval>1200</ocspFetchInterval>
</xro:conf>

The value is the fetch interval in seconds for new OCSP responses.

16. Logs and System Services

Most significant central server services are the following:

System services can be managed using the systemd facility. To start a service, issue the following command as a root user:

systemctl start <service>

To stop a service, enter:

systemctl stop <service>

To read logs, a user must have root user's rights or belong to the xroad system group.

For logging, the Logback system is used.

Logback configuration files are stored in the /etc/xroad/conf.d/ directory.

Default settings for logging are the following:

  • logging level: INFO;

  • rolling policy: whenever file size reaches 100 MB.

17. Migrating to Remote Database Host

Since version 6.23.0 Central Server supports using remote databases. In case you have an already running standalone Central Server with local database, it is possible to migrate it to use remote database host instead. The instructions for this process are listed below.

Prerequisites

  • Same version (12 or later) of PostgreSQL installed on the remote database host.

  • Network connections to PostgreSQL port (tcp/5432) are allowed from the Central Server to the remote database server.

  1. Shutdown X-Road processes.

systemctl stop "xroad*"

  1. Dump the local database centerui_production to be migrated. The credentials of the database admin user can be found in /etc/xroad.properties. Notice that the versions of the local PostgreSQL client and remote PostgreSQL server must match.

pg_dump -F t -h 127.0.0.1 -p 5432 -U centerui_admin -f centerui_production.dat centerui_production

  1. Shut down and mask local postgresql so it won't start when xroad-proxy starts.

systemctl stop postgresql
systemctl mask postgresql

  1. Connect to the remote database server as the superuser postgres and create roles, databases and access permissions as follows.

    psql -h <remote-db-url> -p <remote-db-port> -U postgres
    CREATE DATABASE centerui_production ENCODING 'UTF8';
    REVOKE ALL ON DATABASE centerui_production FROM PUBLIC;
    CREATE ROLE centerui_admin LOGIN PASSWORD '<centerui_admin password>';
    GRANT centerui_admin TO postgres;
    GRANT CREATE,TEMPORARY,CONNECT ON DATABASE centerui_production TO centerui_admin;
    \c centerui_production
    CREATE EXTENSION hstore;
    CREATE SCHEMA centerui AUTHORIZATION centerui_admin;
    REVOKE ALL ON SCHEMA public FROM PUBLIC;
    GRANT USAGE ON SCHEMA public TO centerui_admin;
    CREATE ROLE centerui LOGIN PASSWORD '<centerui password>';
    GRANT centerui TO postgres;
    GRANT TEMPORARY,CONNECT ON DATABASE centerui_production TO centerui;
    GRANT USAGE ON SCHEMA public TO centerui;
    GRANT USAGE ON SCHEMA centerui TO centerui;
    GRANT SELECT,UPDATE,INSERT,DELETE ON ALL TABLES IN SCHEMA centerui TO centerui;
    GRANT SELECT,UPDATE ON ALL SEQUENCES IN SCHEMA centerui TO centerui;
    GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA centerui to centerui;

  1. Restore the database dumps on the remote database host.

pg_restore -h <remote-db-url> -p <remote-db-port> -U centerui_admin -O -n centerui -1 -d centerui_production centerui_production.dat

  1. Create properties file /etc/xroad.properties if it does not exist.

    sudo touch /etc/xroad.properties
    sudo chown root:root /etc/xroad.properties
    sudo chmod 600 /etc/xroad.properties

  1. Make sure /etc/xroad.properties is containing the admin user & its password.

    centerui.database.admin_user = centerui_admin
    centerui.database.admin_password = <centerui_admin password>

  1. Update /etc/xroad/db.properties contents with correct database host URLs and passwords.

    username=centerui
    password=<centerui password>
    database=centerui_production
    host=<database host>
    port=<database port>
    schema=centerui

  1. Start again the X-Road services.

systemctl start "xroad*"
PreviousHA Installation GuideNextConfiguration Proxy Manual

Last updated