fusion registry - metadatatechnology.com · 6 3 configuring fusion registry 3.1 maintenance tool...

27
Fusion Registry: 8.4.x Document Last Updated: May 27 th 2015 FUSION REGISTRY Setup Guide FUSION REGISTRY Setup Guide This guide explains how to install Fusion Registry in a Java Application Server and how to configure it.

Upload: phungphuc

Post on 03-Aug-2018

219 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

Fusion Registry: 8.4.x Document Last Updated: May 27th 2015

FUSION REGISTRY Setup Guide

FUSION REGISTRY Setup Guide

This guide explains how to install Fusion Registry in a Java Application Server and how to configure it.

Page 2: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

1

Contents

1 Fusion Registry Dependencies ........................................................................................................ 3

1.1 Java (required) ........................................................................................................................ 3

1.2 Servlet Container (required) ................................................................................................... 3

1.3 SQL-92 Compliant Database (required) .................................................................................. 3

1.4 Fusion Security (optional) ....................................................................................................... 3

1.5 Fusion Audit (optional) ........................................................................................................... 3

2 Deployment..................................................................................................................................... 4

2.1 Important issue regarding multiple Web Application deployment ........................................ 5

3 Configuring Fusion Registry ............................................................................................................ 6

3.1 Maintenance Tool ................................................................................................................... 6

3.2 General .................................................................................................................................... 7

3.2.1 Registry Name ................................................................................................................. 7

3.2.2 Sender Id ......................................................................................................................... 7

3.2.3 Default Language ............................................................................................................ 7

3.2.4 Default Agency ................................................................................................................ 7

3.3 Change Database Connection ................................................................................................. 8

3.4 Change Email Server ............................................................................................................... 8

3.5 Security ................................................................................................................................... 9

3.6 SDMX Endpoint ..................................................................................................................... 10

3.6.1 What is an Endpoint ...................................................................................................... 10

3.6.2 Endpoint Maintenance.................................................................................................. 10

3.7 Backup and Recovery ............................................................................................................ 13

4 Fusion Registry Properties File ...................................................................................................... 15

4.1 Changing the location of the properties file ......................................................................... 15

4.2 Contents of the properties file .............................................................................................. 16

4.2.1 Database Settings.......................................................................................................... 17

4.2.2 Security Credentials ...................................................................................................... 17

4.2.3 Memory Limit ................................................................................................................ 18

4.2.4 Settings Modification Enabled ...................................................................................... 18

4.2.5 Server URL ..................................................................................................................... 18

4.2.6 Audit Properties ............................................................................................................ 18

4.2.7 Sweep Properties .......................................................................................................... 19

5 Securing Registry Login with HTTPS .............................................................................................. 20

Page 3: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

2

5.1 Choose a port number to use as your secure port ............................................................... 20

5.2 Configuring your Application Server ..................................................................................... 20

5.2.1 Security Certificate ........................................................................................................ 20

5.2.2 Tomcat Configuration ................................................................................................... 21

5.2.3 Fusion Registry Configuration ....................................................................................... 21

5.3 Testing HTTPS ........................................................................................................................ 22

6 Logging .......................................................................................................................................... 22

7 Annex 1 - Alternative Database Platforms .................................................................................... 24

7.1.1 Oracle Database Connection......................................................................................... 24

7.1.2 SQL Server Database Connection .................................................................................. 24

Page 4: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

3

1 Fusion Registry Dependencies Fusion Registry is distributed as a single Web Application Archive (war) file: FusionRegistry.war it

should be deployed to a servlet container such as Apache Tomcat (a free product).

To run a secure Registry with a number of user accounts then Fusion Security must be used to create

and administer the users in the system. Fusion Security configuration is documented in the Fusion

Security setup guide.

If auditing is required, then Fusion Audit must be configured in order to capture audit information.

Fusion Audit configuration is documented in the Fusion Audit setup guide.

The Fusion Registry by default uses an in-memory database, this is only recommended for evaluation

or testing purposes as the database will be dropped when the application server is terminated. To

persist structures to a permanent storage a database connection is required. The Fusion Registry

supports MYSQL, Oracle, and SQL Server.

1.1 Java (required) Java Runtime Environment (JRE) 1.6 or higher is required.

1.2 Servlet Container (required) Fusion Registry is deployed to a Servlet Container. Apache Tomcat is a popular, open source servlet

container, download links and installation instructions can be found at the following URL.

http://tomcat.apache.org/

It is recommended to use the latest version of Apache Tomcat as it will include the latest security

patches. The Fusion products will not run in any Apache Tomcat version lower than version 6.0.

