Configuration

From Groom

Command-line Parameters

The number of command line parameters has been kept very low. The server's configuration is mainly performed through the configuration file detailed below.
The binary take only two command line arguments:

• Eventually the option -v n to set the verbosity, with 0 <= n <= 10. The higher n is, the most verbose the server will be. Default level is 3.
• The name/path of the configuration file

A tipical (linux like) command line to run Groom in background (&) mode could be:

java -jar Groom.jar -v 5 /etc/groom.conf >/var/log/groom.log &

Configuration File

The configuration file is a simple text file.
Every line beginning with '#' is a comment and won't be considered.
It contains a list of (not ordered) pair of key/value(s), respecting the following model:
key = values
values: value | value;value

The keys available to configure the software are detailed hereafter.

Property	Mandatory	Type	Description
General configuration
Port	Y	Int	The port to listen to.
Root	Y	String	The root directory, '/' of the server.
DefaultIndexes	Y	list<String>	Default index to look for when the request is a directory. Ordered.
DefaultHandler	Y	Classname	Handler to use by default (see FileTypeHandler Framework).
DirectoryHandler	N	Classname	Handler to use when the target is a directory, and no DefaultIndexes match. If none, UNAUTHORIZED will be sent back.
DefaultMime	N	String	To specify a default mime type. Advice: do not set it, let the browser do.
HTTPS setting
Secured	N	Bool	true if the secured (HTTPS) protocol shoul be used. In this case, the port should be 443.
KeyStoreFile	N	String	Path to the KeyStore file generated with keytool.
KeyStorePassword	N	String	Password for the keystore file.
KeyPassword	N	String	Password for the key itself.
Specific extensions setup
Extensions	N	list<String>	List of the extensions that carry an override.
Extensions.XXX.handler	N	Classname	Handler to use for extension XXX instead of DefaultHandler. XXX must be part of Extensions.
Extensions.XXX.mime	N	String	Mime type to send for extension XXX instead of DefaultMime or nothing. XXX must be part of Extensions.
Handler's specific properties
Handler.DirectoryHandler.Authorize	N	Bool	true to authorize usage of DirectoryHandler.
Handler.CgiHandler.Authorize	N	Bool	true to authorize usage of CgiHandler, see PHP/CGI Configuration
Handler.PhpHandler.Authorize	N	Bool	true to authorize usage of PhpHandler, see PHP/CGI Configuration
Handler.PhpHandler.Binary	N	String	Location of php-cgi binary (and its parameters, see PHP/CGI Configuration)

For example, a very simple configuration file (with only the basics, no PHP, CGI...) could be as follows. More elaborate examples can be downloaded from Groom Sourceforge page.

Port = 80
Root = /var/www
DefaultIndexes = index.html;index.htm
DefaultHandler = groom.handlers.BinaryHandler
DirectoryHandler = groom.handlers.DirectoryHandler

Extensions = html; htm; txt; groom; php; php3; php4; jpg; jpeg; gif; png; cgi; bat; css; exe
Extensions.txt.mime = text/plain
Extensions.jpg.mime = image/jpeg
Extensions.jpeg.mime = image/jpeg
Extensions.gif.mime = image/gif
Extensions.png.mime = image/png
Extensions.css.mime = text/css
Extensions.htm.mime = text/html
Extensions.html.mime = text/html

HTTP Authentication

Groom can handle BASIC access authentication only (i.e. DIGEST mode is not supported).
The protection system works on a directory basis: when a file (or a directory) is requested, the server scans the directory inside which it is contained (or itself, respectively). The facility is driven by the presence of special files, starting with .groom..

• .groom.Basic

When this file is present in the directory, all the entities it contains (including subdirectories) are protected and can be requested only by entering a login/password.
The syntax of this file is:

<REALMS>
$<COMMENT>
<LOGIN>:<PASSWORD>
<LOGIN>:<PASSWORD>
<LOGIN>:<PASSWORD>
...

The realms (the sentence displayed in the client's browser while authenticating) must allways lies on the very first line of the file.
Every line starting with $ is considered as comments and ignored.
There can be as many couples Login/Password as necessary. They must not be encrypted (i.e. they must be in clear ASCII).
A sample can be found on Sourceforge.

• .groom.Bypass

When this file is present in the directory, all the entities it contains (including subdirectories) can be requested, whatever the policy of the parent directory is.
The content of the file itself is not important, it can be 0 bytes.

Notes:

• Any request from a client trying to retrieve files starting by .groom. will be rejected with UNAUTHORIZED error code.
• These files can be symlinks (when the target OS supports them).
• A subdirectory inherits of the security properties of its parent (recursively, till either .groom.Basic or .groom.Bypass is found).