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 ### 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 1. Modify the example service shown below
to do what you want. It could generate config/script files, mount per-node 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 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. 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 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.
3. Add a **custom_config_services_dir = ~/.coregui/custom_services** entry to the 3. Add a **custom_config_services_dir = ~/.coregui/custom_services** entry to the
/etc/core/core.conf file. /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) 4. Restart the CORE daemon (core-daemon). Any import errors (Python syntax)
should be displayed in the terminal (or service log, like journalctl). 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 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 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 ### 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* control networks, the session option should be used instead of the *core.conf*
default. default.
> **NOTE:** If you have a large scenario with more than 253 nodes, use a control !!! note
> 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 If you have a large scenario with more than 253 nodes, use a control
> session has set up a control network and the its bridge is still up. Close network prefix that allows more than the suggested */24*, such as */23* or
> the previous session first or wait for it to complete. If unable to, the greater.
*core-daemon* may need to be restarted and the lingering bridge(s) removed
> manually. !!! 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 ```shell
# Restart the CORE Daemon # Restart the CORE Daemon
@ -49,11 +53,13 @@ for cb in $ctrlbridges; do
done done
``` ```
> **NOTE:** If adjustments to the primary control network configuration made in !!! note
*/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 If adjustments to the primary control network configuration made in
> cleared. These per session settings override the defaults in **/etc/core/core.conf** do not seem to take affect, check if there is anything
*/etc/core/core.conf*. 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 ## 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 device in the EMANE Options dialog box and leave *ctrl0* for CORE control
traffic. traffic.
> **NOTE:** *controlnet0* may be used in place of *controlnet* to configure !!! note
> the primary control network.
*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 Unlike the primary control network, the auxiliary control networks will not
employ tunneling since their primary purpose is for efficiently transporting employ tunneling since their primary purpose is for efficiently transporting
@ -136,9 +144,11 @@ controlnetif2 = eth2
controlnetif3 = eth3 controlnetif3 = eth3
``` ```
> **NOTE:** There is no need to assign an interface to the primary control !!! note
> network because tunnels are formed between the master and the slaves using IP
> addresses that are provided in *servers.conf*. 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. 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 not work across multiple servers due to the Linux bridging and nftables
rules that are used. rules that are used.
**NOTE: The basic range wireless model does not support distributed emulation, !!! note
but EMANE does.**
The basic range wireless model does not support distributed emulation,
but EMANE does.
When nodes are linked across servers **core-daemons** will automatically When nodes are linked across servers **core-daemons** will automatically
create necessary tunnels between the nodes when executed. Care should be taken 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 ## Distributed Checklist
1. Install CORE on master server 1. Install CORE on master server
1. Install distributed CORE package on all servers needed 2. Install distributed CORE package on all servers needed
1. Installed and configure public-key SSH access on all servers (if you want to use 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 double-click shells or Widgets.) for both the GUI user (for terminals) and root for running CORE commands
1. Update CORE configuration as needed 4. Update CORE configuration as needed
1. Choose the servers that participate in distributed emulation. 5. Choose the servers that participate in distributed emulation.
1. Assign nodes to desired servers, empty for master server. 6. Assign nodes to desired servers, empty for master server.
1. Press the **Start** button to launch the distributed emulation. 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. 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 | | 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 want to have CORE subscribe to EMANE location events, set the following line
in the **core.conf** configuration file. in the **core.conf** configuration file.
> **NOTE:** Do not set this option to True if you want to manually drag nodes around !!! note
> on the canvas to update their location in EMANE.
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 ```shell
emane_event_monitor = True emane_event_monitor = True
@ -278,7 +282,9 @@ being used, along with changing any configuration setting from their defaults.
![](static/emane-configuration.png) ![](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. 1. Follow the steps outlined for normal CORE.
2. Assign nodes to desired servers 2. Assign nodes to desired servers

631
docs/emane/antenna.md
View file

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

17
docs/emane/files.md
View file

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

56
docs/emane/gpsd.md
View file

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

27
docs/emane/precomputed.md
View file

@ -1,35 +1,40 @@
# EMANE Procomputed # EMANE Procomputed
* Table of Contents
{:toc}
## Overview ## Overview
Introduction to using the precomputed propagation model. Introduction to using the precomputed propagation model.
[EMANE Demo 1](https://github.com/adjacentlink/emane-tutorial/wiki/Demonstration-1) [EMANE Demo 1](https://github.com/adjacentlink/emane-tutorial/wiki/Demonstration-1)
for more specifics. for more specifics.
## Run Demo ## Run Demo
1. Select `Open...` within the GUI 1. Select `Open...` within the GUI
1. Load `emane-demo-precomputed.xml` 2. Load `emane-demo-precomputed.xml`
1. Click ![Start Button](../static/gui/start.png) 3. Click ![Start Button](../static/gui/start.png)
1. After startup completes, double click n1 to bring up the nodes terminal 4. After startup completes, double click n1 to bring up the nodes terminal
## Example Demo ## 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. precomputed.
### Failed Pings ### Failed Pings
Due to using precomputed and having not sent any pathloss events, the nodes 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. Open a terminal on n1.
```shell ```shell
root@n1:/tmp/pycore.46777/n1.conf# ping 10.0.0.2 root@n1:/tmp/pycore.46777/n1.conf# ping 10.0.0.2
connect: Network is unreachable connect: Network is unreachable
``` ```
### EMANE Shell ### EMANE Shell
You can leverage `emanesh` to investigate why packets are being dropped. You can leverage `emanesh` to investigate why packets are being dropped.
```shell ```shell
root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy BroadcastPacketDropTable0 UnicastPacketDropTable0 root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy BroadcastPacketDropTable0 UnicastPacketDropTable0
nem 1 phy BroadcastPacketDropTable0 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 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. 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. You can run another command to validate if you have received any pathloss events.
```shell ```shell
root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable
nem 1 phy PathlossEventInfoTable nem 1 phy PathlossEventInfoTable
@ -50,15 +56,19 @@ nem 1 phy PathlossEventInfoTable
``` ```
### Pathloss Events ### Pathloss Events
On the host we will send pathloss events from all nems to all other nems. 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 ```shell
emaneevent-pathloss 1:2 90 -i <controlnet device> 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. Now if we check for pathloss events on n2 we will see what was just sent above.
```shell ```shell
root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable
nem 1 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. You should also now be able to ping n1 from n2.
```shell ```shell
root@n1:/tmp/pycore.46777/n1.conf# ping -c 3 10.0.0.2 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. 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 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**. interfaces will be shown, and one may be selected, then selecting **Apply**.
> **NOTE:** When you press the Start button to instantiate your topology, the !!! note
> interface assigned to the RJ45 will be connected to the CORE topology. The
> interface can no longer be used by the system. 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) ### 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 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. 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 !!! note
> has an interface MTU of 1,458 bytes; when joined to a Linux bridge, the
> bridge's MTU Be aware of possible MTU (Maximum Transmission Unit) issues with GRE devices.
> becomes 1,458 bytes. The Linux bridge will not perform fragmentation for The *gretap* device has an interface MTU of 1,458 bytes; when joined to a Linux
> large packets if other bridge ports have a higher MTU such as 1,500 bytes. 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 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 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 # 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 ## 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. option being preferred.
* [Package based install (rpm/deb)](#package-based-install) * [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 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. 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, !!! note
> tk compatibility for python gui, and venv for virtual environments
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: 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 * 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) * 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 !!! note
> dependency conflicts with system package manager installed python dependencies
> **NOTE:** provide a prefix that will be found on path when running as sudo, Installing locally comes with its own risks, it can result it potential
> if the default prefix /usr/local will not be valid 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: The following tools will be leveraged during installation:
@ -282,7 +290,9 @@ When done see [Post Install](#post-install).
## Installing EMANE ## 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 The recommended way to install EMANE is using prebuilt packages, otherwise
you can follow their instructions for installing from source. Installation 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 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. 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 !!! note
*"how many nodes?"*.
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 For a more detailed study of performance in CORE, refer to the following
publications: 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, configuration files, startup index, starting commands, validation commands,
shutdown commands, and meta-data associated with a node. shutdown commands, and meta-data associated with a node.
> **NOTE:** **Network namespace nodes do not undergo the normal Linux boot process** !!! note
> using the **init**, **upstart**, or **systemd** frameworks. These
> lightweight nodes use configured CORE *services*. **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 ## 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: The dialog has three tabs for configuring the different aspects of the service:
files, directories, and startup/shutdown. files, directories, and startup/shutdown.
> **NOTE:** A **yellow** customize icon next to a service indicates that service !!! note
> requires customization (e.g. the *Firewall* service).
> A **green** customize icon indicates that a custom configuration exists. A **yellow** customize icon next to a service indicates that service
> Click the *Defaults* button when customizing a service to remove any requires customization (e.g. the *Firewall* service).
> customizations. 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 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 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 the Zebra service, because Quagga running on each node needs to write separate
PID files to that directory. PID files to that directory.
> **NOTE:** The **/var/log** and **/var/run** directories are !!! note
> mounted uniquely per-node by default.
> Per-node mount targets can be found in **/tmp/pycore.nnnnn/nN.conf/** The **/var/log** and **/var/run** directories are
(where *nnnnn* is the session number and *N* is the node number.) 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 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 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 produces a non-zero return value, an exception is generated, which will cause
an error to be displayed in the Check Emulation Light. an error to be displayed in the Check Emulation Light.
> **NOTE:** To start, stop, and restart services during run-time, right-click a !!! note
> node and use the *Services...* menu.
To start, stop, and restart services during run-time, right-click a
node and use the *Services...* menu.
## New Services ## New Services
@ -135,6 +142,12 @@ ideas for a service before adding a new service type.
### Creating New Services ### 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 1. Modify the example service shown below
to do what you want. It could generate config/script files, mount per-node 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 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 3. Add a **custom_services_dir = `/home/<user>/.coregui/custom_services`** entry to the
/etc/core/core.conf file. /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) 4. Restart the CORE daemon (core-daemon). Any import errors (Python syntax)
should be displayed in the daemon output. should be displayed in the daemon output.