ECP3.0 Administration Guide - Home

ENTSO-E Energy Communication Platform Administration Guide >1< ENTSO-E Energy Communication Platform Administration guide Un ic or n S ys t em s © 2 0 11 – 20 1 3 Un ic or n S ys t em s a.s . J ank o vc o va 10 3 7/ 4 9, Pr ah a 7 , CZ - 17 0 0 0 Title: ENTSO-E Energy Communication Platform Administration Guide Author: Petr Sochůrek, Stanislav Mikulecký, Michal Ráček, Vlastimil Unucka, Jiří Neuman, Michal Česák, Jiří Dudek, Lukáš Voříšek 3.0.7 10/02/2015 Version: Date: Contact: E-mail: info@unicornsystems.eu Tel.: (+420) 221 400 111 >2< ENTSO-E Energy Communication Platform Administration guide 1. CONTENTS 1. 2. 3. Contents .............................................................................................................3 Revision History .................................................................................................5 ECP Module Configuration ..................................................................................6 3.1. General Instructions ........................................................................................6 3.1.1. Configuration Parameters General Rules ....................................................6 3.1.2. Changing Configurations Steps ..................................................................7 3.1.3. Configuration Parameters – Overview ........................................................7 3.2. Common ECP Module Configuration Parameters .............................................9 3.2.1. Connection to Database .............................................................................9 3.2.2. ECP Module Logging Settings .................................................................. 10 3.2.3. Message Archive Settings ........................................................................ 10 3.2.4. Download Request Signing Settings ......................................................... 11 3.2.5. Connected Endpoint Register Settings ..................................................... 11 3.2.6. Notification of Expiring Keys .................................................................... 12 3.2.7. Message Compression ............................................................................. 12 3.2.8. Message Expiration ................................................................................. 13 3.2.9. Message Priority ...................................................................................... 14 3.2.10. SSL Configuration on Client Side ............................................................. 14 3.2.11. Private Key Encryption............................................................................. 15 3.2.12. Archiving settings .................................................................................... 16 3.3. Endpoint Configuration Parameters ............................................................... 16 3.3.1. Messaging Component Identification ........................................................ 16 3.3.2. Connection to Node ................................................................................. 16 3.3.3. Message Signing Settings ........................................................................ 18 3.3.4. GUI Configuration .................................................................................... 20 3.3.5. Upload/Download Interval Settings ........................................................... 20 3.3.6. Event Manager Settings ........................................................................... 20 3.3.7. ECP Public API – Channel Configuration .................................................. 21 3.3.8. Public API – Receiving Handler Registration ............................................ 23 3.3.9. Public API – Send Handler Registration ................................................... 24 3.4. Node Configuration Parameters ..................................................................... 25 3.4.1. Messaging Component Identification ........................................................ 25 3.4.2. User Authentication ................................................................................. 25 3.4.3. Notification of Certificate Expiration ......................................................... 26 3.5. Registration Component Configuration .......................................................... 26 3.5.1. Node Component Identification ................................................................ 26 3.5.2. Registration Service ................................................................................ 27 3.6. ECP Module Logging..................................................................................... 28 4. Application Server Configuration ....................................................................... 30 4.1. Server-side Networking Port Configuration .................................................... 30 4.1.1. Introduction ............................................................................................. 30 4.1.2. Recommended settings ............................................................................ 30 4.1.3. Enabling HTTPS provided by the ECP Application (server) ....................... 30 4.1.4. Disabling HTTP provided by the ECP Application (server) ........................ 32 4.2. Limiting Access to ECP Web Pages ............................................................... 33 4.3. Securing ECP Application Web Resources .................................................... 34 4.3.1. Purpose ................................................................................................... 34 4.3.2. Built-in Resources Securing ..................................................................... 34 4.3.3. Additional Security Recommendations ...................................................... 35 5. High Availability of ecp application .................................................................... 37 5.1. HA Concept .................................................................................................. 37 5.1.1. Prerequisite ............................................................................................. 37 5.1.2. Installation/Configuration ......................................................................... 37 5.1.3. Integration with business application (BA) ................................................ 37 5.2. Administration Tool Configuration .................................................................. 39 >3< ENTSO-E Energy Communication Platform Administration guide 5.2.1. ECP Guardian ......................................................................................... 39 5.2.2. Geographical Cluster Check ..................................................................... 40 6. Administration Tasks ........................................................................................ 42 6.1. Managing Trusted Certificate Authorities (DSimporter) ................................... 42 6.1.1. Tool Execution and Configuration ............................................................. 42 6.1.2. Operation Description .............................................................................. 44 6.2. Update Node List .......................................................................................... 45 6.2.1. Description .............................................................................................. 45 6.2.2. How to Update Node List File ................................................................... 46 6.2.3. Upload New Node List File ....................................................................... 48 6.3. ECP Certificates Management ....................................................................... 48 6.3.1. ECP Certificates Introduction ................................................................... 48 6.3.2. Issuing NODE CA Certificate.................................................................... 49 6.3.3. Update Certificates for ECP Endpoint ....................................................... 50 6.3.4. Update Certificates for ECP Embedded Endpoint in Node ......................... 55 6.4. Archive Messages in Long-term Storage ........................................................ 56 6.4.1. Structure of Long-term Storage ................................................................ 57 6.4.2. Running MessageArchivation from the Command Line .............................. 58 6.4.3. Running MessageArchivation in the GUI Mode ......................................... 58 6.4.4. Running MessageArchivation on a Regular B asis ..................................... 60 6.4.5. Configuration Parameters ........................................................................ 65 6.4.6. Logging ................................................................................................... 66 6.5. Bandwidth Throttling ..................................................................................... 66 6.5.1. Bandwidth Throttling in General ............................................................... 66 6.5.2. Bandwidth Throttling on Linux .................................................................. 67 7. Monitoring ........................................................................................................ 70 7.1. ECP Module – Monitoring Web Page ............................................................. 70 8. References ....................................................................................................... 74 8.1. Related Documents ....................................................................................... 74 8.2. Web References ........................................................................................... 74 >4< ENTSO-E Energy Communication Platform Administration guide 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 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 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 Vlastimil Unucka, Jiří Updates for ECP 2.0.0. Neuman Petr Zdráhal, Petr Updated for RTE remarks Sochůrek Sections 3.2.12 Archiving settings and 6.4 Update certificates for ECP Node added Sections 4.3 Securing ECP Application Web 3.0.7 10/02/2015 Resources and 5.1 HA Concept added and Lukáš Voříšek section 6.3 ECP Certificates management updated >5< ENTSO-E Energy Communication Platform Administration guide 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 an exclamation mark (!) as the first non-blank character in a line may be used to denote that all of the following text is a comment. 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. >6< ENTSO-E Energy Communication Platform Administration guide Column Description Possible values List all possible values (only if a limited set of values is allowed) / or Example 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: 1. Stop running the ECP Tomcat service (use batch script located in batches/ folder). 2. Modify the module.properties file (located in config/.folder). 3. 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 - Chapter 3.1.3.1 Endpoint Component Configuration - Chapter 3.1.3.2 Node Component Configuration - Chapter 3.1.3.3 Registration Component Configuration - Chapter 3.1.3.4 3.1.3.1. Common ECP Module Configuration This group affects the whole module and includes the configuration of: 1. Connection to database; 2. ECP module logging settings; 3. Message archive setting; 4. Download Request Signing Settings; 5. Connected Endpoint Register Settings; 6. Notification of Expiring Keys; 7. Message compression; 8. Message expiration; 9. Message priority; 10. SSL Configuration on Client Side; >7< ENTSO-E Energy Communication Platform Administration guide 11. 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: 1. Basic configuration of the Endpoint component (its code and description) 2. Message signing Settings 3. GUI configuration 4. Upload/Download Interval Settings 5. Event Manager Settings 6. ECP Public API – Channels Configuration 7. Public API – Receiving Handler Registration 8. Public API – Send Handler Registration 3.1.4. These configuration aspects are further described in Chapter 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). Default Parameter Description Module.messageDeletin Allow enabling/disabling message g.Enabled deleting. Module.messageDeletin Number of days after that the g.retentionDays message can be deleted. - TRUE - - Endpoint Configuration Parameters. 3.1.4.1. Example value Node Component Configuration This group includes: 1. Messaging Component Identification (Node code and description); 2. User Authentication (Credentials for access via the web UI); 3. Notification about Certificates Expiration. >8< ENTSO-E Energy Communication Platform Administration guide To see which parameters can be used to configure the behavior of the Node component, see Chapter 3.4 – Node Configuration Parameters. 3.1.4.2. 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. 1. Node component identification 2. Registration Service To see which parameters can be used to configure the behavior of the Registration component, see Chapter 3.5 – 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 >9< ENTSO-E Energy Communication Platform Administration guide 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.Direc Path to existing directory in which - /tmp/ecp-logs toryPath ECP logs will be stored. > 10 < ENTSO-E Energy Communication Platform Administration guide 3.2.3. Message Archive Settings This affects the way the messages are archived after they have reached the end of their lifecycle. Default value Parameter Description Module.Archive.DisabledTy List of message types that will be pes archived without their content. Example / Other possible values - MESSAGETYPE1;MESSAS SAGETYPE2 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. 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.DownloadReque Implementation of download downloadRequestS / stSigner.Class request signer igner disabledDownloadRequest Signer 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 > 11 < Example ENTSO-E Energy Communication Platform Administration guide Module.EndpointRegiste Time in seconds in which endpoint r.Retention is considered active. If no 600 connection is made by a given endpoint for a specified amount of time, it is deleted from the register of connected endpoints. 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 Module.KeysExpirationN Number of days; the administrator 5 otification.DaysBeforeEx is warned before the expiration of piration a private key. Module.KeysExpirationN Interval in which the system will otification.CheckInterval search for expired or nearly Example 24 expiring private keys. The value is in hours. 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). Default Parameter Description Message.Compres Flag enabling or disabling the compression of sion.Enabled messages. Example value Possible values: TRUE, FALSE > 12 < FALSE TRUE ENTSO-E Energy Communication Platform Administration guide Default Parameter Description Message.Compres List of message types that are compressed. Other sion.TypesCompre message types aren’t compressed. Types are ssed separated by a semicolon (;). Make sure there are Example value - MESSAGETYPE1;ME SSAGETYPE2 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. Message.Compres List of message types that aren’t compressed. sion.TypesSkipped Message types not in this list are compressed. - MESSAGETYPE1;ME SSAGETYPE2 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. 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". > 13 < ENTSO-E Energy Communication Platform Administration guide 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 0 8 expire unless it is in its final state. Value 0 means that the message will never expire. 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>.Va Priority value. Default value is 0, a 0 / -1 / 2 lue higher value means a higher - MESSAGETYPE1;MESSA priority. The value must be an integer. Message.Priority.<X>.Ty Types to which the priority is pes assigned. Types are separated by GETYPE2 a semicolon (;). Make sure no white characters are present between types. 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 > 14 < ENTSO-E Energy Communication Platform Administration guide 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 – Server-side Networking Port Configuration . Parameter Description javax.net.ssl.trustStore Keystore file, which contains a Default Example / Other value possible values - /opt/ecp/ecp_module.jks - password - /opt/ecp/ecp_module.jks - password trusted CA certificate the client uses for the authentication of the server during the SSL authentication procedure. javax.net.ssl.trustStorePassword The password used to protect the integrity of the Keystore. javax.net.ssl.keyStore Keystore file, which contains the client’s SSL certificate used by the client during the SSL authentication procedure. javax.net.ssl.keyStorePassword The password used to protect the integrity of the Keystore. 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 Error! Reference source not found. – Error! Reference source not found.. > 15 < ENTSO-E Energy Communication Platform Administration guide Default value Parameter Description Module.Keystore. Path Encryption.KeyFil database encryption key. This key is used to e encrypt and decrypt all private keys stored in to the Example / Other possible values resource containing the classpath:/default file:/opt/encryptionKey EncryptionKey the database. For more details, see Chapter Error! Reference source not found. – Error! Reference source not found.. 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 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). Default Parameter Description Module.messageDeletin Allow enabling/disabling message g.Enabled deleting. Module.messageDeletin Number of days after that the g.retentionDays message can be deleted. 3.3. Example value - TRUE - - 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. Parameter Description Default value Example Endpoint.Enabled Flag indicating whether the TRUE FALSE Endpoint is enabled (TRUE) or not (FALSE) > 16 < ENTSO-E Energy Communication Platform Administration guide Endpoint.Code Code of endpoint. - 10X1001A1001A094 Endpoint.Description Description of Endpoint - Endpoint 1 component. 3.3.2. Connection to Node Configuration of internal communication channel for connection from Endpoint to Node. Following configuration sets communication via web service: Parameter Description Endpoint.Parent.Enabled Activation status of Default Example / value possible values TRUE / FALSE WS - Other connection to the primary Node Endpoint.Parent.Type Type of channel for connection to the primary Node Endpoint.Parent.Url Endpoint.Parent.RequestTimeout URL to web-service of https://139.49.9.13/ECP_MO the primary Node DULE/services Time after which the WS 30 request times out if no response is received (seconds). Configuration of secondary channel for connection from Endpoint to Node via Web service: Parameter Description Endpoint.Parent.Secondary.Enabled Activation status of Default Example value possible values / FALSE / TRUE WS - Other connection to the secondary Node Endpoint.Parent.Secondary.Type Type of channel for connection to the secondary Node Endpoint.Parent.Secondary.Url URL to web-service of https://139.49.9.2/ECP_MOD the secondary Node ULE/services > 17 < ENTSO-E Energy Communication Platform Administration guide Endpoint.Parent.Secondary.Request Time after which the WS Timeout request times out if no 30 response is received (seconds). See also related issues in chapter 3.2.10 SSL Configuration on Client Side. Configuration of proxy server for connection from Endpoint to Node: Parameter Description Module.proxy.enabled Parameter to indicate Default Example / value possible values FALSE / TRUE Other whether the proxy is to be used TRUE/FALSE Module.proxy.url IP address of proxy 192.168.1.10 server Module.proxy.port Port of the proxy server 8888 Module.proxy.user User to access the proxy user Module.proxy.password Password for the user password 3.3.3. Message Signing Settings These settings allow configuring the Endpoint to sign an outgoing message and verify the signatures of incoming messages. We distinguish two levels of signing:   Signing by standard certificates (specified by MADES; certificates generated during Endpoint registration). Special signing (not specified by MADES; custom certificates). 3.3.3.1. Standard signing Once enabled, the:   sending endpoint will sign all outgoing messages using the standard sender’s signing certificate; receiving endpoint will verify the signatures of all incoming messages using the standard sender’s public signing certificate. Important notice: all communicating endpoints must have this same setting (either enabled or disabled). A receiving endpoint which has standard signing enabled will reject all unsigned messages. > 18 < ENTSO-E Energy Communication Platform Administration guide Parameter Description Default value Endpoint.Signer.Class Allows disabling/enabling standard signing and verification. defaultMessageSigner Possible values:  defaultMessageSigner – signing and verification enabled  disabledMessageSigner - signing and verification enabled It is strongly recommended that signing be kept MADES compliant. 3.3.3.2. Special signing certificates It is possible to configure a specific signing certificate for exchanging messages with a peer Endpoint. Once configured,:   all outgoing messages to the peer are signed using the specific configuration; the signatures of all incoming messages from the peer are verified using the specific configuration. Note that it is necessary to set the symmetric configuration on the peer Endpoint. Important notice: if the recipient has a defined special signing for a sender, it rejects unsigned messages received from that sender. By default this feature is disabled. It is possible to enable it using the following parameter: Parameter Description Endpoint.Signer.0.Class It allows enabling/disabling the special signing and signature verification. Default Example / value possible values specialMessageSigner Each certificate is stored in a separate JKS file and must meet following naming conventions: JKS Keystore naming conventions JKS with a private signing certificate configured on the sender’s side. ReceiverKeystore-<Receiver endpoint code>.JKS JKS with a public signing certificate configured on the recipient’s side. SenderKeystore-<Sender endpoint code>.JKS > 19 < Other ENTSO-E Energy Communication Platform Administration guide Common JKS details are configured using the following parameters: Parameter Description Endpoint.FileKeystore Path to the base directory Provider.Directory where all the special Keystores Default Example value values / Other possible - /opt/ecp/certificates/specialSigning - password - ecp_module_sign are stored. Endpoint.FileKeystore Password protecting the Provider.Password Keystores and the private keys they contain. (All special Keystores must be secured using this password) Endpoint.FileKeystore Alias of the signing certificate in Provider.Alias the Keystores. (All special Keystores must contain a private/public certificate under this alias) 3.3.4. GUI Configuration The configuration of ECP GUI allows the modification of its behavior. Default value Parameter Description Endpoint.MessageListInOu Automatic refresh interval on tbox.Refresh Inbox and Outbox web pages. Example / Other possible values 120000 The value is in milliseconds. 3.3.5. Upload/Download Interval Settings The transport of messages over the ECP network is realized by uploading and downloading between the messaging components. This set of parameters is used to configure the time interval of the upload/download processes on the Endpoint. > 20 < ENTSO-E Energy Communication Platform Administration guide Parameter Description Default value Example Endpoint.TransportTrigger. Delay between application start and the 0 0 / 1000 StartDelay beginning of the message transport 1000 1000 / 0 process. In milliseconds. Endpoint.TransportTrigger. Message transport repeat interval in RepeatInterval milliseconds for Endpoint. When set to 0, the transport process is stopped. 3.3.6. Event Manager Settings The Event Manager is the internal component responsible for distributing internal events within the ECP module. Its settings influence the components listening for events (sending handlers, receiving handlers and FSSF channel). The default values should not be changed. The following parameters can be configured: Default Parameter Description Endpoint.EventManager. Delay in milliseconds between two IterationsDelay distributions of events. Endpoint.EventManager. Delay in milliseconds between EventDeliveryFailureDel attempts to deliver an event whose ay delivery previously failed. Endpoint.EventManager. Maximum number of attempts to AttemptsLimit distribute event to Receiving Example value 500 15000 50 Handlers. 3.3.7. ECP Public API – Channel Configuration The ECP Endpoint provides three types of APIs business applications can use for interaction with ECP. Each API can be switched on/off in the configuration. FSSF (File System Shared Folder) API is the most complex and provides advanced settings. For the specification of the supported types of API, refer to [ECP Public API]. For related examples showing API usage, see [ECP Public API – Usage]. Web-Service Public API: Default value Example Parameter Description Endpoint.ECC.0.Enabled Allows enabling/disabling WS API. TRUE FALSE Endpoint.ECC.0.Type API type WS - / possible values > 21 < Other ENTSO-E Energy Communication Platform Administration guide Notes: The Endpoint exposes public web services for business applications via HTTP. The URL has the following form: http://hostname:<port>/ECP_MODULE/services/ECPEndpointService/. If you want to use HTTPS, see Chapter 4.1 – Server-side Networking Port Configuration . URL has the following form: https://hostname:<port>/ECP_MODULE/services/ECPEndpointService/. JAVA Public API: Default value Example Parameter Description Endpoint.ECC.1.Enabled Allows enabling/disabling Java API. TRUE FALSE Endpoint.ECC.1.Type API type JAVA - / Other possible values FSSF Public API: Default Example value possible values Allows enabling/disabling FSSF API. TRUE FALSE Endpoint.ECC.2.Type API type FSSF - Endpoint.ECC.2.PollInterval Milliseconds between polling out folder. 1000 Endpoint.ECC.2.MessageEve Milliseconds between attempts to write 1000 ntPollInterval events to OUT_LOG. Endpoint.ECC.2.OutgoingDire Folder for messages waiting to be sent. ./OUT/ Endpoint.ECC.2.OutgoingErro Folder where messages rejected by ECP ./OUT_ERROR/ rDirectory will be moved. Endpoint.ECC.2.LogDirectory Folder for messages with logs. Endpoint.ECC.2.LogType Strategy for OUT LOG file creation (one ONE_PER_ log file created for each message/one log MESSAGE Parameter Description Endpoint.ECC.2.Enabled / Other ctory ./OUT_LOG/ ONE_PER_DAY file for each day containing records related to all messages). Endpoint.ECC.2.IncomingDire Folder for received messages. ctory.<X>.Directory > 22 < ./IN/A/ ENTSO-E Energy Communication Platform Administration guide Default Example value possible values / Other Parameter Description Endpoint.ECC.2.IncomingDire Message types received in incoming MESSAGETYPE1;ME ctory.<X>.MessageTypes folder (separated by semicolon). In the SSAGETYPE2 case an empty string is set as the message type value, messages of all types will be received by this incoming directory. Endpoint.ECC.2.Compatibility Set compatibility mode for FSSF file Mode names. OFF OFF = ECP 3 specification, i.e. MADES naming convention. ECP2 = ECP 2.1 specification Notes > If FSSF is enabled, one or more incoming folders must be defined in configuration. Each incoming folder is designated for messages with defined message types. When this type of message arrives at the ECP module of the recipient (endpoint), it is written into the proper incoming folder. Make sure that the same message type is not used more than once. > In the case an empty string is set for a ‘MessageTypes’ parameter, messages of all types will be received into a specified folder. Caution: combining this setting with the specification of any other message receiver (including all types of message receivers) leads to unpredictable behaviour. > For each registered incoming folder, replace token <X> with the number representing the order in the configuration file: 0, 1, 2, etc. > Make sure that both the business applications and the ECP module have read/write access to the IN, OUT, OUT_ERROR and OUT_LOG folders. 3.3.8. Public API – Receiving Handler Registration The concept of custom receiving handlers is described in [ECP Public API]. The following parameters are used for registering a custom receiving handler in the ECP module. Default Parameter Description Endpoint.ReceiveHandle Name of Java class implementing r.<X>.ClassName handler. Endpoint.ReceiveHandle Types of messages the handler r.<X>.Types listens to (separated by semicolon). If Example value an empty value is set, the handler will listen to all messages. Notes > 23 < TRUE eu.unicorn.tst.SimpleAdapter - MESSAGETYPE1; MESSAGETYPE2 ENTSO-E Energy Communication Platform Administration guide > Each registered handler uses a unique parameter name, e.g. replace token <X> with a number representing the order in the configuration file: 0, 1, 2, etc. > In the case an empty string is set to the ‘Types’ parameter, messages of all types will be received by this receiving handler. Caution: combining this setting with the specification of any other message receiver (including all types of message receivers) for explicit message type leads to unpredictable behavior. > Each handler is registered for messages of given types. Make sure that the same message type is not used more than once. > The Java archives containing the handlers must be named as ECP_*.jar, where * represents a sequence of arbitrary characters. In addition, these archives must be put into the WEB-INF/lib directory located either: - inside the ECP_MODULE directory (ECP Endpoint or Node on Windows); - inside the ECP Module’s WAR archive (ECP Node on Linux). This convention is important for preserving the handler after a future upgrade to a higher version of ECP. 3.3.9. Public API – Send Handler Registration The custom send handler concept is described in [ECP Public API]. The following parameters are used for registering the custom send handler in the ECP module. Default Parameter Description Endpoint.SendHandler.< Name of Java class implementing X>.ClassName handler. Endpoint.SendHandler.< Types of messages the handler X>.Types listens to (separated by semicolon). If Example value TRUE eu.unicorn.tst.SimpleAdapter - MESSAGETYPE1; MESSAGETYPE2 an empty value is set, the handler will listen to all messages. Notes > Use a unique parameter name for each registered handler, e.g. replace token <X> with the number representing the order in the configuration file: 0, 1, 2, etc. > The Java archives containing the handlers must be named as ECP_*.jar, where * represents a sequence of arbitrary characters. In addition, these archives must be put into the WEB-INF/lib directory located either: - inside the ECP_MODULE directory (ECP Endpoint or Node on Windows); - inside the ECP Module’s WAR archive (ECP Node on Linux). > 24 < ENTSO-E Energy Communication Platform Administration guide This convention is important for preserving the handler after a future upgrade on higher version of ECP. > 25 < ENTSO-E Energy Communication Platform Administration guide 3.4. Node Configuration Parameters 3.4.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 additional textual description. This information is used for message routing, logging and tracing purposes. Parameter Description Default value Example Node.Enabled Flag indicating whether the Node is TRUE / FALSE - 10X1001A1001A094-MN - Node 1 enabled (TRUE) or not (FALSE) Node.Code Code of Node. Format: [component code of Endpoint]-MN Adding a network standardised extension (e.g. "MN") to the code of the Nodes is recommended so they can be easily identified and not confused with Endpoints. Reminder: no message can be sent using a code such as the receiver code. It will be rejected, since a message can only be sent to an Endpoint (possibly an Endpoint locally installed with a Node), not to a Node. Node.Description Description of Node component. 3.4.2. User Authentication The ECP Node provides restricted access to its GUI only to authorized users after authentication via the log-in page. The following pages are intentionally not restricted:    https://<hostname>/ECP_MODULE/PUBLIC/about.seam (which stand for the default URL) https://<hostname>/ECP_MODULE/PUBLIC/updateForm.seam https://<hostname>/ECP_MODULE/PUBLIC/ADMIN/login.seam > 26 < ENTSO-E Energy Communication Platform Administration guide The user credentials are defined using the following parameters: Parameter Description Default value Example Node.webauthenticati on.<X>.login Username used to log in. - admin Node.webauthenticati on.<X>.password Password login. - password for corresponding Notes > For each authentication a unique login-password pair parameter name must be used. This is achieved by replacing the token <X> with a number representing the order in the configuration file: 0, 1, 2, etc. 3.4.3. Notification of Certificate Expiration The Directory Service, which stores all the certificates of the registered components, is part of the Node. As the certificates are issued only for a limited time period, it is necessary to update them regularly. When any messaging component registered on the Node has either expired certificates or if the expiration date is approaching, the Node administrator is informed. The following parameters modify when the administrator should be notified of the expiration of some certificates. Note: in the case the Node synchronizes with others Nodes, the Directory Service also contains the certificates of the Endpoints registered with others Nodes. A node Administrator is never informed of the expiring certificates of other such Nodes. Parameter Description Default value Node.CertificateExpiratio Number of days, the Node 5 nNotification.DaysBefore administrator is warned of expiring Expiration certificates in advance. Node.CertificateExpiratio Interval in which the system will nNotification.CheckInter search for expired or expiring val certificates. The value is in hours. 3.5. Example 24 Registration Component Configuration 3.5.1. Node Component Identification The Registration Component must contain a basic Node component configuration (Node code and Node description), but the Node.Enabled has to be set to FALSE in the case the Registration Component is deployed at the dedicated application server. > 27 < ENTSO-E Energy Communication Platform Administration guide 3.5.2. Registration Service The Registration Service allows the registration of new Endpoints with the ECP Node. This section describes the configuration parameters that can be changed to modify the behavior of the Registration Service. Parameter Description Node.Registration.Enabled Flag indicating whether the Default Example / Other value possible values TRUE FALSE 2048 1024 - 365 TRUE FALSE - mail.company.eu registration service is enabled (TRUE) or not (FALSE). Node.Registration.GeneratedCertific Length of certificates generated by ate.Length registration service in bits. Node.Registration.GeneratedCertific Time for which generated ECP ate.Validity certificates will be valid. Value is in days. Node.Registration.Notification.Enable Flag indicating whether automatic d email notification of request approval (reject) will be sent. Node.Registration.Smtp.Host SMTP server through which the email notifications will be sent. Node.Registration.Smtp.Port Port on which SMTP server is 25 running. Node.Registration.Smtp.Username Username used to log in to the - johnSmith - password - Registration request SMTP server. If empty, an attempt to log in anonymously will be made. Node.Registration.Smtp.Password Password used to log in to the SMTP server. Node.Registration.Notification.Appro Subject of email message sent ved.Subject automatically after registration approved. request approval. Node.Registration.Notification.Appro Text of email message sent ved.Text automatically after registration has been approved by request approval. ECP administrator. Node.Registration.Notification.Reject Subject of email message sent ed.Subject automatically after registration request rejection. > 28 < - - Your registration request Registration request rejected. ENTSO-E Energy Communication Platform Administration guide Default Example value possible values / Other - Your registration request Parameter Description Node.Registration.Notification.Reject Text of email message sent ed.Text automatically after registration has been rejected by the request rejection. ECP administrator. Node.Registration.Contact.Email Sender email address used for - automatic email notification. This WhoToContant@compa ny.eu information is also written into the metadata of generated certificates. Node.Registration.Contact.Person Sender Name used for automatic - John Smith email notification. This information is also written into the metadata of generated certificates. 3.6. ECP Module Logging Logging is configured separately for each key ECP component running within the ECP module. The settings are stated in log4j properties files, which are included in the deployed module archive (WAR) in the following paths: > WEB-INF\classes\eu\unicorn\ecp\base\logger\log4j.properties > WEB-INF\classes\eu\unicorn\ecp\edclient\logger\log4j.properties > WEB-INF\classes\eu\unicorn\ecp\mclient\logger\log4j.properties > WEB-INF\classes\eu\unicorn\ecp\node\logger\log4j.properties > WEB-INF\classes\eu\unicorn\ecp\ds\log4j.properties Example: #Set application loggers log4j.logger.eu.unicorn.ecp.node=ERROR, CONSOLE_MN, LOGFILE # CONSOLE is set to be a ConsoleAppender using a PatternLayout. log4j.appender.CONSOLE_MN=org.apache.log4j.ConsoleAppender log4j.appender.CONSOLE_MN.layout=org.apache.log4j.PatternLayout log4j.appender.CONSOLE_MN.layout.ConversionPattern=MN [%p] [%t] %d %m%n # LOGFILE is set to be a File appender using a PatternLayout. log4j.appender.LOGFILE=org.apache.log4j.RollingFileAppender log4j.appender.LOGFILE.Threshold=ERROR log4j.appender.LOGFILE.File=${Module.EcpLogger.DirectoryPath}/ecp_mn.lo g log4j.appender.LOGFILE.Append=true log4j.appender.LOGFILE.layout=org.apache.log4j.PatternLayout > 29 < ENTSO-E Energy Communication Platform Administration guide log4j.appender.LOGFILE.layout.ConversionPattern=%d [%t] %-5p %c %x - %m%n log4j.appender.LOGFILE.MaxFileSize=2048KB log4j.appender.LOGFILE.MaxBackupIndex=30 Notes: > By default, each component uses its own log file. The files are stored in the directory set by the ECP configuration parameter: Module.EcpLogger.DirectoryPath. - Only errors are logged in the log file by default. The log file is rotating, which means that once the maximum size of a log file is reached, it is renamed (to have a number extension) and kept for backup reasons. A new empty log file is then created to be used for further logging. If the maximum number of backup log files is reached, the oldest one is removed. - property log4j.appender.LOGFILE.MaxFileSize defines the maximum size of the one log file. - property log4j.appender.LOGFILE.MaxBackupIndex defines the maximum number of backup log files. > 30 < ENTSO-E Energy Communication Platform Administration guide 4. APPLICATION SERVER CONFIGURATION 4.1. Server-side Networking Port Configuration 4.1.1. Introduction The ECP application is deployed in the Tomcat application server, which acts as an HTTP/HTTPS server providing: - web services (called by business applications and other ECP modules); - a web interface (used by ECP Administrators). All these resources are available through networking HTTP and/or HTTPS ports defined in the Tomcat configuration file - <ECP_BASE>/container/conf/server.xml This file contains a “connector” definition for each port that the Tomcat listens on. Note that through each opened port all the resources (web services, web interface) are made accessible to clients. 4.1.2. Recommended settings After the ECP application (ECP Endpoint or ECP Node) is installed, the support for HTTPS is disabled by default, which: > is suitable for the ECP Endpoint; > is not suitable for the ECP Node (MADES specification requires that communication from ECP Endpoint to ECP Node uses HTTPS). Thus, it is strongly recommended that the networking configuration of the ECP Node be changed to provide only an HTTPS networking port. Follow the instructions in chapters: > Chapter 4.1.3 – Enabling HTTPS provided by the ECP Application (server) > Chapter > – Disabling HTTP provided by the ECP Application (server) > Disabling HTTP provided by the ECP Application (server) 4.1.3. Enabling HTTPS provided by the ECP Application (server) To enable HTTPS, add the new connector to the file <ECP_BASE>/container/conf/server.xml (this section is present in server.xml and can be uncommented): Example: <Connector port="443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" > 31 < ENTSO-E Energy Communication Platform Administration guide scheme="https" secure="true" sslProtocol="TLS" keystoreFile="/opt/ecp/certificates/ecp_module.jks" keystorePass="password" keyAlias="ecp_module_auth" clientAuth="false" truststoreFile="/opt/ecp/certificates/ecp_module.jks" truststorePass="password" ciphers="SSL_RSA_WITH_RC4_128_MD5, SSL_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA, SSL_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA" /> Parameter Description port Network port on which the connector Default Example value possible values / 443 8443 Other listens for incoming connections. protocol Mandatory value. HTTP/1.1 - SSLEnabled Mandatory value. true - maxThreads The maximum number of simultaneous 150 - requests that can be handled. scheme Mandatory value. https - secure Mandatory value. true - sslProtocol The version of the SSL protocol to use. TLS - keystoreFile The pathname of the Keystore file where - /opt/certificates/ecp_modul the server certificate is stored. keystorePass The password to access the server e_cert.jks - password The alias used to for the server certificate ecp_module_ - in the Keystore. If not specified, the first auth certificate from the specified Keystore. keyAlias key read in the Keystore will be used. clientAuth Set to true if you want the SSL stack to false true - /opt/certificates/ecp_modul require a valid certificate chain from the client before accepting a connection. truststoreFile The TrustStore file to use to validate client certificates. truststorePass e_cert.jks The password to access the truststore. > 32 < - password ENTSO-E Energy Communication Platform Administration guide Parameter Description ciphers The comma-separated list of encryption Default Example value possible values / Other - ciphers that this socket is allowed to use. By default, the default ciphers for the JVM will be used. Note that this usually means that the weak export grade ciphers will be included in the list of available ciphers. The ciphers are specified using the JSSE cipher naming convention. The list of strong ciphers is described in the connector example above. Notes > The authentication of the client by the server during the SSL handshake is optional when using Tomcat. Note that this type of authentication is not required by ECP, because the authentication is done at a functional level using a token as described in the MADES specification. > For a complete description of the connector settings, see http://tomcat.apache.org/tomcat-6.0- doc/config/http.html. > Appropriate SSL settings related to the client side are described in Chapter 3.2.10 – SSL Configuration on Client Side. 4.1.4. Disabling HTTP provided by the ECP Application (server) By default, the Tomcat application server provides access to its resources (web services, web pages, etc.) via HTTP using port 8080, even when the HTTPS access is enabled (see Chapter 4.1.3).This section describes how to disable this non-secured access. Endpoint The HTTP access may probably not be disabled for Endpoints where no special security requirements are applied, since they are typically located on the same machine or LAN segment as the business applications (BA). In the case HTTP is disabled, access to the ECP Web pages by the administrator and to the web services by the BA will then have to use the HTTPS protocol. In this situation:  the default server certificate for the SSL protocol is the Endpoint authentication certificate received from the registration;  all BAs have to verify and trust the corresponding certificate chain;  the administrator has to insert the ECP network root certificate in his browser to avoid the security warning. > 33 < ENTSO-E Energy Communication Platform Administration guide Node Enabling HTTP on the Nodes represents a potential security hole. HTTP accesses can then be disabled by filtering network ports on the infrastructure firewalls, if they exist. HTTP can be also disabled on the application server by commenting out the HTTP connector in the application descriptor server.xml file: <!-<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="443" /> --> Note that if a local Endpoint has been installed/enabled with the Node, the HTTP access to this Endpoint is also disabled with the previously described consequences. 4.2. Limiting Access to ECP Web Pages By default, access to the ECP Endpoint’s web pages is allowed to an anonymous user. However, it may be desirable to protect access to web pages from unwanted visitors for security reasons. This can be done using the basic authentication mechanism provided by the Tomcat application server. In order to limit access to web pages on Tomcat, follow these steps: 1. Edit the tomcat-users.xml located in directory $TOMCAT_HOME/conf in any text editor and add the following lines under <tomcat-users> element. You may change any value to suite your needs. <role rolename="ECPAdmin"/> <user username="admin" password="password" roles="ECPAdmin"/> 2. Edit web.xml located in ECP_MODULE/WEB-INF directory and add the following lines under the root <web-app> element. If you change the rolename in <role> element in the previous step, you must substitute “ECPAdmin” for the rolename of your choice. <security-constraint>  <web-resource-collection> <web-resource-name> Entire Application </web-resource-name> <url-pattern>*.seam</url-pattern> </web-resource-collection>  <auth-constraint> <role-name>ECPAdmin</role-name> </auth-constraint> </security-constraint>  <login-config> > 34 < ENTSO-E Energy Communication Platform Administration guide <auth-method>BASIC</auth-method> <realm-name>Client Admin Area</realm-name> </login-config> 3. Restart Tomcat to apply the changes. The configuration used in this example limits access to all ECP web pages. To access any page, a user must enter a correct username (admin) and password (password). Access can be limited to only some pages by changing the value of <url-pattern> to match your requirements. 4.3. Securing ECP Application Web Resources 4.3.1. Purpose ECP application is a web application running on HTTP server (Tomcat). Its front-end part provides resources over http protocol. Since ECP application may be exposed to Internet (typically when configured as a Node), or into local network (typically when configured as an Endpoint), it is highly desired to correctly secure access to their resources. The ECP application is composed by three modules which provide web resources as shown on picture. ECP Application Node module GUI module Web services Screens Endpoint module Web services These resources are subject of securing and are further discussed below. Note that Node module and Endpoint module can be disabled by configuration. Once disabled, its security is not an issue. 4.3.2. Built-in Resources Securing This chapter gives details of exposed web resources, and presents the way of their built-in securing. > 35 < ENTSO-E Energy Communication Platform Administration guide 4.3.2.1. GUI Provides to user screens with  Endpoint functionalities - sending and receiving messages  Node functionalities - managing registrations and linkage to other nodes  Management functionalities - monitoring application status Built-in access securing:  If Node module is enabled, the access to GUI is protected via form authentication (with login and password).  If Node module is disabled, access to GUI is not protected at all. 4.3.2.2. Node Module This module exposes following web services  Authentication Service  Messaging Service  Directory Service  Node Synchronization Service Built-in access securing:  Access to Authentication Service, Messaging Service, and Directory Service is provided only to Endpoints after their authentication (authentication mechanism is defined by Mades).  Access to Node Synchronization Service is not secured. It is not security issue since the service provides only not-security sensitive read-only data. 4.3.2.3. Endpoint Module Provides web service (public API) allowing the Business applications to send messages, receive messages, and check messages status. Built-in access securing: Access is not secured. 4.3.3. Additional Security Recommendations 4.3.3.1. Prevention from brute-force attack The ECP application doesn’t contain means to defend against possible brute-force attack for the sake of stealing credentials. > 36 < ENTSO-E Energy Communication Platform Administration guide As a prevention it is recommended to use strong passwords policy - for both basic authentication and form authentication. 4.3.3.2. Securing access to not-secured Endpoint resources Following resources are not secured by default  Web services (public API) provided by Endpoint module  GUI screens (when operating standalone Endpoint) There are following recommended way to secure them:  Protect access by HTTP basic authentication (at Tomcat level configuration).  Allow access to them only from defined machine (at firewall level).  Configure Endpoint to authenticate clients with trusted SSL client certificate. 4.3.3.3. Prevention from DOS attack to Node Node is typically available over Internet and thus may be subject to DOS attack. As a prevention, it is recommended to configure SSL client authentication on the Node (Tomcat). Then, Endpoints will automatically provide authentication certificate which they already own. The authentication certificate was distributed to them during Endpoint registration. 4.3.3.4. Defining access restrictions for resources per networking ports ECP Application can provide its resources by one or more ports (configurable on Tomcat level), but it does not allow to specify, which resources are available via which networking port. Simply, all resources are available via all ports. If there is requirement for such resource-per-port splitting, it should be done at the web-server level (e.g. via Apache Webserver). > 37 < ENTSO-E Energy Communication Platform Administration guide 5. HIGH AVAILABILITY OF ECP APPLICATION 5.1. HA Concept This chapter describes the recommended ways for configuration of ECP Endpoint for high availability. The solution leverages the ability of ECP Endpoint to run concurrently in more instances, forming one logical application cluster. Each instance is running on separate machine, while sharing the same database. Note that the ECP Endpoint cluster does not bring any performance improvement, it is just to avoid SPoF. 5.1.1. Prerequisite There exist external (in-house) database engine which is configured to be high available. Note that scenarios described in this chapter take into account using of ReceiveHandler for receiving messages. 5.1.2. Installation/Configuration During the installation/registration, the external database engine is used as a location for ECP schema. ECP Endpoint applications are installed on separate machine. And all of them are equally configured. It means: 1. 2. 3. 4. 5. 6. They use the same configuration (module.properties). They use the same certificate file (ecp_module.jks). They use the same database schema. They have network visibility to all ECP Nodes which form ECP network. They have deployed ReceiverHandlers. They must be able to pass messages to the Business Application. All instances of ECP Endpoint have network visibility to ECP Node. 5.1.3. Integration with business application (BA) There are two possible integration ways one uses intermediate load balancer, the second way is without load balancer. 5.1.3.1.   Using Intermediate Load Balancer This scenario expects to install load balancer between BA and ECP Endpoints. BA sends messages via load balancer (which hides the ECP Endpoint instances). > 38 < ENTSO-E Energy Communication Platform Administration guide  Both ReceiveHandlers need to have visibility to BA so that they are able to pass received messages to it (using ReceiveHandler). 5.1.3.2.    Without Intermediate Load Balancer This scenario expects that both IPs of both ECP Endpoints are known by BA and BA has implemented possibility for switching between these IPs if one of them becomes unavailable (in fact it behaves like simple load balancer). BA sends message into arbitrary ECP Endpoint Both ReceiveHandlers need to have visibility to BA so that they are able to pass received messages to BA (using ReceiveHandler). > 39 < ENTSO-E Energy Communication Platform Administration guide 5.2. Administration Tool Configuration 5.2.1. ECP Guardian The ECP Guardian is a daemon which guards if the ECP Module is online, and in the event of any troubles, it restarts the ECP Module. It is a simple Java-based administration utility provided together with the ECP platform. 5.2.1.1. Tool Execution The tool is not executed automatically. Execute this tool manually after ECP is started and shut it down before ECP is shut down. The tool is located in the $ECP_HOME/tools/ECPGuardian directory. If you are using the ECP Node on a Linux installation or upgrade package for Linux Node, you can find the tool inside the $PACKAGE_HOME/install/tools/ECPGuardian directory. Before execution, it is necessary to change the directory to the tool’s directory. The tool can be executed by the following command: $JAVA_HOME/bin/java -jar ECPGuardian.jar The tool can be shut down using the common operation system tools. 5.2.1.2. Tool Configuration ECP Guardian is configurable via the ecpguardian.properties file. Parameter Description ip IP address to check, i.e the ECP running IP address. ssl Defines if the web service will be called via SSL. Possible values true/false. If yes, Keystore and keystore_pass parameters must also be configured. heartbeat_interval Time between trials (seconds). trials_to_restart Count of incorrect results in a row to restart the module. sleep_after_restart Sleep time after executing restart script (seconds). keystore Path to Keystore jks file. Keystore_pass Keystore password. > 40 < ENTSO-E Energy Communication Platform Administration guide 5.2.2. Geographical Cluster Check ECP supports the deployment of the Node as a geographic cluster. This means that Node is deployed at two synchronized sites and the Endpoints use one of them depending on their availability. 5.2.2.1. Tool Execution The tool is not executed automatically, and it is therefore recommended that the statup scripts of your ECP Node be edited. The tool is located in the $ECP_HOME/tools/GEOChecker directory. If you are using the ECP Node on an Linux installation or an upgrade package for Linux Node, you can find the tool inside the $PACKAGE_HOME/install/tools/GEOChecker directory. Before the execution it is necessary to change the directory to the tool’s directory. The tool can be executed by the following command: $JAVA_HOME/bin/java -jar GEOChecker.jar The result code of the execution is 0 when a geographical partner is not running and 1 when a geographical partner is running. You can use the following patterns for including GEOChecker in your startup scripts: Usage on the Linux platform: cd <path to GEOChecker> $JAVA_HOME/java –jar GEOChecker.jar if [$? = 1 ]; then return fi <<START APPLICATION SERVER>> Usage on the Windows platform: @cd <path to GEOChecker> @%JAVA_HOME%/java -jar GEOChecker.jar @if errorlevel 0 goto :ok @exit :ok <<START APPLICATION SERVER>> > 41 < ENTSO-E Energy Communication Platform Administration guide 5.2.2.2. Tool Configuration GEO Checker is configurable via the geochecker.properties file. Parameter Description ip IP address to check whether ECP is running on this IP address. ssl Defines if web service will be called via SSL. Possible values true/false. If yes, Keystore and Keystore_pass parameters must also be configured. keystore Path to keystore jks file. Keystore_pass Keystore password. > 42 < ENTSO-E Energy Communication Platform Administration guide 6. ADMINISTRATION TASKS 6.1. Managing Trusted Certificate Authorities (DSimporter) The ECP Node’s trusted certificate authorities can be managed using the Directory Service importer tool. The Directory Service importer is a tool whose main purpose is to manage the Directory Service from the command line. Although it provides a wide range of functions, the use of all of them is not recommended; undocumented operations are used during ECP installation and upgraded by scripts. It is recommended that only the following operations described in this document be used: > Add an external certificate authority into the node’s trusted certificate authorities. > Show the list of trusted certificate authorities. > Disable a trusted certificate authority. > Enable a trusted certificate authority. 6.1.1. Tool Execution and Configuration 6.1.1.1. Tool Execution The tool is located in the $ECP_HOME/tools/DSImporter directory. If you are using the ECP Node on a Linux installation or an upgrade package for Linux Node, you can find the tool inside the $PACKAGE_HOME/install/tools/DSImporter directory. Before execution, it is necessary to change the directory to the tool’s directory. The tool can be executed by the following command: $JAVA_HOME/bin/java -jar DSImporter.jar [operation] [operation parameteres] Supported operations: Operation nothing Description Shows the list of all possible operations and brief help for each of them. Without parameter - Shows the list of possible operations and brief help for each of them. -help With operation name (without leading - ) as parameter – Shows a brief description of the operation. -importCA -listCA Adds a new certificate authority to the Node trusted certificate authorities. Shows the list of trusted certificate authorities of the Node. > 43 < ENTSO-E Energy Communication Platform Administration guide Operation Description -disableCA Disables a trusted certificate authority. -enableCA Enables a trusted certificate authority. If the operation is executed successfully, the last line of the command output will look like this: [INFO] Operation executed successfully. In the case that the operation failed, the command output will contain a brief error description. Details may be found in DSImporter.log. 6.1.1.2. Tool Configuration Some parameters can (DSImporter.properties). be configured Parameter Database Database.Driver Database.Dialect Database.Password Node.Code in the general configuration file for the tool Description The configuration of this parameter is described in Chapter 3.2.1 – Connection to Database. The configuration of this parameter is described in Chapter 3.2.1 – Connection to Database. The configuration of this parameter is described in Chapter 3.2.1 – Connection to Database. The configuration of this parameter is described in Chapter 3.2.1 – Connection to Database. Code of the node component. Code of the endpoint component. Set up only if an Endpoint.Code endpoint component is deployed together with the node. Path to the resource which contains the database encryption key. This key is used to encrypt and decrypt all private keys stored in the database. For details, see Chapter Error! Reference source not found. – Error! Reference source not found.. more Module.Keystore.Encryption.KeyFile 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 following value should be used: file:defaultEncryptionKey > 44 < ENTSO-E Energy Communication Platform Administration guide 6.1.2. Operation Description 6.1.2.1. Import New Certificate Authority "Import new certificate authority" operation adds an external certificate authority to the Node’s trusted certificate authorities. Mandatory parameters are: Parameter Description Path to the JKS keystore which contains the store <path> external certificate authority certificate. storePass <password> alias <alias> Password to the JKS Keystore which contains the external certificate authority certificate. Alias of the external certificate authority certificate. Example: $JAVA_HOME/bin/java -jar DSImporter.jar -importCA -store /opt/eCA.jks - storePass password -alias thawte This operation performs a wide range of checks, and it is not possible to import an invalid certificate or to import the same certificate twice. 6.1.2.2. Show List of Trusted Certificate Authorities The "Show list of trusted certificate authorities" operation shows a table with all trusted certificate authorities of the current Node. This operation also shows the IDs of all certificate authorities. The ID of a certificate is required to execute an enable or disable certificate authority operation. "Show list" operation requires no parameter. Example: $JAVA_HOME/bin/java -jar DSImporter.jar -listCA 6.1.2.3. Disable Certificate Authority The "Disable certificate authority" operation disables an external certificate authority. In the case that a certificate authority is disabled, no certificate issued by this certificate authority can be used in ECP. This operation requires the ID of the certificate authority as a parameter. Example: $JAVA_HOME/bin/java -jar DSImporter.jar –disableCA 10 > 45 < ENTSO-E Energy Communication Platform Administration guide Note that only the external certificate authorities can be disabled. 6.1.2.4. Enable Certificate Authority The "Enable certificate authority" operation re-enables a previously disabled external certificate authority. When the disabled certificate authority is enabled, the certificates issued by this certificate authority can be used again in ECP. This operation requires the ID of the disabled certificate authority as a parameter. Example: $JAVA_HOME/bin/java -jar DSImporter.jar –enableCA 10 6.2. Update Node List 6.2.1. Description The information about an added or removed Node to all Node administrators is published by the ECP Network Administrator, who has the overview of all Nodes and their administrators. A single file containing information about all Nodes in the ECP network is used for the transmission of information about all ECP Nodes. This file is called the “Node List file”. The following step must be performed if a new node is to be connected to the ECP Network: I. [1] The Node Administrator requests the ECP Network Administrator to update the Node List file. II. The ECP Network Administrator approves the request and changes to the Node List file. III. The ECP Network Administrator creates a backup of the current Node List file. > 46 < ENTSO-E Energy Communication Platform Administration guide IV. The ECP Network Administrator updates the current Node List file according to the Node Administrator request (see Chapter 6.2.2 – How to Update Node List File). V. The ECP Network Administrator uploads the updated Node List file into its own Node to verify its validity (see Chapter 6.2.3 – Upload New Node List File). VI. [2] The ECP Network Administrator sends the Node List file to all Node Administrators. VII. [3] All nodes synchronize with the new Node. 6.2.2. How to Update Node List File The Node Administrator only uploads the Node List file received from the ECP Network Administrator (see Chapter 6.2.3 – Upload New Node List File) to the ECP. The following instructions are for the ECP Network Administrator: 6.2.2.1. Description of Node List File Name Description Node component code Code of the Node component. Primary Node URL Primary Node URL in format according to RFC 1738 . Secondary Node URL Secondary Node URL in format according to RFC 1738. Format of the Node list file: > File must be in UTF-8 encoding. > Each Node record is delimited by the new line character (LF U+000A). > Each attribute in the Node record is delimited by an empty space character (SPACE U+0020) for the preceding and following attribute. > Attributes must be stored in the Node record in the following order: - Node component code - Primary Node URL - Secondary Node URL Example of Node list file: Node-1-MN https://192.168.80.176:443/ECP_MODULE/services Node-2-MN https://192.168.80.177:443/ECP_MODULE/services https://192.168.80.178:443/ECP_MODULE/services > Node component with name “Node-1-MN” has only a primary URL. > Node component with name “Node-2-MN” has a primary URL and secondary URL. > 47 < ENTSO-E Energy Communication Platform Administration guide 6.2.2.2. Add New Node 1. Open file with the current Node List (e.g. current-node-list.conf) in the Unicode editor (PSPad, etc.). 2. Add a new NODE at the end of the file according a specification: - Name of Node component - Primary Node URL - Secondary Node URL (optional for Node Administrator) 3. Save as new Node list file (e.g. actual-node-list.conf). Example of new node list file after node with name “Node-3-MN” was added: Node-1-MN https://192.168.80.176:443/ECP_MODULE/services Node-2-MN https://192.168.80.177:443/ECP_MODULE/services https://192.168.80.178:443/ECP_MODULE/services Node-3-MN https://192.168.80.179:443/ECP_MODULE/services 6.2.2.3. Remove Node 1. Open file with the current Node List (e.g. current-node-list.conf) in the Unicode editor (PSPad, etc.). 2. Remove required [Node] from the file. Delete the following for the node with name [Node] from the Node List file: - Name of Node component - Primary Node URL - Secondary Node URL (if existing) 3. Save as new Node list file (e.g. actual-node-list.conf). Example of new node list file after node with name “Node-2-MN” was removed: Node-1-MN https://192.168.80.176:443/ECP_MODULE/services Node-3-MN https://192.168.80.178:443/ECP_MODULE/services 6.2.2.4. Update Node 1. Open the file with the current Node List (e.g. current-node-list.conf) in the Unicode editor (PSPad, etc.). 2. Find the required [Node] and update the file according to the request. Update the following: - Name of Node component - Primary Node URL - Secondary Node URL (if existing) 3. Save as new Node list file (e.g. actual-node-list.conf). Update of the current Node list when a secondary URL is requested. > 48 < ENTSO-E Energy Communication Platform Administration guide Example of new Node List file after a node named “Node-1-MN” was updated (secondary URL was added): Node-1-MN https://192.168.80.176:443/ECP_MODULE/services https://192.168.80.177:443/ECP_MODULE/services Node-3-MN https://192.168.80.178:443/ECP_MODULE/services 6.2.3. Upload New Node List File Log in to the ECP Node as the Node administrator and click on the Node list menu item. Click on the button Update list on the Directory Service page - Node List. The following page will be displayed: Click on the Browse button and find the file with the new Node List. Click on the Update button. Node list was updated and Directory Service - Node List was displayed. Click on the Synchronize button below the header “Other known Nodes” on the bottom of the page. It may happen that Directory Service is locked due to background synchronization. If this situation occurs, the system will show the following error: "Directory service objects may be locked by the background synchronization process. Please repeat the update later." The Directory Service is successfully synchronized if all nodes have green flags in the column “Sync successful”. In the case of an error, a message will be displayed on the monitoring page. 6.3. ECP Certificates Management 6.3.1. ECP Certificates Introduction In general, ECP Network is composed by one or more interconnected ECP NODEs. Each ECP Node serves as a gateway into ECP Network for its child Endpoints. Thus arbitrary two ECP Endpoints can exchange messages. The security of data exchanges between Endpoints is ensured by certificates. For ECP we distinguish following certificates. > 49 < ENTSO-E Energy Communication Platform Administration guide 1. ROOT CA Certificate - Root certificate for the whole ECP Network, owned by ECP Network Administrator. It is used for issuing NODE CA Certificates. 2. NODE CA Certificate - Intermediate CA certificate which is installed into ECP Node application. It is used for issuing Endpoint certificates. 3. Endpoint Certificates - Certificates are used for secure message exchange (encryption certificate), trustful message exchange (signing certificate), and authentication of Endpoint by NODEs. 6.3.2. Issuing NODE CA Certificate All the steps are done by ECP Network Administrator at his environment. 6.3.2.1. Prerequisites > Available ROOT CA Certificate - as two files: PKCS #8 private key file and Certificate file (both in PEM format). > Available Linux machine dedicated for issuing NODE certificates. - Machine contains issuing script configured to use ROOT CA certificate. - The whole machine is periodically archived (or at least the script configuration and all t he generated outputs). > Available machine with installed KeyToolExplorer utility. 6.3.2.2. Generating NODE CA Certificate Steps done on dedicated Linux machine with issuing script installed. 1. Configure issuing script - set attributes of the Node certificate to generate (such as Organization, Name, Email) 2. Execute issuing script to generate NODE (intg) certificate as two files - PKCS #8 private key and Certificate file (both in PEM format) 6.3.2.3. Assembling keystore Steps done on machine where is available KeyToolExplorer utility. 1. 2. 3. 4. Execute KeyToolExplorer utility Create empty ecp_module.jks Import root certificate CA file into ecp_module.jks Import generated NODE certificate into ecp_module.jks 6.3.2.4. Archiving keystore Archive generated ecp_module.jks into local safe storage. > 50 < ENTSO-E Energy Communication Platform Administration guide 6.3.2.5. Distribute keystore Distribute ecp_module.jks file to relevant ECP Node Administrator via safe channel. 6.3.3. Update Certificates for ECP Endpoint 6.3.3.1. Description > The ECP Endpoint Administrator creates an update request (see Chapter 6.3.3.2.1) > The EPC Node Administrator approves it (see Chapter 6.3.3.2.2) > The ECP Endpoint Administrator installs new certificates and private keys for the messaging component (see Chapter 6.3.3.2.3) > 51 < ENTSO-E Energy Communication Platform Administration guide 6.3.3.1.1. Update Certificates Using the Integrated Authority: > 52 < ENTSO-E Energy Communication Platform Administration guide 1. The Endpoint Administrator creates a request for updating certificates using the “Update form” function in the web interface of a home ECP Node. 2. The Endpoint Administrator sends the certificate request to the Node Administrator. The transport channel is not provided by ECP. 3. The Node Administrator approves the request using the “Approve update” function. 4. The Node Administrator sends the update result (i.e. the certificates) to the Endpoint Administrator. The transport channel is not provided by ECP. 5. The Endpoint Administrator imports the certificate using the “Update Certificates” function of the Endpoint. > 53 < ENTSO-E Energy Communication Platform Administration guide 6.3.3.1.2. Update Certificates Using an External Authority 1. The Endpoint Administrator gets obtains the new certificate from the External Certificate Authority if they do not want certificates to be issued by the integrated certificate authority of the home Node. Note that the authentication certificate always has to be issued by the Node’s integrated certificate authority. 2. Continue with step one in the update certificate using the integrated authority. > 54 < ENTSO-E Energy Communication Platform Administration guide 6.3.3.2. How to Update Certificates 6.3.3.2.1. Create the Certificate Update Request The Endpoint Administrator (referred to hereinafter as “the user”) creates an update request: connect to the Node web interface (go to URL of NODE), click on the menu item “Update certificates” and complete the Update form. 1. The user fills in the following fields: - Component code (the code of Endpoint) - Organization - Contact person - Contact e-mail - Contact phone - Signing private/public key (optional*) - Encryption private/public key (optional*) - Authentication private/public key (optional*) * If the user does not enter certificates, the system generates new certificates and private keys. 2. The user submits the form by clicking on the “Submit update” button. 3. The user downloads from the Web interface and stores the temporary private Keystore file (ecp_module_priv.jks) and the update request (ecp_update_request.dat) into a selected local folder. 4. The user sends the Update request file (ecp_update_request.dat) to the ECP Node Administrator via an external communication channel (email, etc.) 6.3.3.2.2. Approve the Certificate Update Request The ECP Node Administrator approves the update certificate request from the Endpoint Administrator and modifies data in the Directory Service. 1. The Node administrator logs in to the ECP and clicks on the “Approve update” menu item. 2. The Node administrator fills in following fields: > 55 < ENTSO-E Energy Communication Platform Administration guide - Component code – code of the Endpoint to update; - Active since – the date on which the updated certificates become valid. - The certificate update request – the request file sent by the Component Administrator (file ecp_update_request.dat). 3. The Node administrator downloads and stores the update result. 4. The Node administrator sends the Update request result file (ecp_update_response.dat) to the ECP Component Administrator via an external communication channel (email, etc.) 6.3.3.2.3. Update Certificates on the component The component Administrator (hereinafter “the user”) updates the certificates which were approved by the Node Administrator. 1. The user logs in to his own ECP and clicks on the Update certificates menu item. 2. The user fills in the following fields: - Private key set – the private key set (ecp_module_priv.jks) which is output of the Create update request UC. - Certificate update result – the file (ecp_update_response.dat) obtained from the Node Administrator. 3. The user submits the form by clicking on the “Update” button. 4. The interface displays the message “Certificates were updated”. The New private keys are inserted into the Keystore and the authentication key store is updated according to the update result. 6.3.4. Update Certificates for ECP Embedded Endpoint in Node > 56 < ENTSO-E Energy Communication Platform Administration guide This chapter describes alternative procedure for updating certificates of Endpoint which is embedded in Node. It cannot be used for standalone Endpoint. All steps have to be done on the Node's application server, no changes on child Endpoints are needed. 1. Shutdown ECP Node's tomcat 2. From ./ecp/certificates/ecp_module.jks delete following records:  ecp_module_auth  ecp_module_sign  ecp_module_encr 3. In ant script ./ecp/tools/DSImporter/setup_ds.xml modify very first target "setupDS" so that its content is:    <antcall target="issueCertificates" /> <antcall target="importCertificate" /> <antcall target="importKeys" /> 4. In ./ecp/tools/DSImporter/DSImporter.properties change value of property Node.Registration.GeneratedCertificate.Validity to reasonable time  e.g. 10 years  Node.Registration.GeneratedCertificate.Validity=3650 5. Delete following logs:  ./ecp/tools/DSImporter/*.log  ./ecp/tools/DSImporter/logs/*.log 6. Execute following command:  ./ecp/tools/setup_ds.sh 7. Check that created logs don't contain errors 8. Startup ECP Node's tomcat 9. Check that Monitoring page doesn't contain error messages and that the "Registered certificates" shows the Auth, Encr and Sign certificates with correct expiry dates. 6.4. Archive Messages in Long-term Storage The MessageArchivation tool provides functionality for moving the messages from the ECP database archive into a long-term storage media. For each message from the ECP component’s database archive, an XML and a binary file are created. The XML file only stores metadata of the message, and the content of the message is written into a binary file. These files are stored in a > 57 < ENTSO-E Energy Communication Platform Administration guide defined directory structure, which is described later. The following figure illustrates the MessageArchivation process. 1. MessageArchivation acquires an ECP message stored in the database archive. 2. It finds all acknowledgments related to the message in the database archive. 3. It transforms the metadata of the message together with its acknowledgments into an XML file and the content of the message into a binary file and puts both files into long-term storage. 4. When the message is successfully written to long-term storage, the message and its acknowledgments are deleted from the database archive. 6.4.1. Structure of Long-term Storage 6.4.1.1. Directory Naming Convention The messages are stored in a well-defined structure under the root directory of long-term storage., Two directories are created under the root directory: the INCOMING directory where the incoming messages are stored and the OUTGOING directory where the outgoing messages are stored. Messages are put into subdirectories with names corresponding to the date the message was sent. Each directory is named according to the pattern YYYY-MM-DD, where YYYY represents the year, MM the month and DD the day. For example, messages sent on 15 May 2010 will be stored in the directory named 2010-05-15. 6.4.1.2. File naming convention Each ECP message is stored in long-term storage in two files – the first one holds metadata and the second contains binary content of the message. The name of the message file is composed of several parts as follows: > XML file with metadata - SENDTIME_SENDER_RECEIVER_TYPE_MESSAGEID_COMPONENT.xml > Binary file with content - SENDTIME_SENDER_RECEIVER_TYPE_MESSAGEID_COMPONENT.bin Parameter Description Regular expression SENDTIME Time the message was sent through ECP. HHmmss > 58 < ENTSO-E Energy Communication Platform Administration guide SENDER Component code of sending Endpoint. [A-Za-z0-9-@]+ RECEIVER Component code of receiving Endpoint. [A-Za-z0-9-@]+ TYPE Type of message supplied by sending BA. [A-Za-z0-9-]+ MESSAGEID The unique message identifier assigned [A-Za-z0-9-]+ by ECP. COMPONENT Code of ECP component to which the One of the following: EDC, message belongs. MC or MN 6.4.2. Running MessageArchivation from the Command Line To run MessageArchivation from command line, follow these steps. 1. Edit configuration file MessageArchivation.properties and update the parameters. Configuration parameters are described in detail in Chapter 6.4.5Error! Reference source not found.. 2. Run the MessageArchivation.sh command (MessageArchivation.cmd on Windows). The progress of the archiving process is logged into a file (see Chapter 6.4.6 – Logging). 6.4.3. Running MessageArchivation in the GUI Mode To run MessageArchivation in GUI (Graphical User Interface) mode, execute the command MessageArchivationGUI.sh on Linux (MessageArchivationGUI.cmd on Windows). MessageArchivation can be configured either in the GUI or directly in the configuration file (MessageArchivation.properties). > 59 < ENTSO-E Energy Communication Platform Administration guide 6.4.3.1. Configuration panel The screenshot below displays the configuration panel of the MessageArchivation tool. All of the parameters described in Chapter 6.4.5 can be set here. The Browse button at the top allows the user to load the configuration file from another location. The database configuration section allows changing the parameters for the database connection. When any change is made in this section, the application must be restarted after saving the configuration. The parameters modifying the archiving process can be changed in the last section. The Save button at the bottom of the panel saves the configuration, the Reset button re-loads the configuration parameters from the file so any unsaved changes are discarded. Important: When you make a change to the configuration, you must save to apply it. If you change the database configuration, you must exit the application after saving the configuration and restart the application. > 60 < ENTSO-E Energy Communication Platform Administration guide 6.4.3.2. Archivation Panel The Run Archivation button at the top starts the archiving process. When the process is running, this button changes to Terminate Archivation, which stops the archiving process (the process is stopped after the current transaction is finished, so the time depends on the number of messages in one transaction). The counter field below shows the number of messages that were already archived in the current process. The progress bar indicates how far the archiving process is. The large text area is used by the MessageArchivation tool to inform the user about its actions. 6.4.4. Running MessageArchivation on a Regular Basis MessageArchivation can be registered as a periodical job (Cron job on Linux; Task on Windows) on the operating system. This is the recommended way for running the archiving process. It > 61 < ENTSO-E Energy Communication Platform Administration guide ensures that the messages will be moved to a long-term storage regularly,thus avoiding large numbers of messages being archived in one run. The following subchapters describe how to schedule jobs on the supported operating systems. Note that the steps may differ slightly for different versions or distributions of the operating systems. In that case, consult the OS documentation. All the filenames are relative to the root directory of MessageArchivation (for the ECP Endpoint this is $INSTALLATION_HOME/tools/MessageArchivation directory). 6.4.4.1. Registering Periodical Jobs on Windows This chapter describes the steps to set up the automatic execution of MessageArchivation on Windows OS. The screenshots attached to the steps are taken on Windows 7. 1. Update the configuration file of MessageArchivation (MessageArchivation.properties). 2. Open "Scheduled Tasks" in the Control Panel. 3. Double click on "Add Scheduled Task" to run the Scheduled Task Wizard. On the first page, click Next. 4. Choose the application to run. Click on the Browse button and select MessageArchivation.cmd file. > 62 < the ENTSO-E Energy Communication Platform Administration guide 5. Select the regularity of the task (e.g. daily). 6. Select the time of the day when the task will be executed and the first date the task will be run. > 63 < ENTSO-E Energy Communication Platform Administration guide 7. Enter the authentication parameters for the user under which the MessageArchivation will be executed. Remember that this user must have: > read/write permission to the root directory with MessageArchivation tool ; > read/write permission to the root directory (and all subdirectories) of long -term storage; > execute permission for the MessageArchivation.cmd file. 8. The summary of the scheduled task is shown. Verify that everything is correct and click Finish. > 64 < ENTSO-E Energy Communication Platform Administration guide 9. Your task is now scheduled. You can verify here when the task was executed for the last time and see the status of the task. 6.4.4.2. Registering Periodical Jobs on Linux This chapter is only relevant for Linux. The steps below describe how to add a Cron job on Linux. 1. Update the configuration file of MessageArchivation (MessageArchivation.properties). 2. Use the command crontab –e to edit the Cron configuration file. The editor tool as defined by the EDITOR environment variable will be used. If this variable is undefined, the configuration file will be opened in default editor (ed). 3. Append a record for MessageArchivation to set the time when archivation will be run. For example, to run the archivation on a daily basis every midnight, append “0 0 * * * cd /opt/ECPPackage/tools/MessageArchivation;./MessageArchivation.sh”. Remember: - The first part (0 0 * * *) is a cron expression specifying when the job is executed. - The second part (cd /opt/ECPPackage/tools/MessageArchivation;./MessageArchivation.sh) changes the directory to Message Archivation tool and then executes the tool. - The job is run under the user who registered it. > 65 < ENTSO-E Energy Communication Platform Administration guide - The user who runs the job must have: - read/write permission to the root directory with MessageArchivation tool; - read/write permission to the root directory (and all subdirectories) of long -term storage; - execute permission for the MessageArchivation.sh file. - The result of running the cron job will be output to the local email account of the user who runs the job. 4. Save the configuration file and close the editor. 6.4.5. Configuration Parameters Before the ECP MessageArchivation can be used, it must be properly configured. Configuration is done by setting the following parameters in the configuration file (MessageArchivation.properties). Parameter Description Default value Database JDBC connection string jdbc:postgresql://localhost:5432/ecp Database.User Database user ecp Database.Password Database password ecpsql Database.Driver Database driver class com.postgresql.Driver Database.Dialect Database dialect. This needs to POSTGRESQL be set to use Hibernate. Archive.MessagesOld Minimum erThan messages to be moved from archive age tables in into days of 7 long-term storage. Archive.MessagesInTr Number of messages processed ansaction in one transaction. Note that 100 each message consumes RAM, so avoid setting this parameter to large values. Archive.Storage.Root Path to the root directory of Directory long-term storage. Under this directory messages will . be stored. Archive.Storage.MaxF Maximum number of files in one ilesInDirectory directory. If less than or equal 0 to zero, the number of files in one directory is unlimited. The Database connection parameters are the same as in the ECP configuration. Refer to Chapter 3.2.1 – Connection to Database to see a sample configuration for all the supported databases. > 66 < ENTSO-E Energy Communication Platform Administration guide 6.4.6. Logging MessageArchivation creates a log file when it is launched. The log file is created in the directory from which the MessageArchivation is run and is named MessageArchivation.log. A record for each message successfully archived will be written into the log. The record contains the ECP Message ID. If any error occurs during the archive process, it will be logged in the file and printed to the console as well. 6.5. Bandwidth Throttling ECP uses the maximum allowed network bandwidth when transporting messages. It is reasonable to limit the bandwidth when ECP uses a network which is also used for other critical services. This chapter describes how the bandwidth for the ECP can be limited. Bandwidth throttling is not implemented as part of ECP. It relies on standard system tools and hence is different for every operation system family which is supported. Operation system family Bandwidth throttling tool Windows Use third-party solution. Linux Traffic Control - tc 6.5.1. Bandwidth Throttling in General The main aim of bandwidth throttling is to limit the bandwidth usage of a shared network (such as Electronic Highway) used for other critical systems. A typical situation is described in the following figure. There are: > ECP Endpoint 1 - It uses its local network to communicate with the database and business application. - Only the ECP module can communicate with the ECP Node. - The bandwidth to the Node should be limited. > ECP Endpoint 2 - It uses its local network to communicate with the database and business application. - Only the ECP module can communicate with the ECP Node. - The bandwidth to the Node should be limited. > ECP Node - It uses its local network to communicate with the database. - Only the ECP module can use the shared network. - The bandwidth to the Node and from the Node should be limited. > 67 < ENTSO-E Energy Communication Platform Administration guide ECP Client 1 ECP Client 2 Business Application Business Application ECP Client 1 Database ECP Client 2 Database Network ECP Node Database ECP Node 6.5.1.1. Throttle Incoming Data Due to the design of TCP/IP there is no way to efficiently throttle incoming data. While the component may limit incoming data, the data still must go through the network and then the component may drop it (if the data comes in at a higher rate than is allowed). Due to this feature bandwidth throttling must always be performed on the sender side. This means that during the uploading of messages from ECP Endpoint 1 to ECP Node, the output policy of ECP Endpoint 1 will be applied and during downloading of messages from the ECP Node the output policy of ECP Node will be applied. 6.5.2. Bandwidth Throttling on Linux The Traffic Control tool exists for bandwidth throttling on Linux. This tool is part of the standard installation of all supported Linux distributions. The full description of this tool is beyond the scope of this document and may be found at Traffic Control HOWTO (the web reference [3]). This chapter describes the configuration of Traffic Control to meet the desired bandwidth. Note that changes made using Traffic Control are not permanent. You should create a setup script and launch it automatically after network device initialization or before the start of ECP. In the next sections, "Eth0" is used as the network device to throttle. Change it according to your network device name. All of the following commands have to be run under the root user. > 68 < ENTSO-E Energy Communication Platform Administration guide 6.5.2.1. Throttle Outgoing Data 1. Drop root qdisc (if existing). The response of the command will be none (qdisc was dropped) or “RTNETLINK answers: No such file or directory” when there is no root qdisc. tc qdisc del dev eth0 root 2. Create root qdisc. tc qdisc add dev eth0 root handle 1: htb default 1 3. Create default class (replace 1000Mbit according to your local network max. bandwidth). tc class add dev eth0 parent 1: classid 1:1 htb prio 50 rate 1000Mbit ceil 1bps 4. Create class for bandwidth throttling (replace 8000kbit with the max. bandwidth you want to assign to this ECP component for outgoing data). tc class add dev eth0 parent 1: classid 1:2 htb prio 50 rate 8000kbit ceil 1bps 5. Assign limited bandwidth equally. tc qdisc add dev eth0 parent 1:2 handle 20: sfq perturb 10 6. Filter traffic you want to limit. You may add as many filters as you want. At the ECP Endpoint you should filter all ECP Nodes in the network and at ECP Node you should filter all ECP Nodes and Clients in the network. - Filter by IP (replace 192.168.80.177 with the desired target IP). tc filter add dev eth0 protocol ip parent 1:0 prio 1 u32 dst 192.168.80.177 flowid 1:2 match ip - Filter by network (replace 192.168.80.0/24 with the desired target network). tc filter add dev eth0 protocol ip parent 1:0 prio 1 u32 dst 192.168.80.0/24 flowid 1:2 6.5.2.2. match ip Throttle Incoming Data The throttling of incoming data is optional and does not limit the usage of the network but the acceptance rate of the component. It can be set up at the Node to make sure that a component which does not throttle outgoing data does not load the network. 1. Drop incoming qdisc (if existing). The response of the command will be none (qdisc was dropped) or “RTNETLINK answers: No such file or directory” when there is no incoming qdisc. tc qdisc del dev eth0 handle ffff: ingress 2. Create incoming qdisc. tc qdisc add dev eth0 handle ffff: ingress 3. Filter traffic you want to limit. You may add as many filters as you want. At the ECP Node you should filter all ECP Nodes and Clients in the network. - Filter by IP (replace 192.168.80.177 with the desired source IP and replace 8000kbit with the max. bandwidth you want to assign to this ECP component for incoming data). tc filter add dev eth0 parent ffff: protocol ip prio 25 u32 match > 69 < ENTSO-E Energy Communication Platform Administration guide ip src 192.168.80.177 police index 1 rate 8000kbit burst 500k flowid :1 - Filter by network (replace 192.168.80.0/24 with the desired source network and replace 8000kbit with the max. bandwidth you want to assign to this ECP component for incoming data). tc filter add dev eth0 parent ffff: protocol ip prio 25 u32 match ip src 192.168.80.0/24 police index 1 rate 8000kbit burst 500k flowid :1 6.5.2.3. Monitoring Monitoring of Traffic Control can be done using the following commands. The description of monitoring commands may be found on the manual page (man tc) or in Traffic Control HOWTO (the web reference [3]). > Monitor qdisc status tc -s -d qdisc show dev eth0 > Monitor classes status tc -s -d class show dev eth0 6.5.2.4. Troubleshooting If you make any mistake during Traffic Control setup, you may remove all changes by deleting the appropriate qdisc (outgoing root or incoming). If you set up Traffic Control according to this guideline and it is not throttling correctly, check for the existence of “giant” packets. “Giant” packets may cause the inaccuracy of bandwidth throttling. The existence of giant packets can be checked with the following command: tc -s -d class show dev eth0 | grep giants If some giant packets exist, you may try to disable TSO (TCP Segmentation Offload). It may be done using the following command: ethtool -K eth0 tso off Note that this is workaround for this problem. The root cause is inside the Traffic Control or network card drivers. You may contact support for your Linux distribution to solve the cause of the problem. > 70 < ENTSO-E Energy Communication Platform Administration guide 7. MONITORING 7.1. ECP Module – Monitoring Web Page Each ECP module provides a simple web page with basic information about the deployed ECP module. In the browser go to the URL http://[appserver]:[port]/ECP_MODULE/monitoringPage,seam, where appserver is the IP address of the application server where the ECP Endpoint is deployed and port is the http(s) port configured for the application (usually 80 or 8080 for HTTP, 443 or 8443 for HTTPS). A web page similar to this example should be displayed (you may be prompted to log in first): > 71 < ENTSO-E Energy Communication Platform Administration guide Notes: > The first part contains brief information about the deployed module (Name, Deployment Mode, Version). The page also contains the 20 latest information messages ordered by the timestamp. For each message the following information is displayed: - Severity – How important the message is. > 72 < ENTSO-E Energy Communication Platform Administration guide - Timestamp – Time when the message was created. - Message – The text description of the message. > The next section contains information about all active modules certificates. For each certificate the following information is shown: - Certificate type – every ECP module has certificates for encryption, signing and authentication purposes. In addition, an ECP Node also has a certificate of the integrated certificate authority. - Certificate authority – name of certificate issuer. - Active since – time the certificate has been active. - Valid until – validity period of the certificate. - Preferred – after updating certificates, it is possible that multiple certificate sets co-exist at the same time. This field indicates which is currently being used by the ECP application. > For each deployed messaging component, one section is shown. When two components are deployed (Endpoint and Node), two sections are displayed. > The table with endpoints connected over network contains : - module name: name of the connected module. This is actually the component code of the communicating messaging component; - module type: the type of the communicating component (Endpoint); - channel: the internal channel type through which the module is connected (WS) ; - last connection: the time the last successful connection was made. > For each component a table is displayed with the timestamps of the latest operations that the component performed: - Upload-In: accepting a message as a reaction to upload of BA or another component. - Upload-Out: uploading a message to another component. - Download-In: accepting a message downloaded from another component. - Download-Out: returning a message to BA or another component which required it. > When a Node is deployed, a table with connected Endpoints is also displayed. This table contains following information: - Endpoint name: the component code of the connected Endpoint. - Connected through: the name of the module through which the Endpoint is connected. - Last download message: the time the Endpoint downloaded the last message. - Last uploaded message: the time the Endpoint uploaded the last message. > When the Node is deployed, a table with trusted certificate authorities is displayed. This table contains the following information: > 73 < ENTSO-E Energy Communication Platform Administration guide - Certificate authority name. - Type – type of the certificate authority. Every ECP Node contains one ROOT certificate authority and one INTEGRATED certificate authority. The Node administrator can add EXTERNAL certificate authorities. - Valid to - time until the certificate authority is valid. If the page is not displayed, check if the application container is running. If the page is displayed but no information about any deployed module is shown, check the logs in the [appcontainer_home]/logs/ directory for any errors. > 74 < ENTSO-E Energy Communication Platform Administration guide 8. REFERENCES 8.1. Related Documents [ECP Public API] 8.2. [1] ECP Public API (ECP Public API.doc) Web References Apache Tomcat Configuration Reference – The HTTP Connector http://tomcat.apache.org/tomcat-6.0-doc/config/http.html [2] Hexadecimal System http://en.wikipedia.org/wiki/Hexadecimal [3] Traffic Control HOWTO http://www.redhat.com/mirrors/LDP/HOWTO/Traffic-Control-HOWTO/index.html > 75 <

ECP3.0 Administration Guide - Home

Related documents

Products

Support

ECP3.0 Administration Guide - Home

Related documents

Add this document to collection(s)

Add this document to saved

Suggest us how to improve StudyLib