X-Road

https://docs.x-road.global
Admin
X-Road is a secure data exchange framework that enables organizations and governments to establish a...
Tokens:310,970
Snippets:3,291
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start Security Server Service

Source: https://docs.x-road.global/Manuals/ig-ss_x-road_v6_security_server_installation_guide_for_rhel.html

Once the installation is complete, use this command to start the Security Server service.

```bash
sudo systemctl start xroad-proxy
```

--------------------------------

### Example Restore (Non-HA)

Source: https://docs.x-road.global/Manuals/ug-cs_x-road_6_central_server_user_guide.html

An example of restoring configuration in a non-HA setup, specifying the instance ID and the path to the backup file.

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

--------------------------------

### Example Restore (HA)

Source: https://docs.x-road.global/Manuals/ug-cs_x-road_6_central_server_user_guide.html

An example of restoring configuration in an HA setup, including the instance ID, node name, and the path to the backup file.

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

--------------------------------

### Install Language Pack for Locale

Source: https://docs.x-road.global/Manuals/ig-cs_x-road_6_central_server_installation_guide.html

Use this command to install the necessary language support if locale commands fail. Example uses English.

```bash
sudo apt install language-pack-en
```

--------------------------------

### Install Local PostgreSQL Server Packages

Source: https://docs.x-road.global/Manuals/ig-ss_x-road_v6_security_server_installation_guide_for_rhel.html

Installs the necessary PostgreSQL server and contrib packages for a local database setup. This is required before proceeding with the X-Road Security Server installation.

```bash
sudo yum install postgresql-server postgresql-contrib
```

--------------------------------

### Start PostgreSQL Server on RHEL

Source: https://docs.x-road.global/Manuals/LoadBalancing/ig-xlb_x-road_external_load_balancer_installation_guide.html

Starts the PostgreSQL server service on RHEL systems.

```bash
systemctl start postgresql-serverconf
```

--------------------------------

### Start a System Service

Source: https://docs.x-road.global/Manuals/ug-ss_x-road_6_security_server_user_guide.html

Use this command to start a specific system service on the Security Server. Ensure you have root privileges.

```bash
service <service> start
```

--------------------------------

### Install X-Road Central Server Package

Source: https://docs.x-road.global/Manuals/ig-cs_x-road_6_central_server_installation_guide.html

Installs the Central Server packages using apt. This command should be run on the server where the Central Server will be installed.

```bash
sudo apt install xroad-centralserver
```

--------------------------------

### Enable and Start SSSD Service

Source: https://docs.x-road.global/Manuals/ug-ss_x-road_6_security_server_user_guide.html

Enables the SSSD service to start on boot and starts the service immediately to apply configuration changes.

```shell
sudo systemctl enable sssd
sudo systemctl start sssd
```

--------------------------------

### Install Hardware Token Support Module

Source: https://docs.x-road.global/Manuals/ig-cs_x-road_6_central_server_installation_guide.html

Installs the xroad-addon-hwtokens package required for hardware token integration.

```bash
sudo apt install xroad-addon-hwtokens
```

--------------------------------

### Install Hardware Token Support Module

Source: https://docs.x-road.global/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.html

Installs the necessary package for hardware security token support on Debian-based systems.

```bash
sudo apt-get install xroad-addon-hwtokens
```

--------------------------------

### Install X-Road Autologin Package

Source: https://docs.x-road.global/Manuals/Utils/ug-autologin_x-road_v6_autologin_user_guide.html

Use these commands to install the autologin package on Ubuntu or RedHat based systems.

```bash
apt install xroad-autologin
```

```bash
yum install xroad-autologin
```

--------------------------------

### Create and View Configuration Proxy Instance

Source: https://docs.x-road.global/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.html

Use 'confproxy-create-instance' to create configuration files for a new proxy and 'confproxy-view-conf' to verify its initial state. The initial output may show missing anchor files and unconfigured signing keys.

```bash
confproxy-create-instance -p PROXY

Populating 'conf.ini' with default values.
Done.

confproxy-view-conf -p PROXY

Configuration for proxy 'PROXY'
Validity interval: 600 s.
anchor.xml
================================================
'anchor.xml' could not be loaded: IOError: /etc/xroad/confproxy/PROXY/anchor.xml (No such file or directory)
Configuration URLs
================================================
http://1.2.3.4/PROXY/conf
https://1.2.3.4/PROXY/conf
Signing keys and certificates
================================================
active-signing-key-id:
    NOT CONFIGURED (add 'active-signing-key-id' to 'conf.ini')
```

