Energy Communication Platform

1.Contents

2.Revision History

3.ECP Module Configuration

3.1.General Instructions

3.1.1.Configuration Parameters General Rules

3.1.2.Changing Configurations Steps

3.1.3.Configuration Parameters – Overview

3.2.Common ECP Module Configuration Parameters

3.2.1.Connection to Database

3.2.2.ECP Module Logging Settings

3.2.3.Message Archive Settings

3.2.4.Download Request Signing Settings

3.2.5.Connected Endpoint Register Settings

3.2.6.Notification of Expiring Keys

3.2.7.Message Compression

3.2.8.Message Expiration

3.2.9.Message Priority

3.2.10.SSL Configuration on Client Side

3.2.11.Private Key Encryption

3.2.12.Archiving settings

3.3.Endpoint Configuration Parameters

3.3.1.Messaging Component Identification

3.3.2.Connection to Node

3.3.3.Message Signing Settings

3.3.4.GUI Configuration

3.3.5.Upload/Download Interval Settings

3.3.6.Event Manager Settings

3.3.7.ECP Public API – Channel Configuration

3.3.8.Public API – Receiving Handler Registration

3.3.9.Public API – Send Handler Registration

3.4.Node Configuration Parameters

3.4.1.Messaging Component Identification

3.4.2.User Authentication

3.4.3.Notification of Certificate Expiration

3.5.Registration Component Configuration

3.5.1.Node Component Identification

3.5.2.Registration Service

3.6.ECP Module Logging

4.Application Server Configuration

4.1.Server-side Networking Port Configuration

4.1.1.Introduction

4.1.2.Recommended settings

4.1.3.Enabling HTTPS provided by the ECP Application (server)

4.1.4.Disabling HTTP provided by the ECP Application (server)

4.2.Limiting Access to ECP Web Pages

4.3.Securing ECP Application Web Resources

4.3.1.Purpose

4.3.2.Built-in Resources Securing

4.3.3.Additional Security Recommendations

5.High Availability of ecp application

5.1.HA Concept

5.1.1.Prerequisite

5.1.2.Installation/Configuration

5.1.3.Integration with business application (BA)

5.2.Administration Tool Configuration

5.2.1.ECP Guardian

5.2.2.Geographical Cluster Check

6.Administration Tasks

6.1.Managing Trusted Certificate Authorities (DSimporter)

6.1.1.Tool Execution and Configuration

6.1.2.Operation Description

6.2.Update Node List

6.2.1.Description

6.2.2.How to Update Node List File

6.2.3.Upload New Node List File

6.3.ECP Certificates Management

6.3.1.ECP Certificates Introduction

6.3.2.Issuing NODE CA Certificate

6.3.3.Update Certificates for ECP Endpoint

6.3.4.Update Certificates for ECP Embedded Endpoint in Node

6.4.Bandwidth Throttling

6.4.1.Bandwidth Throttling in General

6.4.2.Bandwidth Throttling on Linux

7.Monitoring

7.1.ECP Module – Monitoring Web Page

8.References

8.1.Related Documents

8.2.Web References

2.Revision History

Version / Date / Author / Description
1.0 / 09/07/2009 / Stanislav Mikulecký / Document finalized
1.5 / 15/02/2010 / Jiří Neuman / Changes for ECP version 1.5
2.0.0 / 23/11/2010 / Vlastimil Unucka, Jiří Neuman / Updates for ECP 2.0.0.
2.1 / 21/02/2011 / Jiří Dudek / Directory service importer
3.0.0 / 21/06/2013 / Luboš Světik / Updates for ECP 3.0.0
3.0.1 / 01/07/2013 / Petr Zdráhal / Revision and minor changes
3.0.2 / 26/07/2013 / Petr Zdráhal, Petr Sochůrek / Updated for RTE remarks
3.0.3 / 01/08/2013 / Petr Zdráhal / Final version
3.0.4 / 27/08/2013 / Unicorn / English revision
3.0.5 / 13/11/2013 / Petr Zdráhal / Section 3.3.2 Connection to Node added
3.0.6 / 20/01/2015 / Lukáš Voříšek / Sections 3.2.12 Archiving settings and 6.4 Update certificates for ECP Node added
3.0.7 / 10/02/2015 / Lukáš Voříšek / Sections 4.3 Securing ECP Application Web Resources and 5.1 HA Conceptadded and section 6.3ECP Certificates management updated
3.0.8 / 23.11.2016 / Vojtěch Boukal / Deleted section 6.5 (Archive Messages in Long-term Storage)

3.ECP Module Configuration

The configurable aspects of the ECP module can be modified in a single file - module.properties.

