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 |