hsctl - HammerServer control program
hsctl start - start the server hsctl stop - stop the server hsctl restart - stop/start
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.
hsctl relies on the existence of the following files and/or directories:
The configuration file for hsctl and for the HammerServer itself. This file must be present when hsctl is invoked.
Log where the HammerServer's actions are shown. The directory log/ must be present when hsctl is invoked.
Process ID files where started server PID's are kept.
hsctl relies on its configuration file etc/hammerserver.cfg. The syntax is described here.
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.
The storage back end is defined by the variable db. This variable can take the following forms:
PostgreSQL back ends are identified using db = dbi:Pg:database. Additionally, two configuration variables dbuser and dbpass are needed for database logins. For example:
# This uses a PostgreSQL database back end. The database # is hs. Database login credentials are hs/mike. db = dbi:Pg:dbname=hs dbuser = hs dbpass = mike
Flat file back ends are identified using db = file:/path/to/store. For example:
# This is a flat file back end. Hammerserver will generate # the following files: # /var/hammerserver/store (storage itself) # /var/hammerserver/store.idx (index file) # /var/hammerserver/store.lock (lock file) db = file:/var/hammerserver/store
CouchDb back ends are identified using db = couchdb:database:http://server:port. For example:
# This selects the CouchDb database "hs" on # http://server:5984 db = couchdb:hs:http://server:5984
See the start command below that reuses these labels in ${db} etc.
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.
The HammerServer receives requests, examines the URL's, and takes appropriate action. The following URL's are known:
/ and /xslt are for browser support (index page and XML transformation sheet).
/areyouthere returns an I-am-alive signal.
/insert requests data insertion.
/retrieve reads data from the back end, validates, and returns them.
/insertlines allows bulk insertion of newline-separated records.
/seach searches for data.
/verify allows verification of the tamper-resistant log.
/offload dumps data from the database onto a flat file.
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.
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
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.