secdocs installation guidemanuals.ts.fujitsu.com/file/11714/secdocs-installationguideen-v2.2a00.pdf3...
TRANSCRIPT
1
Last Update: 13-JUN-2014
SecDocs V2.2A00 Installation Guide
Index Software Requirements ........................................................................................................................... 3
Delivered Software .................................................................................................................................. 4
Configuring the SecDocs Runtime Environment ..................................................................................... 5
Language Environment ........................................................................................................................ 5
File system Configuration .................................................................................................................... 5
Database Configuration ....................................................................................................................... 6
Oracle Database Configuration ....................................................................................................... 6
Migration of a SecDocs V2.1 TripleStore ......................................................................................... 8
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 .................................................................................................................................... 23
SecDocs Application Start/Stop ............................................................................................................. 23
SecDocs: Further Configuration Steps ................................................................................................... 24
SecDocs Database Migration ................................................................................................................. 24
SecDocs Recovery Tool (recoverFromStorage) ..................................................................................... 25
SecDocs Diagnostic Scripts (User: root/secdocs) .................................................................................. 25
2
Adding the JBoss AS Admin Applications .............................................................................................. 28
SecDocs: English PDF Verification Protocols ......................................................................................... 28
Usage of SecDocs With Another Database Software ............................................................................ 29
MySQL ............................................................................................................................................... 29
SecDocs Tuning ...................................................................................................................................... 30
Max Number of Parallel Web Service Requests ................................................................................ 30
SecDocs JBoss AS Memory Shortage ................................................................................................. 31
Transaction Timeout ......................................................................................................................... 31
Database Connection Pool ................................................................................................................ 31
Oracle ............................................................................................................................................ 32
MySQL............................................................................................................................................ 32
Maximal Number of Open Files ......................................................................................................... 32
Reset of the SecDocs Environemnt ....................................................................................................... 34
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
If no language with UTF-8 encoding is selected (e.g. LANG=en) the SecDocs
application will show a warning on the console and LANG= en_US.UTF-8 will be
used.
To assure the same behavior in all runtime configurations (start as a service or start
from account secdocs) the language to use is set in the script
/home/secdocs/bin/setSecDocsEnv.sh:
SECDOCS_LANG= en_US.UTF-8
or
SECDOCS_LANG= de_DE.UTF-8
Is this variable set (default: en_US.UTF-8) the LANG environment variable will be set
to this value.
The LANG environment variable controls the language used by the messages
created in the SecDocs application. At the moment English (default) and German are
supported out of the box. The related message files are located in the directory
/home/secdocs/jboss/server/secdocs/conf/secdocs/i18n
If a not supported language is set all messages appear in English.
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.
6
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
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
Oracle Database Migration from SecDocs V2.1 to SecDocs V2.2 If you have already a SecDocs V2.1 installation without TripleStore in use you will have the database table Nodes in your schema. This table must be deleted before the first start of SecDocs V2.2: DROP TABLE dbUser.Nodes;
To use the SecDocs TripleStore functionality additional SQL statements must be performed by the Oracle Administrator. Attention: The database structure of the V2.2 TripleStore is incompatible to the old V2.1 database structure! If a SecDocs V2.1 TripleStore is already in use, please read the following section („Migration of a SecDocs V2.1 TripleStore“) before you continue here. For the SecDocs V2.2 TripleStore functionality you have to perform the following SQL statements as Oracle administrator: CREATE GLOBAL TEMPORARY TABLE dbUser.NNodeQuads(
n0 NUMBER(20) ,
n1 NVARCHAR2(2000) ,
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 TABLE dbUser.Nodes (
hash NUMBER(20) NOT NULL,
lex NVARCHAR2(2000),
lang NVARCHAR2(10),
datatype NVARCHAR2(200),
type integer NOT NULL,
PRIMARY KEY (hash)
);
--
EXEC dbms_errlog.create_error_log('dbUser.NODES');
--
CREATE OR REPLACE TRIGGER dbUserJenaTempTables
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;
8
END;
/
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.
Migration of a SecDocs V2.1 TripleStore
The new V2.2 TripleStore structure is incompatible to its V2.1 predecessor. To use
an already existing V2.1 based TripleStore with the new SecDocs V2.2 version you
must first delete the exisiting TripleStore and create it new from scratch.
Step 1: Delete the TripleStore
Perform the following SQL statements as Oracle Administrator:
DROP TRIGGER secDocsJenaTempTables;
DROP TABLE dbUser.NNodeQuads;
DROP TABLE dbUser.NQuads;
DROP TABLE dbUser.Nodes;
DROP TABLE dbUser.Prefixes;
DROP TABLE dbUser.Quads;
DROP TABLE dbUser.Triples;
As described above, the name dbUser must be substituted by the name of the
SecDocs database user.
9
Step 2: Create the new TripleStore database objects
Perform the SQL statements from the previous section to create the SecDocs V2.2
TripleStore.
Step 3: Restore the TripleStore Data
This step is descripted in the section „SecDocs Database Migration“ .
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.
Attention: each Linux user has an UID (User ID) and also each group has a GID
(Group ID). This values must be given to the filer administration.
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.4.1.2.2014050801.x86_64.rpm \
OpenLimit-Middleware-Version-3-Server_CertCRL-
1.4.1.2.2014050801.x86_64.rpm \
OpenLimit-Middleware-Version-3-Server_Database-
1.4.1.2.2014050801.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.4.1.2-
2014050801
OpenLimit-Middleware-Version-3-Server-1.4.1.2-2014050801
OpenLimit-Middleware-Version-3-Server_Database-1.4.1.2-
2014050801
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.4.1.2.2014050801.x86_64.rpm \
OpenLimit-Middleware-Version-3-Server_CertCRL-
1.4.1.2.2014050801.x86_64.rpm \
OpenLimit-Middleware-Version-3-Server_Database-
1.4.1.2.2014050801.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:
# /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(20140319-r647,
Debug, 2014-03-19 12:08:02) $$##
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.4.1.2 / Release: 2014050801 / Arch: x86_64
OpenLimit-Middleware-Version-3-Server / Version: 1.4.1.2 /
Release: 2014050801 / Arch: x86_64
OpenLimit-Middleware-Version-3-Server_Database / Version:
1.4.1.2 / Release: 2014050801 / 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(20140319-r647,
Debug, 2014-03-19 12:08:02) $$##
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.2.1.0-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.2.1.0-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:
16
# rpm –ivh --relocate /home/secdocs=/opt/sd secdocs-2.2.1.0-
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.2/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.2 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 submit and retrieve operations Archiving.wsdl Archiving WSDL
17
ArchivingData.xsd Archiving specific data types filter.xsd SDO filter schema file MandantAdmin.wsdl Mandant Administrator WSDL result2.xjb JAXB mapping file for the wsimport tool secdocs.xsd SecDocs specific data types sparql-protocol-types.xjb JAXB mapping file for the wsimport tool VerificationInfo.xsd Data types of the element SignatureVerificationInfo of the requestForEvidence Response Archiving operation 2.2/query SPARQL related schemata files rdf.xsd result.xsd sparql-protocol-types.xsd xml.xsd 2.2/samples MultiDocument.xsd Schema for the sample MyDocument SDO MultiDocumentFilter.xml Sample filter
Check for any configuration files with the suffix .rpmsave 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.
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.7_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.
22
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.
Hint For The First Start of a Multi Node Configuration
The first start of a multi node configuration after a SecDocs installation should begin
with starting up one multi node instance only. If this instance is ready to run you can
start all the other instances of your multi node configuration. If you start all instances
at once, some of the instances may abort with the following error message in the log
file:
ORA-01408: such column list already indexed
Even if this happens you can restart the aborted multi node instances without any
further problems.
23
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:
24
# 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.1 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 TABLE "dbUser".Nodes ...
EXEC dbms_errlog.create_error_log('"dbUser".NODES');
CREATE OR REPLACE TRIGGER dbUserJenaTempTables ...
TripleStore Migration
The content of a SecDocs V2.1 TripleStore (s. „Oracle Database Configuration“) can’t
be migrated into the SecDocs V2.2 based TripleStore structure. To have the old data
also available in the new version you must delete the old TripleStore and create it
from scratch again in the new V2.2 structure. The deletion of the old TripleStore is
25
described in the section „Oracle Database Configuration“. After migrating SecDocs
database to the new V2.2 structure you can recreate the TripleStore with the
SecDocs Recovery Tool (command update).
A detailed description of the storage recovery tools can be found in the SecDocs
manual (chapter: Recovery (Script: recoverFromStorage)).
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. Hint: the scripts marked with * are calling web based services in the running SecDocs JBoss application via the command line tools curl. Beside the described responses you can get also one of the following responses:
1. No response (no output). In this case the SecDocs JBoss application is not started.
2. HTML code response. The JBoss was not able to start the SecDocs application and the JBoss sends a HTML error message as response.
genArchivingSRWsClientStubs This script shows how to create the web service client stub classes form the file schemas/2.2/ArchivingSR.wsdl with the Java SDK wsimport tool. Running
26
this script will create the files wsStubsArchivingSR-2.2.jar and wsStubsArchivingSourcesSR-2.2.jar in the directory jaxws/lib.
getDiagnosticData * A tool to collect diagnostic information.
getMultiNodeStatus * Shows the running SecDocs multi node instances 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 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 of the 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)
27
removeLogs Removes the SecDocs JBoss logging files
sdsyslog Helper script for creating syslog messages in SecDocs scripts.
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.
28
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
29
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.3.0.jar
# rm lib/orai18n_11.2.0.3.0.jar
As a final step add the JAR file mysql-connector-java-5.1.27-bin.jar to the SecDocs
environment:
# cp mysql-connector-java-5.1.27-bin.jar \
/home/secdocs/jboss/server/secdocs/lib
# cd /home/secdocs/jboss/server/secdocs/lib
# chown secdocs:secdocs \
mysql-connector-java-5.1.27-bin.jar
# chmod 640 mysql-connector-java-5.1.27-bin.jar
30
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.
Max Number of Parallel Web Service Requests
The max number of parallel Web Service requests is limited by the parameter maxThreads in the HTTP connector configuration of file /home/secdocs/jboss/server/secdocs/deploy/jbossweb.sar/server.xml : <!-- A HTTP/1.1 Connector on port 8080 -->
<Connector protocol="HTTP/1.1"
URIEncoding="UTF-8"
port="8080" address="${jboss.bind.address}"
maxThreads="70" acceptCount="20"
connectionTimeout="10000" redirectPort="8443" />
If another upper limit is desired (either lower or higher) this number must be adapted. By default this value is set to 70. If you change this value you must also adapt the max pool size of the database connection pools (s. „Database Connection Pool).
31
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/setSecDocsEnv.sh . 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 /home/secdocs/jboss/server/secdocs/deploy/transaction-jboss-beans.xml : <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 /home/secdocs/jboss/server/secdocs/deploy/secdocs-ds.xml You will find two times (2 data sources!) the following line: <max-pool-size>100</max-pool-size>
I.e.: each data source can use at most 100 (all together 200!) connections to a database. Depending on your environment you can lower/raise this value. Attention: if SecDocs is used in a Multi Node configuration you have to multiply the number of connections by the number of instances in use. The following examples for Oracle and MySQL are given for a Single Node SecDocs configuration.
32
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 250): shut immediate;
startup mount;
alter system set processes=250 scope=spfile;
alter database open;
shutdown immediate;
startup;
show parameter processes;
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 250): set global max_connections=250;
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:
33
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
34
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.