Skip to content

Latest commit

 

History

History
352 lines (258 loc) · 25.3 KB

harmony-ap_installation_guide.md

File metadata and controls

352 lines (258 loc) · 25.3 KB

Harmony eDelivery Access - Access Point Installation Guide

Version: 1.18
Doc. ID: IG-AP

Version history

Date Version Description Author
15.11.2021 1.0 Initial version
07.01.2022 1.1 Add reference to the Static Discovery Configuration Guide [UG-SDCG] Petteri Kivimäki
08.01.2022 1.2 Add party name to section 2.5 and TLS truststore to section 2.10 Petteri Kivimäki
04.02.2022 1.3 Add upgrade instructions. Add section about log files Petteri Kivimäki
23.04.2022 1.4 Add port number to the Access Point Installation section. Update package repository URL Petteri Kivimäki
28.04.2022 1.5 Minor changes Petteri Kivimäki
22.05.2023 1.6 Update references Petteri Kivimäki
29.05.2023 1.7 Update installation and version upgrade instructions Jarkko Hyöty
01.06.2023 1.8 Add more information about allowed characters in certificates Petteri Kivimäki
22.06.2023 1.9 Add a note about the default password expiration policy Petteri Kivimäki
17.08.2023 1.10 Update system requirements Jarkko Hyöty
29.09.2023 1.11 Use PKCS12 keystores by default. Update certificate DN configuration. Jarkko Hyöty
15.01.2024 1.12 Update links to external documents Petteri Kivimäki
28.02.2024 1.13 Update WS Plugin interface path Petteri Kivimäki
01.03.2024 1.14 Update supported operating systems Diego Martin
01.06.2024 1.15 Update links to external documents Petteri Kivimäki
13.12.2024 1.16 Add reference to the Logging Guide [UG-AP-L] Diego Martin
13.01.2025 1.17 Update links to external documents Diego Martin
17.01.2025 1.18 Support for Ubuntu 24.04 Diego Martin

License

This document is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/

Table of Contents

1 Introduction

Harmony eDelivery Access Access Point is an AS4 Access Point for joining eDelivery policy domains. The Access Point is based on the Domibus open source project by the European Commission.

1.1 Target Audience

This guide describes installation and post-installation procedures for Harmony eDelivery Access Access Point.

The intended audience of this Installation Guide are Access Point system administrators responsible for installing and using the Access Point software.

The document is intended for readers with a moderate knowledge of Linux server management, computer networks, and the eDelivery working principles.

1.2 Terms and abbreviations

See eDelivery documentation [TERMS].

1.3 References

  1. [TERMS] eDelivery Documentation, https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/eDelivery
  2. [DOMIBUS_ADMIN_GUIDE] Access Point Administration Guide - Domibus 5.1.6, https://docs.edelivery.tech.ec.europa.eu/domibus/5.1.6/#adminguide
  3. [WS_PLUGIN] Access Point Interface Control Document - WS Plugin, https://docs.edelivery.tech.ec.europa.eu/domibus/5.1.6/#wsplugin_interface
  4. [PLUGIN_COOKBOOK] Domibus Plugin Cookbook, https://docs.edelivery.tech.ec.europa.eu/domibus/5.1.6/#plugin_cookbook
  5. [UG-DDCG] Harmony eDelivery Access - Dynamic Discovery Configuration Guide. Document ID: UG-DDCG
  6. [UG-SDCG] Harmony eDelivery Access - Static Discovery Configuration Guide. Document ID: UG-SDCG
  7. [RFC5280] RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, https://www.rfc-editor.org/rfc/rfc5280
  8. [PS] PrintableString, https://en.wikipedia.org/wiki/PrintableString
  9. [UG-AP-L] Harmony eDelivery Access - Access Point Logging Guide. Document ID: UG-AP-L

2 Installation

2.1 Prerequisites to Installation

