1

Last Update: 20-FEB-2014

SecDocs V2.1A04 Installation Guide

Index Software Requirements ........................................................................................................................... 3

Delivered Software .................................................................................................................................. 4

Configuring the SecDocs Runtime Environment ..................................................................................... 5

Language Environment ........................................................................................................................ 5

SELinux ................................................................................................................................................. 5

File system Configuration .................................................................................................................... 5

Database Configuration ....................................................................................................................... 5

Oracle Database Configuration ....................................................................................................... 6

MySQL Database Configuration ...................................................................................................... 9

Mount Point Creation for Fujitsu ETERNUS CS High End or the NetApp Filer (User: root) ............... 10

Upgrade Installation Hints ................................................................................................................. 11

OpenLimit Middleware Version 3 Server (User: root) ...................................................................... 11

OpenLimit Middleware Version 3 Server Installation ................................................................... 11

Starting of the Middleware Version 3 Server (User: root): .......................................................... 14

Check whether the Middleware Version 3 Server Is Running (User: root): ................................ 15

Stopping the Middleware Version 3 Server (User: root): .............................................................. 15

SecDocs Installation ........................................................................................................................... 15

SecDocs Installation (User: root) ................................................................................................... 15

SecDocs Configuration........................................................................................................................... 18

SecDocs Multi Node Configuration ....................................................................................................... 19

SecDocs Logging .................................................................................................................................... 22

SecDocs Application Start/Stop ............................................................................................................. 22

SecDocs: Further Configuration Steps ................................................................................................... 23

SecDocs Database Migration ................................................................................................................. 23

SecDocs Recovery Tool (recoverFromStorage) ..................................................................................... 24

SecDocs Diagnostic Scripts (User: root/secdocs) .................................................................................. 24

2

Adding the JBoss AS Admin Applications .............................................................................................. 26

SecDocs: English PDF Verification Protocols ......................................................................................... 26

Usage of SecDocs With Another Database Software ............................................................................ 27

MySQL ............................................................................................................................................... 27

SecDocs Tuning ...................................................................................................................................... 28

SecDocs JBoss AS Memory Shortage ................................................................................................. 28

Transaction Timeout ......................................................................................................................... 28

Database Connection Pool ................................................................................................................ 29

Oracle ............................................................................................................................................ 29

MySQL............................................................................................................................................ 30

Maximal Number of Open Files ......................................................................................................... 30

Reset of the SecDocs Environemnt ....................................................................................................... 31

3

Software Requirements

At the moment the SecDocs software is released for RedHat Enterprise Linux

RHEL5.6 64bit (AMD64/x64) or higher and SuSE SLES 11SP2 64bit (AMD64/x64)

or higher operating systems. To run the SecDocs software you need the following

database software component:

Oracle Database 11g Release 2 (11.2.0.2.0 or higher) for Linux 64bit

http://www.oracle.com/technetwork/database/enterprise-

edition/downloads/index.html

A description of the Oracle database software can be found here:

http://www.oracle.com/pls/db112/homepage

As an alternative you can use the following database software:

MySQL 5.5 (5.5.18 or higher) for Linux 64bit

http://dev.mysql.com/downloads/mysql/5.5.html or

http://www.mysql.com/products/

A description of the MySQL database software can be found here:

http://dev.mysql.com/doc/

The database software can also run on another machine.

4

Delivered Software

SecDocs Software SecDocs is a Java EE5 application, programmed in Java 6, and runs on a JBoss AS 5.1.0 application server. The Java SE 6 SDK and the JBoss AS 5.1.0 software are delivered with the SecDocs software.

OpenLimit Software OpenLimit Middleware Version 3 Server (needed to run the SecDocs software)

5

Configuring the SecDocs Runtime Environment

Language Environment

The SecDocs software is based on the UTF-8 encoding. To guarantee proper

input/output behavior make sure that a proper language environment variable is set,

e.g.:

LANG= en_US.UTF-8

or

LANG= de_DE.UTF-8

SELinux

SELinux is enabled by default on RHEL systems. To assure a proper runtime

environment for the SecDocs application (Java based application) SELinux must be

disabled.

File system Configuration

Approximately 12 inodes are needed in the file system to store an SDO. The max