1.3 SQL-92 Compliant Database (required) Fusion Registry makes use of an Object Relational Mapping (ORM) library called Hibernate. This

allows Fusion Registry to communicate with any SQL-92 compliant database.

The database must be installed and running and Fusion Registry must be configured to connect to

the database, this is covered in section 3.3. The Fusion Registry will automatically create the

database tables on connection.

NOTE: Fusion Registry has only been tested with MySQL, Oracle, and SQL Server.

1.4 Fusion Security (optional) By default Fusion Registry provides the ability to secure the Registry only allowing a trusted user to

perform changes. If you wish to have a number of users with different access credentials, then

Fusion Security is required. Please refer to the Fusion Security Setup and User guides as well as the

section on Security in this document (section 3.5).

1.5 Fusion Audit (optional) If a connection to RabbitMQ is configured in the registry properties file, then the Fusion Registry will

send audit and logging information to RabbitMQ which can be processed by Fusion Audit. Fusion

Audit is a separate web application which should be running in order to receive messages from the

message queue. Fusion Audit provides its own Setup and User guides.

Page 5: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

4

2 Deployment Fusion Registry consists of a single .war file called FusionRegistry.war. This file needs to be copied

into the directory: <TOMCAT_HOME>/webapps then the Tomcat server should be started. As the

Tomcat application server starts, the contents of the Fusion Registry war file will be unpacked into

the directory:

<TOMCAT_HOME>/webapps/FusionRegistry

Fusion Registry will default to using an in-memory database. All database, e-mail, security, and

general settings can be modified via the web interface provided by Fusion Registry.

Please check the Tomcat log files to ensure that Fusion Registry has deployed correctly. Once it has

then you may navigate to the URL:

http://[server]:[port]/FusionRegistry/

The values for server and port must be replaced with the IP address and port number that the web

application server is running on. For example, if the web browser is running on the same machine as

the web application server and the Apache Tomcat has not had its default port settings modified,

then the following address can be used:

http://localhost:8080/FusionRegistry/

Once Fusion Registry starts, the following Registry home page will be displayed in your web browser.

The facilities available from this view are explained in the Fusion Registry User Guide.

Figure 1 - Registry home page

Page 6: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

5

2.1 Important issue regarding multiple Web Application deployment PLEASE BE AWARE

Tomcat uses PermGen space to store class definitions and string pools that have been interned. A

single Tomcat instance is comfortable loading a single Fusion Registry web application, however if

you attempt to load another web application (such as Fusion Security) into the same Tomcat, you

may encounter the following error in your Tomcat log:

java.lang.OutOfMemoryError: PermGen space

The default permGenSpace in Tomcat is only set to 64Mb. To increase this value, it is recommended

to create the file setenv.bat (or setenv.sh on Unix environments) and place it in the tomcats bin

directory. To set the PermGenSpace to 128Mb set the contents of the file to the following:

SET JAVA_OPTS=-XX:MaxPermSize=128m

(For Windows systems)

export JAVA_OPTS=-XX:MaxPermSize=128m

(For Unix systems)

Page 7: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

6

3 Configuring Fusion Registry

3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. Click on “Maintenance Tool” to access. In

order to select the “Settings” option the user must be logged in, and when the registry is first

installed there will be no security application assigned to the registry as this is set up using the

“Settings” menu option. Therefore, the registry is supplied with a default user with administrative

privileges.

username: root

password: password

Thereafter, if security is set on then users are maintained using Fusion Security and the

administration of users (including administrative users for the registry) is described in the Fusion

Security guide.

Note: To change the default username and password edit the fusionregistry.properties file as

described in section 4.2.2.

Log in using the credentials described above.

Figure 2 - Selecting the 'Settings' option

Select the “Settings” option.

Figure 3 - Showing Registry settings options

The use of each of these options is described below.

Page 8: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

7

3.2 General

3.2.1 Registry Name To change the Registry name, type into the Registry name text box as shown below. The Registry

name is only used as a display name for the GUI. As the name is modified the GUI is updated

automatically.

Figure 4 - Setting Registry Name

3.2.2 Sender Id The Sender Id is inserted into the header of any SDMX-ML response from the Registry. Typing into

the input box will automatically change the Sender Id output by the Registry. The following output

snippet shows a Sender Id of “TestSender”:

Figure 5 - Showing output Sender Id of 'TestSender'

3.2.3 Default Language The default language setting is used to set the default language of the SDMX structures as they are

presented to the user in the Maintenance GUI. The maintenance GUI will always default to English

(en) if the structure does not have a name/description in the selected language. If there is not

English label, then the next default is the first name/description the application finds, regardless of

