1. REVISION HISTORY

Version Date Author Description 1.5.0 07/02/2010 Jiří Neuman, Petr Sochůrek Created the new document. 2.1.0 29/01/2011 Michal Ráček Updates for version 2.1. 3.0.0 10/06/2013 Luboš Světik Updates for version 3.0 3.0.1 01/07/2013 Petr Zdráhal Document revision and minor changes Layout modification, merger of Linux and 3.0.2 10/07/2013 Petr Zdráhal Windows installation 3.0.3 18/07/2013 Petr Zdráhal RTE remarks processed 3.0.4 25/07/2013 Petr Zdráhal Introduction updated 3.0.5 29/07/2013 Petr Zdráhal Installation steps update 3.0.6 02/08/2013 Petr Zdráhal Minor changes. 3.0.7 27/08/2013 Unicorn English revision 3.0.8 16/03/2015 Daniel Kubát Added note about install DB and revision

> 3 < 2. CONTENTS

> 4 < 3. INTRODUCTION

This installation guide contains step-by-step installation instructions for the central part of the ECP platform – the ECP Node. 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

In ECP-deployment terminology, the central part of ECP is referred to as a Node. It may act not only as a Node, but also as an Endpoint. We strongly recommend reading the detailed concept of ECP in the following documentation before starting the installation: ECP Introduction [Introduction] ECP High Level Concept [HighLevelConcept]

> 5 < ECP Installation [Installation] The installation process involves three main steps: Pre-requisites – a check that all necessary software is installed and configured on the server is made first. ECP Installation – as the second step, the ECP Node itself is installed. Verification – as the last step, we verify that the ECP Node was installed successfully This guide is intended solely as a description of the installation procedure of the ECP Node and does not deal in depth with all of the possible configuration options. For in-depth documentation of ECP configuration, refer to the administration guide [AdminGuide]. Note that this document anticipates that the user installing the ECP software has a good understanding of the concepts of the target operation system.

> 6 < 4. BEFORE THE INSTALLATION

If you are installing a new ECP Node, you must first collect all the information described in Chapter 5.1.1 and check that you fulfill all the requirements (e.g. hardware, connectivity) of the prerequisite Chapter Installation on Windows. Note:  Whereas the ECP Endpoint installation can optionally set up a local PostgreSQL database, the use of an external database is strongly recommended for ECP Node installation. The database must be independently and previously installed and administrated.  The creation of the database schema and database objects (e.g. tables, indexes) is part of the ECP Node installation.  The database must then be up and running during the whole installation process.

> 7 < 5. ECP NODE INSTALLATION

The following ECP 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. The following steps contain the basic installation of the node. If you would like to prepare a more complex deployment (e.g. high-available cluster), contact ECP support.

> 8 < 5.1. Installation on Windows

The following installation steps must be performed during ECP Node Installation on the Windows platform: 1. Run the executable with the installation package. a. Choose the path to extract the ECP package. The selected directory must not exist or must be empty. Replace the temporary path with the final path where ECP will be installed (e.g. C:\Program Files\ECP)

b. Wait until the package is extracted.

The visual installer is then launched. 2. When you are prompted to start setup.exe, cancel it 3. Install the ECP database schema - follow Chapter Install External Database – Install External Database. 4. Prepare the ECP Node configuration file and put it into “./config/module.properties”. Use the “./config/samples/module_node.properties” file. The file contains several tokens that must be replaced manually. Parameter Description Example [databaseConnectionString] JDBC connection string PostgreSQL: for the database. jdbc:postgresql://localhost:5432/ecp MS SQL Server: jdbc:sqlserver://192.168.81.25;datab ase=ecp;integratedSecurity=false;