This file is located in the ECP application deployment directory and is created during the ECP installation or the upgrade procedure.

The following subchapters contain the parameters. They are divided with respect to the possible deployment modes.

3.1.General Instructions

3.1.1.Configuration Parameters General Rules

The module.properties is a text file with a format mainly used for Java configuration files. General rules:

Each line stores a single parameter in the form of a key-value pair separated by the equal mark (=). E.g.

ParameterKey1=ParameterValue1

Neither the parameter nor the value can contain trailing white characters.
Empty lines are allowed.
The number sign(#) or anexclamation mark(!) as the first non-blankcharacterin a line may be used to denote that all of the following text is acomment. E.g.

# this is a comment

Comment marks spanning more lines are not supported.
ParameterValue for the directory setting must always end with the character “/”

In this guide the parameters are listed within tables in which columns have this meaning:

Column / Description
Parameter / Name of a parameter as used in a .properties file.
The existence of the token <X> indicates that the parameter can be used multiple times in a configuration file (if required). For each occurrence, the <X> must be replaced by a number part of a continuous sequence starting with 0.
Description / Description of a parameter.
Default value / Represents the value in a .properties file. This value is used after the standard installation of the application. If this value is different for the Node and Endpoint, it is explicitly mentioned.
Possible values
/
Example / List all possible values (only if a limited set of values is allowed)
or
Example of the real value of a parameter

3.1.2.Changing Configurations Steps

To change the configuration, follow these general steps. If you are operating an ECP application in a cluster, perform each step on every cluster node:

Stop running the ECP Tomcat service (use batch script located in batches/ folder).
Modify the module.properties file (located in config/.folder).
Start the ECP Tomcat service (use batch script located in batches/ folder).

3.1.3.Configuration Parameters – Overview

Configuration parameters are divided into groups. This chapter explains which aspects of ECP can be configured in each group. The groups are:

Basic ECP Module Configuration - Chapter3.1.2.1
Endpoint Component Configuration - Chapter3.1.2.2
Node Component Configuration - Chapter3.1.2.3
Registration Component Configuration - Chapter3.1.2.4

3.1.3.1.Common ECP Module Configuration

This group affects the whole module and includes the configuration of:

Connection to database;
ECP module logging settings;
Message archive setting;
Download Request Signing Settings;
Connected Endpoint Register Settings;
Notification of Expiring Keys;
Message compression;
Message expiration;
Message priority;
SSL Configuration on Client Side;
Private key encryption.

For more details, see Chapter 3.2.

3.1.3.2.Endpoint Component Configuration

This group affects the Endpoint messaging component. The Endpoint is responsible mainly for communication with business applications and for the preparation of messages exchanged through the ECP network. The configuration of the following aspects is supported:

Basic configuration of the Endpoint component (its code and description)
Message signing Settings
GUI configuration
Upload/Download Interval Settings
Event Manager Settings
ECP Public API – Channels Configuration
Public API – Receiving Handler Registration
Public API – Send Handler Registration

These configuration aspects are further described in Chapter 3.3 – Endpoint Configuration Parameters.

3.1.3.3.Node Component Configuration

This group includes:

Messaging Component Identification (Node code and description);
User Authentication (Credentials for access via the web UI);
Notification about Certificates Expiration.

To see which parameters can be used to configure the behavior of the Node component, see Chapter 3.4– Node Configuration Parameters.

3.1.3.4.Registration Component Configuration

The Registration component provides access to the “Update form” function (used for creating update request). The Registration component is part of the ECP Node and accesses the database. However, the Registration component is designed to be deployed at a separate application server.

Node component identification
Registration Service

To see which parameters can be used to configure the behavior of the Registration component, see Chapter 3.6– Registration Component Configuration.

3.2.Common ECP Module Configuration Parameters

This chapter describes the configuration parameters which affect the whole ECP module. These parameters allow the configuration of the aspects that don’t belong to any particular messaging component.

3.2.1.Connection to Database

The ECP application uses a relational database as permanent storage. Supported databases are MySql, MSSQL, Oracle, PostgreSQL.

The database may be operated as:

an embedded database (only PostgreSQL, if you decide to install it together with ECP application);
an external database (MySql/MSSQL/Oracle/PostgreSQL located on same or separate machine).

The connection to the database is configured using the following parameters.

Parameter / Description
Database / JDBC connection string
Database.User / Database user
Database.Password / Database password
Database.Driver / Database driver
Database.Dialect / Database dialect

The value of the parameters depends on the database used, as shown in the following examples.

3.2.1.1.Parameters for Connection to MySQL (example)

Database=jdbc:mysql://192.168.80.157:3306/ecp?autoReconnect=true’

Database.User=ecp

Database.Password=ecpsql

Database.Driver=com.mysql.jdbc.Driver

Database.Dialect=MYSQL

It is recommended that the parameter autoReconnect=true be appended to the connection string. Adding this parameter eliminates the problems of broken connections to the MySQL database which may appear when using FSSF channel on Linux.

3.2.1.2.Parameters for Connection to MSSQL (example)

Database=jdbc:sqlserver://192.168.81.25;database=ecp;integratedSecurity=false;

Database.User=ecp

Database.Password=ecpsql

Database.Driver=com.microsoft.sqlserver.jdbc.SQLServerDriver

Database.Dialect=SQL_SERVER

3.2.1.3.Parameters for Connection to Oracle (example)

Database=jdbc:oracle:thin:@192.168.81.25:1521:xe

Database.User=ecp

Database.Password=ecpsql

Database.Driver=oracle.jdbc.driver.OracleDriver

Database.Dialect=ORACLE

3.2.1.4.Parameters for Connection to PostgreSql (example)

Database=jdbc:postgresql://localhost:5432/ecp

Database.User=ecp

Database.Password=ecpsql

Database.Driver=com.postgresql.Driver

Database.Dialect=POSTGRESQL

3.2.2.ECP Module Logging Settings

It is possible to change the directory in which the ECP module log files are stored.

Parameter / Description / Default value / Example
Module.EcpLogger.DirectoryPath / Path to existing directory in which ECP logs will be stored. / - / /tmp/ecp-logs

3.2.3.Message Archive Settings

This affects the way the messages are archived after they have reached the end of their lifecycle.

Parameter / Description / Default value / Example / Other possible values
Module.Archive.DisabledTypes / List of message types that will be archived without their content.
Message types have to be separated using a semicolon (;). Make sure there are no white characters between types.
If the parameter is missing or empty, messages of all types are stored into the archive along with their content. / - / MESSAGETYPE1;MESSASSAGETYPE2

3.2.4.Download Request Signing Settings

Each download request from a messaging component to another must be signed. For security reasons, disabling signing on the production environment is not recommended. Note that this parameter must have the same value for every ECP module in the whole ECP network.

Parameter / Description / Default value / /Other possible values
Module.DownloadRequestSigner.Class / Implementation of download request signer / downloadRequestSigner / / disabledDownloadRequestSigner

3.2.5.Connected Endpoint Register Settings

These settings allow the configuration of the "Endpoint Register" (an ECP Node internal component), which maintains information about connected endpoints. The content of the Endpoint Register is only used for monitoring purposes.

Parameter / Description / Default value / Example
Module.EndpointRegister.Retention / Time in seconds in which endpoint is considered active. If no connection is made by a given endpoint for a specified amount of time, it is deleted from the register of connected endpoints. / 600

3.2.6.Notification of Expiring Keys

The ECP module reports expired or nearly expiring private keys by means of Information Messages. The following parameters modify when the administrator is notified.

Parameter / Description / Default value / Example
Module.KeysExpirationNotification.DaysBeforeExpiration / Number of days; the administrator is warned before the expiration of a private key. / 5
Module.KeysExpirationNotification.CheckInterval / Interval in which the system will search for expired or nearly expiring private keys. The value is in hours. / 24

3.2.7.Message Compression

The messages sent through ECP can be compressed to reduce the amount of data transferred over the network.

The compression is done by the Sender’s Endpoint and can be configured to apply to:

all messages;
all messages of some defined message types;
all messages, except some defined message types.

Note that the recipient’s Endpoint decompresses obtained messages automatically if they are compressed (regardless of this configuration).

Parameter / Description / Default value / Example
Message.Compression.Enabled / Flag enabling or disabling the compression of messages.
Possible values: TRUE, FALSE / FALSE / TRUE
Message.Compression.TypesCompressed / List of message types that are compressed. Other message types aren’t compressed. Types are separated by a semicolon (;). Make sure there are no white characters between types.
This parameter is ignored If Message.Compression.Enabled is set to FALSE.
This parameter can be present only if Message.Compression.TypesSkipped parameter is not used. / - / MESSAGETYPE1;MESSAGETYPE2
Message.Compression.TypesSkipped / List of message types that aren’t compressed. Message types not in this list are compressed. Types are separated by a semicolon (;). Make sure there are no white characters between types.
This parameter is ignored If Message.Compression.Enabled is set to FALSE.
This parameter can be present only if Message.Compression. TypesCompressed parameter is not used. / - / MESSAGETYPE1;MESSAGETYPE2

Example of usage – No messages are compressed:

Message.Compression.Enabled=FALSE

Example of usage - All the messages are compressed:

Message.Compression.Enabled=TRUE

Example of usage – Only messages with types TYPE1 and TYPE2 are compressed:

Message.Compression.Enabled=TRUE

Message.Compression.TypesCompressed=TYPE1;TYPE2

Example of usage – All messages except of types TYPEA and TYPEB are compressed:

Message.Compression.Enabled=TRUE

Message.Compression.TypesSkipped =TYPEA;TYPEB

3.2.8.Message Expiration

ECP can be configured to set an expiration time for the messages. This setting applies to all sent message from this endpoint.

The information about expiration is part of a message. ECP periodically checks the expiration for messages that have not been delivered yet. Such messages are set to "failed".

The setting of this parameter is highly recommended. This prevents messages from hanging in ECP forever. If not configured, there is a risk that messages could become stacked on the Node if the recipient’s Endpoint is disconnected for a longer time (leading to lowering Node performance).

Parameter / Description / Default value / Example
Message.Expiration.Time / Number of hours after which the message will expire unless it is in its final state. Value 0 means that the message will never expire. / 0 / 8

3.2.9.Message Priority

Message priority can be set for message types, enabling the preferential transportation of one message type over another.

The message priority is not part of a message. It can be configured on each ECP modules on the way (sender’s Endpoint, Node, recipient’s Endpoint).

Parameter / Description / Default value / Example
Message.Priority.<X>.Value / Priority value. Default value is 0, a higher value means a higher priority. The value must be an integer. / 0 / / -1 / 2
Message.Priority.<X>.Types / Types to which the priority is assigned. Types are separated by a semicolon (;). Make sure no white characters are present between types. / - / MESSAGETYPE1;MESSAGETYPE2

Notes

For each priority, replace token <X> with the number representing the sequentional order in the configuration file: 0, 1, 2, etc.
Messages whose types are not configured here have a default value of 0.

Example: Type TYPEA has priority 10, type TYPEB has priority 5, Other types have priority 0:

Message.Priority.0.Value=10

Message.Priority.0.Types=TYPEA

Message.Priority.1.Value=5

Message.Priority.1.Types=TYPEB

3.2.10.SSL Configuration on Client Side

The ECP messaging component can be configured for communication with another messaging component by calling Web service over HTTPS. Establishing a HTTPS connection starts with the SSL authentication procedure (SSL handshake), in which both sides introduce themselves. This procedure requires the proper configuration on both sides of communication (client and server).

This chapter describes settings that should be made on the client side. Appropriate settings related to the server side are described in Chapter 4.1 – SSL configuration on the server side.

Parameter / Description / Default value / Example / Other possible values
javax.net.ssl.trustStore / Keystore file, which contains a trusted CA certificate the client uses for the authentication of the server during the SSL authentication procedure. / - / /opt/ecp/ecp_module.jks
javax.net.ssl.trustStorePassword / The password used to protect the integrity of the Keystore. / - / password
javax.net.ssl.keyStore / Keystore file, which contains the client’s SSL certificate used by the client during the SSL authentication procedure. / - / /opt/ecp/ecp_module.jks
javax.net.ssl.keyStorePassword / The password used to protect the integrity of the Keystore. / - / password

3.2.11.Private Key Encryption

The private keys of all certificates are stored in the database. ECP offers a mechanism to secure this important data. The private keys are stored in the database using an AES cipher with 256-bit length key. For more details, see Chapter 6.2– Securing Private Keys in the Database.

Parameter / Description / Default value / Example / Other possible values
Module.Keystore.Encryption.KeyFile / Path to the resource containing the database encryption key. This key is used to encrypt and decrypt all private keys stored in the database. For more details, see Chapter 6.2 – Securing Private Keys in the Database.
The value must be in the following format:
file:[absolute path to the encryption file]
If you want to use the default encryption file, the value should be:
classpath:/defaultEncryptionKey / classpath:/defaultEncryptionKey / file:/opt/encryptionKey

3.2.12.Archiving settings

Setting of archiving prevents from messages congestions within ECP network (in the case that the messages cannot be delivered for some reason).

Parameter / Description / Default value / Example
Module.messageDeleting.Enabled / Allow enabling/disabling message deleting. / - / TRUE
Module.messageDeleting.retentionDays / Number of days after that the message can be deleted. / - / -

3.3.Endpoint Configuration Parameters

3.3.1.Messaging Component Identification

Each messaging component deployed within a module must be assigned a code that is unique in the entire ECP network. Every component also has an additional textual description. This information is used for message routing, logging and tracing purposes.