language.

3.2.4 Default Agency When a user browses the structures in the Maintenance GUI, only structures for the selected Agency

are shown. The Default Agency setting is used to set the Agency that is selected when the user

opens the Maintenance GUI.

Page 9: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

8

3.3 Change Database Connection To change the database connection to use a persistent store, click on the database tab on the

settings page. Select the database type from the drop-down list. The Registry will create the

database tables automatically, although the database schema must already exist. Please note that

due to licensing restrictions, Fusion Registry does not provide jar files to connect to Oracle or

SqlServer databases. These must be downloaded from the database vendor’s web site and placed

onto the classpath of the application server. Fusion Registry will require that the connection is

tested before the database settings can be applied.

Figure 6 - Database Information dialog box

NOTE: It is possible to connect to other database platforms, in this instance the Fusion Registry

properties file must be modified manually. This is covered in section 4.2.1.

3.4 Change Email Server In order for the Registry to be able to e-mail forgotten passwords, and to e-mail any subscription

notification events, the Email Server must be configured. Click on the ‘Email Server’ tab and fill in

the details. If you do not need to provide a username and password for your mail server, please fill

in the User ID, as this will be used to identify who the email is from. If your email server requires

authentication, please ensure the ‘Has Security’ checkbox is ticked, and the User ID and password

fields are filled in:

Page 10: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

9

Figure 7 - Showing the email settings page

NOTE: Before the e-mail settings can be applied, you must click the `Test Email Settings` button and

send a test e-mail. This is to ensure that the Registry is able to determine if it can communicate with

the e-mail server with the specified credentials.

3.5 Security By default the Fusion Registry is public and allows any user to submit or query for structures. It is

possible to secure the Fusion Registry so only certain users can modify structures. This includes:

1. Root user – the root user can modify any structure.

2. Admin user – an admin user can modify any structure.

3. Agency – an agency can only modify structures that belong to their agency. An agency can

subscribe to structure or registration events in the Fusion Registry.

4. Data Provider – A data provider can register datasets for which provision agreements have

been created. A data provider can subscribe to structure or registration events in the Fusion

Registry.

5. Data Consumer - A data consumer can subscribe to structure or registration events in the

Fusion Registry.

To secure the Registry, click on the Security tab and click Enable Registry Security. This step will

require authentication. At this point the Fusion Registry will be secure so that only the root user can

modify structures. To disable security click the same button (which will again require

authentication).

NOTE: If using a secure registry then it is highly recommended to enforce access over HTTPS.

Details of enabling HTTPS are given in section 5.

In order to create and administer other types of user, it is necessary to use the product Fusion

Security. This can then be used as the administration and authentication application for Fusion

Registry. Fusion Security can be downloaded for free and the set up and configuration is explained

in the Fusion Security guides.

If using Fusion Security the Fusion Registry will be able to use this as an authentication service by

simply adding the URL of Fusion Security to the ‘Authentication Service URL’ text input field as

shown below.

Page 11: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

10

Figure 8 - Showing Security Information page

Enter the URL of the authentication server as shown above and then Click on “Update URL”. At this

stage the Fusion Registry will require you to authenticate using the authentication credentials of a

valid admin or root user known to Fusion Security (NOT the authentication credentials of the user in

Fusion Registry).

Figure 9 - Showing Authentication Required dialog

After submitting these details Fusion Security will authenticate the credentials to ensure the user is

known to Fusion Security. On successful authentication, the authentication server of the Fusion

Registry will be updated. Any authentication now will be delegated to the Fusion Security

application; this means that the credentials for the root user stated in the file

“fusionregistry.properties” will no longer be being used.

3.6 SDMX Endpoint

3.6.1 What is an Endpoint An endpoint for the Fusion Registry is a structural metadata service that can be queried for

structural metadata, and have structures PUSHed to it.

These endpoints can be selected and relevant structures can be retrieved by entering a URL from

where they can be retrieved. This must be an SDMX web service. This feature will pull all of the

structural metadata for selected agencies from the endpoint.

3.6.2 Endpoint Maintenance Select “SDMX Endpoint” to view the endpoints, followed by “Add New” to add a new endpoint

service to the Registry.

Page 12: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

11

Enter the SDMX REST query service from which the structural metadata can be retrieved. This value

must be the location of the Web Service that can provide the structures. Depending on how the

Registry has been set-up this may end with “/ws/rest”. So by way of example a valid URL may be:

http://registry.sdmxcloud.org/ws/rest

If the service that is the endpoint is secure and needs login credentials then complete the username

and password details for the service. Click on “Query Service” to display the list of maintenance

