NAME

Installation of the Hammerserver


INTRODUCTION

This document describes the installation and deployment of the HammerServer. The following topics are covered:

Software:

How to install the necessary software.

Initialization:

Action necesssary to initialize the HammerServer's database back end and to configure the server.

Administration:

Starting, stopping, administration and monitoring.


SOFTWARE INSTALLATION

The installation of all required software consists of no more than unpacking the distribution in a self-chosen directry, e.g. /opt/hammerserver. All necessary files are created under this 'home' directory. Notably the following subdirectories are created:

bin:

Directory with all binaries, such as the stop/start script. For ease of use, you can extend the PATH environment to include this directory.

etc:

Miscellaneous other files, such as: configuration, database definition scripts.

doc:

The documentation for the HammerServer, including this document.

log:

Directory where activity is logged.

mod:

Perl modules which are used by the server and by hsclient, the command-line client script.

offload:

Offloaded data (database cleaning results) are created here.

The directory bin furthermore contains the script hsenv. After unpacking the software, bin/hsenv may be called to verify that all external Perl modules are present. When hsenv reports missing modules, then these must be added to the Perl installation using cpan.


INITIALIZATION

Back End Initialization

The storage back end of the HammerServer must currently be a either:

If you choose to use the HammerServer with a flat-file back end, which is perfectly good for (a) testing, (b) really fast insertion and retrieval, but slow searching and bulk-validations, or (c) having your data on a write/only medium such as a DVR/R, then the initialization is minimal. Simply configure the HammerServer as described below, then run bin/hs-init-backend go and you're set. The invocation of bin/hs-init-backend sends an initial record to the back end (a ``seed'', or ``chain start'').

If you choose to use the HammerServer with a CouchDB back end, then there is also no need for other initializations than configuring the HammerServer and running bin/hs-init-backend go. This provides initial data (``seeding'').

However, if you choose to use the PostgreSQL back end, then you must define the database and its structure. The database definition is contained in the file etc/db-00.sql. Running this script creates the database hs and assigns it to a user hs, using a password which is stated in the configuration file. The necessary steps are:

The database table and one sequence are defined in the file etc/db-01.sql. In most situations the definition will be correct. Advanced DBA's might want to add segment definitions or the like. The following necessary steps are:

After this, run bin/hs-init-backend go to provide initial database contents, and you're set to go.

Server Configuration

The file etc/hammerserver.cfg configures the HammerServer. You should edit this file, and follow the instructions to set the 'right' values. Notably, the default settings that you might want to edit, are:

More information on the configuration is contained in the documentation about the control script hsctl.


ADMINISTRATION

Stopping and Starting

The script bin/hsctl is used to stop or start (or restart) the HammerServer. For testing, the following actions should be taken:

For automatic startup, the script can be called from your local start up file /etc/rc.local, or it can be added to the services chain using chkonfig. This depends on the Unix flavor.

Log File Cleaning

The HammerServer writes the log log/hammerserverd.log. In order to avoid disk space exhaustion, this log should be 'rotated' at regular intervals. A good tool to do this, is logrotate. The log file rotation must be configured separately, the HammerServer takes no actions in this respect.

The server does not need to be restarted when the log file is rotated. Log rotation can occur while the server is running.

Managing Offload Files

The server command to offload database contents onto a flat file, creates files in the subdirectory offload. When the database is cleaned, then such files should be moved to a back up medium (so that disk space isn't exhausted).


AUTHOR

The tamper-resistant server, all tooling, and the documentation were written by Karel Kubat / karel@e-tunity.com. Copyright (c) 2009 ff. Distributed under GPLV3.