> 9 < Oracle: jdbc:oracle:thin:@192.168.81.25:152 1:xe MySQL: jdbc:mysql://192.168.80.157:3306/ec p?autoReconnect=true User for connection to [databaseUser] ecp the database. Password for the [databasePassword] ecpsql database user. PostgreSQL: org.postgresql.Driver MS SQL Server : com.microsoft.sqlserver.jdbc.SQLSer [databaseDriver] Database driver. verDriver Oracle: oracle.jdbc.driver.OracleDriver MySQL: com.mysql.jdbc.Driver PostgreSQL : POSTGRESQL MS SQL Server : SQL_SERVER [databaseDialect] Database dialect. Oracle : ORACLE MySQL : MYSQL The component code of [endpoint] the endpoint that will be TEST installed with the Node. The path of ECP target [appPath] location from step 1. Password to Java [keystorePassword] Password Keystore.

Changing the users that will have access to the Node web interface using parameters is also strongly recommended (see [AdminGuide]) 1. Node.webauthentication.N.login 2. Node.webauthentication.N.password 5. This requires copying the Keystore file to \certificates\ecp_module.jks a. For testing purposes, use the sample file from \certificates\sample\jks\ecp_module.jk. Password for this jks is “password”. b. For production use, the jks file must be assembled in cooperation with ECP root certification authority (e.g. ENTSO-E certificate administrator). 6. Now it is necessary to use the DSImporter tool, the main purpose of which is to initialize the Directory Service and Local Keystore components. Follow Chapter Initialization of the Directory Service – Initialization of the Directory Service. 7. Enable the HTTPS protocol as described in [AdminGuide] Chapter 4.1.3 – Enabling HTTPS provided by the ECP Application. 8. Disable the HTTP protocol as described in [AdminGuide] Chapter 4.1.4 – Disabling HTTP provided by the ECP Application.

> 10 < 9. Run \batches\tomcat_service_install.cmd as the Administrator. 10. Run \batches\tomcat_service_start.cmd. 11. If everything goes well, you will be able to see the login page of ECP when you enter the following address: http://your-server-ip-or-host:8080/ECP_MODULE. The installation is complete.

> 11 < 5.2. Installation on Linux

The following installation steps must be performed during ECP Node Installation on the Linux platform:

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 for the decompressed package will be considered as the root folder of all commands in this tutorial. 2. Install the ECP database schema - follow Chapter Install External Database – Install External Database. 3. Prepare the ECP Node configuration file and put it into “./config/module.properties”. Use the “./config/samples/module_node.properties” file. The file contains several parameters that must be replaced manually. Parameter Description Example PostgreSQL: jdbc:postgresql://localhost:5432/ec p MS SQL Server: jdbc:sqlserver://192.168.81.25;data JDBC connection string base=ecp;integratedSecurity=false; [databaseConnectionString] for the database. Oracle: jdbc:oracle:thin:@192.168.81.25:15 21:xe MySQL: jdbc:mysql://192.168.80.157:3306/e cp?autoReconnect=true User for connection to the [databaseUser] ecp database. Password for the [databasePassword] ecpsql database user. PostgreSQL: org.postgresql.Driver MS SQL Server : com.microsoft.sqlserver.jdbc.SQLS [databaseDriver] Database driver. erverDriver Oracle: oracle.jdbc.driver.OracleDriver MySQL: com.mysql.jdbc.Driver PostgreSQL : POSTGRESQL MS SQL Server : SQL_SERVER [databaseDialect] Database dialect. Oracle : ORACLE MySQL : MYSQL The component code of the endpoint component [endpoint] TEST within the Node installation. The path of ECP target [appPath] location from step 1. Password to Java [keystorePassword] password Keystore.

> 12 < It is strongly recommended that the users who will have access to the Node web interface also be changed using the parameters (see [AdminGuide]): 3. Node.webauthentication.N.login 4. Node.webauthentication.N.password 4. In this step it is necessary to copy the Keystore file to \certificates\ecp_module.jks. a. For testing purposes, use sample file from \certificates\sample\jks\ecp_module.jk. The password for this jks is “password”. b. For production use, the jks file must be assembled in cooperation with ECP root certification authority (e.g. ENTSO-E certificate administrator). 5. Now it is necessary to use the DSImporter tool, the main purpose of which is to initialize the Directory Service and Local Keystore components. Follow Chapter – Initialization of the Directory Service Initialization of the Directory Service. 6. Enable the HTTPS protocol as described in [AdminGuide] Chapter 4.1.3 – Enabling HTTPS provided by the ECP Application. 7. Disable the HTTP protocol as described in [AdminGuide] Chapter 4.1.4 – Disabling HTTP provided by the ECP Application. 8. Run \batches\startup_tomcat.sh. 9. If everything goes well, you will be able to see the login page of ECP when you enter the following address: https://your-server-ip-or-host:443/ECP_MODULE. The installation is complete.