number of inodes in a file system is limited but usually can be raised by tuning the file

system.

Implication: check the max inodes value of your file system configuration before

starting to archive data with SecDocs.

Database Configuration

Have the following configuration requirements in mind for all supported database

systems:

Use UTF-8 as the default character set

The SecDocs database user needs the following permissions: ALTER TABLE,

CREATE TABLE, CREATE TEMPORARY TABLES, DROP TABLE, CREATE

INDEX, SELECT, INSERT, UPDATE, DELETE.

Additional permission for a MySQL database:

LOCK TABLES

6

Oracle Database Configuration

Attention: By default the XA support isn’t configured for an Oracle database instance

but mandatory for the SecDocs application. The Oracle database administrator can

activate the XA support by performing the xaview script:

$ cd $ORACLE_HOME/rdbms/admin

$ sqlplus /nolog

connect sys/<password> as sysdba

@xaview

exit

An Oracle database user (dbUser) is needed to run the SecDocs application:

CREATE USER "dbUser" IDENTIFIED BY "dbPassword"

PROFILE "DEFAULT" DEFAULT TABLESPACE "USERS"

ACCOUNT UNLOCK;

This database user needs the following permissions: GRANT SELECT ON sys.v$xatrans$ TO dbUser;

GRANT SELECT ON sys.dba_pending_transactions TO dbUser;

GRANT SELECT ON sys.pending_trans$ TO dbUser;

GRANT SELECT ON sys.dba_2pc_pending TO dbUser;

GRANT EXECUTE ON sys.dbms_system TO dbUser;

GRANT CONNECT TO dbUser;

GRANT RESOURCE TO dbUser;

7

For the SecDocs TripleStore functionality you have to perform the following SQL statements as Oracle administrator: CREATE GLOBAL TEMPORARY TABLE "dbUser".NNodeQuads(

n0 NUMBER(20) ,

n1 NCLOB ,

n2 NVARCHAR2(10) ,

n3 NVARCHAR2(200) ,

n4 INT

) ON COMMIT DELETE ROWS;

--

CREATE GLOBAL TEMPORARY TABLE "dbUser".NQuads(

t0 NUMBER(20) ,

t1 NUMBER(20) ,

t2 NUMBER(20) ,

t3 NUMBER(20)

) ON COMMIT DELETE ROWS;

CREATE OR REPLACE TRIGGER secDocsJenaTempTables

INSTEAD OF CREATE OR DROP ON "dbUser".schema

WHEN (upper(ora_dict_obj_name) LIKE 'NQUADS' OR

upper(ora_dict_obj_name) LIKE 'NNODEQUADS')

BEGIN

null;

END;

/

8

The following data provided by your Oracle database administrator are needed for the SecDocs application configuration:

dbHost

Name of the machine running the listener of the Oracle database instance.

dbPort

Port number used by the listener of the Oracle database instance.

(Default: 1521)

dbService

Name of the Oracle database service.

dbUser

Name of the Oracle database user.

dbPassword

Password of the Oracle database user.

9

MySQL Database Configuration

For the SecDocs operation you must add the following parameters to the section of your MySQL configuration file: transaction-isolation = READ-COMMITTED

innodb_locks_unsafe_for_binlog = 1

The following data provided by your MySQL database administrator are needed for the SecDocs application configuration

dbHost

Name of the machine running the MySQL database server.

dbPort

Port number used by MySQL database server.

(Default: 3306)

dbName

Name of the MySQL database.

dbUser

Name of the MySQL database user.

dbPassword

Password of the MySQL database user.

10

Mount Point Creation for Fujitsu ETERNUS CS High End or the NetApp Filer

(User: root)

Add a NFS3 mount to the file /etc/fstab as operating system administrator (user root),

e.g. (NetApp filer):

filerHost:/vol/secdocs /filer nfs

rw,nodev,auto,noexec,timeo=600,tcp,vers=3,rsize=32768,wsize=32

768,hard,bg,retry=100 0 0

Attention: the entry above must be added as one line to the file /etc/fstab.

After the first mount change owner/group of the mount point to the SecDocs user

(user: secdocs, group: secdocs).

Contact your ETERNUS CS High End service for the proper mount options.

