7.4.1

ria-ee · Mar 1, 2024 · f95d05d · f95d05d
1 parent 2ac532d
commit f95d05d
Show file tree

Hide file tree

Showing 24 changed files with 11,600 additions and 39 deletions.
diff --git a/md/Monitoring-architecture.md b/md/Monitoring-architecture.md
@@ -1,4 +1,3 @@
-<<<<<<< HEAD
 # X-Road: Environmental Monitoring Architecture
 
 Version: 1.10  
@@ -63,11 +62,11 @@ See X-Road terms and abbreviations documentation \[[TA-TERMS](#Ref_TERMS)\].
 
 | Document ID||
 | ------------- |-------------|
-| PR-GCONF      | [X-Road: Protocol for Downloading Configuration](pr-gconf_x-road_protocol_for_downloading_configuration.md) |
-| UC-GCONF      | [X-Road: Use Case Model for Global Configuration Distribution](uc-gconf_x-road_use_case_model_for_global_configuration_distribution_1.4_Y-883-8.md)|
-| PR-MESS | [X-Road: Message Protocol v4.0](pr-mess_x-road_message_protocol.md)      |
-| PR-TARGETSS | [Security Server targeting extension for the X-Road message protocol](pr-targetss_security_server_targeting_extension_for_the_x-road_protocol.md) |
-| <a id="Ref_TERMS" class="anchor"></a> TA-TERMS | [X-Road Terms and Abbreviations](terms_x-road_docs.md)| 
+| PR-GCONF      | [X-Road: Protocol for Downloading Configuration](../Protocols/pr-gconf_x-road_protocol_for_downloading_configuration.md) |
+| UC-GCONF      | [X-Road: Use Case Model for Global Configuration Distribution](../UseCases/uc-gconf_x-road_use_case_model_for_global_configuration_distribution_1.4_Y-883-8.md)|
+| PR-MESS | [X-Road: Message Protocol v4.0](../Protocols/pr-mess_x-road_message_protocol.md)      |
+| PR-TARGETSS | [Security Server targeting extension for the X-Road message protocol](../Protocols/SecurityServerExtension/pr-targetss_security_server_targeting_extension_for_the_x-road_protocol.md) |
+| <a id="Ref_TERMS" class="anchor"></a> TA-TERMS | [X-Road Terms and Abbreviations](../terms_x-road_docs.md)| 
 
 ## 2 Components
 
@@ -414,5 +413,3 @@ JMX API, in case port and network access is enabled, will provide monitoring dat
 Request for monitor data can be set for limiting optional parts by changing env-monitor.limit-remote-data-set parameter. By limiting data set environmental monitoring will return only proxyVersion, OperatingSystem and Certificate information. 
 
 If request parameters are used and flag is set for limiting, response will include proxyVersion, name and OperatingSystem and/or Certificate information if they are in parameter list and nothing else.
-=======
->>>>>>> main
diff --git a/md/Monitoring-messages.md b/md/Monitoring-messages.md
@@ -0,0 +1,233 @@
+# X-Road: Environmental Monitoring Messages
+
+Version: 1.5  
+Doc. ID: PR-ENVMONMES
+
+| Date       | Version     | Description                                                | Author          |
+|------------|-------------|------------------------------------------------------------|-----------------|
+| 15.12.2015 | 1.0         | Initial version                                            | Ilkka Seppälä   |
+| 04.01.2017 | 1.1         | Fix documentation links                                    | Ilkka Seppälä   |
+| 20.01.2017 | 1.2         | Added license text, table of contents and version history  | Sami Kallio     |
+| 23.02.2017 | 1.3         | Added reference to security server targeting extension     | Olli Lindgren   |
+| 24.08.2017 | 1.4         | Added outputSpec parameter to getSecurityServerMetrics     | Tomi Tolvanen   |
+| 06.03.2018 | 1.5         | Added terms and abbreviations references, numbering and Introduction chapter structure | Tatu Repo |
+
+## Table of Contents
+
+<!-- toc -->
+
+- [License](#license)
+- [1 Introduction](#1-introduction)
+  * [1.1 Terms and abbreviations](#11-terms-and-abbreviations)
+  * [1.2 References](#12-references)
+- [2 Fetching security server metrics](#2-fetching-security-server-metrics)
+  * [2.1 Request](#21-request)
+  * [2.2 Response](#22-response)
+  * [2.3 Response Schema](#23-response-schema)
+
+<!-- tocstop -->
+
+## License
+
+This document is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/.
+
+## 1 Introduction
+
+This document describes the request and response messages for environmental monitoring. 
+
+### 1.1 Terms and abbreviations
+
+See X-Road terms and abbreviations documentation \[[TA-TERMS](#Ref_TERMS)\].
+
+### 1.2 References
+
+| Document ID||
+| ------------- |-------------|
+| <a name="Ref_PR-TARGETSS"></a>\[PR-TARGETSS\] | [Security server targeting extension for the X-Road message protocol](../Protocols/SecurityServerExtension/pr-targetss_security_server_targeting_extension_for_the_x-road_protocol.md)  |
+| <a name="Ref_TERMS"></a>\[TA-TERMS\] | [X-Road Terms and Abbreviations](../terms_x-road_docs.md)
+
+
+## 2 Fetching security server metrics
+
+### 2.1 Request
+
+Fetching security server metrics uses the X-Road protocol. The `getSecurityServerMetrics` request requires a `securityServer` header element as specified by the security server targeting extension for the X-Road message protocol \[[PR-TARGETSS](#Ref_PR-TARGETSS)\] so that the request can be routed to a specific security server.
+
+`Body` element must contain the `getSecurityServerMetrics` element.
+
+An optional `outputSpec` child element can be used to request a subset of the metrics. The `outputSpec` consists of zero or more `outputField` elements referring to the `name` element of a metric in the `metricSet` named _systemMetrics_. Empty or missing `outputSpec` requests all available metrics. 
+
+```xml
+<SOAP-ENV:Envelope
+	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
+	xmlns:id="http://x-road.eu/xsd/identifiers"
+	xmlns:xrd="http://x-road.eu/xsd/xroad.xsd"
+	xmlns:m="http://x-road.eu/xsd/monitoring">
+
+    <SOAP-ENV:Header>
+
+        <xrd:client id:objectType="MEMBER">
+            <id:xRoadInstance>fdev</id:xRoadInstance>
+            <id:memberClass>GOV</id:memberClass>
+            <id:memberCode>1710128-9</id:memberCode>
+        </xrd:client>
+        <xrd:service id:objectType="SERVICE">
+            <id:xRoadInstance>fdev</id:xRoadInstance>
+            <id:memberClass>GOV</id:memberClass>
+            <id:memberCode>1710128-9</id:memberCode>
+            <id:serviceCode>getSecurityServerMetrics</id:serviceCode>
+        </xrd:service>
+        <xrd:securityServer id:objectType="SERVER">
+            <id:xRoadInstance>fdev</id:xRoadInstance>
+            <id:memberClass>GOV</id:memberClass>
+            <id:memberCode>1710128-9</id:memberCode>
+            <id:serverCode>fdev-ss1.i.palveluvayla.com</id:serverCode>
+        </xrd:securityServer>
+
+        <xrd:id>ID11234</xrd:id>
+        <xrd:protocolVersion>4.0</xrd:protocolVersion>
+
+    </SOAP-ENV:Header>
+
+    <SOAP-ENV:Body>
+        <m:getSecurityServerMetrics>
+            <m:outputSpec>
+                <m:outputField>OperatingSystem</m:outputField>
+                <m:outputField>TotalPhysicalMemory</m:outputField>
+            </m:outputSpec>
+        </m:getSecurityServerMetrics>
+    </SOAP-ENV:Body>
+
+</SOAP-ENV:Envelope>
+```
+
+### 2.2 Response
+
+The response `Body` contains one `getSecurityServerMetricsResponse` element which contains one `metricSet` as direct child. The name of the top level set is the security server identifier. The set contains a _proxyVersion_ `stringMetric` and a _systemMetrics_ `metricSet`. The _systemMetrics_ set contains the requested metrics.
+
+```xml
+<SOAP-ENV:Envelope
+    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
+    xmlns:id="http://x-road.eu/xsd/identifiers"
+    xmlns:m="http://x-road.eu/xsd/monitoring"
+    xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
+
+   <SOAP-ENV:Header>
+      <xrd:client id:objectType="MEMBER">
+         <id:xRoadInstance>fdev</id:xRoadInstance>
+         <id:memberClass>GOV</id:memberClass>
+         <id:memberCode>1710128-9</id:memberCode>
+      </xrd:client>
+      <xrd:service id:objectType="SERVICE">
+         <id:xRoadInstance>fdev</id:xRoadInstance>
+         <id:memberClass>GOV</id:memberClass>
+         <id:memberCode>1710128-9</id:memberCode>
+         <id:serviceCode>getSecurityServerMetrics</id:serviceCode>
+      </xrd:service>
+      <xrd:securityServer id:objectType="SERVER">
+         <id:xRoadInstance>fdev</id:xRoadInstance>
+         <id:memberClass>GOV</id:memberClass>
+         <id:memberCode>1710128-9</id:memberCode>
+         <id:serverCode>fdev-ss1.i.palveluvayla.com</id:serverCode>
+      </xrd:securityServer>
+      <xrd:id>ID11234</xrd:id>
+      <xrd:protocolVersion>4.0</xrd:protocolVersion>
+      <xrd:requestHash algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">mChpBRMvFlBBSNKeOxAJQBw4r6XdHZFuH8BOzhjsxjjOdaqXXyPXwnDEdq/NkYfEqbLUTi1h/OHEnX9F5YQ5kQ==</xrd:requestHash>
+   </SOAP-ENV:Header>
+   <SOAP-ENV:Body>
+      <m:getSecurityServerMetricsResponse>
+         <m:metricSet>
+            <m:name>SERVER:fdev/GOV/1710128-9/fdev-ss1.i.palveluvayla.com</m:name>
+            <m:stringMetric>
+               <m:name>proxyVersion</m:name>
+               <m:value>6.7.7-1.20151201075839gitb72b28e</m:value>
+            </m:stringMetric>
+            <m:metricSet>
+               <m:name>systemMetrics</m:name>
+               <m:stringMetric>
+                  <m:name>OperatingSystem</m:name>
+                  <m:value>Linux version 3.13.0-70-generic</m:value>
+               </m:stringMetric>
+               <m:numericMetric>
+                  <m:name>TotalPhysicalMemory</m:name>
+                  <m:value>2097684480</m:value>
+               </m:numericMetric>
+            </m:metricSet>
+         </m:metricSet>
+      </m:getSecurityServerMetricsResponse>
+   </SOAP-ENV:Body>
+</SOAP-ENV:Envelope>
+```
+
+### 2.3 Response Schema
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<schema xmlns="http://www.w3.org/2001/XMLSchema"
+        xmlns:tns="http://x-road.eu/xsd/monitoring" xmlns:xs="http://www.w3.org/2001/XMLSchema"
+        targetNamespace="http://x-road.eu/xsd/monitoring"
+        elementFormDefault="qualified">
+    <xs:complexType name="MetricType" abstract="true">
+        <xs:sequence>
+            <xs:element name="name" type="xs:string"/>
+        </xs:sequence>
+    </xs:complexType>
+    <xs:complexType name="NumericMetricType">
+        <xs:complexContent>
+            <xs:extension base="tns:MetricType">
+                <xs:sequence>
+                    <xs:element name="value" type="xs:decimal"/>
+                </xs:sequence>
+            </xs:extension>
+        </xs:complexContent>
+    </xs:complexType>
+    <xs:complexType name="StringMetricType">
+        <xs:complexContent>
+            <xs:extension base="tns:MetricType">
+                <xs:sequence>
+                    <xs:element name="value" type="xs:string"/>
+                </xs:sequence>
+            </xs:extension>
+        </xs:complexContent>
+    </xs:complexType>
+    <xs:complexType name="HistogramMetricType">
+        <xs:complexContent>
+            <xs:extension base="tns:MetricType">
+                <xs:sequence>
+                    <xs:element name="updated" type="xs:dateTime"/>
+                    <xs:element name="min" type="xs:decimal"/>
+                    <xs:element name="max" type="xs:decimal"/>
+                    <xs:element name="mean" type="xs:decimal"/>
+                    <xs:element name="median" type="xs:decimal"/>
+                    <xs:element name="stddev" type="xs:decimal"/>
+                </xs:sequence>
+            </xs:extension>
+        </xs:complexContent>
+    </xs:complexType>
+    <xs:complexType name="MetricSetType">
+        <xs:complexContent>
+            <xs:extension base="tns:MetricType">
+                <xs:sequence>
+                    <xs:choice maxOccurs="unbounded">
+                        <xs:element name="metricSet" type="tns:MetricSetType"/>
+                        <xs:element name="numericMetric" type="tns:NumericMetricType"/>
+                        <xs:element name="stringMetric" type="tns:StringMetricType"/>
+                        <xs:element name="histogramMetric" type="tns:HistogramMetricType"/>
+                    </xs:choice>
+                </xs:sequence>
+            </xs:extension>
+        </xs:complexContent>
+    </xs:complexType>
+    <xs:element name="getSecurityServerMetricsResponse">
+        <xs:complexType>
+            <xs:sequence>
+                <xs:element name="metricSet" type="tns:MetricSetType"/>
+            </xs:sequence>
+        </xs:complexType>
+    </xs:element>
+    <xs:complexType name="getSecurityServerMetricsType">
+        <xs:sequence/>
+    </xs:complexType>
+    <xs:element name="getSecurityServerMetrics" type="tns:getSecurityServerMetricsType"/>
+</schema>
+```
diff --git a/md/README.md b/md/README.md
@@ -0,0 +1,59 @@
+# Security server cluster setup
+
+This ansible playbook configures a master (1) - replica (n) security server cluster. In addition, setting up a load balancer (out of scope) is needed.
+
+The playbook has been tested in AWS EC2 using stock RHEL 7, Ubuntu 20.04 and Ubuntu 22.04 AMIs running default X-Road security server installation. Other environments might require modifications to the playbook.
+
+## Prerequisites
+
+* One security server that acts as primary
+* One or more replica security servers.
+* The replica server(s) have network access to primary ssh port (tcp/22)
+* The replica server(s) have network access to primary serverconf database (default: tcp/5433)
+* X-Road security server packages have been installed on each server
+    * It is not necessary to configure the servers
+    * The primary server configuration is preserved, so it is possible to create a cluster using an existing security server that is already attached to an X-Road instance.
+* The control host executing this playbook has ssh access with sudo privileges on all the hosts.
+    * Ansible version >2.1 required
+    * The control host can be one of the cluster servers (e.g. the primary node), but a separate control host is recommended.
+* Decide names for the cluster members and configure the nodes in the ansible inventory. 
+    * See hosts/cluster-example.txt for an example (nodename parameter)
+    * Node names are related to certificate DN's, see "Set up SSL keys" for specifics
+* Change the serverconf_password in group_vars/all and preferably encrypt the file using ansible vault. 
+    * The serverconf_password is used to authenticate the local connections to the serverconf database. The default is 'serverconf'.
+
+All the servers in a cluster should have the same operating system (Ubuntu 20.04, Ubuntu 22.04 or RHEL 7). The setup also assumes that the servers are in the same subnet. If that is not the case, one needs to modify primary's pg_hba.nconf so that it accepts replication configurations from the correct network(s).
+
+## Set up SSL keys certificates for PostgreSQL replication connections
+
+Create a CA certificate and store it in PEM format as ca.crt in the "ca" folder. Create TLS key and certificate (PEM) signed by the CA for each node and store those as ca/"nodename"/server.key and ca/"nodename"/server.crt. The server keys must not have a passphrase, but one can and should use ansible-vault to protect
+the keys.
+
+Note that the common name (CN) part of the certificate subject's DN must be the *nodename* defined in the host inventory file.
+
+The ca directory contains two scripts that can be used to generate the keys and certificates.
+* init.sh creates a CA key and self-signed certificate.
+* add-node.sh creates a key and a certificate signed by the CA.
+
+## Running the playbook
+
+Remember to back up the servers before proceeding.
+
+```
+ansible-playbook --ask-vault-pass -i hosts/example.txt xroad_ss_cluster.yml
+```
+If testing the setup in a lxd container:
+```
+ansible-playbook --ask-vault-pass -c lxd --become-method=su -i hosts/example.txt xroad_ss_cluster.yml
+```
+
+The playbook does the following operations
+* sets up a separate serverconf database on the primary hosts and configures it
+  for streaming replication
+* sets up a separate serverconf hot-standby database on the replica hosts
+* configures the security servers to use the serverconf database
+* creates ssh keys for the xroad user on the replica hosts
+* creates an user account (xroad-slave) on the primary host and allows ssh access from replicas using public key authentication
+* installs upstart/systemd tasks on the replicas that replicates /etc/xroad from the primary to replicas (using rsync over ssh)
+* installs /etc/xroad/conf.d/node.ini file and sets replica or primary mode on each node
+* restarts xroad securityserver