> 13 < 6. APPENDIX

> 14 < 1.1. Prerequisites

Make sure that your environment is capable of running the ECP Node. The hardware requirements depend on the traffic that will go through the installed ECP Node. We recommend deploying the ECP Node on a high available clustered environment. The ECP support and maintenance team can help you with thid installation.

> 15 < 6.1.1. Summary of Information to Collect Before Installation

Information Comment Whom to ask ECP Node URL Always needed. The URL looks like: Your Server https://192.168.81.54:443/ECP_MODULE. administrator The database JDBC Check that the Database "transaction isolation connection string, the level" is set to "read committed". Your external database database user and The objects in the database schema (e.g. tables, administrator password indexes) should previously have been created as described in Chapter Install External Database Organization, Contact Needed for configuring the ECP Node. person, Contact email, Your own organization Contact phone

> 16 < 1.1.1. Hardware Requirements

> 17 < 6.1.1.1. Basic Configuration The following configuration can handle units of messages per minute. Component Value Processor 4x CPU RAM 4GB 80GB (depends on the number of messages and Disk their contents)

> 18 < 6.1.1.2. Recommended Configuration The configuration below can handle hundreds of messages per minute. For application servers, we recommend following the minimal configuration. Component Value Processor 2x CPU Quad Core Intel Xeon RAM 4GB Disk 120GB

For database servers we recommend following the minimal configuration. Component Value Processor 2x CPU Quad Core Intel Xeon RAM 8GB Disk 500GB

> 19 < 1.1.2. Operating System

The following operating systems were tested and are supported. The ECP should also work on others platform without any problems.  Red Hat Enterprise Linux 6.3 64bit  Windows Server 2008 32bit/64bit  Windows Server 2012 32bit/64bit  Windows 7 32bit/64bit

> 20 < 1.1.3. Web Browser Support

The following web browsers were tested and are supported for accessing the ECP administration web interface. The application interface should also work on other browsers. Browser Version Mozilla Firefox Version 20 Internet Explorer Version 8, 9, 10 Google Chrome Version 25

> 21 < 6.1.2. OS Users

> 22 < 6.1.2.1. Installation User The ECP application should be installed under an OS user with the following administration rights: Is able to access installation media and to copy the installation package to a temporary directory. Is able to execute Installer and/or installation scripts from the installation package. Has read/write rights to the directory with the installation package and target installation directory. [Windows] Has the right to install OS services. The Tomcat service is always installed and PostgreSQL database service is installed if the default configuration is used (embedded postgreSQL database).

> 23 < 6.1.2.2. User for Running the Application A common user without administration permission is sufficient. User for running application is user, which is running application server (Tomcat). The following conditions must be fulfilled: The user is able to execute the embedded application server (Tomcat). The user is able to execute scripts located in the /batches directory. The user has read/write access to the installation directory. The user has read/write access to the directory in which the application logs are written. The user has the right (login/password) to log into the ECP database. This is necessary when the planned installation configuration is to use an already preinstalled database. Otherwise a PostgreSQL database will be set up as part of the installation process.

> 24 < 1.1.4. Connectivity to External Database Server

In the case that the ECP Node uses an external database server which runs on a separate or local machine, it is necessary to ensure that the database can be accessed. Check the connectivity to the database with your database administrator.

> 25 < 1.2. Install External Database