--------------------------------

### Download Instance Configuration with Script

Source: https://docs.x-road.global/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.html

Use the 'download_instance_configuration.sh' script to download global configuration files. Provide the anchor filename and a target directory as arguments to verify that the proxy is distributing configuration correctly.

```bash
mkdir test_download
/usr/share/xroad/scripts/download_instance_configuration.sh anchor.xml test_download/

... - Downloading configuration from http://1.2.3.4/PROXY/conf
... - Downloading content from http://1.2.3.4/PROXY/123/AA/shared-params.xml
... - Saving SHARED-PARAMETERS to test_download/AA/shared-params.xml
... - Saving content to file test_download/AA/shared-params.xml
... - Downloading content from http://1.2.3.4/PROXY/123/AA/private-params.xml
... - Saving PRIVATE-PARAMETERS to test_download/AA/private-params.xml
... - Saving content to file test_download/AA/private-params.xml
```

--------------------------------

### Operational Monitoring Data Record (REST GET)

Source: https://docs.x-road.global/OperationalMonitoring/Architecture/arc-opmond_x-road_operational_monitoring_daemon_architecture_Y-1096-1.html

Example of a data record for a REST GET service in operational monitoring.

```json
{
      "monitoringDataTs": 1733404603,
      "securityServerInternalIp": "fd42:2642:2cb3:31ac:216:3eff:fedf:85c%eth0",
      "securityServerType": "Client",
      "requestInTs": 1742471252081,
      "requestOutTs": 1742471252151,
      "responseInTs": 1742471252329,
      "responseOutTs": 1742471252379,
      "clientXRoadInstance": "FI",
      "clientMemberClass": "COM",
      "clientMemberCode": "111",
      "clientSubsystemCode": "CLIENT",
      "serviceXRoadInstance": "FI",
      "serviceMemberClass": "COM",
      "serviceMemberCode": "111",
      "serviceSubsystemCode": "SERVICE",
      "serviceCode": "pets",
      "restMethod": "GET",
      "messageId": "1234",
      "messageProtocolVersion": "1",
      "clientSecurityServerAddress": "ss1",
      "serviceSecurityServerAddress": "ss1",
      "requestSize": 214,
      "responseSize": 462,
      "requestAttachmentCount": 0,
      "responseAttachmentCount": 0,
      "succeeded": true,
      "statusCode": 200,
      "xRequestId": "1244d018-9300-4f1b-8c2b-9b7f2bc4e933",
      "xRoadVersion": "7.6.2",
      "serviceType": "REST"
    }
```

--------------------------------

### Start PostgreSQL Primary Instance

Source: https://docs.x-road.global/Manuals/LoadBalancing/ig-xlb_x-road_external_load_balancer_installation_guide.html

Starts the PostgreSQL primary instance. Use the appropriate command for your operating system (Ubuntu or RHEL).

```bash
systemctl start postgresql@<postgresql major version>-serverconf
```

```bash
systemctl start postgresql-serverconf
```

--------------------------------

### Initialize PostgreSQL Database and Configure SELinux (RHEL 7)

Source: https://docs.x-road.global/Manuals/LoadBalancing/ig-xlb_x-road_external_load_balancer_installation_guide.html

Initializes a new PostgreSQL database with specific authentication settings, configures SELinux for the new port, and enables the new service. This is for RHEL 7.

```bash
PGSETUP_INITDB_OPTIONS="--auth-local=peer --auth-host=md5" postgresql-setup initdb postgresql-serverconf
semanage port -a -t postgresql_port_t -p tcp 5433
systemctl enable postgresql-serverconf
```

--------------------------------

### Operational Monitoring Data Record (REST GET with Path)

Source: https://docs.x-road.global/OperationalMonitoring/Architecture/arc-opmond_x-road_operational_monitoring_daemon_architecture_Y-1096-1.html

Example of a data record for a REST GET service with a specific path pattern.

