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

Merge pull request #787 from coreemu/enhancement/documentation

Browse source 
Enhancement/documentation
This commit is contained in:
bharnden 2023-04-18 12:12:57 -07:00 • committed by GitHub
commit 946d161c11
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
35 changed files with 995 additions and 813 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.gitignore vendored
View file

@ -18,6 +18,9 @@ configure~
debian debian
stamp-h1 stamp-h1
# python virtual environments
venv
# generated protobuf files # generated protobuf files
*_pb2.py *_pb2.py
*_pb2_grpc.py *_pb2_grpc.py

3
docs/architecture.md
View file

@ -1,8 +1,5 @@
# CORE Architecture # CORE Architecture
* Table of Contents
{:toc}
## Main Components ## Main Components
* core-daemon * core-daemon

25
docs/configservices.md
View file

@ -1,7 +1,4 @@
# CORE Config Services # Config Services
* Table of Contents
{:toc}
## Overview ## Overview
@ -15,6 +12,7 @@ CORE services are a convenience for creating reusable dynamic scripts
to run on nodes, for carrying out specific task(s). to run on nodes, for carrying out specific task(s).
This boilds down to the following functions: This boilds down to the following functions:
* generating files the service will use, either directly for commands or for configuration * generating files the service will use, either directly for commands or for configuration
* command(s) for starting a service * command(s) for starting a service
* command(s) for validating a service * command(s) for validating a service
@ -81,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
@ -121,6 +117,7 @@ from typing import Dict, List
from core.config import ConfigString, ConfigBool, Configuration from core.config import ConfigString, ConfigBool, Configuration
from core.configservice.base import ConfigService, ConfigServiceMode, ShadowDir from core.configservice.base import ConfigService, ConfigServiceMode, ShadowDir
# class that subclasses ConfigService # class that subclasses ConfigService
class ExampleService(ConfigService): class ExampleService(ConfigService):
# unique name for your service within CORE # unique name for your service within CORE

49
docs/ctrlnet.md
View file

@ -1,8 +1,5 @@
# CORE Control Network # CORE Control Network
* Table of Contents
{:toc}
## Overview ## Overview
The CORE control network allows the virtual nodes to communicate with their The CORE control network allows the virtual nodes to communicate with their
@ -30,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
@ -52,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
@ -120,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
@ -139,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.

5
docs/devguide.md
View file

@ -1,9 +1,6 @@
# CORE Developer's Guide # CORE Developer's Guide
* Table of Contents ## Overview
{:toc}
## Repository Overview
The CORE source consists of several programming languages for The CORE source consists of several programming languages for
historical reasons. Current development focuses on the Python modules and historical reasons. Current development focuses on the Python modules and

29
docs/distributed.md
View file

@ -1,8 +1,5 @@
# CORE - Distributed Emulation # CORE - Distributed Emulation
* Table of Contents
{:toc}
## Overview ## Overview
A large emulation scenario can be deployed on multiple emulation servers and A large emulation scenario can be deployed on multiple emulation servers and
@ -61,6 +58,7 @@ First the distributed servers must be configured to allow passwordless root
login over SSH. login over SSH.
On distributed server: On distributed server:
```shelll ```shelll
# install openssh-server # install openssh-server
sudo apt install openssh-server sudo apt install openssh-server
@ -81,6 +79,7 @@ sudo systemctl restart sshd
``` ```
On master server: On master server:
```shell ```shell
# install package if needed # install package if needed
sudo apt install openssh-client sudo apt install openssh-client
@ -99,6 +98,7 @@ connect_kwargs: {"key_filename": "/home/user/.ssh/core"}
``` ```
On distributed server: On distributed server:
```shell ```shell
# open sshd config # open sshd config
vi /etc/ssh/sshd_config vi /etc/ssh/sshd_config
@ -116,8 +116,9 @@ Make sure the value used below is the absolute path to the file
generated above **~/.ssh/core**" generated above **~/.ssh/core**"
Add/update the fabric configuration file **/etc/fabric.yml**: Add/update the fabric configuration file **/etc/fabric.yml**:
```yaml ```yaml
connect_kwargs: {"key_filename": "/home/user/.ssh/core"} connect_kwargs: { "key_filename": "/home/user/.ssh/core" }
``` ```
## Add Emulation Servers in GUI ## Add Emulation Servers in GUI
@ -169,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
@ -181,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.

3
docs/docker.md
View file

@ -15,7 +15,6 @@ sudo apt install docker.io
### RHEL Systems ### RHEL Systems
## Configuration ## Configuration
Custom configuration required to avoid iptable rules being added and removing Custom configuration required to avoid iptable rules being added and removing
@ -53,6 +52,7 @@ Images used by Docker nodes in CORE need to have networking tools installed for
CORE to automate setup and configuration of the network within the container. CORE to automate setup and configuration of the network within the container.
Example Dockerfile: Example Dockerfile:
``` ```
FROM ubuntu:latest FROM ubuntu:latest
RUN apt-get update RUN apt-get update
@ -60,6 +60,7 @@ RUN apt-get install -y iproute2 ethtool
``` ```
Build image: Build image:
```shell ```shell
sudo docker build -t <name> . sudo docker build -t <name> .
``` ```

30
docs/emane.md
View file

@ -1,7 +1,4 @@
# CORE/EMANE # EMANE (Extendable Mobile Ad-hoc Network Emulator)
* Table of Contents
{:toc}
## What is EMANE? ## What is EMANE?
@ -60,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 |
|--------------------------------------|---------|-----------------------------------------------------------| |--------------------------------------|---------|-----------------------------------------------------------|
@ -92,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
@ -104,6 +105,7 @@ prefix will place the DTD files in **/usr/local/share/emane/dtd** while CORE
expects them in **/usr/share/emane/dtd**. expects them in **/usr/share/emane/dtd**.
Update the EMANE prefix configuration to resolve this problem. Update the EMANE prefix configuration to resolve this problem.
```shell ```shell
emane_prefix = /usr/local emane_prefix = /usr/local
``` ```
@ -116,6 +118,7 @@ placed within the path defined by **emane_models_dir** in the CORE
configuration file. This path cannot end in **/emane**. configuration file. This path cannot end in **/emane**.
Here is an example model with documentation describing functionality: Here is an example model with documentation describing functionality:
```python ```python
""" """
Example custom emane model. Example custom emane model.
@ -279,14 +282,15 @@ 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
1. Follow the steps outlined for normal CORE. Here is a quick checklist for distributed emulation with EMANE.
2. Assign nodes to desired servers
3. Synchronize your machine's clocks prior to starting the emulation, 1. Follow the steps outlined for normal CORE.
2. Assign nodes to desired servers
3. Synchronize your machine's clocks prior to starting the emulation,
using *ntp* or *ptp*. Some EMANE models are sensitive to timing. using *ntp* or *ptp*. Some EMANE models are sensitive to timing.
4. Press the *Start* button to launch the distributed emulation. 4. Press the *Start* button to launch the distributed emulation.
Now when the Start button is used to instantiate the emulation, the local CORE Now when the Start button is used to instantiate the emulation, the local CORE
daemon will connect to other emulation servers that have been assigned daemon will connect to other emulation servers that have been assigned

25
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,14 +9,17 @@ 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">
@ -35,6 +37,7 @@ Create `/tmp/emane/antennaprofile.xml` with the following contents.
``` ```
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">
@ -195,6 +198,7 @@ Create `/tmp/emane/antenna30dsector.xml` with the following contents.
``` ```
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">
@ -333,17 +337,20 @@ Create `/tmp/emane/blockageaft.xml` with the following contents.
``` ```
## 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,12 +359,16 @@ 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">
@ -369,11 +380,12 @@ Create `eventservice.xml` with the following contents.
``` ```
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"/>
@ -384,6 +396,7 @@ Create `eelgenerator.xml` with the following contents.
``` ```
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,11 +426,13 @@ 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

27
docs/emane/eel.md
View file

@ -1,37 +1,44 @@
# 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">
@ -57,11 +64,12 @@ 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"/>
@ -72,6 +80,7 @@ Create `eelgenerator.xml` with the following contents.
``` ```
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'?>

34
docs/emane/gpsd.md
View file

@ -1,28 +1,33 @@
# 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">
@ -34,6 +39,7 @@ First create an `eventdaemon.xml` file on n1 with the following contents.
``` ```
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">
@ -44,11 +50,13 @@ Then create the `gpsdlocationagent.xml` file on n1 with the following contents.
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,10 +67,13 @@ 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">
@ -74,11 +85,12 @@ Create `eventservice.xml` on the host machine with the following contents.
``` ```
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"/>
@ -89,6 +101,7 @@ Create `eelgenerator.xml` on the host machine with the following contents.
``` ```
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.

32
docs/grpc.md
View file

@ -1,7 +1,6 @@
# gRPC API
* Table of Contents * Table of Contents
{:toc}
## Overview
[gRPC](https://grpc.io/) is a client/server API for interfacing with CORE [gRPC](https://grpc.io/) is a client/server API for interfacing with CORE
and used by the python GUI for driving all functionality. It is dependent and used by the python GUI for driving all functionality. It is dependent
@ -9,7 +8,7 @@ on having a running `core-daemon` instance to be leveraged.
A python client can be created from the raw generated grpc files included A python client can be created from the raw generated grpc files included
with CORE or one can leverage a provided gRPC client that helps encapsulate with CORE or one can leverage a provided gRPC client that helps encapsulate
some of the functionality to try and help make things easier. some functionality to try and help make things easier.
## Python Client ## Python Client
@ -19,7 +18,7 @@ to help provide some conveniences when using the API.
### Client HTTP Proxy ### Client HTTP Proxy
Since gRPC is HTTP2 based, proxy configurations can cause issues. By default Since gRPC is HTTP2 based, proxy configurations can cause issues. By default,
the client disables proxy support to avoid issues when a proxy is present. the client disables proxy support to avoid issues when a proxy is present.
You can enable and properly account for this issue when needed. You can enable and properly account for this issue when needed.
@ -56,8 +55,10 @@ when creating interface data for nodes. Alternatively one can manually create
a `core.api.grpc.wrappers.Interface` class instead with appropriate information. a `core.api.grpc.wrappers.Interface` class instead with appropriate information.
Manually creating gRPC client interface: Manually creating gRPC client interface:
```python ```python
from core.api.grpc.wrappers import Interface from core.api.grpc.wrappers import Interface
# id is optional and will set to the next available id # id is optional and will set to the next available id
# name is optional and will default to eth<id> # name is optional and will default to eth<id>
# mac is optional and will result in a randomly generated mac # mac is optional and will result in a randomly generated mac
@ -72,6 +73,7 @@ iface = Interface(
``` ```
Leveraging the interface helper class: Leveraging the interface helper class:
```python ```python
from core.api.grpc import client from core.api.grpc import client
@ -90,6 +92,7 @@ iface_data = iface_helper.create_iface(
Various events that can occur within a session can be listened to. Various events that can occur within a session can be listened to.
Event types: Event types:
* session - events for changes in session state and mobility start/stop/pause * session - events for changes in session state and mobility start/stop/pause
* node - events for node movements and icon changes * node - events for node movements and icon changes
* link - events for link configuration changes and wireless link add/delete * link - events for link configuration changes and wireless link add/delete
@ -101,9 +104,11 @@ Event types:
from core.api.grpc import client from core.api.grpc import client
from core.api.grpc.wrappers import EventType from core.api.grpc.wrappers import EventType
def event_listener(event): def event_listener(event):
print(event) print(event)
# create grpc client and connect # create grpc client and connect
core = client.CoreGrpcClient() core = client.CoreGrpcClient()
core.connect() core.connect()
@ -123,6 +128,7 @@ core.events(session.id, event_listener, [EventType.NODE])
Links can be configured at the time of creation or during runtime. Links can be configured at the time of creation or during runtime.
Currently supported configuration options: Currently supported configuration options:
* bandwidth (bps) * bandwidth (bps)
* delay (us) * delay (us)
* duplicate (%) * duplicate (%)
@ -167,10 +173,11 @@ core.edit_link(session.id, link)
``` ```
### Peer to Peer Example ### Peer to Peer Example
```python ```python
# required imports # required imports
from core.api.grpc import client from core.api.grpc import client
from core.api.grpc.core_pb2 import Position from core.api.grpc.wrappers import Position
# interface helper # interface helper
iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64") iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64")
@ -198,10 +205,11 @@ core.start_session(session)
``` ```
### Switch/Hub Example ### Switch/Hub Example
```python ```python
# required imports # required imports
from core.api.grpc import client from core.api.grpc import client
from core.api.grpc.core_pb2 import NodeType, Position from core.api.grpc.wrappers import NodeType, Position
# interface helper # interface helper
iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64") iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64")
@ -232,10 +240,11 @@ core.start_session(session)
``` ```
### WLAN Example ### WLAN Example
```python ```python
# required imports # required imports
from core.api.grpc import client from core.api.grpc import client
from core.api.grpc.core_pb2 import NodeType, Position from core.api.grpc.wrappers import NodeType, Position
# interface helper # interface helper
iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64") iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64")
@ -283,6 +292,7 @@ For EMANE you can import and use one of the existing models and
use its name for configuration. use its name for configuration.
Current models: Current models:
* core.emane.ieee80211abg.EmaneIeee80211abgModel * core.emane.ieee80211abg.EmaneIeee80211abgModel
* core.emane.rfpipe.EmaneRfPipeModel * core.emane.rfpipe.EmaneRfPipeModel
* core.emane.tdma.EmaneTdmaModel * core.emane.tdma.EmaneTdmaModel
@ -299,7 +309,7 @@ will use the defaults. When no configuration is used, the defaults are used.
```python ```python
# required imports # required imports
from core.api.grpc import client from core.api.grpc import client
from core.api.grpc.core_pb2 import NodeType, Position from core.api.grpc.wrappers import NodeType, Position
from core.emane.models.ieee80211abg import EmaneIeee80211abgModel from core.emane.models.ieee80211abg import EmaneIeee80211abgModel
# interface helper # interface helper
@ -339,6 +349,7 @@ core.start_session(session)
``` ```
EMANE Model Configuration: EMANE Model Configuration:
```python ```python
# emane network specific config, set on an emane node # emane network specific config, set on an emane node
# this setting applies to all nodes connected # this setting applies to all nodes connected
@ -359,6 +370,7 @@ Configuring the files of a service results in a specific hard coded script being
generated, instead of the default scripts, that may leverage dynamic generation. generated, instead of the default scripts, that may leverage dynamic generation.
The following features can be configured for a service: The following features can be configured for a service:
* files - files that will be generated * files - files that will be generated
* directories - directories that will be mounted unique to the node * directories - directories that will be mounted unique to the node
* startup - commands to run start a service * startup - commands to run start a service
@ -366,6 +378,7 @@ The following features can be configured for a service:
* shutdown - commands to run to stop a service * shutdown - commands to run to stop a service
Editing service properties: Editing service properties:
```python ```python
# configure a service, for a node, for a given session # configure a service, for a node, for a given session
node.service_configs[service_name] = NodeServiceData( node.service_configs[service_name] = NodeServiceData(
@ -381,6 +394,7 @@ When editing a service file, it must be the name of `config`
file that the service will generate. file that the service will generate.
Editing a service file: Editing a service file:
```python ```python
# to edit the contents of a generated file you can specify # to edit the contents of a generated file you can specify
# the service, the file name, and its contents # the service, the file name, and its contents

170
docs/gui.md
View file

@ -1,9 +1,5 @@
# CORE GUI # CORE GUI
* Table of Contents
{:toc}
![](static/core-gui.png) ![](static/core-gui.png)
## Overview ## Overview
@ -309,168 +305,6 @@ and options.
| CORE Documentation (www) | Lnk to the CORE Documentation page. | | CORE Documentation (www) | Lnk to the CORE Documentation page. |
| About | Invokes the About dialog box for viewing version information. | | About | Invokes the About dialog box for viewing version information. |
## Connecting with Physical Networks
CORE's emulated networks run in real time, so they can be connected to live
physical networks. The RJ45 tool and the Tunnel tool help with connecting to
the real world. These tools are available from the **Link-layer nodes** menu.
When connecting two or more CORE emulations together, MAC address collisions
should be avoided. CORE automatically assigns MAC addresses to interfaces when
the emulation is started, starting with **00:00:00:aa:00:00** and incrementing
the bottom byte. The starting byte should be changed on the second CORE machine
using the **Tools->MAC Addresses** option the menu.
### RJ45 Tool
The RJ45 node in CORE represents a physical interface on the real CORE machine.
Any real-world network device can be connected to the interface and communicate
with the CORE nodes in real time.
The main drawback is that one physical interface is required for each
connection. When the physical interface is assigned to CORE, it may not be used
for anything else. Another consideration is that the computer or network that
you are connecting to must be co-located with the CORE machine.
To place an RJ45 connection, click on the **Link-layer nodes** toolbar and select
the **RJ45 Tool** from the submenu. Click on the canvas near the node you want to
connect to. This could be a router, hub, switch, or WLAN, for example. Now
click on the *Link Tool* and draw a link between the RJ45 and the other node.
The RJ45 node will display "UNASSIGNED". Double-click the RJ45 node to assign a
physical interface. A list of available interfaces will be shown, and one may
be selected by double-clicking its name in the list, or an interface name may
be entered into the text box.
> **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 RJ45 nodes can be used within CORE and assigned to the same physical
interface if 802.1x VLANs are used. This allows for more RJ45 nodes than
physical ports are available, but the (e.g. switching) hardware connected to
the physical port must support the VLAN tagging, and the available bandwidth
will be shared.
You need to create separate VLAN virtual devices on the Linux host,
and then assign these devices to RJ45 nodes inside of CORE. The VLANning is
actually performed outside of CORE, so when the CORE emulated node receives a
packet, the VLAN tag will already be removed.
Here are example commands for creating VLAN devices under Linux:
```shell
ip link add link eth0 name eth0.1 type vlan id 1
ip link add link eth0 name eth0.2 type vlan id 2
ip link add link eth0 name eth0.3 type vlan id 3
```
### Tunnel Tool
The tunnel tool builds GRE tunnels between CORE emulations or other hosts.
Tunneling can be helpful when the number of physical interfaces is limited or
when the peer is located on a different network. Also a physical interface does
not need to be dedicated to CORE as with the RJ45 tool.
The peer GRE tunnel endpoint may be another CORE machine or another
host that supports GRE tunneling. When placing a Tunnel node, initially
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.
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
should be used when multiple tunnels are used with the same peer. When
configuring the peer side of the tunnel, ensure that the matching keys are
used.
Here are example commands for building the other end of a tunnel on a Linux
machine. In this example, a router in CORE has the virtual address
**10.0.0.1/24** and the CORE host machine has the (real) address
**198.51.100.34/24**. The Linux box
that will connect with the CORE machine is reachable over the (real) network
at **198.51.100.76/24**.
The emulated router is linked with the Tunnel Node. In the
Tunnel Node configuration dialog, the address **198.51.100.76** is entered, with
the key set to **1**. The gretap interface on the Linux box will be assigned
an address from the subnet of the virtual router node,
**10.0.0.2/24**.
```shell
# these commands are run on the tunnel peer
sudo ip link add gt0 type gretap remote 198.51.100.34 local 198.51.100.76 key 1
sudo ip addr add 10.0.0.2/24 dev gt0
sudo ip link set dev gt0 up
```
Now the virtual router should be able to ping the Linux machine:
```shell
# from the CORE router node
ping 10.0.0.2
```
And the Linux machine should be able to ping inside the CORE emulation:
```shell
# from the tunnel peer
ping 10.0.0.1
```
To debug this configuration, **tcpdump** can be run on the gretap devices, or
on the physical interfaces on the CORE or Linux machines. Make sure that a
firewall is not blocking the GRE traffic.
### Communicating with the Host Machine
The host machine that runs the CORE GUI and/or daemon is not necessarily
accessible from a node. Running an X11 application on a node, for example,
requires some channel of communication for the application to connect with
the X server for graphical display. There are different ways to
connect from the node to the host and vice versa.
#### Control Network
The quickest way to connect with the host machine through the primary control
network.
With a control network, the host can launch an X11 application on a node.
To run an X11 application on the node, the **SSH** service can be enabled on
the node, and SSH with X11 forwarding can be used from the host to the node.
```shell
# SSH from host to node n5 to run an X11 app
ssh -X 172.16.0.5 xclock
```
#### Other Methods
There are still other ways to connect a host with a node. The RJ45 Tool
can be used in conjunction with a dummy interface to access a node:
```shell
sudo modprobe dummy numdummies=1
```
A **dummy0** interface should appear on the host. Use the RJ45 tool assigned
to **dummy0**, and link this to a node in your scenario. After starting the
session, configure an address on the host.
```shell
sudo ip link show type bridge
# determine bridge name from the above command
# assign an IP address on the same network as the linked node
sudo ip addr add 10.0.1.2/24 dev b.48304.34658
```
In the example shown above, the host will have the address **10.0.1.2** and
the node linked to the RJ45 may have the address **10.0.1.1**.
## Building Sample Networks ## Building Sample Networks
### Wired Networks ### Wired Networks
@ -516,7 +350,6 @@ hardware.
* See [Wiki](https://github.com/adjacentlink/emane/wiki) for details on general EMANE usage * See [Wiki](https://github.com/adjacentlink/emane/wiki) for details on general EMANE usage
* See [CORE EMANE](emane.md) for details on using EMANE in CORE * See [CORE EMANE](emane.md) for details on using EMANE in CORE
| Model | Type | Supported Platform(s) | Fidelity | Description | | Model | Type | Supported Platform(s) | Fidelity | Description |
|----------|--------|-----------------------|----------|-------------------------------------------------------------------------------| |----------|--------|-----------------------|----------|-------------------------------------------------------------------------------|
| WLAN | On/Off | Linux | Low | Ethernet bridging with nftables | | WLAN | On/Off | Linux | Low | Ethernet bridging with nftables |
@ -561,7 +394,8 @@ CORE has a few ways to script mobility.
| EMANE events | See [EMANE](emane.md) for details on using EMANE scripts to move nodes around. Location information is typically given as latitude, longitude, and altitude. | | EMANE events | See [EMANE](emane.md) for details on using EMANE scripts to move nodes around. Location information is typically given as latitude, longitude, and altitude. |
For the first method, you can create a mobility script using a text For the first method, you can create a mobility script using a text
editor, or using a tool such as [BonnMotion](http://net.cs.uni-bonn.de/wg/cs/applications/bonnmotion/), and associate the script with one of the wireless editor, or using a tool such as [BonnMotion](http://net.cs.uni-bonn.de/wg/cs/applications/bonnmotion/), and associate
the script with one of the wireless
using the WLAN configuration dialog box. Click the *ns-2 mobility script...* using the WLAN configuration dialog box. Click the *ns-2 mobility script...*
button, and set the *mobility script file* field in the resulting *ns2script* button, and set the *mobility script file* field in the resulting *ns2script*
configuration dialog. configuration dialog.

127
docs/hitl.md Normal file
View file

@ -0,0 +1,127 @@
# Hardware In The Loop
## Overview
In some cases it may be impossible or impractical to run software using CORE
nodes alone. You may need to bring in external hardware into the network.
CORE's emulated networks run in real time, so they can be connected to live
physical networks. The RJ45 tool and the Tunnel tool help with connecting to
the real world. These tools are available from the **Link Layer Nodes** menu.
When connecting two or more CORE emulations together, MAC address collisions
should be avoided. CORE automatically assigns MAC addresses to interfaces when
the emulation is started, starting with **00:00:00:aa:00:00** and incrementing
the bottom byte. The starting byte should be changed on the second CORE machine
using the **Tools->MAC Addresses** option the menu.
## RJ45 Node
CORE provides the RJ45 node, which represents a physical
interface within the host that is running CORE. Any real-world network
devices can be connected to the interface and communicate with the CORE nodes in real time.
The main drawback is that one physical interface is required for each
connection. When the physical interface is assigned to CORE, it may not be used
for anything else. Another consideration is that the computer or network that
you are connecting to must be co-located with the CORE machine.
### GUI Usage
To place an RJ45 connection, click on the **Link Layer Nodes** toolbar and select
the **RJ45 Node** from the options. Click on the canvas, where you would like
the nodes to place. Now click on the **Link Tool** and draw a link between the RJ45
and the other node you wish to be connected to. The RJ45 node will display "UNASSIGNED".
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.
### Multiple RJ45s with One Interface (VLAN)
It is possible to have multiple RJ45 nodes using the same physical interface
by leveraging 802.1x VLANs. This allows for more RJ45 nodes than physical ports
are available, but the (e.g. switching) hardware connected to the physical port
must support the VLAN tagging, and the available bandwidth will be shared.
You need to create separate VLAN virtual devices on the Linux host,
and then assign these devices to RJ45 nodes inside of CORE. The VLANing is
actually performed outside of CORE, so when the CORE emulated node receives a
packet, the VLAN tag will already be removed.
Here are example commands for creating VLAN devices under Linux:
```shell
ip link add link eth0 name eth0.1 type vlan id 1
ip link add link eth0 name eth0.2 type vlan id 2
ip link add link eth0 name eth0.3 type vlan id 3
```
## Tunnel Tool
The tunnel tool builds GRE tunnels between CORE emulations or other hosts.
Tunneling can be helpful when the number of physical interfaces is limited or
when the peer is located on a different network. In this case a physical interface does
not need to be dedicated to CORE as with the RJ45 tool.
The peer GRE tunnel endpoint may be another CORE machine or another
host that supports GRE tunneling. When placing a Tunnel node, initially
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.
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
should be used when multiple tunnels are used with the same peer. When
configuring the peer side of the tunnel, ensure that the matching keys are
used.
### Example Usage
Here are example commands for building the other end of a tunnel on a Linux
machine. In this example, a router in CORE has the virtual address
**10.0.0.1/24** and the CORE host machine has the (real) address
**198.51.100.34/24**. The Linux box
that will connect with the CORE machine is reachable over the (real) network
at **198.51.100.76/24**.
The emulated router is linked with the Tunnel Node. In the
Tunnel Node configuration dialog, the address **198.51.100.76** is entered, with
the key set to **1**. The gretap interface on the Linux box will be assigned
an address from the subnet of the virtual router node,
**10.0.0.2/24**.
```shell
# these commands are run on the tunnel peer
sudo ip link add gt0 type gretap remote 198.51.100.34 local 198.51.100.76 key 1
sudo ip addr add 10.0.0.2/24 dev gt0
sudo ip link set dev gt0 up
```
Now the virtual router should be able to ping the Linux machine:
```shell
# from the CORE router node
ping 10.0.0.2
```
And the Linux machine should be able to ping inside the CORE emulation:
```shell
# from the tunnel peer
ping 10.0.0.1
```
To debug this configuration, **tcpdump** can be run on the gretap devices, or
on the physical interfaces on the CORE or Linux machines. Make sure that a
firewall is not blocking the GRE traffic.

19
docs/index.md
View file

@ -11,25 +11,8 @@ CORE is typically used for network and protocol research, demonstrations, applic
networking scenarios, security studies, and increasing the size of physical test networks. networking scenarios, security studies, and increasing the size of physical test networks.
### Key Features ### Key Features
* Efficient and scalable * Efficient and scalable
* Runs applications and protocols without modification * Runs applications and protocols without modification
* Drag and drop GUI * Drag and drop GUI
* Highly customizable * Highly customizable
## Topics
| Topic | Description |
|--------------------------------------|-------------------------------------------------------------------|
| [Installation](install.md) | How to install CORE and its requirements |
| [Architecture](architecture.md) | Overview of the architecture |
| [Node Types](nodetypes.md) | Overview of node types supported within CORE |
| [GUI](gui.md) | How to use the GUI |
| [Python API](python.md) | Covers how to control core directly using python |
| [gRPC API](grpc.md) | Covers how control core using gRPC |
| [Distributed](distributed.md) | Details for running CORE across multiple servers |
| [Control Network](ctrlnet.md) | How to use control networks to communicate with nodes from host |
| [Config Services](configservices.md) | Overview of provided config services and creating custom ones |
| [Services](services.md) | Overview of provided services and creating custom ones |
| [EMANE](emane.md) | Overview of EMANE integration and integrating custom EMANE models |
| [Performance](performance.md) | Notes on performance when using CORE |
| [Developers Guide](devguide.md) | Overview on how to contribute to CORE |

62
docs/install.md
View file

@ -1,11 +1,12 @@
# Installation # Installation
* Table of Contents
{:toc}
> **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)
@ -13,6 +14,7 @@ option being preferred.
* [Dockerfile based install](#dockerfile-based-install) * [Dockerfile based install](#dockerfile-based-install)
### Requirements ### Requirements
Any computer capable of running Linux should be able to run CORE. Since the physical machine will be hosting numerous Any computer capable of running Linux should be able to run CORE. Since the physical machine will be hosting numerous
containers, as a general rule you should select a machine having as much RAM and CPU resources as possible. containers, as a general rule you should select a machine having as much RAM and CPU resources as possible.
@ -21,13 +23,16 @@ containers, as a general rule you should select a machine having as much RAM and
* nftables compatible kernel and nft command line tool * nftables compatible kernel and nft command line tool
### Supported Linux Distributions ### Supported Linux Distributions
Plan is to support recent Ubuntu and CentOS LTS releases. Plan is to support recent Ubuntu and CentOS LTS releases.
Verified: Verified:
* Ubuntu - 18.04, 20.04, 22.04 * Ubuntu - 18.04, 20.04, 22.04
* CentOS - 7.8 * CentOS - 7.8
### Files ### Files
The following is a list of files that would be installed after installation. The following is a list of files that would be installed after installation.
* executables * executables
@ -46,6 +51,7 @@ The following is a list of files that would be installed after installation.
* `<repo>/../ospf-mdr` * `<repo>/../ospf-mdr`
### Installed Scripts ### Installed Scripts
The following python scripts are provided. The following python scripts are provided.
| Name | Description | | Name | Description |
@ -59,17 +65,20 @@ The following python scripts are provided.
| core-service-update | tool to update automate modifying a legacy service to match current naming | | core-service-update | tool to update automate modifying a legacy service to match current naming |
### Upgrading from Older Release ### Upgrading from Older Release
Please make sure to uninstall any previous installations of CORE cleanly Please make sure to uninstall any previous installations of CORE cleanly
before proceeding to install. before proceeding to install.
Clearing out a current install from 7.0.0+, making sure to provide options Clearing out a current install from 7.0.0+, making sure to provide options
used for install (`-l` or `-p`). used for install (`-l` or `-p`).
```shell ```shell
cd <CORE_REPO> cd <CORE_REPO>
inv uninstall <options> inv uninstall <options>
``` ```
Previous install was built from source for CORE release older than 7.0.0: Previous install was built from source for CORE release older than 7.0.0:
```shell ```shell
cd <CORE_REPO> cd <CORE_REPO>
sudo make uninstall sudo make uninstall
@ -78,6 +87,7 @@ make clean
``` ```
Installed from previously built packages: Installed from previously built packages:
```shell ```shell
# centos # centos
sudo yum remove core sudo yum remove core
@ -103,10 +113,13 @@ 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:
```shell ```shell
# recommended to upgrade to the latest version of pip before installation # recommended to upgrade to the latest version of pip before installation
# in python, can help avoid building from source issues # in python, can help avoid building from source issues
@ -128,6 +141,7 @@ sudo <python> -m pip install /opt/core/core-<version>-py3-none-any.whl
``` ```
Example for removal, requires using the same options as install: Example for removal, requires using the same options as install:
```shell ```shell
# remove a standard install # remove a standard install
sudo <yum/apt> remove core sudo <yum/apt> remove core
@ -142,6 +156,7 @@ sudo NO_PYTHON=1 <yum/apt> remove core
``` ```
### Installing OSPF MDR ### Installing OSPF MDR
You will need to manually install OSPF MDR for routing nodes, since this is not You will need to manually install OSPF MDR for routing nodes, since this is not
provided by the package. provided by the package.
@ -159,6 +174,7 @@ sudo make install
When done see [Post Install](#post-install). When done see [Post Install](#post-install).
## Script Based Install ## Script Based Install
The script based installation will install system level dependencies, python library and The script based installation will install system level dependencies, python library and
dependencies, as well as dependencies for building CORE. dependencies, as well as dependencies for building CORE.
@ -166,17 +182,22 @@ The script based install also automatically builds and installs OSPF MDR, used b
on routing nodes. This can optionally be skipped. on routing nodes. This can optionally be skipped.
Installaion will carry out the following steps: Installaion will carry out the following steps:
* installs system dependencies for building core * installs system dependencies for building core
* builds vcmd/vnoded and python grpc files * builds vcmd/vnoded and python grpc files
* installs core into poetry managed virtual environment or locally, if flag is passed * installs core into poetry managed virtual environment or locally, if flag is passed
* 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:
@ -188,6 +209,7 @@ The following tools will be leveraged during installation:
| [poetry](https://python-poetry.org/) | used to install python virtual environment or building a python wheel | | [poetry](https://python-poetry.org/) | used to install python virtual environment or building a python wheel |
First we will need to clone and navigate to the CORE repo. First we will need to clone and navigate to the CORE repo.
```shell ```shell
# clone CORE repo # clone CORE repo
git clone https://github.com/coreemu/core.git git clone https://github.com/coreemu/core.git
@ -229,6 +251,7 @@ Options:
When done see [Post Install](#post-install). When done see [Post Install](#post-install).
### Unsupported Linux Distribution ### Unsupported Linux Distribution
For unsupported OSs you could attempt to do the following to translate For unsupported OSs you could attempt to do the following to translate
an installation to your use case. an installation to your use case.
@ -243,6 +266,7 @@ inv install --dry -v -p <prefix> -i <install type>
``` ```
## Dockerfile Based Install ## Dockerfile Based Install
You can leverage one of the provided Dockerfiles, to run and launch CORE within a Docker container. You can leverage one of the provided Dockerfiles, to run and launch CORE within a Docker container.
Since CORE nodes will leverage software available within the system for a given use case, Since CORE nodes will leverage software available within the system for a given use case,
@ -253,7 +277,7 @@ make sure to update and build the Dockerfile with desired software.
git clone https://github.com/coreemu/core.git git clone https://github.com/coreemu/core.git
cd core cd core
# build image # build image
sudo docker build -t core -f Dockerfile.<centos,ubuntu,oracle> . sudo docker build -t core -f dockerfiles/Dockerfile.<centos,ubuntu,oracle> .
# start container # start container
sudo docker run -itd --name core -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix:rw --privileged core sudo docker run -itd --name core -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix:rw --privileged core
# enable xhost access to the root user # enable xhost access to the root user
@ -265,7 +289,10 @@ sudo docker exec -it core core-gui
When done see [Post Install](#post-install). 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
@ -282,6 +309,7 @@ Also, these EMANE bindings need to be built using `protoc` 3.19+. So make sure
that is available and being picked up on PATH properly. that is available and being picked up on PATH properly.
Examples for building and installing EMANE python bindings for use in CORE: Examples for building and installing EMANE python bindings for use in CORE:
```shell ```shell
# if your system does not have protoc 3.19+ # if your system does not have protoc 3.19+
wget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip wget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip
@ -306,21 +334,26 @@ inv install-emane -e <version tag>
``` ```
## Post Install ## Post Install
After installation completes you are now ready to run CORE. After installation completes you are now ready to run CORE.
### Resolving Docker Issues ### Resolving Docker Issues
If you have Docker installed, by default it will change the iptables If you have Docker installed, by default it will change the iptables
forwarding chain to drop packets, which will cause issues for CORE traffic. forwarding chain to drop packets, which will cause issues for CORE traffic.
You can temporarily resolve the issue with the following command: You can temporarily resolve the issue with the following command:
```shell ```shell
sudo iptables --policy FORWARD ACCEPT sudo iptables --policy FORWARD ACCEPT
``` ```
Alternatively, you can configure Docker to avoid doing this, but will likely Alternatively, you can configure Docker to avoid doing this, but will likely
break normal Docker networking usage. Using the setting below will require break normal Docker networking usage. Using the setting below will require
a restart. a restart.
Place the file contents below in **/etc/docker/docker.json** Place the file contents below in **/etc/docker/docker.json**
```json ```json
{ {
"iptables": false "iptables": false
@ -328,10 +361,12 @@ Place the file contents below in **/etc/docker/docker.json**
``` ```
### Resolving Path Issues ### Resolving Path Issues
One problem running CORE you may run into, using the virtual environment or locally One problem running CORE you may run into, using the virtual environment or locally
can be issues related to your path. can be issues related to your path.
To add support for your user to run scripts from the virtual environment: To add support for your user to run scripts from the virtual environment:
```shell ```shell
# can add to ~/.bashrc # can add to ~/.bashrc
export PATH=$PATH:/opt/core/venv/bin export PATH=$PATH:/opt/core/venv/bin
@ -339,6 +374,7 @@ export PATH=$PATH:/opt/core/venv/bin
This will not solve the path issue when running as sudo, so you can do either This will not solve the path issue when running as sudo, so you can do either
of the following to compensate. of the following to compensate.
```shell ```shell
# run command passing in the right PATH to pickup from the user running the command # run command passing in the right PATH to pickup from the user running the command
sudo env PATH=$PATH core-daemon sudo env PATH=$PATH core-daemon
@ -350,6 +386,7 @@ sudop core-daemon
``` ```
### Running CORE ### Running CORE
The following assumes I have resolved PATH issues and setup the `sudop` alias. The following assumes I have resolved PATH issues and setup the `sudop` alias.
```shell ```shell
@ -360,6 +397,7 @@ core-gui
``` ```
### Enabling Service ### Enabling Service
After installation, the core service is not enabled by default. If you desire to use the After installation, the core service is not enabled by default. If you desire to use the
service, run the following commands. service, run the following commands.

4
docs/install_centos.md
View file

@ -1,5 +1,7 @@
# Install CentOS # Install CentOS
## Overview
Below is a detailed path for installing CORE and related tooling on a fresh Below is a detailed path for installing CORE and related tooling on a fresh
CentOS 7 install. Both of the examples below will install CORE into its CentOS 7 install. Both of the examples below will install CORE into its
own virtual environment located at **/opt/core/venv**. Both examples below own virtual environment located at **/opt/core/venv**. Both examples below
@ -122,6 +124,7 @@ The CORE virtual environment and related scripts will not be found on your PATH,
so some adjustments needs to be made. so some adjustments needs to be made.
To add support for your user to run scripts from the virtual environment: To add support for your user to run scripts from the virtual environment:
```shell ```shell
# can add to ~/.bashrc # can add to ~/.bashrc
export PATH=$PATH:/opt/core/venv/bin export PATH=$PATH:/opt/core/venv/bin
@ -129,6 +132,7 @@ export PATH=$PATH:/opt/core/venv/bin
This will not solve the path issue when running as sudo, so you can do either This will not solve the path issue when running as sudo, so you can do either
of the following to compensate. of the following to compensate.
```shell ```shell
# run command passing in the right PATH to pickup from the user running the command # run command passing in the right PATH to pickup from the user running the command
sudo env PATH=$PATH core-daemon sudo env PATH=$PATH core-daemon

6
docs/install_ubuntu.md
View file

@ -1,7 +1,9 @@
# Install Ubuntu # Install Ubuntu
## Overview
Below is a detailed path for installing CORE and related tooling on a fresh Below is a detailed path for installing CORE and related tooling on a fresh
Ubuntu 22.04 install. Both of the examples below will install CORE into its Ubuntu 22.04 installation. Both of the examples below will install CORE into its
own virtual environment located at **/opt/core/venv**. Both examples below own virtual environment located at **/opt/core/venv**. Both examples below
also assume using **~/Documents** as the working directory. also assume using **~/Documents** as the working directory.
@ -94,6 +96,7 @@ The CORE virtual environment and related scripts will not be found on your PATH,
so some adjustments needs to be made. so some adjustments needs to be made.
To add support for your user to run scripts from the virtual environment: To add support for your user to run scripts from the virtual environment:
```shell ```shell
# can add to ~/.bashrc # can add to ~/.bashrc
export PATH=$PATH:/opt/core/venv/bin export PATH=$PATH:/opt/core/venv/bin
@ -101,6 +104,7 @@ export PATH=$PATH:/opt/core/venv/bin
This will not solve the path issue when running as sudo, so you can do either This will not solve the path issue when running as sudo, so you can do either
of the following to compensate. of the following to compensate.
```shell ```shell
# run command passing in the right PATH to pickup from the user running the command # run command passing in the right PATH to pickup from the user running the command
sudo env PATH=$PATH core-daemon sudo env PATH=$PATH core-daemon

2
docs/lxc.md
View file

@ -1,5 +1,7 @@
# LXC Support # LXC Support
## Overview
LXC nodes are provided by way of LXD to create nodes using predefined LXC nodes are provided by way of LXD to create nodes using predefined
images and provide file system separation. images and provide file system separation.

5
docs/nodetypes.md
View file

@ -1,7 +1,4 @@
# CORE Node Types # Node Types
* Table of Contents
{:toc}
## Overview ## Overview

10
docs/performance.md
View file

@ -1,8 +1,5 @@
# CORE Performance # CORE Performance
* Table of Contents
{:toc}
## Overview ## Overview
The top question about the performance of CORE is often *how many nodes can it The top question about the performance of CORE is often *how many nodes can it
@ -16,7 +13,6 @@ handle?* The answer depends on several factors:
| Network traffic | the more packets that are sent around the virtual network increases the amount of CPU usage. | | Network traffic | the more packets that are sent around the virtual network increases the amount of CPU usage. |
| GUI usage | widgets that run periodically, mobility scenarios, and other GUI interactions generally consume CPU cycles that may be needed for emulation. | | GUI usage | widgets that run periodically, mobility scenarios, and other GUI interactions generally consume CPU cycles that may be needed for emulation. |
On a typical single-CPU Xeon 3.0GHz server machine with 2GB RAM running Linux, On a typical single-CPU Xeon 3.0GHz server machine with 2GB RAM running Linux,
we have found it reasonable to run 30-75 nodes running OSPFv2 and OSPFv3 we have found it reasonable to run 30-75 nodes running OSPFv2 and OSPFv3
routing. On this hardware CORE can instantiate 100 or more nodes, but at routing. On this hardware CORE can instantiate 100 or more nodes, but at
@ -32,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:

3
docs/python.md
View file

@ -1,8 +1,5 @@
# Python API # Python API
* Table of Contents
{:toc}
## Overview ## Overview
Writing your own Python scripts offers a rich programming environment with Writing your own Python scripts offers a rich programming environment with

38
docs/services.md
View file

@ -1,9 +1,6 @@
# CORE Services # Services (Deprecated)
* Table of Contents ## Overview
{:toc}
## Services
CORE uses the concept of services to specify what processes or scripts run on a CORE uses the concept of services to specify what processes or scripts run on a
node when it is started. Layer-3 nodes such as routers and PCs are defined by node when it is started. Layer-3 nodes such as routers and PCs are defined by
@ -15,7 +12,9 @@ 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
**Network namespace nodes do not undergo the normal Linux boot process**
using the **init**, **upstart**, or **systemd** frameworks. These using the **init**, **upstart**, or **systemd** frameworks. These
lightweight nodes use configured CORE *services*. lightweight nodes use configured CORE *services*.
@ -71,7 +70,9 @@ 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
A **yellow** customize icon next to a service indicates that service
requires customization (e.g. the *Firewall* service). requires customization (e.g. the *Firewall* service).
A **green** customize icon indicates that a custom configuration exists. A **green** customize icon indicates that a custom configuration exists.
Click the *Defaults* button when customizing a service to remove any Click the *Defaults* button when customizing a service to remove any
@ -90,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
The **/var/log** and **/var/run** directories are
mounted uniquely per-node by default. mounted uniquely per-node by default.
Per-node mount targets can be found in **/tmp/pycore.nnnnn/nN.conf/** Per-node mount targets can be found in **/tmp/pycore.<session id>/<node name>.conf/**
(where *nnnnn* is the session number and *N* is the node number.)
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
@ -120,7 +122,9 @@ 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
To start, stop, and restart services during run-time, right-click a
node and use the *Services...* menu. node and use the *Services...* menu.
## New Services ## New Services
@ -138,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
@ -151,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.

5
docs/services/bird.md
View file

@ -1,8 +1,5 @@
# BIRD Internet Routing Daemon # BIRD Internet Routing Daemon
* Table of Contents
{:toc}
## Overview ## Overview
The [BIRD Internet Routing Daemon](https://bird.network.cz/) is a routing The [BIRD Internet Routing Daemon](https://bird.network.cz/) is a routing
@ -30,6 +27,7 @@ sudo apt-get install bird
You can download BIRD source code from its You can download BIRD source code from its
[official repository.](https://gitlab.labs.nic.cz/labs/bird/) [official repository.](https://gitlab.labs.nic.cz/labs/bird/)
```shell ```shell
./configure ./configure
make make
@ -37,6 +35,7 @@ su
make install make install
vi /etc/bird/bird.conf vi /etc/bird/bird.conf
``` ```
The installation will place the bird directory inside */etc* where you will The installation will place the bird directory inside */etc* where you will
also find its config file. also find its config file.

3
docs/services/emane.md
View file

@ -1,8 +1,5 @@
# EMANE Services # EMANE Services
* Table of Contents
{:toc}
## Overview ## Overview
EMANE related services for CORE. EMANE related services for CORE.

28
docs/services/frr.md
View file

@ -1,13 +1,14 @@
# FRRouting # FRRouting
* Table of Contents
{:toc}
## Overview ## Overview
FRRouting is a routing software package that provides TCP/IP based routing services with routing protocols support such as BGP, RIP, OSPF, IS-IS and more. FRR also supports special BGP Route Reflector and Route Server behavior. In addition to traditional IPv4 routing protocols, FRR also supports IPv6 routing protocols. With an SNMP daemon that supports the AgentX protocol, FRR provides routing protocol MIB read-only access (SNMP Support). FRRouting is a routing software package that provides TCP/IP based routing services with routing protocols support such
as BGP, RIP, OSPF, IS-IS and more. FRR also supports special BGP Route Reflector and Route Server behavior. In addition
to traditional IPv4 routing protocols, FRR also supports IPv6 routing protocols. With an SNMP daemon that supports the
AgentX protocol, FRR provides routing protocol MIB read-only access (SNMP Support).
FRR (as of v7.2) currently supports the following protocols: FRR (as of v7.2) currently supports the following protocols:
* BGPv4 * BGPv4
* OSPFv2 * OSPFv2
* OSPFv3 * OSPFv3
@ -26,11 +27,13 @@ FRR (as of v7.2) currently supports the following protocols:
## FRRouting Package Install ## FRRouting Package Install
Ubuntu 19.10 and later Ubuntu 19.10 and later
```shell ```shell
sudo apt update && sudo apt install frr sudo apt update && sudo apt install frr
``` ```
Ubuntu 16.04 and Ubuntu 18.04 Ubuntu 16.04 and Ubuntu 18.04
```shell ```shell
sudo apt install curl sudo apt install curl
curl -s https://deb.frrouting.org/frr/keys.asc | sudo apt-key add - curl -s https://deb.frrouting.org/frr/keys.asc | sudo apt-key add -
@ -38,25 +41,35 @@ FRRVER="frr-stable"
echo deb https://deb.frrouting.org/frr $(lsb_release -s -c) $FRRVER | sudo tee -a /etc/apt/sources.list.d/frr.list echo deb https://deb.frrouting.org/frr $(lsb_release -s -c) $FRRVER | sudo tee -a /etc/apt/sources.list.d/frr.list
sudo apt update && sudo apt install frr frr-pythontools sudo apt update && sudo apt install frr frr-pythontools
``` ```
Fedora 31 Fedora 31
```shell ```shell
sudo dnf update && sudo dnf install frr sudo dnf update && sudo dnf install frr
``` ```
## FRRouting Source Code Install ## FRRouting Source Code Install
Building FRR from source is the best way to ensure you have the latest features and bug fixes. Details for each supported platform, including dependency package listings, permissions, and other gotchas, are in the developer’s documentation. Building FRR from source is the best way to ensure you have the latest features and bug fixes. Details for each
supported platform, including dependency package listings, permissions, and other gotchas, are in the developer’s
documentation.
FRR’s source is available on the project [GitHub page](https://github.com/FRRouting/frr). FRR’s source is available on the project [GitHub page](https://github.com/FRRouting/frr).
```shell ```shell
git clone https://github.com/FRRouting/frr.git git clone https://github.com/FRRouting/frr.git
``` ```
Change into your FRR source directory and issue: Change into your FRR source directory and issue:
```shell ```shell
./bootstrap.sh ./bootstrap.sh
``` ```
Then, choose the configuration options that you wish to use for the installation. You can find these options on FRR's [official webpage](http://docs.frrouting.org/en/latest/installation.html). Once you have chosen your configure options, run the configure script and pass the options you chose:
Then, choose the configuration options that you wish to use for the installation. You can find these options on
FRR's [official webpage](http://docs.frrouting.org/en/latest/installation.html). Once you have chosen your configure
options, run the configure script and pass the options you chose:
```shell ```shell
./configure \ ./configure \
--prefix=/usr \ --prefix=/usr \
@ -68,8 +81,11 @@ Then, choose the configuration options that you wish to use for the installation
--enable-watchfrr \ --enable-watchfrr \
... ...
``` ```
After configuring the software, you are ready to build and install it in your system. After configuring the software, you are ready to build and install it in your system.
```shell ```shell
make && sudo make install make && sudo make install
``` ```
If everything finishes successfully, FRR should be installed. If everything finishes successfully, FRR should be installed.

42
docs/services/nrl.md
View file

@ -1,13 +1,21 @@
# NRL Services # NRL Services
* Table of Contents
{:toc}
## Overview ## Overview
The Protean Protocol Prototyping Library (ProtoLib) is a cross-platform library that allows applications to be built while supporting a variety of platforms including Linux, Windows, WinCE/PocketPC, MacOS, FreeBSD, Solaris, etc as well as the simulation environments of NS2 and Opnet. The goal of the Protolib is to provide a set of simple, cross-platform C++ classes that allow development of network protocols and applications that can run on different platforms and in network simulation environments. While Protolib provides an overall framework for developing working protocol implementations, applications, and simulation modules, the individual classes are designed for use as stand-alone components when possible. Although Protolib is principally for research purposes, the code has been constructed to provide robust, efficient performance and adaptability to real applications. In some cases, the code consists of data structures, etc useful in protocol implementations and, in other cases, provides common, cross-platform interfaces to system services and functions (e.g., sockets, timers, routing tables, etc). The Protean Protocol Prototyping Library (ProtoLib) is a cross-platform library that allows applications to be built
while supporting a variety of platforms including Linux, Windows, WinCE/PocketPC, MacOS, FreeBSD, Solaris, etc as well
as the simulation environments of NS2 and Opnet. The goal of the Protolib is to provide a set of simple, cross-platform
C++ classes that allow development of network protocols and applications that can run on different platforms and in
network simulation environments. While Protolib provides an overall framework for developing working protocol
implementations, applications, and simulation modules, the individual classes are designed for use as stand-alone
components when possible. Although Protolib is principally for research purposes, the code has been constructed to
provide robust, efficient performance and adaptability to real applications. In some cases, the code consists of data
structures, etc useful in protocol implementations and, in other cases, provides common, cross-platform interfaces to
system services and functions (e.g., sockets, timers, routing tables, etc).
Currently, the Naval Research Laboratory uses this library to develop a wide variety of protocols.The NRL Protolib
currently supports the following protocols:
Currently the Naval Research Laboratory uses this library to develop a wide variety of protocols.The NRL Protolib currently supports the following protocols:
* MGEN_Sink * MGEN_Sink
* NHDP * NHDP
* SMF * SMF
@ -19,11 +27,14 @@ Currently the Naval Research Laboratory uses this library to develop a wide vari
## NRL Installation ## NRL Installation
In order to be able to use the different protocols that NRL offers, you must first download the support library itself. You can get the source code from their [NRL Protolib Repo](https://github.com/USNavalResearchLaboratory/protolib). In order to be able to use the different protocols that NRL offers, you must first download the support library itself.
You can get the source code from their [NRL Protolib Repo](https://github.com/USNavalResearchLaboratory/protolib).
## Multi-Generator (MGEN) ## Multi-Generator (MGEN)
Download MGEN from the [NRL MGEN Repo](https://github.com/USNavalResearchLaboratory/mgen), unpack it and copy the protolib library into the main folder *mgen*. Execute the following commands to build the protocol. Download MGEN from the [NRL MGEN Repo](https://github.com/USNavalResearchLaboratory/mgen), unpack it and copy the
protolib library into the main folder *mgen*. Execute the following commands to build the protocol.
```shell ```shell
cd mgen/makefiles cd mgen/makefiles
make -f Makefile.{os} mgen make -f Makefile.{os} mgen
@ -32,16 +43,22 @@ make -f Makefile.{os} mgen
## Neighborhood Discovery Protocol (NHDP) ## Neighborhood Discovery Protocol (NHDP)
Download NHDP from the [NRL NHDP Repo](https://github.com/USNavalResearchLaboratory/NCS-Downloads/tree/master/nhdp). Download NHDP from the [NRL NHDP Repo](https://github.com/USNavalResearchLaboratory/NCS-Downloads/tree/master/nhdp).
```shell ```shell
sudo apt-get install libpcap-dev libboost-all-dev sudo apt-get install libpcap-dev libboost-all-dev
wget https://github.com/protocolbuffers/protobuf/releases/download/v3.8.0/protoc-3.8.0-linux-x86_64.zip wget https://github.com/protocolbuffers/protobuf/releases/download/v3.8.0/protoc-3.8.0-linux-x86_64.zip
unzip protoc-3.8.0-linux-x86_64.zip unzip protoc-3.8.0-linux-x86_64.zip
``` ```
Then place the binaries in your $PATH. To know your paths you can issue the following command Then place the binaries in your $PATH. To know your paths you can issue the following command
```shell ```shell
echo $PATH echo $PATH
``` ```
Go to the downloaded *NHDP* tarball, unpack it and place the protolib library inside the NHDP main folder. Now, compile the NHDP Protocol.
Go to the downloaded *NHDP* tarball, unpack it and place the protolib library inside the NHDP main folder. Now, compile
the NHDP Protocol.
```shell ```shell
cd nhdp/unix cd nhdp/unix
make -f Makefile.{os} make -f Makefile.{os}
@ -49,7 +66,9 @@ make -f Makefile.{os}
## Simplified Multicast Forwarding (SMF) ## Simplified Multicast Forwarding (SMF)
Download SMF from the [NRL SMF Repo](https://github.com/USNavalResearchLaboratory/nrlsmf) , unpack it and place the protolib library inside the *smf* main folder. Download SMF from the [NRL SMF Repo](https://github.com/USNavalResearchLaboratory/nrlsmf) , unpack it and place the
protolib library inside the *smf* main folder.
```shell ```shell
cd mgen/makefiles cd mgen/makefiles
make -f Makefile.{os} make -f Makefile.{os}
@ -57,7 +76,10 @@ make -f Makefile.{os}
## Optimized Link State Routing Protocol (OLSR) ## Optimized Link State Routing Protocol (OLSR)
To install the OLSR protocol, download their source code from their [NRL OLSR Repo](https://github.com/USNavalResearchLaboratory/nrlolsr). Unpack it and place the previously downloaded protolib library inside the *nrlolsr* main directory. Then execute the following commands: To install the OLSR protocol, download their source code from
their [NRL OLSR Repo](https://github.com/USNavalResearchLaboratory/nrlolsr). Unpack it and place the previously
downloaded protolib library inside the *nrlolsr* main directory. Then execute the following commands:
```shell ```shell
cd ./unix cd ./unix
make -f Makefile.{os} make -f Makefile.{os}

14
docs/services/quagga.md
View file

@ -1,12 +1,13 @@
# Quagga Routing Suite # Quagga Routing Suite
* Table of Contents
{:toc}
## Overview ## Overview
Quagga is a routing software suite, providing implementations of OSPFv2, OSPFv3, RIP v1 and v2, RIPng and BGP-4 for Unix platforms, particularly FreeBSD, Linux, Solaris and NetBSD. Quagga is a fork of GNU Zebra which was developed by Kunihiro Ishiguro. Quagga is a routing software suite, providing implementations of OSPFv2, OSPFv3, RIP v1 and v2, RIPng and BGP-4 for Unix
The Quagga architecture consists of a core daemon, zebra, which acts as an abstraction layer to the underlying Unix kernel and presents the Zserv API over a Unix or TCP stream to Quagga clients. It is these Zserv clients which typically implement a routing protocol and communicate routing updates to the zebra daemon. platforms, particularly FreeBSD, Linux, Solaris and NetBSD. Quagga is a fork of GNU Zebra which was developed by
Kunihiro Ishiguro.
The Quagga architecture consists of a core daemon, zebra, which acts as an abstraction layer to the underlying Unix
kernel and presents the Zserv API over a Unix or TCP stream to Quagga clients. It is these Zserv clients which typically
implement a routing protocol and communicate routing updates to the zebra daemon.
## Quagga Package Install ## Quagga Package Install
@ -17,10 +18,13 @@ sudo apt-get install quagga
## Quagga Source Install ## Quagga Source Install
First, download the source code from their [official webpage](https://www.quagga.net/). First, download the source code from their [official webpage](https://www.quagga.net/).
```shell ```shell
sudo apt-get install gawk sudo apt-get install gawk
``` ```
Extract the tarball, go to the directory of your currently extracted code and issue the following commands. Extract the tarball, go to the directory of your currently extracted code and issue the following commands.
```shell ```shell
./configure ./configure
make make

8
docs/services/sdn.md
View file

@ -1,11 +1,11 @@
# Software Defined Networking # Software Defined Networking
* Table of Contents
{:toc}
## Overview ## Overview
Ryu is a component-based software defined networking framework. Ryu provides software components with well defined API that make it easy for developers to create new network management and control applications. Ryu supports various protocols for managing network devices, such as OpenFlow, Netconf, OF-config, etc. About OpenFlow, Ryu supports fully 1.0, 1.2, 1.3, 1.4, 1.5 and Nicira Extensions. All of the code is freely available under the Apache 2.0 license. Ryu is a component-based software defined networking framework. Ryu provides software components with well defined API
that make it easy for developers to create new network management and control applications. Ryu supports various
protocols for managing network devices, such as OpenFlow, Netconf, OF-config, etc. About OpenFlow, Ryu supports fully
1.0, 1.2, 1.3, 1.4, 1.5 and Nicira Extensions. All of the code is freely available under the Apache 2.0 license.
## Installation ## Installation

18
docs/services/security.md
View file

@ -1,15 +1,15 @@
# Security Services # Security Services
* Table of Contents
{:toc}
## Overview ## Overview
The security services offer a wide variety of protocols capable of satisfying the most use cases available. Security services such as IP security protocols, for providing security at the IP layer, as well as the suite of protocols designed to provide that security, through authentication and encryption of IP network packets. Virtual Private Networks (VPNs) and Firewalls are also available for use to the user. The security services offer a wide variety of protocols capable of satisfying the most use cases available. Security
services such as IP security protocols, for providing security at the IP layer, as well as the suite of protocols
designed to provide that security, through authentication and encryption of IP network packets. Virtual Private
Networks (VPNs) and Firewalls are also available for use to the user.
## Installation ## Installation
Libraries needed for some of the security services. Libraries needed for some security services.
```shell ```shell
sudo apt-get install ipsec-tools racoon sudo apt-get install ipsec-tools racoon
@ -71,7 +71,9 @@ sudo cp pki/dh.pem $KEYDIR/dh1024.pem
Add VPNServer service to nodes desired for running an OpenVPN server. Add VPNServer service to nodes desired for running an OpenVPN server.
Modify [sampleVPNServer](https://github.com/coreemu/core/blob/master/package/examples/services/sampleVPNServer) for the following Modify [sampleVPNServer](https://github.com/coreemu/core/blob/master/package/examples/services/sampleVPNServer) for the
following
* Edit keydir key/cert directory * Edit keydir key/cert directory
* Edit keyname to use generated server name above * Edit keyname to use generated server name above
* Edit vpnserver to match an address that the server node will have * Edit vpnserver to match an address that the server node will have
@ -80,7 +82,9 @@ Modify [sampleVPNServer](https://github.com/coreemu/core/blob/master/package/exa
Add VPNClient service to nodes desired for acting as an OpenVPN client. Add VPNClient service to nodes desired for acting as an OpenVPN client.
Modify [sampleVPNClient](https://github.com/coreemu/core/blob/master/package/examples/services/sampleVPNClient) for the following Modify [sampleVPNClient](https://github.com/coreemu/core/blob/master/package/examples/services/sampleVPNClient) for the
following
* Edit keydir key/cert directory * Edit keydir key/cert directory
* Edit keyname to use generated client name above * Edit keyname to use generated client name above
* Edit vpnserver to match the address a server was configured to use * Edit vpnserver to match the address a server was configured to use

14
docs/services/utility.md
View file

@ -1,13 +1,11 @@
# Utility Services # Utility Services
* Table of Contents ## Overview
{:toc}
# Overview
Variety of convenience services for carrying out common networking changes. Variety of convenience services for carrying out common networking changes.
The following services are provided as utilities: The following services are provided as utilities:
* UCARP * UCARP
* IP Forward * IP Forward
* Default Routing * Default Routing
@ -25,15 +23,19 @@ The following services are provided as utilities:
## Installation ## Installation
To install the functionality of the previously metioned services you can run the following command: To install the functionality of the previously metioned services you can run the following command:
```shell ```shell
sudo apt-get install isc-dhcp-server apache2 libpcap-dev radvd at sudo apt-get install isc-dhcp-server apache2 libpcap-dev radvd at
``` ```
## UCARP ## UCARP
UCARP allows a couple of hosts to share common virtual IP addresses in order to provide automatic failover. It is a portable userland implementation of the secure and patent-free Common Address Redundancy Protocol (CARP, OpenBSD's alternative to the patents-bloated VRRP). UCARP allows a couple of hosts to share common virtual IP addresses in order to provide automatic failover. It is a
portable userland implementation of the secure and patent-free Common Address Redundancy Protocol (CARP, OpenBSD's
alternative to the patents-bloated VRRP).
Strong points of the CARP protocol are: very low overhead, cryptographically signed messages, interoperability between different operating systems and no need for any dedicated extra network link between redundant hosts. Strong points of the CARP protocol are: very low overhead, cryptographically signed messages, interoperability between
different operating systems and no need for any dedicated extra network link between redundant hosts.
### Installation ### Installation

40
docs/services/xorp.md
View file

@ -1,36 +1,48 @@
# XORP routing suite # XORP routing suite
* Table of Contents
{:toc}
## Overview ## Overview
XORP is an open networking platform that supports OSPF, RIP, BGP, OLSR, VRRP, PIM, IGMP (Multicast) and other routing protocols. Most protocols support IPv4 and IPv6 where applicable. It is known to work on various Linux distributions and flavors of BSD. XORP is an open networking platform that supports OSPF, RIP, BGP, OLSR, VRRP, PIM, IGMP (Multicast) and other routing
protocols. Most protocols support IPv4 and IPv6 where applicable. It is known to work on various Linux distributions and
flavors of BSD.
XORP started life as a project at the ICSI Center for Open Networking (ICON) at the International Computer Science Institute in Berkeley, California, USA, and spent some time with the team at XORP, Inc. It is now maintained and improved on a volunteer basis by a core of long-term XORP developers and some newer contributors. XORP started life as a project at the ICSI Center for Open Networking (ICON) at the International Computer Science
Institute in Berkeley, California, USA, and spent some time with the team at XORP, Inc. It is now maintained and
improved on a volunteer basis by a core of long-term XORP developers and some newer contributors.
XORP's primary goal is to be an open platform for networking protocol implementations and an alternative to proprietary and closed networking products in the marketplace today. It is the only open source platform to offer integrated multicast capability. XORP's primary goal is to be an open platform for networking protocol implementations and an alternative to proprietary
and closed networking products in the marketplace today. It is the only open source platform to offer integrated
multicast capability.
XORP design philosophy is: XORP design philosophy is:
* modularity
* extensibility
* performance
* robustness
This is achieved by carefully separating functionalities into independent modules, and by providing an API for each module.
XORP divides into two subsystems. The higher-level ("user-level") subsystem consists of the routing protocols. The lower-level ("kernel") manages the forwarding path, and provides APIs for the higher-level to access. * modularity
* extensibility
* performance
* robustness
This is achieved by carefully separating functionalities into independent modules, and by providing an API for each
module.
User-level XORP uses multi-process architecture with one process per routing protocol, and a novel inter-process communication mechanism called XRL (XORP Resource Locator). XORP divides into two subsystems. The higher-level ("user-level") subsystem consists of the routing protocols. The
lower-level ("kernel") manages the forwarding path, and provides APIs for the higher-level to access.
The lower-level subsystem can use traditional UNIX kernel forwarding, or Click modular router. The modularity and independency of the lower-level from the user-level subsystem allows for its easily replacement with other solutions including high-end hardware-based forwarding engines. User-level XORP uses multi-process architecture with one process per routing protocol, and a novel inter-process
communication mechanism called XRL (XORP Resource Locator).
The lower-level subsystem can use traditional UNIX kernel forwarding, or Click modular router. The modularity and
independency of the lower-level from the user-level subsystem allows for its easily replacement with other solutions
including high-end hardware-based forwarding engines.
## Installation ## Installation
In order to be able to install the XORP Routing Suite, you must first install scons in order to compile it. In order to be able to install the XORP Routing Suite, you must first install scons in order to compile it.
```shell ```shell
sudo apt-get install scons sudo apt-get install scons
``` ```
Then, download XORP from its official [release web page](http://www.xorp.org/releases/current/). Then, download XORP from its official [release web page](http://www.xorp.org/releases/current/).
```shell ```shell
http://www.xorp.org/releases/current/ http://www.xorp.org/releases/current/
cd xorp cd xorp

57
mkdocs.yml Normal file
View file

@ -0,0 +1,57 @@
site_name: CORE Documentation
use_directory_urls: false
theme:
name: material
palette:
- scheme: slate
toggle:
icon: material/brightness-4
name: Switch to Light Mode
primary: teal
accent: teal
- scheme: default
toggle:
icon: material/brightness-7
name: Switch to Dark Mode
primary: teal
accent: teal
features:
- navigation.path
- navigation.instant
- navigation.footer
- content.code.copy
markdown_extensions:
- pymdownx.snippets:
base_path: docs
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
- pymdownx.inlinehilite
nav:
- Home: index.md
- Overview:
- Architecture: architecture.md
- Performance: performance.md
- Installation:
- Overview: install.md
- Ubuntu: install_ubuntu.md
- CentOS: install_centos.md
- Detailed Topics:
- GUI: gui.md
- Node Types:
- Overview: nodetypes.md
- Docker: docker.md
- LXC: lxc.md
- Services:
- Config Services: configservices.md
- Services (Deprecated): services.md
- API:
- Python: python.md
- gRPC: grpc.md
- Distributed: distributed.md
- Control Network: ctrlnet.md
- Hardware In The Loop: hitl.md
- EMANE: emane.md
- Developers Guide: devguide.md