Skip to content

Proofread and changed formatting #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
Open

Proofread and changed formatting #3

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
9e5cc5d
Update README.md
ploparmor Sep 19, 2019
00c04d8
Merge pull request #1 from ploparmor/ploparmor-patch-1.2
ploparmor Sep 19, 2019
c9a9ae4
Update README.md
ploparmor Sep 19, 2019
df774c9
Update README.md
ploparmor Sep 19, 2019
18363a4
Update README.md
ploparmor Sep 19, 2019
023c242
Update README.md
ploparmor Sep 19, 2019
682a303
Merge pull request #2 from ploparmor/ploparmor-branch-test-1.1
ploparmor Sep 19, 2019
86d8233
Update README.md
ploparmor Sep 19, 2019
3f0862f
Update README.md
ploparmor Sep 19, 2019
4af29d3
Update README.md
ploparmor Jan 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 34 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@

## Overview

SCADA sensor networks are ubiquitous in industry and notoriously difficult to secure effectively. This simulator generates network traffic in a virtual environment and allows students the opportunity to view and work with modbus traffic, the protocol used by SCADA systems. This system fully encompasses a basic SCADA network and allows 1 to N PLC devices attached to HMIs that feed into a central historian. The topology is controled by a single json configuration file, allowing for simple or complex sensor networks.
SCADA sensor networks are ubiquitous in industry and notoriously difficult to secure effectively. This simulator generates network traffic in a virtual environment and allows students the opportunity to view and work with modbus traffic, the protocol used by SCADA systems. This system fully encompasses a basic SCADA network and allows 1 to N PLC devices attached to HMIs that feed into a central historian. The topology is controlled by a single json configuration file, allowing for simple or complex sensor networks.

## Getting Started

The SCADA simulator requires at least three different systems: A historian, one or more HMIs, and a PLC. Each component can run on an independent Ubuntu virtual machine.

