summaryrefslogtreecommitdiffstats
path: root/doc/schemas/logstash/README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/schemas/logstash/README95
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