README.md

   1 netdata
   2 =======
   3
   4 linux network traffic web monitoring
   5
   6 This little program will allow you to create embedable live monitoring charts on any web page.
   7
   8 Example server with 6 interfaces:
   9 ![image](https://f.cloud.github.com/assets/2662304/664777/3dad6c32-d78d-11e2-9ecf-b921afebfb0b.png)
  10
  11 Example server with 20 interfaces:
  12 ![image](https://f.cloud.github.com/assets/2662304/689979/807dfb4e-dac6-11e2-8546-6d83fdb05866.png)
  13
  14
  15 # How it works
  16
  17 1. You run a daemon on your linux: netdata.
  18  This deamon is written in C and is extremely lightweight.
  19
  20  netdata:
  21
  22   - reads /proc/net/dev and for every interface present there it keeps in its memory a short history of its received and sent bytes.
  23   - generates JSON HTTP responses containing all the data needed for the web graphs.
  24   - is a web server. You can access JSON data by using:
  25
  26  ```
  27  http://127.0.0.1:19999/data/net.eth0
  28  ```
  29
  30  This will give you the JSON file for traffic on eth0.
  31  The above is equivalent to:
  32
  33  ```
  34  http://127.0.0.1:19999/data/net.eth0/3600/1/average
  35  ```
  36
  37  where:
  38
  39   - 3600 is the number of entries to generate (3600 is a default which can be overwritten by -l).
  40   - 1 is grouping count, 1 = every single entry, 2 = half the entries, 3 = one every 3 entries, etc
  41   - `average` is the grouping method. It can also be `max`.
  42
  43
  44 2. On your web page, you add a few javascript lines and a DIV for every graph you need.
  45  Your browser will hit the web server to fetch the JSON data and refresh the graphs.
  46
  47 3. Graphs are generated using Google Charts API.
  48
  49
  50
  51 # Installation
  52
  53 ## Automatic installation
  54
  55 1. Download everything in a directory inside your web server.
  56 2. cd to that directory
  57 3. run:
  58
  59 ```sh
  60 ./netdata.start
  61 ```
  62
  63 For this to work, you need to have persmission to create a directory in /run or /var/run or /tmp.
  64 If you run into problems, try to become root to verify it works. Please, do not run netdata are root permanently.
  65 Since netdata is a web server, the right thing to do, is to have a special user for it.
  66
  67 Once you run it, the file netdata.conf will be created. You can edit this file to set options for each graph.
  68 To apply the changes you made, you have to run netdata.start again.
  69
  70 To access the panel for all graphs, go to:
  71
  72  ```
  73  http://127.0.0.1:19999/
  74  ```
  75
  76
  77
  78 ---
  79
  80 ## Installation by hand
  81
  82 ### Compile netdata
  83 step into the directory you downloaded everything and compile netdata
  84
  85 ```sh
  86 gcc -Wall -O3 -o netdata netdata.c -lpthread
  87 ```
  88
  89 ### run netdata
  90 Run netdata:
  91
  92 ```sh
  93 ./netdata -d -l 60 -u 1 -p 19999
  94 ```
  95  - -d says to go daemon mode
  96  - -l 60 says to keep 60 history entries
  97  - -u 1 says to add a new history entry every second
  98  - -p 19999 is the port to listen for web clients
  99
 100 ### edit index.html
 101 Set in index.html the interfaces you would like to monitor on the web page.
 102
 103 ** REMEMBER: there are 2 sections in index.html to edit. A javascript section and an HTML section. **
 104
 105 ### open a web browser
 106
 107  ```
 108  http://127.0.0.1:19999/
 109  ```
 110
 111