agencies available at the Endpoint. If the query was successful, then a Service Alias can be entered.

The service alias will be presented to users when choosing an endpoint to PULL or PUSH structure

from/to.

Figure 10 - Showing 'Adding Endpoint' dialog box

At this stage it is possible to PULL all structures for selected Agencies into the local Registry. The

Registry will PULL all structures for selected agencies, including any cross referenced structures that

may be maintained by other Agencies.

It is possible to add an endpoint without PULLing any structures across. In this instance, the

endpoint will be available to PUSH structures to. After selecting the Agencies to PULL structures for,

click “Add Endpoint”.

Page 13: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

12

Figure 11 - Showing the Fusion Registry with the SDMX Global Registry added as an Endpoint

After adding an endpoint, it will be added to the list of known endpoints.

The Re-synchronise button can be used to re-select the structures for the chosen Agency. There is

no automated synchronisation and if these structural metadata are changed. However, the user can

subscribe to be notified of changes (using the SDMX subscription/notification mechanism of the

Registry) and an automated process can be set up.

Page 14: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

13

Figure 12 showing Fusion Registry overview page with an external SDMX web service configured

3.7 Backup and Recovery To view Fusion Registry transactions, in order to download transaction contents, or roll back the

Fusion Registry to a previous transaction, click on the ‘Backup and Recovery’ button. Enter in any

required filters, note, filters can be left blank to show all transactions, and click ‘Show Transactions’.

The table will then show each transaction that matches the filter criteria, in date ascending order.

Page 15: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

14

To restore the Fusion Registry contents to a point in time, click on the transaction to roll back to, and

click ‘Restore to Transaction’. The Fusion Registry will clear its contents and restore them to reflect

how they were at the time of the transaction restore point. A restore will show up as an additional

transaction, as shown below.

Figure 13 Showing transaction #13 is a restore back to transaction #9

To view what structures were submitted in a transaction, select the transaction and click ‘View

Transaction Items’. This will bring up a list of all the maintainable structures that were submitted in

the transaction, and includes the ability to download a 2.1 SDMX document containing the structure,

as shown below.

Figure 14 showing transaction items for a single transaction.

Page 16: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

15

4 Fusion Registry Properties File Fusion Registry stores information within a properties file and, if configured, within a database.

Database configuration should be performed through the Maintenance Tool (see section 3.3) but the

properties file is used to provide Fusion Registry with information such as the location of the

database to use. The properties file is only read at startup and changing any of the values in the

Fusion Registry properties file whilst Fusion Registry is running will have no effect.

The properties file is called:

fusionregistry.properties

By default the Fusion Registry has a copy of this file located in the directory:

<Tomcat HOME>\webapps\<Web AppName>\WEB-INF\classes

However if you make any changes using the maintenance tool, Fusion Registry will attempt to save a

new properties file to the directory:

<user home>\FusionRegistry

Therefore, on a Windows 7 Operating System this will typically be:

C:\users\<your user name>\FusionRegistry

Whereas on a Unix Operating System, it is more likely to be located at:

/users/<your user name>/FusionRegistry

On Fusion Registry startup, the Fusion Registry will load the properties file from the WEB-INF\classes

directory first, and then look for a properties file in your home directory. If it locates a properties file

in your home directory, the values in this file will be read and will override values from the default

properties file.

If you are unsure about which of the files Fusion Registry is using to obtain system information,

please look at the startup log in your web application server. There will be entries like the following:

INFO localhost-startStop-1

org.springframework.beans.factory.config.PropertyPlaceholderConfigurer -

Loading properties file from class path resource

[fusionregistry.properties]

INFO localhost-startStop-1

org.springframework.beans.factory.config.PropertyPlaceholderConfigurer -

Loading properties file from URL

[file:/C:/Users/<username>/FusionRegistry/fusionregistry.properties]

4.1 Changing the location of the properties file The location of your properties file can be changed. This is useful if you either do not want the

Registry storing information in your home directory or if you wish to run multiple Registries on one

server.

To specify a new location you need to set a Java System variable called “RegistryProperties” to the

URI value of the location where you wish the properties file to be. In Apache Tomcat the easiest way

to achieve this is to create a new file called setenv.bat (or setenv.sh on Unix environments) and

place it in the tomcats bin directory. The contents of this file should state the full location of the

properties file which must be in the URI format. To illustrate this:

Page 17: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

16

SET JAVA_OPTS=-DRegistryProperties=file:///c:/dir/AFile.txt

(For Windows systems)

export JAVA_OPTS=-DRegistryProperties=file:///dir/AFile.txt

(For Unix systems)