```json
{
      "monitoringDataTs": 1733404603,
      "securityServerInternalIp": "fd42:2642:2cb3:31ac:216:3eff:fedf:85c%eth0",
      "securityServerType": "Producer",
      "requestInTs": 1742471252251,
      "requestOutTs": 1742471252251,
      "responseInTs": 1742471252364,
      "responseOutTs": 1742471252364,
      "clientXRoadInstance": "FI",
      "clientMemberClass": "COM",
      "clientMemberCode": "111",
      "clientSubsystemCode": "CLIENT",
      "serviceXRoadInstance": "FI",
      "serviceMemberClass": "COM",
      "serviceMemberCode": "111",
      "serviceSubsystemCode": "SERVICE",
      "serviceCode": "pets",
      "restMethod": "GET",
      "restPath": "/cat/*",
      "messageId": "1234",
      "messageProtocolVersion": "1",
      "clientSecurityServerAddress": "ss1",
      "serviceSecurityServerAddress": "ss1",
      "requestSize": 214,
      "responseSize": 462,
      "requestAttachmentCount": 0,
      "responseAttachmentCount": 0,
      "succeeded": true,
      "statusCode": 200,
      "xRequestId": "1244d018-9300-4f1b-8c2b-9b7f2bc4e933",
      "xRoadVersion": "7.6.2",
      "serviceType": "REST"
    }
```

--------------------------------

### X-Road Configuration Proxy Instance File Tree Example

Source: https://docs.x-road.global/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.html

Illustrates the directory structure for configured proxy instances, including certificates, configuration files (conf.ini), and anchor files (anchor.xml). This structure is required for each proxy instance managed by the Configuration Proxy.

```bash
<configuration-path>/
|-PROXY1/
| |-cert_QWERTY123.pem
| |-cert_321YTREWQ.pem
| |-conf.ini
| \-anchor.xml
|-PROXY2/
| |-cert_1234567890.pem
| |-conf.ini
| \-anchor.xml
\-...

```

--------------------------------

### Check X-Road Services Status

Source: https://docs.x-road.global/Manuals/ig-ss_x-road_v6_security_server_installation_guide_for_rhel.html

Verify that X-Road services are running after installation by listing units starting with 'xroad-'.

```bash
sudo systemctl list-units "xroad-*"
```

--------------------------------

### Pet Store Service Response Body

Source: https://docs.x-road.global/Protocols/pr-rest_x-road_message_protocol_for_rest.html

Example JSON response body for a successful GET request to the pet store service.

```json
{
  "id": 1124,
  "name": "Siddu",
  "photoUrls": [],
  "tags": [],
  "status": "Offline"
}
```

--------------------------------

### Set up External PostgreSQL Database for Sidecar

Source: https://docs.x-road.global/Sidecar/security_server_sidecar_user_guide.html

This example demonstrates setting up a PostgreSQL database and connecting the Sidecar to it using Docker. Ensure the PostgreSQL version is 16 for full compatibility.

```bash
# Create a network for the container(s)
docker network create -d bridge xroad-network

# Start a postgresql server for the external database
docker run -d \
-v postgres-data:/var/lib/postgresql/data \
-e POSTGRES_PASSWORD=<postgres password> \
--name remote-db \
--network xroad-network \
postgres:16

# Run sidecar
docker run -d \
-v <config volume name>:/etc/xroad \
-p 127.0.0.1:<admin port>:4000 \
-p 127.0.0.1:<healthcheck port>:5588 \
-p <consumer information system port>:8443 \
-p 5500:5500 \
-p 5577:5577 \
--network xroad-network \
-e XROAD_TOKEN_PIN=<token pin> \
-e XROAD_ADMIN_USER=<admin user> \
-e XROAD_ADMIN_PASSWORD=<admin password> \
-e XROAD_DB_HOST=remote-db \
-e XROAD_DB_PWD=<postgres password> \
--name <container name> \
niis/xroad-security-server-sidecar:<version[-type[-variant]>

```

--------------------------------

### Example ACME Configuration File (acme.yml)

Source: https://docs.x-road.global/Manuals/ug-ss_x-road_6_security_server_user_guide.html

This YAML file demonstrates the structure for configuring ACME settings, including external account binding credentials for different Certificate Authorities and members, and the account keystore password. Ensure the file is named `acme.yml` and remove the `.example` extension from the provided example file.