The Access Point is officially supported on the following operating systems (x86-64, arm64):

  • Ubuntu Server 20.04 Long-Term Support (LTS).
  • Ubuntu Server 22.04 Long-Term Support (LTS).
  • Ubuntu Server 24.04 Long-Term Support (LTS).

The software can be installed both on physical and virtualized hardware.

Note: If MySQL database engine is already installed then installation requires that root user can access database using UNIX socket peer authentication without password.

Note: Access Point and SMP must not be installed on the same host because they both use port 8443.

2.2 Network Diagram

The network diagram below provides an example of an Access Point setup when dynamic discovery is used.

network diagram

The table below lists the required connections between different components.

Connection Type Source Target Target Ports Protocol Note
Out Access Point Data Exchange Partner Access Point 443, 8443, other tcp
Out Access Point SMP 443, 8443, other tcp
Out Access Point Backend (push) 80, 443, other tcp Target in the internal network
In Data Exchange Partner Access Point Access Point 8443* tcp URL path: /services/msh
In Backend (submit, pull) Access Point 8443* tcp Source in the internal network

URL path: /services/wsplugin
In Admin Access Point 8443* tcp Source in the internal network

URL path: /

* The port number for inbound connections is configurable and the value can be set during the Access Point installation process. Port 8443 is used by default.

It is strongly recommended to protect the Access Point from unwanted access using a firewall (hardware or software based). The firewall can be applied to both incoming and outgoing connections depending on the security requirements of the environment where the Access Point is deployed. It is recommended to allow incoming traffic to specific ports only from explicitly defined sources using IP filtering. Special attention should be paid with the firewall configuration since incorrect configuration may leave the Access Point vulnerable to exploits and attacks.

In addition, it's strongly recommended to use URL path filtering for the Access Point since the admin UI, backend interface and AS4 interface all run on the same port. By default, the port number is 8443, but it is configurable.

Port URL Path Description
8443 / Admin UI for managing the Access Point.
8443 /services/wsplugin Webservice interface (submit requests, pull messages) between the Access Point and backend.
8443 /services/msh AS4 interface between Access Points.

2.3 Requirements for the Access Point

Minimum recommended hardware parameters:

  • the server’s hardware (motherboard, CPU, network interface cards, storage system) must be supported by Ubuntu in general;
  • a 64-bit dual-core Intel, AMD or compatible CPU; AES instruction set support is highly recommended;
  • 4 GB RAM;
  • a 100 Mbps network interface card.

Requirements to software and settings:

  • an installed and configured Ubuntu 20.04, 22.04, or 24.04 LTS x86-64 or arm64 operating system;
  • if the Access Point is separated from other networks by a firewall and/or NAT, the necessary connections to and from the Access Point are allowed;
  • if the Access Point has a private IP address, a corresponding NAT record must be created in the firewall;
  • enabling auxiliary services which are necessary for the functioning and management of the operating system (such as DNS, NTP, and SSH) stay outside the scope of this guide.

2.4 Setup Package Repository

Add the Harmony eDelivery Access repository’s signing key to the list of trusted keys:

curl https://artifactory.niis.org/api/gpg/key/public | sudo apt-key add -

The repository key details:

  • Hash: 935CC5E7FA5397B171749F80D6E3973B
  • Fingerprint: A01B FE41 B9D8 EAF4 872F A3F1 FB0D 532C 10F6 EC5B
  • 3rd party key server: Ubuntu key server

Add Harmony eDelivery Access package repository:

sudo apt-add-repository -y "deb https://artifactory.niis.org/artifactory/harmony-release-deb $(lsb_release -sc)-current main"

Update package repository metadata:

sudo apt update

2.5 Access Point Installation

External MySQL 8 database setup (optional)

When using an external database (MySQL 8 required), it is necessary to create the database schema and user before installing the access point. Please also make sure that the external database accepts connections from the Access Point host.

The schema and user can be created using the following SQL DDL statements (adjust user and schema name as needed; the default harmony_ap is used in the example):

