secdocs installation...
TRANSCRIPT
1
Last Update: 10-JUL-2015
SecDocs V2.3A01 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
MySQL Database Configuration ...................................................................................................... 8
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 (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) ..................................................................................... 24
SecDocs Diagnostic Scripts (User: root/secdocs) .................................................................................. 25
Usage of SecDocs With Another Database Software ............................................................................ 28
MySQL ............................................................................................................................................... 28
2
SecDocs Tuning ...................................................................................................................................... 29
Max Number of Parallel Web Service Requests ................................................................................ 30
SecDocs WildFly Memory Shortage .................................................................................................. 30
Transaction Timeout ......................................................................................................................... 31
Database Connection Pool ................................................................................................................ 31
Oracle ............................................................................................................................................ 32
MySQL............................................................................................................................................ 33
HTTPS Connector Configuration ........................................................................................................ 33
Maximal Number of Open Files ......................................................................................................... 34
Reset of the SecDocs Environment ....................................................................................................... 35
3
Software Requirements
At the moment the SecDocs software is released for RedHat Enterprise Linux
RHEL6.5 64bit (AMD64/x64) or higher and SuSE SLES 11SP3 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.4.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.40 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 EE6 application, programmed in Java 7, and runs on a WildFly 8.2.0 application server. The Java SE 7 SDK Update 80 and the WildFly 8.2.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
To use the SecDocs TripleStore functionality additional SQL statements must be performed by the Oracle Administrator. If a SecDocs V2.2 TripleStore is already in use you can skip the following step (TripleStore configuration). For the SecDocs V2.3 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;
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.
dbSID
SID of the Oracle database instance.
dbUser
Name of the Oracle database user.
dbPassword
Password of the Oracle database user.
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.
9
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). These 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.5.5.2.2015060102.x86_64.rpm \
OpenLimit-Middleware-Version-3-Server_CertCRL-
1.5.5.2.2015060102.x86_64.rpm \
OpenLimit-Middleware-Version-3-Server_Database-
1.5.5.2.2015060102.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-
1.5.5.2.2015060102.x86_64.rpm \
OpenLimit-Middleware-Version-3-Server_CertCRL-
1.5.5.2.2015060102.x86_64.rpm \
OpenLimit-Middleware-Version-3-Server_Database-
1.5.5.2.2015060102.x86_64.rpm
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.5.5.2.2015060102.x86_64.rpm \
OpenLimit-Middleware-Version-3-Server_CertCRL-
1.5.5.2.2015060102.x86_64.rpm \
OpenLimit-Middleware-Version-3-Server_Database-
1.5.5.2.2015060102.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
13
way to call the OpenLimit software related commands is by adding the group olsc to
the user accounts that have to call such commands.
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 2014. All rights
reserved.
##$$ OpenLimit Version3, v3.1, v(3.1.5),
b(r1159_erebusJenkins, Debug, 2015-06-01 13:48:26) $$##
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 / Version: 1.5.5.2 /
Release: 2015060102 / Arch: x86_64
OpenLimit-Middleware-Version-3-Server_Database / Version:
1.5.5.2 / Release: 2015060102 / Arch: x86_64
OpenLimit-Middleware-Version-3-Server_CertCRL / Version:
1.5.5.2 / Release: 2015060102 / Arch: x86_64
OpenLimit SignCubes Service Loader v3.1
Copyright (C) OpenLimit SignCubes AG 2014. All rights
reserved.
##$$ OpenLimit Version3, v3.1, v(3.1.5),
b(r1159_erebusJenkins, Debug, 2015-06-01 13:48:26) $$##
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 ready to use, pid:
30093
Stopping the Middleware Version 3 Server (User: root):
# service v3server stop
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.3.1.1-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.3.1.1-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.3.1.1-
1.x86_64.rpm
16
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 7 64bit SDK
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
secdocs SecDocs WildFly server instance
secdocs/configuration SecDocs WildFly server configuration
secdocs/configuration/secdocs SecDocs configuration data
secdocs/log log files
wildfly WildFly 8.2.0 AS Software.
schemas SecDocs Web Services and related data types 2.3 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
17
Archiving.wsdl Archiving WSDL 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.3/query SPARQL related schemata files rdf.xsd result.xsd sparql-protocol-types.xsd xml.xsd 2.3/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.
Special feature of this version: if a version V2.2 was already installed: the
.rpmsave files of the old SecDocs JBoss AS configuration will be moved to the
directory /home/secdocs/.PreV23Backup. If SecDocs V2.3 was installed with the –
relocate option the directory .PreV23Backup is located under the given path (in our
sample above this would be /opt/sd/.PreV23Backup).
18
SecDocs Configuration
File /home/secdocs/jboss/secdocs/configuration/standalone.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 standalone.xml defines two data sources.
19
File /home/secdocs/jboss/secdocs/configuration/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.9_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/secdocs/log .
WildFly console messages: console.log
All WildFly logging messages are displayed on the screen and written to the
file console.log.
WildFly logging file server.log
All WildFly and SecDocs logging messages are written to this file
The SecDocs WildFly application uses the WildFLy logging framework. The logging
configuration is described in the file
/home/secdocs/jboss/secdocs/configuration/standalone.xml
and is part of the logging subsystem:
<subsystem xmlns="urn:jboss:domain:logging:2.0">
...
</subsystem>
With the tool bin/logAdmin you can change the logging configuration in a running
SecDocs WildFly server instance at any time.
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:
# service secdocs start
SecDocs stop:
# service secdocs stop
24
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.2 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 in the directory install/migration of the SecDocs installation:
$ cd install/migration
$ ./startMigration
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/wildfly
WildFly home directory.
A detailed description of the storage recovery tools can be found in the SecDocs manual (chapter: Recovery (Script: recoverFromStorage)).
25
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. Most of the scripts support the option –help to show some usage information. Hint: the scripts marked with * are calling web based services in the running SecDocs WildFly application via the command line tools curl and wget. Beside the described responses you can get also one of the following responses:
1. No response (no output). In this case the SecDocs WildFly application is not started.
2. HTML code response. WildFly was not able to start the SecDocs application and WildFly sends a HTML error message as response.
checkAvailability Checks whether the SecDocs WildFly Services are available or not. This script show (depending on the state) one of the following messages: SecDocs WildFly is not running The SecDocs WildFly server instance isn’t started. SecDocs WildFly services not available The SecDocs WildFly services aren’t (yet) available. SecDocs WildFly services available The SecDocs WildFly services are available.
clearCache Delete the cache of the SecDocs WildFly server instance.
cli / cli.xml Starts the WildFly CLI administration tool for the SecDocs WildFly server instance.
genArchivingSRWsClientStubs This script shows how to create the web service client stub classes from the file schemas/2.3/ArchivingSR.wsdl with the Java SDK wsimport tool. Running this script will create the files wsStubsArchivingSR-2.3.jar and wsStubsArchivingSourcesSR-2.3.jar in the directory jaxws/lib.
getDiagnosticData * A tool to collect diagnostic information.
26
getADOLockStatus * A diagnostic tool for the SecDocs service team.
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.
logAdmin A script to configure loggers and logging levels in a running SecDocs WildFly server instance.
mksha Create a hash value (SHA-256 or SHA-512) for a file and print the hash value as hex string and BASE64 coded. Sample output:
27
SHA-256 hex value
bf5853dd535fc3d9889b98a0d01eb0256b95ebc27b99d0fb6d6a9591f
e2191d4
SHA-256 value in BASE64
v1hT3VNfw9mIm5ig0B6wJWuV68J7mdD7bWqVkf4hkdQ=
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 WildFly logging files
sdjconsole Starts the Java SDK tool jconsole.
sdjinfo Starts the Java SDK tool jinfo.
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
Usage of SecDocs With Another Database Software In the directory /home/secdocs/install/wildfly 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 using
the account secdocs!
MySQL
For a MySQL database configuration you need the following file:
mysql-connector-java-5.1.34-bin.jar (or a newer version)
(download: http://dev.mysql.com/downloads/connector/j/)
Due to license restrictions this file isn’t delivered with the SecDocs software.
With the following command you can exchange the Oracle WildFly module by the
MySQL WildFLy module:
$ cd /home/secdocs/jboss/wildfly/modules/secdocs
$ rm –fr oracle
$ cd /home/secdocs/jboss/secdocs/configuration
$ rm standalone.xml
$ cd /home/secdocs/install/wildfly
$ cd modules/secdocs/mysql/jdbc/main
$ cp <path-to>/mysql-connector-java-5.1.34-bin.jar .
If another version of the driver is used the related file name in the file moduel.xml
must be adapted.
As a final step add the JAR file mysql-connector-java-5.1.34-bin.jar to the SecDocs
environment:
$ cd /home/secdocs/install/wildfly/modules/secdocs
$ cp –r mysql /home/secdocs/jboss/wildfly/modules/secdocs
29
You can achieve the above described exchange also with the help of the script
addMySQLModule (located in the directory /home/secdocs/install/wildfly). After the
exchange you can (optionally) delete the Oracle WildFly module directory:
$ rm -fr /home/secdocs/jboss/wildfly/modules/secdocs/oracle
To prepare a MySQL specific WildFly configuration file standalone.xml you can use
the templates from the directory /home/secdocs/install/wildfly.
You must adapt the following parameters in the file
/home/secdocs/install/wildfly/standalone_datasources_mysql.xml :
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..
After updating the file you can create a new standalone.xml file with the available
template files:
$ cd /home/secdocs/install/wildfly
$ cat standalone_beforeDatasources.xml \
standalone_datasources_mysql.xml \
standalone_afterDatasources.xml > standalone.xml
$ cp standalone.xml /home/secdocs/jboss/secdocs/configuration
SecDocs Tuning In this chapter we describe some parameters that can be adapted to your needs.
30
Max Number of Parallel Web Service Requests
The max number of parallel web service requests is controlled by the attribute task-max-threads <subsystem xmlns="urn:jboss:domain:io:1.1">
<worker name="default" task-max-threads="70"/>
<buffer-pool name="default"/>
</subsystem>
in the file /home/secdocs/jboss/secdocs/configuration/standalone.xml After installation this value is set to 70. Have in mind to change the max pool size for the datasource configurations (s. „Database Connection Pool”) . You can also change the value in a running SecDocs application. Get the current value: /home/secdocs/bin/cli \
--command="/subsystem=io/worker=default/:read-
attribute(name=task-max-threads)"
Set a new value (in this example to 50): /home/secdocs/bin/cli \
--command="/subsystem=io/worker=default/:write-
attribute(name=task-max-threads,value=50)"
To activate the new value you have to stop and start the SecDocs application.
SecDocs WildFly Memory Shortage
The memory heap size of the SecDocs WildFly application is limited by the following line: # SecDocs WildFLy 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
31
Transaction Timeout
In the file /home/secdocs/jboss/secdocs/configuration/standalone.xml you will find the following line: <coordinator-environment default-timeout="1800"/>
This value indicates that the max time for an open transaction is 1800 seconds. This value may be too small for a big amount of data (= big SDOs and/or many signatures in a SDO). The adaption can be done during a running SecDocs application: Get the current timeout value /home/secdocs/bin/cli \
--command="/subsystem=transactions/:read-a
ttribute(name=default-timeout)"
Set a new timeout value. In this example wes et the value to 2000 seconds: /home/secdocs/bin/cli \
--command="/subsystem=transactions/:write-attr
ibute(name=default-timeout,value=2000"
To activate the new value you have to stop and start the SecDocs application.
Database Connection Pool The database connections are managed by the WildFly application server in a connection pool. In the file /home/secdocs/jboss/secdocs/configuration/standalone.xml you will find twotimes (2 datasources!) the following line: <max-pool-size>75</max-pool-size>
I.e. each pool can hold up to 75 (all together 150!) connections to database. This value may be either too big or too small for your use case. The adaption can be done during a running SecDocs application. Get the current pool size: /home/secdocs/bin/cli \
--command="/subsystem=datasources/data-source=ArchiveDS/:read-
attribute(name=max-pool-size)"
32
/home/secdocs/bin/cli \
--command="/subsystem=datasources/xa-data-
source=ArchiveDSXA/:read-attribute(name=max-pool-size)"
Set a new max pool size value. In this example we set the value to 100. /home/secdocs/bin/cli \
--command="/subsystem=datasources/data-
source=ArchiveDS/:write-attribute(name=max-pool-
size,value=100)"
/home/secdocs/bin/cli \
--command="/subsystem=datasources/xa-data-
source=ArchiveDSXA/:write-attribute(name=max-pool-
size,value=100)"
To activate the new value you have to stop and start the SecDocs application. 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.
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
33
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;
HTTPS Connector Configuration
The SecDocs WildFly server instance will be delivered without a HTTPS connector
configuration. You can add such a configuration with the help of the WildFly CLI tool:
batch
#
/core-service=management/security-realm=UndertowRealm:add()
#
/core-service=management/security-realm=UndertowRealm/server-
identity=ssl:add(keystore-
path=SecDocsServerKeyStore.jks,keystore-relative-
to=jboss.server.config.dir,keystore-password=changeit)
#
/core-service=management/security-realm=UndertowRealm/server-
identity=ssl:write-attribute(name=protocol,value=TLSv1)
#
/subsystem=undertow/server=default-server/https-
listener=https:add(socket-binding=https,max-post-
size=157286400,security-realm=UndertowRealm,enabled-
protocols="TLSv1,TLSv1.1,TLSv1.2")
#
34
run-batch
To activate the new configuration you have to stop and start the SecDocs application.
In the above example we have used the file SecDocsServerKeyStore.jks as
keystore file. This file is located in the directory
/home/secdocs/jboss/secdocs/configuration
Attention: the current WildFly version supports only Java keystores (format: JKS).
Typically server certificates are stored in a PKCS7 formatted file. You can convert
such files with the Java SDK Tool keytool in a JKS formatted file
(option –importkeystore).
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 RHEL6 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
35
Reset of the SecDocs Environment 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.