NAME

hsctl - HammerServer control program


SYNOPSIS

 hsctl start                      - start the server
 hsctl stop                       - stop the server
 hsctl restart                    - stop/start


DESCRIPTION

hsctl is a control script for the HammerServer. It relies on a configuration file (etc/hammerserver.cfg) for the right options. The server can be started, stopped and restarted.


FILES

hsctl relies on the existence of the following files and/or directories:

etc/hammerserver.cfg

The configuration file for hsctl and for the HammerServer itself. This file must be present when hsctl is invoked.

log/hammerserverd.log

Log where the HammerServer's actions are shown. The directory log/ must be present when hsctl is invoked.

log/*pid

Process ID files where started server PID's are kept.


THE CONFIGURATION

hsctl relies on its configuration file etc/hammerserver.cfg. The syntax is described here.

File Syntax

The configuration consists of label and value pairs, as in:

 label = value

Long settings can use backslash-continuation to split over multiple lines, as follows:

 label = very long \
   value

Empty lines are allowed, and comment lines too. Comments must start with a hashmark, such as:

 # This is comment

Only one label has an intrinsic meaning in hsctl, which is start. All other labels can be chosen by the user, and are reused later (variable expansion). For example, the label second expands to the quick brown fox thanks to the label first:

 first = brown
 second = the quick ${first} fox

The "value" of a variable can also be PROMPT: text. In this case, the "text" is displayed on screen, and the invoker has the chance to enter a value. This feature is useful when very sensitive data (e.g., encryption keys) should not be kept in the configuration file, but should be entered at startup.

Storage and Database Connectivity

The storage back end is defined by the variable db. This variable can take the following forms:

See the start command below that reuses these labels in ${db} etc.

Encryption related

Tamper resistance is ensured in the HammerServer by signing each entry using AES. The value aeskey must be a strong passphrase, for example:

 aeskey = bDthZmprIGE7amthZHNmaiBrYWw7ZGZqayBhO2RsZmprIA

It is a good security measure not to have the AES key in the configuration file, but to enter it by hand. In this case the following setting is useful:

 aeskey = PROMPT Enter the AES key:

Note that hsctl always parses the configuration (regardless of the required action), and given this example, it will also prompt for the AES key when a server stop is requested - even though at this point the key isn't really required.

Allowed URL's

The HammerServer receives requests, examines the URL's, and takes appropriate action. The following URL's are known:

When the HammerServer is started, it expects a list of allowed URL's that it can act upon. Often the allowed URL's are configured for later use in a temporary label (expanded later), e.g.:

 # URL's for browser access and simple manipulations
 simpleurls = /,/xslt,/insert,/retrieve
 # URL's for extended usage: searching and bulk upload
 extendedurls = /,/xslt,/search,/insertlines
 # URL's for typical sysop functions
 sysopurls = /,/xslt,/areyouthere,/verify,/offload

The URL's are then reused as ${simpleurls} or ${extendedurls} or ${extendedurls} in the appropriate start commands. Note however that the here shown labels simpleurls, extendedurls and sysopurls are only arbitrarily chosen placeholders without intrinsic meaning.

Command Starting

All settings with label start define a command to be started. Practically the command is bin/hs-httpd-d, the HammerServer over HTTP. Here is an example (which re-uses the above shown labels):

 start = bin/hs-http-d db=${db} dbuser=${dbuser} dbpass=${dbpass} \
         port=10000 aeskey=${aeskey} log-levels=${log-levels} \
         urls=${simpleurls} forking-daemon=yes

When hsctl starts the stated program, then the remaining arguments (in this example: db, dbuser and so on) are sent on stdout to that process. This means that there is no commandline in the processlist that discloses information such as the AES key.

The configuration can contain several start commands. E.g., a second command could start the HammerServer on port 10001 allowing the "sysopurls" from the above example:

 # Standard HammerServer on port 10001. No verifying/offloading:
 start = bin/hs-http-d db=${db} dbuser=${dbuser} dbpass=${dbpass} \
         port=10000 aeskey=${aeskey} log-levels=${log-levels} \
         urls=${simpleurls} forking-daemon=yes
 # Verifying and offloading is allowed on port 10001:
 start = bin/hs-http-d db=${db} dbuser=${dbuser} dbpass=${dbpass} \
         port=10001 aeskey=${aeskey} log-levels=${log-levels} \
         urls=${simpleurls} forking-daemon=yes


AUTHOR

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