-- mysql
create schema if not exists harmony_ap;
alter schema harmony_ap charset=utf8mb4 collate=utf8mb4_bin;
create user if not exists harmony_ap@'%';
alter user harmony_ap@'%' identified by '<password>';
grant all on harmony_ap.* to harmony_ap@'%';

It is also necessary to populate MySQL time zone information tables, e.g. using the following command as root on the external database host:

mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

When using a local database, the installer handles these additional steps.

Access point install

Issue the following command to install the Harmony eDelivery Access Access Point:

sudo apt install harmony-ap

Upon the first installation of the Access Point, the system asks for the following information.

  • Whether you want the Access Point installation to use dynamic discovery.
    • If yes: SML zone that you want to use.
    • If you're not sure about the correct value, please contact the domain authority of the policy domain where the Access Point is registered.
    • The value can be edited later by changing the domibus.smlzone property in the /etc/harmony-ap/domibus.properties configuration file.
  • Username of the administrative user - username to use to log in to administrative UI.
  • Initial password for the administrative user.
    • Note: the default password expiration policy is 90 days, and it applies to the administrative user too.
  • Party name of the Access Point owner organisation.
    • If you don't know the party name of the owner, use the default value (selfsigned).
  • Distinguished Name for generated self-signed content (security) certificate (see Note1 and Note2).
    • For example: 
      CN=org1_gw, O=My Organisation, C=FI
  • Distinguished name (DN) and Subject alternative name (SAN) for the generated self-signed server TLS certificate (see Note1 and Note2).
    • For example: 
      CN=ap.example.org, O=My Organization, C=FI
SAN=DNS:ap.example.org
  • Port number that the Access Point listens to.
    • The default is 8443; Access Point admin UI, backend interface and AS4 interface all run on the defined port.
  • Access point database configuration. When using a local database, accept the defaults.
    • Database host. The default is localhost.
    • Database port. The default is 3306.
    • Database schema name. The default is harmony_ap.
    • Database username. The default is harmony_ap.
    • Database password. There is no default. Leave blank to generate a random password when installing a local database.

Note1: The Distinguished Name (DN) uniquely identifies an entity in an X.509 certificate [RFC5280]. The following attribute types are commonly found in the DN: CN = Common name, O = Organization name, C = Country code. It's recommended to use PrintableString characters [PS] in the attribute type values.
Note2: Different eDelivery policy domains may have different requirements for the Distinguished Name. If you're not sure about the requirements, please contact the domain authority of the policy domain where the Access Point is registered.

See the Static Discovery Configuration Guide [UG-SDCG] and the Dynamic Discovery Configuration Guide [UG-DDCG] for more information about how to configure different discovery options.

(Optional) Configuring the Bouncy Castle cryptography provider preference order

The property domibus.security.bc.provider.order in /etc/harmony-ap/domibus.properties can be used to set the preference order of the Bouncy Castle Java Cryptography Architecture cryptography provider. The preference order is the order in which security providers are searched for algorithms. The Bouncy Castle provider provides alternative implementations and some additional algorithms compared to the OpenJDK standard providers.

By default (when the property is not defined), the provider is added to the last position. To match the behavior of the Domibus Access Point, the provider can be inserted at position 3. However, that breaks standard PKCS12 keystores when using Java 11, and should only be used to resolve potential compatibility issues (no such issues are currently known). A restart of the harmony-ap is required after changing the property.

2.6 Starting harmony-ap Service and Enabling Automatic Startup

To start harmony-ap service issue the following command:

sudo systemctl start harmony-ap

If you want harmony-ap service start at system startup issue the following command:

sudo systemctl enable harmony-ap

2.7 Post-Installation Checks

Ensure that the harmony-ap service is in the running state (example output follows):

sudo systemctl list-units "harmony-ap*"
UNIT                           LOAD   ACTIVE SUB     DESCRIPTION
harmony-ap.service             loaded active running Harmony eDelivery Access - Access Point

