SignServer
Search signserver.org for:

Miscellaneous

Miscellaneous

Timed Services

A Timed Service (formerly called just service) is a task that is run on a timely basis, performing maintenance tasks like changing active key, or it could generate a report.

A Timed Service framework supports a couple basic properties that is used to calculate when and how a timed service should run. These properties are:

ACTIVE = "TRUE" if the service should be run, otherwise it is disabled.

SINGLETON = "TRUE" if the service only should be run on one of the nodes in the cluster at the time. If it's not set or set to FALSE is the service run simultaneously on all nodes in the cluster. If the node running a singleton service fails will another node sense this and start up the service.

INTERVAL = Property defining the interval in seconds the service should run.

INTERVALMS = Property defining the interval in milliseconds the service should run. Notice that the platform and application server might put a lower bound on the value. The lower limit for GlassFish is by default 7000 milliseconds but can be changed by editing minimum-delivery-interval-in-millis in domain.xml.

CRON = Property that should define a CRON expression of how often the service should run. It should conform to Unix CRON standard. (One and only one of INTERVAL, INTERVALMS or CRON is required)

SignerStatusReportTimedService

*** Overview ***

The SignerStatusReportTimedService is a timed service that outputs status for a set of workers to a file. The information includes each workers crypto token status ACTIVE/OFFLINE and if available also the numbers of signatures that has been performed with the key currently associated with the worker. If the worker has a configured limit of number of signatures, this value is also included.

Format: 

workerName=WORKERNAME1, status=STATUS1, KEY3=VALUE3, KEY4=VALUE4, ...
workerName=WORKERNAME2, status=STATUS2, KEY3=VALUE3, KEY4=VALUE4, ...
workerName=WORKERNAME3, status=STATUS3, KEY3=VALUE3, KEY4=VALUE4, ...
...

Rules:

  • Each line contains a set of properties for one worker.
  • Lines are separated by a system dependent newline character (CR, LF or CRLF).
  • Properties are of form KEY=VALUE and are separated by a comma and a space (", ").
  • The properties "workerName" and "status" are the only ones that must be present.
  • The property "workerName" is always the first property.

Properties:

  • workerName: name of the worker. Example: "sod71" or "sod72"
  • status: status of the worker's crypto token and key. Either "ACTIVE" or "OFFLINE".
  • validityNotBefore: the first date the signer is allowed to sign. Format is java.text.SimpleDateFormat("yyyy-MM-dd HH:mm:ss z").
  • validityNotAfter: the last date the signer is allowed to sign.
  • signings: the number of signatures that has been performed with the key used by this worker.
  • signLimit: the maximum number of signatures this worker is allowed to perfom or -1 if there is no limit.

Examples: 

workerName=Sod71, status=ACTIVE, validityNotBefore=2010-07-05 17:32:36 CEST, validityNotAfter=2010-09-08 17:32:36 EEST, signings=132, signLimit=100000,
workerName=Sod72, status=OFFLINE, validityNotBefore=2010-07-05 17:32:33 CEST, validityNotAfter=2010-09-08 17:32:33 EEST, signings=100000, signLimit=100000,
workerName=Sod73, status=OFFLINE, validityNotBefore=2010-07-05 17:32:33 CEST, validityNotAfter=2010-09-08 17:32:33 EEST, signings=0, signLimit=100000,
workerName=Sod74, status=OFFLINE,

Examples explained:

Sod71 has done 132 signings and is ACTIVE and validityNotAfter indicates that it can continue to sign until 8th September if not the sign limit is reached before

Sod72 has performed all of its 100000 signings and can not sign until it gets a new key and certificate.

Sod73 has not reached its limit and is still in validity time but is OFFLINE for some other reason.

Sod74 is OFFLINE and has no certificate configured.

*** Available Properties ***

WORKERS = Comma separated list of worker names (signers) that should be monitored.

