4. Interactive configuration of beltane

NoteRequired privileges
 

Some configuration settings are only available if you have administrator privileges. With user privileges, display settings can be configured, as well as filters, and the GPG key. Users may also change their own password.

Filters have owners. If there is no owner, the filter applies to all users. Only with administrator privileges it is possible to create or modify filters for which the owner does not match the current login user.

With the Configure button in the upper left panel, you get access to the interactive configuration (stored in $HOME/beltanerc The following functions are provided

4.1. Administrative

Administrator privilege required.

Administrator name

Your login name.

Administrator password

Your login password. If this is blank, the stored password will be kept (rather than set to blank). If exactly 32 chars, the input is assumed to be an MD5 hash already, otherwise the MD5 hash will be computed and stored.

Timeout

(seconds) terminate session after this much seconds without user activity.

Domain is stripped

(TRUE/FALSE) yule is configured to strip the domain part from client names.

NoteNOTE
 

Beltane will need the FQDN of clients in the client database (or the IP number, if clients are known to yule by IP number only). In particular, Beltane will not function properly if you have only the hostname in the client database, and yule is configured to strip the domain. See Section 3.2 for more information on the client database.

Comment updates

(TRUE/FALSE) If set to TRUE, beltane will request a comment for each baseline database update. The comment will be stored in the SQL database.

SSL browser login

(TRUE/FALSE) If set to TRUE, and you are using browser-based http authentication over a SSL connection, and your http login name matches a username defined in the beltane configuration, you will automatically get logged in as this user.

LDAP Server

(hostname) If this is not empty, and not set to "none", beltane will not use the userlist defined in the configuration, but will contact the LDAP server on that host to authenticate the user. See Section 5 for details.

LDAP Base DN

(ldap dn) This is the base DN that beltane will use to authenticate users on the LDAP server. See Section 5 for details.

4.2. Files and Utilities

Administrator privilege required.

Yule data directory

The path to yules data directory (e.g. /var/lib/yule). This is the directory where client file signature databases and client configuration files reside.

Yule PID file

The path to yules pid file (e.g. /var/run/yule.pid).

Yule HTML status page

The path to yules HTML status file (e.g. /var/lib/yule/yule.html). This is a file written by the server providing basic status information for the server itself and for the clients known to the server.

Path to beltane_cp

The path to the beltane_cp helper application.

Path to beltane_update

The path to the beltane_update helper application.

Path to beltane_log

The path to the beltane_log helper application.

Path to beltane_sign

The path to the beltane_sign helper application (used for signing file databases).

Path to yulectl

The path to the yulectl application. This is included in the samhain/yule distribution. It provides a command-line interface to connect to the Unix domain socket of yule and submit commands for clients. The server will pass such commands to a client when the client connects for the next time (e.g. for delivering a timestamp message).

Last update stored in

The path to the file where the list of files is stored that were updated with the last non-bulk update. This can be used as file list for the bulk update, i.e. you can use one host as template and select updates manually, and then carry over this selection to other hosts.

4.3. Database

Administrator privilege required.

Database

The database type. Possible values are PostgreSQL, MySQL, Oracle, and ODBC (not tested). Oracle and ODBC are only supported with samhain version 1.8.0 and above.

Database table

The name of the table in the SQL database (default: log).

Database host

The host where the SQL server runs (for UNIX socket: localhost if MySQL, blank if PostgreSQL).

Database name

The name of the SQL database (default: samhain).

Database user

The name of the SQL user.

Database password

The password of the SQL user.

4.4. Display

Per-user configurable (no administrator privilege required).

TZ offset

(integer) add this number of seconds to ctime, and mtime when showing details for modified files. Allows you to fix offsets between these items and log_time.

Displayed messages

(integer) display at most this number of messages. The default value of '0' will display at most 1200 messages (but this is not a hardcoded maximum — you can set a higher limit).

Refresh time

(integer) time in seconds between window refresh for the message and client panel.

View server messages

(TRUE/FALSE) also view messages from the server itself.

Sort clients by name

(TRUE/FALSE) sort clients alphanumerically in the 'Clients' panel.

Default layout

(TRUE/FALSE) whether the message panel should be above (default), or to the right of the clients panel. If you change this option, it will only take effect after hitting Refresh, or the browsers reload button.

Search displays comments

(TRUE/FALSE) whether the user that approved an update, and the comment for that update, should be displayed in the search results for a database search.

Menu panel height

The height (in pixels) of the top panel containing menu and buttons. If you change this option, it will only take effect after hitting Refresh, or the browsers reload button.

Message panel height

The height (in pixels) of the message panel containing the list of messages. If you change this option, it will only take effect after hitting Refresh, or the browsers reload button.

Client panel width

The width (in pixels) of the client panel containing the list of clients. If you change this option, it will only take effect after hitting Refresh, or the browsers reload button.

4.5. Filters

Administrator privilege required for filters not owned by current login user.

Here you will see the list of already defined filters, as well as a single blank entry for the next filter to be defined. To delete a filter, simply delete its 'Pattern' field and submit.

Pattern

The pattern to match. This may be a simple string or a Perl-style regular expression. Log records matching the pattern will get suppressed. Please note that PCRE regular expressions must be enclosed by matching delimiters (e.g. /pattern/ or #pattern#).

On Linux, see man perlre for details on Perl regular expressions. You may also have a look at the PHP manual for an overview of Perl-Compatible Regular Expressions (PCRE): http://php.net/manual/en/pcre.pattern.php

Type

Whether the pattern should be interpreted as string (fast) or regular expression (slow).

ACK filtered

(TRUE/FALSE) automatically confirm filtered messages, i.e. change their status from NEW to ACK_AUTO (acknowleged) in the database. If you don't use this option, the number of messages returned by a database query, but then filtered out, will increase with time, and eventually cause bad performance.

Apply to

The field, to which the filter should be applied. If this field matches the pattern, the message will not be shown, and eventually automatically confirmed, depending on the 'ACK filtered'setting for this filter.

NoteNOTE
 

The 'Log record tag' contains an MD5 checksum computed by yule over an arbitrary set of user-defined database fields. Basically, this should allow you to easily filter any rows in the database you like. E.g. on startup, clients will report the checksum of the configuration file, or the fingerprint of the PGP key used for signing. You could e.g. let yule include these fields in the 'Log record tag' ('log_hash' in the database), and filter ot all startup messages with 'good' config file checksums/PGP fingerprints.

Owner

The 'owner' of a filter is the login user for which this filter applies. If this field is empty, the filter is used for all users. Otherwise, the filter is only applied if the given name matches the login user.

NoteNOTE
 

Users without administrative privilege may only see filters that apply to all users (no owner) and to themselves. They may only create and/or modify filters that are 'owned' by themselves (only).

4.6. GnuPG

Per-user configurable (no administrator privilege required).

GPG Key ID

The key ID for the signing key. Gpg understands the 8-digit hexadecimal ID as well as some other ways to specify the key.

GPG Homedir

The directory where the keyrings are located (usually /some/user/.gnupg).

4.7. Users

Here you will see the list of already defined users, as well as a single blank entry for the next user to be defined. To remove a user from the system, simply delete its 'User name' field and submit. Note that this does not affect currently logged-in users.

User name

Fill in to create a new user. Erase User name to remove a user. Leave Update privilege to FALSE, if you don't want the user to perform any database update actions. See also Section 4.8.

User group(s)

An optional comma-separated list of groups the user belongs to. If you leave this blank, the user belongs to no group, and can view all clients. If you enter a (list of) group(s), the user can view all clients pertaining to these groups. See also Section 6.

User password

Fill in when you create a new user.

Privilege level

(ADMIN/USER/GUEST) Leave Privilege level to GUEST, if you don't want the user to perform any database update actions. See also Section 4.8.

4.8. Additional users

Initially, there is excatly one user, and this user has administrative permissions. It is not possible to delete this user (but it can be renamed).

An arbitrary number of additional users can be defined, which can have one of three different privilege levels: administrative users, normal users, and guests.

Administrative users have permission to update the configuration of Beltane.

Normal users may not alter global configuration settings, or create or modify other users, but can use Beltane to browse messages and update baseline databases.

Guest users may use Beltane to browse messages, but cannot perform any actions that may alter any data.

Users can be members of one or several group(s). For each user, there is a field User group(s), where you can enter a comma-separated list of groups. If you leave this field blank, the user can view all clients. If you enter a group (or list thereof), the user can only view clients pertaining to this group(s).

In the configuration menu, you will always find one empty pair of User name, User password input boxes. Fill them in to create a new user.

For existing users, the user ID is shown, as well as a pair of User name, User password input boxes. Only the user name is shown. If you want to remove a user, just erase the user name and submit.