This chapter describes the steps necessary to install the ECP schema in an external database. There is one additional step for MySQL database users. If you are using a MySQL database, refer to Chapter 5.2.1 first and disable DNS names resolving. Before the installation, also check the transaction isolated level described in Chapter Transaction isolation level. The following steps must be performed: 1. Go to the /db-sql directory located under the ECP installation package directory. 2. Edit build--db.sh script (or build--db.cmd depending on your operating system) and update the database URL, root user and password which will be used to connect to your database. 3. Execute the build--db.sh command (build--db.cmd on Windows) and wait until the ECP schema is successfully installed. Note that during installation it removes any existing schema and user with specified names. Note: Please ignore notification "Unable to locate tools.jar. Expected to find it in C:\Program Files\ECP\java\lib\tools.jar" during performing installation. This is just warning which have no negative effects. The "root user" database is used to create the database schema. If you don't have access to the "root user" database, ask your database administrator to create the schema. For example, when using an Oracle database, the schema creation is done by the /db-sql/sql/Oracle/user.sql script. No privileged access is then required to create the objects within the schema; to do so run the /db-sql/sql/Oracle/install.sql script, which creates tables, indexes and others necessary objects. For other databases you will find similar scripts in the /db-sql/sql/ directory.

> 26 < 1.2.1. Disabling DNS Names Resolving on MySQL Database

The MySQL database server tries to resolve DNS names with each request by default. This operation could cause performance losses in cases when the server is unable to resolve the DNS name properly. There can be delays of up to several seconds for each database request. In order to avoid this issue, we advise you to disable DNS resolving on your MySQL server. You need to update the database server configuration file (my.cnf) with the parameter ‘skip- name-resolve’ in section [mysqld] and restart the database server. Example of section [mysqld] in the configuration file: [mysqld] skip-name-resolve

> 27 < 6.1.3. Transaction isolation level

The database transaction isolation level must be set to the ‘read committed’ level. The PostgreSQL database bundled in the ECP installation package is set to this level by default. For other supported databases, check with your database administrator.

> 28 < 6.2. Initialization of the Directory Service

The DSImporter is a tool used to initialize the Directory Service and the Local Keystore components during the installation of a Node.

> 29 < 6.2.1. Directory Service and Local Keystore Setup

DSImporter tool is located in the \tools\DSImporter directory. 1. Go to the ‘\tools\DSImporter’ directory. 2. Make a backup copy of the file ‘DSImporter.properties’. 3. Rename file ‘DSImporter_Node.properties’ to ‘DSImporter.properties’. 4. Update the DSImporter.properties file values. a. Open the DSImporter.properties file in your favorite text editor. b. Update the configuration parameters described in Chapter 6.3.1.1. Important: the database connection parameters should exactly match the ones used in the previously configured ‘module.properties’ (see Chapter Installation on Windows, step 4 for Windows or Chapter Installation on Linux, step 3 for Linux). c. Save the file and exit the text editor. 5. Make sure the ECP database is running. 6. Run the setup_ds.cmd for Windows (setup_ds.sh for Linux installation) command and check the result (the output has to end with “BUILD SUCCESSFUL”). The DSImporter.log log file should be created in the directory of the DSImporter.

> 30 < 6.2.1.1. Configuration Parameters This chapter briefly describes the configuration parameters needed by DSImporter to set up the ECP Node.

Parameter Description Example value You can specify whether the Endpoint component will be Endpoint.Enabled TRUE / FALSE enabled or disabled within the Node installation. The component code of the endpoint component within the Node installation. This value should be equal to the setting of the parameter Endpoint.Code [endpoint] in TEST ‘module.properties’ file. Add the ‘#’ character at the beginning of the line in the case that the Endpoint component is disabled. The component code of the Node component within the installation. This value should be equal to the setting of ‘Node.Code’ in Node.Code TEST-MN ‘module.properties’ file made in Chapter 5.1, step 4. The component code value for the Node must end with the ‘-MN’ postfix. Primary URL of installed https://192.168.81.43:443/ECP_MODULE/servic Node.PrimaryUrl Node. es Node.SecondaryUrl Secondary URL of installed https://192.168.81.43:443/ECP_MODULE/servic (optional) Node. es Organization in which the Node.Organization Unicorn installed Node belongs. Contact person responsible Node.Person Brandon McCartney for the installed Node. Email of the installed Node Node.Email [email protected] contact person. Phone number of the Node.Phone installed Node contact +420 555 555 person. Description of the system Node.Enviroment environment of the installed Windows Node. PostgreSQL: jdbc:postgresql://localhost:5432/ecp MS SQL Server: JDBC connection string jdbc:sqlserver://192.168.81.25;database=ecp;int Database pointing to the installed ECP egratedSecurity=false; database. Oracle: jdbc:oracle:thin:@192.168.81.25:1521:xe MySQL: jdbc:mysql://192.168.80.157:3306/ecp? autoReconnect=true

> 31 < Parameter Description Example value ECP application database Database.User ecp user. ECP user database Database.Password ecpsql password. PostgreSQL: org.postgresql.Driver MS SQL Server : com.microsoft.sqlserver.jdbc.SQLServerDriver Database.Driver Database driver Oracle: oracle.jdbc.driver.OracleDriver MySQL: com.mysql.jdbc.Driver PostgreSQL : POSTGRESQL MS SQL Server : SQL_SERVER Database.Dialect Database dialect Oracle : ORACLE MySQL : MYSQL

> 32 < 6.2.2. Troubleshooting

All information on running the DSImporter tool is written into log files placed within the ‘\tools\DSImporter\logs\’ directory. These log files always contain information about the reason for the DSImporter failure, and log files should always be checked in the case of any problems with the DSImporter tool.

Most problems with the DSImporter tool are caused by the wrong configuration of the DSImporter.properties file, and the best way to solve them is a detailed check of the configuration.

In the case that the DSImporter fails during the Directory Service initialization, it is necessary to clean the ECP database and the ECP Keystore manually before the DSImporter tool is executed again. To do so:

1. go to the db-sql directory located under the ECP installation package directory;

2. edit build--db.cmd and update the database URL, root user and password to be used to connect to your database.

3. Execute the build--db.cmd and wait until the ECP schema is successfully reinstalled.

Please ignore notification "Unable to locate tools.jar. Expected to find it in C:\Program Files\ECP\java\lib\tools.jar" during performing installation. This is just warning which have no negative effects.

After the database is cleared, override the ecp_module.jks file located in the \certificates directory with the file \certificates\sample\jks\ecp_module.jks. The reason for this step is that setup_ds.cmd issues new certificates on every run, so the Keystore must be cleared, too.

> 33 < 1.3. Verify the Installation

> 34 < 1.3.1. Check Running Tomcat

Check if Tomcat with deployed ECP is running by using one of these commands according to operation system type: Operating Command Example of Expected Result System Type Linux ps aux | grep root 6052 103 5.6 820584 109624 pts/1 Sl 11:40 0:13 java /usr/java/jdk1.6.0_14/bin/java -Djava.util.logging.config.file=/opt/ecp/master-tomcat/apache- tomcat-6.0.20/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManag er -Djava.endorsed.dirs=/opt/ecp/master-tomcat/apache-tomcat- 6.0.20/endorsed -classpath :/opt/ecp/master-tomcat/apache-tomcat- 6.0.20/bin/bootstrap.jar -Dcatalina.base=/opt/ecp/master- tomcat/apache-tomcat-6.0.20 -Dcatalina.home=/opt/ecp/master- tomcat/apache-tomcat-6.0.20 -Djava.io.tmpdir=/opt/ecp/master- tomcat/apache-tomcat-6.0.20/temp org.apache.catalina.startup.Bootstrap start Windows Check NT services or Task Manager The Tomcat service name is “ECP Tomcat Apache”. for Tomcat process

> 35 < 1.3.2. Display ECP Node Web Page

Go to the URL https://[appserver]:[port]/ECP_MODULE/, where appserver is the IP address of the server where the ECP node is deployed and the port is HTTP port configured for application (usually 443). The web page containing information about the deployed ECP components can be accessed using the link ‘Monitoring’ located in the menu (you will probably need to log in before the monitoring page is made accessible to you). Note that information displayed depends on the installed components.