OUTPUTFILE = File that the information will be written to. If the file exists the content will be overwritten. The application server needs to have write access to this file when the service is executed.

Installing a service

To install a service you use the same commands as for installing a worker:

bin/signserver.sh setproperties configuration.properties

Example:

> bin/signserver.sh setproperties doc/sample-configs/qs_signerstatusreport_configuration.properties

Using Glassfish JNDI provider...
===========================================
  Executing Command on host : localhost
===========================================
Configuring properties as defined in the file : doc/sample-configs/qs_signerstatusreport_configuration.properties
Setting the property ACTIVE to TRUE for worker 2
Setting the property INTERVAL to 10 for worker 2
Setting the global property WORKER2.CLASSPATH to org.signserver.server.timedservices.SignerStatusReportTimedService with scope GLOB.
Setting the property WORKERS to PDFSigner1 for worker 2
Setting the property NAME to SignerStatusReporter for worker 2
Setting the property OUTPUTFILE to /tmp/statusreport for worker 2

> bin/signserver.sh reload 2

Using Glassfish JNDI provider...
===========================================
Executing Command on host : localhost
===========================================
SignServer reloaded successfully
Current configuration is now activated.

The Global Configuration Store

The available workers and its crypto tokens and services is configured in something called the global configuration store that is slightly different from a worker configuration.

Is is dynamically configured and activated immediately. I can contain any type of data (in string representation) and can be of two types, either with global scope or node scope. A Global scoped property can be accessed by all nodes in the cluster while a Node scoped property in only used within a node and cannot be accessed by the other nodes.

SignServer specific

Database failure is handled differently. If a node looses connection to the database it put itself in a state called 'unsynchronised' and will continue its operation without storing the data to database by using a cached global configuration. It is possible to later resynchronise one nodes cached global configuration data with the database with a CLI command called 'resync'. But it is only possible to sync one of the nodes global configuration to the database.

Status Repository

The status repository holds local (per JVM) status information (properties) with optional expiration times. After the expiration time the property is not returned.

This could be used by having workers read status from the repository while it is an external service updating it.

Logging

SignServer uses Log4j for logging and there are a few different loggers available where the first two can be useful for audit logging:

  • Worker Log (org.signserver.server.log.IWorkerLogger)
  • System Log (org.signserver.server.log.ISystemLogger)
  • Debug Log (any other class name)

Worker Log

The purpose of the Worker Loggers are to log each transaction handled by the worker. Each worker can choose to have its own configuration for the logger. By default the AllFieldsWorkerLogger is used which used logs all the available fields one after each other separated by semi colons.

Which Worker Logger configuration to use is configured by setting the WORKERLOGGER property to the full class name of the IWorkerLogger implementation in the worker's configuration. Examples: 

WORKERLOGGER=org.signserver.server.log.AllFieldsWorkerLogger
                    
WORKERLOGGER=org.signserver.module.tsa.CustomTimeStampLogger1
                    
WORKERLOGGER=org.signserver.server.log.PatternWorkerLogger
LOGTIMEZONE=GMT
LOGDATEFORMAT=yyyy-MM-dd:HH:mm:ss:z
LOGPATTERN=\$\{(.+?)\}
LOGORDER=AUDIT; LOG_ID: ${LOG_ID}; CLIENT_IP: ${CLIENT_IP}; REQUEST_FULLURL: ${REQUEST_FULLURL}; RequestTime: ${LOG_TIME}; ResponseTime: ${REPLY_TIME}; EXCEPTION: ${EXCEPTION};

System Log

The System Logger is instead for logging all other audit events that are not associated with a particular worker. The default System Logger is the AllFieldsSystemLogger that logs all the available fields one after each other separated by semi colons.

Debug Log

The debug log is just the normal log that can be useful for finding out configuration problems etc.

Configure Log4j for Audit logs

For JBoss you can configure JBOSS_HOME/server/default/conf/jboss-log4j.xml to put the audit logs in a separate file. 

