3. Functions
After logging in, the main window will show up, which is subdivided into four panels.
3.1. The menu panel
In the upper part is the menu panel with a menu row at the top and a row of buttons for fast access to some functions.
Also, the current status of the server (running/stopped/unknown) will be indicated. This information is gained by reading the servers PID from the pid file and probing for the existence of the process. The status line doubles as a link to the HTML status page written by the server.
In addition, the username, privilege level, and remaining time until idle logout are shown.
3.1.1. Buttons
- Refresh
Refresh all panels.
- Signatures
Check PGP signatures on configuration files and baseline file signature databases, and renew them after running an update (see Section 3.3.3).
- Select all
Select all currently displayed messages.
- Update
For all selected messages, the file signature database of the respective client will be updated, and the message be marked as confirmed. Messages for which file signature updates are not applicable (e.g. client startup messages) are handled gracefully.
- Bulk Update
Enter the dialog for bulk updates (see Section 3.3.2).
- Confirm
The record in the SQL database will get acknowleged, but the file signature database will not get updated. For messages that do not refer to filesystem changes, or if you don't want to update the database..
- All Clients
View messages for all clients.
3.1.2. Menu
- File -> Refresh
Refresh all panels (same as 'Refresh' button).
- File -> Logout
Exit the application, and destroy the PHP session.
- Messages -> Select all
Select all displayed messages.
- Messages -> Reset
De-select all selected messages.
- Messages -> All Clients
View messages for all clients (same as 'All Clients' button).
- Updates -> Bulk Update
Enter the dialog for bulk updates (see Section 3.3.2). Same as 'Bulk Update' button.
- Updates -> Update
For all selected messages, the file signature database of the respective client will be updated, and the message be marked as confirmed. Messages for which file signature updates are not applicable (e.g. client startup messages) are handled gracefully. Same as 'Update' button.
- Updates -> Confirm
The record in the SQL database will get acknowleged, but the file signature database will not get updated. For messages that do not refer to filesystem changes, or if you don't want to update the database. Same as 'confirm' button.
- Tools -> Server status
Display the HTML status page written by the server. Same as 'Server status' button.
- Tools -> Signatures
Check PGP signatures on configuration files and baseline file signature databases, and renew them after running an update (see Section 3.3.3). Same as 'Signatures' button.
- Tools -> Search database
Search the SQL database for entries.
- Reload -> Show pending commands
Show the commands queued by the server to be sent to clients. As clients do not listen on the network, commands can only be sent when the client itself connects (e.g. to deliver a timestamp message).
- Reload -> Reload all clients
Tell the server to send a reload command (to reload the configuration) to all clients. As clients do not listen on the network, commands can only be sent when the client itself connects (e.g. to deliver a timestamp message).
- Reload -> Cancel reloads
Tell the server to cancel all pending commands for clients.
- Reload -> Run scan on all clients
Tell the server to send a scan command (to perform a file system check) to all clients. As clients do not listen on the network, commands can only be sent when the client itself connects (e.g. to deliver a timestamp message).
- Configure
Edit Beltanes configuration file entries.
- Help -> Contents
Show this help.
- Help -> Performance
Show some performance data that might be helpful to discover problems.
- Help -> About
Show the version of beltane.
3.2. The Clients panel
In the Clients panel, Beltane shows the list of currently recognized clients. Left in the title bar, you will find the Add function to add a new client entry.
The status of any client is indicated in the leftmost column of the client list. Possible values are:
- Unknown
The client status is unknown, possibly because it has not connected to the server since server startup.
- Active
The client is running.
- Dead
The client has exited, or has not reported within the timeout limit configured in the server configuration. You need to have clients send timestamp messages for this to work properly.
- Uninstalled
The client has an entry in the client database, but is marked as uninstalled.
 | NOTE |
|---|---|
Status information is taken from the server (yule) HTML status page. You need yule 1.7.8 or later for this feature. |
The severity of the most severe new message of any client is indicated by a coloured box to the left of the client name (purple = Alert, red = Critical, orange = Error, yellow = Warning, green = Info, white = None). This status corresponds to the most severe new message for the corresponding client. Filtered messages are not taken into account (see also Section 3.3).
 | Tip |
|---|---|
Left click on the colored box to the left of the client name will show all messages for this client (only) in the messages panel. |
Left click on a client name will bring up a menu with the following items:
- Edit
Edit the entry for this client.
- Delete
Delete the entry for this client.
- Details
Show the entry for this client.
- Messages
Show all new messages for this client.
- ThisMsg
Show the message corresponding to the status indicator. The message will be shown in the lower right panel. In the title bar, a function Acknowledge is provided.
- Bulk Update
Enter the dialog for bulk updates (see Section 3.3.2).
- Reload
Submit a reload command for this client to the yule server. The server will store the command and will issue it to the client next time the client connects (e.g. to deliver the regular timestamp message). The client will then reload its configuration, exactly as if it receives a SIGHUP signal.
NOTE You need yule 1.8.0 or later for this feature. In the yule configuration, you need to enable the server's unix domain socket, and to configure the user (UID) who can send commands to the server. In the Beltane configuration, you need to enter the path to the yulectl command that is part of the samhain/yule distribution and allows to send commands to the server socket.
As of yule 1.8.12, it is possible to use password-based authentication on the server command socket (see the samhain manual), which allows to use this feature also on systems that cannot pass user credentials via a unix domain socket.
- Scan
Submit a scan command for this client to the yule server. The server will store the command and will issue it to the client next time the client connects (e.g. to deliver the regular timestamp message). The client will then perform a file integrity check.
Only supported for samhain client version 2.5.1 and above. Also see note above (on 'Reload').
- Edit config
This allows to edit the client's configuration file. If you are using signed configuration files, you can use the Sign function in the upper panel to renew the signature. You may want to use the Reload function (see above) to force the client to reload the modified configuration.
| Tip |
|---|---|
You can close the context menu by mousing over it and then off of it. |
3.2.1. The Client database
Beltane requires an up-to-date database of installed clients, and allows you to interactively edit this database, if needed. This database is a flat file in XML format, named yulerc.install.db, and located in the profiles/ subdirectory of the yule data directory. For each client, this file has the following entries:
- Hostname
The FQDN (or IP number, if yule cannot resolve the IP) of the client host. This the only entry that is currently used by beltane.
- Group
The group to which the client belongs to. This is used to determine whether a user beltane can view that particular client (as well as reports from that client) or not. See also Section 6 for the access rules that are applied.
- Operating system
The OS of the client host (e.g. redhatlinux_i386, suselinux_i386, debianlinux_i386, solaris).
- Installation date
Date the samhain client was installed on the host.
- Installation status
The status of the samhain client installation (e.g. installed/uninstalled).
- Installation name
The name under which the samhain client was installed on the host. (Samhain fully supports re-naming to some arbitrary name, including re-naming directories, pid file, etc.).
- Installation prefix
The argument to the --prefix option of the configure script for that client. Basically, this, together with the install name, should allow to determine the name and location of the samhain executable on the client host.
- Installation version
The version of samhain installed on this client.
| What should I fill in? |
|---|---|
If you are using the deploy.sh command delivered with samhain in order to deploy clients to remote hosts, the client database will already exist, as deploy.sh uses it to log the performed installations. Otherwise, you will need to edit/create the list of installed clients manually. In that case, the only relevant entry is the hostname. If the file does not exist on startup, Beltane will create a dummy file. You need to create then a valid entry, before you can delete the DUMMY entry. |
 | Warning |
|---|---|
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. |
3.3. The Messages panel
The Messages panel displays new messages, i.e. messages not yet acknowledged by the user. For each message, a status icon, the database index, severity, hostname, the message text, and (if applicable) the file path is shown. Each message can be selected with a select box to the left.
By default, messages are sorted newest first. There are three configuration options which are relevant for the display of messages: Displayed messages is an optional upper limit on the number of messages to display. With Filters you can filter messages that you do not want to see. Messages matching the regular expression will not be displayed. View server messages is a boolean option; if TRUE, also messages from the server itself (rather than only messages received from clients) will be shown.
| Tip |
|---|---|
On-the-fly sorting is possible by clicking on the column headers. Clicking a second time on the same header will revert the sort order. |
| Tip |
|---|---|
If there are more messages than displayed in the panel, you can page using the ">" and "<" link(s) at the left side of the table header. |
Clicking on the database index will display all details of the respective message. Clicking on the host name will alter the message panel to show messages for that host only (use All Clients to reset).
3.3.1. Message details
When the details of a log message are shown in the lower right panel, you can click on Update next to the file path. This will trigger the update of the file signature database, and also acknowledge the corresponding entry in the SQL database.
If you click on Confirm instead, the record in the SQL database will get acknowleged, but the file signature database will not get updated (thus after a re-start of the samhain client, you will get a message for that file again).
3.3.2. Bulk updates
Bulk Update requires PHP >= 4.3.0.
Rather than reviewing client messages, and selecting them manually for update, it is possible to perform a 'bulk update' for all client messages according to some criteria. If you click on Bulk Update, you will enter a dialog to define these criteria.
Currently supported are: Host — the hostname of the client, interpreted as Perl regular expression; Path — the path of the file(s), interpreted as a Perl regular expression; File list — a list of files, one per line, for which you want to perform updates; Modification time — lower and/or upper limits on the modification time of files; Log time — lower and/or upper limits on the time when the message was logged.
If you specify more than one criterium, only files that match all specified criteria are considered for update.
| Regular expressions for host names and paths |
|---|---|
To match a set of hosts, or a set of paths, you can supply a Perl-style regular expression for the Host or Path field. Please note that Perl 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 |
3.3.2.1. Checksums in the file list
A File list may include checksums for the listed files. In that case, the checksum must come first, followed by space, followed by the file path. The checksum must be the same as used by samhain (by default TIGER192, but MD5 and SHA1 are available as runtime configuration options with the DigestAlgo=... option). If you specify checksums, you need to do this for all files in the list. For files that are not regular files (e.g. directories, devices, ...) use a single '0' (zero) as checksum.
You may notice that samhain stores all checksums as 48-digit uppercase hexadecimal values (192 bits). Checksums with less bits than the default TIGER192 checksum (MD5: 128 bits, SHA1: 160 bits) are padded with 0 on the right. You don't need to include this padding, and you can use lowercase hex - beltane will take care to normalize the checksum.
3.3.3. GnuPG Signatures
Renewing GnuPG signatures requires PHP >= 4.3.0. With earlier versions, you will only be able to check signatures.
If you have gpg signed your file signature databases, the signatures will become invalid (and, in fact, removed) when performing an update. Likewise, signatures will become invalid (and removed), if you edit a client configuration files. To fix this, a function is provided to check signatures, and renew missing ones.
Before using this function, you should configure the GPG key ID, and the GPG homedir (the directory where the keyrings are located). Clicking on Sign in the message panel will then run the signature check, and offer you to update missing signatures.
The gpg executable must be in /bin, /usr/bin, /sbin, /usr/sbin, or /usr/local/bin.
| WARNING |
|---|---|
You will need to enter the passphrase for the GPG key. Do not use this function if you access beltane over an insecure connection. |