11

Upgrade Installation Hints

Before upgrading the software you must first remove the old version. After removing

the old software you can install the new version. Before removing the old software

stop the SecDocs application. Before removing the packages make sure that you

have backuped your changed configuration files.

You can get a list of all files in the packages that are marked as a configuration file

with the following command:

# rpm –qc `rpm -qa "secdocs*"`

# rpm –qc `rpm -qa "OpenLimit*"`

You can remove the software with the following command:

# rpm –e `rpm -qa "secdocs*"`

# rpm –e `rpm -qa "OpenLimit*"`

After removing the packages the adapted configuration files only will still be available

in the installation path, renamed by adding the suffix .rpmsave.

OpenLimit Middleware Version 3 Server (User: root)

OpenLimit Middleware Version 3 Server Installation

The software can be found in the directory Linux/pkgs.

The OpenLimit Middleware Version 3 Server software can be installed by the user

root with the rpm command:

# rpm -ivh \

OpenLimit-Middleware-Version-3-Server-

1.3.4.1.2014021803.x86_64.rpm \

OpenLimit-Middleware-Version-3-Server_CertCRL-

1.3.4.1.2014021803.x86_64.rpm \

OpenLimit-Middleware-Version-3-Server_Database-

1.3.4.1.2014021803.x86_64.rpm

If an older version is already installed you must remove the old package before

installing the new one:

# rpm –e `rpm -qa "OpenLimit*"`

After the installation of the package you can view the RPM package name of the new

installed package with the following command:

12

# rpm -qa "OpenLimit*"

OpenLimit-Middleware-Version-3-Server_CertCRL-1.3.4.1-

2014021803

OpenLimit-Middleware-Version-3-Server-1.3.4.1-2014021803

OpenLimit-Middleware-Version-3-Server_Database-1.3.4.1-

2014021803

The installation will add (if not already existing) the Linux user olsc and the related

Linux group olsc. This new user has the home directory /home/olsc. The OpenLimit

Middleware Version 3 Server software will be stored in the directory

/home/olsc/v3server. The RPM installation will also create the RHEL service

v3server. Because you have to configure the installed software this service won’t be

started after the installation.

Installation in another directory:

The OpenLimit software will be installed into the directory /home/olsc by default. This

directory can be changed during installation by using the –relocate option. In the

following example we want to use the directory /opt/olsc as installation location for

the package:

# rpm –ivh --relocate /home=/opt \

OpenLimit-Middleware-Version-3-Server-

1.3.4.1.2014021803.x86_64.rpm \

OpenLimit-Middleware-Version-3-Server_CertCRL-

1.3.4.1.2014021803.x86_64.rpm \

OpenLimit-Middleware-Version-3-Server_Database-

1.3.4.1.2014021803.x86_64.rpm

Hint: the user olsc will be created with the shell

/sbin/nologin

I.e.: nobody (even not the user root) can login to this account. To run a command

under the olsc account anyway you can use as user root the following syntax:

# su - olsc -s /bin/bash –c "<command>"

The above syntax can in principle also be used by other users but in this case the

system administrator (user root) must set a password for the olsc account. Another

way to call the OpenLimit software related commands is by adding the group olsc to

the user accounts that have to call such commands.

13

You can view the version of the installed OpenLimit Middleware Version 3 Server

version with the following command:

# cd /home/olsc/v3server/bin

# ./siqService –v

OpenLimit SignCubes Service Loader v3.1

Copyright (C) OpenLimit SignCubes AG 2012. All rights

reserved.

##$$ OpenLimit Version3, v3.1, v(3.1.3), b(20130613-r253,

Debug, 2013-06-13 17:33:01) $$##

You get a more detailed version information by calling the script getVersion.sh:

# cd /home/olsc/v3server/bin

# ./getVersion.sh

OpenLimit V3 Server identification based on RPM info:

-----------------------------------------------------

* Created with getVersion.sh 1.0.0 (2012-11-06) *

OpenLimit-Middleware-Version-3-Server_CertCRL / Version:

1.3.4.1 / Release: 2014021803 / Arch: x86_64

OpenLimit-Middleware-Version-3-Server / Version: 1.3.4.1 /

