afonso/core-extra
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

docs: adding tutorial 1

Browse source
This commit is contained in:
Blake J. Harnden 2023-06-05 11:11:00 -07:00
parent 01585b6ec5
commit a5727e3355
12 changed files with 764 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs/tutorials/common/grpc.md Normal file
View file

@ -0,0 +1,22 @@
## gRPC Python Scripts
You can also run the same steps above, using the provided gRPC script versions of scenarios.
Below are the steps to run and join one of these scenario, then you can continue with
the remaining steps of a given section.
1. Make sure the CORE daemon is running a terminal, if not already
``` shell
sudop core-daemon
```
2. From another terminal run the tutorial python script, which will create a session to join
``` shell
/opt/core/venv/bin/python scenario.py
```
3. In another terminal run the CORE GUI
``` shell
core-gui
```
4. You will be presented with sessions to join, select the one created by the script
<p align="center">
<img src="images/tutorial-common/running-join.png" width="75%">
</p>

82
docs/tutorials/setup.md Normal file
View file

@ -0,0 +1,82 @@
# Tutorial Setup
## Setup for CORE
We assume the prior installation of CORE, using a virtual environment. You can
then adjust your PATH and add an alias to help more conveniently run CORE
commands.
This can be setup in your **.bashrc**
```shell
export PATH=$PATH:/opt/core/venv/bin
alias sudop='sudo env PATH=$PATH'
```
## Setup for Chat App
There is a simple TCP chat app provided as example software to use and run within
the tutorials provided.
### Installation
The following will install chatapp and its scripts into **/usr/local**, which you
may need to add to PATH within node to be able to use command directly.
``` shell
sudo python3 -m pip install .
```
!!! note
Some Linux distros will not have **/usr/local** in their PATH and you
will need to compensate.
``` shell
export PATH=$PATH:/usr/local
```
### Running the Server
The server will print and log connected clients and their messages.
``` shell
usage: chatapp-server [-h] [-a ADDRESS] [-p PORT]
chat app server
optional arguments:
-h, --help show this help message and exit
-a ADDRESS, --address ADDRESS
address to listen on (default: )
-p PORT, --port PORT port to listen on (default: 9001)
```
### Running the Client
The client will print and log messages from other clients and their join/leave status.
``` shell
usage: chatapp-client [-h] -a ADDRESS [-p PORT]
chat app client
optional arguments:
-h, --help show this help message and exit
-a ADDRESS, --address ADDRESS
address to listen on (default: None)
-p PORT, --port PORT port to listen on (default: 9001)
```
### Installing the Chat App Service
1. You will first need to edit **/etc/core/core.conf** to update the config
service path to pick up your service
``` shell
custom_config_services_dir = <path for service>
```
2. Then you will need to copy/move **chatapp/chatapp_service.py** to the directory
configured above
3. Then you will need to restart the **core-daemon** to pick up this new service
4. Now the service will be an available option under the group **ChatApp** with
the name **ChatApp Server**

250
docs/tutorials/tutorial1.md Normal file
View file

@ -0,0 +1,250 @@
# Tutorial 1 - Wired Network
This tutorial will cover some use cases when using a wired 2 node
scenario in CORE.
<p align="center">
<img src="images/tutorial1/scenario.png" width="75%">
</p>
## Files
Below is the list of files used for this tutorial.
* 2 node wired scenario
* scenario.xml
* scenario.py
* 2 node wired scenario, with **n1** running the "Chat App Server" service
* scenario_service.xml
* scenario_service.py
## Running this Tutorial
This section covers interactions that can be carried out for this scenario.
Our scenario has the following nodes and addresses:
* n1 - 10.0.0.20
* n2 - 10.0.0.21
All usages below assume a clean scenario start.
### Using Ping
Using the command line utility **ping** can be a good way to verify connectivity
between nodes in CORE.
* Make sure the CORE daemon is running a terminal, if not already
``` shell
sudop core-daemon
```
* In another terminal run the GUI
``` shell
core-gui
```
* In the GUI menu bar select **File->Open...**, then navigate to and select **scenario.xml**
<p align="center">
<img src="images/tutorial-common/running-open.png" width="75%">
</p>
* You can now click on the **Start Session** button to run the scenario
<p align="center">
<img src="images/tutorial1/scenario.png" width="75%">
</p>
* Open a terminal on **n1** by double clicking it in the GUI
* Run the following in **n1** terminal
``` shell
ping -c 3 10.0.0.21
```
* You should see the following output
``` shell
PING 10.0.0.21 (10.0.0.21) 56(84) bytes of data.
64 bytes from 10.0.0.21: icmp_seq=1 ttl=64 time=0.085 ms
64 bytes from 10.0.0.21: icmp_seq=2 ttl=64 time=0.079 ms
64 bytes from 10.0.0.21: icmp_seq=3 ttl=64 time=0.072 ms
--- 10.0.0.21 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 1999ms
rtt min/avg/max/mdev = 0.072/0.078/0.085/0.011 ms
```
### Using Tcpdump
Using **tcpdump** can be very beneficial for examining a network. You can verify
traffic being sent/received among many other uses.
* Make sure the CORE daemon is running a terminal, if not already
``` shell
sudop core-daemon
```
* In another terminal run the GUI
``` shell
core-gui
```
* In the GUI menu bar select **File->Open...**, then navigate to and select **scenario.xml**
<p align="center">
<img src="images/tutorial-common/running-open.png" width="75%">
</p>
* You can now click on the **Start Session** button to run the scenario
<p align="center">
<img src="images/tutorial1/scenario.png" width="75%">
</p>
* Open a terminal on **n1** by double clicking it in the GUI
* Open a terminal on **n2** by double clicking it in the GUI
* Run the following in **n2** terminal
``` shell
tcpdump -lenni eth0
```
* Run the following in **n1** terminal
``` shell
ping -c 1 10.0.0.21
```
* You should see the following in **n2** terminal
``` shell
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
10:23:04.685292 00:00:00:aa:00:00 > 00:00:00:aa:00:01, ethertype IPv4 (0x0800), length 98: 10.0.0.20 > 10.0.0.21: ICMP echo request, id 67, seq 1, length 64
10:23:04.685329 00:00:00:aa:00:01 > 00:00:00:aa:00:00, ethertype IPv4 (0x0800), length 98: 10.0.0.21 > 10.0.0.20: ICMP echo reply, id 67, seq 1, length 64
```
### Editing a Link
You can edit links between nodes in CORE to modify loss, delay, bandwidth, and more. This can be
beneficial for understanding how software will behave in adverse conditions.
* Make sure the CORE daemon is running a terminal, if not already
``` shell
sudop core-daemon
```
* In another terminal run the GUI
``` shell
core-gui
```
* In the GUI menu bar select **File->Open...**, then navigate to and select **scenario.xml**
<p align="center">
<img src="images/tutorial-common/running-open.png" width="75%">
</p>
* You can now click on the **Start Session** button to run the scenario
<p align="center">
<img src="images/tutorial1/scenario.png" width="75%">
</p>
* Right click the link between **n1** and **n2**
* Select **Configure**
<p align="center">
<img src="images/tutorial1/link-config.png" width="75%">
</p>
* Update the loss to **25**
<p align="center">
<img src="images/tutorial1/link-config-dialog.png" width="50%">
</p>
* Open a terminal on **n1** by double clicking it in the GUI
* Run the following in **n1** terminal
``` shell
ping -c 10 10.0.0.21
```
* You should see something similar for the summary output, reflecting the change in loss
``` shell
--- 10.0.0.21 ping statistics ---
10 packets transmitted, 6 received, 40% packet loss, time 9000ms
rtt min/avg/max/mdev = 0.077/0.093/0.108/0.016 ms
```
* Remember that the loss above is compounded, since a ping and the loss applied occurs in both directions
### Running Software
We will now leverage the installed Chat App software to stand up a server and client
within the nodes of our scenario.
* Make sure the CORE daemon is running a terminal, if not already
``` shell
sudop core-daemon
```
* In another terminal run the GUI
``` shell
core-gui
```
* In the GUI menu bar select **File->Open...**, then navigate to and select **scenario.xml**
<p align="center">
<img src="images/tutorial-common/running-open.png" width="75%">
</p>
* You can now click on the **Start Session** button to run the scenario
<p align="center">
<img src="images/tutorial1/scenario.png" width="75%">
</p>
* Open a terminal on **n1** by double clicking it in the GUI
* Run the following in **n1** terminal
``` shell
export PATH=$PATH:/usr/local/bin
chatapp-server
```
* Open a terminal on **n2** by double clicking it in the GUI
* Run the following in **n2** terminal
``` shell
export PATH=$PATH:/usr/local/bin
chatapp-client -a 10.0.0.20
```
* You will see the following output in **n1** terminal
``` shell
chat server listening on: :9001
[server] 10.0.0.21:44362 joining
```
* Type the following in **n2** terminal and hit enter
``` shell
hello world
```
* You will see the following output in **n1** terminal
``` shell
chat server listening on: :9001
[server] 10.0.0.21:44362 joining
[10.0.0.21:44362] hello world
```
### Tailing a Log
In this case we are using the service based scenario. This will automatically start
and run the Chat App Server on **n1** and log to a file. This case will demonstrate
using `tail -f` to observe the output of running software.
* Make sure the CORE daemon is running a terminal, if not already
``` shell
sudop core-daemon
```
* In another terminal run the GUI
``` shell
core-gui
```
* In the GUI menu bar select **File->Open...**, then navigate to and select **scenario_service.xml**
<p align="center">
<img src="images/tutorial-common/running-open.png" width="75%">
</p>
* You can now click on the **Start Session** button to run the scenario
<p align="center">
<img src="images/tutorial1/scenario.png" width="75%">
</p>
* Open a terminal on **n1** by double clicking it in the GUI
* Run the following in **n1** terminal
``` shell
tail -f chatapp.log
```
* Open a terminal on **n2** by double clicking it in the GUI
* Run the following in **n2** terminal
``` shell
export PATH=$PATH:/usr/local/bin
chatapp-client -a 10.0.0.20
```
* You will see the following output in **n1** terminal
``` shell
chat server listening on: :9001
[server] 10.0.0.21:44362 joining
```
* Type the following in **n2** terminal and hit enter
``` shell
hello world
```
* You will see the following output in **n1** terminal
``` shell
chat server listening on: :9001
[server] 10.0.0.21:44362 joining
[10.0.0.21:44362] hello world
```
--8<-- "common/grpc.md"