diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/schemas/logstash/README | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/doc/schemas/logstash/README b/doc/schemas/logstash/README new file mode 100644 index 0000000..2f36eb6 --- /dev/null +++ b/doc/schemas/logstash/README @@ -0,0 +1,95 @@ +Example configuration for logstash/elasticsearch +================================================ + +So you've got all these RADIUS logs, but how do you analyse them? What is the +easiest way to query the logs, find out when a client connected or disconnected, +or view the top ten clients logging into the system over the last six hours? + +The elastic stack is designed and built to do just that. elasticsearch is a +search engine; logstash is commonly used to feed data in, and kibana the web +interface to query the logs in near real time. + +Installing the elastic stack is beyond the scope of this document, but can be done +in a short amount of time by any competent sysadmin. Then comes getting the +logs in. + +This directory contains the following files as a starting point for feeding +RADIUS logs into elasticsearch via logstash, then sample dashboards for Kibana +to explore the data. + +Files +----- + +Please note that all files should be reviewed before use to determine if they +are suitable for your configuration/system, especially if you are integrating +this into an existing logstash/elasticsearch setup. + +radius-mapping.sh + + Each elasticsearch index needs a mapping to describe how fields are stored. + If one is not provided then all is not lost as elasticsearch will build one + on the fly. However, this may not be optimal, especially for RADIUS data, as + all fields will be analyzed making some visualisations hard or impossible + (such as showing top N clients). + + This shell script (which just runs curl) pushes a template mapping into the + elasticsearch cluster. + +logstash-radius.conf + + A sample configuration file for logstash that parses RADIUS 'detail' files. + It processes these by joining each record onto one line, then splitting the + tab-delimited key-value pairs out. Some additional data is then extracted + from certain key attributes. + + The logstash config will need to be edited at least to set the input method: + for experimentation the given input (file) may be used. If logstash is running + on the RADIUS server itself then this example input may be appropriate, + otherwise a different input such as log-courier or filebeat may be better to + get the data over the network to logstash. + + It would be best to use an input method that can join the multiple lines of + the detail file together and feed them to logstash as a single entry, rather + than using the logstash multiline codec. + +log-courier.conf + + An example configuration for the log-courier feeder. + +kibana4-dashboard.json + + Basic RADIUS dashboard (for Kibana 4 to Kibana 6). + + To import the dashboard first create a new index called "radius-*" in + Settings/Indices. Then go to Kibana's Settings page, "Objects" and "Import". + Once imported open the "RADIUS detail" dashboard. + + +Example usage +------------- + +Install mapping (only needs to be done once): + + $ ./radius-mapping.sh + +Edit logstash-radius.conf to point to the correct file, then feed a detail file +in: + + # /usr/share/logstash/bin/logstash --path.settings=/etc/logstash -f logstash-radius.conf + +To view debug output, append `--log.level=debug`. + + +See also +-------- + +elasticsearch web site: http://www.elastic.co/ + +The configuration examples presented here have been tested with the +following software versions: + + elasticsearch 6.7.0 + logstash 6.7.0 + kibana 6.7.0 + kibana 5.1.2 + kibana 4.1.11 |