Release: 2014021803 / Arch: x86_64

OpenLimit-Middleware-Version-3-Server_Database / Version:

1.3.4.1 / Release: 2014021803 / Arch: x86_64

OpenLimit SignCubes Service Loader v3.1

Copyright (C) OpenLimit SignCubes AG 2012. All rights

reserved.

##$$ OpenLimit Version3, v3.1, v(3.1.3), b(20140217-r595,

Debug, 2014-02-17 14:36:06) $$##

14

The OpenLimit Middleware Version 3 Server uses HTTP/HTTPS connections to the

internet. If internet access is only possible via a proxy (usually the case in a company

network), you have to add the following lines to the section [JavaOptions] of the file

/home/olsc/v3server/bin/bootsvr.cfg:

-Dhttp.proxyHost=<HTTP Proxy Host>

-Dhttp.proxyPort=<HTTP Proxy Port>

-Dhttps.proxyHost=<HTTP Proxy Host>

-Dhttps.proxyPort=<HTTPS Proxy Port>

For access to external LDAP systems (e.g. CRLs) you have to add additionally the

following lines:

-DsocksProxyHost=<SOCKS Proxy Host>

-DsocksProxyPort=<SOCKS Proxy Port>

In the file /home/olsc/v3server/bin/siqSEMkSrv_svr.cfg you can adapt the

following parameters in the section [ECARD] to your environment:

SOAPHost = 127.0.0.1

SOAPPort = 18080

Usually no change is needed for these parameters.

Check for any .rpmsave files in the directory /home/olsc/v3server/bin after updating

the software. These files indicate that you have made changes to a configuration file

after the installation of the software. Make sure that all changes are done again for

the updated software which will again use the default configuration files.

Starting of the Middleware Version 3 Server (User: root):

# service v3server start

Hint: the directory .olsc will be created in the home directory /home/olsc after the first

start ever of the server.

15

Check whether the Middleware Version 3 Server Is Running (User: root):

# service v3server status

v3server: OpenLimit SignCubes V3 Server is running, pid: 22853

Stopping the Middleware Version 3 Server (User: root):

# service v3server stop

SecDocs Installation

SecDocs Installation (User: root)

The software can be found in the directory Linux/pkgs.

The SecDocs software can be installed by the user root with the rpm command:

# rpm –ivh secdocs-2.1.1.4-1.x86_64.rpm

If an older version is already installed you must remove the old package before

installing the new one:

# rpm –e `rpm -qa "secdocs*"`

After the installation of the package you can view the RPM package name of the new

installed package with the following command:

# rpm -qa "secdocs*"

secdocs-2.1.1.4-1

The installation will add (if not already existing) the Linux user secdocs and the

related Linux group secdocs. This new user has the home directory /home/secdocs.

Installation in another directory:

The SecDocs software will be installed into the directory /home/secdocs by default.

This directory can be changed during installation by using the –relocate option. In the

following example we want to use the directory /opt/sd as installation location for the

package:

# rpm –ivh --relocate /home/secdocs=/opt/sd secdocs-2.1.1.4-

16

1.x86_64.rpm

After the installation you will have the following directories in the home directory:

admin

Administration tools directory

recovery contains the script

recoverFromStorage (SecDocs Recovery Tool).

bin

SecDocs start/stop script and diagnostic scripts

docs/licenses

Licenses of the open source software used in SecDocs.

The file ThirdPartyLicenseReadme.txt contains a list of all

used components.

install

Data used by the SecDocs RPM installation and

optional data for the SecDocs JBoss AS instance.

migration This directory contains the script startMigration

which will migrate the SecDocs database

java

Java SE 6 64bit SDK Update 45.

jaxws wsimport generated web service client stub classes

In the directory bin you will find the script

genArchivingSRWsClientStubs. This script shows how to create

the Archiving web service client stub classes from the file

schemas/2.1/ArchivingSR.wsdl.

javadoc JavaDoc of the generated stub classes

lib JAR files with the stub classes and sources

jboss

JBoss 5.1.0 based SecDocs application.

schemas SecDocs Web Services and related data types 2.1 AdminData.xsd SecDocs Administrator specific data types AdminUpdateData.xsd SecDocs Administrator specific data types ArchiveAdmin.wsdl Archiv Administrator WSDL ArchivingSR.wsdl Archiving WSDL sample for the customer specific s submit and retrieve operations Archiving.wsdl Archiving WSDL ArchivingData.xsd Archiving specific data types

17

filter.xsd SDO filter schema file MandantAdmin.wsdl Mandant Administrator WSDL result2.xjb JAXB mapping file fort he wsimport tool secdocs.xsd SecDocs specific data types sparql-protocol-types.xjb JAXB mapping file fort he wsimport tool VerificationInfo.xsd Data types of the element SignatureVerificationInfo of the requestForEvidence Response Archiving operation 2.1/query SPARQL related schemat files rdf.xsd result.xsd sparql-protocol-types.xsd xml.xsd 2.1/samples MultiDocument.xsd Schema for the sample MyDocument SDO MultiDocumentFilter.xml Sample filter

18

SecDocs Configuration

File /home/secdocs/jboss/server/secdocs/deploy/secdocs-ds.xml

After installation the SecDocs application is preconfigured for an Oracle database.

How to use a MySQL database instead is described later (see MySQL).

The following names in the file must be substituted by the values of your Oracle

database environment:

dbHost

Name of the machine running the listener of the Oracle database instance.

dbPort

Port number used by the listener of the Oracle database instance..

(Default: 1521)

dbService

Name of the Oracle database service.

dbUser

Name of the Oracle database user.

dbPassword

Password of the Oracle database user.

Attention: the secdocs-ds.xml defines two data sources.

19

File /home/secdocs/jboss/server/secdocs/conf/secdocs/secdocs.properties

# path to the root directory of the SecDocs archive data

archiveRoot=/filer

#OpenLimit Middelware Version 3 Server host name

# Default: localhost (127.0.0.1)

signCubesHost=127.0.0.1

#OpenLimit Middleware Version 3 Server port number

#Default: 18080

signCubesPort=18080

#Specify a List of Files separated by ;

#These Files are needed by the certified crypto components to write audit log files. If

none of these

#files can be written, the crypto components will cease work and thus any requests to

#the Archiving Web Service will be rejected.

#To ensure that the crypto components work reliably please state at least to files

located in different

#file systems or volumes on the filer.

#secdocs will not start unless at least one of these audit log files is writable

cryptoAuditFiles=<path1>/cryptoLog1.log;<path2>/cryptoLog2.log

About The Property cryptoAuditFiles

This property names a file, or even better a list of files. Multiple file names must be

separated by a semicolon (;). These files are used by the OpenLimit crypto

components that are used by the SecDocs application to write their own audit log

records. If to none of these files can be written any more the OpenLimit crypto

components will stop working!

Best practice is to use at least two files and to use different file systems for each file.

