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

docs: updates to leverage mkdocs material admonitions

Browse source
This commit is contained in:
Blake Harnden 2023-03-28 21:42:43 -07:00
parent 5b41b4e5be
commit 0053ddb57d
13 changed files with 533 additions and 436 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
docs/configservices.md
View file

@ -79,30 +79,28 @@ introduced to automate tasks.
### Creating New Services
!!! note
The directory base name used in **custom_services_dir** below should
be unique and should not correspond to any existing Python module name.
For example, don't use the name **subprocess** or **services**.
1. Modify the example service shown below
to do what you want. It could generate config/script files, mount per-node
directories, start processes/scripts, etc. Your file can define one or more
classes to be imported. You can create multiple Python files that will be imported.
2. Put these files in a directory such as ~/.coregui/custom_services
Note that the last component of this directory name **myservices** should not
be named something like **services** which conflicts with an existing module.
2. Put these files in a directory such as **~/.coregui/custom_services**.
3. Add a **custom_config_services_dir = ~/.coregui/custom_services** entry to the
/etc/core/core.conf file.
**NOTE:**
The directory name used in **custom_services_dir** should be unique and
should not correspond to
any existing Python module name. For example, don't use the name **subprocess**
or **services**.
4. Restart the CORE daemon (core-daemon). Any import errors (Python syntax)
should be displayed in the terminal (or service log, like journalctl).
5. Start using your custom service on your nodes. You can create a new node
type that uses your service, or change the default services for an existing
node type, or change individual nodes. .
node type, or change individual nodes.
### Example Custom Service

46
docs/ctrlnet.md
View file

@ -27,15 +27,19 @@ new sessions will use by default. To simultaneously run multiple sessions with
control networks, the session option should be used instead of the *core.conf*
default.
> **NOTE:** If you have a large scenario with more than 253 nodes, use a control
> network prefix that allows more than the suggested */24*, such as */23* or
> greater.
!!! note
> **NOTE:** Running a session with a control network can fail if a previous
> session has set up a control network and the its bridge is still up. Close
> the previous session first or wait for it to complete. If unable to, the
*core-daemon* may need to be restarted and the lingering bridge(s) removed
> manually.
If you have a large scenario with more than 253 nodes, use a control
network prefix that allows more than the suggested */24*, such as */23* or
greater.
!!! note
Running a session with a control network can fail if a previous
session has set up a control network and the its bridge is still up. Close
the previous session first or wait for it to complete. If unable to, the
**core-daemon** may need to be restarted and the lingering bridge(s) removed
manually.
```shell
# Restart the CORE Daemon
@ -49,11 +53,13 @@ for cb in $ctrlbridges; do
done
```
> **NOTE:** If adjustments to the primary control network configuration made in
*/etc/core/core.conf* do not seem to take affect, check if there is anything
> set in the *Session Menu*, the *Options...* dialog. They may need to be
> cleared. These per session settings override the defaults in
*/etc/core/core.conf*.
!!! note
If adjustments to the primary control network configuration made in
**/etc/core/core.conf** do not seem to take affect, check if there is anything
set in the *Session Menu*, the *Options...* dialog. They may need to be
cleared. These per session settings override the defaults in
**/etc/core/core.conf**.
## Control Network in Distributed Sessions
@ -117,8 +123,10 @@ assign *ctrl1* to the OTA manager device and *ctrl2* to the Event Service
device in the EMANE Options dialog box and leave *ctrl0* for CORE control
traffic.
> **NOTE:** *controlnet0* may be used in place of *controlnet* to configure
> the primary control network.
!!! note
*controlnet0* may be used in place of *controlnet* to configure
the primary control network.
Unlike the primary control network, the auxiliary control networks will not
employ tunneling since their primary purpose is for efficiently transporting
@ -136,9 +144,11 @@ controlnetif2 = eth2
controlnetif3 = eth3
```
> **NOTE:** There is no need to assign an interface to the primary control
> network because tunnels are formed between the master and the slaves using IP
> addresses that are provided in *servers.conf*.
!!! note
There is no need to assign an interface to the primary control
network because tunnels are formed between the master and the slaves using IP
addresses that are provided in *servers.conf*.
Shown below is a representative diagram of the configuration above.

18
docs/distributed.md
View file

@ -170,8 +170,10 @@ only if an EMANE model is used for the WLAN. The basic range model does
not work across multiple servers due to the Linux bridging and nftables
rules that are used.
**NOTE: The basic range wireless model does not support distributed emulation,
but EMANE does.**
!!! note
The basic range wireless model does not support distributed emulation,
but EMANE does.
When nodes are linked across servers **core-daemons** will automatically
create necessary tunnels between the nodes when executed. Care should be taken
@ -182,10 +184,10 @@ These tunnels are created using GRE tunneling, similar to the Tunnel Tool.
## Distributed Checklist
1. Install CORE on master server
1. Install distributed CORE package on all servers needed
1. Installed and configure public-key SSH access on all servers (if you want to use
2. Install distributed CORE package on all servers needed
3. Installed and configure public-key SSH access on all servers (if you want to use
double-click shells or Widgets.) for both the GUI user (for terminals) and root for running CORE commands
1. Update CORE configuration as needed
1. Choose the servers that participate in distributed emulation.
1. Assign nodes to desired servers, empty for master server.
1. Press the **Start** button to launch the distributed emulation.
4. Update CORE configuration as needed
5. Choose the servers that participate in distributed emulation.
6. Assign nodes to desired servers, empty for master server.
7. Press the **Start** button to launch the distributed emulation.

14
docs/emane.md
View file

@ -57,7 +57,9 @@ You can find more detailed tutorials and examples at the
Every topic below assumes CORE, EMANE, and OSPF MDR have been installed.
> **WARNING:** demo files will be found within the new `core-gui`
!!! info
Demo files will be found within the `core-gui` **~/.coregui/xmls** directory
| Topic | Model | Description |
|--------------------------------------|---------|-----------------------------------------------------------|
@ -89,8 +91,10 @@ If you have an EMANE event generator (e.g. mobility or pathloss scripts) and
want to have CORE subscribe to EMANE location events, set the following line
in the **core.conf** configuration file.
> **NOTE:** Do not set this option to True if you want to manually drag nodes around
> on the canvas to update their location in EMANE.
!!! note
Do not set this option to True if you want to manually drag nodes around
on the canvas to update their location in EMANE.
```shell
emane_event_monitor = True
@ -278,7 +282,9 @@ being used, along with changing any configuration setting from their defaults.
![](static/emane-configuration.png)
> **NOTE:** Here is a quick checklist for distributed emulation with EMANE.
!!! note
Here is a quick checklist for distributed emulation with EMANE.
1. Follow the steps outlined for normal CORE.
2. Assign nodes to desired servers

631
docs/emane/antenna.md
View file

@ -1,8 +1,7 @@
# EMANE Antenna Profiles
* Table of Contents
{:toc}
## Overview
Introduction to using the EMANE antenna profile in CORE, based on the example
EMANE Demo linked below.
@ -10,340 +9,348 @@ EMANE Demo linked below.
for more specifics.
## Demo Setup
We will need to create some files in advance of starting this session.
Create directory to place antenna profile files.
```shell
mkdir /tmp/emane
```
Create `/tmp/emane/antennaprofile.xml` with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE profiles SYSTEM "file:///usr/share/emane/dtd/antennaprofile.dtd">
<profiles>
<profile id="1"
antennapatternuri="/tmp/emane/antenna30dsector.xml"
blockagepatternuri="/tmp/emane/blockageaft.xml">
<placement north="0" east="0" up="0"/>
</profile>
<profile id="2"
antennapatternuri="/tmp/emane/antenna30dsector.xml">
<placement north="0" east="0" up="0"/>
</profile>
<profile id="1"
antennapatternuri="/tmp/emane/antenna30dsector.xml"
blockagepatternuri="/tmp/emane/blockageaft.xml">
<placement north="0" east="0" up="0"/>
</profile>
<profile id="2"
antennapatternuri="/tmp/emane/antenna30dsector.xml">
<placement north="0" east="0" up="0"/>
</profile>
</profiles>
```
Create `/tmp/emane/antenna30dsector.xml` with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE antennaprofile SYSTEM "file:///usr/share/emane/dtd/antennaprofile.dtd">
<!-- 30degree sector antenna pattern with main beam at +6dB and gain decreasing by 3dB every 5 degrees in elevation or bearing.-->
<antennaprofile>
<antennapattern>
<elevation min='-90' max='-16'>
<bearing min='0' max='359'>
<gain value='-200'/>
</bearing>
</elevation>
<elevation min='-15' max='-11'>
<bearing min='0' max='5'>
<gain value='0'/>
</bearing>
<bearing min='6' max='10'>
<gain value='-3'/>
</bearing>
<bearing min='11' max='15'>
<gain value='-6'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='-6'/>
</bearing>
<bearing min='350' max='354'>
<gain value='-3'/>
</bearing>
<bearing min='355' max='359'>
<gain value='0'/>
</bearing>
</elevation>
<elevation min='-10' max='-6'>
<bearing min='0' max='5'>
<gain value='3'/>
</bearing>
<bearing min='6' max='10'>
<gain value='0'/>
</bearing>
<bearing min='11' max='15'>
<gain value='-3'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='-3'/>
</bearing>
<bearing min='350' max='354'>
<gain value='0'/>
</bearing>
<bearing min='355' max='359'>
<gain value='3'/>
</bearing>
</elevation>
<elevation min='-5' max='-1'>
<bearing min='0' max='5'>
<gain value='6'/>
</bearing>
<bearing min='6' max='10'>
<gain value='3'/>
</bearing>
<bearing min='11' max='15'>
<gain value='0'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='0'/>
</bearing>
<bearing min='350' max='354'>
<gain value='3'/>
</bearing>
<bearing min='355' max='359'>
<gain value='6'/>
</bearing>
</elevation>
<elevation min='0' max='5'>
<bearing min='0' max='5'>
<gain value='6'/>
</bearing>
<bearing min='6' max='10'>
<gain value='3'/>
</bearing>
<bearing min='11' max='15'>
<gain value='0'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='0'/>
</bearing>
<bearing min='350' max='354'>
<gain value='3'/>
</bearing>
<bearing min='355' max='359'>
<gain value='6'/>
</bearing>
</elevation>
<elevation min='6' max='10'>
<bearing min='0' max='5'>
<gain value='3'/>
</bearing>
<bearing min='6' max='10'>
<gain value='0'/>
</bearing>
<bearing min='11' max='15'>
<gain value='-3'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='-3'/>
</bearing>
<bearing min='350' max='354'>
<gain value='0'/>
</bearing>
<bearing min='355' max='359'>
<gain value='3'/>
</bearing>
</elevation>
<elevation min='11' max='15'>
<bearing min='0' max='5'>
<gain value='0'/>
</bearing>
<bearing min='6' max='10'>
<gain value='-3'/>
</bearing>
<bearing min='11' max='15'>
<gain value='-6'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='-6'/>
</bearing>
<bearing min='350' max='354'>
<gain value='-3'/>
</bearing>
<bearing min='355' max='359'>
<gain value='0'/>
</bearing>
</elevation>
<elevation min='16' max='90'>
<bearing min='0' max='359'>
<gain value='-200'/>
</bearing>
</elevation>
</antennapattern>
<antennapattern>
<elevation min='-90' max='-16'>
<bearing min='0' max='359'>
<gain value='-200'/>
</bearing>
</elevation>
<elevation min='-15' max='-11'>
<bearing min='0' max='5'>
<gain value='0'/>
</bearing>
<bearing min='6' max='10'>
<gain value='-3'/>
</bearing>
<bearing min='11' max='15'>
<gain value='-6'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='-6'/>
</bearing>
<bearing min='350' max='354'>
<gain value='-3'/>
</bearing>
<bearing min='355' max='359'>
<gain value='0'/>
</bearing>
</elevation>
<elevation min='-10' max='-6'>
<bearing min='0' max='5'>
<gain value='3'/>
</bearing>
<bearing min='6' max='10'>
<gain value='0'/>
</bearing>
<bearing min='11' max='15'>
<gain value='-3'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='-3'/>
</bearing>
<bearing min='350' max='354'>
<gain value='0'/>
</bearing>
<bearing min='355' max='359'>
<gain value='3'/>
</bearing>
</elevation>
<elevation min='-5' max='-1'>
<bearing min='0' max='5'>
<gain value='6'/>
</bearing>
<bearing min='6' max='10'>
<gain value='3'/>
</bearing>
<bearing min='11' max='15'>
<gain value='0'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='0'/>
</bearing>
<bearing min='350' max='354'>
<gain value='3'/>
</bearing>
<bearing min='355' max='359'>
<gain value='6'/>
</bearing>
</elevation>
<elevation min='0' max='5'>
<bearing min='0' max='5'>
<gain value='6'/>
</bearing>
<bearing min='6' max='10'>
<gain value='3'/>
</bearing>
<bearing min='11' max='15'>
<gain value='0'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='0'/>
</bearing>
<bearing min='350' max='354'>
<gain value='3'/>
</bearing>
<bearing min='355' max='359'>
<gain value='6'/>
</bearing>
</elevation>
<elevation min='6' max='10'>
<bearing min='0' max='5'>
<gain value='3'/>
</bearing>
<bearing min='6' max='10'>
<gain value='0'/>
</bearing>
<bearing min='11' max='15'>
<gain value='-3'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='-3'/>
</bearing>
<bearing min='350' max='354'>
<gain value='0'/>
</bearing>
<bearing min='355' max='359'>
<gain value='3'/>
</bearing>
</elevation>
<elevation min='11' max='15'>
<bearing min='0' max='5'>
<gain value='0'/>
</bearing>
<bearing min='6' max='10'>
<gain value='-3'/>
</bearing>
<bearing min='11' max='15'>
<gain value='-6'/>
</bearing>
<bearing min='16' max='344'>
<gain value='-200'/>
</bearing>
<bearing min='345' max='349'>
<gain value='-6'/>
</bearing>
<bearing min='350' max='354'>
<gain value='-3'/>
</bearing>
<bearing min='355' max='359'>
<gain value='0'/>
</bearing>
</elevation>
<elevation min='16' max='90'>
<bearing min='0' max='359'>
<gain value='-200'/>
</bearing>
</elevation>
</antennapattern>
</antennaprofile>
```
Create `/tmp/emane/blockageaft.xml` with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE antennaprofile SYSTEM "file:///usr/share/emane/dtd/antennaprofile.dtd">
<!-- blockage pattern: 1) entire aft in bearing (90 to 270) blocked 2) elevation below -10 blocked, 3) elevation from -10 to -1 is at -10dB to -1 dB 3) elevation from 0 to 90 no blockage-->
<antennaprofile>
<blockagepattern>
<elevation min='-90' max='-11'>
<bearing min='0' max='359'>
<gain value='-200'/>
</bearing>
</elevation>
<elevation min='-10' max='-10'>
<bearing min='0' max='89'>
<gain value='-10'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-10'/>
</bearing>
</elevation>
<elevation min='-9' max='-9'>
<bearing min='0' max='89'>
<gain value='-9'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-9'/>
</bearing>
</elevation>
<elevation min='-8' max='-8'>
<bearing min='0' max='89'>
<gain value='-8'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-8'/>
</bearing>
</elevation>
<elevation min='-7' max='-7'>
<bearing min='0' max='89'>
<gain value='-7'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-7'/>
</bearing>
</elevation>
<elevation min='-6' max='-6'>
<bearing min='0' max='89'>
<gain value='-6'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-6'/>
</bearing>
</elevation>
<elevation min='-5' max='-5'>
<bearing min='0' max='89'>
<gain value='-5'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-5'/>
</bearing>
</elevation>
<elevation min='-4' max='-4'>
<bearing min='0' max='89'>
<gain value='-4'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-4'/>
</bearing>
</elevation>
<elevation min='-3' max='-3'>
<bearing min='0' max='89'>
<gain value='-3'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-3'/>
</bearing>
</elevation>
<elevation min='-2' max='-2'>
<bearing min='0' max='89'>
<gain value='-2'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-2'/>
</bearing>
</elevation>
<elevation min='-1' max='-1'>
<bearing min='0' max='89'>
<gain value='-1'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-1'/>
</bearing>
</elevation>
<elevation min='0' max='90'>
<bearing min='0' max='89'>
<gain value='0'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='0'/>
</bearing>
</elevation>
</blockagepattern>
<blockagepattern>
<elevation min='-90' max='-11'>
<bearing min='0' max='359'>
<gain value='-200'/>
</bearing>
</elevation>
<elevation min='-10' max='-10'>
<bearing min='0' max='89'>
<gain value='-10'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-10'/>
</bearing>
</elevation>
<elevation min='-9' max='-9'>
<bearing min='0' max='89'>
<gain value='-9'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-9'/>
</bearing>
</elevation>
<elevation min='-8' max='-8'>
<bearing min='0' max='89'>
<gain value='-8'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-8'/>
</bearing>
</elevation>
<elevation min='-7' max='-7'>
<bearing min='0' max='89'>
<gain value='-7'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-7'/>
</bearing>
</elevation>
<elevation min='-6' max='-6'>
<bearing min='0' max='89'>
<gain value='-6'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-6'/>
</bearing>
</elevation>
<elevation min='-5' max='-5'>
<bearing min='0' max='89'>
<gain value='-5'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-5'/>
</bearing>
</elevation>
<elevation min='-4' max='-4'>
<bearing min='0' max='89'>
<gain value='-4'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-4'/>
</bearing>
</elevation>
<elevation min='-3' max='-3'>
<bearing min='0' max='89'>
<gain value='-3'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-3'/>
</bearing>
</elevation>
<elevation min='-2' max='-2'>
<bearing min='0' max='89'>
<gain value='-2'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-2'/>
</bearing>
</elevation>
<elevation min='-1' max='-1'>
<bearing min='0' max='89'>
<gain value='-1'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='-1'/>
</bearing>
</elevation>
<elevation min='0' max='90'>
<bearing min='0' max='89'>
<gain value='0'/>
</bearing>
<bearing min='90' max='270'>
<gain value='-200'/>
</bearing>
<bearing min='271' max='359'>
<gain value='0'/>
</bearing>
</elevation>
</blockagepattern>
</antennaprofile>
```
## Run Demo
1. Select `Open...` within the GUI
1. Load `emane-demo-antenna.xml`
1. Click ![Start Button](../static/gui/start.png)
1. After startup completes, double click n1 to bring up the nodes terminal
## Example Demo
This demo will cover running an EMANE event service to feed in antenna,
location, and pathloss events to demonstrate how antenna profiles
can be used.
### EMANE Event Dump
On n1 lets dump EMANE events, so when we later run the EMANE event service
you can monitor when and what is sent.
@ -352,38 +359,44 @@ root@n1:/tmp/pycore.44917/n1.conf# emaneevent-dump -i ctrl0
```
### Send EMANE Events
On the host machine create the following to send EMANE events.
> **WARNING:** make sure to set the `eventservicedevice` to the proper control
> network value
!!! warning
Make sure to set the `eventservicedevice` to the proper control
network value
Create `eventservice.xml` with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventservice SYSTEM "file:///usr/share/emane/dtd/eventservice.dtd">
<eventservice>
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="b.9001.da"/>
<generator definition="eelgenerator.xml"/>
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="b.9001.da"/>
<generator definition="eelgenerator.xml"/>
</eventservice>
```
Create `eelgenerator.xml` with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventgenerator SYSTEM "file:///usr/share/emane/dtd/eventgenerator.dtd">
<eventgenerator library="eelgenerator">
<param name="inputfile" value="scenario.eel" />
<param name="inputfile" value="scenario.eel"/>
<paramlist name="loader">
<item value="commeffect:eelloadercommeffect:delta"/>
<item value="location,velocity,orientation:eelloaderlocation:delta"/>
<item value="pathloss:eelloaderpathloss:delta"/>
<item value="antennaprofile:eelloaderantennaprofile:delta"/>
<item value="commeffect:eelloadercommeffect:delta"/>
<item value="location,velocity,orientation:eelloaderlocation:delta"/>
<item value="pathloss:eelloaderpathloss:delta"/>
<item value="antennaprofile:eelloaderantennaprofile:delta"/>
</paramlist>
</eventgenerator>
```
Create `scenario.eel` with the following contents.
```shell
0.0 nem:1 antennaprofile 1,0.0,0.0
0.0 nem:4 antennaprofile 2,0.0,0.0
@ -413,23 +426,25 @@ Create `scenario.eel` with the following contents.
Run the EMANE event service, monitor what is output on n1 for events
dumped and see the link changes within the CORE GUI.
```shell
emaneeventservice -l 3 eventservice.xml
```
### Stages
The events sent will trigger 4 different states.
* State 1
* n2 and n3 see each other
* n4 and n3 are pointing away
* n2 and n3 see each other
* n4 and n3 are pointing away
* State 2
* n2 and n3 see each other
* n1 and n2 see each other
* n4 and n3 see each other
* n2 and n3 see each other
* n1 and n2 see each other
* n4 and n3 see each other
* State 3
* n2 and n3 see each other
* n4 and n3 are pointing at each other but blocked
* n2 and n3 see each other
* n4 and n3 are pointing at each other but blocked
* State 4
* n2 and n3 see each other
* n4 and n3 see each other
* n2 and n3 see each other
* n4 and n3 see each other

41
docs/emane/eel.md
View file

@ -1,44 +1,51 @@
# EMANE Emulation Event Log (EEL) Generator
* Table of Contents
{:toc}
## Overview
Introduction to using the EMANE event service and eel files to provide events.
[EMANE Demo 1](https://github.com/adjacentlink/emane-tutorial/wiki/Demonstration-1)
for more specifics.
## Run Demo
1. Select `Open...` within the GUI
1. Load `emane-demo-eel.xml`
1. Click ![Start Button](../static/gui/start.png)
1. After startup completes, double click n1 to bring up the nodes terminal
2. Load `emane-demo-eel.xml`
3. Click ![Start Button](../static/gui/start.png)
4. After startup completes, double click n1 to bring up the nodes terminal
## Example Demo
This demo will go over defining an EMANE event service and eel file to drive
an emane event service.
### Viewing Events
On n1 we will use the EMANE event dump utility to listen to events.
```shell
root@n1:/tmp/pycore.46777/n1.conf# emaneevent-dump -i ctrl0
```
### Sending Events
On the host machine we will create the following files and start the
EMANE event service targeting the control network.
> **WARNING:** make sure to set the `eventservicedevice` to the proper control
> network value
!!! warning
Make sure to set the `eventservicedevice` to the proper control
network value
Create `eventservice.xml` with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventservice SYSTEM "file:///usr/share/emane/dtd/eventservice.dtd">
<eventservice>
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="b.9001.f"/>
<generator definition="eelgenerator.xml"/>
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="b.9001.f"/>
<generator definition="eelgenerator.xml"/>
</eventservice>
```
@ -57,21 +64,23 @@ These configuration items tell the EEL Generator which sentences to map to
which plugin and whether to issue delta or full updates.
Create `eelgenerator.xml` with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventgenerator SYSTEM "file:///usr/share/emane/dtd/eventgenerator.dtd">
<eventgenerator library="eelgenerator">
<param name="inputfile" value="scenario.eel" />
<param name="inputfile" value="scenario.eel"/>
<paramlist name="loader">
<item value="commeffect:eelloadercommeffect:delta"/>
<item value="location,velocity,orientation:eelloaderlocation:delta"/>
<item value="pathloss:eelloaderpathloss:delta"/>
<item value="antennaprofile:eelloaderantennaprofile:delta"/>
<item value="commeffect:eelloadercommeffect:delta"/>
<item value="location,velocity,orientation:eelloaderlocation:delta"/>
<item value="pathloss:eelloaderpathloss:delta"/>
<item value="antennaprofile:eelloaderantennaprofile:delta"/>
</paramlist>
</eventgenerator>
```
Finally, create `scenario.eel` with the following contents.
```shell
0.0 nem:1 pathloss nem:2,90.0
0.0 nem:2 pathloss nem:1,90.0
@ -80,11 +89,13 @@ Finally, create `scenario.eel` with the following contents.
```
Start the EMANE event service using the files created above.
```shell
emaneeventservice eventservice.xml -l 3
```
### Sent Events
If we go back to look at our original terminal we will see the events logged
out to the terminal.

17
docs/emane/files.md
View file

@ -1,8 +1,7 @@
# EMANE XML Files
* Table of Contents
{:toc}
## Overview
Introduction to the XML files generated by CORE used to drive EMANE for
a given node.
@ -10,12 +9,14 @@ a given node.
may provide more helpful details.
## Run Demo
1. Select `Open...` within the GUI
1. Load `emane-demo-files.xml`
1. Click ![Start Button](../static/gui/start.png)
1. After startup completes, double click n1 to bring up the nodes terminal
2. Load `emane-demo-files.xml`
3. Click ![Start Button](../static/gui/start.png)
4. After startup completes, double click n1 to bring up the nodes terminal
## Example Demo
We will take a look at the files generated in the example demo provided. In this
case we are running the RF Pipe model.
@ -31,6 +32,7 @@ case we are running the RF Pipe model.
| \<interface name>-trans.xml | configuration when a raw transport is being used |
### Listing File
Below are the files within n1 after starting the demo session.
```shell
@ -41,6 +43,7 @@ eth0-phy.xml n1-emane.log usr.local.etc.quagga var.run.quagga
```
### Platform XML
The root configuration file used to run EMANE for a node is the platform xml file.
In this demo we are looking at `n1-platform.xml`.
@ -78,6 +81,7 @@ root@n1:/tmp/pycore.46777/n1.conf# cat n1-platform.xml
```
### NEM XML
The nem definition will contain reference to the transport, mac, and phy xml
definitions being used for a given nem.
@ -93,6 +97,7 @@ root@n1:/tmp/pycore.46777/n1.conf# cat eth0-nem.xml
```
### MAC XML
MAC layer configuration settings would be found in this file. CORE will write
out all values, even if the value is a default value.
@ -115,6 +120,7 @@ root@n1:/tmp/pycore.46777/n1.conf# cat eth0-mac.xml
```
### PHY XML
PHY layer configuration settings would be found in this file. CORE will write
out all values, even if the value is a default value.
@ -149,6 +155,7 @@ root@n1:/tmp/pycore.46777/n1.conf# cat eth0-phy.xml
```
### Transport XML
```shell
root@n1:/tmp/pycore.46777/n1.conf# cat eth0-trans-virtual.xml
<?xml version='1.0' encoding='UTF-8'?>

56
docs/emane/gpsd.md
View file

@ -1,54 +1,62 @@
# EMANE GPSD Integration
* Table of Contents
{:toc}
## Overview
Introduction to integrating gpsd in CORE with EMANE.
[EMANE Demo 0](https://github.com/adjacentlink/emane-tutorial/wiki/Demonstration-0)
may provide more helpful details.
> **WARNING:** requires installation of [gpsd](https://gpsd.gitlab.io/gpsd/index.html)
!!!! warning
Requires installation of [gpsd](https://gpsd.gitlab.io/gpsd/index.html)
## Run Demo
1. Select `Open...` within the GUI
1. Load `emane-demo-gpsd.xml`
1. Click ![Start Button](../static/gui/start.png)
1. After startup completes, double click n1 to bring up the nodes terminal
2. Load `emane-demo-gpsd.xml`
3. Click ![Start Button](../static/gui/start.png)
4. After startup completes, double click n1 to bring up the nodes terminal
## Example Demo
This section will cover how to run a gpsd location agent within EMANE, that will
write out locations to a pseudo terminal file. That file can be read in by the
gpsd server and make EMANE location events available to gpsd clients.
### EMANE GPSD Event Daemon
First create an `eventdaemon.xml` file on n1 with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventdaemon SYSTEM "file:///usr/share/emane/dtd/eventdaemon.dtd">
<eventdaemon nemid="1">
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="ctrl0"/>
<agent definition="gpsdlocationagent.xml"/>
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="ctrl0"/>
<agent definition="gpsdlocationagent.xml"/>
</eventdaemon>
```
Then create the `gpsdlocationagent.xml` file on n1 with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventagent SYSTEM "file:///usr/share/emane/dtd/eventagent.dtd">
<eventagent library="gpsdlocationagent">
<param name="pseudoterminalfile" value="gps.pty"/>
<param name="pseudoterminalfile" value="gps.pty"/>
</eventagent>
```
Start the EMANE event agent. This will facilitate feeding location events
out to a pseudo terminal file defined above.
```shell
emaneeventd eventdaemon.xml -r -d -l 3 -f emaneeventd.log
```
Start gpsd, reading in the pseudo terminal file.
```shell
gpsd -G -n -b $(cat gps.pty)
```
@ -59,36 +67,41 @@ EEL Events will be played out from the actual host machine over the designated
control network interface. Create the following files in the same directory
somewhere on your host.
> **NOTE:** make sure the below eventservicedevice matches the control network
> device being used on the host for EMANE
!!! note
Make sure the below eventservicedevice matches the control network
device being used on the host for EMANE
Create `eventservice.xml` on the host machine with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventservice SYSTEM "file:///usr/share/emane/dtd/eventservice.dtd">
<eventservice>
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="b.9001.1"/>
<generator definition="eelgenerator.xml"/>
<param name="eventservicegroup" value="224.1.2.8:45703"/>
<param name="eventservicedevice" value="b.9001.1"/>
<generator definition="eelgenerator.xml"/>
</eventservice>
```
Create `eelgenerator.xml` on the host machine with the following contents.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE eventgenerator SYSTEM "file:///usr/share/emane/dtd/eventgenerator.dtd">
<eventgenerator library="eelgenerator">
<param name="inputfile" value="scenario.eel" />
<param name="inputfile" value="scenario.eel"/>
<paramlist name="loader">
<item value="commeffect:eelloadercommeffect:delta"/>
<item value="location,velocity,orientation:eelloaderlocation:delta"/>
<item value="pathloss:eelloaderpathloss:delta"/>
<item value="antennaprofile:eelloaderantennaprofile:delta"/>
<item value="commeffect:eelloadercommeffect:delta"/>
<item value="location,velocity,orientation:eelloaderlocation:delta"/>
<item value="pathloss:eelloaderpathloss:delta"/>
<item value="antennaprofile:eelloaderantennaprofile:delta"/>
</paramlist>
</eventgenerator>
```
Create `scenario.eel` file with the following contents.
```shell
0.0 nem:1 location gps 40.031075,-74.523518,3.000000
0.0 nem:2 location gps 40.031165,-74.523412,3.000000
@ -96,7 +109,8 @@ Create `scenario.eel` file with the following contents.
Start the EEL event service, which will send the events defined in the file above
over the control network to all EMANE nodes. These location events will be received
and provided to gpsd. This allow gpsd client to connect to and get gps locations.
and provided to gpsd. This allows gpsd client to connect to and get gps locations.
```shell
emaneeventservice eventservice.xml -l 3
```

27
docs/emane/precomputed.md
View file

@ -1,35 +1,40 @@
# EMANE Procomputed
* Table of Contents
{:toc}
## Overview
Introduction to using the precomputed propagation model.
[EMANE Demo 1](https://github.com/adjacentlink/emane-tutorial/wiki/Demonstration-1)
for more specifics.
## Run Demo
1. Select `Open...` within the GUI
1. Load `emane-demo-precomputed.xml`
1. Click ![Start Button](../static/gui/start.png)
1. After startup completes, double click n1 to bring up the nodes terminal
2. Load `emane-demo-precomputed.xml`
3. Click ![Start Button](../static/gui/start.png)
4. After startup completes, double click n1 to bring up the nodes terminal
## Example Demo
This demo is uing the RF Pipe model witht he propagation model set to
This demo is using the RF Pipe model with the propagation model set to
precomputed.
### Failed Pings
Due to using precomputed and having not sent any pathloss events, the nodes
cannot ping eachother yet.
cannot ping each other yet.
Open a terminal on n1.
```shell
root@n1:/tmp/pycore.46777/n1.conf# ping 10.0.0.2
connect: Network is unreachable
```
### EMANE Shell
You can leverage `emanesh` to investigate why packets are being dropped.
```shell
root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy BroadcastPacketDropTable0 UnicastPacketDropTable0
nem 1 phy BroadcastPacketDropTable0
@ -43,6 +48,7 @@ nem 1 phy UnicastPacketDropTable0
In the example above we can see that the reason packets are being dropped is due to
the propogation model and that is because we have not issued any pathloss events.
You can run another command to validate if you have received any pathloss events.
```shell
root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable
nem 1 phy PathlossEventInfoTable
@ -50,15 +56,19 @@ nem 1 phy PathlossEventInfoTable
```
### Pathloss Events
On the host we will send pathloss events from all nems to all other nems.
> **NOTE:** make sure properly specify the right control network device
!!! note
Make sure properly specify the right control network device
```shell
emaneevent-pathloss 1:2 90 -i <controlnet device>
```
Now if we check for pathloss events on n2 we will see what was just sent above.
```shell
root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable
nem 1 phy PathlossEventInfoTable
@ -67,6 +77,7 @@ nem 1 phy PathlossEventInfoTable
```
You should also now be able to ping n1 from n2.
```shell
root@n1:/tmp/pycore.46777/n1.conf# ping -c 3 10.0.0.2
PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.

20
docs/hitl.md
View file

@ -34,9 +34,11 @@ and the other node you wish to be connected to. The RJ45 node will display "UNAS
Double-click the RJ45 node to assign a physical interface. A list of available
interfaces will be shown, and one may be selected, then selecting **Apply**.
> **NOTE:** When you press the Start button to instantiate your topology, the
> interface assigned to the RJ45 will be connected to the CORE topology. The
> interface can no longer be used by the system.
!!! note
When you press the Start button to instantiate your topology, the
interface assigned to the RJ45 will be connected to the CORE topology. The
interface can no longer be used by the system.
### Multiple RJ45s with One Interface (VLAN)
@ -71,11 +73,13 @@ the node will display "UNASSIGNED". This text should be replaced with the IP
address of the tunnel peer. This is the IP address of the other CORE machine or
physical machine, not an IP address of another virtual node.
> **NOTE:** Be aware of possible MTU (Maximum Transmission Unit) issues with GRE devices. The *gretap* device
> has an interface MTU of 1,458 bytes; when joined to a Linux bridge, the
> bridge's MTU
> becomes 1,458 bytes. The Linux bridge will not perform fragmentation for
> large packets if other bridge ports have a higher MTU such as 1,500 bytes.
!!! note
Be aware of possible MTU (Maximum Transmission Unit) issues with GRE devices.
The *gretap* device has an interface MTU of 1,458 bytes; when joined to a Linux
bridge, the bridge's MTU becomes 1,458 bytes. The Linux bridge will not perform
fragmentation for large packets if other bridge ports have a higher MTU such
as 1,500 bytes.
The GRE key is used to identify flows with GRE tunneling. This allows multiple
GRE tunnels to exist between that same pair of tunnel peers. A unique number

28
docs/install.md
View file

@ -1,10 +1,12 @@
# Installation
> **WARNING:** if Docker is installed, the default iptable rules will block CORE traffic
!!! warning
If Docker is installed, the default iptable rules will block CORE traffic
## Overview
CORE currently supports and provides the following install options, with the package
CORE currently supports and provides the following installation options, with the package
option being preferred.
* [Package based install (rpm/deb)](#package-based-install)
@ -111,8 +113,10 @@ The built packages will require and install system level dependencies, as well a
a post install script to install the provided CORE python wheel. A similar uninstall script
is ran when uninstalling and would require the same options as given, during the install.
> **NOTE:** PYTHON defaults to python3 for installs below, CORE requires python3.9+, pip,
> tk compatibility for python gui, and venv for virtual environments
!!! note
PYTHON defaults to python3 for installs below, CORE requires python3.9+, pip,
tk compatibility for python gui, and venv for virtual environments
Examples for install:
@ -185,11 +189,15 @@ Installaion will carry out the following steps:
* installs systemd service pointing to appropriate python location based on install type
* clone/build/install working version of [OPSF MDR](https://github.com/USNavalResearchLaboratory/ospf-mdr)
> **NOTE:** installing locally comes with its own risks, it can result it potential
> dependency conflicts with system package manager installed python dependencies
!!! note
> **NOTE:** provide a prefix that will be found on path when running as sudo,
> if the default prefix /usr/local will not be valid
Installing locally comes with its own risks, it can result it potential
dependency conflicts with system package manager installed python dependencies
!!! note
Provide a prefix that will be found on path when running as sudo,
if the default prefix /usr/local will not be valid
The following tools will be leveraged during installation:
@ -282,7 +290,9 @@ When done see [Post Install](#post-install).
## Installing EMANE
> **NOTE:** installing EMANE for the virtual environment is known to work for 1.21+
!!! note
Installing EMANE for the virtual environment is known to work for 1.21+
The recommended way to install EMANE is using prebuilt packages, otherwise
you can follow their instructions for installing from source. Installation

6
docs/performance.md
View file

@ -28,8 +28,10 @@ the number of times the system as a whole needed to deal with a packet. As
more network hops are added, this increases the number of context switches
and decreases the throughput seen on the full length of the network path.
> **NOTE:** The right question to be asking is *"how much traffic?"*, not
*"how many nodes?"*.
!!! note
The right question to be asking is *"how much traffic?"*, not
*"how many nodes?"*.
For a more detailed study of performance in CORE, refer to the following
publications:

47
docs/services.md
View file

@ -12,9 +12,11 @@ set of default services. Each service defines the per-node directories,
configuration files, startup index, starting commands, validation commands,
shutdown commands, and meta-data associated with a node.
> **NOTE:** **Network namespace nodes do not undergo the normal Linux boot process**
> using the **init**, **upstart**, or **systemd** frameworks. These
> lightweight nodes use configured CORE *services*.
!!! note
**Network namespace nodes do not undergo the normal Linux boot process**
using the **init**, **upstart**, or **systemd** frameworks. These
lightweight nodes use configured CORE *services*.
## Available Services
@ -68,11 +70,13 @@ the service customization dialog for that service.
The dialog has three tabs for configuring the different aspects of the service:
files, directories, and startup/shutdown.
> **NOTE:** A **yellow** customize icon next to a service indicates that service
> requires customization (e.g. the *Firewall* service).
> A **green** customize icon indicates that a custom configuration exists.
> Click the *Defaults* button when customizing a service to remove any
> customizations.
!!! note
A **yellow** customize icon next to a service indicates that service
requires customization (e.g. the *Firewall* service).
A **green** customize icon indicates that a custom configuration exists.
Click the *Defaults* button when customizing a service to remove any
customizations.
The Files tab is used to display or edit the configuration files or scripts that
are used for this service. Files can be selected from a drop-down list, and
@ -87,10 +91,11 @@ per-node directories that are defined by the services. For example, the
the Zebra service, because Quagga running on each node needs to write separate
PID files to that directory.
> **NOTE:** The **/var/log** and **/var/run** directories are
> mounted uniquely per-node by default.
> Per-node mount targets can be found in **/tmp/pycore.nnnnn/nN.conf/**
(where *nnnnn* is the session number and *N* is the node number.)
!!! note
The **/var/log** and **/var/run** directories are
mounted uniquely per-node by default.
Per-node mount targets can be found in **/tmp/pycore.<session id>/<node name>.conf/**
The Startup/shutdown tab lists commands that are used to start and stop this
service. The startup index allows configuring when this service starts relative
@ -117,8 +122,10 @@ if a process is running and return zero when found. When a validate command
produces a non-zero return value, an exception is generated, which will cause
an error to be displayed in the Check Emulation Light.
> **NOTE:** To start, stop, and restart services during run-time, right-click a
> node and use the *Services...* menu.
!!! note
To start, stop, and restart services during run-time, right-click a
node and use the *Services...* menu.
## New Services
@ -135,6 +142,12 @@ ideas for a service before adding a new service type.
### Creating New Services
!!! note
The directory name used in **custom_services_dir** below should be unique and
should not correspond to any existing Python module name. For example, don't
use the name **subprocess** or **services**.
1. Modify the example service shown below
to do what you want. It could generate config/script files, mount per-node
directories, start processes/scripts, etc. sample.py is a Python file that
@ -148,12 +161,6 @@ ideas for a service before adding a new service type.
3. Add a **custom_services_dir = `/home/<user>/.coregui/custom_services`** entry to the
/etc/core/core.conf file.
**NOTE:**
The directory name used in **custom_services_dir** should be unique and
should not correspond to
any existing Python module name. For example, don't use the name **subprocess**
or **services**.
4. Restart the CORE daemon (core-daemon). Any import errors (Python syntax)
should be displayed in the daemon output.