> For the complete documentation index, see [llms.txt](https://docs.devland.is/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devland.is/products/x-road/x-road-security-server-installation-and-registration-steps.md). # 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 ```