Web Configuration

Most settings in the elsa_web.conf and elsa_node.conf files should be fine with the defaults, but there are a few important settings which need to be changed depending on the environment.
elsa_web.conf:
● Nodes: Contains the connection information to the log node databases which hold the actual data.
● Auth_method: Controls how authentication and authorization occurs. For LDAP, the ldap settings must also be filled out.
● Link_key: should be changed to something other than the default. It is used to salt the auth hashes for permalinks.
● Email: For alerts and archive query notifications, you need to setup the email server to use. If you wish to get the actual results from an alert, in addition to a link to the results, add the following config to the email section:
“email”: {
“include_data”: 1
}
● Meta_db: Should point to the database which stores the web management information. This can reside on a node, but probably shouldn’t. The performance won’t be much of a factor, so running this locally on the web server should be fine.
● Excluded_classes: If you want to remove some classes from the menus and searches altogether, configure the config entry for excluded_classes like this:
“excluded_classes”: {
“BRO_SSL”: 1
},
● APIKeys: The “apikeys” hash holds all known username/apikey combinations, such as:
“apikeys”: { “elsa”: “abc” }
● Peers: Configuration for how this ELSA node will talk to other ELSA nodes. Note that a configuration for itself (127.0.0.1) is required for any query to complete. An example configuration is:
“peers”: {
“127.0.0.1”: {
“url”: “http://127.0.0.1/”,
“user”: “elsa”,
“apikey”: “abc”
}
}
● Default OR: By default, all search terms are required to be found in the event to constitute a match (AND). If you wish, you can set the config value “default_or” to a true value to change the default behavior to making the search match if any of the given values are true:
“default_or”: 1

Node Configuration

● Database: Edit the connection settings for the local database, if non-default.
● Log_size_limit: Total size in bytes allowed for all logs and indexes.
● Sphinx/perm_index_size: This setting must be tweaked so that perm_index_size number of logs come into the system before (num_indexes* sphinx/index_interval) seconds pass.
● Archive/percentage: Percentage of log_size_limit reserved for archive.
● Archive/days: Max number of days to retain logs for in the archive
● Sphinx/days: Max number of days to retain logs for in the indexes
● forwarding/forward_only: This node will only forward logs and not index them.
● forwarding/destinations: An array of hashes of forwarders, as detailed in the Forwarding section.

Forwarding Logs

ELSA can be setup to forward (replicate) logs to an unlimited number of destinations in several ways:

File Copy

Configuration options:

SSH

Configuration options:

URL

Configuration items:

An example forwarding configuration may look like this:

“forwarding”: {
“forward_only”: “1”,
“destinations”: [
{ “method”: “url”, “url”: “http://example.com/API/upload” },
{ “method”: “url”, “url”: “https://secure.example.com/API/upload”, “ca_file”: “/etc/mycafile.pem” }
]
}

Low volume configuration tuning

If your ELSA node isn’t receiving many logs (less than a few hundred per minute), you may need to tune your setup so that permanent indexes aren’t underutilized. There are at most num_indexes number of permanent indexes, and if there isn’t a free one available, the oldest one will be overwritten. If this happens before the log_size_limit has been reached, then it means that you rolled logs before you wanted to. This means you need to tweak some settings in elsa_node.conf:

• Increase num_indexes to something larger like 400
• Increase allowed_temp_percent to 80

This should give you .8 x 400 x 60 seconds of time before temp indexes get rolled into a perm index, and should give you more perm indexes before they get rolled. With 400 perm indexes, that should be more than 88 days of possible index time. If that’s still not enough, move index_interval up from 60 seconds to something larger (this will extend the “lifetime” of a temp index).

If you set num_indexes to be larger than 200, you should increase the open files limit for searchd (Sphinx). You can do this on Linux by editing/etc/security/limits.conf and adding:

root soft nofile 100000
root hard nofile 200000

Then logout, login, and restart searchd.

Changing num_indexes

If you change the num_indexes setting in /etc/elsa_node.conf, you will need to regenerate the /usr/local/etc/sphinx.conf file. To do so, either delete or move the existing sphinx.conf file and then run:

echo “” | perl /usr/local/elsa/node/elsa.pl -on
pkill searchd
/usr/local/sphinx/bin/searchd –config /usr/local/etc/sphinx.conf

This will regenerate the config file using the new num_indexes value. There is one last step that needs to be taken, and that is to instantiate the actual Sphinx files by running indexer on these previously non-existent files. This step depends on what the new value of num_indexes is. In this example, we have changed num_indexes from 200 to 400, so we need to instantiate indexes 201 through 400. We do this thusly:

for COUNTER in `seq 201 400`; do /usr/local/sphinx/bin/indexer –config /usr/local/etc/sphinx.conf temp_$COUNTER perm_$COUNTER; done

Now, restart searchd and the new indexes should be available.

Making changes to syslog-ng.conf

install.sh will use /usr/local/elsa/node/conf/syslog-ng.conf as a template, using /etc/elsa_syslog-ng.conf (if it exists) as a reference for any persistent changes, and write the combination to /usr/local/syslog-ng/etc/syslog-ng.conf which is what is actually run. So, put any local changes in /etc/elsa_syslog-ng.conf to make sure they survive an update. Keep in mind that the file is included before the log {} statements, so you can redefine sources and destinations there, or put in additional log {} statements.

Firewall Settings

API Keys – API section.

The literal structure of an APIKey as it is transmitted is in the form of an HTTP Authorization header. The format is this: Authorization: ApiKey <username>:<current epoch timestamp>:<SHA512 hex digest of timestamp concatenated with configured API key>

As an example, if the API key were “abc,” then the request would look like this for a user of “myuser” and a timestamp of 1364322947 would be:

Authorization: ApiKey myuser:1364322947:05e84771a03cf3aaf88e947e915f73b4ef3685a382f8ca603b787168eb464a06eb178a908b868832af6ff913ca9b096880c4f4089bc4e0585fe6ac40e29f061d

To revoke an API key, simply remove that username from the list of “apikeys” in elsa_web.conf or change the key for that username to reset it.

Preferences

You can set per-user preferences by navigating to the “Preferences” dialog under the “ELSA” menu in the upper-left-hand corner of the page. Preference changes will take effect at the next page load.

Keyboard Shortcuts