Configuration

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:

Method Config Directive
File Copy cp
SSH scp
HTTP/S url

File Copy

Configuration options:

Option Meaning Required
dir Directory to copy the file to. This can be a destination where backup agent reads from or an NFS mount. Yes

SSH

Configuration options:

Option Meaning Required
user Username for SSH Yes
password Password for the user If no key_path
key_path Path for RSA/DSA keypair files (.pub) If no password
host IP or DNS name of host to forward to Yes
dir Remote directory to copy to Yes

URL

Configuration items:

Option Meaning Required
url Full URL, (including https://), of where to send logs Yes
verify_mode Boolean indicating whether strict SSL certificate checking is to be enforced. Use zero for certificates that don’t have a trusted certificate authority on the forwarder (default self-signed, for instance) No
timeout Number of seconds to issue a timeout on. Defaults to zero (no timeout) No
ca_file SSL certificate authority file to use to verify the remote server’s certificate No
cert_file Client-side SSL certificate the server may require to verify the client’s identity No
key_file Key corresponding with cert_file No

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

Source Destination Port
Web Clients Web Node TCP 80/443
Web Node LDAP/AD Server TCP 389/636
Web Node Log Node TCP 3306 deprecated
Web Node Log Node TCP 9306 (formerly 3307) deprecated
Web Node Log Node TCP 80/443
Log Clients Log Node TCP/UDP 514

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.

Type Name Value to Enable Function
default_settings reuse_tab 0 Overrides server setting for whether or not to reuse the current tab for each new query
default_settings grid_display 1 Defaults results to grid view
default_settings no_column_wrap 1 Disables column wrapping in grid view
custom openfpc_username <user name> User name for sending to OpenFPC if pcap_url is set
custom openfpc_password <password> OpenFPC password
default_settings pcap_offset <seconds> Number of seconds before/after to set get_pcap retrieval time to
default_settings use_utc 1 Display all dates in UTC (GMT)
default_settings orderby_dir DESC Default to reverse sort (descending)
default_settings timeout <natural number> Override the system default for query timeout
default_settings default_or 1 Override the system default for making events match if any of the query terms match instead of if all query terms match
default_settings limit 100 Default limit to use for number of results to return
default_settings rows_per_page 15 Default for rows per page of results when displayed

Keyboard Shortcuts

Key Action
F8 Closes all result tabs
F9 Closes all result tabs before active
F10 Closes all tabs except active