# Setting up an X-Road Security Server ## Hardware requirements * 64-bit dual-core Intel, AMD or compatible CPU; AES instruction set support is highly recommended * 2 CPU * 4 GB RAM * 10 GB free disk space (OS partition) and 20-40 GB free disk space on the “/var” partition * 100 Mbps network interface card ## Operating System Requirements This guide assumes one of the following: * **Red Hat Enterprise Linux** * RHEL8+ * **Ubuntu** * 20.04 LTS * 22.04 LTS ***Note**: Installing and configuring an X-Road Security Server requires  `sudo`* permissions on the host. {% hint style="info" %} #### Running in a container Running the X-Road Security Server in a container is outside the scope of this guide, but you can refer to the official [Security Server Sidecar User Guide](< https://github.com/nordic-institute/X-Road/blob/develop/doc/Sidecar/security_server_sidecar_user_guide.md>) for guidance. {% endhint %} ## Network Configuration Check the [Network Configuration sub-page](#network-configuration). ## FQDN Requirements The FQDN of a Security Server should easily identity the Tier and Owner:
EnvironmentTierFQDN Template
IS-DEVDevelopmentxroad-dev.<member's domain>.is
IS-TESTTesting / QA / UAT / Staging et.al.xroad-test.<member's domain>.is
ISProductionxroad-prod1.<member's domain>.is
xroad-prod2.<member's domain>.is
## Installing X-Road ### Provision the `xroad` POSIX user The X-Road Server should be run under a dedicated POSIX user, usually named `xroad` Create this user by running the following command: ```sh sudo useradd \ --system \ --home /var/lib/xroad \ --no-create-home \ --shell /bin/bash \ --user-group \ --comment "X-Road system user" \ xroad ``` {% hint style="info" %} If that user will be used for interactive SSH log-ins, then we must ensure that the Security Server PIN (see below) doesn't get cleared (even though auto-login is configured), by running the following command: ```bash loginctl enable-linger xroad ``` {% endhint %} ### Follow the installation guide NIIS maintains a guide for setting up Security Servers on Ubuntu and RHEL inside their knowlegebase, which you can find here: [How to Set Up a Security Server?](https://nordic-institute.atlassian.net/wiki/spaces/XRDKB/pages/4916118/How+to+Set+Up+a+Security+Server) While following the guide above, take care to override the official documentation with specific steps for the Icelandic environment (*Straumurinn*), outlined at [https://github.com/digitaliceland/Straumurinn](https://github.com/digitaliceland/Straumurinn#getting-started-installing-security-server-and-intial-configuration) #### Certificate generation During installation, a dialog will appear asking for **host** and **IP information** for certificate generation. The latter set of the dialog will be for configuring certificates for the `xroad-proxy-ui-api`. Here it may be desirable to change the value from the auto-detected machine host name to a domain name used for accessing the Admin UI: ![](/files/-MSDDXe8F28AfuXu9ATl) ![](/files/-MSDDXeENQrasy1aMhff) ## Registration Once a Security Server has been successfully installed, the Admin UI can be accessed by pointing a web browser at [https://SECURITYSERVER:4000/](https://securityserver:4000/) . ### Required configuration for registration Before being able to import a Configuration Anchor, the Security Server IP and FQDN must be whitelisted by the operator of the *Straumurinn* X-Road Central Services. To register a Security Server into *Straumurinn,* the following configuration values are required: #### 1. Outgoing IP Address of the Security Server {% hint style="info" %} #### The public outgoing IP address of the server can be found with with the following command from a Security Server terminal session: ``` $ curl ifconfig.me ``` {% endhint %} #### **2. FQDN of the Security Server** {% hint style="info" %} Refer to the section about [#fqdn-requirements](#fqdn-requirements "mention"). {% endhint %} #### **3. Member's Kennitala / SSN** ### Registration contact To register, an email containing the values listed above the should be sent to the operator of the *Straumurinn* X-Road Central Server at #### Example email for registering a Security Server to Central.

Example email for registering a X-Road Security Server to Central

## Post-registration steps Have a look at the [Security Server initial configuration](https://github.com/nordic-institute/X-Road/blob/develop/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide.md#3-security-server-initial-configuration) guide from X-Road. Some of the next steps are derived from there. ### Disable message payload logging The `xroad-securityserver-is` variant has the message logging disabled by default, from X-Road version 6.24.0 onwards. ### Software Token PIN {% hint style="danger" %} Keep the the PIN secret. Keep it safe. {% endhint %} During the Security Server initial configuration, we need to generate a password called the "software token PIN". The PIN is a 12 digit, alpha-numeric password: * * You will be asked to supply the PIN during [Initial Configuraion (see below)](#initial-configuration). #### Configure Auto-Login PIN entry functionality {% hint style="warning" %} If Auto-Login is not configured, the server will require **manual** entry of the Soft Token PIN during startup / restart, which can have implications for the Security Server's reliability. {% endhint %} For the PIN to be entered automatically when starting X-Road services, refer to the [X-Road: Autologin User Guide](https://github.com/nordic-institute/X-Road/blob/develop/doc/Manuals/Utils/ug-autologin_x-road_v6_autologin_user_guide.md) #### Test auto-login PIN entry functionality To verify that auto-login PIN entry works as expected, you can try stopping and starting all the X-Road services like this: ```bash for i in xroad-confclient xroad-proxy xroad-signer xroad-monitor xroad-opmonitor xroad-proxy-ui-api ;\ do \ echo "stopping $i"; \ sudo service $i stop; \ done; sudo systemctl list-units "xroad*" for i in xroad-confclient xroad-proxy xroad-signer xroad-monitor xroad-opmonitor xroad-proxy-ui-api; \ do \ echo "starting $i"; \ sudo service $i start; \ done ``` ### Ensure if all services are up and running ```bash sudo systemctl list-units "xroad*" ``` ### Enable health check endpoint Refer to the [Health check service configuration](https://github.com/nordic-institute/X-Road/blob/develop/doc/Manuals/LoadBalancing/ig-xlb_x-road_external_load_balancer_installation_guide.md#34-health-check-service-configuration) for information on enabling the health check endpoints. ## Initial Configuration ### Configuration Anchors Start by acquiring the Configuration Anchor for the X-Road network, found here: Next, point your browser at the Security Server, on port 4000 and log in. ![The X-Road Security Server Login Screen](/files/-MSDDXeOOGSUpSiP_2Cd) Upload the environment's[ configuration anchor.](#start-by-acquiring-the-configuration-anchors) ![Step 1 of the Initial Configuration Wizard, which allows the User to upload a Configuration Anchor](/files/-MSDDXeRFMIeg6G-dA8O) After anchor has been uploaded, it needs to be confirmed. Ensure that the "Hash Generated" corresponds to the information on the Central Server. Click \[CONFIRM]. ![Configuration Anchor Confirmation Dialog](/files/-MSDDXeUkagUJWEHFrJc) The Configuration Anchor has now been configured and should show you something like the following: ![A successfully configured Configuration Anchor](/files/-MSDDXeXR2VesdYiVagY) ### Owner Member In the initial configuration screen input the values as follows. * Member Class - the Member Class of the organization that maintains the central server. * Member Code - the Member Code of the organization that maintains the central server. * Member Name - is auto completed when Member Code is added. * Security Server Code - unique code identifying the Security Server. * Use short-name for Server Code * Do not use FQDN, ".", "/" or "". * Some extensions use dots as separators, e.g. REST Adapter Service. * X-Road Message Protocol imposes some restrictions on the characters that can be used in X-Road identifiers. The following characters SHALL NOT be used in the identifier values: * Colon * Semicolon * Slash * Backslash * Percent * Path identifiers (such as /../) * Non-printable characters (tab, newline etc.) * * ![Step 2 of the Initial Configuration Wizard, which allows the User to configure the Owner Member of the Security Server](/files/-MSDDXeeEgNzpnevdgLq) ### Software Token PIN * PIN - the password that protects the security server's secret keys. * Repeat PIN - repeat the above PIN. {% hint style="danger" %} Keep the PIN secret. Keep it safe. {% endhint %} ![Step 3 of the Initial Configuration Wizard, which allows the USer to set the Software Token PIN.](/files/-MSDDXehfN6WFTkfQvJ_) The initial configuration was saved successfully. ### CSR certificates ![Configuration window for adding members, clients or subsystems](/files/-MSDDXel3Bf_A4qQyRJP) The security server asks for PIN code. Click the *Please enter soft token PIN* link. ![An X-Road Security Server Admin UI page showing a red banner with the message "Please enter soft token PIN" along with a button for logging in with the PIN](/files/-MSDDXepHA7UDEf0Fzps) Clicking the link navigates to Keys and Certificates page. * Click \[LOG IN] on the `softToken` Service. * Enter PIN Code * Click \[LOG IN] in the modal window. ![Logging in with PIN Code](/files/-MSDDXeriLztL7AvXuSy) The red error message bar should now disappear. ## Final steps ### Configure Timestamping Services Go to: Settings > Timestamping Services and click \[ADD] ![The Settings -> System Parameters page which shows the empty Timestamping Services.](/files/-MSDDXevMUVoovmV6IGj) Pick a time-stamping service from the list and click \[OK.] ![A modal for adding a Timestamping Service.](/files/-MSDDXezSXc70_mlJz0Z) The message "Timestamping message added" should appear. ![Admin UI: The Settings -> System Parameters page which shows that aTimestamping service has been added](/files/-MSDDXf--WXaSoRHcow0) ### Configure SIGN and AUTH Keys #### SIGN Key Navigate to "KEYS AND CERTIFICATES" ![The Keys and Certificate Page](/files/-MSDDXf0182qQHFhvekz) Click \[ADD KEY] ![The wizard for generating a certificate signing key ](/files/-MSDDXf1agX_pwotwYap) Enter ”*sign*” for the "Key Label" and click \[NEXT] ![The CSR Details page inside the Add Key wizard.](/files/-MSDDXf2abTAuzNVkX3w) Fill out the form with the following values: * **Usage**: *SIGNING* * **Client**: *Select the relevant Client from the dropdown.* * **CSR Format:** *PEM* Click \[GENERATE CSR] ![The Generate CSR page inside the Add Key wizard](/files/-MSDDXf5ZgT0iCPOB_zH) Click \[DONE] ![Final confirmation page of the Add Key wizard](/files/-MSDDXf9qUMoeZ44sG4T) The CSR should be downloaded to browser's download folder. ![An overview of SIGN and AUTH keys, showing that a CSR for the SIGN key has been created.](/files/-MSDDXfCQ1GiXbvygNLw) *** #### The AUTH key If you are not already there, start by navigating to "KEYS AND CERTIFICATES"->"SIGN AND AUTH KEYS" of the Admin UI (see above). Click \[ADD KEY] \ Enter “auth” and click \[NEXT] ![Part 1 of the The Add Key wizard, showing "Key Label" being set to "auth"](/files/-MSDDXfGYPpL6qT5E4NX) Choose AUTHENTICATON and change CSR Format to PEM Fill out the form with the following values: * **Usage**: *AUTHENTICATION* * **Certification Service:** *Select the appropriate certification service (there should only be 1)* * **CSR Format:** *PEM* ![Part 2 of the The Add Key wizard: CSR details](/files/-MSDDXfJOPAa2OILi4A_) Enter your Server DNS name (CN) ![Part 3 of the Add Key Wizard: Generate CSR](/files/-MSDDXfMZVAOiADYWm9g) Press GENERATE CSR ![Final confirmation page of the Add Key wizard](/files/-MSDDXfQDxeQj5O3VEuS) The certificate request is downloaded to browser's download folder. ![An overview of SIGN and AUTH keys, showing that a CSR for both the SIGN and AUTH keys have been created.](/files/-MSDDXfRNFPDvGUFCZXO) Now you can see that there are two keys in the overview, Sign and Auth. The certificate request should be sent to . ### Import Certificates Navigate to KEYS AND CERTIFICATIONS and click \[IMPORT CERT]. #### Import the AUTH Certificate Navigate to and select the .pem file containing your certificate. ![The "KEYS AND CERTIFICATIONS" and screen overlaid by a MacOS File System Browser highlighting a .pem file.](/files/-MSDDXfStilZTjKgTSxI) ![The "SIGN AND AUTH KEYS" showing a successfully imported AUTH Certificate](/files/-MSDDXfTKXpiX8qWjhUF) #### Activate auth signed certificate Click the name of the certificate (test.xrd.island.is...) and press Activate *SCREENSHOT NEEDED* #### Import the SIGN Certificate ![](/files/-MSDDXfUaixYeWjhVzTC) ![](/files/-MSDDXfV2Twz4PPTy6O0) ![](/files/-MSDDXfWAteNiDT1zXgF) Finally press **Register** on the auth certificate and enter inn the FQDN of the server and press ADD ![A "Registration request" modal which accepts the Security Server DNS name](/files/-MSDDXf_n9627tJokpR1) !["SIGN AND AUTH KEYS" Screen showing that the status of AUTH Certificate is "Registration in progress"](/files/-MSDDXfbU_vaK6uilJHF) !["SIGN AND AUTH KEYS" Screen showing that both SIGN and AUTH Certificates have been Registered.](/files/-MSDDXfdaNd4BX-dGRUy) ## Confirm communication between two security servers ```bash curl --insecure -H "X-Road-Client: IS-TEST/COM/5302922079/Origo-client" " https://origo-staging.xroad.coldcloudlab.com/r1/IS-TEST/GOV/7005942039/VMST-Protected/APIS/company?name=origo " ``` IS-**DEV** **Ísland.is to Skatturinn**: ```bash curl -H "X-Road-Client: IS-DEV/GOV/10000/island-is-client" "http://localhost:8080/r1/IS-DEV/GOV/10006/Skatturinn-Protected/APIS-v1/company?name=skatturinn" ``` IS-**TEST** **Ísland.is to Skatturinn:** ```bash curl -H "X-Road-Client: IS-TEST/GOV/5501692829/island-is-client" "http://localhost:8080/r1/IS-TEST/GOV/5402696029/Skatturinn-Protected/APIS-v1/company?name=skatturinn" ``` ## Removal of Security Server #### Ubuntu ```bash #!/bin/bash set -x sudo apt-get purge xroad-base sudo apt-get autoremove sudo rm -rf /etc/xroad sudo rm -rf /usr/share/xroad sudo rm -rf /var/lib/xroad sudo rm -rf /var/log/xroad sudo rm -rf /var/tmp/xroad sudo apt-get purge nginx sudo -u postgres dropdb messagelog sudo -u postgres dropdb serverconf sudo -u postgres dropdb op-monitor sudo -u postgres psql -c "drop user serverconf" sudo -u postgres psql -c "drop user messagelog" sudo -u postgres psql -c "drop user opmonitor" sudo -u postgres psql -c "drop user serverconf_admin" sudo -u postgres psql -c "drop user messagelog_admin" sudo -u postgres psql -c "drop user opmonitor_admin" sudo apt-get --purge remove postgresql\* sudo rm -rf /etc/postgresql/ sudo rm -rf /var/lib/postgresql sudo userdel -r postgres ``` #### RHEL ```bash #!/bin/bash set -x sudo yum remove xroad-base sudo rm -rf /etc/xroad sudo rm -rf /usr/share/xroad sudo rm -rf /var/lib/xroad sudo rm -rf /var/log/xroad sudo rm -rf /var/tmp/xroad sudo yum remove nginx sudo -u postgres dropdb messagelog sudo -u postgres dropdb serverconf sudo -u postgres psql -c "drop user serverconf" sudo yum remove postgresql ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.devland.is/products/x-road/x-road-security-server-installation-and-registration-steps.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.