It is important to note that Fusion Registry will NOT start if this value is incorrect or if this file cannot

be created.

To check that this value is being used by the system, check the Registry log during Registry startup

and look for a line similar to the following:

Property RegistryProperties has been specified as

file:///c:/dir/AFile.txt

4.2 Contents of the properties file The default contents of the properties file fusionregistry.properties are shown below:

######################################################################

# DATABASE CONNECTION #

######################################################################

database.driver=org.hsqldb.jdbcDriver

database.username=sa

database.password=

database.url=jdbc:hsqldb:mem:FusionRegistry

hibernate.dialect=org.hibernate.dialect.HSQLDialect

######################################################################

# DEFAULT SECURITY (IF NOT USING FUSION SECURITY) #

######################################################################

default.username=root

default.password=password

######################################################################

# IN MEMORY PROCESSING LIMIT #

######################################################################

memory.limit=30720

######################################################################

# MAINTENANCE GUI SETTINGS ENABLED #

######################################################################

# Shows or hides 'settings' control from the Maintenance Tool

settings.modification.enabled=true

######################################################################

# SERVER URL #

######################################################################

# If not set, the Registry will determine the URL dynamically

server.url=

######################################################################

# AUDITING #

Page 18: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

17

######################################################################

mq.username=

mq.password=

mq.host=

mq.port=

######################################################################

# FILE SWEEPER #

######################################################################

sweep.dir.read=

sweep.dir.move=

sweep.sleep=

4.2.1 Database Settings These settings control the communication to the database (if there is one configured).

It is highly recommended not to attempt to edit these directly in the file but instead to use the

Maintenance Tool to set the values for you. This is described in section 3.3.

The table below gives information on each of the properties if configuring these manually.

Property Description

database.driver The Java driver to use. For a MySQL database this must be set to: com.mysql.jdbc.Driver

database.username The username to connect to the database. database.password The password for the user. database.url The location of your database specified as a URL. For a MySQL

database this is of the form: jdbc:mysql://<server>:<port>/<database schema>

hibernate.dialect For a MySQL database this must be: org.hibernate.dialect.MySQLDialect

To change the database platform:

Provide an appropriate JDBC driver for the database on the class path,

Change the JDBC properties (driver, url, user, password)

Change the dialect used by Hibernate to talk to the database

5 Details on changing to another database are detailed in Logging Fusion Registry defaults to output log events to [tomcat]/logs/Fusion Registry.log. Additionally if

configured to use Fusion Audit, log events will also be audited against each audited event.

The default log level is INFO. Log levels, layout and style and output location can all be configured in

the following file.

[tomcat]/webapps/FusionSecurity/WEB-INF/classes/log4j.properties

The default configuration is shown below:

#ROOT LOGGER

Page 19: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

18

log4j.rootLogger=INFO, fileout, stdout, fusionaudit

log4j.rootLogger.additivity=false

#SPECIFIC LOGGERS

log4j.logger.com.sdmxfusion = INFO

log4j.logger.com.metadatatechnology = INFO

log4j.logger.org.sdmxsource = INFO

#LOG TO FILE (LOCATION, STYLE & LAYOUT)

log4j.appender.fileout=org.apache.log4j.RollingFileAppender

log4j.appender.fileout.file=${catalina.base}/logs/FusionRegistry.log

log4j.appender.fileout.MaxFileSize=1024KB

log4j.appender.fileout.MaxBackupIndex=4

log4j.appender.fileout.layout=org.apache.log4j.PatternLayout

log4j.appender.fileout.layout.ConversionPattern=%p %t %c - %m%n

#LOG TO CONSOLE (STYLE & LAYOUT)

log4j.appender.stdout=org.apache.log4j.ConsoleAppender

log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

log4j.appender.stdout.layout.ConversionPattern=%d %p [%c] - <%m>%n

#LOG TO AUDIT

log4j.appender.fusionaudit=com.sdmxfusion.sdmx.integration.manager.publishe

r.LogPublisher

For more information about logging please read the log4j documentation which is available online.

The version of log4J used in this release is 1.2.14.

Annex 1 - Alternative Database Platforms.

5.1.1 Security Credentials If the Registry has not been configured to use Fusion Security then the Registry provides a single

user account with root privileges. The username and password for this single account are

maintained in this properties file. If the Fusion Registry is configured to use Fusion Security then

these values will be ignored.

To change the credentials, simply modify the username and password values and restart Fusion

Registry.

Note: The password is not encrypted in this file, so ensure that unauthorised individuals do not have

access to this file if you wish to keep your password secret.

5.1.2 Memory Limit The Fusion Registry processes submitted structures in memory, however it will overflow to the file