The other properties in this file are described in the SecDocs manual (chapter

“Configuration file secdocs.properties").

SecDocs Multi Node Configuration Optionally SecDocs can be operated in a multi node configuration. In a SecDocs

multi node configuration several SecDocs instances run in an identic configuration

(database and storage) as one system. To activate the multi node mode you have to

add the following entries to the secdocs.properties file of each instance:

20

#For multi node support set this property to true

#Default false

multiNode=true

#Full path to the Hazelcast configuration file

#This property is mandatory in multi node mode and will be

#ignored in single node mode

multiNode.hazelcastConfigFile=<full path>/hazelcast.xml

Hazelcast

The SecDocs instance synchronization is performed with the help of the Hazelcast

software (http://www.hazelcast.com/).. The Hazelcast layer is configured with the

help of the file hazelcast.xml. You will find a template for your own Hazelcast

configuration under

/home/secdocs/jboss/server/secdocs/conf/secdocs/hazelcast.xml.

A description of all configuration options is part of the Hazelcast documentation

(/home/secdocs/docs/hazelcast-2.6_documentation.pdf).

We will explain here only the entries you should adapt to your environment:

<group>

<name>SecDocs</name>

<password>secdocs</password>

</group>

Using an identical network configuration (see entry multicast-group) all instances with

the same group name form one Hazelcast cluster. You can use the group name to

give different SecDocs multi node configurations a unique name.

<port auto-increment="true">5701</port>

Hazelcast uses the port 5701 as local listener port. Is the port already in use,

Hazelcast will increment the port number until a free port is found.

21

<multicast enabled="true">

<multicast-group>224.2.2.3</multicast-group>

<multicast-port>54327</multicast-port>

</multicast>

The Hazelcast cluster uses multicasts for the internal communication. You might be

forced to change the multicast address and/or the multicast port.

<interfaces enabled="false">

<interface>192.168.1.*</interface>

</interfaces>

Hazelcast uses the first found network interface for the network configuration.

Changing the value of the attribute enabled from false to true you can address a

network interface in the interface element.

Multi Node Configuration Recommendation

To have a consistent multi node configuration we suggest that you use for all

instances the same secdocs.properties file and the same hazelcast.xml file. Both files

should be located on a storage that is reachable from all SecDocs multi node

instances. To achieve this, you can use in each SecDocs multi node instance a

secdocs.properties file with the following content (see file

secdocs.properties.multinode):

globalPropertiesFile= <full path>/secdocs.properties

All SecDocs instances use this central, so called, secondary properties file.

Each SecDocs multi node instance uses its own OpenLimit Middleware Version 3

Server instance. You must be aware that own certificates must be imported to the

user trustbase of each OpenLimit Middleware Version 3 Server instance.

22

SecDocs Logging All logging information of the SecDocs application can be found in the directory

/home/secdocs/jboss/server/secdocs/log .

JBoss console messages: console.log

All JBoss logging messages are displayed on the screen and written to the file

console.log.

JBoss logging file server.log

All JBoss and SecDocs logging messages are written to this file

The SecDocs JBoss application uses Log4J as logging framework. The logging

configuration is described in the file

/home/secdocs/jboss/server/secdocs/conf/jboss-log4j.xml

The following logging configuration template files are delivered:

jboss-log4j_prod.xml (standard logging configuration)

Logging configuration for a production environment.

jboss-log4j_debug.xml

Logging configuration for debugging.

.

jboss-log4j_timestamps.xml

Special logging configuration to protocol the time needed for each submitSDO

archiving operation. The related logging messages will be written to the file

secdocs-ts.log in the directory /home/secdocs/jboss/server/secdocs/log.

SecDocs Application Start/Stop The SecDocs RPM installation creates the RHEL service secdocs. I.e.: after each

reboot of the machine the SecDocs application will automatically be started. The

system administrator (user root) can use this service to start and stop the SecDocs

application manually.

SecDocs start:

23

# service secdocs start

SecDocs stop:

# service secdocs stop

SecDocs: Further Configuration Steps Further configuration steps are described in the SecDocs manual „Administration and

Operation“. You will find an overview about the needed steps in the chapter „Step-by-

step guides“

SecDocs Database Migration After upgrading an existing SecDocs 2.0 installation the SecDocs database tables

must be migrated to the new SecDocs version. Without this step the new version of

the SecDocs application won’t start.

This migration task step is performed by the script startMigration. You will find this

script ion the directory install/migration of the SecDocs installation:

$ cd install/migration

$ ./startMigration

Attention (Oracle database): is an Oracle database in use the Oracle database

administrator must enter the following SQL statements for the SecDocs database

user before starting the SecDocs application (s. „Oracle Database Configuration“)

CREATE GLOBAL TEMPORARY TABLE "dbUser".NNodeQuads ...

CREATE GLOBAL TEMPORARY TABLE "dbUser".NQuads ...

CREATE OR REPLACE TRIGGER secDocsJenaTempTables ...

Attention (new feature: Short Subject): If $Subject is used in a filter SecDocs 2.1

will add also up to 200 characters of the given subject into a Short Subject database

field. The migration software will add this new field to the database but won’t fill the

field for already submitted documents. To fill the Short Subject field for already

submitted documents you have to run the SecDocs Recovery Tool with option

update.

24

SecDocs Recovery Tool (recoverFromStorage) You will find the storage recovery tool in the directory admin/recovery in the JAR file

StorageRecovery.jar. You can start this tool easily with the help of the script

recoveryFromStorage.

recoverFromStorage <Optionen>

The storage recovery tool needs a properties file to run. The file recover.properties is

available in the directory admin/recovery. You must adapt the following entire in this

file:

asPath=/home/secdocs/jboss

JBoss AS home directory.

A detailed description of the storage recovery tools can be found in the SecDocs manual (chapter: Recovery (Script: recoverFromStorage)).

SecDocs Diagnostic Scripts (User: root/secdocs) The diagnostics scripts are located in the directory bin of the account secdocs and can be used by the system administrator (user root) and the user secdocs.

genArchivingSRWsClientStubs This script shows how to create the web service client stub classes form the file schemas/2.1/ArchivingSR.wsdl with the Java SDK wsimport tool. Running this script will create the files wsStubsArchivingSR-2.1.jar and wsStubsArchivingSourcesSR-2.1.jar in the directory jaxws/lib.

getDiagnosticData A tool to collect diagnostic information.

getMultiNodeStatus Shows the running SecDocs multi node instanzen in this multi node configuration.

getSecDocsConfigData This script shows important diagnostic information of a running SecDocs application.. Is the SecDocs application not running you won’t get any data.

getStatus Shows whether the SecDocs web services are available or not

25

SecDocs web services available or SecDocs web services NOT available Is the SecDocs application not running you won’t get any data.

getVersion Show the version of the running SecDocs application. Is the SecDocs application not running you won’t get any data.

heapdump Creates a JVM heap dump oft he running SecDocs instance.

jhatRunner Start the Java SDK tool jhat

jstatdRunner / jstatdRunner.policy Skript und configuration file for starting the Java SDK tool jstatd.

jtop Diagnostic tool: starts the Java SE 6 console with the JTop plugin.

olscStatus Shows whether the OpenLimit Middleware Version 3 Server is running or not. (works only if the server is running on the same machine)

removeLogs Removes the SecDocs JBoss logging files

secdocs Same functionality as the RHEL service secdocs

setSecDocsEnv.sh The SecDocs related environment variables are set in this script. All SecDocs scripts do call this script.

sysinfo This script collect important diagnostic information about the machine configuration.

26

Adding the JBoss AS Admin Applications For security reasons the standard JBoss AS administration applications aren’t available in the SecDocs JBoss AS instance. If, by any means, these applications are needed, you can copy them from the directory /home/secdocs/install/jboss/adminApps into the /home/secdocs/jboss/server/secdocs/deploy directory. After restarting the SecDocs application the JBoss AS administration applications are available. Attention: by default anybody can use the JBoss AS administration applications! Make sure that you secure this applications (e.g. by user/password).

SecDocs: English PDF Verification Protocols The verification protocols generated by the OpenLimit Middleware Version 3 Server can optionally be delivered as a human readable PDF report. These reports are by default in German. The reports can also be generated in English. To do so you have to exchange the PDFCreator.jar file with the following commands # service secdocs stop

# cd /home/secdocs/install/openlimit

# cp PDFCreator_en.jar \

/home/secdocs/jboss/server/secdocs/lib/PDFCreator.jar

# cd /home/secdocs/jboss/server/secdocs/lib

# chown secdocs:secdocs PDFCreator.jar

# chmod 640 PDFCreator.jar

# service secdocs start

27

Usage of SecDocs With Another Database Software In the directory /home/secdocs/install/jboss/database you will find templates and the

JDBC JAR file for the Oracle database (preconfigured) and MySQL. Before

exchanging the database configuration you must stop the SecDocs application.

Attention: you must repeat the described steps after each SecDocs installation!

MySQL

For a MySQL database configuration you need the following files:

secdocs-ds_mysql.xml (directory install/jboss/database)

mysql-connector-java-5.1.20-bin.jar (or a newer version)

Due to license restrictions this file isn’t delivered with the SecDocs software.

With the following command you can exchange the Oracle configuration by the

MySQL configuration:

# cd /home/secdocs/install/jboss/database

# cp secdocs-ds_mysql.xml \

/home/secdocs/jboss/server/secdocs/deploy/secdocs-ds.xml

# cd /home/secdocs/jboss/server/secdocs

# chown secdocs:secdocs deploy/secdocs-ds.xml

# chmod 640 deploy/secdocs-ds.xml

# rm lib/ojdbc6_11.2.0.2.0.jar

As a final step add the JAR file mysql-connector-java-5.1.20-bin.jar to the SecDocs

environment:

# cp mysql-connector-java-5.1.20-bin.jar \

/home/secdocs/jboss/server/secdocs/lib

# cd /home/secdocs/jboss/server/secdocs/lib

# chown secdocs:secdocs \

mysql-connector-java-5.1.20-bin.jar

# chmod 640 mysql-connector-java-5.1.20-bin.jar

28

You must adapt the following parameters new file

/home/secdocs/jboss/server/secdocs/deploy/secdocs-ds.xml :

dbHost

Name of the machine running the MySQL database server.

dbPort

Port number used by MySQL database server.er lauscht

(Default: 3306)

dbName

Name of the MySQL database.

dbUser

Name of the MySQL database user.

dbPassword

Password of the MySQL database user..

SecDocs Tuning In this chapter we describe some parameters that can be adapted to your needs.

SecDocs JBoss AS Memory Shortage

The memory heap size of the SecDocs JBoss AS application is limited by the following line: # SecDocs JBoss AS maximum Java heap size

JAVA_MEM_MX=-Xmx4096m

This default value of 4GB may be too small in a production environment. If enough RAM is available in your server machine you can raise this value. You will find the above line in the script file /home/secdocs/bin/secdocs . Examples for possible memory shortages in the standard configuration:

Parallel store of big/many SDOs.

Parallel store of SDOs with many signatures

Transaction Timeout

You will find the following line in the file jboss/server/secdocs/deploy/transaction-jboss-beans.xml :

29

<property name="transactionTimeout">1800</property>

This property limits the maximum time for a transaction to 1800 seconds. This value may be too small for big data (= big SDOs and/or many signatures in a SDO) and can be raised, if necessary.

Database Connection Pool

The database connections are managed in a connection pool by the JBoss application server. In the file jboss/server/secdocs/deploy/secdocs-ds.xml you will find two times (2 data sources!) the following line: <max-pool-size>500</max-pool-size>

I.e.: each data source can use at most 500 (all together 1000!) connections to a database. Depending on your environment you can lower/raise this value.

Oracle

Attention: each database connection uses an Oracle database process. The default value may be too small for your SecDocs configuration. The database administrator can get the configured number of Oracle database processes with the following command: show parameter processes;

Beside other configuration parameters of the database instance you will see a line of the following form: NAME TYPE VALUE

processes integer 150

The database administrator can change this value with the following commands (in this example we change the value to 1100): shut immediate;

startup mount;

alter system set processes=1100 scope=spfile;

alter database open;

shutdown immediate;

startup;

show parameter processes;

30

MySQL

In a standard MySQL configuration the max number of allowed connections (max_connections) is too small for the SecDocs connection pools. The database administrator can get the configured value with the following command: show variables like 'max_connections';

The database administrator can change the value with the following command (in this example we set the value to 1100): set global max_connections=1100;

Maximal Number of Open Files

Each mandant use a permanent open audit log file. Beside this a lot of files are used frequently for most of the web service operations (e.g.: submit a document, retrieve a document, or seal a document). It may happen that the number of open files gets bigger than the value configured in the RHEL5 Linux kernel. The system administrator (user root) can change the value of kernel parameter:

1. Get the current value of the fs.file-max kernel parameter # sysctl –e fs.file-max

2. Change the value of the kernel parameter

Open the file /etc/sysctl.conf

and add a line of the following format with the desired value to this file fs.file-max = <number of max open files>

Example: fs.file-max = 6815744

3. Either reboot the machine or activate the new value immediately.

To activate the new value without reboot use the following command: # sysctl –p

4. Check that the new kernel parameter value is active:

# sysctl –e fs.file-max

31

Reset of the SecDocs Environemnt In a test environment you may want to delete the archive data without reinstalling the

software.

The following data must be deleted:

Database

All tables of the SecDocs database user.

Either use “DROP TABLE tablename;“ for all tables or delete the database

user and create it again

File system

All directories/files in the directory given in the property archiveRoot (file

secdocs.properties).

Attention: if mandant specific mount points are in use you can remove the

related directories (mount points) only if they are no longer needed. The data

in these directories must be deleted.