> 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 Security Server Installation, Registration and Configuration ## Hardware requirements * 64-bit dual-core Intel, AMD or compatible CPU; AES instruction set support is highly recommended * 2 CPU * 4 GB RAM * 10 GB free disk space (OS partition) and 20-40 GB free disk space on the “/var” partition * 100 Mbps network interface card ## Operating System Requirements This guide assumes one of the following: * **Red Hat Enterprise Linux** * 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: ![](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-21e7347a435dd128266945a0a07b0431d7a9f414%2F0%20\(2\).png?alt=media) ![](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-f0558afd9306955dcbd1548c8322df5bceab7098%2F1%20\(1\).png?alt=media) ## 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](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-2e59aa48f290a6dffeafc1d2d00c21e760960458%2F4%20\(1\).png?alt=media) 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](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-abbaa4d027a21b575315e499e0c43588c83c245b%2F5.png?alt=media) 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](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-ad5817581e68b7ed78cf14ac419b7ec372f66c17%2F6.png?alt=media) The Configuration Anchor has now been configured and should show you something like the following: ![A successfully configured Configuration Anchor](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-d139b78d1e8858054712c659fefa76cc5178b04a%2F7.png?alt=media) ### 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](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-d7facf6bf575a8932b9dd3d739a3de4270267337%2F8.png?alt=media) ### 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.](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-9cfd30c265371a7df4df57dfec7d1ae36d568827%2F9%20\(1\).png?alt=media) The initial configuration was saved successfully. ### CSR certificates ![Configuration window for adding members, clients or subsystems](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-0738b2ccd80981fb69b7ad163fddfdbd78636415%2F10%20\(1\).png?alt=media) 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](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-fd021406d543d7a5e8c780de53f8cd94ce78e76b%2F11%20\(1\).png?alt=media) 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](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-0bb5d99ffe6345da1f802325cd6e02453c7bb738%2F12.png?alt=media) 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.](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-be78000622cf062adb2a04ce2f1cc83f7d9291a9%2F13%20\(1\).png?alt=media) Pick a time-stamping service from the list and click \[OK.] ![A modal for adding a Timestamping Service.](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-c5181392b1ba0e4db888d0fcf12805e9c7d19825%2F14%20\(1\).png?alt=media) The message "Timestamping message added" should appear. ![Admin UI: The Settings -> System Parameters page which shows that aTimestamping service has been added](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-cfd698859c1076817cc28d8461316c90f22c0c16%2F15.png?alt=media) ### Configure SIGN and AUTH Keys #### SIGN Key Navigate to "KEYS AND CERTIFICATES" ![The Keys and Certificate Page](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-bfe3650e01276d73df1509591139ab2753159ebb%2F16%20\(1\).png?alt=media) Click \[ADD KEY] ![The wizard for generating a certificate signing key ](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-5f06b2c2646de64a3d9ea6d1e4afa1ad90b63c2a%2F17.png?alt=media) Enter ”*sign*” for the "Key Label" and click \[NEXT] ![The CSR Details page inside the Add Key wizard.](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-f6b856b5eac4f1852d9347523530a3f67d0465d0%2F18.png?alt=media) 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](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-2357649c2458db0c1bf77d9fab066480e01ce405%2F19%20\(1\).png?alt=media) Click \[DONE] ![Final confirmation page of the Add Key wizard](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-c0cbc1cf74dd651621d729768957603a938db808%2F20%20\(1\).png?alt=media) 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.](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-aff71fb64fe541083c794739c1811bd5d6a75256%2F21%20\(1\).png?alt=media) *** #### 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"](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-c7a457afe636b99400f7b4ab30c04eafeab97ef3%2F22.png?alt=media) 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](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-491b0f483cb91c6b4bb47066b1105385690c6c02%2F23.png?alt=media) Enter your Server DNS name (CN) ![Part 3 of the Add Key Wizard: Generate CSR](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-5c54648ff16238741170a7c63cb18d2e12eb22bf%2F24%20\(1\).png?alt=media) Press GENERATE CSR ![Final confirmation page of the Add Key wizard](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-7b0286fd5cde4e49d6b7e2652a0d3fe29d2e1a8c%2F25.png?alt=media) 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.](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-84a339b92865041ef15b673b10415923985a559d%2F26%20\(1\).png?alt=media) 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.](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-052b12f71e4cfc25bb07d99608f4093ed5be4920%2F27.png?alt=media) ![The "SIGN AND AUTH KEYS" showing a successfully imported AUTH Certificate](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-1addd2071334ab270f165e0278096f102ee8af6e%2F28%20\(1\).png?alt=media) #### Activate auth signed certificate Click the name of the certificate (test.xrd.island.is...) and press Activate *SCREENSHOT NEEDED* #### Import the SIGN Certificate ![](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-546620546b3c26043e7c7f590a1a531db8d20868%2F29.png?alt=media) ![](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-bb191fd6dc8fa2a542ae67c0d7c6dfe0f05ffde7%2F30.png?alt=media) ![](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-e180fcff0b0960bfd968d9aa7c15f0fdbe68eac3%2F31%20\(1\).png?alt=media) 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](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-61d00f45f105004009d3e8fd20320acd2eefc044%2F32%20\(1\).png?alt=media) !["SIGN AND AUTH KEYS" Screen showing that the status of AUTH Certificate is "Registration in progress"](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-67be2f3e2f4940f2ecb6affce1313ec2a95fed12%2F33.png?alt=media) !["SIGN AND AUTH KEYS" Screen showing that both SIGN and AUTH Certificates have been Registered.](https://3924059971-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJWCB43mX_-7DO7e_Oj%2Fuploads%2Fgit-blob-11b2ae5163ed11601fa3c549ed741761b1f38ad3%2F34%20\(1\).png?alt=media) ## 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 ```