system if the submitted document is too large to fit in memory. The memory.limit property specifies

the in memory limit for processing before the information is written to disk. This value is specified

in KB and the default value is 30720 which is 30 Mb. This value can be modified if required.

Note: The memory limit defines the limit for all information in memory at any given point in time. It

is not a tied to a single submission.

Page 20: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

19

5.1.3 Settings Modification Enabled Setting the property settings.modification.enabled to true or false, will result in enabling or disabling

the ability to access this settings page of the maintenance UI. This should be set to false to disable

modification of database connection, security, email server, endpoint, and general Registry settings.

5.1.4 Server URL The Registry will be hosted on a specific URL which it will attempt to determine dynamically.

However in some situations the URL that the Registry obtains will not reflect the public URL of the

Registry service. An example is if the Registry is deployed to a server which is using advanced

routing (for example using Apache to redirect incoming traffic to alternate URL/ports). The external

URL may be:

https://registry.sdmxcloud.org

But the URL as determined by the Registry might be:

http://localhost:8082/FusionRegistry

In this scenario the server.url property can be used to tell the Fusion Registry which URL to use. This

value when set must start with http:// or https:// and contain the Web Application name (if you are

using one). So legal values could be:

http://myserver.com:8080/FusionRegistry

http://localhost:8080/FusionRegistry

https://anotherServer.com/FusionRegistry

https://registry.sdmx.org

Note: This property must be set if Fusion Registry has been configured to use Fusion Security. The

server.url value is used in the reset password functionality as the link for a user to navigate to, in

order to reset their password.

Note: If you wish to run the Registry as the ROOT application of Tomcat then you will need to specify

the server.url value of your system.

5.1.5 Audit Properties These properties are required if sending audit information to Fusion Audit. The Audit properties

define the connection details for Rabbit MQ. Rabbit MQ is the message broker which transports

messages from auditing applications to Fusion Audit.

These properties can only be modified by directly editing the properties file (there is no user

interface to maintain the connection). Default settings for Rabbit MQ are:

mq.username=guest mq.password=guest mq.host=[Server IP hosting Rabbit MQ, set to ‘localhost’ if running on the same server as the Fusion Registry] mq.port=5672

If these properties are configured then the Fusion Registry will send audit information to Rabbit MQ

for collection by Fusion Audit. If left blank, then the Fusion Registry will not capture audit

information.

Page 21: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

20

5.1.6 Sweep Properties These properties, if set, define a directory on the file system to be polled at distinct intervals of time.

Any files in the swept directory will be processed as a structure submission.

NOTE: The submission will bypass security.

Property Description

sweep.dir.read The directory which the Fusion Registry will

periodically check for files for submission.

sweep.dir.move The directory which the Fusion Registry will move the swept files to after processing.

sweep.sleep The interval between sweeping a directory, measured in milliseconds.

Page 22: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

21

6 Securing Registry Login with HTTPS The Registry provides the ability for connections to be made using HTTP Secure (HTTPS). This allows

for a much more secure system ensuring that user ids and passwords are passed from the client side

Registry Web Application to the server side of the Registry in an encrypted form. This is achieved by

using the Secure Sockets Layer (SSL) protocol.

6.1 Choose a port number to use as your secure port You will need to choose a port to use for your secure port. The default secure port number Apache

Tomcat and Fusion Registry is 8443. You will need to understand the system that Fusion Registry will

be deployed to and evaluate what ports you have available. Choose an available port. We will use

this port number repeatedly in the rest of the document.

6.2 Configuring your Application Server The application server must be configured to support SSL connections. The following text details

how to perform this on Apache Tomcat version 7. For other application servers please refer to the

vendor’s instructions.

6.2.1 Security Certificate

The first thing that you will require to enable HTTPS is a valid certificate for the server to prove to

the client that it is to be trusted. This certificate should ideally be signed by a trusted Certification

Authority (CA). Untrusted certificates may be used but these will cause a slight inconvenience for

your end users.

Certificates can be obtained from certificate authorities (e.g. VeriSign / Microsoft / etc.). If you are

planning on running the Registry in a production environment is it recommended you fully

understand how certificates operate and setup a trusted certificate. If you wish to just explore how

the Registry supports HTTPS you can setup a certificate through the Java supplied application:

keytool. This application is supplied as part of the Java Development Kit (JDK) and can be used to

view the contents of key stores or create a new key store and certificate. Details of how keytool

works can be found on Oracle’s website:

http://docs.oracle.com/javase/7/docs/technotes/tools/windows/keytool.html

The following command creates an unsigned certificate and a keystore named metatech.keystore