```yaml
# Example acme.yml file that has properties related to Automatic Certificate Management Environment (ACME)
# that is used to automate acquiring certificates from Certificate Authorities. To use this file
# remove '.example' form the file name and replace with correct values as needed or create a new file named 'acme.yml'.

# ACME external account binding credentials grouped by Certification Authorities(CA-s) and Members,
# where CAs have their name as key and should be surrounded by quotation marks to allow spaces.
# For Members the key is the Member ID in the form <instance_id>:<member_class>:<member_code> and
# should also be surrounded by quotation marks to allow for ':'. They have two properties: kid and mac-key, which should be
# acquired externally from the CA. If the CA supports kid-based certificate type selection, then credentials starting
# with the prefix "auth-" can be used to order authentication certificate and credentials starting with "sign-" can
# be used to order signing certificates.
# Property mac-key-base64-encoded should be true if the provided mac-keys are encoded in base64.
eab-credentials:
  certificate-authorities:
    'Example Root CA':
      mac-key-base64-encoded: true
      members:
        'EU:COM:1234567-8':
          auth-kid: key_2
          auth-mac-key: YXV0aGVudGljYXRpb25zZWNyZXRtYWNrZXk=
          sign-kid: key_3
          sign-mac-key: c2VjcmV0X21hY19rZXlfZm9yX3NpZ25pbmc=
    'Some Other CA':
      mac-key-base64-encoded: false
      members:
        'EU:GOV:9090909-1':
          kid: kid123
          mac-key: goodlongsecretwordthatisnotshort

# This is the password for the PKCS #12 keystore of the ACME Server account. The password is populated automatically by the Security Server.
# Keystore is at /etc/xroad/ssl/acme.p12
account-keystore-password:

```

--------------------------------

### Generate and Update System Locales

Source: https://docs.x-road.global/Manuals/ig-cs_x-road_6_central_server_installation_guide.html

Commands to generate and update system locale files after installing a language pack. Example uses US locale.

```bash
sudo locale-gen en_US.UTF-8
```

```bash
sudo update-locale en_US.UTF-8
```

--------------------------------

### Direct GET Request to Pet Store Service

Source: https://docs.x-road.global/Protocols/pr-rest_x-road_message_protocol_for_rest.html

Example of how to call the pet store service directly using curl, specifying the endpoint and accept header.

```bash
curl -X GET "https://petstore.niis.org/v2/pets/1124" -H "accept: application/json"
```

--------------------------------

### Create Password Store and Import Key

Source: https://docs.x-road.global/Manuals/ug-ss_x-road_6_security_server_user_guide.html

Use this command to create a keystore for the message log and import a private key. Ensure the keystore path and alias are correctly specified.

```bash
keytool -keystore /etc/xroad/messagelog/messagelog.p12 -storetype pkcs12 -importpassword -alias key1
```

--------------------------------

### GET Request to Pet Store Service via X-Road

Source: https://docs.x-road.global/Protocols/pr-rest_x-road_message_protocol_for_rest.html

Example of how to call the pet store service through an X-Road security server, including necessary X-Road headers.

```bash
curl -X GET "https://{securityserver}/r1/{serviceId}/v2/pets/1124" -H "accept: application/json" -H "X-Road-Client: {client}"
```

--------------------------------

### Get High-Availability Cluster Status

Source: https://docs.x-road.global/Manuals/ug-cs_x-road_6_central_server_user_guide.html

Retrieves the status of all nodes within the high-availability cluster. This is useful for monitoring the health and operational state of the distributed Central Server setup.

```APIDOC
## GET /api/v1/system/high-availability-cluster/status

### Description
Retrieves the status of all nodes within the high-availability cluster. This is useful for monitoring the health and operational state of the distributed Central Server setup.

### Method
GET

### Endpoint
https://localhost:4000/api/v1/system/high-availability-cluster/status

### Parameters
#### Query Parameters
None

#### Headers
- **Authorization** (string) - Required - API key for authentication. Format: X-Road-ApiKey token=<api key>

### Request Example
```bash
curl --header "Authorization: X-Road-ApiKey token=<api key>" -k https://localhost:4000/api/v1/system/high-availability-cluster/status
```

### Response
#### Success Response (200)
- **status** (object) - Contains the status information for each node in the cluster.
  - **node_id** (string) - The unique identifier of the node.
  - **status** (string) - The current status of the node (e.g., 'registered', 'unregistered', 'error').
  - **last_seen** (string) - Timestamp of the last seen activity from the node.

#### Response Example
```json
{
  "status": {
    "node1": {
      "status": "registered",
      "last_seen": "2023-10-27T10:00:00Z"
    },
    "node2": {
      "status": "registered",
      "last_seen": "2023-10-27T10:01:00Z"
    }
  }
}
```
```

--------------------------------

### Configure Token ID Format in devices.ini

Source: https://docs.x-road.global/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.html