Ensure that the administrative user interface at https://<host>:8443/ can be opened in a Web browser. To log in, use the administrative username and password chosen during the installation. While the user interface is still starting up, the Web browser may display a connection refused -error.

2.8 Installing Custom Plugins

The Access Point comes with one default plugin - the Web Service (WS) Plugin. See the WS Plugin documentation [WS_PLUGIN] for more details.

Custom plugins can be installed by following the steps below:

  1. stop the harmony-ap service (sudo systemctl stop harmony-ap);
  2. copy the custom plugin jar file to the plugins folder (/etc/harmony-ap/plugins/lib);
  3. copy the custom plugin configuration files to the config folder (/etc/harmony-ap/plugins/config);
  4. start the harmony-ap service (sudo systemctl start harmony-ap).

See the Domibus Plugin Cookbook [PLUGIN_COOKBOOK] for more information on developing custom plugins.

2.9 Changes Made to System During Installation

In addition to installing required dependencies, the installation process completes the following steps:

  • creates linux user harmony-ap that is used to run the Access Point service;
  • creates MySQL database user harmony_ap and generates random password for it;
  • creates MySQL database schema harmony_ap and populates it with needed metadata;
  • loads initial configuration into database;
  • generates self-signed certificates for content encryption and transport encryption;
  • creates initial configuration for One-Way SSL between two Access Points;
    • sharing and importing certificates must be handled manually after the installation;
  • installs the harmony-ap systemd service but does not enable or start it.

2.10 Location of Configuration and Generated Passwords

All Access Point configuration files are located in the /etc/harmony-ap directory. See the Domibus Administration Guide [DOMIBUS_ADMIN_GUIDE] for more details.

During the installation process, multiple random passwords are generated.

Password purpose Password location
Password for harmony-ap MySQL user Configuration file: /etc/harmony-ap/domibus.properties

Properties: domibus.datasource.xa.property.password and domibus.datasource.password.
Content encryption keystore (/etc/harmony-ap/ap-keystore.p12) password Configuration file: /etc/harmony-ap/domibus.properties

Properties: domibus.security.keystore.password and domibus.security.key.private.password. Content of this keystore can be changed using the administrative UI.
Content encryption truststore (/etc/harmony-ap/ap-truststore.p12) password Configuration file: /etc/harmony-ap/domibus.properties

Properties: domibus.security.truststore.password. Content of this keystore can be changed using the administrative UI.
TLS keystore (/etc/harmony-ap/tls-keystore.p12) password Configuration file: /etc/harmony-ap/conf/server.xml

Property: keystorePass
TLS truststore (/etc/harmony-ap/tls-truststore.p12) password Configuration file: /etc/harmony-ap/conf/server.xml

Property: truststorePass

2.11 Log Files

The Access Point application log files are located in the /var/log/harmony-ap/ directory.

For more detailed information, see the Access Point Logging Guide [UG-AP-L].

3 Version Upgrade

It is recommended to take a backup of the system (database and configuration in /etc/harmony-ap) before the upgrade.

3.1 Additional steps for an external database

If you are using an external database, you need to grant the Harmony access point database user additional rights before the upgrade. The additional rights can be revoked afterwards.

-- mysql
grant SYSTEM_VARIABLES_ADMIN on *.* to harmony_ap'@'%'

When using an external database, it is also necessary to manually populate MySQL time zone information tables, e.g. using the following command as root on the external database host:

mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

3.2 Upgrade

The harmony-ap service is automatically stopped for the upgrade and automatically restarted after the upgrade if the service has been enabled. Otherwise, the service must be manually restarted after the upgrade.

Update package repository metadata:

sudo apt update

Issue the following command to run the upgrade:

sudo apt upgrade

If the installer asks for database configuration, accept the existing configuration read from /etc/harmony-ap/domibus.properties. Leaving the database password blank uses the password from configuration.

If starting the service at system startup hasn't been enabled, the harmony-ap service must be started manually after the upgrade:

sudo systemctl start harmony-ap