which has a password of password. When prompted you will need to answer questions regarding

the name and organisation of the certificate. For further details please refer to the keytool

documentation.

keytool -genkeypair -alias serverTrust -keyalg RSA -validity 365 -storepass

password -keystore metatech.keystore -storetype JKS -ext san=ip:192.168.4.1

Note: Certificates are valid for a specific domain. You may specify your domain name as the CN

name of the certificate but in the example above I have specified that the "Subject Alternative

Name" (SAN) is the IP address: 192.168.4.1. This means that the machine running on this IP is

trusted with this certificate. If you use the example above ensure you modify the SAN value to be

the IP address of the machine that is running your Tomcat server.

Page 23: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

22

6.2.2 Tomcat Configuration

Your keystore file must be copied to the conf directory of your Apache Tomcat.

Also within the conf directory, you will need to edit the file server.xml. Locate the section regarding

SSL and enable it. It will look something like the following:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"

maxThreads="150" scheme="https" secure="true"

clientAuth="false" sslProtocol="TLS"

keystoreFile="conf/metatech.keystore"

keystorePass="password" />

In the above example the secure port has been defined as 8443. If you are using a secure port other

than 8443 you would need to change this value. The value for keystoreFile must be the location of

your keystore file (which you just copied to your conf directory) and the value for keystorePass must

be the correct password for your keystore.

It is also recommended to setup a value for a variable called “secure.port” (this will be used later by

FusionRegistry). This value must be the port number that you have chosen to use as your secure

port and will match the values you previously specified in the file: server.xml.

The simplest way to setup this variable is to create an environment file that Tomcat will load on

startup. Within the directory <tomcat home>/bin create the file “setenv.bat” (if using a Windows

version of Tomcat) or “setenv.sh” (if using a Unix version of Tomcat). The contents of the file for

Windows users using port 8443 must be:

set JAVA_OPTS=-Dsecure.port=8443

and for Unix users it is:

export JAVA_OPTS=-Dsecure.port=8443

This file is only read on Tomcat startup, so changing this file whilst Tomcat is running will have no

effect.

Once the above has been configured you may start your Tomcat application server. In the startup

log you will now notice that there will be an output for your new secure port. A typical example is

shown below which states that there are two ports open: the first on 8080 (for http connections)

and the other on 8443 (for https connections):

org.apache.coyote.AbstractProtocol init

INFO: Initializing ProtocolHandler ["http-bio-8080"]

org.apache.coyote.AbstractProtocol init

INFO: Initializing ProtocolHandler ["http-bio-8443"]

6.2.3 Fusion Registry Configuration

To allow the Registry GUI to communicate on the secure port some changes are required to the web

application. Assuming that the Tomcat Server has been started at some stage, Fusion Registry will

have been installed into the directory: <tomcat home>/webapps/FusionRegistry. Locate this install

directory and then perform the following changes:

6.2.3.1 Enable a secure channel

Locate the file: services-config.xml within the sub-directory: WEB-INF/flex. Within this file you will

need to enable the secure channel named “my-secure-amf”. Locate the section in this file. This

section starts:

Page 24: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

23

<channel-definition id="my-secure-amf"

This section must be un-commented by removing the leading characters <!-- and the trailing

characters --> .

Note: this channel-definition refers to “secure.port” the value of which you placed into the setenv

file earlier.

6.2.3.2 Restart your Application Server

Changes to the above files are only actioned when the Tomcat Application Server restarts, so please

restart Tomcat now. The secure communications channel will now be available for Fusion Registry

to use.

6.3 Testing HTTPS To test that HTTPS has been enabled you can navigate to the URL below. If HTTPS has not been set

up, then an HTTP Error of 404 will be shown. If HTTPS is enabled a completely blank screen will be

shown. The URL is:

https://{server.name}:{secure.port}/{context.root}/messagebroker/amfsecure

For example:

https://localhost:8443/FusionRegistry/messagebroker/amfsecure

If the security certificate is untrusted then most web browsers will consider that URL a security risk

since the connection is considered untrusted. A security warning will be displayed to the user

preventing the connection to the URL unless the user manually adds an exception. Different web

browsers perform this process differently and each user will need to add an exception before they

can use HTTPS on the Registry. Using a signed and trusted certificate will avoid this issue.

7 Logging Fusion Registry defaults to output log events to [tomcat]/logs/Fusion Registry.log. Additionally if

configured to use Fusion Audit, log events will also be audited against each audited event.

The default log level is INFO. Log levels, layout and style and output location can all be configured in

the following file.

[tomcat]/webapps/FusionSecurity/WEB-INF/classes/log4j.properties

