Update elasticsearch example files

[freeradius.git] / doc / schemas / logstash / README

diff --git a/doc/schemas/logstash/README b/doc/schemas/logstash/README
index 93b937c..e43fe4d 100644 (file)
--- a/doc/schemas/logstash/README
+++ b/doc/schemas/logstash/README
@@ -2,9 +2,8 @@ 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?
+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 logstash/elasticsearch/kibana stack is designed and built to do just that.
 elasticsearch is a search engine; logstash is commonly used to feed data in,
@@ -15,13 +14,15 @@ 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.
+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.
+are suitable for your configuration/system, especially if you are integrating
+this into an existing logstash/elasticsearch setup.
 
 radius-mapping.sh
 
@@ -34,12 +35,12 @@ radius-mapping.sh
   This shell script (which just runs curl) pushes a template mapping into the
   elasticsearch cluster.
 
-
-radius.conf
+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.
+  tab-delimited key-value pairs out. Some additional data is then extracted
+  from certain key attributes.
 
   The file will need to be edited at least to set the input method: for
   experimentation the given input (stdin) may be used. If logstash is running on
@@ -47,6 +48,27 @@ radius.conf
   input such as log-courier or logstash-forwarder may be better to get the data
   over the network to the logstash server.
 
+  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 filter.
+
+log-courier.conf
+
+  An example configuration for the log-courier feeder.
+
+kibana4-dashboard.json
+
+  Basic RADIUS dashboard for Kibana4.
+
+  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.
+
+kibana3-dashboard.json
+
+  Basic RADIUS dashboard for Kibana3. To import the dashboard go to Load,
+  Advanced and "Choose File".
+
 
 Example usage
 -------------
@@ -55,7 +77,7 @@ Install mapping (only needs to be done once):
 $ ./radius-mapping.sh
 
 Feed a detail file in:
-$ /path/to/logstash -f radius.conf < acct-detail
+$ /path/to/logstash -f logstash-radius.conf < acct-detail
 
 
 See also
@@ -64,7 +86,6 @@ See also
 elasticsearch web site: http://www.elastic.co/
 
 
-
 Matthew Newton
-April 2015
+January 2016