> 36 < If the page is not displayed, check whether Tomcat is running. In the case of any error, the info page will contain an error message with occurred exception stacktrace. To solve installation problems, send the error message with stacktrace to ECP support, which will provide assistance in solving the issue. The error cause can be also found

> 37 < in the ECP log files. According to current ECP deployment, find the directory containing log files using this table: Log type Logs directory location. Tomcat /container/logs ECP Node /log

> 38 < 1.3.3. Perform Send/Receive Message Test

This test can only be performed using the ECP Node interface if a local Endpoint has been enabled during the installation. Otherwise the message test has to be performed from an external standalone Endpoint installed independently.

> 39 < 1.3.3.1. Send/Receive Message Test Steps To test the ability of the installed ECP Endpoint to send and receive messages, follow these steps to perform the Send/Receive test: 7. Make sure that ECP application is running. 8. Open the ECP info page in the web browser using this address: http://:/ECP_MODULE/. 9. If the login page is displayed, enter your login name and password. 10. Open the Send message page via the link under menu at the top of the page.

11. Fill in the form displayed below.

 A - In the ‘Receiver’s end-point code’ field type the component code of your installed Endpoint.  B - In the ‘Message type’ field insert arbitrary text (for example Type1).  C - Use the ‘Browse...’ button to select the file to be used as message content.  D - Send message by clicking the ‘Send’ button.

> 40 < 12. In the case of a successfully sent message, the Outbox page will appear with your message listed:

13. To receive a sent message, go to the Inbox page (via the link in the menu):

- Click the ‘Download’ button and choose a path to save the file in the save dialog. At this moment the Send/Receive Message test is successfully finished.

> 41 < 1.4. Additional Information

> 42 < 13.1.1. Endpoint Component Installed with the Node

In the case a (local) Endpoint component is enabled, the following points are useful: 1. The local Endpoint is automatically registered with the Node during the installation, i.e. there is no further operation to manually register the Endpoint. 2. Three keys (private/public) and the corresponding certificates (encryption, signing and authentication) are generated during the installation. 3. These 3 certificates are signed using the Node "integrated CA" certificate. 4. The encryption and signing certificates will only be used by the local Endpoint to send/receive messages. 5. The communication between the local Endpoint and the Node uses Java API and not https web services. 6. The authentication certificate will be used by Endpoint to sign the authentication token when communicating over MADES services with “remote” Nodes the in case of multi- node environment. 7. All 3 certificates are stored in the \certificates\ecp_module.jks file together with the Node "Integrated CA" and the "root CA" certificates.

> 43 < 1.4.1. Component Codes

Every ECP component (Node and Endpoint) must have a code that is unique in the ECP network. These codes are technically assigned during the installation process and shall be set in the module.properties file.

> 44 < 1.4.2. Structure of Installed ECP Node

The structure and purpose of folders of installed ECP Node is described in the table (regardless of the platform). Folder Description /ant Apache Ant needed to run some scripts. Batch files for starting and stopping the ECP /batches Node. Keystore file with private certificates related to the /certificates ECP Node. The Keystore file is created during installation. Module.properties configuration file. /config The configuration file is created during installation. Tomcat web application container with deployed /container ECP Node. PostgreSql database server with installed ECP /db schema. Installation scripts for installing the ECP schema in /db-sql supported databases. /documents Documentation relevant to ECP. Messages that are sent and received over the /fssf FSSF public interface if an Endpoint is enabled by the Node. /java Java runtime environment (JRE). /log Log files produced by the ECP application. /tools Additional administration tools.

> 45 < 14. GLOSSARY

Acronym/Keyword Description ECP Energy Communication Platform. Acronym of File System Shared Folder, which is the file-based channel for FSSF accessing the ECP public API. API Application Programming Interface. GUI Graphical User Interface.

> 46 < 15. REFERENCES

[AdminGuide] ECP Administrator’s Guide, Unicorn [Introduction] ECP Introduction, Unicorn [HighLevelConcept] ECP High Level Concept, Unicorn [Installation] ECP Installation, Unicorn [EndpointInstallation] ECP Installation Guide - Endpoint, Unicorn

> 47 <