1. Revision History
Version / Date / Author / Description1.00 / 08/10/2009 / Valentin Vladescu, Petr Sochůrek / First version
1.5 / 07/02/2010 / Jiří Šitina, Jiří Neuman, Petr Sochůrek / Updates for ECP version 1.5
2.1.0 / 27/01/2011 / Michal Ráček / Updates for ECP version 2.1
3.0.0 / 10/06/2013 / Luboš Světik, Petr Zdráhal / Updates for ECP version 3.0
3.0.1 / 02/07/2013 / Petr Zdráhal / Update Linux installation proces.
3.0.2 / 09/07/2013 / Petr Zdráhal / New template, content revision.
3.0.3 / 16/07/2013 / Petr Zdráhal / RTE remarks processed
3.0.4 / 25/07/2013 / Petr Zdráhal / Export of ECP Configuration
3.0.5 / 29/07/2013 / Petr Zdráhal / Proxy setting in Linux installation
3.0.6 / 02/08/2013 / Petr Zdráhal / Minor changes
3.0.7 / 27/08/2013 / Unicorn / English revision
3.0.8 / 19/02/2014 / Petr Zdráhal / Minor changes in Linux installation steps
3.0.9 / 24/11/2014 / Petr Sochůrek / Endpoint HA concept
3.0.10 / 16/03/2014 / Daniel Kubát / Added note about install DB
2. ContentS
1. Revision History 3
2. ContentS 4
3. Introduction 6
4. ECP Endpoint Installation 8
4.1. First Installation or Reinstallation 8
4.2. Installation on Windows 8
4.3. Installation on Linux 17
5. Appendix 21
5.1. Prerequisites 21
5.1.1. Summary of Information to Collect Before Installation 21
5.1.2. Hardware Requirements 21
5.1.3. Operating System 22
5.1.4. Web Browser Support 22
5.1.5. OS Users 22
5.1.6. Connectivity to External Database Server 23
5.1.7. Connectivity to ECP Node 23
5.2. Install External Database 23
5.2.1. Disabling DNS Names Resolving on MySQL Database 24
5.2.2. Transaction Isolation Level 24
5.3. Verify the Installation 25
5.3.1. Check Running Application Server 25
5.3.2. Display ECP Client Web Page 25
5.3.3. Perform Send/Receive Message Test 26
5.4. Additional Information 28
5.4.1. ECP Endpoint Registration 28
5.4.2. Backup of Embedded PostgreSQL Database 30
5.4.3. Export of ECP Configuration 30
5.4.4. Component Codes 31
5.4.5. Structure of Installed ECP Endpoint 31
5.5. Endpoint High Availability Concept 32
6. Uninstalling ECP Endpoint 34
7. TroubleShooting 35
7.1. Tomcat does not Start on Windows 2008 35
7.2. Send/Receive Message Test Troubleshooting 35
8. Glossary 36
9. References 37
3. Introduction
This installation guide contains step-by-step installation instructions for the client part of the ECP platform.
To understand the concepts of the installation, let’s look at the basics of the ECP architecture. The ECP platform is organized into two main components:
> Node – the central ECP component.
> Endpoint – the client-side ECP component, responsible for message encryption, decryption, signing and signature verification and communication with the Node.
Figure 1: ECP Architecture
The business applications (BA) that send and receive messages through ECP communicate using the ECP API that is exposed by the Endpoint. There are three different API referred to as channels – Web services, Java API and shared folder.
Reading the detailed concept of ECP in following documentation before starting the installation is strongly recommended:
> ECP Introduction [Introduction]
> ECP High Level Concept [HighLevelConcept]
> ECP Installation [Installation]
The installation process involves a few steps:
1. Checking the installation prerequisites.
2. ECP Endpoint Installation - this step is different for the Windows and Linux platforms.
3. Verification – as a last step, we verify that the ECP Endpoint was installed successfully.
The guide is solely intended for describing the installation procedure of the ECP Endpoint and does not treat all of the possible configuration options in great detail. For in-depth documentation of ECP configuration, refer to the administration guide [AdminGuide].
This guide only targets client-side ECP component installation. The Installation of a Node is described in separate documents – ECP Installation Guide – Node [InstallNode].
There are three possible API that a business application can use to send and receive messages using ECP: Web services, Java API and shared folder (also referred as FSSF). The API are described in ECP Public Interface [PublicInterface].
Note that this document assumes that the user installing the ECP software has a good understanding of the concepts of target operating system.
4. ECP Endpoint Installation
The following ECP Endpoint installation packages are available:
> Windows platform (ECP_Windows_X.Y.Z_BUILD-xxx.exe)
> Linux platform (ECP_Linux_X.Y.Z_BUILD-xxx.zip)
The installation procedure differs for the platforms:
> For Linux platforms the installation procedure is manual. It is necessary to copy unzipped package content to the target location, modify its configuration, and run it using the delivered scripts.
> For the Windows platform a user-friendly visual installer is provided to guide you through the entire installation and registration procedure.
4.1. First Installation or Reinstallation
If you are installing a new ECP Endpoint, you first need to collect all information described in Chapter 5.1.1 and check that you fulfill all the requirements (e.g. hardware, connectivity) of the prerequisite Chapter 5.1.
The installation includes registration to the ECP Node and the generation of the certificates used to secure the communication and the exchanged messages.
Important: When the installation is completed correctly and your registration is approved by the Node Administrator, it is highly recommended that you export and store in a secured and safe location the installation configuration file, which contains all information about the Endpoint, including certificates. This configuration can be downloaded from the monitoring page on the web interface.
This information will be necessary if you need to reinstall the Endpoint with the same configuration; otherwise you will have to register again and generate new certificates.
4.2. Installation on Windows
The ECP Installation package for Windows is provided as a self-extractable archive.
To install the ECP Endpoint, follow these steps:
1. Run the installation package (run the installer under OS user with sufficient rights as described in Chapter 5.1.5.1 – Installation User).
a. Choose the directory path for extracting the ECP package. The selected directory must not exist or be empty.
b. Wait until the package is extracted.
The visual installer is then launched.
1. The launched GUI installer shows the first page where you can load the configuration for the ECP Installer and notes. If you use the configuration file and load them using this button, all subsequent steps will be prefilled with parameters from this file. The configuration file can be generated from a previous installation of ECP or can be obtained from the ECP administrator with the installation package.
2. The next page requires you to enter the URL address of your ECP home Node.
You can enter a proxy configuration if a proxy server is needed to connect to the Node.
3. On the next page you can enter the destination path or use the default, and you may choose whether you want to have shortcuts created on your desktop and in the start menu.
The start menu contains the following items:
4. The next step asks you for registration information.
The following information must be filled in:
a. Organization: the official company name (e.g. Elia).
b. Contact person: an internal person that can be contacted by the ECP node administrator if needed.
c. Contact email: an e-mail address that will be used for official ECP communication.
d. Contact phone: a phone number that will be used for official ECP communication.
5. In the next step, you choose which ECP database you want to use. By default an embedded PostreSQL database will be installed and in this case, no other configuration is needed.
If you wish to use an external database, you must perform the following steps:
a. Install the ECP schema - follow Chapter 5.2 – Install External Database.
b. Insert the JDBC connection string, database user and password.
6. On the next page you may choose custom encryption and signing certificates or use the default configuration.
7. When you proceed to the next page, a summary will be displayed. Verify that the information shown is correct and corresponds to your requirements. Then click the Install button. If you want to change any parameters, you can return to the previous pages and correct the values.
8. When you click the Install button, the installation of the ECP Client will start. Wait until the installer completes all steps. Then click Next.
If an error occurs during installation, the installation is stopped and a short description of the problem is shown on the page. Details concerning the error are logged into ecp_setup.log file (located in the folder where the self-executable was extracted; see step 1). In this case the user can only click Cancel, which exits the visual installer.
9. If the installation was successfully completed, the installation result page is displayed.
At this point the Endpoint is installed but is not running. Before you exit the installer, you can do the following operations:
a. Export the configuration of the installer (including certificates) – it is recommended that you save your installation configuration files with registration information for future use, such as the reinstallation of ECP is needed. The configuration may be saved later using the web interface as described in Chapter 5.4.3. It is strongly recommended that you save your configuration after the Endpoint is successfully installed.
b. You can start the module by checking the “Start ECP Endpoint after exit” box. This starts the Tomcat and PostgreSQL embedded services. The services can be started manually later using the shortcuts in the start menu or using scripts in the batches directory in the ECP installation directory.
10. Once the Endpoint module is running, you should wait for registration approval by the ECP Node Administrator.
11. After successful installation, you will be able to open the web page of your ECP client by entering the address: http://your-server-ip-or-host:8080/ECP_MODULE in your web browser. You can also use the shortcut from your desktop or start menu to get there.
12. After the first installation is finished, there are possibilities for some additional configurations. For more details, refer to the administration guide [AdminGuide] and contact your ECP support.
Note:
> Installed services for Tomcat and PostgreSQL always start automatically when the machine boots.
> If you would like to start ECP manually from “start menu” links, take the following steps:
- Start Command Line as Administrator.
- Run command sc config "ECP" start=demand for Tomcat.
- Run command sc config "ECP postgre" start=demand for PostgreSQL.
4.3. Installation on Linux
The ECP Installation procedure consists of the following steps (they should be done under an OS user which has sufficient rights as described in Chapter 5.1.5.1 – Installation User):
1. Decompress the installation package zip file to the target location.
a. Use the “unzip ECP_Linux_X.Y.Z_BUILD-xxx.zip” command. The target folder of the decompressed package will be considered the root folder for all commands in this tutorial.
2. If you want to use the embedded PostgreSQL database, you must perform the following steps:
a. Ensure that the user postgres exists in the OS. Use the “useradd postgres” command to create the user and “passwd postgres” to assign the arbitrary password to it (otherwise the account remains locked).
b. Allow the OS user postgres to be the owner of the directory in which the database is located. Use the “chown –R postgres ./db” command.
c. Start your database. If you use an embedded database, go to the directory “./batches/” and execute the “./startup_db.sh” command.
3. If you want to use an external database, you must perform the following steps:
a. Install the ECP schema - follow Chapter 5.2 – Install External Database.
b. Configure the connection to the external database in “./tools/DSImporter/DSImporter.properties”.
Parameter / Description / DefaultDatabase / JDBC connection string for the database. / jdbc:postgresql://localhost:5432/ecp
Database.User / User for connection to the database. / ecp
Database.Password / Password for the database user. / ecpsql
Database.Driver / Database driver. / org.postgresql.Driver
Database.Dialect / Database dialect. / POSTGRESQL
4. The registration tool will now be used. This tool creates registration on Node and stores information in the database. For correct functionality, the “./tools/RegistrationTool/registration.properties” file must be configured.
Parameter / DescriptionRegistration.Type / Defines purpose of the registration tool. (default value is ECP)
Registration.Organization / The official company name (e.g. Elia).
Registration.Person / Name of the internal person that can be contacted by the ECP node administrator if needed.
Registration.Email / E-mail address that will be used for official ECP communication.
Registration.Phone / Phone number that will be used for official ECP communication.
Registration.NodeUrl / URL of the Node where the Client will be connected.
(e.g. https://ecptest.entsoe.eu/ECP_MODULE
https://ecp.entsoe.eu/ECP_MODULE)
Registration.Environment / Environment in which the Client is installed (Linux, Windows).
Certificate.Signing.Private / Path to the custom Signing private certificate (optional).
Certificate.Signing.Public / Path to the custom Signing public certificate (optional).
Certificate.Encryption.Private / Path to the custom Encryption private certificate (optional).
Certificate.Encryption.Public / Path to the custom Encryption public certificate (optional).
Proxy.UseProxy / Parameter indicating whether the proxy must be used TRUE/FALSE (optional)
Proxy.IP / IP address of proxy server (required if proxy is used).
Proxy.Port / Port of the proxy server (required if proxy is used).
Proxy.User / User to access the proxy (optional).
Proxy.Password / Password for the user (optional).
5. Go to the “./tools/RegistrationTool/” directory and execute script “registrationTool.sh”. After the registration is finished, record the component code from the results of the registration.
6. Prepare ECP Client configuration file and put it into “./config/module.properties”. Use “./config/samples/module_endpoint_template.properties” file. The file contains several tokens that need to be manually replaced: