diff --git a/technical_manual/Architechture.png b/technical_manual/Architechture.png deleted file mode 100644 index c0e80ab..0000000 Binary files a/technical_manual/Architechture.png and /dev/null differ diff --git a/technical_manual/CommunicationDiagram.png b/technical_manual/CommunicationDiagram.png deleted file mode 100644 index 96a8e6a..0000000 Binary files a/technical_manual/CommunicationDiagram.png and /dev/null differ diff --git a/technical_manual/technical_manual.pdf b/technical_manual/technical_manual.pdf index 33856ab..774df10 100644 Binary files a/technical_manual/technical_manual.pdf and b/technical_manual/technical_manual.pdf differ diff --git a/user_manual/images/NetworkDiagram.png b/user_manual/images/NetworkDiagram.png new file mode 100644 index 0000000..2375379 Binary files /dev/null and b/user_manual/images/NetworkDiagram.png differ diff --git a/user_manual/images/grafanaMetrics.png b/user_manual/images/grafanaMetrics.png new file mode 100644 index 0000000..8549b26 Binary files /dev/null and b/user_manual/images/grafanaMetrics.png differ diff --git a/user_manual/images/grafanalogin.png b/user_manual/images/grafanalogin.png new file mode 100644 index 0000000..aaaec79 Binary files /dev/null and b/user_manual/images/grafanalogin.png differ diff --git a/user_manual/images/graphite.png b/user_manual/images/graphite.png new file mode 100644 index 0000000..eb4145d Binary files /dev/null and b/user_manual/images/graphite.png differ diff --git a/user_manual/user_manual.md b/user_manual/user_manual.md index c715b54..dd15a98 100644 --- a/user_manual/user_manual.md +++ b/user_manual/user_manual.md @@ -2,4 +2,248 @@ ## Contents -* Please refer to readme.md until submittion +1. Dependencies +2. How to install + - 2.1 Install OS + - 2.1 Installing system +3. How to use +4. Configuration +5. Plugins Created +6. Help +7. Installing graphite +8. Installing grafana +9. Configuring Diagram Drawer + +### Dependencies + +* Python **3.6** or higher +* Pip3 for installing requirements in requirments.txt +* You can also see a list of required modules in requirments.txt + +### How to install + +#### Installing the OS + +First we need to download the kali linux image from [kali website](https://www.offensive-security.com/kali-linux-arm-images/#1493408272250-e17e9049-9ce8) + +Or with the following command + +```bash +$ wget https://images.offensive-security.com/arm-images/kali-linux-2018.1a-rpi3-nexmon.img.xz +``` + +> **Remember** : Never download Kali Linux images from anywhere other than the official sources, and you should go [here](https://docs.kali.org/kali-on-arm/install-kali-linux-arm-raspberry-pi) to see how to verify your image + +Once we have our image we want to write it to and sd card. Insert the sd card into your machine and type + +```bash +$ sudo fdisk -l +``` + +Find the disk that is your sd card (should be something like /dev/sdb, but may not) + +> **Warning** Make sure this is not your harddrive and is your sd card, everything will be overwritten + +When you have found your card you can write the image to the card with the following command + +```bash +$ sudo dd if=PATH of=DEST bs=512k +``` + +where PATH will be the path to where you downloaded the fie to +and DEST will be the path to your sd card we found earlier, e.g. /dev/sdb + +Now you can remove your sd card pop it in your pi and boot it up. We are gonna need a monitor keyboard and mouse for this next bit + +#### Installing the Software on the OS + +```bash +$ git clone https://gitlab.computing.dcu.ie/doylet9/2018-CA326-tdoyle-distributedwifimonitoring.git +$ cd 2018-CA326-tdoyle-distributedwifimonitoring/code/ +$ chmod +x install.sh +$ ./install.sh +``` + +### How to use + +* Once installed all the plugins will run on reboot. +* If you do not want to reboot you can run them manualy by running the following options + +```bash +$ ./start # To start all the plugins + +$ ./stop # To stop all the plugins + +$ ./start && ./stop # To restart all the plugins +``` + +> If you do not like, want or need a plugin just move it to another folder + +```bash +$ mkdir bakupPlugins +$ mv pluings/example bakupPlugins/example +``` + +### Configuration + +You can change many things about the project so that is runs to suit your needs. The following is an example config you can use to get your started. + +> You should edit your config.json created after install not the config.example + +> You can also edit you hostname in /etc/hostname so that each node has a unique name + +#### Example Config + +```json +{ + "slack": { + "slack_token": "Insert slack token", + "slack_channel": "#random", + "slack_emoji": ":robot_face:", + "slack_username": "Panoptes Alerts"}, + "ap_metrics":{ + "sleeptime" : 1, + "interface" : "mon1", + "pktcount" : 500}, + "nodeup" : { + "sleeptime" : 2}, + "system_stats" : { + "errorlog" : "/var/log/panoptes/system.log", + "sleeptime" : 2}, + "ssid_detection" : { + "interface": "mon1", + "errorlog" : "/var/log/panoptes/system.log", + "known_ssids" : "/etc/panoptes/known_ssids.txt"}, + "ping_metrics" : { + "sleeptime" : 1}, + "packet_stats": { + "timeout" : 1, + "interface": "mon1"}, + "pushbullet": { + "push_device_tokens": ["insert api tokens"]} +} +``` +##### slack + +This specifies settings for slack messages (used for alerts) +> **slack_token**: An api key for your slack channel. +> **slack_channel**: What slack channel do you want you alerts to go to. +> **slack_emojii**: What emoji will be the character for your slack messenger +> **slack_username**: Username of the message sender + +##### ap_metrics + +This specifies settings for ap_metrics plugin +> **sleeptime**: How often the plugin will run (Seconds) +> **interface**: What interface will the pllugin use to sniff +> **pktcount**: How many packets will the plugin sniff before analysing + +##### nodeup + +This specifies settings for node up, a phone home plugin +> **sleeptime**: How often plugin runs i.e. How often it reports home (Seconds) + +##### system_stats + +This specifies setting for collecting metrics about the nodes load +> **errorlog**: Where the error log will write to +> **sleeptime**: How often the pluigin runs (Seconds) + +##### ssid_detection + +This specifies settings for ssid detection plugin +> **interface**: What interface should we sniff on +> **errorlog**: Where to write errors to +> **known_ssids**: Where to read from for known ssids + +##### ping_metrics + +This specifies settings for ping metrics plugin +> **sleeptime**: How often to run plugin (Seconds) + +##### pushbullet + +This specifes setting for pushbullet alerts +> **push_device_tokens**: is a list of api keys for each device you want to alert, becuase there is no group functionality in pushbullet + + +### Plugins created + +* [X] Ssid detection - Detects ssids spoofing trusted ones +* [X] Metric fling - Exports metrics to graphite database +* [X] Access Point Metrics - Collects signal from surrounding access points +* [X] System Load Average - Collects load average for nodes +* [X] Nodes Up - Reports if a node is up +* [X] Ping Metrics - Reports latency metrics + +### Help + +You can find help with the help function + +```bash +$ python3.6 panoptes.py -h +``` + +Find solved issues and create new issues on the [gitlab issues](https://gitlab.computing.dcu.ie/doylet9/2018-CA326-tdoyle-distributedwifimonitoring/issues) page for this project + +### Installing Graphite + +This guide does not cover installing graphite. Refer to this [guide](https://graphite.readthedocs.io/en/latest/install.html) + +When you get it running graphite has a web interface. It should look like this: + +![graphite](images/graphite.png) + +Graphite is quite bare bones and not as pretty as alertitives for graphs. So we are also using grafana + +### Installing Grafana + +This guide does not cover installing grafanan. Refer to this [guide](http://docs.grafana.org/installation/) + +When you are done you should be greated by this login page. + +![grafana login](images/grafanalogin.png) + +Then you can follow grafana's already great [guides](http://docs.grafana.org/guides/getting_started/) to get started. + +When you have your graphs set up they could look something like this. + +![grafana dashboard](images/grafanaMetrics.png) + +### Setting up Diagram drawer + +The diagram drawer is set up to put an index.html page in your /var/www/ directory in a subdirectory called diagrams. + +They only configuration for this is to point your site at it, possibly using apache. + +![network diagram](images/NetworkDiagram.png) + +**Example Apache Config** + +```apache + + + + ServerName diagram.example.xyz + ServerAdmin admin@example.xys + DocumentRoot /var/www/diagrams/ + + ErrorLog ${APACHE_LOG_DIR}/error.log + CustomLog ${APACHE_LOG_DIR}/access.log combined + + + + + + + ServerName diagram.example.xyz + ServerAdmin admin@example.xys + DocumentRoot /var/www/diagrams/ + + ErrorLog ${APACHE_LOG_DIR}/error.log + CustomLog ${APACHE_LOG_DIR}/access.log combined + + + + +``` diff --git a/user_manual/user_manual.pdf b/user_manual/user_manual.pdf new file mode 100644 index 0000000..b977cd1 Binary files /dev/null and b/user_manual/user_manual.pdf differ