diff --git a/doc/Manuals/ig-cs_x-road_6_central_server_installation_guide.md b/doc/Manuals/ig-cs_x-road_6_central_server_installation_guide.md index 8e53f5d114..cfbaa3a4b7 100644 --- a/doc/Manuals/ig-cs_x-road_6_central_server_installation_guide.md +++ b/doc/Manuals/ig-cs_x-road_6_central_server_installation_guide.md @@ -352,15 +352,19 @@ To configure support for hardware security tokens (smartcard, USB token, Hardwar 1. Install the hardware token support module using the following command: - sudo apt install xroad-addon-hwtokens - + ```bash + sudo apt install xroad-addon-hwtokens + ``` + 2. Install and configure a PKCS\#11 driver for the hardware token according to the manufacturer's instructions. 3. Add the path to the PKCS\#11 driver to the file `/etc/xroad/devices.ini` (as described in the example given in the file). 4. After installing and configuring the driver, the xroad-signer service must be restarted: - sudo service xroad-signer restart + ```bash + sudo service xroad-signer restart + ``` If you are running a high availability (HA) hardware token setup (such as a cluster with replicated tokens) then you may need to constrain the token identifier format such that the token replicas can be seen as the same token. The token identifier format can be changed in `/etc/xroad/devices.ini` via the `token_id_format` property (default value: `{moduleType}{slotIndex}{serialNumber}{label}`). Removing certain parts of the identifier will allow the HA setup to work correctly when one of the tokens goes down and is replaced by a replica. For example, if the token replicas are reported to be on different slots the `{slotIndex}` part should be removed from the identifier format. @@ -413,7 +417,8 @@ Configuration parameters for management web service are specified in the [UG-SYS The installation is successful if the system services are started and the user interface is responding. -- Ensure from the command line that relevant X-Road services are in the `running` state (example output follows). Notice that it is normal for the xroad-confclient to be in `stopped` state on the Central Server since it operates in one-shot mode. +- Ensure from the command line that relevant X-Road services are in the `running` state (example output follows). Notice that it is normal for the xroad-confclient to be in `stopped` state on the Central Server since it operates in one-shot mode. + ```bash sudo systemctl list-units "xroad*" @@ -478,7 +483,7 @@ appoint the subsystem as the management service provider - [UG-CS](#Ref_UG-CS) s It is possible to automatically encrypt Central Server configuration backups. Central Server uses The GNU Privacy Guard (https://www.gnupg.org) for backup encryption and verification. 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). -```bash +```ini [center] backup-encryption-enabled = true diff --git a/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide.md b/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide.md index ba85d207cb..242b34c92f 100644 --- a/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide.md +++ b/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide.md @@ -137,19 +137,16 @@ This document is licensed under the Creative Commons Attribution-ShareAlike 3.0 ## 1 Introduction - ### 1.1 Target Audience The intended audience of this Installation Guide are X-Road Security Server system administrators responsible for installing and using X-Road software. The daily operation and maintenance of the Security Server is covered by its User Guide \[[UG-SS](#Ref_UG-SS)\]. The document is intended for readers with a moderate knowledge of Linux server management, computer networks, and the X-Road working principles. - ### 1.2 Terms and abbreviations See X-Road terms and abbreviations documentation \[[TA-TERMS](#Ref_TERMS)\]. - ### 1.3 References 1. \[UG-SS\] X-Road 7. Security Server User Guide. Document ID: [UG-SS](ug-ss_x-road_6_security_server_user_guide.md) @@ -273,36 +270,46 @@ Requirements to software and settings: * Add an X-Road system administrator user (**reference data: 1.3**) whom all roles in the user interface are granted to. Add a new user with the command - sudo adduser + ```bash + sudo adduser + ``` User roles are discussed in detail in X-Road Security Server User Guide \[[UG-SS](#Ref_UG-SS)\]. Do not use the user name `xroad`, it is reserved for the X-Road system user. * Set the operating system locale. Add following line to the `/etc/environment` file. - LC_ALL=en_US.UTF-8 + ```bash + LC_ALL=en_US.UTF-8 + ``` * Ensure that the packages `locales` and `software-properties-common` are present - - sudo apt-get install locales software-properties-common + + ```bash + sudo apt-get install locales software-properties-common + ``` * Ensure that the locale is available - - sudo locale-gen en_US.UTF-8 - + + ```bash + sudo locale-gen en_US.UTF-8 + ``` ### 2.5 Setup Package Repository Add the X-Road repository’s signing key to the list of trusted keys (**reference data: 1.2**): + ```bash curl https://artifactory.niis.org/api/gpg/key/public | sudo apt-key add - ``` Add X-Road package repository (**reference data: 1.1**) + ```bash sudo apt-add-repository -y "deb https://artifactory.niis.org/xroad-release-deb $(lsb_release -sc)-current main" ``` Update package repository metadata: + ```bash sudo apt update ``` @@ -314,11 +321,13 @@ If you are installing the default setup with local PostgreSQL database and want *This is an optional step.* Optionally, the Security Server can use a remote database server. To avoid installing the default local PostgreSQL server during Security Server installation, first install the `xroad-database-remote` -package. + ```bash sudo apt install xroad-database-remote ``` For the application level backup and restore feature to work correctly, it is important to verify that the local PostgreSQL client has the same or later major version than the remote database server and, if necessary, install a different version of the `postgresql-client` package (see https://www.postgresql.org/download/linux/ubuntu/) + ```bash psql --version psql (PostgreSQL) 12.6 (Ubuntu 12.6-0ubuntu0.20.04.1) @@ -327,11 +336,12 @@ psql -h -U -tAc 'show server_version' 10.16 (Ubuntu 10.16-0ubuntu0.18.04.1) ``` -The Security Server installer can create the database and users for you, but you need to create a configuration file containing the database administrator credentials. +The Security Server installer can create the database and users for you, but you need to create a configuration file containing the database administrator credentials. For advanced setup, e.g. when using separate servers for the databases, sharing a database with several Security Servers, or if storing the database administrator password on the Security Server is not an option, you can create the database users and structure manually as described in [Annex D Create Database Structure Manually](#annex-d-create-database-structure-manually) and then continue to section 2.7. Otherwise, perform the following steps: Create the property file: + ```bash sudo touch /etc/xroad.properties sudo chown root:root /etc/xroad.properties @@ -339,13 +349,16 @@ sudo chmod 600 /etc/xroad.properties ``` Edit `/etc/xroad.properties`. See the example below. Replace parameter values with your own. + ```properties postgres.connection.password = postgres.connection.user = ``` + Note. If Microsoft Azure database for PostgreSQL is used, the connection user needs to be in format `username@hostname`. Before continuing, test that the connection to the database works, e.g. + ```bash psql -h -U -tAc 'show server_version' ``` @@ -379,22 +392,30 @@ Upon the first installation of the packages, the system asks for the following i * The *Subject DN* must be entered in the format: - /CN=server.domain.tld - + ```bash + /CN=server.domain.tld + ``` + * All IP addresses and domain names in use must be entered as alternative names in the format: - IP:1.2.3.4,IP:4.3.2.1,DNS:servername,DNS:servername2.domain.tld + ```bash + IP:1.2.3.4,IP:4.3.2.1,DNS:servername,DNS:servername2.domain.tld + ``` * The Distinguished Name of the owner of the TLS certificate that is used for securing the HTTPS access point of information systems (**reference data: 1.8; 1.11**). The name and IP addresses detected from the system are suggested as default values. * The *Subject DN* must be entered in the format: - /CN=server.domain.tld + ```bash + /CN=server.domain.tld + ``` * All IP addresses and domain names in use must be entered as alternative names in the format: - IP:1.2.3.4,IP:4.3.2.1,DNS:servername,DNS:servername2.domain.tld + ```bash + IP:1.2.3.4,IP:4.3.2.1,DNS:servername,DNS:servername2.domain.tld + ``` * The memory allocation configuration for the Java Virtual Machine (JVM) used by the proxy service. Allowed values are: @@ -415,6 +436,7 @@ The meta-package `xroad-securityserver` also installs metaservices module `xroad The installation is successful if system services are started and the user interface is responding. * Ensure from the command line that X-Road services are in the `running` state (example output follows): + ```bash sudo systemctl list-units "xroad-*" @@ -427,6 +449,7 @@ The installation is successful if system services are started and the user inter xroad-proxy.service loaded active running X-Road Proxy xroad-signer.service loaded active running X-Road signer ``` + * Ensure that the Security Server user interface at https://SECURITYSERVER:4000/ (**reference data: 1.8; 1.6**) can be opened in a Web browser. To log in, use the account name chosen during the installation (**reference data: 1.3**). While the user interface is still starting up, the Web browser may display a connection refused -error. ### 2.10 Installing the Support for Hardware Tokens @@ -435,7 +458,9 @@ To configure support for hardware security tokens (smartcard, USB token, Hardwar 1. Install the hardware token support module using the following command: - sudo apt-get install xroad-addon-hwtokens + ```bash + sudo apt-get install xroad-addon-hwtokens + ``` 2. Install and configure a PKCS\#11 driver for the hardware token according to the manufacturer's instructions. @@ -443,7 +468,9 @@ To configure support for hardware security tokens (smartcard, USB token, Hardwar 4. After installing and configuring the driver, the `xroad-signer` service must be restarted: - sudo systemctl restart xroad-signer + ```bash + sudo systemctl restart xroad-signer + ``` If you are running a high availability (HA) hardware token setup (such as a cluster with replicated tokens) then you may need to constrain the token identifier format such that the token replicas can be seen as the same token. The token identifier format can be changed in `/etc/xroad/devices.ini` via the `token_id_format` property (default value: `{moduleType}{slotIndex}{serialNumber}{label}`). Removing certain parts of the identifier will allow the HA setup to work correctly when one of the tokens goes down and is replaced by a replica. For example, if the token replicas are reported to be on different slots the `{slotIndex}` part should be removed from the identifier format. @@ -481,12 +508,10 @@ The support for environmental monitoring functionality on a Security Server is p During the Security Server initial configuration, the server’s X-Road membership information and the software token’s PIN are set. - ### 3.1 Prerequisites Configuring the Security Server assumes that the Security Server owner is a member of the X-Road. - ### 3.2 Reference Data ATTENTION: Reference items 2.1 - 2.3 in the reference data are provided to the Security Server owner by the X-Road central’s administrator. @@ -504,8 +529,9 @@ The Security Server code and the software token’s PIN will be determined durin ### 3.3 Configuration To perform the initial configuration, open the address - - https://SECURITYSERVER:4000/ +``` +https://SECURITYSERVER:4000/ +``` in a Web browser (**reference data: 1.8; 1.6**). To log in, use the account name chosen during the installation (**reference data: 1.3).** @@ -543,7 +569,7 @@ firewall access rules for specific hosts based on their descriptions. The Security Server has a special `[proxy]` parameter [connector-host](ug-syspar_x-road_v6_system_parameters.md#32-proxy-parameters-proxy) which determines the interfaces that the Security Server uses to listen for incoming connections. The default value for this parameter in the default X-Road packages is `0.0.0.0`, -which makes the Security Server accept connections from any server. For country-specific defaults, please refer to the system parameters documentation. +which makes the Security Server accept connections from any server. For country-specific defaults, please refer to the system parameters documentation. The parameter can be changed by following the [System Parameters guide](ug-syspar_x-road_v6_system_parameters.md#21-changing-the-system-parameter-values-in-configuration-files). @@ -553,9 +579,11 @@ It is possible to automatically encrypt Security Server configuration backups. S for backup encryption and verification. 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 `[proxy]` section (add or edit this section). - [proxy] - backup-encryption-enabled = true - backup-encryption-keyids = , , ... +```ini +[proxy] +backup-encryption-enabled = true +backup-encryption-keyids = , , ... +``` To turn backup encryption on, please change the `backup-encryption-enabled` property value to `true`. By default, backups are encrypted using Security Server's backup encryption key. 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 Security Server's private key is lost. It is up to Security Server's administrator to check that keys used are sufficiently strong, there are no automatic checks. @@ -571,13 +599,17 @@ Security Server backup encryption key is generated during initialisation. To export Security Server's backup encryption public key use the following command: - gpg --homedir /etc/xroad/gpghome --armor --output server-public-key.gpg --export AA/GOV/TS1OWNER/TS1 +```bash +gpg --homedir /etc/xroad/gpghome --armor --output server-public-key.gpg --export AA/GOV/TS1OWNER/TS1 +``` where `AA/GOV/TS1OWNER/TS1` is the Security Server id. The key can then be moved to an external host and imported to GPG keyring with the following command: - gpg --homedir /your_gpg_homedir_here --import server-public-key.gpg +```bash +gpg --homedir /your_gpg_homedir_here --import server-public-key.gpg +``` ### 3.6 Enabling ACME Support @@ -591,70 +623,87 @@ More information about the required configuration is available in the [Security ## 4 Installation Error handling - ### 4.1 Cannot Set LC\_ALL to Default Locale If running the locale command results in the error message - locale: Cannot set LC_ALL to default locale: No such file or directory, +```bash +locale: Cannot set LC_ALL to default locale: No such file or directory, +``` then the support for this particular language has not been installed. To install it, run the command (the example uses the English language): - sudo apt-get install language-pack-en +```bash +sudo apt-get install language-pack-en +``` Then, to update the system’s locale files, run the following commands (the example uses the US locale): - sudo locale-gen en_US.UTF-8 - sudo update-locale en_US.UTF-8 +```bash +sudo locale-gen en_US.UTF-8 +sudo update-locale en_US.UTF-8 +``` Set operating system locale. Add following line to `/etc/environment` file: - LC_ALL=en_US.UTF-8 +```bash +LC_ALL=en_US.UTF-8 +``` After updating the system’s locale settings, it is recommended to restart the operating system. - ### 4.2 PostgreSQL Is Not UTF8 Compatible If the Security Server installation is aborted with the error message - postgreSQL is not UTF8 compatible, +```bash +postgreSQL is not UTF8 compatible, +``` then the PostgreSQL package is installed with a wrong locale. One way to resolve it is to remove the data store created upon the PostgreSQL installation and recreate it with the correct encoding. **WARNING**: All data in the database will be erased! - sudo pg_dropcluster --stop 10 main - LC_ALL="en_US.UTF-8" sudo pg_createcluster --start 10 main +```bash +sudo pg_dropcluster --stop 10 main +LC_ALL="en_US.UTF-8" sudo pg_createcluster --start 10 main +``` To complete the interrupted installation, run the command - sudo apt-get -f install - +```bash +sudo apt-get -f install +``` ### 4.3 Could Not Create Default Cluster If the following error message is displayed during PostgreSQL installation: - Error: The locale requested by the environment is invalid. - Error: could not create default cluster. Please create it manually with pg_createcluster 10 main –start, +``` +Error: The locale requested by the environment is invalid. +Error: could not create default cluster. Please create it manually with pg_createcluster 10 main –start, +``` use the following command to create the PostgreSQL data cluster: - LC_ALL="en_US.UTF-8" sudo pg_createcluster --start 10 main +```bash +LC_ALL="en_US.UTF-8" sudo pg_createcluster --start 10 main +``` The interrupted installation can be finished using - sudo apt-get -f install - +```bash +sudo apt-get -f install +``` ### 4.4 Is Postgres Running On Port 5432? If the following error message appears during installation - Is postgres running on port 5432 ? - Aborting installation! please fix issues and rerun with apt-get -f install, - +``` +Is postgres running on port 5432 ? +Aborting installation! please fix issues and rerun with apt-get -f install, +``` check if any of the following errors occurred during the installation of PostgreSQL. * Error installing the data cluster. Refer to section [“Could not create default cluster”](#43-could-not-create-default-cluster). @@ -663,21 +712,24 @@ check if any of the following errors occurred during the installation of Postgre The interrupted installation can be finished using - sudo apt-get -f install - +```bash +sudo apt-get -f install +``` ### 4.5 Different versions of xroad-\* packages after successful upgrade Sometimes, after using `sudo apt-get upgrade` command, some of the packages are not upgraded. In the following example `xroad-securityserver` package version is still 6.8.3 although other packages are upgraded to 6.8.5: - # sudo dpkg -l | grep xroad- - ii xroad-addon-messagelog 6.8.5.20160929134539gitfe60f90 - ii xroad-addon-metaservices 6.8.5.20160929134539gitfe60f90 - ii xroad-addon-wsdlvalidator 6.8.5.20160929134539gitfe60f90 - ii xroad-common 6.8.5.20160929134539gitfe60f90 - ii xroad-jetty9 6.8.5.20160929134539gitfe60f90 - ii xroad-proxy 6.8.5.20160929134539gitfe60f90 - ii xroad-securityserver 6.8.3-3-201605131138 +```bash +# sudo dpkg -l | grep xroad- +ii xroad-addon-messagelog 6.8.5.20160929134539gitfe60f90 +ii xroad-addon-metaservices 6.8.5.20160929134539gitfe60f90 +ii xroad-addon-wsdlvalidator 6.8.5.20160929134539gitfe60f90 +ii xroad-common 6.8.5.20160929134539gitfe60f90 +ii xroad-jetty9 6.8.5.20160929134539gitfe60f90 +ii xroad-proxy 6.8.5.20160929134539gitfe60f90 +ii xroad-securityserver 6.8.3-3-201605131138 +``` `apt-get upgrade` command doesn’t install new packages - in this particular case new packages `xroad-monitor` and `xroad-addon-proxymonitor` installation is needed for upgrade of `xroad-securityserver` package. @@ -740,7 +792,6 @@ Finally, we can upgrade to our target version 7.3.x as follows. apt upgrade xroad-securityserver ``` - ## Annex A Security Server Default Database Properties `/etc/xroad/db.properties` @@ -772,7 +823,6 @@ op-monitor.hibernate.hikari.dataSource.currentSchema = opmonitor,public op-monitor.hibernate.jdbc.use_streams_for_binary = true ``` - ## Annex B Default Database Users | User | Database | Privileges | Description | @@ -785,22 +835,18 @@ op-monitor.hibernate.jdbc.use_streams_for_binary = true | opmonitor_admin | op-monitor | CREATE,TEMPORARY,CONNECT | The database user used to create/update the op-monitor schema. | | postgres | ALL | ALL | PostgreSQL database default superuser. | - ## Annex C Deployment Options - ### C.1 General X-Road Security Server has multiple deployment options. The simplest choice is to have a single Security Server with local database. This is usually fine for majority of the cases, but there are multiple reasons to tailor the deployment. - ### C.2 Local Database The simplest deployment option is to use a single Security Server with local database. For development and testing purposes there is rarely need for anything else, but for production the requirements may be stricter. ![Security Server with local database](img/ig-ss_local_db.svg) - ### C.3 Remote Database It is possible to use a remote database with Security Server. This option is sometimes used in development and testing when there's need to externalize the database state. @@ -809,21 +855,18 @@ Security Server supports a variety of cloud databases including AWS RDS and Azur ![Security Server with remote database](img/ig-ss_remote_db.svg) - ### C.4 High Availability Setup In production systems it's rarely acceptable to have a single point of failure. Security Server supports provider side high availability setup via so called internal load balancing mechanism. The setup works so that the same member / member class / member code / subsystem / service code is configured on multiple Security Servers and X-Road will then route the request to the server that responds the fastest. Note that this deployment option does not provide performance benefits, just redundancy. ![Security Server high-availability setup](img/ig-ss_high_availability.svg) - ### C.5 Load Balancing Setup Busy production systems may need scalable performance in addition to high availability. X-Road supports external load balancing mechanism to address both of these problems simultaneously. A load balancer is added in front of a Security Server cluster to route the requests based on selected algorithm. This deployment option is extensively documented in \[[IG-XLB](#Ref_IG-XLB)\]. ![Security Server load balancing setup](img/ig-ss_load_balancing.svg) - ### C.6 Summary The following table lists a summary of the Security Server deployment options and indicates whether they are aimed for development or production use. @@ -846,6 +889,7 @@ Depending on installed components, the Security Server uses one to three databas These databases can be hosted on one database server (default setup), or you can use several servers. Login to the database server(s) as the superuser (`postgres` by default) to run the commands, e.g. + ```bash psql -h : -U -d postgres ``` @@ -932,6 +976,7 @@ Lastly, customize the database connection properties to match the values used wh Note. When using Microsoft Azure PostgreSQL, the user names need to be in format `username@hostname` in the properties files. Create the configuration file `/etc/xroad.properties`. + ```bash sudo touch /etc/xroad.properties sudo chown root:root /etc/xroad.properties @@ -939,6 +984,7 @@ sudo chmod 600 /etc/xroad.properties ``` Edit `/etc/xroad.properties` and add/update the following properties (if you customized the role names, use your own). The admin users are used to run database migrations during the install and upgrades. + ```properties serverconf.database.admin_user = serverconf.database.admin_password = @@ -949,6 +995,7 @@ op-monitor.database.admin_password = ``` Create the `/etc/xroad/db.properties` file + ```bash sudo mkdir /etc/xroad sudo chown xroad:xroad /etc/xroad @@ -960,6 +1007,7 @@ sudo chown xroad:xroad /etc/xroad/db.properties Edit the `/etc/xroad/db.properties` file and add/update the following connection properties (if you customized the database, user, and/or role names, use the customized values). The database connection url format is `jdbc:postgresql://:/` + ```properties serverconf.hibernate.connection.url = jdbc:postgresql://:/ serverconf.hibernate.connection.username = diff --git a/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide_for_rhel.md b/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide_for_rhel.md index bb4ccb02f6..d4a6a935b2 100644 --- a/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide_for_rhel.md +++ b/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide_for_rhel.md @@ -241,48 +241,59 @@ Sample installation steps are provided below. * Check the current java version: - java -version + ```bash + java -version + ``` If the current Java version is 21, following steps should be skipped. If not, install Java 21 (OpenJDK): - sudo yum install openjdk-21-jre-headless +```bash +sudo yum install openjdk-21-jre-headless +``` After the installation, verify the current java version: - - java -version + +```bash +java -version +``` The output should contain Java version 21. If it does not, set the default Java version to 21 using *alternatives*: - sudo alternatives --config java +```bash +sudo alternatives --config java +``` ### 2.4 Preparing OS * Set the operating system locale. Add following line to the `/etc/environment` file. - LC_ALL=en_US.UTF-8 +```bash +LC_ALL=en_US.UTF-8 +``` * Install `yum-utils`, a collection of utilities that integrate with yum to extend its native features. - sudo yum install yum-utils - +```bash +sudo yum install yum-utils +``` ### 2.5 Setup Package Repository Add X-Road package repository (**reference data: 1.1**) and Extra Packages for Enterprise Linux (EPEL) repository: - ```bash - RHEL_MAJOR_VERSION=$(source /etc/os-release;echo ${VERSION_ID%.*}) - sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-${RHEL_MAJOR_VERSION}.noarch.rpm - sudo yum-config-manager --add-repo https://artifactory.niis.org/xroad-release-rpm/rhel/${RHEL_MAJOR_VERSION}/current - ``` +```bash +RHEL_MAJOR_VERSION=$(source /etc/os-release;echo ${VERSION_ID%.*}) +sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-${RHEL_MAJOR_VERSION}.noarch.rpm +sudo yum-config-manager --add-repo https://artifactory.niis.org/xroad-release-rpm/rhel/${RHEL_MAJOR_VERSION}/current +``` The following packages are fetched from EPEL: `crudini`, and `rlwrap`. Add the X-Road repository’s signing key to the list of trusted keys (**reference data: 1.2**): - ```bash - sudo rpm --import https://artifactory.niis.org/api/gpg/key/public - ``` +```bash +sudo rpm --import https://artifactory.niis.org/api/gpg/key/public +``` ### 2.6 Database Setup @@ -301,6 +312,7 @@ sudo yum install postgresql-server postgresql-contrib *This is an optional step.* Optionally, the Security Server can use a remote database server. To avoid installing the default local PostgreSQL server during Security Server installation, install the `xroad-database-remote` -package, which will also install the PostgreSQL client and create the `xroad` system user and configuration directories (`/etc/xroad`). + ```bash sudo yum install xroad-database-remote ``` @@ -312,6 +324,7 @@ sudo yum install postgresql-contrib ``` For the application level backup and restore feature to work correctly, it is important to verify that the local PostgreSQL client has the same or later major version than the remote database server and, if necessary, install a different version of the `postgresql` package (see https://www.postgresql.org/download/linux/redhat/) + ```bash psql --version psql (PostgreSQL) 10.16 @@ -325,6 +338,7 @@ The Security Server installer can create the database and users for you, but you For advanced setup, e.g. when using separate instances for the different databases, sharing a database with several Security Servers, or if storing the database administrator password on the Security Server is not an option, you can create the database users and structure manually as described in [Annex D Create Database Structure Manually](#annex-d-create-database-structure-manually) and then continue to section 2.7. Otherwise, perform the following steps: Create the property file for database credentials: + ```bash sudo touch /etc/xroad.properties sudo chown root:root /etc/xroad.properties @@ -332,10 +346,12 @@ sudo chmod 600 /etc/xroad.properties ``` Edit `/etc/xroad.properties`. See the example below. Replace parameter values with your own. + ```properties postgres.connection.password = postgres.connection.user = ``` + Note. If Microsoft Azure database for PostgreSQL is used, the connection user needs to be in format `username@hostname`. @@ -343,6 +359,7 @@ For additional security, the `postgresql.connection.*` properties can be removed Create the `/etc/xroad/db.properties` file + ```bash sudo touch /etc/xroad/db.properties sudo chmod 0640 /etc/xroad/db.properties @@ -350,16 +367,20 @@ sudo chown xroad:xroad /etc/xroad/db.properties ``` Add the following properties to the `/etc/xroad/db.properties` file (replace parameters with your own): + ```properties serverconf.hibernate.connection.url = jdbc:postgresql://:/serverconf messagelog.hibernate.connection.url = jdbc:postgresql://:/messagelog ``` + If installing the optional xroad-opmonitor component, also add the following line + ```properties op-monitor.hibernate.connection.url = jdbc:postgresql://:/op-monitor ``` Before continuing, test that the connection to the database works, e.g. + ```bash psql -h -U -tAc 'show server_version' ``` @@ -378,17 +399,17 @@ echo "ENABLE_MESSAGELOG=false" | sudo tee /etc/sysconfig/xroad-addon-messagelog Issue the following command to install the Security Server packages (use package `xroad-securityserver-fi` to include configuration specific to Finland; use package `xroad-securityserver-is` to include configuration specific to Iceland; there's no Estonia-specific package for RHEL): - ```bash - sudo yum install xroad-securityserver - ``` +```bash +sudo yum install xroad-securityserver +``` The meta-package `xroad-securityserver` also installs metaservices module `xroad-addon-metaservices`, messagelog module `xroad-addon-messagelog` and WSDL validator module `xroad-addon-wsdlvalidator`. The meta-packages `xroad-securityserver-fi`, `xroad-securityserver-is`, and `xroad-securityserver-fo` install operational data monitoring module `xroad-addon-opmonitoring`. Add system user (**reference data: 1.3**) whom all roles in the user interface are granted to. Add a new user with the command - ```bash - sudo xroad-add-admin-user - ``` +```bash +sudo xroad-add-admin-user +``` User roles are discussed in detail in X-Road Security Server User Guide \[[UG-SS](#Ref_UG-SS)\]. @@ -396,9 +417,9 @@ User roles are discussed in detail in X-Road Security Server User Guide \[[UG-SS Once the installation is completed, start the Security Server - ```bash - sudo systemctl start xroad-proxy - ``` +```bash +sudo systemctl start xroad-proxy +``` ### 2.9 Post-Installation Checks @@ -458,7 +479,9 @@ The Security Server code and the software token’s PIN will be determined durin To perform the initial configuration, open the address - https://SECURITYSERVER:4000/ +``` +https://SECURITYSERVER:4000/ +``` in a Web browser (**reference data: 1.8; 1.6**). To log in, use the account name chosen during the installation (**reference data: 1.3).** @@ -484,9 +507,11 @@ It is possible to automatically encrypt Security Server configuration backups. S for backup encryption and verification. 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 `[proxy]` section (add or edit this section). - [proxy] - backup-encryption-enabled = true - backup-encryption-keyids = , , ... +```ini +[proxy] +backup-encryption-enabled = true +backup-encryption-keyids = , , ... +``` To turn backup encryption on, please change the `backup-encryption-enabled` property value to `true`. By default, backups are encrypted using Security Server's backup encryption key. 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 Security Server's private key is lost. It is up to Security Server's administrator to check that keys used are sufficiently strong, there are no automatic checks. @@ -502,13 +527,17 @@ Security Server backup encryption key is generated during initialisation. To export Security Server's backup encryption public key use the following command: - gpg --homedir /etc/xroad/gpghome --armor --output server-public-key.gpg --export AA/GOV/TS1OWNER/TS1 +```bash +gpg --homedir /etc/xroad/gpghome --armor --output server-public-key.gpg --export AA/GOV/TS1OWNER/TS1 +``` where `AA/GOV/TS1OWNER/TS1` is the Security Server id. The key can then be moved to an external host and imported to GPG keyring with the following command: - gpg --homedir /your_gpg_homedir_here --import server-public-key.gpg +```bash +gpg --homedir /your_gpg_homedir_here --import server-public-key.gpg +``` ### 3.5 Enabling ACME Support @@ -685,6 +714,7 @@ Depending on installed components, the Security Server uses one to three databas These databases can be hosted on one database server (default setup), or you can use several servers. Login to the database server(s) as the superuser (`postgres` by default) to run the commands, e.g. + ```bash psql -h : -U -d postgres ``` @@ -757,6 +787,7 @@ Lastly, customize the database connection properties to match the values used wh Note. When using Microsoft Azure PostgreSQL, the user names need to be in format `username@hostname` in the properties files. Create the configuration file `/etc/xroad.properties`. + ```bash sudo touch /etc/xroad.properties sudo chown root:root /etc/xroad.properties @@ -764,6 +795,7 @@ sudo chmod 600 /etc/xroad.properties ``` Edit `/etc/xroad.properties` and add/update the following properties (if you customized the role names, use your own). The admin users are used to run database migrations during the install and upgrades. + ```properties serverconf.database.admin_user = serverconf_admin serverconf.database.admin_password = @@ -774,6 +806,7 @@ messagelog.database.admin_password = ``` Create the `/etc/xroad/db.properties` file + ```bash sudo mkdir /etc/xroad sudo chown xroad:xroad /etc/xroad @@ -785,6 +818,7 @@ sudo chown xroad:xroad /etc/xroad/db.properties Edit the `/etc/xroad/db.properties` file and add/update the following connection properties (if you customized the database, user, and/or role names, use the customized values). The database connection url format is `jdbc:postgresql://:/` + ```properties serverconf.hibernate.connection.url = jdbc:postgresql://:/serverconf serverconf.hibernate.connection.username = serverconf diff --git a/doc/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.md b/doc/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.md index e21d521dca..d11fe07eea 100644 --- a/doc/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.md +++ b/doc/Manuals/ug-cp_x-road_v6_configuration_proxy_manual.md @@ -147,16 +147,22 @@ To install the X-Road Configuration Proxy software, follow these steps. 1. Add the X-Road repository’s signing key to the list of trusted keys (**reference data: 1.2**): - curl https://artifactory.niis.org/api/gpg/key/public | sudo apt-key add - + ```bash + curl https://artifactory.niis.org/api/gpg/key/public | sudo apt-key add - + ``` 2. Add X-Road package repository (**reference data: 1.1**) - sudo apt-add-repository -y "deb https://artifactory.niis.org/xroad-release-deb $(lsb_release -sc)-current main" + ```bash + sudo apt-add-repository -y "deb https://artifactory.niis.org/xroad-release-deb $(lsb_release -sc)-current main" + ``` 3. Issue the following commands to install the Configuration Proxy packages: - sudo apt-get update - sudo apt-get install xroad-confproxy + ```bash + sudo apt-get update + sudo apt-get install xroad-confproxy + ``` ### 2.6 Post-Installation Checks @@ -196,7 +202,9 @@ To configure support for hardware security tokens (smartcard, USB token, Hardwar 1. Install the hardware token support module using the following command: - sudo apt-get install xroad-addon-hwtokens + ```bash + sudo apt-get install xroad-addon-hwtokens + ``` 2. Install and configure a PKCS\#11 driver for the hardware token according to the manufacturer's instructions. @@ -204,7 +212,9 @@ To configure support for hardware security tokens (smartcard, USB token, Hardwar 4. After installing and configuring the driver, the `xroad-signer` service must be restarted: - sudo service xroad-signer restart + ```bash + sudo service xroad-signer restart + ``` If you are running a high availability (HA) hardware token setup (such as a cluster with replicated tokens) then you may need to constrain the token identifier format such that the token replicas can be seen as the same token. The token identifier format can be changed in `/etc/xroad/devices.ini` via the `token_id_format` property (default value: `{moduleType}{slotIndex}{serialNumber}{label}`). Removing certain parts of the identifier will allow the HA setup to work correctly when one of the tokens goes down and is replaced by a replica. For example, if the token replicas are reported to be on different slots the `{slotIndex}` part should be removed from the identifier format. @@ -439,7 +449,7 @@ confproxy-generate-anchor -p -f If generation was successful the output should be simply: -```bash +``` confproxy-generate-anchor -p PROXY -f /home/xroad/anchor.xml Generated anchor xml to '/home/xroad/anchor.xml' @@ -489,7 +499,7 @@ confproxy-del-signing-key -p -k where <SIGNING_KEY_ID> can be found in the output of 'confproxy-view-conf' (example output follows): -```bash +``` confproxy-del-signing-key -p PROXY -k QWERTY123 Deleted key from signer diff --git a/doc/Manuals/ug-cs_x-road_6_central_server_user_guide.md b/doc/Manuals/ug-cs_x-road_6_central_server_user_guide.md index f22dd9d589..4e2c5bc1f3 100644 --- a/doc/Manuals/ug-cs_x-road_6_central_server_user_guide.md +++ b/doc/Manuals/ug-cs_x-road_6_central_server_user_guide.md @@ -1217,7 +1217,9 @@ Additional keys for backup encryption should be generated and stored outside Cen 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 +```bash +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. @@ -1245,7 +1247,8 @@ gpg --homedir /etc/xroad/gpghome/ --edit-key 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.: -```bash + +```ini [center] backup-encryption-enabled = true backup-encryption-keyids = 87268CC66939CFF3 @@ -1272,7 +1275,9 @@ 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 +```bash +gpg --homedir /etc/xroad/gpghome --armor --output server-public-key.gpg --export +``` where `` is the Central Server instance id, for example, `EE`. @@ -1680,29 +1685,29 @@ Prerequisites 1. Shutdown X-Road processes. -```bash -systemctl stop "xroad*" -``` + ```bash + systemctl stop "xroad*" + ``` 2. 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. -```bash -pg_dump -F t -h 127.0.0.1 -p 5432 -U centerui_admin -f centerui_production.dat centerui_production -``` + ```bash + pg_dump -F t -h 127.0.0.1 -p 5432 -U centerui_admin -f centerui_production.dat centerui_production + ``` 3. Shut down and mask local postgresql so it won't start when xroad-proxy starts. -```bash -systemctl stop postgresql -``` + ```bash + systemctl stop postgresql + ``` -```bash -systemctl mask postgresql -``` + ```bash + systemctl mask postgresql + ``` 4. Connect to the remote database server as the superuser postgres and create roles, databases and access permissions as follows. -```bash + ```bash psql -h -p -U postgres CREATE DATABASE centerui_production ENCODING 'UTF8'; REVOKE ALL ON DATABASE centerui_production FROM PUBLIC; @@ -1722,43 +1727,43 @@ systemctl mask postgresql 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; -``` + ``` 5. Restore the database dumps on the remote database host. -```bash -pg_restore -h -p -U centerui_admin -O -n centerui -1 -d centerui_production centerui_production.dat -``` + ```bash + pg_restore -h -p -U centerui_admin -O -n centerui -1 -d centerui_production centerui_production.dat + ``` 6. Create properties file `/etc/xroad.properties` if it does not exist. -```bash + ```bash sudo touch /etc/xroad.properties sudo chown root:root /etc/xroad.properties sudo chmod 600 /etc/xroad.properties -``` + ``` 7. Make sure `/etc/xroad.properties` is containing the admin user & its password. -```properties + ```properties centerui.database.admin_user = centerui_admin centerui.database.admin_password = -``` + ``` 8. Update `/etc/xroad/db.properties` contents with correct database host URLs and passwords. -```properties + ```properties spring.datasource.username= spring.datasource.password= spring.datasource.hikari.data-source-properties.currentSchema= spring.datasource.url=jdbc:postgresql://:/ -``` + ``` 9. Start again the X-Road services. -```bash -systemctl start "xroad*" -``` + ```bash + systemctl start "xroad*" + ``` ## 19. Additional Security Hardening @@ -1772,7 +1777,7 @@ First step to pass additional configurations is to create `db_libpq.env` file in Example of file contents: -```bash +``` export PGSSLMODE="verify-full" export PGSSLCERT="/etc/xroad/ssl/internal.crt" export PGSSLKEY="/etc/xroad/ssl/internal.key" diff --git a/doc/Manuals/ug-sec_x_road_security_hardening.md b/doc/Manuals/ug-sec_x_road_security_hardening.md index 6d5f712171..c351a2d3c1 100644 --- a/doc/Manuals/ug-sec_x_road_security_hardening.md +++ b/doc/Manuals/ug-sec_x_road_security_hardening.md @@ -139,29 +139,42 @@ To harden the user account security, make sure that users are not allowed to acc 1. Create a user group in which users are allowed to connect to the server via SSH while all other users are denied. 2. Add users which should have SSH access to newly created group. 3. Add the following line to `/etc/ssh/sshd_config`: - - AllowGroups + + ```bash + AllowGroups + ``` 4. Restart the SSH service: - sudo systemctl restart sshd + ```bash + sudo systemctl restart sshd + ``` It is also recommended to disable SSH password login and allow key-based authentication only. Before this modification, add users' public keys to the server. Edit `/etc/ssh/sshd_config` and add the following lines: - ChallengeResponseAuthentication no - PasswordAuthentication no +``` +ChallengeResponseAuthentication no +PasswordAuthentication no +``` + Restart the SSH service once again: - sudo systemctl restart sshd +```bash +sudo systemctl restart sshd +``` In addition, the users should be prevented from logging in to the system. This can be achieved by issuing the following command on Ubuntu: - usermod -s /bin/false user +```bash +usermod -s /bin/false user +``` On RHEL, the corresponding command is: - usermod -s /sbin/nologin user +```bash +usermod -s /sbin/nologin user +``` The system administrator should also implement a monitoring and alerting system regarding anomalous logins. @@ -184,8 +197,10 @@ On the service provider side, the Security Server administrator can limit the mi For example, setting the value `server-min-supported-client-version = 7.3.1` means that client Security Server version should be at least `7.3.1`: - [proxy] - server-min-supported-client-version = 7.3.1 +```ini +[proxy] +server-min-supported-client-version = 7.3.1 +``` ## 5. Publish global configuration over HTTPS diff --git a/doc/Manuals/ug-sigdoc_x-road_signed_document_download_and_verification_manual.md b/doc/Manuals/ug-sigdoc_x-road_signed_document_download_and_verification_manual.md index 5b5926f2aa..4438c8c33c 100644 --- a/doc/Manuals/ug-sigdoc_x-road_signed_document_download_and_verification_manual.md +++ b/doc/Manuals/ug-sigdoc_x-road_signed_document_download_and_verification_manual.md @@ -69,7 +69,9 @@ This document describes the retrieving and verification process of the signed an The security server offers the asic web service for downloading its signed documents. The service is used via HTTP GET requests to the service URL: - http://SECURITYSERVER/asic +``` +http://SECURITYSERVER/asic +``` where `SECURITYSERVER` is the actual address of the security server. @@ -88,7 +90,9 @@ The service requires the identifier of the corresponding message and the X-Road Thus, in order to retrieve the signed document for a message with transaction identifier *abc12345* exchanged by security server *sec1.gov* by client *EE/ENT/CLIENT1/SUB*, the request URL is - http://sec1.gov/asic?queryId=abc12345&xRoadInstance=EE&memberClass=ENT&memberCode=CLIENT1&subsystemCode=SUB +``` +http://sec1.gov/asic?queryId=abc12345&xRoadInstance=EE&memberClass=ENT&memberCode=CLIENT1&subsystemCode=SUB +``` If a message with the given identifier was indeed exchanged by the security server and by the specified client, the server would respond with a ZIP archive (content-type `application/zip`, filename `queryId.zip`), which contains signed documents for all requests and responses that match the specified parameters. @@ -119,7 +123,9 @@ If this behavior is not desired the following parameter can be used: Thus, in order to retrieve the signed document for a message with transaction identifier *abc12345* exchanged by the security server *sec1.gov* by the client *EE/ENT/CLIENT1/SUB* and force any missing timestamps to be created, the request URL is - http://sec1.gov/asic?queryId=abc12345&xRoadInstance=EE&memberClass=ENT&memberCode=CLIENT1&subsystemCode=SUB&force +``` +http://sec1.gov/asic?queryId=abc12345&xRoadInstance=EE&memberClass=ENT&memberCode=CLIENT1&subsystemCode=SUB&force +``` Should there be no working time-stamping provider available to the security server, the signed document retrieval service will respond with the error message "Failed to get timestamp from any time-stamping providers". @@ -144,74 +150,86 @@ Verification of signed documents is done by the asicverifier utility tool. The t The asicverifier utility is shipped with security server and it is located in the following directory: - /usr/share/xroad/jlib/asicverifier.jar +``` +/usr/share/xroad/jlib/asicverifier.jar +``` ### 3.1 Usage The asicverifier utility is run as follows: - java -jar asicverifier.jar ( --version | ) +```bash +java -jar asicverifier.jar ( --version | ) +``` where `` is the path to the signed document being verified and `` is the path to the verification configuration for this container (see Section 3.2 ). You can check the version of the asicverifier tool with the `--version` option. If verification is successful the output will be similar to: - Loading configuration from18 verificationconf/... - Verifying ASiC container "abc12345-request-1ab2c3d4f5.asice" ... - Verification successful. - Signer - Certificate: - Subject: CN=CLIENT1, O=COM, C=EE - Issuer: C=EE, O=EJBCA Sample, CN=AdminCA1 - Serial number: 897779140320284054 - Valid from: Mon May 04 14:30:38 EEST 2015 - Valid until: Wed May 03 14:30:38 EEST 2017 - ID: MEMBER:EE/COM/CLIENT1 - OCSP response - Signed by: - Subject: C=EE, O=EJBCA Sample, CN=AdminCA1 - Issuer: C=EE, O=EJBCA Sample, CN=AdminCA1 - Serial number: 6005434255669835317 - Valid from: Thu Jun 14 13:04:29 EEST 2012 - Valid until: Sun Jun 12 13:04:29 EEST 2022 - Produced at: Fri Jun 05 08:47:11 EEST 2015 - Timestamp - Signed by: - Subject: CN=timestamp1, O=Internet Widgits Pty Ltd, C=EE - Issuer: CN=timestamp1, O=Internet Widgits Pty Ltd, C=EE - Serial number: 12319570547049363959 - Valid from: Sun Nov 30 22:13:44 EET 2014 - Valid until: Wed Nov 27 22:13:44 EET 2024 - Date: Fri Jun 05 09:31:37 EEST 2015 - - - Would you like to extract the signed files? (y/n) y - Created file message.xml - Files successfully extracted. +``` +Loading configuration from18 verificationconf/... +Verifying ASiC container "abc12345-request-1ab2c3d4f5.asice" ... +Verification successful. +Signer + Certificate: + Subject: CN=CLIENT1, O=COM, C=EE + Issuer: C=EE, O=EJBCA Sample, CN=AdminCA1 + Serial number: 897779140320284054 + Valid from: Mon May 04 14:30:38 EEST 2015 + Valid until: Wed May 03 14:30:38 EEST 2017 + ID: MEMBER:EE/COM/CLIENT1 +OCSP response + Signed by: + Subject: C=EE, O=EJBCA Sample, CN=AdminCA1 + Issuer: C=EE, O=EJBCA Sample, CN=AdminCA1 + Serial number: 6005434255669835317 + Valid from: Thu Jun 14 13:04:29 EEST 2012 + Valid until: Sun Jun 12 13:04:29 EEST 2022 + Produced at: Fri Jun 05 08:47:11 EEST 2015 +Timestamp + Signed by: + Subject: CN=timestamp1, O=Internet Widgits Pty Ltd, C=EE + Issuer: CN=timestamp1, O=Internet Widgits Pty Ltd, C=EE + Serial number: 12319570547049363959 + Valid from: Sun Nov 30 22:13:44 EET 2014 + Valid until: Wed Nov 27 22:13:44 EET 2024 + Date: Fri Jun 05 09:31:37 EEST 2015 + + +Would you like to extract the signed files? (y/n) y +Created file message.xml +Files successfully extracted. +``` As can be seen from the example above, the asicverifier tool will optionally extract the signed files to the working directory. In the case of REST message, the request/response line and headers are in `message.xml` and the REST body (if logged) is present in a file `attachment1`. Should the verification fail, the reason for failure will be presented to the user in an error message. For example: - Loading configuration from verificationconf/... - Verifying ASiC container "abc12345-request-1ab2c3d4f5.asice" ... - Verification failed: Certificate is not issued by approved certification service provider. - - Would you like to extract the signed files? (y/n) y - Created file message.xml - Files successfully extracted. +``` +Loading configuration from verificationconf/... +Verifying ASiC container "abc12345-request-1ab2c3d4f5.asice" ... +Verification failed: Certificate is not issued by approved certification service provider. + +Would you like to extract the signed files? (y/n) y +Created file message.xml +Files successfully extracted. +``` In case of verification failure, the asicverifier tool will optionally extract the signed files to the working directory. Notice that when `messagelog.message-body-logging` property is set to `false`, the verification always fails with the error message: - Verification failed: Signature is not valid +``` +Verification failed: Signature is not valid +``` ### 3.2 Verification Configuration The asicverifier tool requires the proper verification configuration containing certificates needed by the verification process. The verification configuration can be downloaded from the same security server by making a HTTP GET request to the URL: - http://SECURITYSERVER/verificationconf +``` +http://SECURITYSERVER/verificationconf +``` where `SECURITYSERVER` is the actual address of the security server. @@ -219,5 +237,6 @@ The *verificationconf* service has no parameters and responds with a ZIP archive A convenient way to download the verification configuration is with the web browser or use of the curl tool: - curl -J -O http://sec1.gov/verificationconf - +```bash +curl -J -O http://sec1.gov/verificationconf +``` diff --git a/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md b/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md index e4436ef061..32acaa4aa8 100644 --- a/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md +++ b/doc/Manuals/ug-ss_x-road_6_security_server_user_guide.md @@ -420,25 +420,33 @@ User management is carried out on the command line in root user permissions. To add a new user, enter the command: - adduser username +```bash +adduser username +``` To grant permissions to the user you created, add it to the corresponding system groups, for example: - adduser username xroad-security-officer - adduser username xroad-registration-officer - adduser username xroad-service-administrator - adduser username xroad-system-administrator - adduser username xroad-securityserver-observer +```bash +adduser username xroad-security-officer +adduser username xroad-registration-officer +adduser username xroad-service-administrator +adduser username xroad-system-administrator +adduser username xroad-securityserver-observer +``` To remove user permission, remove the user from the corresponding system group, for example: - deluser username xroad-security-officer +```bash +deluser username xroad-security-officer +``` Modified user permissions are applied only after a user does a new login. To remove a user, enter: - deluser username +```bash +deluser username +``` ### 2.3 LDAP user authentication @@ -1493,7 +1501,7 @@ Service providers can configure a minimum required X-Road software version for c Service providers can configure the required minimum version in the `/etc/xroad/conf.d/local.ini` configuration file using the `proxy.server-min-supported-client-version` system property. For example: -``` +```ini [proxy] server-min-supported-client-version=7.0.0 ``` @@ -1948,19 +1956,25 @@ The Security Server periodically composes signed (and timestamped) documents fro Configuration parameters are defined in INI files \[[INI](#Ref_INI)\], where each section contains the parameters for a particular Security Server component. The default message log configuration is located in the file - /etc/xroad/conf.d/addons/message-log.ini +``` +/etc/xroad/conf.d/addons/message-log.ini +``` In order to override default values, create or edit the file - /etc/xroad/conf.d/local.ini +``` +/etc/xroad/conf.d/local.ini +``` Create the `[message-log]` section (if not present) in the file. Below the start of the section, list the values of the parameters, one per line. For example, to configure the parameters `archive-path` and `archive-max-filesize`, the following lines must be added to the configuration file: - [message-log] - archive-path=/my/archive/path/ - archive-max-filesize=67108864 +```ini +[message-log] +archive-path=/my/archive/path/ +archive-max-filesize=67108864 +``` #### 11.1.1 Common Parameters @@ -2051,21 +2065,28 @@ Archive files (ZIP containers) are located in the directory specified by the con The most basic example of an archive file name when the encryption and grouping are switched off: - mlog-20210901100858-20210901100905-95b1f27097524105.zip +```bash +mlog-20210901100858-20210901100905-95b1f27097524105.zip +``` When the archive encryption switched on: - mlog-20210901101923-20210901101926-95b1f27097524105.zip.gpg +```bash +mlog-20210901101923-20210901101926-95b1f27097524105.zip.gpg +``` Switching on archive grouping by member produces the following: - mlog-INSTANCE_CLASS_CODE-20210901102251-20210901102254-95b1f27097524105.zip.gpg +```bash +mlog-INSTANCE_CLASS_CODE-20210901102251-20210901102254-95b1f27097524105.zip.gpg +``` Finally, switching to archive grouping by subsystem gives: - mlog-INSTANCE_CLASS_CODE_CONSUMERSUBSYSTEM-20210901102521-20210901102524-95b1f27097524105.zip.gpg - mlog-INSTANCE_CLASS_CODE_PROVIDERSUBSYSTEM-20210901102521-20210901102524-b1f27097524105ac.zip.gpg - +```bash +mlog-INSTANCE_CLASS_CODE_CONSUMERSUBSYSTEM-20210901102521-20210901102524-95b1f27097524105.zip.gpg +mlog-INSTANCE_CLASS_CODE_PROVIDERSUBSYSTEM-20210901102521-20210901102524-b1f27097524105ac.zip.gpg +``` #### 11.1.7 Archive Encryption and Grouping @@ -2103,17 +2124,20 @@ Warning. The archiving process fails if a required key is not present in the gpg **Configuration example** Generate a keypair for encryption with defaults and no expiration and export the public key: + ```bash gpg [--homedir ] --quick-generate-key INSTANCE/memberClass/memberCode default default never gpg [--homedir ] --export INSTANCE/memberClass/memberCode >INSTANCE-memberClass-memberCode.pgp ``` Import the public key to the gpg keyring in `archive-gpg-home-directory` and take note of the key id. + ```bash gpg --homedir --import INSTANCE-memberClass-memberCode.pgp ``` Edit the key and add ultimate trust. + ```bash gpg --homedir --edit-key ``` @@ -2121,12 +2145,14 @@ gpg --homedir --edit-key At the `gpg>` prompt, type `trust`, then type `5` for ultimate trust, then `y` to confirm, then `quit`. Add the mapping to `archive-encryption-keys-config` file (mappings can be edited without restarting X-Road services), e.g.: -```bash + +``` INSTANCE/memberClass/memberCode = 96F20FF6578A5EF90DFBA18D8C003019508B5637 ``` Add the mapping file location (`archive-encryption-keys-config`) and grouping level (`archive-grouping`) to `/etc/xroad/conf.d/local.ini` file (editing the file requires restarting X-Road services), e.g.: -```bash + +```ini [message-log] archive-encryption-enabled = true archive-grouping = member @@ -2134,6 +2160,7 @@ archive-encryption-keys-config = /etc/xroad/messagelog/archive-encryption-mappin ``` To decrypt the encrypted archives, use the following syntax: + ```bash gpg [--homedir ] --decrypt --output ``` @@ -2159,8 +2186,10 @@ The archive file has been successfully transferred when the archiving server ret Override the configuration parameter archive-transfer-command (create or edit the file `etc/xroad/conf.d/local.ini`) to set up a transferring script. For example: - [message-log] - archive-transfer-command=/usr/share/xroad/scripts/archive-http-transporter.sh -r http://my-archiving-server/cgi-bin/upload +```ini +[message-log] +archive-transfer-command=/usr/share/xroad/scripts/archive-http-transporter.sh -r http://my-archiving-server/cgi-bin/upload +``` The message log package contains the CGI script `/usr/share/doc/xroad-addon-messagelog/archive-server/demo-upload.pl` for a demo archiving server for the purpose of testing or development. @@ -2171,35 +2200,45 @@ The message log database can be located outside of the Security Server. The foll 1. Create a database user at remote database host: - postgres@db_host:~$ createuser -P messagelog_user - Enter password for new role: - Enter it again: + ```bash + postgres@db_host:~$ createuser -P messagelog_user + Enter password for new role: + Enter it again: + ``` 2. Create a database owned by the message log user at remote database host: - postgres@db_host:~$ createdb messagelog_dbname -O messagelog_user -E UTF-8 + ```bash + postgres@db_host:~$ createdb messagelog_dbname -O messagelog_user -E UTF-8 + ``` 3. Verify connectivity from Security Server to the remote database: - user@security_server:~$ psql -h db_host -U messagelog_user messagelog_dbname - Password for user messagelog_user: - psql (9.3.9) - SSL connection (cipher: DHE-RSA-AES256-GCM-SHA384, bits: 256) - Type "help" for help. - messagelog_dbname=> + ```bash + user@security_server:~$ psql -h db_host -U messagelog_user messagelog_dbname + Password for user messagelog_user: + psql (9.3.9) + SSL connection (cipher: DHE-RSA-AES256-GCM-SHA384, bits: 256) + Type "help" for help. + messagelog_dbname=> + ``` 4. Stop xroad-proxy service for reconfiguration: - root@security_server:~# service xroad-proxy stop + ```bash + root@security_server:~# service xroad-proxy stop + ``` 5. Configure the database connection parameters to achieve encrypted connections, in `/etc/xroad/db.properties`: - messagelog.hibernate.jdbc.use_streams_for_binary = true - messagelog.hibernate.dialect = ee.ria.xroad.common.db.CustomPostgreSQLDialect - messagelog.hibernate.connection.driver_class = org.postgresql.Driver - messagelog.hibernate.connection.url = jdbc:postgresql://db_host:5432/messagelog_dbname?ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory - messagelog.hibernate.connection.username = messagelog_user - messagelog.hibernate.connection.password = messagelog_password + ```properties + messagelog.hibernate.jdbc.use_streams_for_binary = true + messagelog.hibernate.dialect = ee.ria.xroad.common.db.CustomPostgreSQLDialect + messagelog.hibernate.connection.driver_class = org.postgresql.Driver + messagelog.hibernate.connection.url = jdbc:postgresql://db_host:5432/messagelog_dbname?ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory + messagelog.hibernate.connection.username = messagelog_user + messagelog.hibernate.connection.password = messagelog_password + ``` 6. Populate database schema by reinstalling messagelog addon package and start xroad-proxy @@ -2247,31 +2286,42 @@ For example: By default, audit log is located in the file - /var/log/xroad/audit.log +``` +/var/log/xroad/audit.log +``` ### 12.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 +``` +/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 +``` +/var/log/xroad/audit.log +``` The default behavior can be changed by editing the *rsyslog* configuration file - /etc/rsyslog.d/40-xroad.conf +``` +/etc/rsyslog.d/40-xroad.conf +``` Restart the *rsyslog* service to apply the changes made to the configuration file - service rsyslog restart +```bash +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-proxy - +``` +/etc/logrotate.d/xroad-proxy +``` ### 12.2 Archiving the Audit Log @@ -2349,20 +2399,26 @@ To restore configuration from the command line, the following data must be avail To find the X-Road ID of the Security Server, the following command can be used: - cat /etc/xroad/gpghome/openpgp-revocs.d/.rev | grep uid +```bash +cat /etc/xroad/gpghome/openpgp-revocs.d/.rev | grep uid +``` It is expected that the restore command is run by the xroad user. In order to restore configuration, the following command should be used: - /usr/share/xroad/scripts/restore_xroad_proxy_configuration.sh \ - -s -f [-P -N] +```bash +/usr/share/xroad/scripts/restore_xroad_proxy_configuration.sh \ +-s -f [-P -N] +``` For example (all on one line): - /usr/share/xroad/scripts/restore_xroad_proxy_configuration.sh \ - -s AA/GOV/TS1OWNER/TS1 \ - –f /var/lib/xroad/backup/conf_backup_20140703-110438.gpg +```bash +/usr/share/xroad/scripts/restore_xroad_proxy_configuration.sh \ +-s AA/GOV/TS1OWNER/TS1 \ +–f /var/lib/xroad/backup/conf_backup_20140703-110438.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 @@ -2371,13 +2427,17 @@ skip checking archive signature. If a backup is restored on a new uninitialized (the initial configuration hasn't been completed) Security Server, the Security Server's gpg key must be manually created before restoring the backup: - /usr/share/xroad/scripts/generate_gpg_keypair.sh /etc/xroad/gpghome +```bash +/usr/share/xroad/scripts/generate_gpg_keypair.sh /etc/xroad/gpghome +``` If it is absolutely necessary to restore the system from a backup made on a different Security Server, the forced mode of the restore command can be used with the –F option together with unencrypted backup archive flags. For example (all on one line): - /usr/share/xroad/scripts/restore_xroad_proxy_configuration.sh \ - -F -P –f /var/lib/xroad/backup/conf_backup_20140703-110438.tar +```bash +/usr/share/xroad/scripts/restore_xroad_proxy_configuration.sh \ +-F -P –f /var/lib/xroad/backup/conf_backup_20140703-110438.tar +``` In case backup archives were encrypted they have to be first unencrypted in external safe environment and then securely transported to Security Server filesystem. @@ -2420,7 +2480,9 @@ Additional keys for backup encryption should be generated and stored outside Sec 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 +```bash +gpg --output backupadmin.publickey --armor --export backupadmin@example.org +``` Resulting file `backupadmin.publickey` should be moved to Security Server and imported to backup gpg keyring. Administrator should make sure that the key has not been changed during transfer, for example by validating the key fingerprint. @@ -2430,17 +2492,20 @@ them can be used to decrypt backups and thus mount attacks on the Security Serve **Configuration example** Generate a keypair for encryption with defaults and no expiration and export the public key: + ```bash gpg [--homedir ] --quick-generate-key backupadmin@example.org default default never gpg [--homedir ] --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. + ```bash gpg --homedir /etc/xroad/gpghome --import backupadmin@example.org.pgp ``` Edit the key and add ultimate trust. + ```bash gpg --homedir /etc/xroad/gpghome/ --edit-key ``` @@ -2448,6 +2513,7 @@ gpg --homedir /etc/xroad/gpghome/ --edit-key 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.: + ```bash [proxy] backup-encryption-enabled = true @@ -2475,7 +2541,9 @@ decrypted and verified in these separate environments. To export Security Servers backup encryption public key use the following command: - gpg --homedir /etc/xroad/gpghome --armor --output server-public-key.gpg --export /// +```bash +gpg --homedir /etc/xroad/gpghome --armor --output server-public-key.gpg --export /// +``` where `///` is the Security Server id, for example, `AA/GOV/TS1OWNER/TS1`. @@ -2622,20 +2690,28 @@ All overrides to the default configuration values must be made in the file `/etc If, for any reason, operational data should not be collected and forwarded to the operational monitoring daemon, the parameter size can be set to 0: - [op-monitor-buffer] - size = 0 +```ini +[op-monitor-buffer] +size = 0 +``` After the configuration change, the xroad-proxy service must be restarted: - service xroad-proxy restart +```bash +service xroad-proxy restart +``` In addition, the operational monitoring daemon should be stopped: - service xroad-opmonitor stop +```bash +service xroad-opmonitor stop +``` For the service to stay stopped after reboot the following command should be run: - echo manual > /etc/init/xroad-opmonitor.override +```bash +echo manual > /etc/init/xroad-opmonitor.override +``` ### 15.2 Operational Monitoring Daemon @@ -2678,8 +2754,10 @@ For configuring the endpoint of the operational monitoring daemon, the following If any of these values are changed, both the proxy and the operational monitoring daemon services must be restarted: - service xroad-proxy restart - service xroad-opmonitor restart +```bash +service xroad-proxy restart +service xroad-opmonitor restart +``` #### 15.2.4 Installing an External Operational Monitoring Daemon @@ -2694,10 +2772,11 @@ For running a separate operational monitoring daemon, the xroad-opmonitor packag As a result of installation, the following services will be running: - xroad-confclient - xroad-signer - xroad-opmonitor - +```bash +xroad-confclient +xroad-signer +xroad-opmonitor +``` #### 15.2.5 Configuring an External Operational Monitoring Daemon and the Corresponding Security Server @@ -2713,31 +2792,43 @@ The internal TLS certificate of the Security Server is used for authenticating t In the configuration of the external daemon, the corresponding path must be set in `/etc/xroad/conf.d/local.ini`: - [op-monitor] - client-tls-certificate = +```ini +[op-monitor] +client-tls-certificate = +``` Next, a TLS key and the corresponding certificate must be generated on the host of the external monitoring daemon as well, using the command - generate-opmonitor-certificate +```bash +generate-opmonitor-certificate +``` The script will prompt you for standard fields for input to TLS certificates and its output (key files and the certificate) will be generated to the directory `/etc/xroad/ssl`. The generated certificate, in the file `opmonitor.crt`, must be copied to the corresponding Security Server. The system user `xroad` must have permissions to read this file. Its path at the Security Server must be written to the configuration (note the name of the section, although it is the proxy service that will read the configuration): - [op-monitor] - tls-certificate = +```ini +[op-monitor] +tls-certificate = +``` For the external operational daemon to be used, the proxy service at the Security Server must be restarted: - service xroad-proxy restart +```bash +service xroad-proxy restart +``` In addition, on the host running the corresponding Security Server, the operational monitoring daemon must be stopped: - service xroad-opmonitor stop +```bash +service xroad-opmonitor stop +``` For the service to stay stopped after reboot the following command should be run: - echo manual > /etc/init/xroad-opmonitor.override +```bash +echo manual > /etc/init/xroad-opmonitor.override +``` The configuration anchor (renamed as `configuration-anchor.xml`) file must be manually copied into the directory `/etc/xroad` of the external monitoring daemon in order for configuration client to be able to download the global configuration (by default configuration download interval is 60 seconds). The system user xroad must have permissions to read this file. @@ -2802,11 +2893,15 @@ System services are managed through the *systemd* facility. **To start a service**, issue the following command as a `root` user: - service start +```bash +service start +``` **To stop a service**, enter: - service stop +```bash +service stop +``` Services use the [default unit start rate limits](https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html#DefaultStartLimitIntervalSec=). An exception to this is `xroad-proxy-ui-api`, which uses a longer start rate limit ([5 starts / 40 seconds](https://github.com/nordic-institute/X-Road/blob/master/src/packages/src/xroad/ubuntu/generic/xroad-proxy-ui-api.service#L5-6)) @@ -3000,7 +3095,6 @@ revocation was successful and `HTTP 404` if key did not exist. ```bash curl -X DELETE -u : https://localhost:4000/api/v1/api-keys/60 -k - ``` #### 19.1.5 API key caching @@ -3049,6 +3143,7 @@ can be used to find the log messages related to a specific API call. The correlation ID header is returned for all requests, both successful and failed ones. For example, these log messages are related to an API call with correlation ID `3d5f193102435242`: + ``` 2019-08-26 13:16:23,611 [https-jsse-nio-4000-exec-10] correlation-id:[3d5f193102435242] DEBUG o.s.s.w.c.HttpSessionSecurityContextRepository - The HttpSession is currently null, and the HttpSessionSecurityContextRepository is prohibited from creating an HttpSession (because the allowSessionCreation property is false) - SecurityContext thus not stored for next request 2019-08-26 13:16:23,611 [https-jsse-nio-4000-exec-10] correlation-id:[3d5f193102435242] WARN o.s.w.s.m.m.a.ExceptionHandlerExceptionResolver - Resolved [org.niis.xroad.restapi.exceptions.ConflictException: local group with code koodi6 already added] @@ -3377,7 +3472,7 @@ First step to pass additional configurations is to create `db_libpq.env` file in Example of file contents: -```bash +``` export PGSSLMODE="verify-full" export PGSSLCERT="/etc/xroad/ssl/internal.crt" export PGSSLKEY="/etc/xroad/ssl/internal.key" diff --git a/doc/Manuals/ug-syspar_x-road_v6_system_parameters.md b/doc/Manuals/ug-syspar_x-road_v6_system_parameters.md index 334c40e19a..b44c744f68 100644 --- a/doc/Manuals/ug-syspar_x-road_v6_system_parameters.md +++ b/doc/Manuals/ug-syspar_x-road_v6_system_parameters.md @@ -191,26 +191,34 @@ The configuration files are INI files \[[INI](#Ref_INI)\], where each section co In order to override the default values of system parameters, create or edit the file - /etc/xroad/conf.d/local.ini +```bash +/etc/xroad/conf.d/local.ini +``` Each system parameter affects a specific server component. To change the value of a system parameter, a section for the affected component must be created in the INI file. The name-value pairs of the system parameters for that component are written under the section, one pair per line. The following format is used for the sections: - [ServerComponent] - SystemParameterName1=Value1 - SystemParameterName2=Value2 +```ini +[ServerComponent] +SystemParameterName1=Value1 +SystemParameterName2=Value2 +``` For example, to configure the parameter *client-http-port* for the *proxy* component, the following lines must be added to the configuration file: - [proxy] - client-http-port=1234 +```ini +[proxy] +client-http-port=1234 +``` Multiple parameters can be configured under the same section: - [proxy] - client-http-port=1234 - server-listen-port=20000 +```ini +[proxy] +client-http-port=1234 +server-listen-port=20000 +``` **NB! Changing the parameter values in the configuration files requires restarting of the server.** @@ -220,19 +228,27 @@ Multiple parameters can be configured under the same section: The central server database can be accessed with the psql utility using the following command (password is defined in `/etc/xroad/db.properties`): - psql -U centerui -h localhost centerui_production +```bash +psql -U centerui -h localhost centerui_production +``` The default value of a system parameter can be overridden by adding the parameter name and value to the *system_parameters* table: - INSERT INTO system_parameters (key, value, created_at, updated_at) VALUES ('parameter_name', 'parameter_value', (now() at time zone 'utc'), (now() at time zone 'utc')); +```sql +INSERT INTO system_parameters (key, value, created_at, updated_at) VALUES ('parameter_name', 'parameter_value', (now() at time zone 'utc'), (now() at time zone 'utc')); +``` To edit the value of a system parameter already inserted into the *system_parameters* table: - UPDATE system_parameters SET value = '*parameter_value*', updated_at = (now() at time zone 'utc') WHERE key = 'parameter_name'; +```sql +UPDATE system_parameters SET value = '*parameter_value*', updated_at = (now() at time zone 'utc') WHERE key = 'parameter_name'; +``` To restore the default value of a system parameter, delete the parameter from the *system_parameters* table: - DELETE FROM system_parameters WHERE key = 'parameter_name'; +```sql +DELETE FROM system_parameters WHERE key = 'parameter_name'; +``` **NB! Modifying or deleting system parameters other than the ones listed in section** [System Parameters in the Database](#system-parameters-in-the-database) **will cause the system to crash.** diff --git a/doc/Sidecar/security_server_sidecar_user_guide.md b/doc/Sidecar/security_server_sidecar_user_guide.md index 457eaed195..1041e7c4d8 100644 --- a/doc/Sidecar/security_server_sidecar_user_guide.md +++ b/doc/Sidecar/security_server_sidecar_user_guide.md @@ -356,7 +356,9 @@ The configuration files are INI files [INI], where each section contains paramet In order to override the default values of system parameters, create or edit the file - /etc/xroad/conf.d/local.ini +``` +/etc/xroad/conf.d/local.ini +``` See [UG-SYSPAR](#Ref_UG-SYSPAR) for configuration details.