#<center> Table of Contents</center>
# Table of Contents
1. [Check out SCADA code](#Pull-SCADA-Source-Code)
2. [Install Dependencies](#Install-Dependencies)
3. [Setup Postgres DB](#Setup-Postgres-DB-for-Deployment)
4. [Initilize SCADA](#Initilize-SCADA)
3. [Setup Postgres Database](#Setup-Postgres-DB-for-Deployment)
4. [Initialize SCADA](#Initialize-SCADA)
5. [Local Deployment](#Local-Deployment)
6. [Historian Deployment](#Historian-Deployment)
7. [HMI Deployment](#HMI-Deployment)
Expand Down Expand Up @@ -46,13 +46,13 @@ $ systemctl start postgresql && systemctl enable postgresql
```bash
$ python ./init.py --help # Help CLI arguments
$ python ./init.py -f path/to/config.json -u <db-username> -d <db-name> -w <db-password> # Local
$ python ./init.py -s -f path/to/config.json -u <db-username> -d <db-name> -w <db-password> # Distrobuted
$ python ./init.py -s -f path/to/config.json -u <db-username> -d <db-name> -w <db-password> # Distributed
```
Troubleshoot 1: Make sure if you have a distributed SCADA network that you can connect to HMIs defined in the configuration file.

Troubleshoot 2: Ensure the postgres service is on and the pg_hba.conf file allows for users to connect remotely to the defined HMIs.
## 5. <a name="Local-Deployment"></a>Local Deployment - Open three terminals and navigate to the SCADA home directory
<center>**Data Server - Terminal 1**</center>
**Data Server - Terminal 1**
```bash
$ python ./dataserver.py --help # Help CLI arguments
$ python ./dataserver.py -u <db-username> -d <db-name> -w <db-password>
Expand All @@ -61,7 +61,7 @@ Open browser and go to http://localhost:5000

Troubleshoot 1: Default port is port 5000 ensure that the firewall allows communication over port 5000.

<center>**HMI Server - Terminal 2**</center>
**HMI Server - Terminal 2**
```bash
$ python ./HMI_Server.py --help # Help CLI arguments
$ python ./HMI_Server.py -p 5001 -u <db-username> -d <db-name> -w <db-password>
Expand All @@ -70,7 +70,7 @@ Troubleshoot 1: Ensure that the Data Server is started and currently running.

Troubleshoot 2: Ensure firewall allows communication over port 5001 local

<center>**PLC Engine - Terminal 3**</center>
**PLC Engine - Terminal 3**
```bash
$ python ./PLC_manager.py --help # Help CLI arguments
$ python ./PLC_manager.py -f path/to/config.json
Expand All @@ -81,21 +81,21 @@ Troubleshoot 2: Ensure firewall allows communication over port 5001 local.

## 6. <a name="Historian-Deployment"></a>Historian Deployment - Only the Data Server is required for the historian

<center>**Data Server - Terminal 1**</center>
**Data Server - Terminal 1**
```bash
$ python ./dataserver.py --help # Help CLI arguments
$ python ./dataserver.py -i <host-ip> -p <host-port> -u <db-username> -d <db-name> -w <db-password>
```
Troubleshoot 1: Ensure that the firewall allows communication over the defined port. If the port number is low then sudo may be required.
## 7. <a name="HMI-Deployment"></a>HMI Deployment - Open two terminals and navigate to JASPR home directory.

<center>**Data Server - Terminal 1**</center>
**Data Server - Terminal 1**
```bash
$ python ./dataserver.py --help # Help CLI arguments
$ python ./dataserver.py -i <host-ip> -p <host-port> -u <db-username> -d <db-name> -w <db-password>
```
Troubleshoot 1: Ensure that the firewall allows communication over the defined port. If the port number is low then sudo may be required.
<center>**7b. HMI Server - Terminal 2**</center>
**7b. HMI Server - Terminal 2**
```bash
$ python ./HMI_Server.py --help # Help CLI arguments
$ python ./HMI_Server.py -i <host-ip> -p <host-port> -u <db-username> -d <db-name> -w <db-password>
Expand All @@ -112,19 +112,17 @@ $ python ./PLC_engine.py -H http://<host-ip>:<host-port>/api/modbus-config
```

## 9. <a name="Configuration-File-Standard"></a>Configuration File Standard
* 9a. This project simulates a SCADA system that has three unique parts: Histoian, HMI, and PLC. The Historian is the central repository for all of the Human-Managment Interfaces. The Historian poles the HMIs to gather a historiacal picture of what the HMIs are seeing. The default poling interval is 30 seconds, if the poling interval should be larger or shorter then the sleep time in HMI_Server.py/historina_handler can be changed up or down. The HMIs are a real time view of the PLC devices readings. This allows users to identify real time issues associated with each individual PLC devices. The HMI unlike the Historian only maintains records of the last 1000 readings pulled from the PLC devices. Finally the PLC devices are modled off of the arduino controller archetecture. Each ardunino has its own unique IP address and allows two way communication. These modules are comprised of actuators and sensors with the actuators having direct relationship with the sesnors, meaning if a heater actuator is turned up the temperture sensor will start rising in value. The next couple of sections will walk you through how to properly configure the json configuration file in order to correctly map your SCADA System.
* 9a. This project simulates a SCADA system that has three unique parts: Historian, HMI, and PLC. The Historian is the central repository for all of the Human-Managment Interfaces. The Historian polls the HMIs to gather a historical picture of what the HMIs are seeing. The default polling interval is 30 seconds, if the polling interval should be larger or shorter then the sleep time in HMI_Server.py/historian_handler can be changed up or down. The HMIs are a real time view of the PLC devices readings. This allows users to identify real time issues associated with each individual PLC devices. The HMI unlike the Historian only maintains records of the last 1000 readings pulled from the PLC devices. Finally the PLC devices are modeled off of the arduino controller architecture. Each arduino has its own unique IP address and allows two way communication. These modules are comprised of actuators and sensors with the actuators having direct relationship with the sensors, meaning if a heater actuator is turned up the temperture sensor will start rising in value. The next couple of sections will walk you through how to properly configure the json configuration file in order to correctly map your SCADA System.
* **9b. Historian**
* 9b.1 The required keys are: name_system, name, location, actuators, and sub_devices. The default IP address is 127.0.0.1 and listening port is 5020
* 9b.2 Sub Devices are HMIs or Controllers(PLC Device) the Historian cannot have any controller devices and must have atleaset one HMI
* 9b.3 The "Status" Actuator is required for all devices this allows users to turn on and off services that the device provides as well as all services dependant on the device ex: if the Historian is disabled then all HMIs will be disabled and all PLC devices relying on the HMI.
* 9b.2 Sub Devices are HMIs or Controllers(PLC Device) the Historian cannot have any controller devices and must have atleast one HMI
* 9b.3 The "Status" Actuator is required for all devices this allows users to turn on and off services that the device provides as well as all services dependent on the device ex: if the Historian is disabled then all HMIs will be disabled and all PLC devices relying on the HMI.
* 9b.4 The Historian only has one Actuator and cannot have any additional sensors or actuators.
* 9b.5 Below is an example of the Hisorian Configuration:

<center>**Example Historian Configuration**</center>
```json
* 9b.5 **Example of Historian Configuration:**
```json5
{
"Historian": {
"name_system": <SCADA SYSTEM NAME>,
"name_system": <SCADA_SYSTEM_NAME>,
"name": <Historian NAME>,
"location": <Location>,
"device_type": "Historian",
Expand All @@ -139,15 +137,13 @@ $ python ./PLC_engine.py -H http://<host-ip>:<host-port>/api/modbus-config
"sub_devices" : {}
}
```

* **9c. HMI**
* 9c.1 The required keys are: name_system, name, location, actuators, and sub_devices. The default Host and HMI IP address is 127.0.0.1 and listening port for the host is 5020 and HMI is 5021
* 9c.2 The Host IP address is the web page front end for the HMI while the HMI IP address is the interface communicating with the PLC devices
* 9c.3 The HMI only has one Actuator and cannot have any additional sensors or actuators.
* 9c.4 The HMI Identifier is a unique string that identifies the HMI. This is what will be used to bind PLC devices to the HMI and can be any unique string

<center>**Example HMI Configuration**</center>
```json
* **Example of HMI Configuration:**
```json5
<HMI Identifier> : {
"name_system": <HMI System Name>,
"name": <HMI Name>,
Expand All @@ -168,12 +164,11 @@ $ python ./PLC_engine.py -H http://<host-ip>:<host-port>/api/modbus-config
```
* **9d. Controller**
* 9d.1 The required keys are: name_system, name, location, and sub_devices.
* 9d.2 The IP address will be assigned during the initilization phase of deployment
* 9d.3 The controller can have as many actuators and sensors necessary but, must have atleaset one actuator or sensor.
* 9d.2 The IP address will be assigned during the initialization phase of deployment
* 9d.3 The controller can have as many actuators and sensors necessary but, must have atleast one actuator or sensor.
* 9d.4 The PLC Identifier is a unique string that identifies the HMI. This is what will be used to bind PLC devices to the HMI and can be any unique string

<center>**Example Controller Configuration**</center>
```json
* **Example of Controller Configuration:**
```json5
<PLC Identifier> : {
"name_system": <PLC System Name>,
"name": <PLC Name>,
Expand All @@ -186,12 +181,11 @@ $ python ./PLC_engine.py -H http://<host-ip>:<host-port>/api/modbus-config
```
* **9e. Sensor**
* 9e.1 The required keys are: type, units, initial_value, and variability.
* 9e.2 The variability is the how far +- the sensor readings will flucuate from the current_value
* 9e.2 The variability is the how far +- the sensor readings will fluctuate from the current_value
* 9e.3 The valid types are: "locked", "enabled", "open", "temperature", "pressure", "humidity", "flow", "live-stream", "speed", "rotation", "power", "motion"
* 9e.4 The threshold is optional if not defined the PLC will only fail if the controller tells it to fail. Otherwise the Sensors Controller will fail/shutoff if the sensor reads below the min or above the max

<center>**Example Sensor Configuration**</center>
```json
* **Example of the Sensor Configuration:**
```json5
<Sensor Identifier>: {
"type": <PLC Type>,
"units": <Unit of Measure>,
Expand All @@ -202,24 +196,21 @@ $ python ./PLC_engine.py -H http://<host-ip>:<host-port>/api/modbus-config
```
* **9f. Actuator**
* 9f.1 The required keys are: type, and initial_value.
* 9f.2 The relationship can be as follows: positive - The value increases, negative - The value decreases, and variable - The value can both increase or decrease according to the current value (0 OFF 1 Decrease 2 Maintian 3 Increase)
* 9f.2 The relationship can be as follows: positive - The value increases, negative - The value decreases, and variable - The value can both increase or decrease according to the current value (0 OFF 1 Decrease 2 Maintain 3 Increase)
* 9f.3 The valid types are: "locked", "enabled", "live-stream", "variable", "relational" with locked, enabled and live-stream will have sensors the reflect the actuator current value
* 9f.4 Type with Variable will have a relationship of positive or negative while relational will have a relationship of variable
* 9f.5 The master field must have the sensor identifier of which sensor that will reflect the changes spawned from the actuator

<center>**Example Actuator Configuration**</center>
```json
<Actuaror Identifier>: {
* **Example of Actuator Configuration:**
```json5
<Actuator Identifier>: {
"type": <PLC Type>,
"initial_value": <Initial Value>,
"master" : <Sensor Identifier>,
"relationship": <Relationship Type>
}
```
* **9e. Complete Example:**

<center>**Example**</center>
```json
```json5
{
"Historian": {
"name_system": "SCADA System",
Expand Down Expand Up @@ -319,15 +310,15 @@ $ python ./PLC_engine.py -H http://<host-ip>:<host-port>/api/modbus-config
```

## 10. <a name="Install and Configure Docker"></a>Install and Configure Docker
To install Docker on your PLC Box follow the instructions in the following Link: https://docs.docker.com/engine/installation/, however this guide will be going over how to install on a CentOS 5 or above.
<center>**Download and Install Docker (you must be in the scada home directory)**</center>
To install Docker on your PLC Box follow the instructions in the following Link: https://docs.docker.com/engine/installation/, however this guide will be going over how to install on a CentOS 5 or above.
**Download and Install Docker (you must be in the scada home directory)**
```bash
$ cp ./docker.repo /etc/yum.repos.d
$ sudo yum update && sudo yum install docker-engine
$ sudo systemctl enable docker.service
$ sudo systemctl start docker.service
```

<center>**Prepare docker image for ardunio engine**</center>
**Prepare docker image for arduino engine**
```bash
```