The default configuration is shown below:

#ROOT LOGGER

log4j.rootLogger=INFO, fileout, stdout, fusionaudit

log4j.rootLogger.additivity=false

#SPECIFIC LOGGERS

log4j.logger.com.sdmxfusion = INFO

log4j.logger.com.metadatatechnology = INFO

log4j.logger.org.sdmxsource = INFO

Page 25: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

24

#LOG TO FILE (LOCATION, STYLE & LAYOUT)

log4j.appender.fileout=org.apache.log4j.RollingFileAppender

log4j.appender.fileout.file=${catalina.base}/logs/FusionRegistry.log

log4j.appender.fileout.MaxFileSize=1024KB

log4j.appender.fileout.MaxBackupIndex=4

log4j.appender.fileout.layout=org.apache.log4j.PatternLayout

log4j.appender.fileout.layout.ConversionPattern=%p %t %c - %m%n

#LOG TO CONSOLE (STYLE & LAYOUT)

log4j.appender.stdout=org.apache.log4j.ConsoleAppender

log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

log4j.appender.stdout.layout.ConversionPattern=%d %p [%c] - <%m>%n

#LOG TO AUDIT

log4j.appender.fusionaudit=com.sdmxfusion.sdmx.integration.manager.publishe

r.LogPublisher

For more information about logging please read the log4j documentation which is available online.

The version of log4J used in this release is 1.2.14.

Page 26: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

25

8 Annex 1 - Alternative Database Platforms The following list details how to connect to alternative database platforms. Note that in some instances a driver class is required that is not supplied with Fusion Registry. To suport a new driver add the relevant jar file into the following folder: [tomcat]/webapp/FusionRegistry/WEB-INF/lib

8.1.1 Oracle Database Connection database.driver=oracle.jdbc.driver.OracleDriver

database.username=sa

database.password=pwd

database.url=jdbc:oracle:thin:@127.0.0.1:1521:MKYONG

hibernate.dialect=org.hibernate.dialect.OracleDialect

8.1.2 SQL Server Database Connection There are two drivers to connect to SQL Server; the open source jTDS and the Microsoft driver. The driver class and the JDBC URL depend on which one you use.

8.1.2.1 jTDS driver database.driver=net.sourceforge.jtds.jdbc.Driver

database.username=sa

database.password=pwd

database.url=jdbc:jtds:sqlserver://<server>[:<port>][/<database>][;<propert

y>=<value>[;...]]

hibernate.dialect=org.hibernate.dialect.SQLServerDialect

8.1.2.2 Microsoft SQL Server JDBC 3.0 database.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver

database.username=sa

database.password=pwd

database.url=jdbc:sqlserver://[serverName[\instanceName][:portNumber]];d

atabaseName=

hibernate.dialect=org.hibernate.dialect.SQLServerDialect

A complete list of Hibernate dialects is shown in the table below

RDBMS Dialect

DB2 org.hibernate.dialect.DB2Dialect

DB2 AS/400 org.hibernate.dialect.DB2400Dialect

DB2 OS390 org.hibernate.dialect.DB2390Dialect

PostgreSQL org.hibernate.dialect.PostgreSQLDialect

MySQL org.hibernate.dialect.MySQLDialect

MySQL with InnoDB org.hibernate.dialect.MySQLInnoDBDialect

MySQL with MyISAM org.hibernate.dialect.MySQLMyISAMDialect

Oracle (any version) org.hibernate.dialect.OracleDialect

Oracle 9i/10g org.hibernate.dialect.Oracle9Dialect

Sybase org.hibernate.dialect.SybaseDialect

Sybase Anywhere org.hibernate.dialect.SybaseAnywhereDialect

Page 27: Fusion Registry - metadatatechnology.com · 6 3 Configuring Fusion Registry 3.1 Maintenance Tool Registry settings are maintained in the Maintenance Tool. lick on ^Maintenance Tool

26

Microsoft SQL Server org.hibernate.dialect.SQLServerDialect

SAP DB org.hibernate.dialect.SAPDBDialect

Informix org.hibernate.dialect.InformixDialect

HypersonicSQL org.hibernate.dialect.HSQLDialect

Ingres org.hibernate.dialect.IngresDialect

Progress org.hibernate.dialect.ProgressDialect

Mckoi SQL org.hibernate.dialect.MckoiDialect

Interbase org.hibernate.dialect.InterbaseDialect

Pointbase org.hibernate.dialect.PointbaseDialect

FrontBase org.hibernate.dialect.FrontbaseDialect

Firebird org.hibernate.dialect.FirebirdDialect