<appender name="SIGNSERVER_AUDIT" class="org.jboss.logging.appender.DailyRollingFileAppender">
    <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
    <param name="File" value="${jboss.server.log.dir}/signserver_audit.log" />
    <param name="Append" value="true" />

    <!-- Rollover at midnight each day -->
    <param name="DatePattern" value="'.'yyyy-MM-dd" />
    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%d %-5p [%c] %m%n" />
    </layout>
</appender>

<category name="org.signserver.server.log.ISystemLogger">
    <appender-ref ref="SIGNSERVER_AUDIT"/>
</category>
<category name="org.signserver.server.log.IWorkerLogger">
    <appender-ref ref="SIGNSERVER_AUDIT"/>
</category>

Installation Packages

From version 3.1 and upwards will there be binary installation packages released alongside the regular source packages. The packages includes all software necessary except for Java, were JDK 1.6+ is required.

At the current moment are the platforms Linux (mainly Debian distribution is tested but it should work for other distributions as well) and Windows XP/2003 supported. The SignServer have two packages, one server part that should be installed in every node in the cluster and one management package containing the CLI.

Using the Installation Packages

The installation package can be used either by using a GUI or on the command line by specifying the argument '-mode text'

For an advanced set-up, for instance if many nodes should be installed with similar configuration, it is possible to preconfigure the installation by specifying a properties file containing some or all the properties asked during the installation. The properties will be used directly during installation and there will be no questions about it. See each package section for details about supported properties.

The configuration file should be in the following locations: 

Unix SignServer Installation            : /etc/signserver/signserver.conf
Windows SignServer Installation         : %SYSTEMROOT%\signserver.conf
                                         (i.e C:\WINDOWS\signserver.conf)

After installation will all the settings be saved to the configuration file by the installation program to simplify re-installation.

If all necessary properties is given in the property file, it's possible to install the package silently by specifying '--mode unattended' on the command line.

*** SignServer Node ***

The server part of the SignServer package contains everything (except Java) that is needed to set-up a node in a cluster. It contains a preconfigured version of JBoss that is ready to use.

The steps performed during the installation process are:

Unix:

  • By default is everything unpacked in /opt/signserver-<version> .
  • If a /etc/signserver/signserver.conf file exists, it's read and used during installation.
  • The user and group 'signserver' is created
  • JBoss init.d script is configured to run at runlevel 3,4,5
  • Directory /etc/signserver/ is created to contain all configuration files
  • Database configuration file /etc/signserver/database-conf.xml is populated.
  • Log configuration file /etc/signserver/log-conf.xml is populated and configured to log to the directory /var/log/signserver
  • If no HTTP SSL certificate is specified in the configuration file will dummy key stores be generated to /etc/signserver.
  • Tomcat is configured for HTTPS and it's configuration file is placed in /etc/signserver/webserver-conf.xml
  • Finally is Jboss started and ready to be used.

Windows:

  • By default is everything unpacked in C:\Program\SignServer\SignServer-<version> .
  • If a c:\WINDOWS\signserver.conf file exists it's read and used during installation.
  • JBoss is configured to be run as a service that is started automatically.
  • Database configuration file <INSTALLDIR>\database-conf.xml is populated.
  • Log configuration file <INSTALLDIR>\log-conf.xml is populated and configured to log to the default directory <INSTALLDIR>\jboss\server\default\log
  • If no HTTP SSL certificate is specified will dummy key stores be generated to <INSTALLDIR>
  • Tomcat is configured for HTTPS and it's configuration file is placed in <INSTALLDIR>\webserver-conf.xml
  • Finally is Jboss started and ready to be used.

The supported properties in the configuration file /etc/signserver/signserver.conf (or %SYSTEMROOT%\signerserver.conf for windows) are:

Property Name Description Example value Where to manually reconfigure
SIGNSERVER_NODEID A unique string value (containing alphanumeric characters only) identifying the node in a cluster. node1 Unix: /etc/signserver/signserver.conf
Windows:
%Systemroot%\signserver.conf
database.type Type of database, currently are Hypersonic, Mysql, Mysql Cluster, Postgres and MS SQL 2000 supported hsqldb, mysql, mysqlndb, postgres, mssql2000 Unix:
/etc/signserver/database-conf.xml
Windows: %Installdir%\database-conf.xml
database.hosts The hostnames of the databases used. (not used for hsqldb). localhost Unix:
/etc/signserver/database-conf.xml
Windows: %Installdir%\database-conf.xml
database.port The port of the database (not used for hsqldb). 1433 Unix:
/etc/signserver/database-conf.xml
Windows: %Installdir%\database-conf.xml
database.name The name of the database (not used for hsqldb). signserver Unix:
/etc/signserver/database-conf.xml
Windows: %Installdir%\database-conf.xml
database.username The username used for authentication against the database (not used for hsqldb). signserver Unix:
/etc/signserver/database-conf.xml
Windows: %Installdir%\database-conf.xml
database.password The password used for authentication against the database (not used for hsqldb). foo123 Unix:
/etc/signserver/database-conf.xml
Windows: %Installdir%\database-conf.xml
httpserver.hostname Hostname used as CN in generated SSL Server certificate. host1.someorg Only used during the of SSL Server certificate generation phase of installation.
httpserver.storepath Path to the key store (JKS file) containing the SSL server certificate. /etc/signserver/tomcat.jks Unix:
/etc/signserver/webserver-conf.xml
Windows: %Installdir%\webserver-conf.xml
httpserver.password Password to unlock the SSL server certificate key store. foo123 Unix:
/etc/signserver/webserver-conf.xml
Windows: %Installdir%\webserver-conf.xml
httptrust.storepath Path to the key store (JKS file) containing the CA trust store. /etc/signserver/truststore.jks Unix:
/etc/signserver/webserver-conf.xml
Windows: %Installdir%\webserver-conf.xml
httptrust.password Password unlocking the CA truststore. foo123 Unix:
/etc/signserver/webserver-conf.xml
Windows: %Installdir%\webserver-conf.xml
syslog.hostname Host name of the Syslog server. This setting also indicates that Syslog should be used. loghost.someorg.org Unix:
/etc/signserver/log-conf.xml
Windows: %Installdir%\log-conf.xml
*** SignServer Management ***

This package installs the CLI interface on the management station (which can be the same as a node). The following steps are performed during installation:

Unix:

  • By default is everything unpacked in /opt/signserver-<version> .
  • If a /etc/signserver/signserver.conf file exists it's read and used during installation.
  • The user and group 'signserver' is created
  • A link from /opt/signserver-<version>/bin/signserver.sh is done to /usr/local/bin.

Windows:

  • Everything is unpacked in C:\Program\SignServer\SignServer-<version> by default.
  • If a c:\WINDOWS\signserver.conf file exists it's read and used during installation.

The signserver.conf supports the following settings:

Property Name Description Example value Where to manually reconfigure
hostname.masternode Hostname of master node in the cluster. node1.someorg.org Unix:
/etc/signserver/signserver.conf
Windows: %Installdir%\signserver.conf
hostname.allnodes Hostname of all hosts in cluster, separated by ';'. node1.someorg.org;node2.someorg.org Unix:
/etc/signserver/signserver.conf
Windows: %Installdir%\signserver.conf

Generating Installation Packages

Before generating a installation package must Bitrock InstallBuilder be installed on a Linux workstation. Then set the build mode in signserver_build.properties and go to src/install/bitrock. If a SignServer package should be generated must the environment variable JBOSS_PREP point the a prepared JBoss installation that will be included in the package.

Then execute the script './buildsignserverpkgs.sh <version>' to start the generation process. The packages will be generated in BitRocks default output directory.

References

Copyright © 2007-2011 SignServer team. All rights reserved.