Example of modifying the token identifier format in /etc/xroad/devices.ini to support high availability hardware token setups by removing the slot index.

```ini
token_id_format = {moduleType}{serialNumber}{label}
```

--------------------------------

### Start PostgreSQL Server on Ubuntu

Source: https://docs.x-road.global/Manuals/LoadBalancing/ig-xlb_x-road_external_load_balancer_installation_guide.html

Starts the PostgreSQL server service on Ubuntu systems, specifying the major version and cluster name.

```bash
systemctl start postgresql@<postgresql major version>-serverconf
```

--------------------------------

### Example X-Road REST Request

Source: https://docs.x-road.global/Protocols/pr-rest_x-road_message_protocol_for_rest.html

Illustrates a practical GET request to an X-Road REST service, including the protocol version, client identifier, service ID, path, and query parameters.

```plaintext
GET /r1/INSTANCE/CLASS2/MEMBER2/SUBSYSTEM2/BARSERVICE/v1/bar/zyggy?quu=1
```

--------------------------------

### Create /etc/xroad/db.properties File

Source: https://docs.x-road.global/Manuals/ig-cs_x-road_6_central_server_installation_guide.html

Create and set permissions for the database connection properties file.

```bash
sudo mkdir /etc/xroad
sudo chown xroad:xroad /etc/xroad
sudo chmod 751 /etc/xroad
sudo touch /etc/xroad/db.properties
sudo chmod 0640 /etc/xroad/db.properties
sudo chown xroad:xroad /etc/xroad/db.properties
```

--------------------------------

### Install Locales and LSB Release Packages

Source: https://docs.x-road.global/Manuals/ig-ss_x-road_v6_security_server_installation_guide.html

Ensure that the 'locales' and 'lsb-release' packages are installed on the system. This command installs them if they are not already present.

```bash
sudo apt-get install locales lsb-release
```

--------------------------------

### Install Security Server Packages

Source: https://docs.x-road.global/Manuals/ig-ss_x-road_v6_security_server_installation_guide_for_rhel.html

Use this command to install the core Security Server packages. Optional packages for specific regions like Finland or Iceland can be included.

```bash
sudo yum install xroad-securityserver
```

--------------------------------

### Install X-Road Configuration Proxy

Source: https://docs.x-road.global/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.html

Update the package list and install the xroad-confproxy package. This command installs the Configuration Proxy software.

```bash
sudo apt-get update
sudo apt-get install xroad-confproxy
```

--------------------------------

### Start New Container with Specific Volumes for 7.5.x Upgrade

Source: https://docs.x-road.global/Sidecar/security_server_sidecar_user_guide.html

When upgrading to 7.5.x with a local database, start a new container using the new image and explicitly define volumes for configuration, backup, and the new PostgreSQL 16 data directory.

```bash
docker run -d \
-v sidecar_config_volume:/etc/xroad \
-v sidecar_backup_volume:/var/lib/xroad \
-v <new DB volume name>:/var/lib/postgresql/16/main
... published ports and other parameters, e.g network ...
-e XROAD_ADMIN_USER=<admin user> \
-e XROAD_ADMIN_PASSWORD=<admin password> \
--name <container name> \
niis/xroad-security-server-sidecar:<new version[-type[-variant]>
```

--------------------------------

### Install Security Server Packages

Source: https://docs.x-road.global/Manuals/ig-ss_x-road_v6_security_server_installation_guide.html

Use this command to install the core Security Server packages. Use specific packages like `xroad-securityserver-ee` for Estonia or `xroad-securityserver-fi` for Finland.

```bash
sudo apt install xroad-securityserver
```

--------------------------------

### Install Remote Database Package

Source: https://docs.x-road.global/Manuals/ig-cs_x-road_6_central_server_installation_guide.html

Install the `xroad-database-remote` package to enable the Central Server to use a remote database server instead of a local PostgreSQL installation.

```bash
sudo apt install xroad-database-remote
```

--------------------------------

### Create New Container with Volume Mounts from Temporary Image

Source: https://docs.x-road.global/Sidecar/security_server_sidecar_user_guide.html

Launch a new container using the temporary image, mounting necessary volumes for configuration and data. This step is part of preparing for an upgrade when direct volume mounting is not sufficient.

```bash
docker run -v sidecar-config:/etc/xroad -v sidecar-db:/var/lib/postgresql/16/data ... -n <container-name-temp> sidecar-temp-image
```
Tokens:
Raw