doc/schemas/logstash/README

   1 Example configuration for logstash/elasticsearch
   2 ================================================
   3
   4 So you've got all these RADIUS logs, but how do you analyse them? What is the
   5 easiest way to query the logs, find out when a client connected or disconnected,
   6 or view the top ten clients logging into the system over the last six hours?
   7
   8 The elastic stack is designed and built to do just that. elasticsearch is a
   9 search engine; logstash is commonly used to feed data in, and kibana the web
  10 interface to query the logs in near real time.
  11
  12 Installing the elastic stack is beyond the scope of this document, but can be done
  13 in a short amount of time by any competent sysadmin. Then comes getting the
  14 logs in.
  15
  16 This directory contains the following files as a starting point for feeding
  17 RADIUS logs into elasticsearch via logstash, then sample dashboards for Kibana
  18 to explore the data.
  19
  20 Files
  21 -----
  22
  23 Please note that all files should be reviewed before use to determine if they
  24 are suitable for your configuration/system, especially if you are integrating
  25 this into an existing logstash/elasticsearch setup.
  26
  27 radius-mapping.sh
  28
  29   Each elasticsearch index needs a mapping to describe how fields are stored.
  30   If one is not provided then all is not lost as elasticsearch will build one
  31   on the fly. However, this may not be optimal, especially for RADIUS data, as
  32   all fields will be analyzed making some visualisations hard or impossible
  33   (such as showing top N clients).
  34
  35   This shell script (which just runs curl) pushes a template mapping into the
  36   elasticsearch cluster.
  37
  38 logstash-radius.conf
  39
  40   A sample configuration file for logstash that parses RADIUS 'detail' files.
  41   It processes these by joining each record onto one line, then splitting the
  42   tab-delimited key-value pairs out. Some additional data is then extracted
  43   from certain key attributes.
  44
  45   The logstash config will need to be edited at least to set the input method:
  46   for experimentation the given input (file) may be used. If logstash is running
  47   on the RADIUS server itself then this example input may be appropriate,
  48   otherwise a different input such as log-courier or filebeat may be better to
  49   get the data over the network to logstash.
  50
  51   It would be best to use an input method that can join the multiple lines of
  52   the detail file together and feed them to logstash as a single entry, rather
  53   than using the logstash multiline codec.
  54
  55 log-courier.conf
  56
  57   An example configuration for the log-courier feeder.
  58
  59 kibana4-dashboard.json
  60
  61   Basic RADIUS dashboard for Kibana 4 and Kibana 5.
  62
  63   To import the dashboard first create a new index called "radius-*" in
  64   Settings/Indices. Then go to Kibana's Settings page, "Objects" and "Import".
  65   Once imported open the "RADIUS detail" dashboard.
  66
  67
  68 Example usage
  69 -------------
  70
  71 Install mapping (only needs to be done once):
  72
  73     $ ./radius-mapping.sh
  74
  75 Edit logstash-radius.conf to point to the correct file, then feed a detail file
  76 in:
  77
  78     # /usr/share/logstash/bin/logstash --path.settings=/etc/logstash -f logstash-radius.conf
  79
  80
  81 See also
  82 --------
  83
  84 elasticsearch web site: http://www.elastic.co/
  85
  86 The configuration examples presented here have been tested with the
  87 following software versions (note that elasticsearch 2.x may not yet
  88 work with this config).
  89
  90   elasticsearch 5.1.2
  91   logstash 5.1.2
  92   kibana 5.1.2
  93   kibana 4.1.11
  94
  95 Matthew Newton
  96 January 2017
  97