DAC Installation Guide

coldwaterphewΔιακομιστές

17 Νοε 2013 (πριν από 3 χρόνια και 11 μήνες)

233 εμφανίσεις



















DAC
Installation Guide






1203137.008





© Deltares, 2011





Erik de Rooij









Titel

DAC
Installation Guide



Opdrachtgever

Deltares

Project


Pagina's

16









Abstract

This document describes all aspects of the Data Access Component; description of the
components, how to install and how to secure the webservices.






Version

Datum

Auteur

Paraaf

Review

Paraaf

Approved

Paraaf


June
. 201
3

Erik de Rooij


Daniel
Twigt





















Status

Final







17 november 2013
, voorlopig



DAC
Installation Guide


i


Contents

3.1

Java

2

3.2

Tomcat

2

3.3

FEWS bin + region
-
home

2

3.
4

Data Access Component

3

3.5

FEWS PI web service

4

3.6

FEWS client server system and central database

5

5.1

Aanmaken certificaten

Error! Bookmark not defined.

5.1
.1

Stap 1: Creëer client en server key
-
pairs / certificaten:

8

5.1.2

Stap 2: Configureer Tomcat om over HTTPS te communiceren

9

5.1.3

Stap 3: Configureer FEWS client om gebruik te maken van HTTPS

10







17 november 2013
, voorlopig



DAC
Installation Guide


1


1

Introduction

The FEWS Data Access Component (DAC) is a web application that al
lows Webservices to
directly access the FEWS system. The DAC communicates directly with the FEWS data

store
component
. The database is created and updated by a FEWS Operator Client system.

Webservices hosted in a Tomcat container can access the DAC and exc
hange data with the
underlying FEWS system.


2

Component Overview

The following compon
en
ts are requi
r
ed to setup the DAC.



Java Runtime En
v
ironment
7

(JRE)
:

Needed to
run
Tomcat.


Tomcat
7
:
Is
a

open

source web container
developed by the
Apache Software Fo
undation.
Tomcat
is a web

container that enables the hosting of webservices
.


FewsPi

webservice
:
This is a WAR file that can be loaded into the Tomcat web container.
The FewsPi webservice is not part of the DAC. It provides an example of how the DAC can
be

used. What the FewsPi webservice does is exchange data with a FEWS central database
using the
DataAccessComponent.


Data Access Component (DAC)
:

This
is a component that runs as a Global Resource in
Tomcat. This component provides the communication betwee
n the webservice (FewsPi) and
the FEWS central database. It is required that the DAC connects directly to the FEWS central
database.


F
EWS

bin +
region
home
(
v2012.0
2 or later
):


The bin
-
directory contains all FEWS libraries.
The region home directory cont
ains the basic configuration files to connect to the FEWS
system. They are both needed by the DAC.


FEWS Central Database
:

This is the central database that is installed and used by the
FEWS client


server system. The following database flavours are suppo
rted: Oracle,
Postgresql and MS Sql Server.


FEWS
client server

system
:
The FEWS client server system is outside the scope of this
document. For more information on this topic we refer to the System Administration Guide
that is
provided when installing a
client server system.










2


12 maart 2012, final


DAC
Installation Guide



Figure
2
.
1

Deployment view
FewsPiService

webservice

3

Installation

3.1

Java

Download
the
lat
est

stable version for the

JRE

(
Version

1.
7 +
)
.
Select the correct version
depending on the operating system on which to install

(Windows o
r

Linux).

Follow the provided instructions
.

3.2

Tomcat

Download de
latest stable versio
n for

Tomcat
(Version

7 +
)
.
Select the correct version
depending on the operating system on which to install (Windows or

Linux).

Follow the provide instructions
.

3.3

F
EWS

bin

+
region
-
home

Within the installation directory of Tomcat create two subdirectories,
one with the name

bin_<version>


(e.g. bin_201202)
,

and one with the
FEWS

region
-
home’
name (preferably no
spaces). Into the bin directory copy all the files from the fews
-
stable
-
<version>
-
bin
-
<buildnr>.zip. In the ‘region
-
home’ directory copy the files
‘clientConfig.xml’ and
‘log4j.properties’.

In the example files below replace all values marked in
pink
by appropriate
values.





17 november 2013
, voorlopig



DAC
Installation Guide


3


clientConfig.xml
:


log4j.properties:


3.4

Data Access Component

Copy the f
ollowing two files to the <Tomcat installation>/lib directory:

-

Dac.jar

(
provided by
Deltares)

-
Log4j
-
<version>.jar
(
extract from FEWS
bin
directory
)

Next update the Tomcat configuration file
<Tomcat installation
>/conf/server.xml
as described
below
:


Add

DacLifecycleListener
:

Between the
element <
Host
> ... </
Host
>
add following line (
bold
)
:

# This configuration file should be placed in the FEWS region home directory in order for DAC to load it.

# Chang
e the <region_name> to match name of actual region.

log4j.debug
=true

log4j.rootLogger
=INFO, DAC


# Define all the appenders

log4j.appender.DAC
=org.apache.log4j.DailyRollingFileAppender

log4j.appender.DAC.File
=${catalina.base}/logs/DAC_
<fews_home_dir>
.log

l
og4j.appender.DAC.Append
=true

log4j.appender.DAC.Encoding
=UTF
-
8

# Roll
-
over the log once per day

log4j.appender.DAC.DatePattern
='.'yyyy
-
MM
-
dd'.log'

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

log4j.appender.DAC.layout.ConversionPattern = %d
[%t] %
-
5p %c
-

%m%n


log4j.logger.nl.wldelft.fews=INFO</clientConfiguration>

<?
xml

version
="1.0"
encoding
="UTF
-
8"?>

<
clientConfiguration

xmlns
="http://www.wldelft.nl/fews"
xmlns:xsi
="http://www.w3.org/2001/XMLSchema
-
instance"
xsi:schemaL
ocation
="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/clientConfig.xsd">


<
databaseServer
>




<!

Keuze uit: postgresql, oracle of
sqlserver

--
>


<
dbServerType
>
postgresql
</
dbServerType
>




<
dbServerName
>
db_s
erverhostname
</
dbServerName
>


<
dbServerPort
>
db_oort

</
dbServerPort
>


<
dbInstanceName
>
database naam
</
dbInstanceName
>


<
dbInstanceUser
>
gebruiker
</
dbInstanceUser
>


<!
--

<dbInstancePassword>
clear text
password</dbInstancePasswor
d>
--
>


<
dbInstanceEncryptedPassword
>
encrypted password
</
dbInstanceEncryptedPassword
>


</
databaseServer
>

</
clientConfiguration
>








4


12 maart 2012, final


DAC
Installation Guide




Add the
DAC
as
‘global resource’
:

Within the

element <
GlobalNamingResources
> ... </
GlobalNamingResources
>
add the
following lines
(
replac
e all fields marke

as

pink
)
:




3.5

FEWS PI

web service

Make a directory
‘fews’

within the

<Tomcat

installation
>
directory
.
Copy the
FewsPiService.war

file provided by
Deltares

into this directory
.

Next a configuration file must
be

created. The name of this file will be used by Tomcat in the URL path so choose it wisely
(no spaces). The extension of this file must be XML.
(bv:
<fews_home_dir>
.xml).



For Tomcat to load the configuration XML file it must be placed in the directory <T
omcat
installation>/conf/Catalina/localhost. Once the XML file is copied into this directory Tomcat will
automatically load the FewsPiService.war.


The content of this file is as follows. Replace all fields marked in

pink

by

installation specific
values
.

<Host
name
="
localhost
"
appBase
="
webapps
"


unpackWARs
="
true
"
autoDeploy
="
true
">

...


<!
--

Class that listens to Tomcat lifecycle events in order to shutdown DataAcces
sComponent
--
>


<Listener

className
=
"nl.wldelft.fews.system.data.dac.DacLifecycleListener"

/>

...

</Host>

<!


Defin
e

DAC global resource in
the

file
server.xml. Pa
ths must be
absolute:

windows: d:/fews/bin or

d:/fews/
<region
-
home>
; linux: /fews/bin of
/fews/
<region
-
home>

--
>

<
GlobalNamingResources
>

...

<
Resource

name
="
global_resource_nam
e
"

auth
="Container"


type
="nl.wldelft.fews.system.data.dac.DataAccessComponent"





factory
="nl.wldelft.fews.system.data.dac.DacBeanFactory"



regionHome
="
absolut
e

pa
th

to
fews_
region_
home_dir
"


binPath
="
absolut
e

pa
th

to

fews_bin_dir
"


closeMethod
="
stop
"

/>


</
GlobalNamingResources
>




17 november 2013
, voorlopig



DAC
Installation Guide


5




3.6

FEWS

client server

syste
m
and

central database


The installation and configuration of the FEWS client server system lies outside the scope of
this document. For more information on this topic refer to the

Delft
-
FEWS Client
-
Serv
er
System Installation Guide.


It is possible to add a configuration file to the general FEWS configuration, that can be used
to configure the FewsPiService webservice. This configuration file is to be placed in the
PiClientConfigFiles directory of FEWS. T
he name of this file must match the name configured
<?xml version="1.0" encoding="UTF
-
8"?>

<!
--


Licensed to the Apache Software Foun
dation (ASF) under one or more


contributor license agreements. See the NOTICE file distributed with


this work for additional information regarding copyright ownership.


The ASF licenses this file to You under the Apache License, Version 2.0


(the "L
icense"); you may not use this file except in compliance with


the License. You may obtain a copy of the License at



http://www.apache.org/licenses/LICENSE
-
2.0



Unless required by applicable law or agreed to in writing, software


distributed und
er the License is distributed on an "AS IS" BASIS,


WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.


See the License for the specific language governing permissions and


limitations under the License.

--
>


<!
--

Location of speci
fic AI war file. (Can be a symlink)
--
>

<
Context

docBase
="${catalina.home}/fews/
FewsPiService
.war"
antiJARLocking
="true"
crossContext
="true" >


<!



clientConfigFileId’
points to a

FEWS configuration file

in de FEWS
configuration directory

‘PiClientConf
igFiles’.
--
>


<
Parameter

name
="clientConfigFileId" value="
fewspiservice
.properties
"
override
="false"/>


<!

resourceId
must match the ‘name’ of
‘ResourceLink’
below

--
>


<
Parameter

name
="resourceId"
value
="

resourcelink_na
m
e

"
override
="false"/>


<
Parameter

name
="serviceName"
value
="
FewsPiService
"
override
="false"/>


<
Parameter

name
="namespaceUri"
value
="http://
fewpiservice
.wldelft.nl"
override
="false"/>


<
Parameter

name
="portName"
value
="
FewsPiServicePort
"
override
="false"/>


<!




fewspi
_config_naam’
must match the file name of this configuration file without the XML extension.

--
>


<
Parameter

name
="wsdl"
value
="http://localhost:
<port>
/
fewspi
_config_nam
e
/
fewspiservice
?wsdl"
override
="false"/>


<!


m a k e

‘ r e s o u c e l i n k
_ n a m e

e q u a l t o t h e


r e s o u c e l i n k _ n a m e
’ d e s c r i b e d b y r e s o u r c e i d a b o v e
.

global_resource_name
’ m
ust be the same as the
DAC r
e
sou
r
ce nam
e

in
the file

‘server.xml’
--
>


<
ResourceLink

name
="
resoucelink_nam
e
"


global
="
global_resource_nam
e
"



type
="nl.wldelft.fews.system.data.dac.DataAccessComponent"/>







<
Loader

loaderClass="nl.wldelft.fews.system.data.dac.DacClassLoader"
delegate
="true"/>





</
Context
>








6


12 maart 2012, final


DAC
Installation Guide


in the field


clientConfigFileId
’ described in the above FewsPiService configuration file. The
contents of the file is as follows. Again replace all fields marked in
pink

by installation specific
values
.


FewsPiService
.properties:



4

Starting and Stopping the system

Stopping and starting of the FewsPi webservice can be done through the manager console
of Tomcat

(
Figure
4
.
1
)
.

This can be accessed via th
e following URL
:

http://<
serverhostname
>:<
http
_poort
>
/manager/html

o
r

over https

https://<serverhostname>:<https_poort>/manager/html.


serverhostname

= nam
e

of the
server
on which
Tomcat
runs
.
In the case Tomcat is running
locally use

‘localhost’

http
_po
r
t

= port

on which

T
omcat

listens to
HTTP
traffic
.
This is configured during installation
.
Default = 8080.

https_port

= port
on which T
omcat
listens to
HTTPS
traffic
.
This is configured during
installation. Default =
8443.


If the FewsPi webservice loaded c
orrectly it can be found in the list of applications. The name
will match the name given to the configuration XML file that was described in section
3.5
.

Using the link options
‘start’
and

‘stop’
it is possible to respectively
start

and

stop

the service
.


# This configuration file should be placed in the FEWS con
f
iguration
directory PiClientConfigFiles. This file contains

# FEWS specific configuration information for the
FewsPiService

webservice.

# All fields are optional

#
Id

from the Filters.xml file in the RegionConfigFiles directory. Filter id defines all timeseries t
hat are
accessible for

# reading by

the
FewsPiService

service.

If omitted all timeseries configured in Filters.xml can be accessed.

FILTERID
=filter_id

# Id of the flagconversion file to use. Flagconversions are located in configuration folder FlagConversio
nsFiles

EXPORT_FLAGCONVERSION_ID=
export_flagconversions_id

# Id of the unitconversion file to use. Unitconversions are located in configuration folder UnitConversionsFiles

EXPORT_UNITCONVERSION_ID=
export_unitconversions_id

# Id of the id
-
mapping file to us
e. Id Mappings are located in configuration folder IdMapFiles

EXPORT_IDMAP_ID=
export_id_map

# Value to which NaN values are to be mapped. If omitted then NaN are exported as NaN

MISSING_VALUE
=
-
999

# Option to skip exporting NaN values. If omitted defaults
to true.

OMIT_MISSING_VALUES=
true

# Option to convert absolute level values to values relative to the location level. If omitted defaults to false.

CONVERT_DATUM
=false




17 november 2013
, voorlopig



DAC
Installation Guide


7


Whenever the Tomcat configuration changes or the DAC jar is updated
(
3.2

en
3.4
)
then it is
necessary to restart the whole Tomcat instance
.
For details on this please re
fer to the

Tomcat

manual
.



Figure
4
.
1
Tomcat Manager console




5

Security

To prevent unauthorised parties accessing the FEWS Pi webservice it is possible to make
use of
Secure Socket Layers (SSL)
.
In this si
tuation all data transferred between the client
and the
FEWS
PI w
eb
service

is encrypted

(
see

Figure
2
.
1
)
.
For this we make use of both
client and server certificate files.

This implies that
Tomcat
asks all clients
accessing Tomcat,
for a certificate
.
Once Tomcat has verified this certificate will the client be granted access to
the FEWS Pi

webservice.
The same goes in opposite direction. All clients accessing the
Tomcat server can request a certificate from Tomcat
.
This certificate can be checked to verify
that the client is dealing with the correct Tomcat instance.


5.1

Create Certificates









8


12 maart 2012, final


DAC
Installation Guide


5.1.1

Step

1:
Create client and server key
-
pairs

/
certificates
:


All certificates will be generated using the program ‘keytool’, that ca
n be found in the JRE

bin
directory

(
see

3.1
). In
these examples

replace
<serverhostname>

by the name of the Tomcat
server
.
Note that the
client
-
keystore

and


truststore

should have the same
passw
o
rd

as
shown in this example
.


Create

the

server key store




This command
does not generate any output message
.


Export
the

server
certificate




This command generates the following response
:

Certificate stored

in file <serverh
ostname>.cer>


Create

the

client trust store




This command shall ask if the certificate can be trusted
.
Answer
‘yes’
.


Then a similar type of text will appear
:

Owner: CN=<serverhostname>, OU=FEWS, O=Deltares, L=Delft, ST=Zuid
-
Holland, C=NL

Issuer: CN=<serverhostname>, OU=FEWS, O=Deltares, L=Delft, ST=Zuid
-
Holland, C=NL

Serial number: 48f489c8

Valid from: Tue Oct 14 14:00:08 CEST 2008 until: Mon Jan 12 13:00:08 CET 2009

Certificate fingerprints:

MD5: 27:43:89:28:F7:71:7B:61:9B:4
E:E1:18:02:CA:86:FC

SHA1: 23:A9:F5:13:F0:61:05:32:36:89:BD:6E:67:C2:3A:5E:30:F1:1C:7B

Trust this certificate? [no]: yes

Certificate was added to keystore

[Storing client.truststore]


Create the
client key store


keytool
-
import
-
v
-
alias
<serverhostname
>
-
keystore client.truststore
-
storepass d3lftf3ws

-
fi
le
<serverhostname>.
cer

keytool
-
export
-
alias
<serverhostname>

-
file
<serverhostname>
.cer
-
storepass d3lftf3ws

-
keystore
<server
hostname>
.keystore

keytool
-
genkey
-
alias <serverhostname>
-
keyalg RSA
-
validity 2000
-
keypass d3lftf3ws

-
storepass d3lftf3ws
-
keystore
<serverhostname>
.keystore
-
dname "CN
=<serverhostname>
,
OU=FEWS, O=
<Bedrijfsnaam>
, L=
<Locatie>
, S=
<Provincie>
, C=NL"





17 november 2013
, voorlopig



DAC
Installation Guide


9



This command do
es not generate any output message.


Export
the
client
certificate




This command generates the following message


Certificate stored in file client.cer


Create the
server trust store




This command

will ask the question if the certificate can be trusted
.
Answer
‘yes’
.


Afterward a similar type of text will be displayed
:

Owner: CN=localhost, OU=FEWS, O=Deltares, L=Delft, ST=Zuid
-
Holland, C=NL

Issuer: CN=localhost, OU=FEWS, O=Deltares, L=Delft, ST=Zui
d
-
Holland,
C=NL

Serial number: 48f48aa3

Valid from: Tue Oct 14 14:03:47 CEST 2008 until: Mon Jan 12 13:03:47 CET
2009

Certificate fingerprints:

MD5: 2A:60:D3:85:02:E4:4B:52:1A:2B:C9:B6:F8:E7:E3:EB

SHA1: 15:0B:8F:D1:BC:2A:AB:78:F7:F8:D2:99:AF:06:A6:BC:B6:2F
:05:C0

Trust this certificate? [no]: yes

Certificate was added to keystore

[Storing <serverhostname>.truststore]


5.1.2

St
e
p 2:
Configure Tomcat to communicate
over HTTPS


De Tomcat server

must be configured to communicate over

HTTPS
using the generated

key
-

en
trust
-

stores.


Copy
the server key store
and

trust store


Copy the files

<serverhostname>.keystore
and

<serverhostname>.truststore

generated in the
previous section to the directory

<Tomcat_
installation
>/conf/ssl

.


Configure

the

SSL/TLS Connector

In the
file
<Tomcat_
installation
>/conf/server.xml

add the configuration
(
this is already present
but needs to be un
-
commented
):


keytool
-
import
-
v

alias localhost
-
keystore
<serverhostname>
.truststore
-
storepass
d3lftf3ws

file client.cer

keytool
-
export
-
alias localhost

file client.cer
-
storepass d3lftf3ws

keystore client.keystore

keytool
-
genkey
-
alias localhost
-
keyalg RSA
-
validity 2000
-
keypass d3lftf3ws
-
storepass
d3lftf3ws
-
keystore clien
t.keystore
-
dname "CN=localhost, OU=FEWS, O=
<Bedrijfsnaam>
,
L=
<Locatie>
, S=
<Provincie>
, C=NL"









10


12 maart 2012, final


DAC
Installation Guide




To switch off all communication over
HTTP
comment out the
HTTP Connector

using the tags

<!
--

--
>
.




5.1.3

St
ep

3:
Configure
FEWS
client
to use

HTTPS


Copy the
client key store
and

trust store

Copy the files client.keystore and
client.truststore
,
generated in the previous section to the
FEWS_HOME_DIR
of the
FEWS
client.


Configure the

HTTP
connection

All import files in the

ModuleInstanceConfigFiles
directory that use the FewsPi webservice
.
Must now reference the HTTPS URL

of
Tomcat:


<serverUrl>https://<serverhostname>:8443/<service_nam
e
>/
fewspiservice
?wsdl</serverUrl>


<!
--

A "Connector" represents an endpoint by which requests are received


and responses are returned. Documentation at :


Java H
TTP Connector: /docs/config/http.html (blocking & non
-
blocking)


Java AJP Connector: /docs/config/ajp.html


APR (HTTP/AJP) Connector: /docs/apr.html


Define a non
-
SSL HTTP/1.1 Connector on port 8083


--
>

<!
--

<Connector port=
"808
0
" protocol="HTTP/1.1"


connectionTimeout="20000"


redirectPort="8443" />
--
>

<!
--

Define a SSL HTTP/1.1 Connector on port 8443


This connector uses the JSSE configuration, when using APR, the


connector should be using the OpenSSL style configuration


descr
ibed in the APR documentation
--
>



<Connector
port
="8443"
maxThreads
="150"
scheme
="https"
secure
="true"
SSLEnabled
="true"
keystoreFile
="${catalina.home}/conf/ssl
/<serverhostname>.
keystore"
keystorePass
="d3lftf3ws"
truststoreFile
="${catalina.home}/c
onf/ssl/
<serverhostname>.
truststore"
truststorePass
="d3lftf3ws"



clientAuth
="true"
sslProtocol
="TLS"/>