fusion registry - metadatatechnology.com · 6 3 configuring fusion registry 3.1 maintenance tool...
TRANSCRIPT
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.
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
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
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.
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
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)
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.
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.
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:
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.
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.
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”.
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.
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.
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.
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:
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 #
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
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.
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.
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.
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.
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:
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
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.
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
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