CORE can create and run multiple emulated sessions at once, below is an +overview of the states a session will transition between during typical +GUI interactions.
+
The CORE framework runs on Linux and uses Linux namespacing for creating +node containers. These nodes are linked together using Linux bridging and +virtual interfaces. CORE sessions are a set of nodes and links operating +together for a specific purpose.
+Linux network namespaces (also known as netns) is the primary +technique used by CORE. Most recent Linux distributions have +namespaces-enabled kernels out of the box. Each namespace has its own process +environment and private network stack. Network namespaces share the same +filesystem in CORE.
+CORE combines these namespaces with Linux Ethernet bridging to form networks. +Link characteristics are applied using Linux Netem queuing disciplines. +Nftables provides Ethernet frame filtering on Linux bridges. Wireless networks are +emulated by controlling which interfaces can send and receive with nftables +rules.
+CORE has been released by Boeing to the open source community under the BSD +license. If you find CORE useful for your work, please contribute back to the +project. Contributions can be as simple as reporting a bug, dropping a line of +encouragement, or can also include submitting patches or maintaining aspects +of the tool.
+ + + + + + +Config services are a newer version of services for CORE, that leverage a +templating engine, for more robust service file creation. They also +have the power of configuration key/value pairs that values that can be +defined and displayed within the GUI, to help further tweak a service, +as needed.
+CORE services are a convenience for creating reusable dynamic scripts +to run on nodes, for carrying out specific task(s).
+This boilds down to the following functions:
+Most CORE nodes will have a default set of services to run, associated with +them. You can however customize the set of services a node will use. Or even +further define a new node type within the GUI, with a set of services, that +will allow quickly dragging and dropping that node type during creation.
+| Service Group | +Services | +
|---|---|
| BIRD | +BGP, OSPF, RADV, RIP, Static | +
| EMANE | +Transport Service | +
| FRR | +BABEL, BGP, OSPFv2, OSPFv3, PIMD, RIP, RIPNG, Zebra | +
| NRL | +arouted, MGEN Sink, MGEN Actor, NHDP, OLSR, OLSRORG, OLSRv2, SMF | +
| Quagga | +BABEL, BGP, OSPFv2, OSPFv3, OSPFv3 MDR, RIP, RIPNG, XPIMD, Zebra | +
| SDN | +OVS, RYU | +
| Security | +Firewall, IPsec, NAT, VPN Client, VPN Server | +
| Utility | +ATD, Routing Utils, DHCP, FTP, IP Forward, PCAP, RADVD, SSF, UCARP | +
| XORP | +BGP, OLSR, OSPFv2, OSPFv3, PIMSM4, PIMSM6, RIP, RIPNG, Router Manager | +
Here are the default node types and their services:
+| Node Type | +Services | +
|---|---|
| router | +zebra, OSFPv2, OSPFv3, and IPForward services for IGP link-state routing. | +
| PC | +DefaultRoute service for having a default route when connected directly to a router. | +
| mdr | +zebra, OSPFv3MDR, and IPForward services for wireless-optimized MANET Designated Router routing. | +
| prouter | +a physical router, having the same default services as the router node type; for incorporating Linux testbed machines into an emulation. | +
Configuration files can be automatically generated by each service. For +example, CORE automatically generates routing protocol configuration for the +router nodes in order to simplify the creation of virtual networks.
+To change the services associated with a node, double-click on the node to +invoke its configuration dialog and click on the Services... button, +or right-click a node a choose Services... from the menu. +Services are enabled or disabled by clicking on their names. The button next to +each service name allows you to customize all aspects of this service for this +node. For example, special route redistribution commands could be inserted in +to the Quagga routing configuration associated with the zebra service.
+To change the default services associated with a node type, use the Node Types +dialog available from the Edit button at the end of the Layer-3 nodes +toolbar, or choose Node types... from the Session menu. Note that +any new services selected are not applied to existing nodes if the nodes have +been customized.
+The node types are saved in the GUI config file ~/.coregui/config.yaml. +Keep this in mind when changing the default services for +existing node types; it may be better to simply create a new node type. It is +recommended that you do not change the default built-in node types.
+Services can save time required to configure nodes, especially if a number +of nodes require similar configuration procedures. New services can be +introduced to automate tasks.
+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.
+Modify the example service shown below + to do what you want. It could generate config/script files, mount per-node + directories, start processes/scripts, etc. Your file can define one or more + classes to be imported. You can create multiple Python files that will be imported.
+Put these files in a directory such as ~/.coregui/custom_services.
+Add a custom_config_services_dir = ~/.coregui/custom_services entry to the + /etc/core/core.conf file.
+Restart the CORE daemon (core-daemon). Any import errors (Python syntax) + should be displayed in the terminal (or service log, like journalctl).
+Start using your custom service on your nodes. You can create a new node + type that uses your service, or change the default services for an existing + node type, or change individual nodes.
+Below is the skeleton for a custom service with some documentation. Most +people would likely only setup the required class variables (name/group). +Then define the files to generate and implement the +get_text_template function to dynamically create the files wanted. Finally, +the startup commands would be supplied, which typically tend to be +running the shell files generated.
+from typing import Dict, List
+
+from core.config import ConfigString, ConfigBool, Configuration
+from core.configservice.base import ConfigService, ConfigServiceMode, ShadowDir
+
+
+# class that subclasses ConfigService
+class ExampleService(ConfigService):
+ # unique name for your service within CORE
+ name: str = "Example"
+ # the group your service is associated with, used for display in GUI
+ group: str = "ExampleGroup"
+ # directories that the service should shadow mount, hiding the system directory
+ directories: List[str] = [
+ "/usr/local/core",
+ ]
+ # files that this service should generate, defaults to nodes home directory
+ # or can provide an absolute path to a mounted directory
+ files: List[str] = [
+ "example-start.sh",
+ "/usr/local/core/file1",
+ ]
+ # executables that should exist on path, that this service depends on
+ executables: List[str] = []
+ # other services that this service depends on, can be used to define service start order
+ dependencies: List[str] = []
+ # commands to run to start this service
+ startup: List[str] = []
+ # commands to run to validate this service
+ validate: List[str] = []
+ # commands to run to stop this service
+ shutdown: List[str] = []
+ # validation mode, blocking, non-blocking, and timer
+ validation_mode: ConfigServiceMode = ConfigServiceMode.BLOCKING
+ # configurable values that this service can use, for file generation
+ default_configs: List[Configuration] = [
+ ConfigString(id="value1", label="Text"),
+ ConfigBool(id="value2", label="Boolean"),
+ ConfigString(id="value3", label="Multiple Choice", options=["value1", "value2", "value3"]),
+ ]
+ # sets of values to set for the configuration defined above, can be used to
+ # provide convenient sets of values to typically use
+ modes: Dict[str, Dict[str, str]] = {
+ "mode1": {"value1": "value1", "value2": "0", "value3": "value2"},
+ "mode2": {"value1": "value2", "value2": "1", "value3": "value3"},
+ "mode3": {"value1": "value3", "value2": "0", "value3": "value1"},
+ }
+ # defines directories that this service can help shadow within a node
+ shadow_directories: List[ShadowDir] = [
+ ShadowDir(path="/user/local/core", src="/opt/core")
+ ]
+
+ def get_text_template(self, name: str) -> str:
+ return """
+ # sample script 1
+ # node id(${node.id}) name(${node.name})
+ # config: ${config}
+ echo hello
+ """
+Validation modes are used to determine if a service has started up successfully.
+Shadow directories provide a convenience for copying a directory and the files within +it to a nodes home directory, to allow a unique set of per node files.
+ShadowDir(path="/user/local/core") - copies files at the given location into the nodeShadowDir(path="/user/local/core", src="/opt/core") - copies files to the given location,
+ but sourced from the provided locationShadowDir(path="/user/local/core", templates=True) - copies files and treats them as
+ templates for generationShadowDir(path="/user/local/core", has_node_paths=True) - copies files from the given
+ location, and looks for unique node names directories within it, using a directory named
+ default, when not presetThe CORE control network allows the virtual nodes to communicate with their +host environment. There are two types: the primary control network and +auxiliary control networks. The primary control network is used mainly for +communicating with the virtual nodes from host machines and for master-slave +communications in a multi-server distributed environment. Auxiliary control +networks have been introduced to for routing namespace hosted emulation +software traffic to the test network.
+Under the Session Menu, the Options... dialog has an option to set a +control network prefix.
+This can be set to a network prefix such as 172.16.0.0/24. A bridge will +be created on the host machine having the last address in the prefix range +(e.g. 172.16.0.254), and each node will have an extra ctrl0 control +interface configured with an address corresponding to its node number +(e.g. 172.16.0.3 for n3.)
+A default for the primary control network may also be specified by setting +the controlnet line in the /etc/core/core.conf configuration file which +new sessions will use by default. To simultaneously run multiple sessions with +control networks, the session option should be used instead of the core.conf +default.
+Note
+If you have a large scenario with more than 253 nodes, use a control +network prefix that allows more than the suggested /24, such as /23 or +greater.
+Note
+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.
+# Restart the CORE Daemon
+sudo /etc/init.d core-daemon restart
+
+# Remove lingering control network bridges
+ctrlbridges=`brctl show | grep b.ctrl | awk '{print $1}'`
+for cb in $ctrlbridges; do
+ sudo ifconfig $cb down
+ sudo brctl delbr $cb
+done
+Note
+If adjustments to the primary control network configuration made in +/etc/core/core.conf do not seem to take affect, check if there is anything +set in the Session Menu, the Options... dialog. They may need to be +cleared. These per session settings override the defaults in +/etc/core/core.conf.
+When the primary control network is activated for a distributed session, a +control network bridge will be created on each of the slave servers, with +GRE tunnels back to the master server's bridge. The slave control bridges +are not assigned an address. From the host, any of the nodes (local or remote) +can be accessed, just like the single server case.
+In some situations, remote emulated nodes need to communicate with the host +on which they are running and not the master server. Multiple control network +prefixes can be specified in the either the session option or +/etc/core/core.conf, separated by spaces and beginning with the master +server. Each entry has the form "server:prefix". For example, if the servers +core1,core2, and core3 are assigned with nodes in the scenario and using +/etc/core/core.conf instead of the session option.
+controlnet=core1:172.16.1.0/24 core2:172.16.2.0/24 core3:172.16.1.0/24
+Then, the control network bridges will be assigned as follows:
+Tunnels back to the master server will still be built, but it is up to the +user to add appropriate routes if networking between control network prefixes +is desired. The control network script may help with this.
+A control network script may be specified using the controlnet_updown_script +option in the /etc/core/core.conf file. This script will be run after the +bridge has been built (and address assigned) with the first argument being the +name of the bridge, and the second argument being the keyword "startup". +The script will again be invoked prior to bridge removal with the second +argument being the keyword "shutdown".
+Starting with EMANE 0.9.2, CORE will run EMANE instances within namespaces. +Since it is advisable to separate the OTA traffic from other traffic, we will +need more than single channel leading out from the namespace. Up to three +auxiliary control networks may be defined. Multiple control networks are set +up in /etc/core/core.conf file. Lines controlnet1, controlnet2 and +controlnet3 define the auxiliary networks.
+For example, having the following /etc/core/core.conf:
+controlnet = core1:172.17.1.0/24 core2:172.17.2.0/24 core3:172.17.3.0/24
+controlnet1 = core1:172.18.1.0/24 core2:172.18.2.0/24 core3:172.18.3.0/24
+controlnet2 = core1:172.19.1.0/24 core2:172.19.2.0/24 core3:172.19.3.0/24
+This will activate the primary and two auxiliary control networks and add +interfaces ctrl0, ctrl1, ctrl2 to each node. One use case would be to +assign ctrl1 to the OTA manager device and ctrl2 to the Event Service +device in the EMANE Options dialog box and leave ctrl0 for CORE control +traffic.
+Note
+controlnet0 may be used in place of controlnet to configure +the primary control network.
+Unlike the primary control network, the auxiliary control networks will not +employ tunneling since their primary purpose is for efficiently transporting +multicast EMANE OTA and event traffic. Note that there is no per-session +configuration for auxiliary control networks.
+To extend the auxiliary control networks across a distributed test +environment, host network interfaces need to be added to them. The following +lines in /etc/core/core.conf will add host devices eth1, eth2 and eth3 +to controlnet1, controlnet2, controlnet3:
+controlnetif1 = eth1
+controlnetif2 = eth2
+controlnetif3 = eth3
+Note
+There is no need to assign an interface to the primary control +network because tunnels are formed between the master and the slaves using IP +addresses that are provided in servers.conf.
+Shown below is a representative diagram of the configuration above.
+
The CORE source consists of several programming languages for +historical reasons. Current development focuses on the Python modules and +daemon. Here is a brief description of the source directories.
+| Directory | +Description | +
|---|---|
| daemon | +Python CORE daemon/gui code that handles receiving API calls and creating containers | +
| docs | +Markdown Documentation currently hosted on GitHub | +
| man | +Template files for creating man pages for various CORE command line utilities | +
| netns | +C program for creating CORE containers | +
To setup CORE for develop we will leverage to automated install script.
+cd ~/Documents
+git clone https://github.com/coreemu/core.git
+cd core
+git checkout develop
+This command will automatically install system dependencies, clone and build OSPF-MDR, +build CORE, setup the CORE poetry environment, and install pre-commit hooks. You can +refer to the install docs for issues related to different distributions.
+./install -d
+pre-commit hooks help automate running tools to check modified code. Every time a commit is made +python utilities will be ran to check validity of code, potentially failing and backing out the commit. +These changes are currently mandated as part of the current CI, so add the changes and commit again.
+You can now run core as you normally would, or leverage some of the invoke tasks to +conveniently run tests, etc.
+# run core-daemon
+sudo core-daemon
+
+# run gui
+core-gui
+
+# run mocked unit tests
+cd <CORE_REPO>
+inv test-mock
+Linux network namespace containers are often managed using the Linux Container Tools or lxc-tools package. +The lxc-tools website is available here http://lxc.sourceforge.net/ for more information. CORE does not use these +management utilities, but includes its own set of tools for instantiating and configuring network namespace containers. +This section describes these tools.
+The vnoded daemon is the program used to create a new namespace, and listen on a control channel for commands that +may instantiate other processes. This daemon runs as PID 1 in the container. It is launched automatically by the CORE +daemon. The control channel is a UNIX domain socket usually named /tmp/pycore.23098/n3, for node 3 running on CORE +session 23098, for example. Root privileges are required for creating a new namespace.
+The vcmd program is used to connect to the vnoded daemon in a Linux network namespace, for running commands in the +namespace. The CORE daemon uses the same channel for setting up a node and running processes within it. This program +has two required arguments, the control channel name, and the command line to be run within the namespace. This command +does not need to run with root privileges.
+When you double-click on a node in a running emulation, CORE will open a shell window for that node using a command +such as:
+gnome-terminal -e vcmd -c /tmp/pycore.50160/n1 -- bash
+Similarly, the IPv4 routes Observer Widget will run a command to display the routing table using a command such as:
+vcmd -c /tmp/pycore.50160/n1 -- /sbin/ip -4 ro
+A script named core-cleanup is provided to clean up any running CORE emulations. It will attempt to kill any
+remaining vnoded processes, kill any EMANE processes, remove the :file:/tmp/pycore.* session directories, and remove
+any bridges or nftables rules. With a -d option, it will also kill any running CORE daemon.
The netns command is not used by CORE directly. This utility can be used to run a command in a new network namespace +for testing purposes. It does not open a control channel for receiving further commands.
+Here are some other Linux commands that are useful for managing the Linux network namespace emulation.
+# view the Linux bridging setup
+ip link show type bridge
+# view the netem rules used for applying link effects
+tc qdisc show
+# view the rules that make the wireless LAN work
+nft list ruleset
+A large emulation scenario can be deployed on multiple emulation servers and +controlled by a single GUI. The GUI, representing the entire topology, can be +run on one of the emulation servers or on a separate machine.
+Each machine that will act as an emulation will require the installation of a +distributed CORE package and some configuration to allow SSH as root.
+CORE configuration settings required for using distributed functionality.
+Edit /etc/core/core.conf or specific configuration file being used.
+# uncomment and set this to the address that remote servers
+# use to get back to the main host, example below
+distributed_address = 129.168.0.101
+EMANE needs to have controlnet configured in core.conf in order to startup correctly. +The names before the addresses need to match the names of distributed servers configured.
+controlnet = core1:172.16.1.0/24 core2:172.16.2.0/24 core3:172.16.3.0/24 core4:172.16.4.0/24 core5:172.16.5.0/24
+emane_event_generate = True
+Distributed CORE works using the python fabric library to run commands on +remote servers over SSH.
+You need to have the same user defined on each server, since the user used +for these remote shells is the same user that is running the CORE GUI.
+Edit -> Preferences... -> Terminal program:
+Currently recommend setting this to xterm -e as the default +gnome-terminal will not work.
+May need to install xterm if, not already installed.
+sudo apt install xterm
+First the distributed servers must be configured to allow passwordless root +login over SSH.
+On distributed server:
+# install openssh-server
+sudo apt install openssh-server
+
+# open sshd config
+vi /etc/ssh/sshd_config
+
+# verify these configurations in file
+PermitRootLogin yes
+PasswordAuthentication yes
+
+# if desired add/modify the following line to allow SSH to
+# accept all env variables
+AcceptEnv *
+
+# restart sshd
+sudo systemctl restart sshd
+On master server:
+# install package if needed
+sudo apt install openssh-client
+
+# generate ssh key if needed
+ssh-keygen -o -t rsa -b 4096 -f ~/.ssh/core
+
+# copy public key to authorized_keys file
+ssh-copy-id -i ~/.ssh/core root@server
+
+# configure fabric to use the core ssh key
+sudo vi /etc/fabric.yml
+
+# set configuration
+connect_kwargs: {"key_filename": "/home/user/.ssh/core"}
+On distributed server:
+# open sshd config
+vi /etc/ssh/sshd_config
+
+# change configuration for root login to without password
+PermitRootLogin without-password
+
+# restart sshd
+sudo systemctl restart sshd
+Make sure the value used below is the absolute path to the file +generated above ~/.ssh/core"
+Add/update the fabric configuration file /etc/fabric.yml:
+connect_kwargs: { "key_filename": "/home/user/.ssh/core" }
+Within the core-gui navigate to menu option:
+Session -> Servers...
+Within the dialog box presented, add or modify an existing server if present +to use the name, address, and port for the a server you plan to use.
+Server configurations are loaded and written to in a configuration file for +the GUI.
+The user needs to assign nodes to emulation servers in the scenario. Making no +assignment means the node will be emulated on the master server +In the configuration window of every node, a drop-down box located between +the Node name and the Image button will select the name of the emulation +server. By default, this menu shows (none), indicating that the node will +be emulated locally on the master. When entering Execute mode, the CORE GUI +will deploy the node on its assigned emulation server.
+Another way to assign emulation servers is to select one or more nodes using +the select tool (ctrl-click to select multiple), and right-click one of the +nodes and choose Assign to....
+The CORE emulation servers dialog box may also be used to assign nodes to +servers. The assigned server name appears in parenthesis next to the node name. +To assign all nodes to one of the servers, click on the server name and then +the all nodes button. Servers that have assigned nodes are shown in blue in +the server list. Another option is to first select a subset of nodes, then open +the CORE emulation servers box and use the selected nodes button.
+IMPORTANT: Leave the nodes unassigned if they are to be run on the master +server. Do not explicitly assign the nodes to the master server.
+If there is a link between two nodes residing on different servers, the GUI +will draw the link with a dashed line.
+Wireless nodes, i.e. those connected to a WLAN node, can be assigned to +different emulation servers and participate in the same wireless network +only if an EMANE model is used for the WLAN. The basic range model does +not work across multiple servers due to the Linux bridging and nftables +rules that are used.
+Note
+The basic range wireless model does not support distributed emulation, +but EMANE does.
+When nodes are linked across servers core-daemons will automatically +create necessary tunnels between the nodes when executed. Care should be taken +to arrange the topology such that the number of tunnels is minimized. The +tunnels carry data between servers to connect nodes as specified in the topology. +These tunnels are created using GRE tunneling, similar to the Tunnel Tool.
+Provided below is some information for helping setup and use Docker +nodes within a CORE scenario.
+sudo apt install docker.io
+Custom configuration required to avoid iptable rules being added and removing +the need for the default docker network, since core will be orchestrating +connections between nodes.
+Place the file below in /etc/docker/docker.json
+{
+ "bridge": "none",
+ "iptables": false
+}
+To use Docker nodes within the python GUI, you will need to make sure the +user running the GUI is a member of the docker group.
+# add group if does not exist
+sudo groupadd docker
+
+# add user to group
+sudo usermod -aG docker $USER
+
+# to get this change to take effect, log out and back in or run the following
+newgrp docker
+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.
+Example Dockerfile:
+FROM ubuntu:latest
+RUN apt-get update
+RUN apt-get install -y iproute2 ethtool
+Build image:
+sudo docker build -t <name> .
+The Extendable Mobile Ad-hoc Network Emulator (EMANE) allows heterogeneous +network emulation using a pluggable MAC and PHY layer architecture. The +EMANE framework provides an implementation architecture for modeling +different radio interface types in the form of Network Emulation Modules +(NEMs) and incorporating these modules into a real-time emulation running +in a distributed environment.
+EMANE is developed by U.S. Naval Research Labs (NRL) Code 5522 and Adjacent +Link LLC, who maintain these websites:
+ +Instead of building Linux Ethernet bridging networks with CORE, +higher-fidelity wireless networks can be emulated using EMANE bound to virtual +devices. CORE emulates layers 3 and above (network, session, application) with +its virtual network stacks and process space for protocols and applications, +while EMANE emulates layers 1 and 2 (physical and data link) using its +pluggable PHY and MAC models.
+The interface between CORE and EMANE is a TAP device. CORE builds the virtual +node using Linux network namespaces, installs the TAP device into the namespace +and instantiates one EMANE process in the namespace. The EMANE process binds a +user space socket to the TAP device for sending and receiving data from CORE.
+An EMANE instance sends and receives OTA (Over-The-Air) traffic to and from +other EMANE instances via a control port (e.g. ctrl0, ctrl1). It also +sends and receives Events to and from the Event Service using the same or a +different control port. EMANE models are configured through the GUI's +configuration dialog. A corresponding EmaneModel Python class is sub-classed +for each supported EMANE model, to provide configuration items and their +mapping to XML files. This way new models can be easily supported. When +CORE starts the emulation, it generates the appropriate XML files that +specify the EMANE NEM configuration, and launches the EMANE daemons.
+Some EMANE models support location information to determine when packets +should be dropped. EMANE has an event system where location events are +broadcast to all NEMs. CORE can generate these location events when nodes +are moved on the canvas. The canvas size and scale dialog has controls for +mapping the X,Y coordinate system to a latitude, longitude geographic system +that EMANE uses. When specified in the core.conf configuration file, CORE +can also subscribe to EMANE location events and move the nodes on the canvas +as they are moved in the EMANE emulation. This would occur when an Emulation +Script Generator, for example, is running a mobility script.
+This section will cover some high level topics and examples for running and +using EMANE in CORE.
+You can find more detailed tutorials and examples at the +EMANE Tutorial.
+Every topic below assumes CORE, EMANE, and OSPF MDR have been installed.
+Info
+Demo files will be found within the core-gui ~/.coregui/xmls directory
| Topic | +Model | +Description | +
|---|---|---|
| XML Files | +RF Pipe | +Overview of generated XML files used to drive EMANE | +
| GPSD | +RF Pipe | +Overview of running and integrating gpsd with EMANE | +
| Precomputed | +RF Pipe | +Overview of using the precomputed propagation model | +
| EEL | +RF Pipe | +Overview of using the Emulation Event Log (EEL) Generator | +
| Antenna Profiles | +RF Pipe | +Overview of using antenna profiles in EMANE | +
The CORE configuration file /etc/core/core.conf has options specific to +EMANE. An example emane section from the core.conf file is shown below:
+# EMANE configuration
+emane_platform_port = 8101
+emane_transform_port = 8201
+emane_event_monitor = False
+#emane_models_dir = /home/<user>/.coregui/custom_emane
+# EMANE log level range [0,4] default: 2
+emane_log_level = 2
+emane_realtime = True
+# prefix used for emane installation
+# emane_prefix = /usr
+If you have an EMANE event generator (e.g. mobility or pathloss scripts) and +want to have CORE subscribe to EMANE location events, set the following line +in the core.conf configuration file.
+Note
+Do not set this option to True if you want to manually drag nodes around +on the canvas to update their location in EMANE.
+emane_event_monitor = True
+Another common issue is if installing EMANE from source, the default configure +prefix will place the DTD files in /usr/local/share/emane/dtd while CORE +expects them in /usr/share/emane/dtd.
+Update the EMANE prefix configuration to resolve this problem.
+emane_prefix = /usr/local
+CORE supports custom developed EMANE models by way of dynamically loading user +created python files that represent the model. Custom EMANE models should be +placed within the path defined by emane_models_dir in the CORE +configuration file. This path cannot end in /emane.
+Here is an example model with documentation describing functionality:
+"""
+Example custom emane model.
+"""
+from pathlib import Path
+from typing import Dict, Optional, Set, List
+
+from core.config import Configuration
+from core.emane import emanemanifest, emanemodel
+
+
+class ExampleModel(emanemodel.EmaneModel):
+ """
+ Custom emane model.
+
+ :cvar name: defines the emane model name that will show up in the GUI
+
+ Mac Definition:
+ :cvar mac_library: defines that mac library that the model will reference
+ :cvar mac_xml: defines the mac manifest file that will be parsed to obtain configuration options,
+ that will be displayed within the GUI
+ :cvar mac_defaults: allows you to override options that are maintained within the manifest file above
+ :cvar mac_config: parses the manifest file and converts configurations into core supported formats
+
+ Phy Definition:
+ NOTE: phy configuration will default to the universal model as seen below and the below section does not
+ have to be included
+ :cvar phy_library: defines that phy library that the model will reference, used if you need to
+ provide a custom phy
+ :cvar phy_xml: defines the phy manifest file that will be parsed to obtain configuration options,
+ that will be displayed within the GUI
+ :cvar phy_defaults: allows you to override options that are maintained within the manifest file above
+ or for the default universal model
+ :cvar phy_config: parses the manifest file and converts configurations into core supported formats
+
+ Custom Override Options:
+ NOTE: these options default to what's seen below and do not have to be included
+ :cvar config_ignore: allows you to ignore options within phy/mac, used typically if you needed to add
+ a custom option for display within the gui
+ """
+
+ name: str = "emane_example"
+ mac_library: str = "rfpipemaclayer"
+ mac_xml: str = "/usr/share/emane/manifest/rfpipemaclayer.xml"
+ mac_defaults: Dict[str, str] = {
+ "pcrcurveuri": "/usr/share/emane/xml/models/mac/rfpipe/rfpipepcr.xml"
+ }
+ mac_config: List[Configuration] = []
+ phy_library: Optional[str] = None
+ phy_xml: str = "/usr/share/emane/manifest/emanephy.xml"
+ phy_defaults: Dict[str, str] = {
+ "subid": "1", "propagationmodel": "2ray", "noisemode": "none"
+ }
+ phy_config: List[Configuration] = []
+ config_ignore: Set[str] = set()
+
+ @classmethod
+ def load(cls, emane_prefix: Path) -> None:
+ """
+ Called after being loaded within the EmaneManager. Provides configured
+ emane_prefix for parsing xml files.
+
+ :param emane_prefix: configured emane prefix path
+ :return: nothing
+ """
+ cls._load_platform_config(emane_prefix)
+ manifest_path = "share/emane/manifest"
+ # load mac configuration
+ mac_xml_path = emane_prefix / manifest_path / cls.mac_xml
+ cls.mac_config = emanemanifest.parse(mac_xml_path, cls.mac_defaults)
+ # load phy configuration
+ phy_xml_path = emane_prefix / manifest_path / cls.phy_xml
+ cls.phy_config = emanemanifest.parse(phy_xml_path, cls.phy_defaults)
+This section describes running CORE and EMANE on a single machine. This is the +default mode of operation when building an EMANE network with CORE. The OTA +manager and Event service interface are set to use ctrl0 and the virtual +nodes use the primary control channel for communicating with one another. The +primary control channel is automatically activated when a scenario involves +EMANE. Using the primary control channel prevents your emulation session from +sending multicast traffic on your local network and interfering with other +EMANE users.
+EMANE is configured through an EMANE node. Once a node is linked to an EMANE +cloud, the radio interface on that node may also be configured +separately (apart from the cloud.)
+Right click on an EMANE node and select EMANE Config to open the configuration dialog. +The EMANE models should be listed here for selection. (You may need to restart the +CORE daemon if it was running prior to installing the EMANE Python bindings.)
+When an EMANE model is selected, you can click on the models option button +causing the GUI to query the CORE daemon for configuration items. +Each model will have different parameters, refer to the +EMANE documentation for an explanation of each item. The defaults values are +presented in the dialog. Clicking Apply and Apply again will store the +EMANE model selections.
+The RF-PIPE and IEEE 802.11abg models use a Universal PHY that supports +geographic location information for determining pathloss between nodes. A +default latitude and longitude location is provided by CORE and this +location-based pathloss is enabled by default; this is the pathloss mode +setting for the Universal PHY. Moving a node on the canvas while the +emulation is running generates location events for EMANE. To view or change +the geographic location or scale of the canvas use the Canvas Size and Scale +dialog available from the Canvas menu.
+Note that conversion between geographic and Cartesian coordinate systems is +done using UTM (Universal Transverse Mercator) projection, where different +zones of 6 degree longitude bands are defined. The location events generated +by CORE may become inaccurate near the zone boundaries for very large scenarios +that span multiple UTM zones. It is recommended that EMANE location scripts be +used to achieve geo-location accuracy in this situation.
+Clicking the green Start button launches the emulation and causes TAP devices +to be created in the virtual nodes that are linked to the EMANE WLAN. These +devices appear with interface names such as eth0, eth1, etc. The EMANE processes +should now be running in each namespace.
+To view the configuration generated by CORE, look in the /tmp/pycore.nnnnn/ session +directory to find the generated EMANE xml files. One easy way to view +this information is by double-clicking one of the virtual nodes and listing the files +in the shell.
+
Running CORE and EMANE distributed among two or more emulation servers is +similar to running on a single machine. There are a few key configuration +items that need to be set in order to be successful, and those are outlined here.
+It is a good idea to maintain separate networks for data (OTA) and control. +The control network may be a shared laboratory network, for example, and you do +not want multicast traffic on the data network to interfere with other EMANE +users. Furthermore, control traffic could interfere with the OTA latency and +throughput and might affect emulation fidelity. The examples described here will +use eth0 as a control interface and eth1 as a data interface, although +using separate interfaces is not strictly required. Note that these interface +names refer to interfaces present on the host machine, not virtual interfaces +within a node.
+IMPORTANT: If an auxiliary control network is used, an interface on the host +has to be assigned to that network.
+Each machine that will act as an emulation server needs to have CORE distributed +and EMANE installed. As well as be setup to work for CORE distributed mode.
+The IP addresses of the available servers are configured from the CORE +servers dialog box. The dialog shows available +servers, some or all of which may be assigned to nodes on the canvas.
+Nodes need to be assigned to servers and can be done so using the node +configuration dialog. When a node is not assigned to any emulation server, +it will be emulated locally.
+Using the EMANE node configuration dialog. You can change the EMANE model +being used, along with changing any configuration setting from their defaults.
+
Note
+Here is a quick checklist for distributed emulation with EMANE.
+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 +to nodes. Each server will have its own session directory where the +platform.xml file and other EMANE XML files are generated. The NEM IDs are +automatically coordinated across servers so there is no overlap.
+An Ethernet device is used for disseminating multicast EMANE events, as +specified in the configure emane dialog. EMANE's Event Service can be run +with mobility or pathloss scripts. +If CORE is not subscribed to location events, it will generate them as nodes +are moved on the canvas.
+Double-clicking on a node during runtime will cause the GUI to attempt to SSH +to the emulation server for that node and run an interactive shell. The public +key SSH configuration should be tested with all emulation servers prior to +starting the emulation.
+ + + + + + +Introduction to using the EMANE antenna profile in CORE, based on the example +EMANE Demo linked below.
+EMANE Demo 6 +for more specifics.
+We will need to create some files in advance of starting this session.
+Create directory to place antenna profile files.
+mkdir /tmp/emane
+Create /tmp/emane/antennaprofile.xml with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE profiles SYSTEM "file:///usr/share/emane/dtd/antennaprofile.dtd">
+<profiles>
+ <profile id="1"
+ antennapatternuri="/tmp/emane/antenna30dsector.xml"
+ blockagepatternuri="/tmp/emane/blockageaft.xml">
+ <placement north="0" east="0" up="0"/>
+ </profile>
+ <profile id="2"
+ antennapatternuri="/tmp/emane/antenna30dsector.xml">
+ <placement north="0" east="0" up="0"/>
+ </profile>
+</profiles>
+Create /tmp/emane/antenna30dsector.xml with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE antennaprofile SYSTEM "file:///usr/share/emane/dtd/antennaprofile.dtd">
+
+<!-- 30degree sector antenna pattern with main beam at +6dB and gain decreasing by 3dB every 5 degrees in elevation or bearing.-->
+<antennaprofile>
+ <antennapattern>
+ <elevation min='-90' max='-16'>
+ <bearing min='0' max='359'>
+ <gain value='-200'/>
+ </bearing>
+ </elevation>
+ <elevation min='-15' max='-11'>
+ <bearing min='0' max='5'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='6' max='10'>
+ <gain value='-3'/>
+ </bearing>
+ <bearing min='11' max='15'>
+ <gain value='-6'/>
+ </bearing>
+ <bearing min='16' max='344'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='345' max='349'>
+ <gain value='-6'/>
+ </bearing>
+ <bearing min='350' max='354'>
+ <gain value='-3'/>
+ </bearing>
+ <bearing min='355' max='359'>
+ <gain value='0'/>
+ </bearing>
+ </elevation>
+ <elevation min='-10' max='-6'>
+ <bearing min='0' max='5'>
+ <gain value='3'/>
+ </bearing>
+ <bearing min='6' max='10'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='11' max='15'>
+ <gain value='-3'/>
+ </bearing>
+ <bearing min='16' max='344'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='345' max='349'>
+ <gain value='-3'/>
+ </bearing>
+ <bearing min='350' max='354'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='355' max='359'>
+ <gain value='3'/>
+ </bearing>
+ </elevation>
+ <elevation min='-5' max='-1'>
+ <bearing min='0' max='5'>
+ <gain value='6'/>
+ </bearing>
+ <bearing min='6' max='10'>
+ <gain value='3'/>
+ </bearing>
+ <bearing min='11' max='15'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='16' max='344'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='345' max='349'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='350' max='354'>
+ <gain value='3'/>
+ </bearing>
+ <bearing min='355' max='359'>
+ <gain value='6'/>
+ </bearing>
+ </elevation>
+ <elevation min='0' max='5'>
+ <bearing min='0' max='5'>
+ <gain value='6'/>
+ </bearing>
+ <bearing min='6' max='10'>
+ <gain value='3'/>
+ </bearing>
+ <bearing min='11' max='15'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='16' max='344'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='345' max='349'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='350' max='354'>
+ <gain value='3'/>
+ </bearing>
+ <bearing min='355' max='359'>
+ <gain value='6'/>
+ </bearing>
+ </elevation>
+ <elevation min='6' max='10'>
+ <bearing min='0' max='5'>
+ <gain value='3'/>
+ </bearing>
+ <bearing min='6' max='10'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='11' max='15'>
+ <gain value='-3'/>
+ </bearing>
+ <bearing min='16' max='344'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='345' max='349'>
+ <gain value='-3'/>
+ </bearing>
+ <bearing min='350' max='354'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='355' max='359'>
+ <gain value='3'/>
+ </bearing>
+ </elevation>
+ <elevation min='11' max='15'>
+ <bearing min='0' max='5'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='6' max='10'>
+ <gain value='-3'/>
+ </bearing>
+ <bearing min='11' max='15'>
+ <gain value='-6'/>
+ </bearing>
+ <bearing min='16' max='344'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='345' max='349'>
+ <gain value='-6'/>
+ </bearing>
+ <bearing min='350' max='354'>
+ <gain value='-3'/>
+ </bearing>
+ <bearing min='355' max='359'>
+ <gain value='0'/>
+ </bearing>
+ </elevation>
+ <elevation min='16' max='90'>
+ <bearing min='0' max='359'>
+ <gain value='-200'/>
+ </bearing>
+ </elevation>
+ </antennapattern>
+</antennaprofile>
+Create /tmp/emane/blockageaft.xml with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE antennaprofile SYSTEM "file:///usr/share/emane/dtd/antennaprofile.dtd">
+
+<!-- blockage pattern: 1) entire aft in bearing (90 to 270) blocked 2) elevation below -10 blocked, 3) elevation from -10 to -1 is at -10dB to -1 dB 3) elevation from 0 to 90 no blockage-->
+<antennaprofile>
+ <blockagepattern>
+ <elevation min='-90' max='-11'>
+ <bearing min='0' max='359'>
+ <gain value='-200'/>
+ </bearing>
+ </elevation>
+ <elevation min='-10' max='-10'>
+ <bearing min='0' max='89'>
+ <gain value='-10'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='-10'/>
+ </bearing>
+ </elevation>
+ <elevation min='-9' max='-9'>
+ <bearing min='0' max='89'>
+ <gain value='-9'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='-9'/>
+ </bearing>
+ </elevation>
+ <elevation min='-8' max='-8'>
+ <bearing min='0' max='89'>
+ <gain value='-8'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='-8'/>
+ </bearing>
+ </elevation>
+ <elevation min='-7' max='-7'>
+ <bearing min='0' max='89'>
+ <gain value='-7'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='-7'/>
+ </bearing>
+ </elevation>
+ <elevation min='-6' max='-6'>
+ <bearing min='0' max='89'>
+ <gain value='-6'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='-6'/>
+ </bearing>
+ </elevation>
+ <elevation min='-5' max='-5'>
+ <bearing min='0' max='89'>
+ <gain value='-5'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='-5'/>
+ </bearing>
+ </elevation>
+ <elevation min='-4' max='-4'>
+ <bearing min='0' max='89'>
+ <gain value='-4'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='-4'/>
+ </bearing>
+ </elevation>
+ <elevation min='-3' max='-3'>
+ <bearing min='0' max='89'>
+ <gain value='-3'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='-3'/>
+ </bearing>
+ </elevation>
+ <elevation min='-2' max='-2'>
+ <bearing min='0' max='89'>
+ <gain value='-2'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='-2'/>
+ </bearing>
+ </elevation>
+ <elevation min='-1' max='-1'>
+ <bearing min='0' max='89'>
+ <gain value='-1'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='-1'/>
+ </bearing>
+ </elevation>
+ <elevation min='0' max='90'>
+ <bearing min='0' max='89'>
+ <gain value='0'/>
+ </bearing>
+ <bearing min='90' max='270'>
+ <gain value='-200'/>
+ </bearing>
+ <bearing min='271' max='359'>
+ <gain value='0'/>
+ </bearing>
+ </elevation>
+ </blockagepattern>
+</antennaprofile>
+Open... within the GUIemane-demo-antenna.xml
This demo will cover running an EMANE event service to feed in antenna, +location, and pathloss events to demonstrate how antenna profiles +can be used.
+On n1 lets dump EMANE events, so when we later run the EMANE event service +you can monitor when and what is sent.
+root@n1:/tmp/pycore.44917/n1.conf# emaneevent-dump -i ctrl0
+On the host machine create the following to send EMANE events.
+Warning
+Make sure to set the eventservicedevice to the proper control
+network value
Create eventservice.xml with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE eventservice SYSTEM "file:///usr/share/emane/dtd/eventservice.dtd">
+<eventservice>
+ <param name="eventservicegroup" value="224.1.2.8:45703"/>
+ <param name="eventservicedevice" value="b.9001.da"/>
+ <generator definition="eelgenerator.xml"/>
+</eventservice>
+Create eelgenerator.xml with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE eventgenerator SYSTEM "file:///usr/share/emane/dtd/eventgenerator.dtd">
+<eventgenerator library="eelgenerator">
+ <param name="inputfile" value="scenario.eel"/>
+ <paramlist name="loader">
+ <item value="commeffect:eelloadercommeffect:delta"/>
+ <item value="location,velocity,orientation:eelloaderlocation:delta"/>
+ <item value="pathloss:eelloaderpathloss:delta"/>
+ <item value="antennaprofile:eelloaderantennaprofile:delta"/>
+ </paramlist>
+</eventgenerator>
+Create scenario.eel with the following contents.
0.0 nem:1 antennaprofile 1,0.0,0.0
+0.0 nem:4 antennaprofile 2,0.0,0.0
+#
+0.0 nem:1 pathloss nem:2,60 nem:3,60 nem:4,60
+0.0 nem:2 pathloss nem:3,60 nem:4,60
+0.0 nem:3 pathloss nem:4,60
+#
+0.0 nem:1 location gps 40.025495,-74.315441,3.0
+0.0 nem:2 location gps 40.025495,-74.312501,3.0
+0.0 nem:3 location gps 40.023235,-74.315441,3.0
+0.0 nem:4 location gps 40.023235,-74.312501,3.0
+0.0 nem:4 velocity 180.0,0.0,10.0
+#
+30.0 nem:1 velocity 20.0,0.0,10.0
+30.0 nem:1 orientation 0.0,0.0,10.0
+30.0 nem:1 antennaprofile 1,60.0,0.0
+30.0 nem:4 velocity 270.0,0.0,10.0
+#
+60.0 nem:1 antennaprofile 1,105.0,0.0
+60.0 nem:4 antennaprofile 2,45.0,0.0
+#
+90.0 nem:1 velocity 90.0,0.0,10.0
+90.0 nem:1 orientation 0.0,0.0,0.0
+90.0 nem:1 antennaprofile 1,45.0,0.0
+Run the EMANE event service, monitor what is output on n1 for events +dumped and see the link changes within the CORE GUI.
+emaneeventservice -l 3 eventservice.xml
+The events sent will trigger 4 different states.
+Introduction to using the EMANE event service and eel files to provide events.
+EMANE Demo 1 +for more specifics.
+Open... within the GUIemane-demo-eel.xmlThis demo will go over defining an EMANE event service and eel file to drive +an emane event service.
+On n1 we will use the EMANE event dump utility to listen to events.
+root@n1:/tmp/pycore.46777/n1.conf# emaneevent-dump -i ctrl0
+On the host machine we will create the following files and start the +EMANE event service targeting the control network.
+Warning
+Make sure to set the eventservicedevice to the proper control
+network value
Create eventservice.xml with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE eventservice SYSTEM "file:///usr/share/emane/dtd/eventservice.dtd">
+<eventservice>
+ <param name="eventservicegroup" value="224.1.2.8:45703"/>
+ <param name="eventservicedevice" value="b.9001.f"/>
+ <generator definition="eelgenerator.xml"/>
+</eventservice>
+Next we will create the eelgenerator.xml file. The EEL Generator is actually
+a plugin that loads sentence parsing plugins. The sentence parsing plugins know
+how to convert certain sentences, in this case commeffect, location, velocity,
+orientation, pathloss and antennaprofile sentences, into their corresponding
+emane event equivalents.
These configuration items tell the EEL Generator which sentences to map to +which plugin and whether to issue delta or full updates.
+Create eelgenerator.xml with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE eventgenerator SYSTEM "file:///usr/share/emane/dtd/eventgenerator.dtd">
+<eventgenerator library="eelgenerator">
+ <param name="inputfile" value="scenario.eel"/>
+ <paramlist name="loader">
+ <item value="commeffect:eelloadercommeffect:delta"/>
+ <item value="location,velocity,orientation:eelloaderlocation:delta"/>
+ <item value="pathloss:eelloaderpathloss:delta"/>
+ <item value="antennaprofile:eelloaderantennaprofile:delta"/>
+ </paramlist>
+</eventgenerator>
+Finally, create scenario.eel with the following contents.
0.0 nem:1 pathloss nem:2,90.0
+0.0 nem:2 pathloss nem:1,90.0
+0.0 nem:1 location gps 40.031075,-74.523518,3.000000
+0.0 nem:2 location gps 40.031165,-74.523412,3.000000
+Start the EMANE event service using the files created above.
+emaneeventservice eventservice.xml -l 3
+If we go back to look at our original terminal we will see the events logged +out to the terminal.
+root@n1:/tmp/pycore.46777/n1.conf# emaneevent-dump -i ctrl0
+[1601858142.917224] nem: 0 event: 100 len: 66 seq: 1 [Location]
+ UUID: 0af267be-17d3-4103-9f76-6f697e13bcec
+ (1, {'latitude': 40.031075, 'altitude': 3.0, 'longitude': -74.823518})
+ (2, {'latitude': 40.031165, 'altitude': 3.0, 'longitude': -74.523412})
+[1601858142.917466] nem: 1 event: 101 len: 14 seq: 2 [Pathloss]
+ UUID: 0af267be-17d3-4103-9f76-6f697e13bcec
+ (2, {'forward': 90.0, 'reverse': 90.0})
+[1601858142.917889] nem: 2 event: 101 len: 14 seq: 3 [Pathloss]
+ UUID: 0af267be-17d3-4103-9f76-6f697e13bcec
+ (1, {'forward': 90.0, 'reverse': 90.0})
+Introduction to the XML files generated by CORE used to drive EMANE for +a given node.
+EMANE Demo 0 +may provide more helpful details.
+Open... within the GUIemane-demo-files.xmlWe will take a look at the files generated in the example demo provided. In this +case we are running the RF Pipe model.
+| Name | +Description | +
|---|---|
| \ |
+configuration file for the emulator instances | +
| \ |
+configuration for creating a NEM | +
| \ |
+configuration for defining a NEMs MAC layer | +
| \ |
+configuration for defining a NEMs PHY layer | +
| \ |
+configuration when a virtual transport is being used | +
| \ |
+configuration when a raw transport is being used | +
Below are the files within n1 after starting the demo session.
+root@n1:/tmp/pycore.46777/n1.conf# ls
+eth0-mac.xml eth0-trans-virtual.xml n1-platform.xml var.log
+eth0-nem.xml ipforward.sh quaggaboot.sh var.run
+eth0-phy.xml n1-emane.log usr.local.etc.quagga var.run.quagga
+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.
root@n1:/tmp/pycore.46777/n1.conf# cat n1-platform.xml
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE platform SYSTEM "file:///usr/share/emane/dtd/platform.dtd">
+<platform>
+ <param name="antennaprofilemanifesturi" value=""/>
+ <param name="controlportendpoint" value="0.0.0.0:47000"/>
+ <param name="eventservicedevice" value="ctrl0"/>
+ <param name="eventservicegroup" value="224.1.2.8:45703"/>
+ <param name="eventservicettl" value="1"/>
+ <param name="otamanagerchannelenable" value="1"/>
+ <param name="otamanagerdevice" value="ctrl0"/>
+ <param name="otamanagergroup" value="224.1.2.8:45702"/>
+ <param name="otamanagerloopback" value="0"/>
+ <param name="otamanagermtu" value="0"/>
+ <param name="otamanagerpartcheckthreshold" value="2"/>
+ <param name="otamanagerparttimeoutthreshold" value="5"/>
+ <param name="otamanagerttl" value="1"/>
+ <param name="stats.event.maxeventcountrows" value="0"/>
+ <param name="stats.ota.maxeventcountrows" value="0"/>
+ <param name="stats.ota.maxpacketcountrows" value="0"/>
+ <nem id="1" name="tap1.0.f" definition="eth0-nem.xml">
+ <transport definition="eth0-trans-virtual.xml">
+ <param name="device" value="eth0"/>
+ </transport>
+ </nem>
+</platform>
+The nem definition will contain reference to the transport, mac, and phy xml +definitions being used for a given nem.
+root@n1:/tmp/pycore.46777/n1.conf# cat eth0-nem.xml
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE nem SYSTEM "file:///usr/share/emane/dtd/nem.dtd">
+<nem name="emane_rfpipe NEM">
+ <transport definition="eth0-trans-virtual.xml"/>
+ <mac definition="eth0-mac.xml"/>
+ <phy definition="eth0-phy.xml"/>
+</nem>
+MAC layer configuration settings would be found in this file. CORE will write +out all values, even if the value is a default value.
+root@n1:/tmp/pycore.46777/n1.conf# cat eth0-mac.xml
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE mac SYSTEM "file:///usr/share/emane/dtd/mac.dtd">
+<mac name="emane_rfpipe MAC" library="rfpipemaclayer">
+ <param name="datarate" value="1000000"/>
+ <param name="delay" value="0.000000"/>
+ <param name="enablepromiscuousmode" value="0"/>
+ <param name="flowcontrolenable" value="0"/>
+ <param name="flowcontroltokens" value="10"/>
+ <param name="jitter" value="0.000000"/>
+ <param name="neighbormetricdeletetime" value="60.000000"/>
+ <param name="pcrcurveuri" value="/usr/share/emane/xml/models/mac/rfpipe/rfpipepcr.xml"/>
+ <param name="radiometricenable" value="0"/>
+ <param name="radiometricreportinterval" value="1.000000"/>
+</mac>
+PHY layer configuration settings would be found in this file. CORE will write +out all values, even if the value is a default value.
+root@n1:/tmp/pycore.46777/n1.conf# cat eth0-phy.xml
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE phy SYSTEM "file:///usr/share/emane/dtd/phy.dtd">
+<phy name="emane_rfpipe PHY">
+ <param name="bandwidth" value="1000000"/>
+ <param name="fading.model" value="none"/>
+ <param name="fading.nakagami.distance0" value="100.000000"/>
+ <param name="fading.nakagami.distance1" value="250.000000"/>
+ <param name="fading.nakagami.m0" value="0.750000"/>
+ <param name="fading.nakagami.m1" value="1.000000"/>
+ <param name="fading.nakagami.m2" value="200.000000"/>
+ <param name="fixedantennagain" value="0.000000"/>
+ <param name="fixedantennagainenable" value="1"/>
+ <param name="frequency" value="2347000000"/>
+ <param name="frequencyofinterest" value="2347000000"/>
+ <param name="noisebinsize" value="20"/>
+ <param name="noisemaxclampenable" value="0"/>
+ <param name="noisemaxmessagepropagation" value="200000"/>
+ <param name="noisemaxsegmentduration" value="1000000"/>
+ <param name="noisemaxsegmentoffset" value="300000"/>
+ <param name="noisemode" value="none"/>
+ <param name="propagationmodel" value="2ray"/>
+ <param name="subid" value="1"/>
+ <param name="systemnoisefigure" value="4.000000"/>
+ <param name="timesyncthreshold" value="10000"/>
+ <param name="txpower" value="0.000000"/>
+</phy>
+root@n1:/tmp/pycore.46777/n1.conf# cat eth0-trans-virtual.xml
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE transport SYSTEM "file:///usr/share/emane/dtd/transport.dtd">
+<transport name="Virtual Transport" library="transvirtual">
+ <param name="bitrate" value="0"/>
+ <param name="devicepath" value="/dev/net/tun"/>
+</transport>
+Introduction to integrating gpsd in CORE with EMANE.
+EMANE Demo 0 +may provide more helpful details.
+Warning
+Requires installation of gpsd
+Open... within the GUIemane-demo-gpsd.xmlThis section will cover how to run a gpsd location agent within EMANE, that will +write out locations to a pseudo terminal file. That file can be read in by the +gpsd server and make EMANE location events available to gpsd clients.
+First create an eventdaemon.xml file on n1 with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE eventdaemon SYSTEM "file:///usr/share/emane/dtd/eventdaemon.dtd">
+<eventdaemon nemid="1">
+ <param name="eventservicegroup" value="224.1.2.8:45703"/>
+ <param name="eventservicedevice" value="ctrl0"/>
+ <agent definition="gpsdlocationagent.xml"/>
+</eventdaemon>
+Then create the gpsdlocationagent.xml file on n1 with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE eventagent SYSTEM "file:///usr/share/emane/dtd/eventagent.dtd">
+<eventagent library="gpsdlocationagent">
+ <param name="pseudoterminalfile" value="gps.pty"/>
+</eventagent>
+Start the EMANE event agent. This will facilitate feeding location events +out to a pseudo terminal file defined above.
+emaneeventd eventdaemon.xml -r -d -l 3 -f emaneeventd.log
+Start gpsd, reading in the pseudo terminal file.
+gpsd -G -n -b $(cat gps.pty)
+EEL Events will be played out from the actual host machine over the designated +control network interface. Create the following files in the same directory +somewhere on your host.
+Note
+Make sure the below eventservicedevice matches the control network +device being used on the host for EMANE
+Create eventservice.xml on the host machine with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE eventservice SYSTEM "file:///usr/share/emane/dtd/eventservice.dtd">
+<eventservice>
+ <param name="eventservicegroup" value="224.1.2.8:45703"/>
+ <param name="eventservicedevice" value="b.9001.1"/>
+ <generator definition="eelgenerator.xml"/>
+</eventservice>
+Create eelgenerator.xml on the host machine with the following contents.
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE eventgenerator SYSTEM "file:///usr/share/emane/dtd/eventgenerator.dtd">
+<eventgenerator library="eelgenerator">
+ <param name="inputfile" value="scenario.eel"/>
+ <paramlist name="loader">
+ <item value="commeffect:eelloadercommeffect:delta"/>
+ <item value="location,velocity,orientation:eelloaderlocation:delta"/>
+ <item value="pathloss:eelloaderpathloss:delta"/>
+ <item value="antennaprofile:eelloaderantennaprofile:delta"/>
+ </paramlist>
+</eventgenerator>
+Create scenario.eel file with the following contents.
0.0 nem:1 location gps 40.031075,-74.523518,3.000000
+0.0 nem:2 location gps 40.031165,-74.523412,3.000000
+Start the EEL event service, which will send the events defined in the file above +over the control network to all EMANE nodes. These location events will be received +and provided to gpsd. This allows gpsd client to connect to and get gps locations.
+emaneeventservice eventservice.xml -l 3
+Introduction to using the precomputed propagation model.
+EMANE Demo 1 +for more specifics.
+Open... within the GUIemane-demo-precomputed.xmlThis demo is using the RF Pipe model with the propagation model set to +precomputed.
+Due to using precomputed and having not sent any pathloss events, the nodes +cannot ping each other yet.
+Open a terminal on n1.
+root@n1:/tmp/pycore.46777/n1.conf# ping 10.0.0.2
+connect: Network is unreachable
+You can leverage emanesh to investigate why packets are being dropped.
root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy BroadcastPacketDropTable0 UnicastPacketDropTable0
+nem 1 phy BroadcastPacketDropTable0
+| NEM | Out-of-Band | Rx Sensitivity | Propagation Model | Gain Location | Gain Horizon | Gain Profile | Not FOI | Spectrum Clamp | Fade Location | Fade Algorithm | Fade Select |
+| 2 | 0 | 0 | 169 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
+
+nem 1 phy UnicastPacketDropTable0
+| NEM | Out-of-Band | Rx Sensitivity | Propagation Model | Gain Location | Gain Horizon | Gain Profile | Not FOI | Spectrum Clamp | Fade Location | Fade Algorithm | Fade Select |
+In the example above we can see that the reason packets are being dropped is due to +the propogation model and that is because we have not issued any pathloss events. +You can run another command to validate if you have received any pathloss events.
+root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable
+nem 1 phy PathlossEventInfoTable
+| NEM | Forward Pathloss | Reverse Pathloss |
+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
+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.
+root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable
+nem 1 phy PathlossEventInfoTable
+| NEM | Forward Pathloss | Reverse Pathloss |
+| 2 | 90.0 | 90.0
+You should also now be able to ping n1 from n2.
+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.
+64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=3.06 ms
+64 bytes from 10.0.0.2: icmp_seq=2 ttl=64 time=2.12 ms
+64 bytes from 10.0.0.2: icmp_seq=3 ttl=64 time=1.99 ms
+
+--- 10.0.0.2 ping statistics ---
+3 packets transmitted, 3 received, 0% packet loss, time 2001ms
+rtt min/avg/max/mdev = 1.991/2.393/3.062/0.479 ms
+gRPC is a client/server API for interfacing with CORE
+and used by the python GUI for driving all functionality. It is dependent
+on having a running core-daemon instance to be leveraged.
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 +some functionality to try and help make things easier.
+A python client wrapper is provided at +CoreGrpcClient +to help provide some conveniences when using the API.
+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. +You can enable and properly account for this issue when needed.
+Proto files are used to define the API and protobuf messages that are used for +interfaces with this API.
+They can be found +here +to see the specifics of +what is going on and response message values that would be returned.
+When creating nodes of type NodeType.DEFAULT these are the default models
+and the services they map to.
There is an interface helper class that can be leveraged for convenience
+when creating interface data for nodes. Alternatively one can manually create
+a core.api.grpc.wrappers.Interface class instead with appropriate information.
Manually creating gRPC client interface:
+from core.api.grpc.wrappers import Interface
+
+# id is optional and will set to the next available id
+# name is optional and will default to eth<id>
+# mac is optional and will result in a randomly generated mac
+iface = Interface(
+ id=0,
+ name="eth0",
+ ip4="10.0.0.1",
+ ip4_mask=24,
+ ip6="2001::",
+ ip6_mask=64,
+)
+Leveraging the interface helper class:
+from core.api.grpc import client
+
+iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64")
+# node_id is used to get an ip4/ip6 address indexed from within the above prefixes
+# iface_id is required and used exactly for that
+# name is optional and would default to eth<id>
+# mac is optional and will result in a randomly generated mac
+iface_data = iface_helper.create_iface(
+ node_id=1, iface_id=0, name="eth0", mac="00:00:00:00:aa:00"
+)
+Various events that can occur within a session can be listened to.
+Event types:
+from core.api.grpc import client
+from core.api.grpc.wrappers import EventType
+
+
+def event_listener(event):
+ print(event)
+
+
+# create grpc client and connect
+core = client.CoreGrpcClient()
+core.connect()
+
+# add session
+session = core.create_session()
+
+# provide no events to listen to all events
+core.events(session.id, event_listener)
+
+# provide events to listen to specific events
+core.events(session.id, event_listener, [EventType.NODE])
+Links can be configured at the time of creation or during runtime.
+Currently supported configuration options:
+from core.api.grpc import client
+from core.api.grpc.wrappers import LinkOptions, Position
+
+# interface helper
+iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64")
+
+# create grpc client and connect
+core = client.CoreGrpcClient()
+core.connect()
+
+# add session
+session = core.create_session()
+
+# create nodes
+position = Position(x=100, y=100)
+node1 = session.add_node(1, position=position)
+position = Position(x=300, y=100)
+node2 = session.add_node(2, position=position)
+
+# configuring when creating a link
+options = LinkOptions(
+ bandwidth=54_000_000,
+ delay=5000,
+ dup=5,
+ loss=5.5,
+ jitter=0,
+)
+iface1 = iface_helper.create_iface(node1.id, 0)
+iface2 = iface_helper.create_iface(node2.id, 0)
+link = session.add_link(node1=node1, node2=node2, iface1=iface1, iface2=iface2)
+
+# configuring during runtime
+link.options.loss = 10.0
+core.edit_link(session.id, link)
+# required imports
+from core.api.grpc import client
+from core.api.grpc.wrappers import Position
+
+# interface helper
+iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64")
+
+# create grpc client and connect
+core = client.CoreGrpcClient()
+core.connect()
+
+# add session
+session = core.create_session()
+
+# create nodes
+position = Position(x=100, y=100)
+node1 = session.add_node(1, position=position)
+position = Position(x=300, y=100)
+node2 = session.add_node(2, position=position)
+
+# create link
+iface1 = iface_helper.create_iface(node1.id, 0)
+iface2 = iface_helper.create_iface(node2.id, 0)
+session.add_link(node1=node1, node2=node2, iface1=iface1, iface2=iface2)
+
+# start session
+core.start_session(session)
+# required imports
+from core.api.grpc import client
+from core.api.grpc.wrappers import NodeType, Position
+
+# interface helper
+iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64")
+
+# create grpc client and connect
+core = client.CoreGrpcClient()
+core.connect()
+
+# add session
+session = core.create_session()
+
+# create nodes
+position = Position(x=200, y=200)
+switch = session.add_node(1, _type=NodeType.SWITCH, position=position)
+position = Position(x=100, y=100)
+node1 = session.add_node(2, position=position)
+position = Position(x=300, y=100)
+node2 = session.add_node(3, position=position)
+
+# create links
+iface1 = iface_helper.create_iface(node1.id, 0)
+session.add_link(node1=node1, node2=switch, iface1=iface1)
+iface1 = iface_helper.create_iface(node2.id, 0)
+session.add_link(node1=node2, node2=switch, iface1=iface1)
+
+# start session
+core.start_session(session)
+# required imports
+from core.api.grpc import client
+from core.api.grpc.wrappers import NodeType, Position
+
+# interface helper
+iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64")
+
+# create grpc client and connect
+core = client.CoreGrpcClient()
+core.connect()
+
+# add session
+session = core.create_session()
+
+# create nodes
+position = Position(x=200, y=200)
+wlan = session.add_node(1, _type=NodeType.WIRELESS_LAN, position=position)
+position = Position(x=100, y=100)
+node1 = session.add_node(2, model="mdr", position=position)
+position = Position(x=300, y=100)
+node2 = session.add_node(3, model="mdr", position=position)
+
+# create links
+iface1 = iface_helper.create_iface(node1.id, 0)
+session.add_link(node1=node1, node2=wlan, iface1=iface1)
+iface1 = iface_helper.create_iface(node2.id, 0)
+session.add_link(node1=node2, node2=wlan, iface1=iface1)
+
+# set wlan config using a dict mapping currently
+# support values as strings
+wlan.set_wlan(
+ {
+ "range": "280",
+ "bandwidth": "55000000",
+ "delay": "6000",
+ "jitter": "5",
+ "error": "5",
+ }
+)
+
+# start session
+core.start_session(session)
+For EMANE you can import and use one of the existing models and +use its name for configuration.
+Current models:
+Their configurations options are driven dynamically from parsed EMANE manifest files +from the installed version of EMANE.
+Options and their purpose can be found at the EMANE Wiki.
+If configuring EMANE global settings or model mac/phy specific settings, any value not provided +will use the defaults. When no configuration is used, the defaults are used.
+# required imports
+from core.api.grpc import client
+from core.api.grpc.wrappers import NodeType, Position
+from core.emane.models.ieee80211abg import EmaneIeee80211abgModel
+
+# interface helper
+iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64")
+
+# create grpc client and connect
+core = client.CoreGrpcClient()
+core.connect()
+
+# add session
+session = core.create_session()
+
+# create nodes
+position = Position(x=200, y=200)
+emane = session.add_node(
+ 1, _type=NodeType.EMANE, position=position, emane=EmaneIeee80211abgModel.name
+)
+position = Position(x=100, y=100)
+node1 = session.add_node(2, model="mdr", position=position)
+position = Position(x=300, y=100)
+node2 = session.add_node(3, model="mdr", position=position)
+
+# create links
+iface1 = iface_helper.create_iface(node1.id, 0)
+session.add_link(node1=node1, node2=emane, iface1=iface1)
+iface1 = iface_helper.create_iface(node2.id, 0)
+session.add_link(node1=node2, node2=emane, iface1=iface1)
+
+# setting emane specific emane model configuration
+emane.set_emane_model(EmaneIeee80211abgModel.name, {
+ "eventservicettl": "2",
+ "unicastrate": "3",
+})
+
+# start session
+core.start_session(session)
+EMANE Model Configuration:
+# emane network specific config, set on an emane node
+# this setting applies to all nodes connected
+emane.set_emane_model(EmaneIeee80211abgModel.name, {"unicastrate": "3"})
+
+# node specific config for an individual node connected to an emane network
+node.set_emane_model(EmaneIeee80211abgModel.name, {"unicastrate": "3"})
+
+# node interface specific config for an individual node connected to an emane network
+node.set_emane_model(EmaneIeee80211abgModel.name, {"unicastrate": "3"}, iface_id=0)
+Services help generate and run bash scripts on nodes for a given purpose.
+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.
+The following features can be configured for a service:
+Editing service properties:
+# configure a service, for a node, for a given session
+node.service_configs[service_name] = NodeServiceData(
+ configs=["file1.sh", "file2.sh"],
+ directories=["/etc/node"],
+ startup=["bash file1.sh"],
+ validate=[],
+ shutdown=[],
+)
+When editing a service file, it must be the name of config
+file that the service will generate.
Editing a service file:
+# to edit the contents of a generated file you can specify
+# the service, the file name, and its contents
+file_configs = node.service_file_configs.setdefault(service_name, {})
+file_configs[file_name] = "echo hello world"
+File versions of the network examples can be found +here. +These examples will create a session using the gRPC API when the core-daemon is running.
+You can then switch to and attach to these sessions using either of the CORE GUIs.
+ + + + + + +
The GUI is used to draw nodes and network devices on a canvas, linking them +together to create an emulated network session.
+After pressing the start button, CORE will proceed through these phases, +staying in the runtime phase. After the session is stopped, CORE will +proceed to the data collection phase before tearing down the emulated +state.
+CORE can be customized to perform any action at each state. See the +Hooks... entry on the Session Menu for details about +when these session states are reached.
+Beyond installing CORE, you must have the CORE daemon running. This is done +on the command line with either systemd or sysv.
+# systemd service
+sudo systemctl daemon-reload
+sudo systemctl start core-daemon
+
+# direct invocation
+sudo core-daemon
+The GUI will create a directory in your home directory on first run called +~/.coregui. This directory will help layout various files that the GUI may use.
+The CORE GUI has two primary modes of operation, Edit and Execute +modes. Running the GUI, by typing core-gui with no options, starts in +Edit mode. Nodes are drawn on a blank canvas using the toolbar on the left +and configured from right-click menus or by double-clicking them. The GUI +does not need to be run as root.
+Once editing is complete, pressing the green Start button instantiates +the topology and enters Execute mode. In execute mode, +the user can interact with the running emulated machines by double-clicking or +right-clicking on them. The editing toolbar disappears and is replaced by an +execute toolbar, which provides tools while running the emulation. Pressing +the red Stop button will destroy the running emulation and return CORE +to Edit mode.
+Once the emulation is running, the GUI can be closed, and a prompt will appear +asking if the emulation should be terminated. The emulation may be left +running and the GUI can reconnect to an existing session at a later time.
+The GUI can be run as a normal user on Linux.
+The GUI currently provides the following options on startup.
+usage: core-gui [-h] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-p]
+ [-s SESSION] [--create-dir]
+
+CORE Python GUI
+
+optional arguments:
+ -h, --help show this help message and exit
+ -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+ logging level
+ -p, --proxy enable proxy
+ -s SESSION, --session SESSION
+ session id to join
+ --create-dir create gui directory and exit
+The toolbar is a row of buttons that runs vertically along the left side of the +CORE GUI window. The toolbar changes depending on the mode of operation.
+When CORE is in Edit mode (the default), the vertical Editing Toolbar exists on +the left side of the CORE window. Below are brief descriptions for each toolbar +item, starting from the top. Most of the tools are grouped into related +sub-menus, which appear when you click on their group icon.
+| Icon | +Name | +Description | +
|---|---|---|
 |
+Selection Tool | +Tool for selecting, moving, configuring nodes. | +
 |
+Start Button | +Starts Execute mode, instantiates the emulation. | +
 |
+Link | +Allows network links to be drawn between two nodes by clicking and dragging the mouse. | +
These nodes will create a new node container and run associated services.
+| Icon | +Name | +Description | +
|---|---|---|
 |
+Router | +Runs Quagga OSPFv2 and OSPFv3 routing to forward packets. | +
 |
+Host | +Emulated server machine having a default route, runs SSH server. | +
 |
+PC | +Basic emulated machine having a default route, runs no processes by default. | +
 |
+MDR | +Runs Quagga OSPFv3 MDR routing for MANET-optimized routing. | +
|
+PRouter | +Physical router represents a real testbed machine. | +
These nodes are mostly used to create a Linux bridge that serves the +purpose described below.
+| Icon | +Name | +Description | +
|---|---|---|
 |
+Hub | +Ethernet hub forwards incoming packets to every connected node. | +
 |
+Switch | +Ethernet switch intelligently forwards incoming packets to attached hosts using an Ethernet address hash table. | +
 |
+Wireless LAN | +When routers are connected to this WLAN node, they join a wireless network and an antenna is drawn instead of a connecting line; the WLAN node typically controls connectivity between attached wireless nodes based on the distance between them. | +
 |
+RJ45 | +RJ45 Physical Interface Tool, emulated nodes can be linked to real physical interfaces; using this tool, real networks and devices can be physically connected to the live-running emulation. | +
 |
+Tunnel | +Tool allows connecting together more than one CORE emulation using GRE tunnels. | +
| Icon | +Name | +Description | +
|---|---|---|
 |
+Marker | +For drawing marks on the canvas. | +
 |
+Oval | +For drawing circles on the canvas that appear in the background. | +
 |
+Rectangle | +For drawing rectangles on the canvas that appear in the background. | +
 |
+Text | +For placing text captions on the canvas. | +
When the Start button is pressed, CORE switches to Execute mode, and the Edit +toolbar on the left of the CORE window is replaced with the Execution toolbar +Below are the items on this toolbar, starting from the top.
+| Icon | +Name | +Description | +
|---|---|---|
 |
+Stop Button | +Stops Execute mode, terminates the emulation, returns CORE to edit mode. | +
|
+Selection Tool | +In Execute mode, the Selection Tool can be used for moving nodes around the canvas, and double-clicking on a node will open a shell window for that node; right-clicking on a node invokes a pop-up menu of run-time options for that node. | +
|
+Marker | +For drawing freehand lines on the canvas, useful during demonstrations; markings are not saved. | +
 |
+Run Tool | +This tool allows easily running a command on all or a subset of all nodes. A list box allows selecting any of the nodes. A text entry box allows entering any command. The command should return immediately, otherwise the display will block awaiting response. The ping command, for example, with no parameters, is not a good idea. The result of each command is displayed in a results box. The first occurrence of the special text "NODE" will be replaced with the node name. The command will not be attempted to run on nodes that are not routers, PCs, or hosts, even if they are selected. | +
The menubar runs along the top of the CORE GUI window and provides access to a +variety of features. Some of the menus are detachable, such as the Widgets +menu, by clicking the dashed line at the top.
+The File menu contains options for saving and opening saved sessions.
+| Option | +Description | +
|---|---|
| New Session | +This starts a new session with an empty canvas. | +
| Save | +Saves the current topology. If you have not yet specified a file name, the Save As dialog box is invoked. | +
| Save As | +Invokes the Save As dialog box for selecting a new .xml file for saving the current configuration in the XML file. | +
| Open | +Invokes the File Open dialog box for selecting a new XML file to open. | +
| Recently used files | +Above the Quit menu command is a list of recently use files, if any have been opened. You can clear this list in the Preferences dialog box. You can specify the number of files to keep in this list from the Preferences dialog. Click on one of the file names listed to open that configuration file. | +
| Execute Python Script | +Invokes a File Open dialog box for selecting a Python script to run and automatically connect to. After a selection is made, a Python Script Options dialog box is invoked to allow for command-line options to be added. The Python script must create a new CORE Session and add this session to the daemon's list of sessions in order for this to work. | +
| Quit | +The Quit command should be used to exit the CORE GUI. CORE may prompt for termination if you are currently in Execute mode. Preferences and the recently-used files list are saved. | +
| Option | +Description | +
|---|---|
| Preferences | +Invokes the Preferences dialog box. | +
| Custom Nodes | +Custom node creation dialog box. | +
| Undo | +(Disabled) Attempts to undo the last edit in edit mode. | +
| Redo | +(Disabled) Attempts to redo an edit that has been undone. | +
| Cut, Copy, Paste, Delete | +Used to cut, copy, paste, and delete a selection. When nodes are pasted, their node numbers are automatically incremented, and existing links are preserved with new IP addresses assigned. Services and their customizations are copied to the new node, but care should be taken as node IP addresses have changed with possibly old addresses remaining in any custom service configurations. Annotations may also be copied and pasted. | +
The canvas menu provides commands related to the editing canvas.
+| Option | +Description | +
|---|---|
| Size/scale | +Invokes a Canvas Size and Scale dialog that allows configuring the canvas size, scale, and geographic reference point. The size controls allow changing the width and height of the current canvas, in pixels or meters. The scale allows specifying how many meters are equivalent to 100 pixels. The reference point controls specify the latitude, longitude, and altitude reference point used to convert between geographic and Cartesian coordinate systems. By clicking the Save as default option, all new canvases will be created with these properties. The default canvas size can also be changed in the Preferences dialog box. | +
| Wallpaper | +Used for setting the canvas background image. | +
The View menu features items for toggling on and off their display on the canvas.
+| Option | +Description | +
|---|---|
| Interface Names | +Display interface names on links. | +
| IPv4 Addresses | +Display IPv4 addresses on links. | +
| IPv6 Addresses | +Display IPv6 addresses on links. | +
| Node Labels | +Display node names. | +
| Link Labels | +Display link labels. | +
| Annotations | +Display annotations. | +
| Canvas Grid | +Display the canvas grid. | +
The tools menu lists different utility functions.
+| Option | +Description | +
|---|---|
| Find | +Display find dialog used for highlighting a node on the canvas. | +
| Auto Grid | +Automatically layout nodes in a grid. | +
| IP addresses | +Invokes the IP Addresses dialog box for configuring which IPv4/IPv6 prefixes are used when automatically addressing new interfaces. | +
| MAC addresses | +Invokes the MAC Addresses dialog box for configuring the starting number used as the lowest byte when generating each interface MAC address. This value should be changed when tunneling between CORE emulations to prevent MAC address conflicts. | +
Widgets are GUI elements that allow interaction with a running emulation. +Widgets typically automate the running of commands on emulated nodes to report +status information of some type and display this on screen.
+These Widgets are those available from the main Widgets menu. More than one +of these Widgets may be run concurrently. An event loop fires once every second +that the emulation is running. If one of these Widgets is enabled, its periodic +routine will be invoked at this time. Each Widget may have a configuration +dialog box which is also accessible from the Widgets menu.
+Here are some standard widgets:
+These Widgets are available from the Observer Widgets submenu of the +Widgets menu, and from the Widgets Tool on the toolbar. Only one Observer Widget may +be used at a time. Mouse over a node while the session is running to pop up +an informational display about that node.
+Available Observer Widgets include IPv4 and IPv6 routing tables, socket +information, list of running processes, and OSPFv2/v3 neighbor information.
+Observer Widgets may be edited by the user and rearranged. Choosing +Widgets->Observer Widgets->Edit Observers from the Observer Widget menu will +invoke the Observer Widgets dialog. A list of Observer Widgets is displayed along +with up and down arrows for rearranging the list. Controls are available for +renaming each widget, for changing the command that is run during mouse over, and +for adding and deleting items from the list. Note that specified commands should +return immediately to avoid delays in the GUI display. Changes are saved to a +config.yaml file in the CORE configuration directory.
+The Session Menu has entries for starting, stopping, and managing sessions, +in addition to global options such as node types, comments, hooks, servers, +and options.
+| Option | +Description | +
|---|---|
| Sessions | +Invokes the CORE Sessions dialog box containing a list of active CORE sessions in the daemon. Basic session information such as name, node count, start time, and a thumbnail are displayed. This dialog allows connecting to different sessions, shutting them down, or starting a new session. | +
| Servers | +Invokes the CORE emulation servers dialog for configuring. | +
| Options | +Presents per-session options, such as the IPv4 prefix to be used, if any, for a control network the ability to preserve the session directory; and an on/off switch for SDT3D support. | +
| Hooks | +Invokes the CORE Session Hooks window where scripts may be configured for a particular session state. The session states are defined in the table below. The top of the window has a list of configured hooks, and buttons on the bottom left allow adding, editing, and removing hook scripts. The new or edit button will open a hook script editing window. A hook script is a shell script invoked on the host (not within a virtual node). | +
| State | +Description | +
|---|---|
| Definition | +Used by the GUI to tell the backend to clear any state. | +
| Configuration | +When the user presses the Start button, node, link, and other configuration data is sent to the backend. This state is also reached when the user customizes a service. | +
| Instantiation | +After configuration data has been sent, just before the nodes are created. | +
| Runtime | +All nodes and networks have been built and are running. (This is the same state at which the previously-named global experiment script was run.) | +
| Datacollect | +The user has pressed the Stop button, but before services have been stopped and nodes have been shut down. This is a good time to collect log files and other data from the nodes. | +
| Shutdown | +All nodes and networks have been shut down and destroyed. | +
| Option | +Description | +
|---|---|
| CORE Github (www) | +Link to the CORE GitHub page. | +
| CORE Documentation (www) | +Lnk to the CORE Documentation page. | +
| About | +Invokes the About dialog box for viewing version information. | +
Wired networks are created using the Link Tool to draw a link between two +nodes. This automatically draws a red line representing an Ethernet link and +creates new interfaces on network-layer nodes.
+Double-click on the link to invoke the link configuration dialog box. Here +you can change the Bandwidth, Delay, Loss, and Duplicate +rate parameters for that link. You can also modify the color and width of the +link, affecting its display.
+Link-layer nodes are provided for modeling wired networks. These do not create +a separate network stack when instantiated, but are implemented using Linux bridging. +These are the hub, switch, and wireless LAN nodes. The hub copies each packet from +the incoming link to every connected link, while the switch behaves more like an +Ethernet switch and keeps track of the Ethernet address of the connected peer, +forwarding unicast traffic only to the appropriate ports.
+The wireless LAN (WLAN) is covered in the next section.
+Wireless networks allow moving nodes around to impact the connectivity between them. Connections between a +pair of nodes is stronger when the nodes are closer while connection is weaker when the nodes are further away. +CORE offers several levels of wireless emulation fidelity, depending on modeling needs and available +hardware.
+| Model | +Type | +Supported Platform(s) | +Fidelity | +Description | +
|---|---|---|---|---|
| WLAN | +On/Off | +Linux | +Low | +Ethernet bridging with nftables | +
| Wireless | +On/Off | +Linux | +Medium | +Ethernet bridging with nftables | +
| EMANE | +RF | +Linux | +High | +TAP device connected to EMANE emulator with pluggable MAC and PHY radio types | +
To quickly build a wireless network, you can first place several router nodes +onto the canvas. If you have the +Quagga MDR software installed, it is +recommended that you use the mdr node type for reduced routing overhead. Next +choose the WLAN from the Link-layer nodes submenu. First set the +desired WLAN parameters by double-clicking the cloud icon. Then you can link +all selected right-clicking on the WLAN and choosing Link to Selected.
+Linking a router to the WLAN causes a small antenna to appear, but no red link +line is drawn. Routers can have multiple wireless links and both wireless and +wired links (however, you will need to manually configure route +redistribution.) The mdr node type will generate a routing configuration that +enables OSPFv3 with MANET extensions. This is a Boeing-developed extension to +Quagga's OSPFv3 that reduces flooding overhead and optimizes the flooding +procedure for mobile ad-hoc (MANET) networks.
+The default configuration of the WLAN is set to use the basic range model. Having this model +selected causes core-daemon to calculate the distance between nodes based +on screen pixels. A numeric range in screen pixels is set for the wireless +network using the Range slider. When two wireless nodes are within range of +each other, a green line is drawn between them and they are linked. Two +wireless nodes that are farther than the range pixels apart are not linked. +During Execute mode, users may move wireless nodes around by clicking and +dragging them, and wireless links will be dynamically made or broken.
+You can double click a node to bring up a terminal for running shell commands. Within +the terminal you can run anything you like and those commands will be run in context of the node. +For standard CORE nodes, the only thing to keep in mind is that you are using the host file +system and anything you change or do can impact the greater system. By default, your terminal +will open within the nodes home directory for the running session, but it is temporary and +will be removed when the session is stopped.
+You can also launch GUI based applications from within standard CORE nodes, but you need to +enable xhost access to root.
+xhost +local:root
+CORE has a few ways to script mobility.
+| Option | +Description | +
|---|---|
| ns-2 script | +The script specifies either absolute positions or waypoints with a velocity. Locations are given with Cartesian coordinates. | +
| gRPC API | +An external entity can move nodes by leveraging the gRPC API | +
| EMANE events | +See EMANE 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 +editor, or using a tool such as BonnMotion, and associate +the script with one of the wireless +using the WLAN configuration dialog box. Click the ns-2 mobility script... +button, and set the mobility script file field in the resulting ns2script +configuration dialog.
+Here is an example for creating a BonnMotion script for 10 nodes:
+bm -f sample RandomWaypoint -n 10 -d 60 -x 1000 -y 750
+bm NSFile -f sample
+# use the resulting 'sample.ns_movements' file in CORE
+When the Execute mode is started and one of the WLAN nodes has a mobility +script, a mobility script window will appear. This window contains controls for +starting, stopping, and resetting the running time for the mobility script. The +loop checkbox causes the script to play continuously. The resolution text +box contains the number of milliseconds between each timer event; lower values +cause the mobility to appear smoother but consumes greater CPU time.
+The format of an ns-2 mobility script looks like:
+# nodes: 3, max time: 35.000000, max x: 600.00, max y: 600.00
+$node_(2) set X_ 144.0
+$node_(2) set Y_ 240.0
+$node_(2) set Z_ 0.00
+$ns_ at 1.00 "$node_(2) setdest 130.0 280.0 15.0"
+The first three lines set an initial position for node 2. The last line in the +above example causes node 2 to move towards the destination (130, 280) at +speed 15. All units are screen coordinates, with speed in units per second. +The total script time is learned after all nodes have reached their waypoints. +Initially, the time slider in the mobility script dialog will not be +accurate.
+Examples mobility scripts (and their associated topology files) can be found +in the configs/ directory.
+The alerts button is located in the bottom right-hand corner +of the status bar in the CORE GUI. This will change colors to indicate one or +more problems with the running emulation. Clicking on the alerts button will invoke the +alerts dialog.
+The alerts dialog contains a list of alerts received from +the CORE daemon. An alert has a time, severity level, optional node number, +and source. When the alerts button is red, this indicates one or more fatal +exceptions. An alert with a fatal severity level indicates that one or more +of the basic pieces of emulation could not be created, such as failure to +create a bridge or namespace, or the failure to launch EMANE processes for an +EMANE-based network.
+Clicking on an alert displays details for that +exceptio. The exception source is a text string +to help trace where the exception occurred; "service:UserDefined" for example, +would appear for a failed validation command with the UserDefined service.
+A button is available at the bottom of the dialog for clearing the exception +list.
+Several annotation tools are provided for changing the way your topology is +presented. Captions may be added with the Text tool. Ovals and rectangles may +be drawn in the background, helpful for visually grouping nodes together.
+During live demonstrations the marker tool may be helpful for drawing temporary +annotations on the canvas that may be quickly erased. A size and color palette +appears at the bottom of the toolbar when the marker tool is selected. Markings +are only temporary and are not saved in the topology file.
+The basic node icons can be replaced with a custom image of your choice. Icons +appear best when they use the GIF or PNG format with a transparent background. +To change a node's icon, double-click the node to invoke its configuration +dialog and click on the button to the right of the node name that shows the +node's current icon.
+A background image for the canvas may be set using the Wallpaper... option +from the Canvas menu. The image may be centered, tiled, or scaled to fit the +canvas size. An existing terrain, map, or network diagram could be used as a +background, for example, with CORE nodes drawn on top.
+ + + + + + +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.
+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.
+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.
+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:
+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
+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.
+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.
+# 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:
+# from the CORE router node
+ping 10.0.0.2
+And the Linux machine should be able to ping inside the CORE emulation:
+# 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.
+ + + + + + +CORE (Common Open Research Emulator) is a tool for building virtual networks. As an emulator, CORE builds a +representation of a real computer network that runs in real time, as opposed to simulation, where abstract models are +used. The live-running emulation can be connected to physical networks and routers. It provides an environment for +running real applications and protocols, taking advantage of tools provided by the Linux operating system.
+CORE is typically used for network and protocol research, demonstrations, application and platform testing, evaluating +networking scenarios, security studies, and increasing the size of physical test networks.
+Warning
+If Docker is installed, the default iptable rules will block CORE traffic
+CORE currently supports and provides the following installation options, with the package +option being preferred.
+ +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.
+Plan is to support recent Ubuntu and CentOS LTS releases.
+Verified:
+The following is a list of files that would be installed after installation.
+<prefix>/bin/{vcmd, vnode}/opt/core/venvpython3 -c "import core; print(core.__file__)"/opt/core/venv/bin/usr/local/bin/etc/core/{core.conf, logging.conf}<repo>/../ospf-mdrThe following python scripts are provided.
+| Name | +Description | +
|---|---|
| core-cleanup | +tool to help removed lingering core created containers, bridges, directories | +
| core-cli | +tool to query, open xml files, and send commands using gRPC | +
| core-daemon | +runs the backed core server providing a gRPC API | +
| core-gui | +starts GUI | +
| core-python | +provides a convenience for running the core python virtual environment | +
| core-route-monitor | +tool to help monitor traffic across nodes and feed that to SDT | +
| core-service-update | +tool to update automate modifying a legacy service to match current naming | +
Please make sure to uninstall any previous installations of CORE cleanly +before proceeding to install.
+Clearing out a current install from 7.0.0+, making sure to provide options
+used for install (-l or -p).
cd <CORE_REPO>
+inv uninstall <options>
+Previous install was built from source for CORE release older than 7.0.0:
+cd <CORE_REPO>
+sudo make uninstall
+make clean
+./bootstrap.sh clean
+Installed from previously built packages:
+# centos
+sudo yum remove core
+# ubuntu
+sudo apt remove core
+The below links will take you to sections providing complete examples for installing +CORE and related utilities on fresh installations. Otherwise, a breakdown for installing +different components and the options available are detailed below.
+Starting with 9.0.0 there are pre-built rpm/deb packages. You can retrieve the +rpm/deb package from releases page.
+The built packages will require and install system level dependencies, as well as running +a post install script to install the provided CORE python wheel. A similar uninstall script +is ran when uninstalling and would require the same options as given, during the install.
+Note
+PYTHON defaults to python3 for installs below, CORE requires python3.9+, pip, +tk compatibility for python gui, and venv for virtual environments
+Examples for install:
+# recommended to upgrade to the latest version of pip before installation
+# in python, can help avoid building from source issues
+sudo <python> -m pip install --upgrade pip
+# install vcmd/vnoded, system dependencies,
+# and core python into a venv located at /opt/core/venv
+sudo <yum/apt> install -y ./<package>
+# disable the venv and install to python directly
+sudo NO_VENV=1 <yum/apt> install -y ./<package>
+# change python executable used to install for venv or direct installations
+sudo PYTHON=python3.9 <yum/apt> install -y ./<package>
+# disable venv and change python executable
+sudo NO_VENV=1 PYTHON=python3.9 <yum/apt> install -y ./<package>
+# skip installing the python portion entirely, as you plan to carry this out yourself
+# core python wheel is located at /opt/core/core-<version>-py3-none-any.whl
+sudo NO_PYTHON=1 <yum/apt> install -y ./<package>
+# install python wheel into python of your choosing
+sudo <python> -m pip install /opt/core/core-<version>-py3-none-any.whl
+Example for removal, requires using the same options as install:
+# remove a standard install
+sudo <yum/apt> remove core
+# remove a local install
+sudo NO_VENV=1 <yum/apt> remove core
+# remove install using alternative python
+sudo PYTHON=python3.9 <yum/apt> remove core
+# remove install using alternative python and local install
+sudo NO_VENV=1 PYTHON=python3.9 <yum/apt> remove core
+# remove install and skip python uninstall
+sudo NO_PYTHON=1 <yum/apt> remove core
+You will need to manually install OSPF MDR for routing nodes, since this is not +provided by the package.
+git clone https://github.com/USNavalResearchLaboratory/ospf-mdr.git
+cd ospf-mdr
+./bootstrap.sh
+./configure --disable-doc --enable-user=root --enable-group=root \
+ --with-cflags=-ggdb --sysconfdir=/usr/local/etc/quagga --enable-vtysh \
+ --localstatedir=/var/run/quagga
+make -j$(nproc)
+sudo make install
+When done see Post Install.
+The script based installation will install system level dependencies, python library and +dependencies, as well as dependencies for building CORE.
+The script based install also automatically builds and installs OSPF MDR, used by default +on routing nodes. This can optionally be skipped.
+Installaion will carry out the following steps:
+Note
+Installing locally comes with its own risks, it can result it potential +dependency conflicts with system package manager installed python dependencies
+Note
+Provide a prefix that will be found on path when running as sudo, +if the default prefix /usr/local will not be valid
+The following tools will be leveraged during installation:
+| Tool | +Description | +
|---|---|
| pip | +used to install pipx | +
| pipx | +used to install standalone python tools (invoke, poetry) | +
| invoke | +used to run provided tasks (install, uninstall, reinstall, etc) | +
| poetry | +used to install python virtual environment or building a python wheel | +
First we will need to clone and navigate to the CORE repo.
+# clone CORE repo
+git clone https://github.com/coreemu/core.git
+cd core
+
+# install dependencies to run installation task
+./setup.sh
+# skip installing system packages, due to using python built from source
+NO_SYSTEM=1 ./setup.sh
+
+# run the following or open a new terminal
+source ~/.bashrc
+
+# Ubuntu
+inv install
+# CentOS
+inv install -p /usr
+# optionally skip python system packages
+inv install --no-python
+# optionally skip installing ospf mdr
+inv install --no-ospf
+
+# install command options
+Usage: inv[oke] [--core-opts] install [--options] [other tasks here ...]
+
+Docstring:
+ install core, poetry, scripts, service, and ospf mdr
+
+Options:
+ -d, --dev install development mode
+ -i STRING, --install-type=STRING used to force an install type, can be one of the following (redhat, debian)
+ -l, --local determines if core will install to local system, default is False
+ -n, --no-python avoid installing python system dependencies
+ -o, --[no-]ospf disable ospf installation
+ -p STRING, --prefix=STRING prefix where scripts are installed, default is /usr/local
+ -v, --verbose
+When done see Post Install.
+For unsupported OSs you could attempt to do the following to translate +an installation to your use case.
+<repo>/tasks.py# this will print the commands that would be ran for a given installation
+# type without actually running them, they may help in being used as
+# the basis for translating to your OS
+inv install --dry -v -p <prefix> -i <install type>
+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, +make sure to update and build the Dockerfile with desired software.
+# clone core
+git clone https://github.com/coreemu/core.git
+cd core
+# build image
+sudo docker build -t core -f dockerfiles/Dockerfile.<centos,ubuntu> .
+# start container
+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
+xhost +local:root
+# launch core-gui
+sudo docker exec -it core core-gui
+When done see Post Install.
+Note
+Installing EMANE for the virtual environment is known to work for 1.21+
+The recommended way to install EMANE is using prebuilt packages, otherwise +you can follow their instructions for installing from source. Installation +information can be found here.
+There is an invoke task to help install the EMANE bindings into the CORE virtual +environment, when needed. An example for running the task is below and the version +provided should match the version of the packages installed.
+You will also need to make sure, you are providing the correct python binary where CORE +is being used.
+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.
Examples for building and installing EMANE python bindings for use in CORE:
+# 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
+mkdir protoc
+unzip protoc-3.19.6-linux-x86_64.zip -d protoc
+git clone https://github.com/adjacentlink/emane.git
+cd emane
+git checkout v1.3.3
+./autogen.sh
+PYTHON=/opt/core/venv/bin/python ./configure --prefix=/usr
+cd src/python
+PATH=/opt/protoc/bin:$PATH make
+/opt/core/venv/bin/python -m pip install .
+
+# when your system has protoc 3.19+
+cd <CORE_REPO>
+# example version tag v1.3.3
+# overriding python used to leverage the default virtualenv install
+PYTHON=/opt/core/venv/bin/python inv install-emane -e <version tag>
+# local install that uses whatever python3 refers to
+inv install-emane -e <version tag>
+After installation completes you are now ready to run CORE.
+If you have Docker installed, by default it will change the iptables +forwarding chain to drop packets, which will cause issues for CORE traffic.
+You can temporarily resolve the issue with the following command:
+sudo iptables --policy FORWARD ACCEPT
+Alternatively, you can configure Docker to avoid doing this, but will likely +break normal Docker networking usage. Using the setting below will require +a restart.
+Place the file contents below in /etc/docker/docker.json
+{
+ "iptables": false
+}
+One problem running CORE you may run into, using the virtual environment or locally +can be issues related to your path.
+To add support for your user to run scripts from the virtual environment:
+# can add to ~/.bashrc
+export PATH=$PATH:/opt/core/venv/bin
+This will not solve the path issue when running as sudo, so you can do either +of the following to compensate.
+# run command passing in the right PATH to pickup from the user running the command
+sudo env PATH=$PATH core-daemon
+
+# add an alias to ~/.bashrc or something similar
+alias sudop='sudo env PATH=$PATH'
+# now you can run commands like so
+sudop core-daemon
+The following assumes I have resolved PATH issues and setup the sudop alias.
# in one terminal run the server daemon using the alias above
+sudop core-daemon
+# in another terminal run the gui client
+core-gui
+After installation, the core service is not enabled by default. If you desire to use the +service, run the following commands.
+sudo systemctl enable core-daemon
+sudo systemctl start core-daemon
+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 +own virtual environment located at /opt/core/venv. Both examples below +also assume using ~/Documents as the working directory.
+This section covers step by step commands that can be used to install CORE using +the script based installation path.
+# install system packages
+sudo yum -y update
+sudo yum install -y git sudo wget tzdata unzip libpcap-devel libpcre3-devel \
+ libxml2-devel protobuf-devel unzip uuid-devel tcpdump make epel-release
+sudo yum-builddep -y python3
+
+# install python3.9
+cd ~/Documents
+wget https://www.python.org/ftp/python/3.9.15/Python-3.9.15.tgz
+tar xf Python-3.9.15.tgz
+cd Python-3.9.15
+./configure --enable-optimizations --with-ensurepip=install
+sudo make -j$(nproc) altinstall
+python3.9 -m pip install --upgrade pip
+
+# install core
+cd ~/Documents
+git clone https://github.com/coreemu/core
+cd core
+NO_SYSTEM=1 PYTHON=/usr/local/bin/python3.9 ./setup.sh
+source ~/.bashrc
+PYTHON=python3.9 inv install -p /usr --no-python
+
+# install emane
+cd ~/Documents
+wget -q https://adjacentlink.com/downloads/emane/emane-1.3.3-release-1.el7.x86_64.tar.gz
+tar xf emane-1.3.3-release-1.el7.x86_64.tar.gz
+cd emane-1.3.3-release-1/rpms/el7/x86_64
+sudo yum install -y ./openstatistic*.rpm ./emane*.rpm ./python3-emane_*.rpm
+
+# install emane python bindings into CORE virtual environment
+cd ~/Documents
+wget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip
+mkdir protoc
+unzip protoc-3.19.6-linux-x86_64.zip -d protoc
+git clone https://github.com/adjacentlink/emane.git
+cd emane
+git checkout v1.3.3
+./autogen.sh
+PYTHON=/opt/core/venv/bin/python ./configure --prefix=/usr
+cd src/python
+PATH=~/Documents/protoc/bin:$PATH make
+sudo /opt/core/venv/bin/python -m pip install .
+This section covers step by step commands that can be used to install CORE using +the package based installation path. This will require downloading a package from the release +page, to use during the install CORE step below.
+# install system packages
+sudo yum -y update
+sudo yum install -y git sudo wget tzdata unzip libpcap-devel libpcre3-devel libxml2-devel \
+ protobuf-devel unzip uuid-devel tcpdump automake gawk libreadline-devel libtool \
+ pkg-config make
+sudo yum-builddep -y python3
+
+# install python3.9
+cd ~/Documents
+wget https://www.python.org/ftp/python/3.9.15/Python-3.9.15.tgz
+tar xf Python-3.9.15.tgz
+cd Python-3.9.15
+./configure --enable-optimizations --with-ensurepip=install
+sudo make -j$(nproc) altinstall
+python3.9 -m pip install --upgrade pip
+
+# install core
+cd ~/Documents
+sudo PYTHON=python3.9 yum install -y ./core_*.rpm
+
+# install ospf mdr
+cd ~/Documents
+git clone https://github.com/USNavalResearchLaboratory/ospf-mdr.git
+cd ospf-mdr
+./bootstrap.sh
+./configure --disable-doc --enable-user=root --enable-group=root \
+ --with-cflags=-ggdb --sysconfdir=/usr/local/etc/quagga --enable-vtysh \
+ --localstatedir=/var/run/quagga
+make -j$(nproc)
+sudo make install
+
+# install emane
+cd ~/Documents
+wget -q https://adjacentlink.com/downloads/emane/emane-1.3.3-release-1.el7.x86_64.tar.gz
+tar xf emane-1.3.3-release-1.el7.x86_64.tar.gz
+cd emane-1.3.3-release-1/rpms/el7/x86_64
+sudo yum install -y ./openstatistic*.rpm ./emane*.rpm ./python3-emane_*.rpm
+
+# install emane python bindings into CORE virtual environment
+cd ~/Documents
+wget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip
+mkdir protoc
+unzip protoc-3.19.6-linux-x86_64.zip -d protoc
+git clone https://github.com/adjacentlink/emane.git
+cd emane
+git checkout v1.3.3
+./autogen.sh
+PYTHON=/opt/core/venv/bin/python ./configure --prefix=/usr
+cd src/python
+PATH=~/Documents/protoc/bin:$PATH make
+sudo /opt/core/venv/bin/python -m pip install .
+The CORE virtual environment and related scripts will not be found on your PATH, +so some adjustments needs to be made.
+To add support for your user to run scripts from the virtual environment:
+# can add to ~/.bashrc
+export PATH=$PATH:/opt/core/venv/bin
+This will not solve the path issue when running as sudo, so you can do either +of the following to compensate.
+# run command passing in the right PATH to pickup from the user running the command
+sudo env PATH=$PATH core-daemon
+
+# add an alias to ~/.bashrc or something similar
+alias sudop='sudo env PATH=$PATH'
+# now you can run commands like so
+sudop core-daemon
+Below is a detailed path for installing CORE and related tooling on a fresh +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 +also assume using ~/Documents as the working directory.
+This section covers step by step commands that can be used to install CORE using +the script based installation path.
+# install system packages
+sudo apt-get update -y
+sudo apt-get install -y ca-certificates git sudo wget tzdata libpcap-dev libpcre3-dev \
+ libprotobuf-dev libxml2-dev protobuf-compiler unzip uuid-dev iproute2 iputils-ping \
+ tcpdump
+
+# install core
+cd ~/Documents
+git clone https://github.com/coreemu/core
+cd core
+./setup.sh
+source ~/.bashrc
+inv install
+
+# install emane
+cd ~/Documents
+wget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip
+mkdir protoc
+unzip protoc-3.19.6-linux-x86_64.zip -d protoc
+git clone https://github.com/adjacentlink/emane.git
+cd emane
+./autogen.sh
+./configure --prefix=/usr
+make -j$(nproc)
+sudo make install
+cd src/python
+make clean
+PATH=~/Documents/protoc/bin:$PATH make
+sudo /opt/core/venv/bin/python -m pip install .
+This section covers step by step commands that can be used to install CORE using +the package based installation path. This will require downloading a package from the release +page, to use during the install CORE step below.
+# install system packages
+sudo apt-get update -y
+sudo apt-get install -y ca-certificates python3 python3-tk python3-pip python3-venv \
+ libpcap-dev libpcre3-dev libprotobuf-dev libxml2-dev protobuf-compiler unzip \
+ uuid-dev automake gawk git wget libreadline-dev libtool pkg-config g++ make \
+ iputils-ping tcpdump
+
+# install core
+cd ~/Documents
+sudo apt-get install -y ./core_*.deb
+
+# install ospf mdr
+cd ~/Documents
+git clone https://github.com/USNavalResearchLaboratory/ospf-mdr.git
+cd ospf-mdr
+./bootstrap.sh
+./configure --disable-doc --enable-user=root --enable-group=root \
+ --with-cflags=-ggdb --sysconfdir=/usr/local/etc/quagga --enable-vtysh \
+ --localstatedir=/var/run/quagga
+make -j$(nproc)
+sudo make install
+
+# install emane
+cd ~/Documents
+wget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip
+mkdir protoc
+unzip protoc-3.19.6-linux-x86_64.zip -d protoc
+git clone https://github.com/adjacentlink/emane.git
+cd emane
+./autogen.sh
+./configure --prefix=/usr
+make -j$(nproc)
+sudo make install
+cd src/python
+make clean
+PATH=~/Documents/protoc/bin:$PATH make
+sudo /opt/core/venv/bin/python -m pip install .
+The CORE virtual environment and related scripts will not be found on your PATH, +so some adjustments needs to be made.
+To add support for your user to run scripts from the virtual environment:
+# can add to ~/.bashrc
+export PATH=$PATH:/opt/core/venv/bin
+This will not solve the path issue when running as sudo, so you can do either +of the following to compensate.
+# run command passing in the right PATH to pickup from the user running the command
+sudo env PATH=$PATH core-daemon
+
+# add an alias to ~/.bashrc or something similar
+alias sudop='sudo env PATH=$PATH'
+# now you can run commands like so
+sudop core-daemon
+LXC nodes are provided by way of LXD to create nodes using predefined +images and provide file system separation.
+sudo snap install lxd
+Initialize LXD and say no to adding a default bridge.
+sudo lxd init
+To use LXC nodes within the python GUI, you will need to make sure the user running the GUI is a member of the +lxd group.
+# add group if does not exist
+sudo groupadd lxd
+
+# add user to group
+sudo usermod -aG lxd $USER
+
+# to get this change to take effect, log out and back in or run the following
+newgrp lxd
+Different node types can be used within CORE, each with their own +tradeoffs and functionality.
+CORE nodes are the standard node type typically used in CORE. They are
+backed by Linux network namespaces. They use very little system resources
+in order to emulate a network. They do however share the hosts file system
+as they do not get their own. CORE nodes will have a directory uniquely
+created for them as a place to keep their files and mounted directories
+(/tmp/pycore.<session id>/<node name.conf),
+which will usually be wiped and removed upon shutdown.
Docker nodes provide a convenience for running nodes using predefind images +and filesystems that CORE nodes do not provide. Details for using Docker +nodes can be found here.
+LXC nodes provide a convenience for running nodes using predefind images +and filesystems that CORE nodes do not provide. Details for using LXC +nodes can be found here.
+The physical machine type is used for nodes that represent a real Linux-based +machine that will participate in the emulated network scenario. This is +typically used, for example, to incorporate racks of server machines from an +emulation testbed. A physical node is one that is running the CORE daemon +(core-daemon), but will not be further partitioned into containers. +Services that are run on the physical node do not run in an isolated +environment, but directly on the operating system.
+Physical nodes must be assigned to servers, the same way nodes are assigned to +emulation servers with Distributed Emulation. The list of available physical +nodes currently shares the same dialog box and list as the emulation servers, +accessed using the Emulation Servers... entry from the Session menu.
+Support for physical nodes is under development and may be improved in future +releases. Currently, when any node is linked to a physical node, a dashed line +is drawn to indicate network tunneling. A GRE tunneling interface will be +created on the physical node and used to tunnel traffic to and from the +emulated world.
+Double-clicking on a physical node during runtime opens a terminal with an +SSH shell to that node. Users should configure public-key SSH login as done +with emulation servers.
+ + + + + + +The top question about the performance of CORE is often how many nodes can it +handle? The answer depends on several factors:
+| Factor | +Performance Impact | +
|---|---|
| Hardware | +the number and speed of processors in the computer, the available processor cache, RAM memory, and front-side bus speed may greatly affect overall performance. | +
| Operating system version | +distribution of Linux and the specific kernel versions used will affect overall performance. | +
| Active processes | +all nodes share the same CPU resources, so if one or more nodes is performing a CPU-intensive task, overall performance will suffer. | +
| 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. | +
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 +routing. On this hardware CORE can instantiate 100 or more nodes, but at +that point it becomes critical as to what each of the nodes is doing.
+Because this software is primarily a network emulator, the more appropriate +question is how much network traffic can it handle? On the same 3.0GHz +server described above, running Linux, about 300,000 packets-per-second can +be pushed through the system. The number of hops and the size of the packets +is less important. The limiting factor is the number of times that the +operating system needs to handle a packet. The 300,000 pps figure represents +the number of times the system as a whole needed to deal with a packet. As +more network hops are added, this increases the number of context switches +and decreases the throughput seen on the full length of the network path.
+Note
+The right question to be asking is "how much traffic?", not +"how many nodes?".
+For a more detailed study of performance in CORE, refer to the following +publications:
+Writing your own Python scripts offers a rich programming environment with +complete control over all aspects of the emulation.
+The scripts need to be ran with root privileges because they create new network +namespaces. In general, a CORE Python script does not connect to the CORE +daemon, in fact the core-daemon is just another Python script that uses +the CORE Python modules and exchanges messages with the GUI.
+When creating nodes of type core.nodes.base.CoreNode these are the default models
+and the services they map to.
There is an interface helper class that can be leveraged for convenience
+when creating interface data for nodes. Alternatively one can manually create
+a core.emulator.data.InterfaceData class instead with appropriate information.
Manually creating interface data:
+from core.emulator.data import InterfaceData
+
+# id is optional and will set to the next available id
+# name is optional and will default to eth<id>
+# mac is optional and will result in a randomly generated mac
+iface_data = InterfaceData(
+ id=0,
+ name="eth0",
+ ip4="10.0.0.1",
+ ip4_mask=24,
+ ip6="2001::",
+ ip6_mask=64,
+)
+Leveraging the interface prefixes helper class:
+from core.emulator.data import IpPrefixes
+
+ip_prefixes = IpPrefixes(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64")
+# node is used to get an ip4/ip6 address indexed from within the above prefixes
+# name is optional and would default to eth<id>
+# mac is optional and will result in a randomly generated mac
+iface_data = ip_prefixes.create_iface(
+ node=node, name="eth0", mac="00:00:00:00:aa:00"
+)
+Various events that can occur within a session can be listened to.
+Event types:
+def event_listener(event):
+ print(event)
+
+
+# add an event listener to event type you want to listen to
+# each handler will receive an object unique to that type
+session.event_handlers.append(event_listener)
+session.exception_handlers.append(event_listener)
+session.node_handlers.append(event_listener)
+session.link_handlers.append(event_listener)
+session.file_handlers.append(event_listener)
+session.config_handlers.append(event_listener)
+Links can be configured at the time of creation or during runtime.
+Currently supported configuration options:
+from core.emulator.data import LinkOptions
+
+# configuring when creating a link
+options = LinkOptions(
+ bandwidth=54_000_000,
+ delay=5000,
+ dup=5,
+ loss=5.5,
+ jitter=0,
+)
+session.add_link(n1_id, n2_id, iface1_data, iface2_data, options)
+
+# configuring during runtime
+session.update_link(n1_id, n2_id, iface1_id, iface2_id, options)
+# required imports
+from core.emulator.coreemu import CoreEmu
+from core.emulator.data import IpPrefixes
+from core.emulator.enumerations import EventTypes
+from core.nodes.base import CoreNode, Position
+
+# ip nerator for example
+ip_prefixes = IpPrefixes(ip4_prefix="10.0.0.0/24")
+
+# create emulator instance for creating sessions and utility methods
+coreemu = CoreEmu()
+session = coreemu.create_session()
+
+# must be in configuration state for nodes to start, when using "node_add" below
+session.set_state(EventTypes.CONFIGURATION_STATE)
+
+# create nodes
+position = Position(x=100, y=100)
+n1 = session.add_node(CoreNode, position=position)
+position = Position(x=300, y=100)
+n2 = session.add_node(CoreNode, position=position)
+
+# link nodes together
+iface1 = ip_prefixes.create_iface(n1)
+iface2 = ip_prefixes.create_iface(n2)
+session.add_link(n1.id, n2.id, iface1, iface2)
+
+# start session
+session.instantiate()
+
+# do whatever you like here
+input("press enter to shutdown")
+
+# stop session
+session.shutdown()
+# required imports
+from core.emulator.coreemu import CoreEmu
+from core.emulator.data import IpPrefixes
+from core.emulator.enumerations import EventTypes
+from core.nodes.base import CoreNode, Position
+from core.nodes.network import SwitchNode
+
+# ip nerator for example
+ip_prefixes = IpPrefixes(ip4_prefix="10.0.0.0/24")
+
+# create emulator instance for creating sessions and utility methods
+coreemu = CoreEmu()
+session = coreemu.create_session()
+
+# must be in configuration state for nodes to start, when using "node_add" below
+session.set_state(EventTypes.CONFIGURATION_STATE)
+
+# create switch
+position = Position(x=200, y=200)
+switch = session.add_node(SwitchNode, position=position)
+
+# create nodes
+position = Position(x=100, y=100)
+n1 = session.add_node(CoreNode, position=position)
+position = Position(x=300, y=100)
+n2 = session.add_node(CoreNode, position=position)
+
+# link nodes to switch
+iface1 = ip_prefixes.create_iface(n1)
+session.add_link(n1.id, switch.id, iface1)
+iface1 = ip_prefixes.create_iface(n2)
+session.add_link(n2.id, switch.id, iface1)
+
+# start session
+session.instantiate()
+
+# do whatever you like here
+input("press enter to shutdown")
+
+# stop session
+session.shutdown()
+# required imports
+from core.emulator.coreemu import CoreEmu
+from core.emulator.data import IpPrefixes
+from core.emulator.enumerations import EventTypes
+from core.location.mobility import BasicRangeModel
+from core.nodes.base import CoreNode, Position
+from core.nodes.network import WlanNode
+
+# ip nerator for example
+ip_prefixes = IpPrefixes(ip4_prefix="10.0.0.0/24")
+
+# create emulator instance for creating sessions and utility methods
+coreemu = CoreEmu()
+session = coreemu.create_session()
+
+# must be in configuration state for nodes to start, when using "node_add" below
+session.set_state(EventTypes.CONFIGURATION_STATE)
+
+# create wlan
+position = Position(x=200, y=200)
+wlan = session.add_node(WlanNode, position=position)
+
+# create nodes
+options = CoreNode.create_options()
+options.model = "mdr"
+position = Position(x=100, y=100)
+n1 = session.add_node(CoreNode, position=position, options=options)
+position = Position(x=300, y=100)
+n2 = session.add_node(CoreNode, position=position, options=options)
+
+# configuring wlan
+session.mobility.set_model_config(wlan.id, BasicRangeModel.name, {
+ "range": "280",
+ "bandwidth": "55000000",
+ "delay": "6000",
+ "jitter": "5",
+ "error": "5",
+})
+
+# link nodes to wlan
+iface1 = ip_prefixes.create_iface(n1)
+session.add_link(n1.id, wlan.id, iface1)
+iface1 = ip_prefixes.create_iface(n2)
+session.add_link(n2.id, wlan.id, iface1)
+
+# start session
+session.instantiate()
+
+# do whatever you like here
+input("press enter to shutdown")
+
+# stop session
+session.shutdown()
+For EMANE you can import and use one of the existing models and +use its name for configuration.
+Current models:
+Their configurations options are driven dynamically from parsed EMANE manifest files +from the installed version of EMANE.
+Options and their purpose can be found at the EMANE Wiki.
+If configuring EMANE global settings or model mac/phy specific settings, any value not provided +will use the defaults. When no configuration is used, the defaults are used.
+# required imports
+from core.emane.models.ieee80211abg import EmaneIeee80211abgModel
+from core.emane.nodes import EmaneNet
+from core.emulator.coreemu import CoreEmu
+from core.emulator.data import IpPrefixes
+from core.emulator.enumerations import EventTypes
+from core.nodes.base import CoreNode, Position
+
+# ip nerator for example
+ip_prefixes = IpPrefixes(ip4_prefix="10.0.0.0/24")
+
+# create emulator instance for creating sessions and utility methods
+coreemu = CoreEmu()
+session = coreemu.create_session()
+
+# location information is required to be set for emane
+session.location.setrefgeo(47.57917, -122.13232, 2.0)
+session.location.refscale = 150.0
+
+# must be in configuration state for nodes to start, when using "node_add" below
+session.set_state(EventTypes.CONFIGURATION_STATE)
+
+# create emane
+options = EmaneNet.create_options()
+options.emane_model = EmaneIeee80211abgModel.name
+position = Position(x=200, y=200)
+emane = session.add_node(EmaneNet, position=position, options=options)
+
+# create nodes
+options = CoreNode.create_options()
+options.model = "mdr"
+position = Position(x=100, y=100)
+n1 = session.add_node(CoreNode, position=position, options=options)
+position = Position(x=300, y=100)
+n2 = session.add_node(CoreNode, position=position, options=options)
+
+# configure general emane settings
+config = session.emane.get_configs()
+config.update({
+ "eventservicettl": "2"
+})
+
+# configure emane model settings
+# using a dict mapping currently support values as strings
+session.emane.set_model_config(emane.id, EmaneIeee80211abgModel.name, {
+ "unicastrate": "3",
+})
+
+# link nodes to emane
+iface1 = ip_prefixes.create_iface(n1)
+session.add_link(n1.id, emane.id, iface1)
+iface1 = ip_prefixes.create_iface(n2)
+session.add_link(n2.id, emane.id, iface1)
+
+# start session
+session.instantiate()
+
+# do whatever you like here
+input("press enter to shutdown")
+
+# stop session
+session.shutdown()
+EMANE Model Configuration:
+from core import utils
+
+# standardized way to retrieve an appropriate config id
+# iface id can be omitted, to allow a general configuration for a model, per node
+config_id = utils.iface_config_id(node.id, iface_id)
+# set emane configuration for the config id
+session.emane.set_config(config_id, EmaneIeee80211abgModel.name, {
+ "unicastrate": "3",
+})
+Services help generate and run bash scripts on nodes for a given purpose.
+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.
+The following features can be configured for a service:
+Editing service properties:
+# configure a service, for a node, for a given session
+session.services.set_service(node_id, service_name)
+service = session.services.get_service(node_id, service_name)
+service.configs = ("file1.sh", "file2.sh")
+service.dirs = ("/etc/node",)
+service.startup = ("bash file1.sh",)
+service.validate = ()
+service.shutdown = ()
+When editing a service file, it must be the name of config
+file that the service will generate.
Editing a service file:
+# to edit the contents of a generated file you can specify
+# the service, the file name, and its contents
+session.services.set_service_file(
+ node_id,
+ service_name,
+ file_name,
+ "echo hello",
+)
+File versions of the network examples can be found +here.
+To execute a python script from a GUI you need have the following.
+The builtin name check here to know it is being executed from the GUI, this can +be avoided if your script does not use a name check.
+if __name__ in ["__main__", "__builtin__"]:
+ main()
+A script can add sessions to the core-daemon. A global coreemu variable is +exposed to the script pointing to the CoreEmu object.
+The example below has a fallback to a new CoreEmu object, in the case you would +like to run the script standalone, outside of the core-daemon.
+coreemu = globals().get("coreemu") or CoreEmu()
+session = coreemu.create_session()
+CORE (Common Open Research Emulator) is a tool for building virtual networks. As an emulator, CORE builds a representation of a real computer network that runs in real time, as opposed to simulation, where abstract models are used. The live-running emulation can be connected to physical networks and routers. It provides an environment for running real applications and protocols, taking advantage of tools provided by the Linux operating system.
CORE is typically used for network and protocol research, demonstrations, application and platform testing, evaluating networking scenarios, security studies, and increasing the size of physical test networks.
"},{"location":"index.html#key-features","title":"Key Features","text":"CORE can create and run multiple emulated sessions at once, below is an overview of the states a session will transition between during typical GUI interactions.
"},{"location":"architecture.html#how-does-it-work","title":"How Does it Work?","text":"The CORE framework runs on Linux and uses Linux namespacing for creating node containers. These nodes are linked together using Linux bridging and virtual interfaces. CORE sessions are a set of nodes and links operating together for a specific purpose.
"},{"location":"architecture.html#linux","title":"Linux","text":"Linux network namespaces (also known as netns) is the primary technique used by CORE. Most recent Linux distributions have namespaces-enabled kernels out of the box. Each namespace has its own process environment and private network stack. Network namespaces share the same filesystem in CORE.
CORE combines these namespaces with Linux Ethernet bridging to form networks. Link characteristics are applied using Linux Netem queuing disciplines. Nftables provides Ethernet frame filtering on Linux bridges. Wireless networks are emulated by controlling which interfaces can send and receive with nftables rules.
"},{"location":"architecture.html#open-source-project-and-resources","title":"Open Source Project and Resources","text":"CORE has been released by Boeing to the open source community under the BSD license. If you find CORE useful for your work, please contribute back to the project. Contributions can be as simple as reporting a bug, dropping a line of encouragement, or can also include submitting patches or maintaining aspects of the tool.
"},{"location":"configservices.html","title":"Config Services","text":""},{"location":"configservices.html#overview","title":"Overview","text":"Config services are a newer version of services for CORE, that leverage a templating engine, for more robust service file creation. They also have the power of configuration key/value pairs that values that can be defined and displayed within the GUI, to help further tweak a service, as needed.
CORE services are a convenience for creating reusable dynamic scripts to run on nodes, for carrying out specific task(s).
This boilds down to the following functions:
Most CORE nodes will have a default set of services to run, associated with them. You can however customize the set of services a node will use. Or even further define a new node type within the GUI, with a set of services, that will allow quickly dragging and dropping that node type during creation.
"},{"location":"configservices.html#available-services","title":"Available Services","text":"Service Group Services BIRD BGP, OSPF, RADV, RIP, Static EMANE Transport Service FRR BABEL, BGP, OSPFv2, OSPFv3, PIMD, RIP, RIPNG, Zebra NRL arouted, MGEN Sink, MGEN Actor, NHDP, OLSR, OLSRORG, OLSRv2, SMF Quagga BABEL, BGP, OSPFv2, OSPFv3, OSPFv3 MDR, RIP, RIPNG, XPIMD, Zebra SDN OVS, RYU Security Firewall, IPsec, NAT, VPN Client, VPN Server Utility ATD, Routing Utils, DHCP, FTP, IP Forward, PCAP, RADVD, SSF, UCARP XORP BGP, OLSR, OSPFv2, OSPFv3, PIMSM4, PIMSM6, RIP, RIPNG, Router Manager"},{"location":"configservices.html#node-types-and-default-services","title":"Node Types and Default Services","text":"Here are the default node types and their services:
Node Type Services router zebra, OSFPv2, OSPFv3, and IPForward services for IGP link-state routing. PC DefaultRoute service for having a default route when connected directly to a router. mdr zebra, OSPFv3MDR, and IPForward services for wireless-optimized MANET Designated Router routing. prouter a physical router, having the same default services as the router node type; for incorporating Linux testbed machines into an emulation.Configuration files can be automatically generated by each service. For example, CORE automatically generates routing protocol configuration for the router nodes in order to simplify the creation of virtual networks.
To change the services associated with a node, double-click on the node to invoke its configuration dialog and click on the Services... button, or right-click a node a choose Services... from the menu. Services are enabled or disabled by clicking on their names. The button next to each service name allows you to customize all aspects of this service for this node. For example, special route redistribution commands could be inserted in to the Quagga routing configuration associated with the zebra service.
To change the default services associated with a node type, use the Node Types dialog available from the Edit button at the end of the Layer-3 nodes toolbar, or choose Node types... from the Session menu. Note that any new services selected are not applied to existing nodes if the nodes have been customized.
The node types are saved in the GUI config file ~/.coregui/config.yaml. Keep this in mind when changing the default services for existing node types; it may be better to simply create a new node type. It is recommended that you do not change the default built-in node types.
"},{"location":"configservices.html#new-services","title":"New Services","text":"Services can save time required to configure nodes, especially if a number of nodes require similar configuration procedures. New services can be introduced to automate tasks.
"},{"location":"configservices.html#creating-new-services","title":"Creating New Services","text":"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.
Modify the example service shown below to do what you want. It could generate config/script files, mount per-node directories, start processes/scripts, etc. Your file can define one or more classes to be imported. You can create multiple Python files that will be imported.
Put these files in a directory such as ~/.coregui/custom_services.
Add a custom_config_services_dir = ~/.coregui/custom_services entry to the /etc/core/core.conf file.
Restart the CORE daemon (core-daemon). Any import errors (Python syntax) should be displayed in the terminal (or service log, like journalctl).
Start using your custom service on your nodes. You can create a new node type that uses your service, or change the default services for an existing node type, or change individual nodes.
Below is the skeleton for a custom service with some documentation. Most people would likely only setup the required class variables (name/group). Then define the files to generate and implement the get_text_template function to dynamically create the files wanted. Finally, the startup commands would be supplied, which typically tend to be running the shell files generated.
from typing import Dict, List\n\nfrom core.config import ConfigString, ConfigBool, Configuration\nfrom core.configservice.base import ConfigService, ConfigServiceMode, ShadowDir\n\n\n# class that subclasses ConfigService\nclass ExampleService(ConfigService):\n # unique name for your service within CORE\n name: str = \"Example\"\n # the group your service is associated with, used for display in GUI\n group: str = \"ExampleGroup\"\n # directories that the service should shadow mount, hiding the system directory\n directories: List[str] = [\n \"/usr/local/core\",\n ]\n # files that this service should generate, defaults to nodes home directory\n # or can provide an absolute path to a mounted directory\n files: List[str] = [\n \"example-start.sh\",\n \"/usr/local/core/file1\",\n ]\n # executables that should exist on path, that this service depends on\n executables: List[str] = []\n # other services that this service depends on, can be used to define service start order\n dependencies: List[str] = []\n # commands to run to start this service\n startup: List[str] = []\n # commands to run to validate this service\n validate: List[str] = []\n # commands to run to stop this service\n shutdown: List[str] = []\n # validation mode, blocking, non-blocking, and timer\n validation_mode: ConfigServiceMode = ConfigServiceMode.BLOCKING\n # configurable values that this service can use, for file generation\n default_configs: List[Configuration] = [\n ConfigString(id=\"value1\", label=\"Text\"),\n ConfigBool(id=\"value2\", label=\"Boolean\"),\n ConfigString(id=\"value3\", label=\"Multiple Choice\", options=[\"value1\", \"value2\", \"value3\"]),\n ]\n # sets of values to set for the configuration defined above, can be used to\n # provide convenient sets of values to typically use\n modes: Dict[str, Dict[str, str]] = {\n \"mode1\": {\"value1\": \"value1\", \"value2\": \"0\", \"value3\": \"value2\"},\n \"mode2\": {\"value1\": \"value2\", \"value2\": \"1\", \"value3\": \"value3\"},\n \"mode3\": {\"value1\": \"value3\", \"value2\": \"0\", \"value3\": \"value1\"},\n }\n # defines directories that this service can help shadow within a node\n shadow_directories: List[ShadowDir] = [\n ShadowDir(path=\"/user/local/core\", src=\"/opt/core\")\n ]\n\n def get_text_template(self, name: str) -> str:\n return \"\"\"\n # sample script 1\n # node id(${node.id}) name(${node.name})\n # config: ${config}\n echo hello\n \"\"\"\nValidation modes are used to determine if a service has started up successfully.
Shadow directories provide a convenience for copying a directory and the files within it to a nodes home directory, to allow a unique set of per node files.
ShadowDir(path=\"/user/local/core\") - copies files at the given location into the nodeShadowDir(path=\"/user/local/core\", src=\"/opt/core\") - copies files to the given location, but sourced from the provided locationShadowDir(path=\"/user/local/core\", templates=True) - copies files and treats them as templates for generationShadowDir(path=\"/user/local/core\", has_node_paths=True) - copies files from the given location, and looks for unique node names directories within it, using a directory named default, when not presetThe CORE control network allows the virtual nodes to communicate with their host environment. There are two types: the primary control network and auxiliary control networks. The primary control network is used mainly for communicating with the virtual nodes from host machines and for master-slave communications in a multi-server distributed environment. Auxiliary control networks have been introduced to for routing namespace hosted emulation software traffic to the test network.
"},{"location":"ctrlnet.html#activating-the-primary-control-network","title":"Activating the Primary Control Network","text":"Under the Session Menu, the Options... dialog has an option to set a control network prefix.
This can be set to a network prefix such as 172.16.0.0/24. A bridge will be created on the host machine having the last address in the prefix range (e.g. 172.16.0.254), and each node will have an extra ctrl0 control interface configured with an address corresponding to its node number (e.g. 172.16.0.3 for n3.)
A default for the primary control network may also be specified by setting the controlnet line in the /etc/core/core.conf configuration file which new sessions will use by default. To simultaneously run multiple sessions with control networks, the session option should be used instead of the core.conf default.
Note
If you have a large scenario with more than 253 nodes, use a control network prefix that allows more than the suggested /24, such as /23 or greater.
Note
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.
# Restart the CORE Daemon\nsudo /etc/init.d core-daemon restart\n\n# Remove lingering control network bridges\nctrlbridges=`brctl show | grep b.ctrl | awk '{print $1}'`\nfor cb in $ctrlbridges; do\nsudo ifconfig $cb down\n sudo brctl delbr $cb\ndone\nNote
If adjustments to the primary control network configuration made in /etc/core/core.conf do not seem to take affect, check if there is anything set in the Session Menu, the Options... dialog. They may need to be cleared. These per session settings override the defaults in /etc/core/core.conf.
"},{"location":"ctrlnet.html#control-network-in-distributed-sessions","title":"Control Network in Distributed Sessions","text":"When the primary control network is activated for a distributed session, a control network bridge will be created on each of the slave servers, with GRE tunnels back to the master server's bridge. The slave control bridges are not assigned an address. From the host, any of the nodes (local or remote) can be accessed, just like the single server case.
In some situations, remote emulated nodes need to communicate with the host on which they are running and not the master server. Multiple control network prefixes can be specified in the either the session option or /etc/core/core.conf, separated by spaces and beginning with the master server. Each entry has the form \"server:prefix\". For example, if the servers core1,core2, and core3 are assigned with nodes in the scenario and using /etc/core/core.conf instead of the session option.
controlnet=core1:172.16.1.0/24 core2:172.16.2.0/24 core3:172.16.1.0/24\nThen, the control network bridges will be assigned as follows:
Tunnels back to the master server will still be built, but it is up to the user to add appropriate routes if networking between control network prefixes is desired. The control network script may help with this.
"},{"location":"ctrlnet.html#control-network-script","title":"Control Network Script","text":"A control network script may be specified using the controlnet_updown_script option in the /etc/core/core.conf file. This script will be run after the bridge has been built (and address assigned) with the first argument being the name of the bridge, and the second argument being the keyword \"startup\". The script will again be invoked prior to bridge removal with the second argument being the keyword \"shutdown\".
"},{"location":"ctrlnet.html#auxiliary-control-networks","title":"Auxiliary Control Networks","text":"Starting with EMANE 0.9.2, CORE will run EMANE instances within namespaces. Since it is advisable to separate the OTA traffic from other traffic, we will need more than single channel leading out from the namespace. Up to three auxiliary control networks may be defined. Multiple control networks are set up in /etc/core/core.conf file. Lines controlnet1, controlnet2 and controlnet3 define the auxiliary networks.
For example, having the following /etc/core/core.conf:
controlnet = core1:172.17.1.0/24 core2:172.17.2.0/24 core3:172.17.3.0/24\ncontrolnet1 = core1:172.18.1.0/24 core2:172.18.2.0/24 core3:172.18.3.0/24\ncontrolnet2 = core1:172.19.1.0/24 core2:172.19.2.0/24 core3:172.19.3.0/24\nThis will activate the primary and two auxiliary control networks and add interfaces ctrl0, ctrl1, ctrl2 to each node. One use case would be to assign ctrl1 to the OTA manager device and ctrl2 to the Event Service device in the EMANE Options dialog box and leave ctrl0 for CORE control traffic.
Note
controlnet0 may be used in place of controlnet to configure the primary control network.
Unlike the primary control network, the auxiliary control networks will not employ tunneling since their primary purpose is for efficiently transporting multicast EMANE OTA and event traffic. Note that there is no per-session configuration for auxiliary control networks.
To extend the auxiliary control networks across a distributed test environment, host network interfaces need to be added to them. The following lines in /etc/core/core.conf will add host devices eth1, eth2 and eth3 to controlnet1, controlnet2, controlnet3:
controlnetif1 = eth1\ncontrolnetif2 = eth2\ncontrolnetif3 = eth3\nNote
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.
"},{"location":"devguide.html","title":"CORE Developer's Guide","text":""},{"location":"devguide.html#overview","title":"Overview","text":"The CORE source consists of several programming languages for historical reasons. Current development focuses on the Python modules and daemon. Here is a brief description of the source directories.
Directory Description daemon Python CORE daemon/gui code that handles receiving API calls and creating containers docs Markdown Documentation currently hosted on GitHub man Template files for creating man pages for various CORE command line utilities netns C program for creating CORE containers"},{"location":"devguide.html#getting-started","title":"Getting started","text":"To setup CORE for develop we will leverage to automated install script.
"},{"location":"devguide.html#clone-core-repo","title":"Clone CORE Repo","text":"cd ~/Documents\ngit clone https://github.com/coreemu/core.git\ncd core\ngit checkout develop\nThis command will automatically install system dependencies, clone and build OSPF-MDR, build CORE, setup the CORE poetry environment, and install pre-commit hooks. You can refer to the install docs for issues related to different distributions.
./install -d\npre-commit hooks help automate running tools to check modified code. Every time a commit is made python utilities will be ran to check validity of code, potentially failing and backing out the commit. These changes are currently mandated as part of the current CI, so add the changes and commit again.
"},{"location":"devguide.html#running-core","title":"Running CORE","text":"You can now run core as you normally would, or leverage some of the invoke tasks to conveniently run tests, etc.
# run core-daemon\nsudo core-daemon\n\n# run gui\ncore-gui\n\n# run mocked unit tests\ncd <CORE_REPO>\ninv test-mock\nLinux network namespace containers are often managed using the Linux Container Tools or lxc-tools package. The lxc-tools website is available here http://lxc.sourceforge.net/ for more information. CORE does not use these management utilities, but includes its own set of tools for instantiating and configuring network namespace containers. This section describes these tools.
"},{"location":"devguide.html#vnoded","title":"vnoded","text":"The vnoded daemon is the program used to create a new namespace, and listen on a control channel for commands that may instantiate other processes. This daemon runs as PID 1 in the container. It is launched automatically by the CORE daemon. The control channel is a UNIX domain socket usually named /tmp/pycore.23098/n3, for node 3 running on CORE session 23098, for example. Root privileges are required for creating a new namespace.
"},{"location":"devguide.html#vcmd","title":"vcmd","text":"The vcmd program is used to connect to the vnoded daemon in a Linux network namespace, for running commands in the namespace. The CORE daemon uses the same channel for setting up a node and running processes within it. This program has two required arguments, the control channel name, and the command line to be run within the namespace. This command does not need to run with root privileges.
When you double-click on a node in a running emulation, CORE will open a shell window for that node using a command such as:
gnome-terminal -e vcmd -c /tmp/pycore.50160/n1 -- bash\nSimilarly, the IPv4 routes Observer Widget will run a command to display the routing table using a command such as:
vcmd -c /tmp/pycore.50160/n1 -- /sbin/ip -4 ro\nA script named core-cleanup is provided to clean up any running CORE emulations. It will attempt to kill any remaining vnoded processes, kill any EMANE processes, remove the :file:/tmp/pycore.* session directories, and remove any bridges or nftables rules. With a -d option, it will also kill any running CORE daemon.
The netns command is not used by CORE directly. This utility can be used to run a command in a new network namespace for testing purposes. It does not open a control channel for receiving further commands.
"},{"location":"devguide.html#other-useful-commands","title":"Other Useful Commands","text":"Here are some other Linux commands that are useful for managing the Linux network namespace emulation.
# view the Linux bridging setup\nip link show type bridge\n# view the netem rules used for applying link effects\ntc qdisc show\n# view the rules that make the wireless LAN work\nnft list ruleset\nA large emulation scenario can be deployed on multiple emulation servers and controlled by a single GUI. The GUI, representing the entire topology, can be run on one of the emulation servers or on a separate machine.
Each machine that will act as an emulation will require the installation of a distributed CORE package and some configuration to allow SSH as root.
"},{"location":"distributed.html#core-configuration","title":"CORE Configuration","text":"CORE configuration settings required for using distributed functionality.
Edit /etc/core/core.conf or specific configuration file being used.
# uncomment and set this to the address that remote servers\n# use to get back to the main host, example below\ndistributed_address = 129.168.0.101\nEMANE needs to have controlnet configured in core.conf in order to startup correctly. The names before the addresses need to match the names of distributed servers configured.
controlnet = core1:172.16.1.0/24 core2:172.16.2.0/24 core3:172.16.3.0/24 core4:172.16.4.0/24 core5:172.16.5.0/24\nemane_event_generate = True\nDistributed CORE works using the python fabric library to run commands on remote servers over SSH.
"},{"location":"distributed.html#remote-gui-terminals","title":"Remote GUI Terminals","text":"You need to have the same user defined on each server, since the user used for these remote shells is the same user that is running the CORE GUI.
Edit -> Preferences... -> Terminal program:
Currently recommend setting this to xterm -e as the default gnome-terminal will not work.
May need to install xterm if, not already installed.
sudo apt install xterm\nFirst the distributed servers must be configured to allow passwordless root login over SSH.
On distributed server:
# install openssh-server\nsudo apt install openssh-server\n\n# open sshd config\nvi /etc/ssh/sshd_config\n\n# verify these configurations in file\nPermitRootLogin yes\nPasswordAuthentication yes\n\n# if desired add/modify the following line to allow SSH to\n# accept all env variables\nAcceptEnv *\n\n# restart sshd\nsudo systemctl restart sshd\nOn master server:
# install package if needed\nsudo apt install openssh-client\n\n# generate ssh key if needed\nssh-keygen -o -t rsa -b 4096 -f ~/.ssh/core\n\n# copy public key to authorized_keys file\nssh-copy-id -i ~/.ssh/core root@server\n\n# configure fabric to use the core ssh key\nsudo vi /etc/fabric.yml\n\n# set configuration\nconnect_kwargs: {\"key_filename\": \"/home/user/.ssh/core\"}\nOn distributed server:
# open sshd config\nvi /etc/ssh/sshd_config\n\n# change configuration for root login to without password\nPermitRootLogin without-password\n\n# restart sshd\nsudo systemctl restart sshd\nMake sure the value used below is the absolute path to the file generated above ~/.ssh/core\"
Add/update the fabric configuration file /etc/fabric.yml:
connect_kwargs: { \"key_filename\": \"/home/user/.ssh/core\" }\nWithin the core-gui navigate to menu option:
Session -> Servers...
Within the dialog box presented, add or modify an existing server if present to use the name, address, and port for the a server you plan to use.
Server configurations are loaded and written to in a configuration file for the GUI.
"},{"location":"distributed.html#assigning-nodes","title":"Assigning Nodes","text":"The user needs to assign nodes to emulation servers in the scenario. Making no assignment means the node will be emulated on the master server In the configuration window of every node, a drop-down box located between the Node name and the Image button will select the name of the emulation server. By default, this menu shows (none), indicating that the node will be emulated locally on the master. When entering Execute mode, the CORE GUI will deploy the node on its assigned emulation server.
Another way to assign emulation servers is to select one or more nodes using the select tool (ctrl-click to select multiple), and right-click one of the nodes and choose Assign to....
The CORE emulation servers dialog box may also be used to assign nodes to servers. The assigned server name appears in parenthesis next to the node name. To assign all nodes to one of the servers, click on the server name and then the all nodes button. Servers that have assigned nodes are shown in blue in the server list. Another option is to first select a subset of nodes, then open the CORE emulation servers box and use the selected nodes button.
IMPORTANT: Leave the nodes unassigned if they are to be run on the master server. Do not explicitly assign the nodes to the master server.
"},{"location":"distributed.html#gui-visualization","title":"GUI Visualization","text":"If there is a link between two nodes residing on different servers, the GUI will draw the link with a dashed line.
"},{"location":"distributed.html#concerns-and-limitations","title":"Concerns and Limitations","text":"Wireless nodes, i.e. those connected to a WLAN node, can be assigned to different emulation servers and participate in the same wireless network only if an EMANE model is used for the WLAN. The basic range model does not work across multiple servers due to the Linux bridging and nftables rules that are used.
Note
The basic range wireless model does not support distributed emulation, but EMANE does.
When nodes are linked across servers core-daemons will automatically create necessary tunnels between the nodes when executed. Care should be taken to arrange the topology such that the number of tunnels is minimized. The tunnels carry data between servers to connect nodes as specified in the topology. These tunnels are created using GRE tunneling, similar to the Tunnel Tool.
"},{"location":"distributed.html#distributed-checklist","title":"Distributed Checklist","text":"Provided below is some information for helping setup and use Docker nodes within a CORE scenario.
"},{"location":"docker.html#installation","title":"Installation","text":""},{"location":"docker.html#debian-systems","title":"Debian Systems","text":"sudo apt install docker.io\nCustom configuration required to avoid iptable rules being added and removing the need for the default docker network, since core will be orchestrating connections between nodes.
Place the file below in /etc/docker/docker.json
{\n\"bridge\": \"none\",\n\"iptables\": false\n}\nTo use Docker nodes within the python GUI, you will need to make sure the user running the GUI is a member of the docker group.
# add group if does not exist\nsudo groupadd docker\n\n# add user to group\nsudo usermod -aG docker $USER\n\n# to get this change to take effect, log out and back in or run the following\nnewgrp docker\nImages 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.
Example Dockerfile:
FROM ubuntu:latest\nRUN apt-get update\nRUN apt-get install -y iproute2 ethtool\nBuild image:
sudo docker build -t <name> .\nThe Extendable Mobile Ad-hoc Network Emulator (EMANE) allows heterogeneous network emulation using a pluggable MAC and PHY layer architecture. The EMANE framework provides an implementation architecture for modeling different radio interface types in the form of Network Emulation Modules (NEMs) and incorporating these modules into a real-time emulation running in a distributed environment.
EMANE is developed by U.S. Naval Research Labs (NRL) Code 5522 and Adjacent Link LLC, who maintain these websites:
Instead of building Linux Ethernet bridging networks with CORE, higher-fidelity wireless networks can be emulated using EMANE bound to virtual devices. CORE emulates layers 3 and above (network, session, application) with its virtual network stacks and process space for protocols and applications, while EMANE emulates layers 1 and 2 (physical and data link) using its pluggable PHY and MAC models.
The interface between CORE and EMANE is a TAP device. CORE builds the virtual node using Linux network namespaces, installs the TAP device into the namespace and instantiates one EMANE process in the namespace. The EMANE process binds a user space socket to the TAP device for sending and receiving data from CORE.
An EMANE instance sends and receives OTA (Over-The-Air) traffic to and from other EMANE instances via a control port (e.g. ctrl0, ctrl1). It also sends and receives Events to and from the Event Service using the same or a different control port. EMANE models are configured through the GUI's configuration dialog. A corresponding EmaneModel Python class is sub-classed for each supported EMANE model, to provide configuration items and their mapping to XML files. This way new models can be easily supported. When CORE starts the emulation, it generates the appropriate XML files that specify the EMANE NEM configuration, and launches the EMANE daemons.
Some EMANE models support location information to determine when packets should be dropped. EMANE has an event system where location events are broadcast to all NEMs. CORE can generate these location events when nodes are moved on the canvas. The canvas size and scale dialog has controls for mapping the X,Y coordinate system to a latitude, longitude geographic system that EMANE uses. When specified in the core.conf configuration file, CORE can also subscribe to EMANE location events and move the nodes on the canvas as they are moved in the EMANE emulation. This would occur when an Emulation Script Generator, for example, is running a mobility script.
"},{"location":"emane.html#emane-in-core","title":"EMANE in CORE","text":"This section will cover some high level topics and examples for running and using EMANE in CORE.
You can find more detailed tutorials and examples at the EMANE Tutorial.
Every topic below assumes CORE, EMANE, and OSPF MDR have been installed.
Info
Demo files will be found within the core-gui ~/.coregui/xmls directory
The CORE configuration file /etc/core/core.conf has options specific to EMANE. An example emane section from the core.conf file is shown below:
# EMANE configuration\nemane_platform_port = 8101\nemane_transform_port = 8201\nemane_event_monitor = False\n#emane_models_dir = /home/<user>/.coregui/custom_emane\n# EMANE log level range [0,4] default: 2\nemane_log_level = 2\nemane_realtime = True\n# prefix used for emane installation\n# emane_prefix = /usr\nIf you have an EMANE event generator (e.g. mobility or pathloss scripts) and want to have CORE subscribe to EMANE location events, set the following line in the core.conf configuration file.
Note
Do not set this option to True if you want to manually drag nodes around on the canvas to update their location in EMANE.
emane_event_monitor = True\nAnother common issue is if installing EMANE from source, the default configure prefix will place the DTD files in /usr/local/share/emane/dtd while CORE expects them in /usr/share/emane/dtd.
Update the EMANE prefix configuration to resolve this problem.
emane_prefix = /usr/local\nCORE supports custom developed EMANE models by way of dynamically loading user created python files that represent the model. Custom EMANE models should be placed within the path defined by emane_models_dir in the CORE configuration file. This path cannot end in /emane.
Here is an example model with documentation describing functionality:
\"\"\"\nExample custom emane model.\n\"\"\"\nfrom pathlib import Path\nfrom typing import Dict, Optional, Set, List\n\nfrom core.config import Configuration\nfrom core.emane import emanemanifest, emanemodel\n\n\nclass ExampleModel(emanemodel.EmaneModel):\n\"\"\"\n Custom emane model.\n\n :cvar name: defines the emane model name that will show up in the GUI\n\n Mac Definition:\n :cvar mac_library: defines that mac library that the model will reference\n :cvar mac_xml: defines the mac manifest file that will be parsed to obtain configuration options,\n that will be displayed within the GUI\n :cvar mac_defaults: allows you to override options that are maintained within the manifest file above\n :cvar mac_config: parses the manifest file and converts configurations into core supported formats\n\n Phy Definition:\n NOTE: phy configuration will default to the universal model as seen below and the below section does not\n have to be included\n :cvar phy_library: defines that phy library that the model will reference, used if you need to\n provide a custom phy\n :cvar phy_xml: defines the phy manifest file that will be parsed to obtain configuration options,\n that will be displayed within the GUI\n :cvar phy_defaults: allows you to override options that are maintained within the manifest file above\n or for the default universal model\n :cvar phy_config: parses the manifest file and converts configurations into core supported formats\n\n Custom Override Options:\n NOTE: these options default to what's seen below and do not have to be included\n :cvar config_ignore: allows you to ignore options within phy/mac, used typically if you needed to add\n a custom option for display within the gui\n \"\"\"\n\n name: str = \"emane_example\"\n mac_library: str = \"rfpipemaclayer\"\n mac_xml: str = \"/usr/share/emane/manifest/rfpipemaclayer.xml\"\n mac_defaults: Dict[str, str] = {\n \"pcrcurveuri\": \"/usr/share/emane/xml/models/mac/rfpipe/rfpipepcr.xml\"\n }\n mac_config: List[Configuration] = []\n phy_library: Optional[str] = None\n phy_xml: str = \"/usr/share/emane/manifest/emanephy.xml\"\n phy_defaults: Dict[str, str] = {\n \"subid\": \"1\", \"propagationmodel\": \"2ray\", \"noisemode\": \"none\"\n }\n phy_config: List[Configuration] = []\n config_ignore: Set[str] = set()\n\n @classmethod\n def load(cls, emane_prefix: Path) -> None:\n\"\"\"\n Called after being loaded within the EmaneManager. Provides configured\n emane_prefix for parsing xml files.\n\n :param emane_prefix: configured emane prefix path\n :return: nothing\n \"\"\"\n cls._load_platform_config(emane_prefix)\n manifest_path = \"share/emane/manifest\"\n # load mac configuration\n mac_xml_path = emane_prefix / manifest_path / cls.mac_xml\n cls.mac_config = emanemanifest.parse(mac_xml_path, cls.mac_defaults)\n # load phy configuration\n phy_xml_path = emane_prefix / manifest_path / cls.phy_xml\n cls.phy_config = emanemanifest.parse(phy_xml_path, cls.phy_defaults)\nThis section describes running CORE and EMANE on a single machine. This is the default mode of operation when building an EMANE network with CORE. The OTA manager and Event service interface are set to use ctrl0 and the virtual nodes use the primary control channel for communicating with one another. The primary control channel is automatically activated when a scenario involves EMANE. Using the primary control channel prevents your emulation session from sending multicast traffic on your local network and interfering with other EMANE users.
EMANE is configured through an EMANE node. Once a node is linked to an EMANE cloud, the radio interface on that node may also be configured separately (apart from the cloud.)
Right click on an EMANE node and select EMANE Config to open the configuration dialog. The EMANE models should be listed here for selection. (You may need to restart the CORE daemon if it was running prior to installing the EMANE Python bindings.)
When an EMANE model is selected, you can click on the models option button causing the GUI to query the CORE daemon for configuration items. Each model will have different parameters, refer to the EMANE documentation for an explanation of each item. The defaults values are presented in the dialog. Clicking Apply and Apply again will store the EMANE model selections.
The RF-PIPE and IEEE 802.11abg models use a Universal PHY that supports geographic location information for determining pathloss between nodes. A default latitude and longitude location is provided by CORE and this location-based pathloss is enabled by default; this is the pathloss mode setting for the Universal PHY. Moving a node on the canvas while the emulation is running generates location events for EMANE. To view or change the geographic location or scale of the canvas use the Canvas Size and Scale dialog available from the Canvas menu.
Note that conversion between geographic and Cartesian coordinate systems is done using UTM (Universal Transverse Mercator) projection, where different zones of 6 degree longitude bands are defined. The location events generated by CORE may become inaccurate near the zone boundaries for very large scenarios that span multiple UTM zones. It is recommended that EMANE location scripts be used to achieve geo-location accuracy in this situation.
Clicking the green Start button launches the emulation and causes TAP devices to be created in the virtual nodes that are linked to the EMANE WLAN. These devices appear with interface names such as eth0, eth1, etc. The EMANE processes should now be running in each namespace.
To view the configuration generated by CORE, look in the /tmp/pycore.nnnnn/ session directory to find the generated EMANE xml files. One easy way to view this information is by double-clicking one of the virtual nodes and listing the files in the shell.
"},{"location":"emane.html#distributed-emane","title":"Distributed EMANE","text":"Running CORE and EMANE distributed among two or more emulation servers is similar to running on a single machine. There are a few key configuration items that need to be set in order to be successful, and those are outlined here.
It is a good idea to maintain separate networks for data (OTA) and control. The control network may be a shared laboratory network, for example, and you do not want multicast traffic on the data network to interfere with other EMANE users. Furthermore, control traffic could interfere with the OTA latency and throughput and might affect emulation fidelity. The examples described here will use eth0 as a control interface and eth1 as a data interface, although using separate interfaces is not strictly required. Note that these interface names refer to interfaces present on the host machine, not virtual interfaces within a node.
IMPORTANT: If an auxiliary control network is used, an interface on the host has to be assigned to that network.
Each machine that will act as an emulation server needs to have CORE distributed and EMANE installed. As well as be setup to work for CORE distributed mode.
The IP addresses of the available servers are configured from the CORE servers dialog box. The dialog shows available servers, some or all of which may be assigned to nodes on the canvas.
Nodes need to be assigned to servers and can be done so using the node configuration dialog. When a node is not assigned to any emulation server, it will be emulated locally.
Using the EMANE node configuration dialog. You can change the EMANE model being used, along with changing any configuration setting from their defaults.
Note
Here is a quick checklist for distributed emulation with EMANE.
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 to nodes. Each server will have its own session directory where the platform.xml file and other EMANE XML files are generated. The NEM IDs are automatically coordinated across servers so there is no overlap.
An Ethernet device is used for disseminating multicast EMANE events, as specified in the configure emane dialog. EMANE's Event Service can be run with mobility or pathloss scripts. If CORE is not subscribed to location events, it will generate them as nodes are moved on the canvas.
Double-clicking on a node during runtime will cause the GUI to attempt to SSH to the emulation server for that node and run an interactive shell. The public key SSH configuration should be tested with all emulation servers prior to starting the emulation.
"},{"location":"grpc.html","title":"gRPC","text":"gRPC is a client/server API for interfacing with CORE and used by the python GUI for driving all functionality. It is dependent on having a running core-daemon instance to be leveraged.
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 some functionality to try and help make things easier.
"},{"location":"grpc.html#python-client","title":"Python Client","text":"A python client wrapper is provided at CoreGrpcClient to help provide some conveniences when using the API.
"},{"location":"grpc.html#client-http-proxy","title":"Client HTTP Proxy","text":"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. You can enable and properly account for this issue when needed.
"},{"location":"grpc.html#proto-files","title":"Proto Files","text":"Proto files are used to define the API and protobuf messages that are used for interfaces with this API.
They can be found here to see the specifics of what is going on and response message values that would be returned.
"},{"location":"grpc.html#examples","title":"Examples","text":""},{"location":"grpc.html#node-models","title":"Node Models","text":"When creating nodes of type NodeType.DEFAULT these are the default models and the services they map to.
There is an interface helper class that can be leveraged for convenience when creating interface data for nodes. Alternatively one can manually create a core.api.grpc.wrappers.Interface class instead with appropriate information.
Manually creating gRPC client interface:
from core.api.grpc.wrappers import Interface\n\n# id is optional and will set to the next available id\n# name is optional and will default to eth<id>\n# mac is optional and will result in a randomly generated mac\niface = Interface(\n id=0,\n name=\"eth0\",\n ip4=\"10.0.0.1\",\n ip4_mask=24,\n ip6=\"2001::\",\n ip6_mask=64,\n)\nLeveraging the interface helper class:
from core.api.grpc import client\n\niface_helper = client.InterfaceHelper(ip4_prefix=\"10.0.0.0/24\", ip6_prefix=\"2001::/64\")\n# node_id is used to get an ip4/ip6 address indexed from within the above prefixes\n# iface_id is required and used exactly for that\n# name is optional and would default to eth<id>\n# mac is optional and will result in a randomly generated mac\niface_data = iface_helper.create_iface(\n node_id=1, iface_id=0, name=\"eth0\", mac=\"00:00:00:00:aa:00\"\n)\nVarious events that can occur within a session can be listened to.
Event types:
from core.api.grpc import client\nfrom core.api.grpc.wrappers import EventType\n\n\ndef event_listener(event):\n print(event)\n\n\n# create grpc client and connect\ncore = client.CoreGrpcClient()\ncore.connect()\n\n# add session\nsession = core.create_session()\n\n# provide no events to listen to all events\ncore.events(session.id, event_listener)\n\n# provide events to listen to specific events\ncore.events(session.id, event_listener, [EventType.NODE])\nLinks can be configured at the time of creation or during runtime.
Currently supported configuration options:
from core.api.grpc import client\nfrom core.api.grpc.wrappers import LinkOptions, Position\n\n# interface helper\niface_helper = client.InterfaceHelper(ip4_prefix=\"10.0.0.0/24\", ip6_prefix=\"2001::/64\")\n\n# create grpc client and connect\ncore = client.CoreGrpcClient()\ncore.connect()\n\n# add session\nsession = core.create_session()\n\n# create nodes\nposition = Position(x=100, y=100)\nnode1 = session.add_node(1, position=position)\nposition = Position(x=300, y=100)\nnode2 = session.add_node(2, position=position)\n\n# configuring when creating a link\noptions = LinkOptions(\n bandwidth=54_000_000,\n delay=5000,\n dup=5,\n loss=5.5,\n jitter=0,\n)\niface1 = iface_helper.create_iface(node1.id, 0)\niface2 = iface_helper.create_iface(node2.id, 0)\nlink = session.add_link(node1=node1, node2=node2, iface1=iface1, iface2=iface2)\n\n# configuring during runtime\nlink.options.loss = 10.0\ncore.edit_link(session.id, link)\n# required imports\nfrom core.api.grpc import client\nfrom core.api.grpc.wrappers import Position\n\n# interface helper\niface_helper = client.InterfaceHelper(ip4_prefix=\"10.0.0.0/24\", ip6_prefix=\"2001::/64\")\n\n# create grpc client and connect\ncore = client.CoreGrpcClient()\ncore.connect()\n\n# add session\nsession = core.create_session()\n\n# create nodes\nposition = Position(x=100, y=100)\nnode1 = session.add_node(1, position=position)\nposition = Position(x=300, y=100)\nnode2 = session.add_node(2, position=position)\n\n# create link\niface1 = iface_helper.create_iface(node1.id, 0)\niface2 = iface_helper.create_iface(node2.id, 0)\nsession.add_link(node1=node1, node2=node2, iface1=iface1, iface2=iface2)\n\n# start session\ncore.start_session(session)\n# required imports\nfrom core.api.grpc import client\nfrom core.api.grpc.wrappers import NodeType, Position\n\n# interface helper\niface_helper = client.InterfaceHelper(ip4_prefix=\"10.0.0.0/24\", ip6_prefix=\"2001::/64\")\n\n# create grpc client and connect\ncore = client.CoreGrpcClient()\ncore.connect()\n\n# add session\nsession = core.create_session()\n\n# create nodes\nposition = Position(x=200, y=200)\nswitch = session.add_node(1, _type=NodeType.SWITCH, position=position)\nposition = Position(x=100, y=100)\nnode1 = session.add_node(2, position=position)\nposition = Position(x=300, y=100)\nnode2 = session.add_node(3, position=position)\n\n# create links\niface1 = iface_helper.create_iface(node1.id, 0)\nsession.add_link(node1=node1, node2=switch, iface1=iface1)\niface1 = iface_helper.create_iface(node2.id, 0)\nsession.add_link(node1=node2, node2=switch, iface1=iface1)\n\n# start session\ncore.start_session(session)\n# required imports\nfrom core.api.grpc import client\nfrom core.api.grpc.wrappers import NodeType, Position\n\n# interface helper\niface_helper = client.InterfaceHelper(ip4_prefix=\"10.0.0.0/24\", ip6_prefix=\"2001::/64\")\n\n# create grpc client and connect\ncore = client.CoreGrpcClient()\ncore.connect()\n\n# add session\nsession = core.create_session()\n\n# create nodes\nposition = Position(x=200, y=200)\nwlan = session.add_node(1, _type=NodeType.WIRELESS_LAN, position=position)\nposition = Position(x=100, y=100)\nnode1 = session.add_node(2, model=\"mdr\", position=position)\nposition = Position(x=300, y=100)\nnode2 = session.add_node(3, model=\"mdr\", position=position)\n\n# create links\niface1 = iface_helper.create_iface(node1.id, 0)\nsession.add_link(node1=node1, node2=wlan, iface1=iface1)\niface1 = iface_helper.create_iface(node2.id, 0)\nsession.add_link(node1=node2, node2=wlan, iface1=iface1)\n\n# set wlan config using a dict mapping currently\n# support values as strings\nwlan.set_wlan(\n {\n \"range\": \"280\",\n \"bandwidth\": \"55000000\",\n \"delay\": \"6000\",\n \"jitter\": \"5\",\n \"error\": \"5\",\n }\n)\n\n# start session\ncore.start_session(session)\nFor EMANE you can import and use one of the existing models and use its name for configuration.
Current models:
Their configurations options are driven dynamically from parsed EMANE manifest files from the installed version of EMANE.
Options and their purpose can be found at the EMANE Wiki.
If configuring EMANE global settings or model mac/phy specific settings, any value not provided will use the defaults. When no configuration is used, the defaults are used.
# required imports\nfrom core.api.grpc import client\nfrom core.api.grpc.wrappers import NodeType, Position\nfrom core.emane.models.ieee80211abg import EmaneIeee80211abgModel\n\n# interface helper\niface_helper = client.InterfaceHelper(ip4_prefix=\"10.0.0.0/24\", ip6_prefix=\"2001::/64\")\n\n# create grpc client and connect\ncore = client.CoreGrpcClient()\ncore.connect()\n\n# add session\nsession = core.create_session()\n\n# create nodes\nposition = Position(x=200, y=200)\nemane = session.add_node(\n 1, _type=NodeType.EMANE, position=position, emane=EmaneIeee80211abgModel.name\n)\nposition = Position(x=100, y=100)\nnode1 = session.add_node(2, model=\"mdr\", position=position)\nposition = Position(x=300, y=100)\nnode2 = session.add_node(3, model=\"mdr\", position=position)\n\n# create links\niface1 = iface_helper.create_iface(node1.id, 0)\nsession.add_link(node1=node1, node2=emane, iface1=iface1)\niface1 = iface_helper.create_iface(node2.id, 0)\nsession.add_link(node1=node2, node2=emane, iface1=iface1)\n\n# setting emane specific emane model configuration\nemane.set_emane_model(EmaneIeee80211abgModel.name, {\n \"eventservicettl\": \"2\",\n \"unicastrate\": \"3\",\n})\n\n# start session\ncore.start_session(session)\nEMANE Model Configuration:
# emane network specific config, set on an emane node\n# this setting applies to all nodes connected\nemane.set_emane_model(EmaneIeee80211abgModel.name, {\"unicastrate\": \"3\"})\n\n# node specific config for an individual node connected to an emane network\nnode.set_emane_model(EmaneIeee80211abgModel.name, {\"unicastrate\": \"3\"})\n\n# node interface specific config for an individual node connected to an emane network\nnode.set_emane_model(EmaneIeee80211abgModel.name, {\"unicastrate\": \"3\"}, iface_id=0)\nServices help generate and run bash scripts on nodes for a given purpose.
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.
The following features can be configured for a service:
Editing service properties:
# configure a service, for a node, for a given session\nnode.service_configs[service_name] = NodeServiceData(\n configs=[\"file1.sh\", \"file2.sh\"],\n directories=[\"/etc/node\"],\n startup=[\"bash file1.sh\"],\n validate=[],\n shutdown=[],\n)\nWhen editing a service file, it must be the name of config file that the service will generate.
Editing a service file:
# to edit the contents of a generated file you can specify\n# the service, the file name, and its contents\nfile_configs = node.service_file_configs.setdefault(service_name, {})\nfile_configs[file_name] = \"echo hello world\"\nFile versions of the network examples can be found here. These examples will create a session using the gRPC API when the core-daemon is running.
You can then switch to and attach to these sessions using either of the CORE GUIs.
"},{"location":"gui.html","title":"CORE GUI","text":""},{"location":"gui.html#overview","title":"Overview","text":"The GUI is used to draw nodes and network devices on a canvas, linking them together to create an emulated network session.
After pressing the start button, CORE will proceed through these phases, staying in the runtime phase. After the session is stopped, CORE will proceed to the data collection phase before tearing down the emulated state.
CORE can be customized to perform any action at each state. See the Hooks... entry on the Session Menu for details about when these session states are reached.
"},{"location":"gui.html#prerequisites","title":"Prerequisites","text":"Beyond installing CORE, you must have the CORE daemon running. This is done on the command line with either systemd or sysv.
# systemd service\nsudo systemctl daemon-reload\nsudo systemctl start core-daemon\n\n# direct invocation\nsudo core-daemon\nThe GUI will create a directory in your home directory on first run called ~/.coregui. This directory will help layout various files that the GUI may use.
The CORE GUI has two primary modes of operation, Edit and Execute modes. Running the GUI, by typing core-gui with no options, starts in Edit mode. Nodes are drawn on a blank canvas using the toolbar on the left and configured from right-click menus or by double-clicking them. The GUI does not need to be run as root.
Once editing is complete, pressing the green Start button instantiates the topology and enters Execute mode. In execute mode, the user can interact with the running emulated machines by double-clicking or right-clicking on them. The editing toolbar disappears and is replaced by an execute toolbar, which provides tools while running the emulation. Pressing the red Stop button will destroy the running emulation and return CORE to Edit mode.
Once the emulation is running, the GUI can be closed, and a prompt will appear asking if the emulation should be terminated. The emulation may be left running and the GUI can reconnect to an existing session at a later time.
The GUI can be run as a normal user on Linux.
The GUI currently provides the following options on startup.
usage: core-gui [-h] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-p]\n[-s SESSION] [--create-dir]\n\nCORE Python GUI\n\noptional arguments:\n -h, --help show this help message and exit\n-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --level {DEBUG,INFO,WARNING,ERROR,CRITICAL}\nlogging level\n -p, --proxy enable proxy\n -s SESSION, --session SESSION\n session id to join\n --create-dir create gui directory and exit\nThe toolbar is a row of buttons that runs vertically along the left side of the CORE GUI window. The toolbar changes depending on the mode of operation.
"},{"location":"gui.html#editing-toolbar","title":"Editing Toolbar","text":"When CORE is in Edit mode (the default), the vertical Editing Toolbar exists on the left side of the CORE window. Below are brief descriptions for each toolbar item, starting from the top. Most of the tools are grouped into related sub-menus, which appear when you click on their group icon.
Icon Name Description Selection Tool Tool for selecting, moving, configuring nodes. Start Button Starts Execute mode, instantiates the emulation. Link Allows network links to be drawn between two nodes by clicking and dragging the mouse."},{"location":"gui.html#core-nodes","title":"CORE Nodes","text":"These nodes will create a new node container and run associated services.
Icon Name Description Router Runs Quagga OSPFv2 and OSPFv3 routing to forward packets. Host Emulated server machine having a default route, runs SSH server. PC Basic emulated machine having a default route, runs no processes by default. MDR Runs Quagga OSPFv3 MDR routing for MANET-optimized routing. PRouter Physical router represents a real testbed machine."},{"location":"gui.html#network-nodes","title":"Network Nodes","text":"These nodes are mostly used to create a Linux bridge that serves the purpose described below.
Icon Name Description Hub Ethernet hub forwards incoming packets to every connected node. Switch Ethernet switch intelligently forwards incoming packets to attached hosts using an Ethernet address hash table. Wireless LAN When routers are connected to this WLAN node, they join a wireless network and an antenna is drawn instead of a connecting line; the WLAN node typically controls connectivity between attached wireless nodes based on the distance between them. RJ45 RJ45 Physical Interface Tool, emulated nodes can be linked to real physical interfaces; using this tool, real networks and devices can be physically connected to the live-running emulation. Tunnel Tool allows connecting together more than one CORE emulation using GRE tunnels."},{"location":"gui.html#annotation-tools","title":"Annotation Tools","text":"Icon Name Description Marker For drawing marks on the canvas. Oval For drawing circles on the canvas that appear in the background. Rectangle For drawing rectangles on the canvas that appear in the background. Text For placing text captions on the canvas."},{"location":"gui.html#execution-toolbar","title":"Execution Toolbar","text":"When the Start button is pressed, CORE switches to Execute mode, and the Edit toolbar on the left of the CORE window is replaced with the Execution toolbar Below are the items on this toolbar, starting from the top.
Icon Name Description Stop Button Stops Execute mode, terminates the emulation, returns CORE to edit mode. Selection Tool In Execute mode, the Selection Tool can be used for moving nodes around the canvas, and double-clicking on a node will open a shell window for that node; right-clicking on a node invokes a pop-up menu of run-time options for that node. Marker For drawing freehand lines on the canvas, useful during demonstrations; markings are not saved. Run Tool This tool allows easily running a command on all or a subset of all nodes. A list box allows selecting any of the nodes. A text entry box allows entering any command. The command should return immediately, otherwise the display will block awaiting response. The ping command, for example, with no parameters, is not a good idea. The result of each command is displayed in a results box. The first occurrence of the special text \"NODE\" will be replaced with the node name. The command will not be attempted to run on nodes that are not routers, PCs, or hosts, even if they are selected."},{"location":"gui.html#menu","title":"Menu","text":"The menubar runs along the top of the CORE GUI window and provides access to a variety of features. Some of the menus are detachable, such as the Widgets menu, by clicking the dashed line at the top.
"},{"location":"gui.html#file-menu","title":"File Menu","text":"The File menu contains options for saving and opening saved sessions.
Option Description New Session This starts a new session with an empty canvas. Save Saves the current topology. If you have not yet specified a file name, the Save As dialog box is invoked. Save As Invokes the Save As dialog box for selecting a new .xml file for saving the current configuration in the XML file. Open Invokes the File Open dialog box for selecting a new XML file to open. Recently used files Above the Quit menu command is a list of recently use files, if any have been opened. You can clear this list in the Preferences dialog box. You can specify the number of files to keep in this list from the Preferences dialog. Click on one of the file names listed to open that configuration file. Execute Python Script Invokes a File Open dialog box for selecting a Python script to run and automatically connect to. After a selection is made, a Python Script Options dialog box is invoked to allow for command-line options to be added. The Python script must create a new CORE Session and add this session to the daemon's list of sessions in order for this to work. Quit The Quit command should be used to exit the CORE GUI. CORE may prompt for termination if you are currently in Execute mode. Preferences and the recently-used files list are saved."},{"location":"gui.html#edit-menu","title":"Edit Menu","text":"Option Description Preferences Invokes the Preferences dialog box. Custom Nodes Custom node creation dialog box. Undo (Disabled) Attempts to undo the last edit in edit mode. Redo (Disabled) Attempts to redo an edit that has been undone. Cut, Copy, Paste, Delete Used to cut, copy, paste, and delete a selection. When nodes are pasted, their node numbers are automatically incremented, and existing links are preserved with new IP addresses assigned. Services and their customizations are copied to the new node, but care should be taken as node IP addresses have changed with possibly old addresses remaining in any custom service configurations. Annotations may also be copied and pasted."},{"location":"gui.html#canvas-menu","title":"Canvas Menu","text":"The canvas menu provides commands related to the editing canvas.
Option Description Size/scale Invokes a Canvas Size and Scale dialog that allows configuring the canvas size, scale, and geographic reference point. The size controls allow changing the width and height of the current canvas, in pixels or meters. The scale allows specifying how many meters are equivalent to 100 pixels. The reference point controls specify the latitude, longitude, and altitude reference point used to convert between geographic and Cartesian coordinate systems. By clicking the Save as default option, all new canvases will be created with these properties. The default canvas size can also be changed in the Preferences dialog box. Wallpaper Used for setting the canvas background image."},{"location":"gui.html#view-menu","title":"View Menu","text":"The View menu features items for toggling on and off their display on the canvas.
Option Description Interface Names Display interface names on links. IPv4 Addresses Display IPv4 addresses on links. IPv6 Addresses Display IPv6 addresses on links. Node Labels Display node names. Link Labels Display link labels. Annotations Display annotations. Canvas Grid Display the canvas grid."},{"location":"gui.html#tools-menu","title":"Tools Menu","text":"The tools menu lists different utility functions.
Option Description Find Display find dialog used for highlighting a node on the canvas. Auto Grid Automatically layout nodes in a grid. IP addresses Invokes the IP Addresses dialog box for configuring which IPv4/IPv6 prefixes are used when automatically addressing new interfaces. MAC addresses Invokes the MAC Addresses dialog box for configuring the starting number used as the lowest byte when generating each interface MAC address. This value should be changed when tunneling between CORE emulations to prevent MAC address conflicts."},{"location":"gui.html#widgets-menu","title":"Widgets Menu","text":"Widgets are GUI elements that allow interaction with a running emulation. Widgets typically automate the running of commands on emulated nodes to report status information of some type and display this on screen.
"},{"location":"gui.html#periodic-widgets","title":"Periodic Widgets","text":"These Widgets are those available from the main Widgets menu. More than one of these Widgets may be run concurrently. An event loop fires once every second that the emulation is running. If one of these Widgets is enabled, its periodic routine will be invoked at this time. Each Widget may have a configuration dialog box which is also accessible from the Widgets menu.
Here are some standard widgets:
These Widgets are available from the Observer Widgets submenu of the Widgets menu, and from the Widgets Tool on the toolbar. Only one Observer Widget may be used at a time. Mouse over a node while the session is running to pop up an informational display about that node.
Available Observer Widgets include IPv4 and IPv6 routing tables, socket information, list of running processes, and OSPFv2/v3 neighbor information.
Observer Widgets may be edited by the user and rearranged. Choosing Widgets->Observer Widgets->Edit Observers from the Observer Widget menu will invoke the Observer Widgets dialog. A list of Observer Widgets is displayed along with up and down arrows for rearranging the list. Controls are available for renaming each widget, for changing the command that is run during mouse over, and for adding and deleting items from the list. Note that specified commands should return immediately to avoid delays in the GUI display. Changes are saved to a config.yaml file in the CORE configuration directory.
"},{"location":"gui.html#session-menu","title":"Session Menu","text":"The Session Menu has entries for starting, stopping, and managing sessions, in addition to global options such as node types, comments, hooks, servers, and options.
Option Description Sessions Invokes the CORE Sessions dialog box containing a list of active CORE sessions in the daemon. Basic session information such as name, node count, start time, and a thumbnail are displayed. This dialog allows connecting to different sessions, shutting them down, or starting a new session. Servers Invokes the CORE emulation servers dialog for configuring. Options Presents per-session options, such as the IPv4 prefix to be used, if any, for a control network the ability to preserve the session directory; and an on/off switch for SDT3D support. Hooks Invokes the CORE Session Hooks window where scripts may be configured for a particular session state. The session states are defined in the table below. The top of the window has a list of configured hooks, and buttons on the bottom left allow adding, editing, and removing hook scripts. The new or edit button will open a hook script editing window. A hook script is a shell script invoked on the host (not within a virtual node)."},{"location":"gui.html#session-states","title":"Session States","text":"State Description Definition Used by the GUI to tell the backend to clear any state. Configuration When the user presses the Start button, node, link, and other configuration data is sent to the backend. This state is also reached when the user customizes a service. Instantiation After configuration data has been sent, just before the nodes are created. Runtime All nodes and networks have been built and are running. (This is the same state at which the previously-named global experiment script was run.) Datacollect The user has pressed the Stop button, but before services have been stopped and nodes have been shut down. This is a good time to collect log files and other data from the nodes. Shutdown All nodes and networks have been shut down and destroyed."},{"location":"gui.html#help-menu","title":"Help Menu","text":"Option Description CORE Github (www) Link to the CORE GitHub page. CORE Documentation (www) Lnk to the CORE Documentation page. About Invokes the About dialog box for viewing version information."},{"location":"gui.html#building-sample-networks","title":"Building Sample Networks","text":""},{"location":"gui.html#wired-networks","title":"Wired Networks","text":"Wired networks are created using the Link Tool to draw a link between two nodes. This automatically draws a red line representing an Ethernet link and creates new interfaces on network-layer nodes.
Double-click on the link to invoke the link configuration dialog box. Here you can change the Bandwidth, Delay, Loss, and Duplicate rate parameters for that link. You can also modify the color and width of the link, affecting its display.
Link-layer nodes are provided for modeling wired networks. These do not create a separate network stack when instantiated, but are implemented using Linux bridging. These are the hub, switch, and wireless LAN nodes. The hub copies each packet from the incoming link to every connected link, while the switch behaves more like an Ethernet switch and keeps track of the Ethernet address of the connected peer, forwarding unicast traffic only to the appropriate ports.
The wireless LAN (WLAN) is covered in the next section.
"},{"location":"gui.html#wireless-networks","title":"Wireless Networks","text":"Wireless networks allow moving nodes around to impact the connectivity between them. Connections between a pair of nodes is stronger when the nodes are closer while connection is weaker when the nodes are further away. CORE offers several levels of wireless emulation fidelity, depending on modeling needs and available hardware.
To quickly build a wireless network, you can first place several router nodes onto the canvas. If you have the Quagga MDR software installed, it is recommended that you use the mdr node type for reduced routing overhead. Next choose the WLAN from the Link-layer nodes submenu. First set the desired WLAN parameters by double-clicking the cloud icon. Then you can link all selected right-clicking on the WLAN and choosing Link to Selected.
Linking a router to the WLAN causes a small antenna to appear, but no red link line is drawn. Routers can have multiple wireless links and both wireless and wired links (however, you will need to manually configure route redistribution.) The mdr node type will generate a routing configuration that enables OSPFv3 with MANET extensions. This is a Boeing-developed extension to Quagga's OSPFv3 that reduces flooding overhead and optimizes the flooding procedure for mobile ad-hoc (MANET) networks.
The default configuration of the WLAN is set to use the basic range model. Having this model selected causes core-daemon to calculate the distance between nodes based on screen pixels. A numeric range in screen pixels is set for the wireless network using the Range slider. When two wireless nodes are within range of each other, a green line is drawn between them and they are linked. Two wireless nodes that are farther than the range pixels apart are not linked. During Execute mode, users may move wireless nodes around by clicking and dragging them, and wireless links will be dynamically made or broken.
"},{"location":"gui.html#running-commands-within-nodes","title":"Running Commands within Nodes","text":"You can double click a node to bring up a terminal for running shell commands. Within the terminal you can run anything you like and those commands will be run in context of the node. For standard CORE nodes, the only thing to keep in mind is that you are using the host file system and anything you change or do can impact the greater system. By default, your terminal will open within the nodes home directory for the running session, but it is temporary and will be removed when the session is stopped.
You can also launch GUI based applications from within standard CORE nodes, but you need to enable xhost access to root.
xhost +local:root\nCORE has a few ways to script mobility.
Option Description ns-2 script The script specifies either absolute positions or waypoints with a velocity. Locations are given with Cartesian coordinates. gRPC API An external entity can move nodes by leveraging the gRPC API EMANE events See EMANE 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 editor, or using a tool such as BonnMotion, and associate the script with one of the wireless using the WLAN configuration dialog box. Click the ns-2 mobility script... button, and set the mobility script file field in the resulting ns2script configuration dialog.
Here is an example for creating a BonnMotion script for 10 nodes:
bm -f sample RandomWaypoint -n 10 -d 60 -x 1000 -y 750\nbm NSFile -f sample\n# use the resulting 'sample.ns_movements' file in CORE\nWhen the Execute mode is started and one of the WLAN nodes has a mobility script, a mobility script window will appear. This window contains controls for starting, stopping, and resetting the running time for the mobility script. The loop checkbox causes the script to play continuously. The resolution text box contains the number of milliseconds between each timer event; lower values cause the mobility to appear smoother but consumes greater CPU time.
The format of an ns-2 mobility script looks like:
# nodes: 3, max time: 35.000000, max x: 600.00, max y: 600.00\n$node_(2) set X_ 144.0\n$node_(2) set Y_ 240.0\n$node_(2) set Z_ 0.00\n$ns_ at 1.00 \"$node_(2) setdest 130.0 280.0 15.0\"\nThe first three lines set an initial position for node 2. The last line in the above example causes node 2 to move towards the destination (130, 280) at speed 15. All units are screen coordinates, with speed in units per second. The total script time is learned after all nodes have reached their waypoints. Initially, the time slider in the mobility script dialog will not be accurate.
Examples mobility scripts (and their associated topology files) can be found in the configs/ directory.
"},{"location":"gui.html#alerts","title":"Alerts","text":"The alerts button is located in the bottom right-hand corner of the status bar in the CORE GUI. This will change colors to indicate one or more problems with the running emulation. Clicking on the alerts button will invoke the alerts dialog.
The alerts dialog contains a list of alerts received from the CORE daemon. An alert has a time, severity level, optional node number, and source. When the alerts button is red, this indicates one or more fatal exceptions. An alert with a fatal severity level indicates that one or more of the basic pieces of emulation could not be created, such as failure to create a bridge or namespace, or the failure to launch EMANE processes for an EMANE-based network.
Clicking on an alert displays details for that exceptio. The exception source is a text string to help trace where the exception occurred; \"service:UserDefined\" for example, would appear for a failed validation command with the UserDefined service.
A button is available at the bottom of the dialog for clearing the exception list.
"},{"location":"gui.html#customizing-your-topologys-look","title":"Customizing your Topology's Look","text":"Several annotation tools are provided for changing the way your topology is presented. Captions may be added with the Text tool. Ovals and rectangles may be drawn in the background, helpful for visually grouping nodes together.
During live demonstrations the marker tool may be helpful for drawing temporary annotations on the canvas that may be quickly erased. A size and color palette appears at the bottom of the toolbar when the marker tool is selected. Markings are only temporary and are not saved in the topology file.
The basic node icons can be replaced with a custom image of your choice. Icons appear best when they use the GIF or PNG format with a transparent background. To change a node's icon, double-click the node to invoke its configuration dialog and click on the button to the right of the node name that shows the node's current icon.
A background image for the canvas may be set using the Wallpaper... option from the Canvas menu. The image may be centered, tiled, or scaled to fit the canvas size. An existing terrain, map, or network diagram could be used as a background, for example, with CORE nodes drawn on top.
"},{"location":"hitl.html","title":"Hardware In The Loop","text":""},{"location":"hitl.html#overview","title":"Overview","text":"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.
"},{"location":"hitl.html#rj45-node","title":"RJ45 Node","text":"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.
"},{"location":"hitl.html#gui-usage","title":"GUI Usage","text":"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.
"},{"location":"hitl.html#multiple-rj45s-with-one-interface-vlan","title":"Multiple RJ45s with One Interface (VLAN)","text":"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:
ip link add link eth0 name eth0.1 type vlan id 1\nip link add link eth0 name eth0.2 type vlan id 2\nip link add link eth0 name eth0.3 type vlan id 3\nThe 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.
"},{"location":"hitl.html#example-usage","title":"Example Usage","text":"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.
# these commands are run on the tunnel peer\nsudo ip link add gt0 type gretap remote 198.51.100.34 local 198.51.100.76 key 1\nsudo ip addr add 10.0.0.2/24 dev gt0\nsudo ip link set dev gt0 up\nNow the virtual router should be able to ping the Linux machine:
# from the CORE router node\nping 10.0.0.2\nAnd the Linux machine should be able to ping inside the CORE emulation:
# from the tunnel peer\nping 10.0.0.1\nTo 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.
"},{"location":"install.html","title":"Installation","text":"Warning
If Docker is installed, the default iptable rules will block CORE traffic
"},{"location":"install.html#overview","title":"Overview","text":"CORE currently supports and provides the following installation options, with the package option being preferred.
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.
Plan is to support recent Ubuntu and CentOS LTS releases.
Verified:
The following is a list of files that would be installed after installation.
<prefix>/bin/{vcmd, vnode}/opt/core/venvpython3 -c \"import core; print(core.__file__)\"/opt/core/venv/bin/usr/local/bin/etc/core/{core.conf, logging.conf}<repo>/../ospf-mdrThe following python scripts are provided.
Name Description core-cleanup tool to help removed lingering core created containers, bridges, directories core-cli tool to query, open xml files, and send commands using gRPC core-daemon runs the backed core server providing a gRPC API core-gui starts GUI core-python provides a convenience for running the core python virtual environment core-route-monitor tool to help monitor traffic across nodes and feed that to SDT core-service-update tool to update automate modifying a legacy service to match current naming"},{"location":"install.html#upgrading-from-older-release","title":"Upgrading from Older Release","text":"Please make sure to uninstall any previous installations of CORE cleanly before proceeding to install.
Clearing out a current install from 7.0.0+, making sure to provide options used for install (-l or -p).
cd <CORE_REPO>\ninv uninstall <options>\nPrevious install was built from source for CORE release older than 7.0.0:
cd <CORE_REPO>\nsudo make uninstall\nmake clean\n./bootstrap.sh clean\nInstalled from previously built packages:
# centos\nsudo yum remove core\n# ubuntu\nsudo apt remove core\nThe below links will take you to sections providing complete examples for installing CORE and related utilities on fresh installations. Otherwise, a breakdown for installing different components and the options available are detailed below.
Starting with 9.0.0 there are pre-built rpm/deb packages. You can retrieve the rpm/deb package from releases page.
The built packages will require and install system level dependencies, as well as running a post install script to install the provided CORE python wheel. A similar uninstall script is ran when uninstalling and would require the same options as given, during the install.
Note
PYTHON defaults to python3 for installs below, CORE requires python3.9+, pip, tk compatibility for python gui, and venv for virtual environments
Examples for install:
# recommended to upgrade to the latest version of pip before installation\n# in python, can help avoid building from source issues\nsudo <python> -m pip install --upgrade pip\n# install vcmd/vnoded, system dependencies,\n# and core python into a venv located at /opt/core/venv\nsudo <yum/apt> install -y ./<package>\n# disable the venv and install to python directly\nsudo NO_VENV=1 <yum/apt> install -y ./<package>\n# change python executable used to install for venv or direct installations\nsudo PYTHON=python3.9 <yum/apt> install -y ./<package>\n# disable venv and change python executable\nsudo NO_VENV=1 PYTHON=python3.9 <yum/apt> install -y ./<package>\n# skip installing the python portion entirely, as you plan to carry this out yourself\n# core python wheel is located at /opt/core/core-<version>-py3-none-any.whl\nsudo NO_PYTHON=1 <yum/apt> install -y ./<package>\n# install python wheel into python of your choosing\nsudo <python> -m pip install /opt/core/core-<version>-py3-none-any.whl\nExample for removal, requires using the same options as install:
# remove a standard install\nsudo <yum/apt> remove core\n# remove a local install\nsudo NO_VENV=1 <yum/apt> remove core\n# remove install using alternative python\nsudo PYTHON=python3.9 <yum/apt> remove core\n# remove install using alternative python and local install\nsudo NO_VENV=1 PYTHON=python3.9 <yum/apt> remove core\n# remove install and skip python uninstall\nsudo NO_PYTHON=1 <yum/apt> remove core\nYou will need to manually install OSPF MDR for routing nodes, since this is not provided by the package.
git clone https://github.com/USNavalResearchLaboratory/ospf-mdr.git\ncd ospf-mdr\n./bootstrap.sh\n./configure --disable-doc --enable-user=root --enable-group=root \\\n--with-cflags=-ggdb --sysconfdir=/usr/local/etc/quagga --enable-vtysh \\\n--localstatedir=/var/run/quagga\nmake -j$(nproc)\nsudo make install\nWhen done see Post Install.
"},{"location":"install.html#script-based-install","title":"Script Based Install","text":"The script based installation will install system level dependencies, python library and dependencies, as well as dependencies for building CORE.
The script based install also automatically builds and installs OSPF MDR, used by default on routing nodes. This can optionally be skipped.
Installaion will carry out the following steps:
Note
Installing locally comes with its own risks, it can result it potential dependency conflicts with system package manager installed python dependencies
Note
Provide a prefix that will be found on path when running as sudo, if the default prefix /usr/local will not be valid
The following tools will be leveraged during installation:
Tool Description pip used to install pipx pipx used to install standalone python tools (invoke, poetry) invoke used to run provided tasks (install, uninstall, reinstall, etc) poetry used to install python virtual environment or building a python wheelFirst we will need to clone and navigate to the CORE repo.
# clone CORE repo\ngit clone https://github.com/coreemu/core.git\ncd core\n\n# install dependencies to run installation task\n./setup.sh\n# skip installing system packages, due to using python built from source\nNO_SYSTEM=1 ./setup.sh\n\n# run the following or open a new terminal\nsource ~/.bashrc\n\n# Ubuntu\ninv install\n# CentOS\ninv install -p /usr\n# optionally skip python system packages\ninv install --no-python\n# optionally skip installing ospf mdr\ninv install --no-ospf\n\n# install command options\nUsage: inv[oke] [--core-opts] install [--options] [other tasks here ...]\n\nDocstring:\n install core, poetry, scripts, service, and ospf mdr\n\nOptions:\n -d, --dev install development mode\n -i STRING, --install-type=STRING used to force an install type, can be one of the following (redhat, debian)\n-l, --local determines if core will install to local system, default is False\n -n, --no-python avoid installing python system dependencies\n -o, --[no-]ospf disable ospf installation\n -p STRING, --prefix=STRING prefix where scripts are installed, default is /usr/local\n -v, --verbose\nWhen done see Post Install.
"},{"location":"install.html#unsupported-linux-distribution","title":"Unsupported Linux Distribution","text":"For unsupported OSs you could attempt to do the following to translate an installation to your use case.
<repo>/tasks.py# this will print the commands that would be ran for a given installation\n# type without actually running them, they may help in being used as\n# the basis for translating to your OS\ninv install --dry -v -p <prefix> -i <install type>\nYou 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, make sure to update and build the Dockerfile with desired software.
# clone core\ngit clone https://github.com/coreemu/core.git\ncd core\n# build image\nsudo docker build -t core -f dockerfiles/Dockerfile.<centos,ubuntu> .\n# start container\nsudo docker run -itd --name core -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix:rw --privileged core\n# enable xhost access to the root user\nxhost +local:root\n# launch core-gui\nsudo docker exec -it core core-gui\nWhen done see Post Install.
"},{"location":"install.html#installing-emane","title":"Installing EMANE","text":"Note
Installing EMANE for the virtual environment is known to work for 1.21+
The recommended way to install EMANE is using prebuilt packages, otherwise you can follow their instructions for installing from source. Installation information can be found here.
There is an invoke task to help install the EMANE bindings into the CORE virtual environment, when needed. An example for running the task is below and the version provided should match the version of the packages installed.
You will also need to make sure, you are providing the correct python binary where CORE is being used.
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.
Examples for building and installing EMANE python bindings for use in CORE:
# if your system does not have protoc 3.19+\nwget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip\nmkdir protoc\nunzip protoc-3.19.6-linux-x86_64.zip -d protoc\ngit clone https://github.com/adjacentlink/emane.git\ncd emane\ngit checkout v1.3.3\n./autogen.sh\nPYTHON=/opt/core/venv/bin/python ./configure --prefix=/usr\ncd src/python\nPATH=/opt/protoc/bin:$PATH make\n/opt/core/venv/bin/python -m pip install .\n\n# when your system has protoc 3.19+\ncd <CORE_REPO>\n# example version tag v1.3.3\n# overriding python used to leverage the default virtualenv install\nPYTHON=/opt/core/venv/bin/python inv install-emane -e <version tag>\n# local install that uses whatever python3 refers to\ninv install-emane -e <version tag>\nAfter installation completes you are now ready to run CORE.
"},{"location":"install.html#resolving-docker-issues","title":"Resolving Docker Issues","text":"If you have Docker installed, by default it will change the iptables forwarding chain to drop packets, which will cause issues for CORE traffic.
You can temporarily resolve the issue with the following command:
sudo iptables --policy FORWARD ACCEPT\nAlternatively, you can configure Docker to avoid doing this, but will likely break normal Docker networking usage. Using the setting below will require a restart.
Place the file contents below in /etc/docker/docker.json
{\n\"iptables\": false\n}\nOne problem running CORE you may run into, using the virtual environment or locally can be issues related to your path.
To add support for your user to run scripts from the virtual environment:
# can add to ~/.bashrc\nexport PATH=$PATH:/opt/core/venv/bin\nThis will not solve the path issue when running as sudo, so you can do either of the following to compensate.
# run command passing in the right PATH to pickup from the user running the command\nsudo env PATH=$PATH core-daemon\n\n# add an alias to ~/.bashrc or something similar\nalias sudop='sudo env PATH=$PATH'\n# now you can run commands like so\nsudop core-daemon\nThe following assumes I have resolved PATH issues and setup the sudop alias.
# in one terminal run the server daemon using the alias above\nsudop core-daemon\n# in another terminal run the gui client\ncore-gui\nAfter installation, the core service is not enabled by default. If you desire to use the service, run the following commands.
sudo systemctl enable core-daemon\nsudo systemctl start core-daemon\nBelow 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 own virtual environment located at /opt/core/venv. Both examples below also assume using ~/Documents as the working directory.
"},{"location":"install_centos.html#script-install","title":"Script Install","text":"This section covers step by step commands that can be used to install CORE using the script based installation path.
# install system packages\nsudo yum -y update\nsudo yum install -y git sudo wget tzdata unzip libpcap-devel libpcre3-devel \\\nlibxml2-devel protobuf-devel unzip uuid-devel tcpdump make epel-release\nsudo yum-builddep -y python3\n\n# install python3.9\ncd ~/Documents\nwget https://www.python.org/ftp/python/3.9.15/Python-3.9.15.tgz\ntar xf Python-3.9.15.tgz\ncd Python-3.9.15\n./configure --enable-optimizations --with-ensurepip=install\nsudo make -j$(nproc) altinstall\npython3.9 -m pip install --upgrade pip\n\n# install core\ncd ~/Documents\ngit clone https://github.com/coreemu/core\ncd core\nNO_SYSTEM=1 PYTHON=/usr/local/bin/python3.9 ./setup.sh\nsource ~/.bashrc\nPYTHON=python3.9 inv install -p /usr --no-python\n\n# install emane\ncd ~/Documents\nwget -q https://adjacentlink.com/downloads/emane/emane-1.3.3-release-1.el7.x86_64.tar.gz\ntar xf emane-1.3.3-release-1.el7.x86_64.tar.gz\ncd emane-1.3.3-release-1/rpms/el7/x86_64\nsudo yum install -y ./openstatistic*.rpm ./emane*.rpm ./python3-emane_*.rpm\n\n# install emane python bindings into CORE virtual environment\ncd ~/Documents\nwget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip\nmkdir protoc\nunzip protoc-3.19.6-linux-x86_64.zip -d protoc\ngit clone https://github.com/adjacentlink/emane.git\ncd emane\ngit checkout v1.3.3\n./autogen.sh\nPYTHON=/opt/core/venv/bin/python ./configure --prefix=/usr\ncd src/python\nPATH=~/Documents/protoc/bin:$PATH make\nsudo /opt/core/venv/bin/python -m pip install .\nThis section covers step by step commands that can be used to install CORE using the package based installation path. This will require downloading a package from the release page, to use during the install CORE step below.
# install system packages\nsudo yum -y update\nsudo yum install -y git sudo wget tzdata unzip libpcap-devel libpcre3-devel libxml2-devel \\\nprotobuf-devel unzip uuid-devel tcpdump automake gawk libreadline-devel libtool \\\npkg-config make\nsudo yum-builddep -y python3\n\n# install python3.9\ncd ~/Documents\nwget https://www.python.org/ftp/python/3.9.15/Python-3.9.15.tgz\ntar xf Python-3.9.15.tgz\ncd Python-3.9.15\n./configure --enable-optimizations --with-ensurepip=install\nsudo make -j$(nproc) altinstall\npython3.9 -m pip install --upgrade pip\n\n# install core\ncd ~/Documents\nsudo PYTHON=python3.9 yum install -y ./core_*.rpm\n\n# install ospf mdr\ncd ~/Documents\ngit clone https://github.com/USNavalResearchLaboratory/ospf-mdr.git\ncd ospf-mdr\n./bootstrap.sh\n./configure --disable-doc --enable-user=root --enable-group=root \\\n--with-cflags=-ggdb --sysconfdir=/usr/local/etc/quagga --enable-vtysh \\\n--localstatedir=/var/run/quagga\nmake -j$(nproc)\nsudo make install\n\n# install emane\ncd ~/Documents\nwget -q https://adjacentlink.com/downloads/emane/emane-1.3.3-release-1.el7.x86_64.tar.gz\ntar xf emane-1.3.3-release-1.el7.x86_64.tar.gz\ncd emane-1.3.3-release-1/rpms/el7/x86_64\nsudo yum install -y ./openstatistic*.rpm ./emane*.rpm ./python3-emane_*.rpm\n\n# install emane python bindings into CORE virtual environment\ncd ~/Documents\nwget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip\nmkdir protoc\nunzip protoc-3.19.6-linux-x86_64.zip -d protoc\ngit clone https://github.com/adjacentlink/emane.git\ncd emane\ngit checkout v1.3.3\n./autogen.sh\nPYTHON=/opt/core/venv/bin/python ./configure --prefix=/usr\ncd src/python\nPATH=~/Documents/protoc/bin:$PATH make\nsudo /opt/core/venv/bin/python -m pip install .\nThe CORE virtual environment and related scripts will not be found on your PATH, so some adjustments needs to be made.
To add support for your user to run scripts from the virtual environment:
# can add to ~/.bashrc\nexport PATH=$PATH:/opt/core/venv/bin\nThis will not solve the path issue when running as sudo, so you can do either of the following to compensate.
# run command passing in the right PATH to pickup from the user running the command\nsudo env PATH=$PATH core-daemon\n\n# add an alias to ~/.bashrc or something similar\nalias sudop='sudo env PATH=$PATH'\n# now you can run commands like so\nsudop core-daemon\nBelow is a detailed path for installing CORE and related tooling on a fresh 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 also assume using ~/Documents as the working directory.
"},{"location":"install_ubuntu.html#script-install","title":"Script Install","text":"This section covers step by step commands that can be used to install CORE using the script based installation path.
# install system packages\nsudo apt-get update -y\nsudo apt-get install -y ca-certificates git sudo wget tzdata libpcap-dev libpcre3-dev \\\nlibprotobuf-dev libxml2-dev protobuf-compiler unzip uuid-dev iproute2 iputils-ping \\\ntcpdump\n\n# install core\ncd ~/Documents\ngit clone https://github.com/coreemu/core\ncd core\n./setup.sh\nsource ~/.bashrc\ninv install\n\n# install emane\ncd ~/Documents\nwget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip\nmkdir protoc\nunzip protoc-3.19.6-linux-x86_64.zip -d protoc\ngit clone https://github.com/adjacentlink/emane.git\ncd emane\n./autogen.sh\n./configure --prefix=/usr\nmake -j$(nproc)\nsudo make install\ncd src/python\nmake clean\nPATH=~/Documents/protoc/bin:$PATH make\nsudo /opt/core/venv/bin/python -m pip install .\nThis section covers step by step commands that can be used to install CORE using the package based installation path. This will require downloading a package from the release page, to use during the install CORE step below.
# install system packages\nsudo apt-get update -y\nsudo apt-get install -y ca-certificates python3 python3-tk python3-pip python3-venv \\\nlibpcap-dev libpcre3-dev libprotobuf-dev libxml2-dev protobuf-compiler unzip \\\nuuid-dev automake gawk git wget libreadline-dev libtool pkg-config g++ make \\\niputils-ping tcpdump\n\n# install core\ncd ~/Documents\nsudo apt-get install -y ./core_*.deb\n\n# install ospf mdr\ncd ~/Documents\ngit clone https://github.com/USNavalResearchLaboratory/ospf-mdr.git\ncd ospf-mdr\n./bootstrap.sh\n./configure --disable-doc --enable-user=root --enable-group=root \\\n--with-cflags=-ggdb --sysconfdir=/usr/local/etc/quagga --enable-vtysh \\\n--localstatedir=/var/run/quagga\nmake -j$(nproc)\nsudo make install\n\n# install emane\ncd ~/Documents\nwget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.6/protoc-3.19.6-linux-x86_64.zip\nmkdir protoc\nunzip protoc-3.19.6-linux-x86_64.zip -d protoc\ngit clone https://github.com/adjacentlink/emane.git\ncd emane\n./autogen.sh\n./configure --prefix=/usr\nmake -j$(nproc)\nsudo make install\ncd src/python\nmake clean\nPATH=~/Documents/protoc/bin:$PATH make\nsudo /opt/core/venv/bin/python -m pip install .\nThe CORE virtual environment and related scripts will not be found on your PATH, so some adjustments needs to be made.
To add support for your user to run scripts from the virtual environment:
# can add to ~/.bashrc\nexport PATH=$PATH:/opt/core/venv/bin\nThis will not solve the path issue when running as sudo, so you can do either of the following to compensate.
# run command passing in the right PATH to pickup from the user running the command\nsudo env PATH=$PATH core-daemon\n\n# add an alias to ~/.bashrc or something similar\nalias sudop='sudo env PATH=$PATH'\n# now you can run commands like so\nsudop core-daemon\nLXC nodes are provided by way of LXD to create nodes using predefined images and provide file system separation.
"},{"location":"lxc.html#installation","title":"Installation","text":""},{"location":"lxc.html#debian-systems","title":"Debian Systems","text":"sudo snap install lxd\nInitialize LXD and say no to adding a default bridge.
sudo lxd init\nTo use LXC nodes within the python GUI, you will need to make sure the user running the GUI is a member of the lxd group.
# add group if does not exist\nsudo groupadd lxd\n\n# add user to group\nsudo usermod -aG lxd $USER\n\n# to get this change to take effect, log out and back in or run the following\nnewgrp lxd\nDifferent node types can be used within CORE, each with their own tradeoffs and functionality.
"},{"location":"nodetypes.html#core-nodes","title":"CORE Nodes","text":"CORE nodes are the standard node type typically used in CORE. They are backed by Linux network namespaces. They use very little system resources in order to emulate a network. They do however share the hosts file system as they do not get their own. CORE nodes will have a directory uniquely created for them as a place to keep their files and mounted directories (/tmp/pycore.<session id>/<node name.conf), which will usually be wiped and removed upon shutdown.
Docker nodes provide a convenience for running nodes using predefind images and filesystems that CORE nodes do not provide. Details for using Docker nodes can be found here.
"},{"location":"nodetypes.html#lxc-nodes","title":"LXC Nodes","text":"LXC nodes provide a convenience for running nodes using predefind images and filesystems that CORE nodes do not provide. Details for using LXC nodes can be found here.
"},{"location":"nodetypes.html#physical-nodes","title":"Physical Nodes","text":"The physical machine type is used for nodes that represent a real Linux-based machine that will participate in the emulated network scenario. This is typically used, for example, to incorporate racks of server machines from an emulation testbed. A physical node is one that is running the CORE daemon (core-daemon), but will not be further partitioned into containers. Services that are run on the physical node do not run in an isolated environment, but directly on the operating system.
Physical nodes must be assigned to servers, the same way nodes are assigned to emulation servers with Distributed Emulation. The list of available physical nodes currently shares the same dialog box and list as the emulation servers, accessed using the Emulation Servers... entry from the Session menu.
Support for physical nodes is under development and may be improved in future releases. Currently, when any node is linked to a physical node, a dashed line is drawn to indicate network tunneling. A GRE tunneling interface will be created on the physical node and used to tunnel traffic to and from the emulated world.
Double-clicking on a physical node during runtime opens a terminal with an SSH shell to that node. Users should configure public-key SSH login as done with emulation servers.
"},{"location":"performance.html","title":"CORE Performance","text":""},{"location":"performance.html#overview","title":"Overview","text":"The top question about the performance of CORE is often how many nodes can it handle? The answer depends on several factors:
Factor Performance Impact Hardware the number and speed of processors in the computer, the available processor cache, RAM memory, and front-side bus speed may greatly affect overall performance. Operating system version distribution of Linux and the specific kernel versions used will affect overall performance. Active processes all nodes share the same CPU resources, so if one or more nodes is performing a CPU-intensive task, overall performance will suffer. 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.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 routing. On this hardware CORE can instantiate 100 or more nodes, but at that point it becomes critical as to what each of the nodes is doing.
Because this software is primarily a network emulator, the more appropriate question is how much network traffic can it handle? On the same 3.0GHz server described above, running Linux, about 300,000 packets-per-second can be pushed through the system. The number of hops and the size of the packets is less important. The limiting factor is the number of times that the operating system needs to handle a packet. The 300,000 pps figure represents the number of times the system as a whole needed to deal with a packet. As more network hops are added, this increases the number of context switches and decreases the throughput seen on the full length of the network path.
Note
The right question to be asking is \"how much traffic?\", not \"how many nodes?\".
For a more detailed study of performance in CORE, refer to the following publications:
Writing your own Python scripts offers a rich programming environment with complete control over all aspects of the emulation.
The scripts need to be ran with root privileges because they create new network namespaces. In general, a CORE Python script does not connect to the CORE daemon, in fact the core-daemon is just another Python script that uses the CORE Python modules and exchanges messages with the GUI.
"},{"location":"python.html#examples","title":"Examples","text":""},{"location":"python.html#node-models","title":"Node Models","text":"When creating nodes of type core.nodes.base.CoreNode these are the default models and the services they map to.
There is an interface helper class that can be leveraged for convenience when creating interface data for nodes. Alternatively one can manually create a core.emulator.data.InterfaceData class instead with appropriate information.
Manually creating interface data:
from core.emulator.data import InterfaceData\n\n# id is optional and will set to the next available id\n# name is optional and will default to eth<id>\n# mac is optional and will result in a randomly generated mac\niface_data = InterfaceData(\n id=0,\n name=\"eth0\",\n ip4=\"10.0.0.1\",\n ip4_mask=24,\n ip6=\"2001::\",\n ip6_mask=64,\n)\nLeveraging the interface prefixes helper class:
from core.emulator.data import IpPrefixes\n\nip_prefixes = IpPrefixes(ip4_prefix=\"10.0.0.0/24\", ip6_prefix=\"2001::/64\")\n# node is used to get an ip4/ip6 address indexed from within the above prefixes\n# name is optional and would default to eth<id>\n# mac is optional and will result in a randomly generated mac\niface_data = ip_prefixes.create_iface(\n node=node, name=\"eth0\", mac=\"00:00:00:00:aa:00\"\n)\nVarious events that can occur within a session can be listened to.
Event types:
def event_listener(event):\n print(event)\n\n\n# add an event listener to event type you want to listen to\n# each handler will receive an object unique to that type\nsession.event_handlers.append(event_listener)\nsession.exception_handlers.append(event_listener)\nsession.node_handlers.append(event_listener)\nsession.link_handlers.append(event_listener)\nsession.file_handlers.append(event_listener)\nsession.config_handlers.append(event_listener)\nLinks can be configured at the time of creation or during runtime.
Currently supported configuration options:
from core.emulator.data import LinkOptions\n\n# configuring when creating a link\noptions = LinkOptions(\n bandwidth=54_000_000,\n delay=5000,\n dup=5,\n loss=5.5,\n jitter=0,\n)\nsession.add_link(n1_id, n2_id, iface1_data, iface2_data, options)\n\n# configuring during runtime\nsession.update_link(n1_id, n2_id, iface1_id, iface2_id, options)\n# required imports\nfrom core.emulator.coreemu import CoreEmu\nfrom core.emulator.data import IpPrefixes\nfrom core.emulator.enumerations import EventTypes\nfrom core.nodes.base import CoreNode, Position\n\n# ip nerator for example\nip_prefixes = IpPrefixes(ip4_prefix=\"10.0.0.0/24\")\n\n# create emulator instance for creating sessions and utility methods\ncoreemu = CoreEmu()\nsession = coreemu.create_session()\n\n# must be in configuration state for nodes to start, when using \"node_add\" below\nsession.set_state(EventTypes.CONFIGURATION_STATE)\n\n# create nodes\nposition = Position(x=100, y=100)\nn1 = session.add_node(CoreNode, position=position)\nposition = Position(x=300, y=100)\nn2 = session.add_node(CoreNode, position=position)\n\n# link nodes together\niface1 = ip_prefixes.create_iface(n1)\niface2 = ip_prefixes.create_iface(n2)\nsession.add_link(n1.id, n2.id, iface1, iface2)\n\n# start session\nsession.instantiate()\n\n# do whatever you like here\ninput(\"press enter to shutdown\")\n\n# stop session\nsession.shutdown()\n# required imports\nfrom core.emulator.coreemu import CoreEmu\nfrom core.emulator.data import IpPrefixes\nfrom core.emulator.enumerations import EventTypes\nfrom core.nodes.base import CoreNode, Position\nfrom core.nodes.network import SwitchNode\n\n# ip nerator for example\nip_prefixes = IpPrefixes(ip4_prefix=\"10.0.0.0/24\")\n\n# create emulator instance for creating sessions and utility methods\ncoreemu = CoreEmu()\nsession = coreemu.create_session()\n\n# must be in configuration state for nodes to start, when using \"node_add\" below\nsession.set_state(EventTypes.CONFIGURATION_STATE)\n\n# create switch\nposition = Position(x=200, y=200)\nswitch = session.add_node(SwitchNode, position=position)\n\n# create nodes\nposition = Position(x=100, y=100)\nn1 = session.add_node(CoreNode, position=position)\nposition = Position(x=300, y=100)\nn2 = session.add_node(CoreNode, position=position)\n\n# link nodes to switch\niface1 = ip_prefixes.create_iface(n1)\nsession.add_link(n1.id, switch.id, iface1)\niface1 = ip_prefixes.create_iface(n2)\nsession.add_link(n2.id, switch.id, iface1)\n\n# start session\nsession.instantiate()\n\n# do whatever you like here\ninput(\"press enter to shutdown\")\n\n# stop session\nsession.shutdown()\n# required imports\nfrom core.emulator.coreemu import CoreEmu\nfrom core.emulator.data import IpPrefixes\nfrom core.emulator.enumerations import EventTypes\nfrom core.location.mobility import BasicRangeModel\nfrom core.nodes.base import CoreNode, Position\nfrom core.nodes.network import WlanNode\n\n# ip nerator for example\nip_prefixes = IpPrefixes(ip4_prefix=\"10.0.0.0/24\")\n\n# create emulator instance for creating sessions and utility methods\ncoreemu = CoreEmu()\nsession = coreemu.create_session()\n\n# must be in configuration state for nodes to start, when using \"node_add\" below\nsession.set_state(EventTypes.CONFIGURATION_STATE)\n\n# create wlan\nposition = Position(x=200, y=200)\nwlan = session.add_node(WlanNode, position=position)\n\n# create nodes\noptions = CoreNode.create_options()\noptions.model = \"mdr\"\nposition = Position(x=100, y=100)\nn1 = session.add_node(CoreNode, position=position, options=options)\nposition = Position(x=300, y=100)\nn2 = session.add_node(CoreNode, position=position, options=options)\n\n# configuring wlan\nsession.mobility.set_model_config(wlan.id, BasicRangeModel.name, {\n \"range\": \"280\",\n \"bandwidth\": \"55000000\",\n \"delay\": \"6000\",\n \"jitter\": \"5\",\n \"error\": \"5\",\n})\n\n# link nodes to wlan\niface1 = ip_prefixes.create_iface(n1)\nsession.add_link(n1.id, wlan.id, iface1)\niface1 = ip_prefixes.create_iface(n2)\nsession.add_link(n2.id, wlan.id, iface1)\n\n# start session\nsession.instantiate()\n\n# do whatever you like here\ninput(\"press enter to shutdown\")\n\n# stop session\nsession.shutdown()\nFor EMANE you can import and use one of the existing models and use its name for configuration.
Current models:
Their configurations options are driven dynamically from parsed EMANE manifest files from the installed version of EMANE.
Options and their purpose can be found at the EMANE Wiki.
If configuring EMANE global settings or model mac/phy specific settings, any value not provided will use the defaults. When no configuration is used, the defaults are used.
# required imports\nfrom core.emane.models.ieee80211abg import EmaneIeee80211abgModel\nfrom core.emane.nodes import EmaneNet\nfrom core.emulator.coreemu import CoreEmu\nfrom core.emulator.data import IpPrefixes\nfrom core.emulator.enumerations import EventTypes\nfrom core.nodes.base import CoreNode, Position\n\n# ip nerator for example\nip_prefixes = IpPrefixes(ip4_prefix=\"10.0.0.0/24\")\n\n# create emulator instance for creating sessions and utility methods\ncoreemu = CoreEmu()\nsession = coreemu.create_session()\n\n# location information is required to be set for emane\nsession.location.setrefgeo(47.57917, -122.13232, 2.0)\nsession.location.refscale = 150.0\n\n# must be in configuration state for nodes to start, when using \"node_add\" below\nsession.set_state(EventTypes.CONFIGURATION_STATE)\n\n# create emane\noptions = EmaneNet.create_options()\noptions.emane_model = EmaneIeee80211abgModel.name\nposition = Position(x=200, y=200)\nemane = session.add_node(EmaneNet, position=position, options=options)\n\n# create nodes\noptions = CoreNode.create_options()\noptions.model = \"mdr\"\nposition = Position(x=100, y=100)\nn1 = session.add_node(CoreNode, position=position, options=options)\nposition = Position(x=300, y=100)\nn2 = session.add_node(CoreNode, position=position, options=options)\n\n# configure general emane settings\nconfig = session.emane.get_configs()\nconfig.update({\n \"eventservicettl\": \"2\"\n})\n\n# configure emane model settings\n# using a dict mapping currently support values as strings\nsession.emane.set_model_config(emane.id, EmaneIeee80211abgModel.name, {\n \"unicastrate\": \"3\",\n})\n\n# link nodes to emane\niface1 = ip_prefixes.create_iface(n1)\nsession.add_link(n1.id, emane.id, iface1)\niface1 = ip_prefixes.create_iface(n2)\nsession.add_link(n2.id, emane.id, iface1)\n\n# start session\nsession.instantiate()\n\n# do whatever you like here\ninput(\"press enter to shutdown\")\n\n# stop session\nsession.shutdown()\nEMANE Model Configuration:
from core import utils\n\n# standardized way to retrieve an appropriate config id\n# iface id can be omitted, to allow a general configuration for a model, per node\nconfig_id = utils.iface_config_id(node.id, iface_id)\n# set emane configuration for the config id\nsession.emane.set_config(config_id, EmaneIeee80211abgModel.name, {\n \"unicastrate\": \"3\",\n})\nServices help generate and run bash scripts on nodes for a given purpose.
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.
The following features can be configured for a service:
Editing service properties:
# configure a service, for a node, for a given session\nsession.services.set_service(node_id, service_name)\nservice = session.services.get_service(node_id, service_name)\nservice.configs = (\"file1.sh\", \"file2.sh\")\nservice.dirs = (\"/etc/node\",)\nservice.startup = (\"bash file1.sh\",)\nservice.validate = ()\nservice.shutdown = ()\nWhen editing a service file, it must be the name of config file that the service will generate.
Editing a service file:
# to edit the contents of a generated file you can specify\n# the service, the file name, and its contents\nsession.services.set_service_file(\n node_id,\n service_name,\n file_name,\n \"echo hello\",\n)\nFile versions of the network examples can be found here.
"},{"location":"python.html#executing-scripts-from-gui","title":"Executing Scripts from GUI","text":"To execute a python script from a GUI you need have the following.
The builtin name check here to know it is being executed from the GUI, this can be avoided if your script does not use a name check.
if __name__ in [\"__main__\", \"__builtin__\"]:\n main()\nA script can add sessions to the core-daemon. A global coreemu variable is exposed to the script pointing to the CoreEmu object.
The example below has a fallback to a new CoreEmu object, in the case you would like to run the script standalone, outside of the core-daemon.
coreemu = globals().get(\"coreemu\") or CoreEmu()\nsession = coreemu.create_session()\nCORE 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 the services that they run.
Services may be customized for each node, or new custom services can be created. New node types can be created each having a different name, icon, and set of default services. Each service defines the per-node directories, configuration files, startup index, starting commands, validation commands, shutdown commands, and meta-data associated with a node.
Note
Network namespace nodes do not undergo the normal Linux boot process using the init, upstart, or systemd frameworks. These lightweight nodes use configured CORE services.
"},{"location":"services.html#available-services","title":"Available Services","text":"Service Group Services BIRD BGP, OSPF, RADV, RIP, Static EMANE Transport Service FRR BABEL, BGP, OSPFv2, OSPFv3, PIMD, RIP, RIPNG, Zebra NRL arouted, MGEN Sink, MGEN Actor, NHDP, OLSR, OLSRORG, OLSRv2, SMF Quagga BABEL, BGP, OSPFv2, OSPFv3, OSPFv3 MDR, RIP, RIPNG, XPIMD, Zebra SDN OVS, RYU Security Firewall, IPsec, NAT, VPN Client, VPN Server Utility ATD, Routing Utils, DHCP, FTP, IP Forward, PCAP, RADVD, SSF, UCARP XORP BGP, OLSR, OSPFv2, OSPFv3, PIMSM4, PIMSM6, RIP, RIPNG, Router Manager"},{"location":"services.html#node-types-and-default-services","title":"Node Types and Default Services","text":"Here are the default node types and their services:
Node Type Services router zebra, OSFPv2, OSPFv3, and IPForward services for IGP link-state routing. host DefaultRoute and SSH services, representing an SSH server having a default route when connected directly to a router. PC DefaultRoute service for having a default route when connected directly to a router. mdr zebra, OSPFv3MDR, and IPForward services for wireless-optimized MANET Designated Router routing. prouter a physical router, having the same default services as the router node type; for incorporating Linux testbed machines into an emulation.Configuration files can be automatically generated by each service. For example, CORE automatically generates routing protocol configuration for the router nodes in order to simplify the creation of virtual networks.
To change the services associated with a node, double-click on the node to invoke its configuration dialog and click on the Services... button, or right-click a node a choose Services... from the menu. Services are enabled or disabled by clicking on their names. The button next to each service name allows you to customize all aspects of this service for this node. For example, special route redistribution commands could be inserted in to the Quagga routing configuration associated with the zebra service.
To change the default services associated with a node type, use the Node Types dialog available from the Edit button at the end of the Layer-3 nodes toolbar, or choose Node types... from the Session menu. Note that any new services selected are not applied to existing nodes if the nodes have been customized.
"},{"location":"services.html#customizing-a-service","title":"Customizing a Service","text":"A service can be fully customized for a particular node. From the node's configuration dialog, click on the button next to the service name to invoke the service customization dialog for that service. The dialog has three tabs for configuring the different aspects of the service: files, directories, and startup/shutdown.
Note
A yellow customize icon next to a service indicates that service requires customization (e.g. the Firewall service). A green customize icon indicates that a custom configuration exists. Click the Defaults button when customizing a service to remove any customizations.
The Files tab is used to display or edit the configuration files or scripts that are used for this service. Files can be selected from a drop-down list, and their contents are displayed in a text entry below. The file contents are generated by the CORE daemon based on the network topology that exists at the time the customization dialog is invoked.
The Directories tab shows the per-node directories for this service. For the default types, CORE nodes share the same filesystem tree, except for these per-node directories that are defined by the services. For example, the /var/run/quagga directory needs to be unique for each node running the Zebra service, because Quagga running on each node needs to write separate PID files to that directory.
Note
The /var/log and /var/run directories are mounted uniquely per-node by default. Per-node mount targets can be found in /tmp/pycore./.conf/
The Startup/shutdown tab lists commands that are used to start and stop this service. The startup index allows configuring when this service starts relative to the other services enabled for this node; a service with a lower startup index value is started before those with higher values. Because shell scripts generated by the Files tab will not have execute permissions set, the startup commands should include the shell name, with something like sh script.sh.
Shutdown commands optionally terminate the process(es) associated with this service. Generally they send a kill signal to the running process using the kill or killall commands. If the service does not terminate the running processes using a shutdown command, the processes will be killed when the vnoded daemon is terminated (with kill -9) and the namespace destroyed. It is a good practice to specify shutdown commands, which will allow for proper process termination, and for run-time control of stopping and restarting services.
Validate commands are executed following the startup commands. A validate command can execute a process or script that should return zero if the service has started successfully, and have a non-zero return value for services that have had a problem starting. For example, the pidof command will check if a process is running and return zero when found. When a validate command produces a non-zero return value, an exception is generated, which will cause an error to be displayed in the Check Emulation Light.
Note
To start, stop, and restart services during run-time, right-click a node and use the Services... menu.
"},{"location":"services.html#new-services","title":"New Services","text":"Services can save time required to configure nodes, especially if a number of nodes require similar configuration procedures. New services can be introduced to automate tasks.
"},{"location":"services.html#leveraging-userdefined","title":"Leveraging UserDefined","text":"The easiest way to capture the configuration of a new process into a service is by using the UserDefined service. This is a blank service where any aspect may be customized. The UserDefined service is convenient for testing ideas for a service before adding a new service type.
"},{"location":"services.html#creating-new-services","title":"Creating New Services","text":"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.
Modify the example service shown below to do what you want. It could generate config/script files, mount per-node directories, start processes/scripts, etc. sample.py is a Python file that defines one or more classes to be imported. You can create multiple Python files that will be imported.
Put these files in a directory such as /home/<user>/.coregui/custom_services Note that the last component of this directory name custom_services should not be named the same as any python module, due to naming conflicts.
Add a custom_services_dir = /home/<user>/.coregui/custom_services entry to the /etc/core/core.conf file.
Restart the CORE daemon (core-daemon). Any import errors (Python syntax) should be displayed in the daemon output.
Start using your custom service on your nodes. You can create a new node type that uses your service, or change the default services for an existing node type, or change individual nodes.
If you have created a new service type that may be useful to others, please consider contributing it to the CORE project.
"},{"location":"services.html#example-custom-service","title":"Example Custom Service","text":"Below is the skeleton for a custom service with some documentation. Most people would likely only setup the required class variables (name/group). Then define the configs (files they want to generate) and implement the generate_config function to dynamically create the files wanted. Finally the startup commands would be supplied, which typically tends to be running the shell files generated.
\"\"\"\nSimple example custom service, used to drive shell commands on a node.\n\"\"\"\nfrom typing import Tuple\n\nfrom core.nodes.base import CoreNode\nfrom core.services.coreservices import CoreService, ServiceMode\n\n\nclass ExampleService(CoreService):\n\"\"\"\n Example Custom CORE Service\n\n :cvar name: name used as a unique ID for this service and is required, no spaces\n :cvar group: allows you to group services within the GUI under a common name\n :cvar executables: executables this service depends on to function, if executable is\n not on the path, service will not be loaded\n :cvar dependencies: services that this service depends on for startup, tuple of\n service names\n :cvar dirs: directories that this service will create within a node\n :cvar configs: files that this service will generate, without a full path this file\n goes in the node's directory e.g. /tmp/pycore.12345/n1.conf/myfile\n :cvar startup: commands used to start this service, any non-zero exit code will\n cause a failure\n :cvar validate: commands used to validate that a service was started, any non-zero\n exit code will cause a failure\n :cvar validation_mode: validation mode, used to determine startup success.\n NON_BLOCKING - runs startup commands, and validates success with validation commands\n BLOCKING - runs startup commands, and validates success with the startup commands themselves\n TIMER - runs startup commands, and validates success by waiting for \"validation_timer\" alone\n :cvar validation_timer: time in seconds for a service to wait for validation, before\n determining success in TIMER/NON_BLOCKING modes.\n :cvar validation_period: period in seconds to wait before retrying validation,\n only used in NON_BLOCKING mode\n :cvar shutdown: shutdown commands to stop this service\n \"\"\"\n\n name: str = \"ExampleService\"\n group: str = \"Utility\"\n executables: Tuple[str, ...] = ()\n dependencies: Tuple[str, ...] = ()\n dirs: Tuple[str, ...] = ()\n configs: Tuple[str, ...] = (\"myservice1.sh\", \"myservice2.sh\")\n startup: Tuple[str, ...] = tuple(f\"sh {x}\" for x in configs)\n validate: Tuple[str, ...] = ()\n validation_mode: ServiceMode = ServiceMode.NON_BLOCKING\n validation_timer: int = 5\n validation_period: float = 0.5\n shutdown: Tuple[str, ...] = ()\n\n @classmethod\n def on_load(cls) -> None:\n\"\"\"\n Provides a way to run some arbitrary logic when the service is loaded, possibly\n to help facilitate dynamic settings for the environment.\n\n :return: nothing\n \"\"\"\n pass\n\n @classmethod\n def get_configs(cls, node: CoreNode) -> Tuple[str, ...]:\n\"\"\"\n Provides a way to dynamically generate the config files from the node a service\n will run. Defaults to the class definition and can be left out entirely if not\n needed.\n\n :param node: core node that the service is being ran on\n :return: tuple of config files to create\n \"\"\"\n return cls.configs\n\n @classmethod\n def generate_config(cls, node: CoreNode, filename: str) -> str:\n\"\"\"\n Returns a string representation for a file, given the node the service is\n starting on the config filename that this information will be used for. This\n must be defined, if \"configs\" are defined.\n\n :param node: core node that the service is being ran on\n :param filename: configuration file to generate\n :return: configuration file content\n \"\"\"\n cfg = \"#!/bin/sh\\n\"\n if filename == cls.configs[0]:\n cfg += \"# auto-generated by MyService (sample.py)\\n\"\n for iface in node.get_ifaces():\n cfg += f'echo \"Node {node.name} has interface {iface.name}\"\\n'\n elif filename == cls.configs[1]:\n cfg += \"echo hello\"\n return cfg\n\n @classmethod\n def get_startup(cls, node: CoreNode) -> Tuple[str, ...]:\n\"\"\"\n Provides a way to dynamically generate the startup commands from the node a\n service will run. Defaults to the class definition and can be left out entirely\n if not needed.\n\n :param node: core node that the service is being ran on\n :return: tuple of startup commands to run\n \"\"\"\n return cls.startup\n\n @classmethod\n def get_validate(cls, node: CoreNode) -> Tuple[str, ...]:\n\"\"\"\n Provides a way to dynamically generate the validate commands from the node a\n service will run. Defaults to the class definition and can be left out entirely\n if not needed.\n\n :param node: core node that the service is being ran on\n :return: tuple of commands to validate service startup with\n \"\"\"\n return cls.validate\nIntroduction to using the EMANE antenna profile in CORE, based on the example EMANE Demo linked below.
EMANE Demo 6 for more specifics.
"},{"location":"emane/antenna.html#demo-setup","title":"Demo Setup","text":"We will need to create some files in advance of starting this session.
Create directory to place antenna profile files.
mkdir /tmp/emane\nCreate /tmp/emane/antennaprofile.xml with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE profiles SYSTEM \"file:///usr/share/emane/dtd/antennaprofile.dtd\">\n<profiles>\n<profile id=\"1\"\nantennapatternuri=\"/tmp/emane/antenna30dsector.xml\"\nblockagepatternuri=\"/tmp/emane/blockageaft.xml\">\n<placement north=\"0\" east=\"0\" up=\"0\"/>\n</profile>\n<profile id=\"2\"\nantennapatternuri=\"/tmp/emane/antenna30dsector.xml\">\n<placement north=\"0\" east=\"0\" up=\"0\"/>\n</profile>\n</profiles>\nCreate /tmp/emane/antenna30dsector.xml with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE antennaprofile SYSTEM \"file:///usr/share/emane/dtd/antennaprofile.dtd\">\n\n<!-- 30degree sector antenna pattern with main beam at +6dB and gain decreasing by 3dB every 5 degrees in elevation or bearing.-->\n<antennaprofile>\n<antennapattern>\n<elevation min='-90' max='-16'>\n<bearing min='0' max='359'>\n<gain value='-200'/>\n</bearing>\n</elevation>\n<elevation min='-15' max='-11'>\n<bearing min='0' max='5'>\n<gain value='0'/>\n</bearing>\n<bearing min='6' max='10'>\n<gain value='-3'/>\n</bearing>\n<bearing min='11' max='15'>\n<gain value='-6'/>\n</bearing>\n<bearing min='16' max='344'>\n<gain value='-200'/>\n</bearing>\n<bearing min='345' max='349'>\n<gain value='-6'/>\n</bearing>\n<bearing min='350' max='354'>\n<gain value='-3'/>\n</bearing>\n<bearing min='355' max='359'>\n<gain value='0'/>\n</bearing>\n</elevation>\n<elevation min='-10' max='-6'>\n<bearing min='0' max='5'>\n<gain value='3'/>\n</bearing>\n<bearing min='6' max='10'>\n<gain value='0'/>\n</bearing>\n<bearing min='11' max='15'>\n<gain value='-3'/>\n</bearing>\n<bearing min='16' max='344'>\n<gain value='-200'/>\n</bearing>\n<bearing min='345' max='349'>\n<gain value='-3'/>\n</bearing>\n<bearing min='350' max='354'>\n<gain value='0'/>\n</bearing>\n<bearing min='355' max='359'>\n<gain value='3'/>\n</bearing>\n</elevation>\n<elevation min='-5' max='-1'>\n<bearing min='0' max='5'>\n<gain value='6'/>\n</bearing>\n<bearing min='6' max='10'>\n<gain value='3'/>\n</bearing>\n<bearing min='11' max='15'>\n<gain value='0'/>\n</bearing>\n<bearing min='16' max='344'>\n<gain value='-200'/>\n</bearing>\n<bearing min='345' max='349'>\n<gain value='0'/>\n</bearing>\n<bearing min='350' max='354'>\n<gain value='3'/>\n</bearing>\n<bearing min='355' max='359'>\n<gain value='6'/>\n</bearing>\n</elevation>\n<elevation min='0' max='5'>\n<bearing min='0' max='5'>\n<gain value='6'/>\n</bearing>\n<bearing min='6' max='10'>\n<gain value='3'/>\n</bearing>\n<bearing min='11' max='15'>\n<gain value='0'/>\n</bearing>\n<bearing min='16' max='344'>\n<gain value='-200'/>\n</bearing>\n<bearing min='345' max='349'>\n<gain value='0'/>\n</bearing>\n<bearing min='350' max='354'>\n<gain value='3'/>\n</bearing>\n<bearing min='355' max='359'>\n<gain value='6'/>\n</bearing>\n</elevation>\n<elevation min='6' max='10'>\n<bearing min='0' max='5'>\n<gain value='3'/>\n</bearing>\n<bearing min='6' max='10'>\n<gain value='0'/>\n</bearing>\n<bearing min='11' max='15'>\n<gain value='-3'/>\n</bearing>\n<bearing min='16' max='344'>\n<gain value='-200'/>\n</bearing>\n<bearing min='345' max='349'>\n<gain value='-3'/>\n</bearing>\n<bearing min='350' max='354'>\n<gain value='0'/>\n</bearing>\n<bearing min='355' max='359'>\n<gain value='3'/>\n</bearing>\n</elevation>\n<elevation min='11' max='15'>\n<bearing min='0' max='5'>\n<gain value='0'/>\n</bearing>\n<bearing min='6' max='10'>\n<gain value='-3'/>\n</bearing>\n<bearing min='11' max='15'>\n<gain value='-6'/>\n</bearing>\n<bearing min='16' max='344'>\n<gain value='-200'/>\n</bearing>\n<bearing min='345' max='349'>\n<gain value='-6'/>\n</bearing>\n<bearing min='350' max='354'>\n<gain value='-3'/>\n</bearing>\n<bearing min='355' max='359'>\n<gain value='0'/>\n</bearing>\n</elevation>\n<elevation min='16' max='90'>\n<bearing min='0' max='359'>\n<gain value='-200'/>\n</bearing>\n</elevation>\n</antennapattern>\n</antennaprofile>\nCreate /tmp/emane/blockageaft.xml with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE antennaprofile SYSTEM \"file:///usr/share/emane/dtd/antennaprofile.dtd\">\n\n<!-- blockage pattern: 1) entire aft in bearing (90 to 270) blocked 2) elevation below -10 blocked, 3) elevation from -10 to -1 is at -10dB to -1 dB 3) elevation from 0 to 90 no blockage-->\n<antennaprofile>\n<blockagepattern>\n<elevation min='-90' max='-11'>\n<bearing min='0' max='359'>\n<gain value='-200'/>\n</bearing>\n</elevation>\n<elevation min='-10' max='-10'>\n<bearing min='0' max='89'>\n<gain value='-10'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='-10'/>\n</bearing>\n</elevation>\n<elevation min='-9' max='-9'>\n<bearing min='0' max='89'>\n<gain value='-9'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='-9'/>\n</bearing>\n</elevation>\n<elevation min='-8' max='-8'>\n<bearing min='0' max='89'>\n<gain value='-8'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='-8'/>\n</bearing>\n</elevation>\n<elevation min='-7' max='-7'>\n<bearing min='0' max='89'>\n<gain value='-7'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='-7'/>\n</bearing>\n</elevation>\n<elevation min='-6' max='-6'>\n<bearing min='0' max='89'>\n<gain value='-6'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='-6'/>\n</bearing>\n</elevation>\n<elevation min='-5' max='-5'>\n<bearing min='0' max='89'>\n<gain value='-5'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='-5'/>\n</bearing>\n</elevation>\n<elevation min='-4' max='-4'>\n<bearing min='0' max='89'>\n<gain value='-4'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='-4'/>\n</bearing>\n</elevation>\n<elevation min='-3' max='-3'>\n<bearing min='0' max='89'>\n<gain value='-3'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='-3'/>\n</bearing>\n</elevation>\n<elevation min='-2' max='-2'>\n<bearing min='0' max='89'>\n<gain value='-2'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='-2'/>\n</bearing>\n</elevation>\n<elevation min='-1' max='-1'>\n<bearing min='0' max='89'>\n<gain value='-1'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='-1'/>\n</bearing>\n</elevation>\n<elevation min='0' max='90'>\n<bearing min='0' max='89'>\n<gain value='0'/>\n</bearing>\n<bearing min='90' max='270'>\n<gain value='-200'/>\n</bearing>\n<bearing min='271' max='359'>\n<gain value='0'/>\n</bearing>\n</elevation>\n</blockagepattern>\n</antennaprofile>\nOpen... within the GUIemane-demo-antenna.xmlThis demo will cover running an EMANE event service to feed in antenna, location, and pathloss events to demonstrate how antenna profiles can be used.
"},{"location":"emane/antenna.html#emane-event-dump","title":"EMANE Event Dump","text":"On n1 lets dump EMANE events, so when we later run the EMANE event service you can monitor when and what is sent.
root@n1:/tmp/pycore.44917/n1.conf# emaneevent-dump -i ctrl0\nOn the host machine create the following to send EMANE events.
Warning
Make sure to set the eventservicedevice to the proper control network value
Create eventservice.xml with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE eventservice SYSTEM \"file:///usr/share/emane/dtd/eventservice.dtd\">\n<eventservice>\n<param name=\"eventservicegroup\" value=\"224.1.2.8:45703\"/>\n<param name=\"eventservicedevice\" value=\"b.9001.da\"/>\n<generator definition=\"eelgenerator.xml\"/>\n</eventservice>\nCreate eelgenerator.xml with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE eventgenerator SYSTEM \"file:///usr/share/emane/dtd/eventgenerator.dtd\">\n<eventgenerator library=\"eelgenerator\">\n<param name=\"inputfile\" value=\"scenario.eel\"/>\n<paramlist name=\"loader\">\n<item value=\"commeffect:eelloadercommeffect:delta\"/>\n<item value=\"location,velocity,orientation:eelloaderlocation:delta\"/>\n<item value=\"pathloss:eelloaderpathloss:delta\"/>\n<item value=\"antennaprofile:eelloaderantennaprofile:delta\"/>\n</paramlist>\n</eventgenerator>\nCreate scenario.eel with the following contents.
0.0 nem:1 antennaprofile 1,0.0,0.0\n0.0 nem:4 antennaprofile 2,0.0,0.0\n#\n0.0 nem:1 pathloss nem:2,60 nem:3,60 nem:4,60\n0.0 nem:2 pathloss nem:3,60 nem:4,60\n0.0 nem:3 pathloss nem:4,60\n#\n0.0 nem:1 location gps 40.025495,-74.315441,3.0\n0.0 nem:2 location gps 40.025495,-74.312501,3.0\n0.0 nem:3 location gps 40.023235,-74.315441,3.0\n0.0 nem:4 location gps 40.023235,-74.312501,3.0\n0.0 nem:4 velocity 180.0,0.0,10.0\n#\n30.0 nem:1 velocity 20.0,0.0,10.0\n30.0 nem:1 orientation 0.0,0.0,10.0\n30.0 nem:1 antennaprofile 1,60.0,0.0\n30.0 nem:4 velocity 270.0,0.0,10.0\n#\n60.0 nem:1 antennaprofile 1,105.0,0.0\n60.0 nem:4 antennaprofile 2,45.0,0.0\n#\n90.0 nem:1 velocity 90.0,0.0,10.0\n90.0 nem:1 orientation 0.0,0.0,0.0\n90.0 nem:1 antennaprofile 1,45.0,0.0\nRun the EMANE event service, monitor what is output on n1 for events dumped and see the link changes within the CORE GUI.
emaneeventservice -l 3 eventservice.xml\nThe events sent will trigger 4 different states.
Introduction to using the EMANE event service and eel files to provide events.
EMANE Demo 1 for more specifics.
"},{"location":"emane/eel.html#run-demo","title":"Run Demo","text":"Open... within the GUIemane-demo-eel.xmlThis demo will go over defining an EMANE event service and eel file to drive an emane event service.
"},{"location":"emane/eel.html#viewing-events","title":"Viewing Events","text":"On n1 we will use the EMANE event dump utility to listen to events.
root@n1:/tmp/pycore.46777/n1.conf# emaneevent-dump -i ctrl0\nOn the host machine we will create the following files and start the EMANE event service targeting the control network.
Warning
Make sure to set the eventservicedevice to the proper control network value
Create eventservice.xml with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE eventservice SYSTEM \"file:///usr/share/emane/dtd/eventservice.dtd\">\n<eventservice>\n<param name=\"eventservicegroup\" value=\"224.1.2.8:45703\"/>\n<param name=\"eventservicedevice\" value=\"b.9001.f\"/>\n<generator definition=\"eelgenerator.xml\"/>\n</eventservice>\nNext we will create the eelgenerator.xml file. The EEL Generator is actually a plugin that loads sentence parsing plugins. The sentence parsing plugins know how to convert certain sentences, in this case commeffect, location, velocity, orientation, pathloss and antennaprofile sentences, into their corresponding emane event equivalents.
These configuration items tell the EEL Generator which sentences to map to which plugin and whether to issue delta or full updates.
Create eelgenerator.xml with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE eventgenerator SYSTEM \"file:///usr/share/emane/dtd/eventgenerator.dtd\">\n<eventgenerator library=\"eelgenerator\">\n<param name=\"inputfile\" value=\"scenario.eel\"/>\n<paramlist name=\"loader\">\n<item value=\"commeffect:eelloadercommeffect:delta\"/>\n<item value=\"location,velocity,orientation:eelloaderlocation:delta\"/>\n<item value=\"pathloss:eelloaderpathloss:delta\"/>\n<item value=\"antennaprofile:eelloaderantennaprofile:delta\"/>\n</paramlist>\n</eventgenerator>\nFinally, create scenario.eel with the following contents.
0.0 nem:1 pathloss nem:2,90.0\n0.0 nem:2 pathloss nem:1,90.0\n0.0 nem:1 location gps 40.031075,-74.523518,3.000000\n0.0 nem:2 location gps 40.031165,-74.523412,3.000000\nStart the EMANE event service using the files created above.
emaneeventservice eventservice.xml -l 3\nIf we go back to look at our original terminal we will see the events logged out to the terminal.
root@n1:/tmp/pycore.46777/n1.conf# emaneevent-dump -i ctrl0\n[1601858142.917224] nem: 0 event: 100 len: 66 seq: 1 [Location]\nUUID: 0af267be-17d3-4103-9f76-6f697e13bcec\n (1, {'latitude': 40.031075, 'altitude': 3.0, 'longitude': -74.823518})\n(2, {'latitude': 40.031165, 'altitude': 3.0, 'longitude': -74.523412})\n[1601858142.917466] nem: 1 event: 101 len: 14 seq: 2 [Pathloss]\nUUID: 0af267be-17d3-4103-9f76-6f697e13bcec\n (2, {'forward': 90.0, 'reverse': 90.0})\n[1601858142.917889] nem: 2 event: 101 len: 14 seq: 3 [Pathloss]\nUUID: 0af267be-17d3-4103-9f76-6f697e13bcec\n (1, {'forward': 90.0, 'reverse': 90.0})\nIntroduction to the XML files generated by CORE used to drive EMANE for a given node.
EMANE Demo 0 may provide more helpful details.
"},{"location":"emane/files.html#run-demo","title":"Run Demo","text":"Open... within the GUIemane-demo-files.xmlWe will take a look at the files generated in the example demo provided. In this case we are running the RF Pipe model.
"},{"location":"emane/files.html#generated-files","title":"Generated Files","text":"Name Description \\-platform.xml configuration file for the emulator instances \\-nem.xml configuration for creating a NEM \\-mac.xml configuration for defining a NEMs MAC layer \\-phy.xml configuration for defining a NEMs PHY layer \\-trans-virtual.xml configuration when a virtual transport is being used \\-trans.xml configuration when a raw transport is being used"},{"location":"emane/files.html#listing-file","title":"Listing File","text":"Below are the files within n1 after starting the demo session.
root@n1:/tmp/pycore.46777/n1.conf# ls\neth0-mac.xml eth0-trans-virtual.xml n1-platform.xml var.log\neth0-nem.xml ipforward.sh quaggaboot.sh var.run\neth0-phy.xml n1-emane.log usr.local.etc.quagga var.run.quagga\nThe 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.
root@n1:/tmp/pycore.46777/n1.conf# cat n1-platform.xml\n<?xml version='1.0' encoding='UTF-8'?>\n<!DOCTYPE platform SYSTEM \"file:///usr/share/emane/dtd/platform.dtd\">\n<platform>\n <param name=\"antennaprofilemanifesturi\" value=\"\"/>\n <param name=\"controlportendpoint\" value=\"0.0.0.0:47000\"/>\n <param name=\"eventservicedevice\" value=\"ctrl0\"/>\n <param name=\"eventservicegroup\" value=\"224.1.2.8:45703\"/>\n <param name=\"eventservicettl\" value=\"1\"/>\n <param name=\"otamanagerchannelenable\" value=\"1\"/>\n <param name=\"otamanagerdevice\" value=\"ctrl0\"/>\n <param name=\"otamanagergroup\" value=\"224.1.2.8:45702\"/>\n <param name=\"otamanagerloopback\" value=\"0\"/>\n <param name=\"otamanagermtu\" value=\"0\"/>\n <param name=\"otamanagerpartcheckthreshold\" value=\"2\"/>\n <param name=\"otamanagerparttimeoutthreshold\" value=\"5\"/>\n <param name=\"otamanagerttl\" value=\"1\"/>\n <param name=\"stats.event.maxeventcountrows\" value=\"0\"/>\n <param name=\"stats.ota.maxeventcountrows\" value=\"0\"/>\n <param name=\"stats.ota.maxpacketcountrows\" value=\"0\"/>\n <nem id=\"1\" name=\"tap1.0.f\" definition=\"eth0-nem.xml\">\n <transport definition=\"eth0-trans-virtual.xml\">\n <param name=\"device\" value=\"eth0\"/>\n </transport>\n </nem>\n</platform>\nThe nem definition will contain reference to the transport, mac, and phy xml definitions being used for a given nem.
root@n1:/tmp/pycore.46777/n1.conf# cat eth0-nem.xml\n<?xml version='1.0' encoding='UTF-8'?>\n<!DOCTYPE nem SYSTEM \"file:///usr/share/emane/dtd/nem.dtd\">\n<nem name=\"emane_rfpipe NEM\">\n <transport definition=\"eth0-trans-virtual.xml\"/>\n <mac definition=\"eth0-mac.xml\"/>\n <phy definition=\"eth0-phy.xml\"/>\n</nem>\nMAC layer configuration settings would be found in this file. CORE will write out all values, even if the value is a default value.
root@n1:/tmp/pycore.46777/n1.conf# cat eth0-mac.xml\n<?xml version='1.0' encoding='UTF-8'?>\n<!DOCTYPE mac SYSTEM \"file:///usr/share/emane/dtd/mac.dtd\">\n<mac name=\"emane_rfpipe MAC\" library=\"rfpipemaclayer\">\n <param name=\"datarate\" value=\"1000000\"/>\n <param name=\"delay\" value=\"0.000000\"/>\n <param name=\"enablepromiscuousmode\" value=\"0\"/>\n <param name=\"flowcontrolenable\" value=\"0\"/>\n <param name=\"flowcontroltokens\" value=\"10\"/>\n <param name=\"jitter\" value=\"0.000000\"/>\n <param name=\"neighbormetricdeletetime\" value=\"60.000000\"/>\n <param name=\"pcrcurveuri\" value=\"/usr/share/emane/xml/models/mac/rfpipe/rfpipepcr.xml\"/>\n <param name=\"radiometricenable\" value=\"0\"/>\n <param name=\"radiometricreportinterval\" value=\"1.000000\"/>\n</mac>\nPHY layer configuration settings would be found in this file. CORE will write out all values, even if the value is a default value.
root@n1:/tmp/pycore.46777/n1.conf# cat eth0-phy.xml\n<?xml version='1.0' encoding='UTF-8'?>\n<!DOCTYPE phy SYSTEM \"file:///usr/share/emane/dtd/phy.dtd\">\n<phy name=\"emane_rfpipe PHY\">\n <param name=\"bandwidth\" value=\"1000000\"/>\n <param name=\"fading.model\" value=\"none\"/>\n <param name=\"fading.nakagami.distance0\" value=\"100.000000\"/>\n <param name=\"fading.nakagami.distance1\" value=\"250.000000\"/>\n <param name=\"fading.nakagami.m0\" value=\"0.750000\"/>\n <param name=\"fading.nakagami.m1\" value=\"1.000000\"/>\n <param name=\"fading.nakagami.m2\" value=\"200.000000\"/>\n <param name=\"fixedantennagain\" value=\"0.000000\"/>\n <param name=\"fixedantennagainenable\" value=\"1\"/>\n <param name=\"frequency\" value=\"2347000000\"/>\n <param name=\"frequencyofinterest\" value=\"2347000000\"/>\n <param name=\"noisebinsize\" value=\"20\"/>\n <param name=\"noisemaxclampenable\" value=\"0\"/>\n <param name=\"noisemaxmessagepropagation\" value=\"200000\"/>\n <param name=\"noisemaxsegmentduration\" value=\"1000000\"/>\n <param name=\"noisemaxsegmentoffset\" value=\"300000\"/>\n <param name=\"noisemode\" value=\"none\"/>\n <param name=\"propagationmodel\" value=\"2ray\"/>\n <param name=\"subid\" value=\"1\"/>\n <param name=\"systemnoisefigure\" value=\"4.000000\"/>\n <param name=\"timesyncthreshold\" value=\"10000\"/>\n <param name=\"txpower\" value=\"0.000000\"/>\n</phy>\nroot@n1:/tmp/pycore.46777/n1.conf# cat eth0-trans-virtual.xml\n<?xml version='1.0' encoding='UTF-8'?>\n<!DOCTYPE transport SYSTEM \"file:///usr/share/emane/dtd/transport.dtd\">\n<transport name=\"Virtual Transport\" library=\"transvirtual\">\n <param name=\"bitrate\" value=\"0\"/>\n <param name=\"devicepath\" value=\"/dev/net/tun\"/>\n</transport>\nIntroduction to integrating gpsd in CORE with EMANE.
EMANE Demo 0 may provide more helpful details.
Warning
Requires installation of gpsd
"},{"location":"emane/gpsd.html#run-demo","title":"Run Demo","text":"Open... within the GUIemane-demo-gpsd.xmlThis section will cover how to run a gpsd location agent within EMANE, that will write out locations to a pseudo terminal file. That file can be read in by the gpsd server and make EMANE location events available to gpsd clients.
"},{"location":"emane/gpsd.html#emane-gpsd-event-daemon","title":"EMANE GPSD Event Daemon","text":"First create an eventdaemon.xml file on n1 with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE eventdaemon SYSTEM \"file:///usr/share/emane/dtd/eventdaemon.dtd\">\n<eventdaemon nemid=\"1\">\n<param name=\"eventservicegroup\" value=\"224.1.2.8:45703\"/>\n<param name=\"eventservicedevice\" value=\"ctrl0\"/>\n<agent definition=\"gpsdlocationagent.xml\"/>\n</eventdaemon>\nThen create the gpsdlocationagent.xml file on n1 with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE eventagent SYSTEM \"file:///usr/share/emane/dtd/eventagent.dtd\">\n<eventagent library=\"gpsdlocationagent\">\n<param name=\"pseudoterminalfile\" value=\"gps.pty\"/>\n</eventagent>\nStart the EMANE event agent. This will facilitate feeding location events out to a pseudo terminal file defined above.
emaneeventd eventdaemon.xml -r -d -l 3 -f emaneeventd.log\nStart gpsd, reading in the pseudo terminal file.
gpsd -G -n -b $(cat gps.pty)\nEEL Events will be played out from the actual host machine over the designated control network interface. Create the following files in the same directory somewhere on your host.
Note
Make sure the below eventservicedevice matches the control network device being used on the host for EMANE
Create eventservice.xml on the host machine with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE eventservice SYSTEM \"file:///usr/share/emane/dtd/eventservice.dtd\">\n<eventservice>\n<param name=\"eventservicegroup\" value=\"224.1.2.8:45703\"/>\n<param name=\"eventservicedevice\" value=\"b.9001.1\"/>\n<generator definition=\"eelgenerator.xml\"/>\n</eventservice>\nCreate eelgenerator.xml on the host machine with the following contents.
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE eventgenerator SYSTEM \"file:///usr/share/emane/dtd/eventgenerator.dtd\">\n<eventgenerator library=\"eelgenerator\">\n<param name=\"inputfile\" value=\"scenario.eel\"/>\n<paramlist name=\"loader\">\n<item value=\"commeffect:eelloadercommeffect:delta\"/>\n<item value=\"location,velocity,orientation:eelloaderlocation:delta\"/>\n<item value=\"pathloss:eelloaderpathloss:delta\"/>\n<item value=\"antennaprofile:eelloaderantennaprofile:delta\"/>\n</paramlist>\n</eventgenerator>\nCreate scenario.eel file with the following contents.
0.0 nem:1 location gps 40.031075,-74.523518,3.000000\n0.0 nem:2 location gps 40.031165,-74.523412,3.000000\nStart the EEL event service, which will send the events defined in the file above over the control network to all EMANE nodes. These location events will be received and provided to gpsd. This allows gpsd client to connect to and get gps locations.
emaneeventservice eventservice.xml -l 3\nIntroduction to using the precomputed propagation model.
EMANE Demo 1 for more specifics.
"},{"location":"emane/precomputed.html#run-demo","title":"Run Demo","text":"Open... within the GUIemane-demo-precomputed.xmlThis demo is using the RF Pipe model with the propagation model set to precomputed.
"},{"location":"emane/precomputed.html#failed-pings","title":"Failed Pings","text":"Due to using precomputed and having not sent any pathloss events, the nodes cannot ping each other yet.
Open a terminal on n1.
root@n1:/tmp/pycore.46777/n1.conf# ping 10.0.0.2\nconnect: Network is unreachable\nYou can leverage emanesh to investigate why packets are being dropped.
root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy BroadcastPacketDropTable0 UnicastPacketDropTable0\nnem 1 phy BroadcastPacketDropTable0\n| NEM | Out-of-Band | Rx Sensitivity | Propagation Model | Gain Location | Gain Horizon | Gain Profile | Not FOI | Spectrum Clamp | Fade Location | Fade Algorithm | Fade Select |\n| 2 | 0 | 0 | 169 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |\n\nnem 1 phy UnicastPacketDropTable0\n| NEM | Out-of-Band | Rx Sensitivity | Propagation Model | Gain Location | Gain Horizon | Gain Profile | Not FOI | Spectrum Clamp | Fade Location | Fade Algorithm | Fade Select |\nIn the example above we can see that the reason packets are being dropped is due to the propogation model and that is because we have not issued any pathloss events. You can run another command to validate if you have received any pathloss events.
root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable\nnem 1 phy PathlossEventInfoTable\n| NEM | Forward Pathloss | Reverse Pathloss |\nOn the host we will send pathloss events from all nems to all other nems.
Note
Make sure properly specify the right control network device
emaneevent-pathloss 1:2 90 -i <controlnet device>\nNow if we check for pathloss events on n2 we will see what was just sent above.
root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable\nnem 1 phy PathlossEventInfoTable\n| NEM | Forward Pathloss | Reverse Pathloss |\n| 2 | 90.0 | 90.0\nYou should also now be able to ping n1 from n2.
root@n1:/tmp/pycore.46777/n1.conf# ping -c 3 10.0.0.2\nPING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.\n64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=3.06 ms\n64 bytes from 10.0.0.2: icmp_seq=2 ttl=64 time=2.12 ms\n64 bytes from 10.0.0.2: icmp_seq=3 ttl=64 time=1.99 ms\n\n--- 10.0.0.2 ping statistics ---\n3 packets transmitted, 3 received, 0% packet loss, time 2001ms\nrtt min/avg/max/mdev = 1.991/2.393/3.062/0.479 ms\nThe BIRD Internet Routing Daemon is a routing daemon; i.e., a software responsible for managing kernel packet forwarding tables. It aims to develop a dynamic IP routing daemon with full support of all modern routing protocols, easy to use configuration interface and powerful route filtering language, primarily targeted on (but not limited to) Linux and other UNIX-like systems and distributed under the GNU General Public License. BIRD has a free implementation of several well known and common routing and router-supplemental protocols, namely RIP, RIPng, OSPFv2, OSPFv3, BGP, BFD, and NDP/RA. BIRD supports IPv4 and IPv6 address families, Linux kernel and several BSD variants (tested on FreeBSD, NetBSD and OpenBSD). BIRD consists of bird daemon and birdc interactive CLI client used for supervision.
In order to be able to use the BIRD Internet Routing Protocol, you must first install the project on your machine.
"},{"location":"services/bird.html#bird-package-install","title":"BIRD Package Install","text":"sudo apt-get install bird\nYou can download BIRD source code from its official repository.
./configure\nmake\nsu\nmake install\nvi /etc/bird/bird.conf\nThe installation will place the bird directory inside /etc where you will also find its config file.
In order to be able to do use the Bird Internet Routing Protocol, you must modify bird.conf due to the fact that the given configuration file is not configured beyond allowing the bird daemon to start, which means that nothing else will happen if you run it.
"},{"location":"services/emane.html","title":"EMANE Services","text":""},{"location":"services/emane.html#overview","title":"Overview","text":"EMANE related services for CORE.
"},{"location":"services/emane.html#transport-service","title":"Transport Service","text":"Helps with setting up EMANE for using an external transport.
"},{"location":"services/frr.html","title":"FRRouting","text":""},{"location":"services/frr.html#overview","title":"Overview","text":"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:
Ubuntu 19.10 and later
sudo apt update && sudo apt install frr\nUbuntu 16.04 and Ubuntu 18.04
sudo apt install curl\ncurl -s https://deb.frrouting.org/frr/keys.asc | sudo apt-key add -\nFRRVER=\"frr-stable\"\necho deb https://deb.frrouting.org/frr $(lsb_release -s -c) $FRRVER | sudo tee -a /etc/apt/sources.list.d/frr.list\nsudo apt update && sudo apt install frr frr-pythontools\nFedora 31
sudo dnf update && sudo dnf install frr\nBuilding 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\u2019s documentation.
FRR\u2019s source is available on the project GitHub page.
git clone https://github.com/FRRouting/frr.git\nChange into your FRR source directory and issue:
./bootstrap.sh\nThen, choose the configuration options that you wish to use for the installation. You can find these options on FRR's official webpage. Once you have chosen your configure options, run the configure script and pass the options you chose:
./configure \\\n--prefix=/usr \\\n--enable-exampledir=/usr/share/doc/frr/examples/ \\\n--localstatedir=/var/run/frr \\\n--sbindir=/usr/lib/frr \\\n--sysconfdir=/etc/frr \\\n--enable-pimd \\\n--enable-watchfrr \\\n...\nAfter configuring the software, you are ready to build and install it in your system.
make && sudo make install\nIf everything finishes successfully, FRR should be installed.
"},{"location":"services/nrl.html","title":"NRL Services","text":""},{"location":"services/nrl.html#overview","title":"Overview","text":"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:
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.
"},{"location":"services/nrl.html#multi-generator-mgen","title":"Multi-Generator (MGEN)","text":"Download MGEN from the NRL MGEN Repo, unpack it and copy the protolib library into the main folder mgen. Execute the following commands to build the protocol.
cd mgen/makefiles\nmake -f Makefile.{os} mgen\nDownload NHDP from the NRL NHDP Repo.
sudo apt-get install libpcap-dev libboost-all-dev\nwget https://github.com/protocolbuffers/protobuf/releases/download/v3.8.0/protoc-3.8.0-linux-x86_64.zip\nunzip protoc-3.8.0-linux-x86_64.zip\nThen place the binaries in your $PATH. To know your paths you can issue the following command
echo $PATH\nGo to the downloaded NHDP tarball, unpack it and place the protolib library inside the NHDP main folder. Now, compile the NHDP Protocol.
cd nhdp/unix\nmake -f Makefile.{os}\nDownload SMF from the NRL SMF Repo , unpack it and place the protolib library inside the smf main folder.
cd mgen/makefiles\nmake -f Makefile.{os}\nTo install the OLSR protocol, download their source code from their NRL OLSR Repo. Unpack it and place the previously downloaded protolib library inside the nrlolsr main directory. Then execute the following commands:
cd ./unix\nmake -f Makefile.{os}\nQuagga 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. 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.
"},{"location":"services/quagga.html#quagga-package-install","title":"Quagga Package Install","text":"sudo apt-get install quagga\nFirst, download the source code from their official webpage.
sudo apt-get install gawk\nExtract the tarball, go to the directory of your currently extracted code and issue the following commands.
./configure\nmake\nsudo make install\nRyu 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.
"},{"location":"services/sdn.html#installation","title":"Installation","text":""},{"location":"services/sdn.html#prerequisites","title":"Prerequisites","text":"sudo apt-get install gcc python-dev libffi-dev libssl-dev libxml2-dev libxslt1-dev zlib1g-dev\npip install ryu\ngit clone git://github.com/osrg/ryu.git\ncd ryu\npip install .\nThe 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.
"},{"location":"services/security.html#installation","title":"Installation","text":"Libraries needed for some security services.
sudo apt-get install ipsec-tools racoon\nBelow is a set of instruction for running a very simple OpenVPN client/server scenario.
"},{"location":"services/security.html#installation_1","title":"Installation","text":"# install openvpn\nsudo apt install openvpn\n\n# retrieve easyrsa3 for key/cert generation\ngit clone https://github.com/OpenVPN/easy-rsa\n# navigate into easyrsa3 repo subdirectory that contains built binary\ncd easy-rsa/easyrsa3\n\n# initalize pki\n./easyrsa init-pki\n\n# build ca\n./easyrsa build-ca\n\n# generate and sign server keypair(s)\nSERVER_NAME=server1\n./easyrsa get-req $SERVER_NAME nopass\n./easyrsa sign-req server $SERVER_NAME\n\n# generate and sign client keypair(s)\nCLIENT_NAME=client1\n./easyrsa get-req $CLIENT_NAME nopass\n./easyrsa sign-req client $CLIENT_NAME\n\n# DH generation\n./easyrsa gen-dh\n\n# create directory for keys for CORE to use\n# NOTE: the default is set to a directory that requires using sudo, but can be\n# anywhere and not require sudo at all\nKEYDIR=/etc/core/keys\nsudo mkdir $KEYDIR\n\n# move keys to directory\nsudo cp pki/ca.crt $KEYDIR\nsudo cp pki/issued/*.crt $KEYDIR\nsudo cp pki/private/*.key $KEYDIR\nsudo cp pki/dh.pem $KEYDIR/dh1024.pem\nAdd VPNServer service to nodes desired for running an OpenVPN server.
Modify sampleVPNServer for the following
Add VPNClient service to nodes desired for acting as an OpenVPN client.
Modify sampleVPNClient for the following
Variety of convenience services for carrying out common networking changes.
The following services are provided as utilities:
To install the functionality of the previously metioned services you can run the following command:
sudo apt-get install isc-dhcp-server apache2 libpcap-dev radvd at\nUCARP 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.
"},{"location":"services/utility.html#installation_1","title":"Installation","text":"sudo apt-get install ucarp\nXORP 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'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 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.
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.
"},{"location":"services/xorp.html#installation","title":"Installation","text":"In order to be able to install the XORP Routing Suite, you must first install scons in order to compile it.
sudo apt-get install scons\nThen, download XORP from its official release web page.
http://www.xorp.org/releases/current/\ncd xorp\nsudo apt-get install libssl-dev ncurses-dev\nscons\nscons install\nThese tutorials will cover various use cases within CORE. These tutorials will provide example python, gRPC, XML, and related files, as well as an explanation for their usage and purpose.
"},{"location":"tutorials/overview.html#checklist","title":"Checklist","text":"These are the items you should become familiar with for running all the tutorials below.
We assume the prior installation of CORE, using a virtual environment. You can then adjust your PATH and add an alias to help more conveniently run CORE commands.
This can be setup in your .bashrc
export PATH=$PATH:/opt/core/venv/bin\nalias sudop='sudo env PATH=$PATH'\nThere is a simple TCP chat app provided as example software to use and run within the tutorials provided.
"},{"location":"tutorials/setup.html#installation","title":"Installation","text":"The following will install chatapp and its scripts into /usr/local, which you may need to add to PATH within node to be able to use command directly.
sudo python3 -m pip install .\nNote
Some Linux distros will not have /usr/local in their PATH and you will need to compensate.
export PATH=$PATH:/usr/local\nThe server will print and log connected clients and their messages.
usage: chatapp-server [-h] [-a ADDRESS] [-p PORT]\n\nchat app server\n\noptional arguments:\n -h, --help show this help message and exit\n-a ADDRESS, --address ADDRESS\n address to listen on (default: )\n-p PORT, --port PORT port to listen on (default: 9001)\nThe client will print and log messages from other clients and their join/leave status.
usage: chatapp-client [-h] -a ADDRESS [-p PORT]\n\nchat app client\n\noptional arguments:\n -h, --help show this help message and exit\n-a ADDRESS, --address ADDRESS\n address to listen on (default: None)\n-p PORT, --port PORT port to listen on (default: 9001)\ncustom_config_services_dir = <path for service>\nThis tutorial will cover some use cases when using a wired 2 node scenario in CORE.
"},{"location":"tutorials/tutorial1.html#files","title":"Files","text":"
Below is the list of files used for this tutorial.
This section covers interactions that can be carried out for this scenario.
Our scenario has the following nodes and addresses:
All usages below assume a clean scenario start.
"},{"location":"tutorials/tutorial1.html#using-ping","title":"Using Ping","text":"Using the command line utility ping can be a good way to verify connectivity between nodes in CORE.
sudop core-daemon\ncore-gui\nIn the GUI menu bar select File->Open..., then navigate to and select scenario.xml
You can now click on the Start Session button to run the scenario
Open a terminal on n1 by double clicking it in the GUI
ping -c 3 10.0.0.21\nPING 10.0.0.21 (10.0.0.21) 56(84) bytes of data.\n64 bytes from 10.0.0.21: icmp_seq=1 ttl=64 time=0.085 ms\n64 bytes from 10.0.0.21: icmp_seq=2 ttl=64 time=0.079 ms\n64 bytes from 10.0.0.21: icmp_seq=3 ttl=64 time=0.072 ms\n\n--- 10.0.0.21 ping statistics ---\n3 packets transmitted, 3 received, 0% packet loss, time 1999ms\nrtt min/avg/max/mdev = 0.072/0.078/0.085/0.011 ms\nUsing tcpdump can be very beneficial for examining a network. You can verify traffic being sent/received among many other uses.
sudop core-daemon\ncore-gui\nIn the GUI menu bar select File->Open..., then navigate to and select scenario.xml
You can now click on the Start Session button to run the scenario
Open a terminal on n1 by double clicking it in the GUI
tcpdump -lenni eth0\nping -c 1 10.0.0.21\ntcpdump: verbose output suppressed, use -v or -vv for full protocol decode\nlistening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes\n10:23:04.685292 00:00:00:aa:00:00 > 00:00:00:aa:00:01, ethertype IPv4 (0x0800), length 98: 10.0.0.20 > 10.0.0.21: ICMP echo request, id 67, seq 1, length 64\n10:23:04.685329 00:00:00:aa:00:01 > 00:00:00:aa:00:00, ethertype IPv4 (0x0800), length 98: 10.0.0.21 > 10.0.0.20: ICMP echo reply, id 67, seq 1, length 64\nYou can edit links between nodes in CORE to modify loss, delay, bandwidth, and more. This can be beneficial for understanding how software will behave in adverse conditions.
sudop core-daemon\ncore-gui\nIn the GUI menu bar select File->Open..., then navigate to and select scenario.xml
You can now click on the Start Session button to run the scenario
Right click the link between n1 and n2
Select Configure
Update the loss to 25
Open a terminal on n1 by double clicking it in the GUI
ping -c 10 10.0.0.21\n--- 10.0.0.21 ping statistics ---\n10 packets transmitted, 6 received, 40% packet loss, time 9000ms\nrtt min/avg/max/mdev = 0.077/0.093/0.108/0.016 ms\nWe will now leverage the installed Chat App software to stand up a server and client within the nodes of our scenario.
sudop core-daemon\ncore-gui\nIn the GUI menu bar select File->Open..., then navigate to and select scenario.xml
You can now click on the Start Session button to run the scenario
Open a terminal on n1 by double clicking it in the GUI
export PATH=$PATH:/usr/local/bin\nchatapp-server\nexport PATH=$PATH:/usr/local/bin\nchatapp-client -a 10.0.0.20\nchat server listening on: :9001\n[server] 10.0.0.21:44362 joining\nhello world\nchat server listening on: :9001\n[server] 10.0.0.21:44362 joining\n[10.0.0.21:44362] hello world\nIn this case we are using the service based scenario. This will automatically start and run the Chat App Server on n1 and log to a file. This case will demonstrate using tail -f to observe the output of running software.
sudop core-daemon\ncore-gui\nIn the GUI menu bar select File->Open..., then navigate to and select scenario_service.xml
You can now click on the Start Session button to run the scenario
Open a terminal on n1 by double clicking it in the GUI
tail -f chatapp.log\nexport PATH=$PATH:/usr/local/bin\nchatapp-client -a 10.0.0.20\nchat server listening on: :9001\n[server] 10.0.0.21:44362 joining\nhello world\nchat server listening on: :9001\n[server] 10.0.0.21:44362 joining\n[10.0.0.21:44362] hello world\nYou can also run the same steps above, using the provided gRPC script versions of scenarios. Below are the steps to run and join one of these scenario, then you can continue with the remaining steps of a given section.
sudop core-daemon\n/opt/core/venv/bin/python scenario.py\ncore-gui\n
This tutorial will cover the use of a 3 node scenario in CORE. Then running a chat server on one node and a chat client on the other. The client will send a simple message and the server will log receipt of the message.
"},{"location":"tutorials/tutorial2.html#files","title":"Files","text":"Below is the list of files used for this tutorial.
This section will cover running this sample tutorial using the XML scenario file, leveraging an NS2 mobility file.
sudop core-daemon\ncore-gui\nYou can now click play to start the session
Note that OSPF routing protocol is included in the scenario to provide routes to other nodes, as they are discovered
ping -c 2 10.0.0.2\nPING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.\n64 bytes from 10.0.0.2: icmp_seq=1 ttl=63 time=20.2 ms\n64 bytes from 10.0.0.2: icmp_seq=2 ttl=63 time=20.2 ms\n\n--- 10.0.0.2 ping statistics ---\n2 packets transmitted, 2 received, 0% packet loss, time 1000ms\nrtt min/avg/max/mdev = 20.168/20.173/20.178/0.005 ms\nRight click on the wlan1 node and select WLAN Config, then set delay to 500000
Using the open terminal for node n4, ping n2 again, expect about 2 seconds delay
ping -c 5 10.0.0.2\n64 bytes from 10.0.0.2: icmp_seq=1 ttl=63 time=2001 ms\n64 bytes from 10.0.0.2: icmp_seq=2 ttl=63 time=2000 ms\n64 bytes from 10.0.0.2: icmp_seq=3 ttl=63 time=2000 ms\n64 bytes from 10.0.0.2: icmp_seq=4 ttl=63 time=2000 ms\n64 bytes from 10.0.0.2: icmp_seq=5 ttl=63 time=2000 ms\n\n--- 10.0.0.2 ping statistics ---\n5 packets transmitted, 5 received, 0% packet loss, time 4024ms\nrtt min/avg/max/mdev = 2000.176/2000.438/2001.166/0.376 ms, pipe 2\nRight click on the wlan1 node and select WLAN Config, set delay back to 5000 and loss to 10
Using the open terminal for node n4, ping n2 again, expect to notice considerable loss
ping -c 10 10.0.0.2\nPING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.\n64 bytes from 10.0.0.2: icmp_seq=1 ttl=63 time=20.4 ms\n64 bytes from 10.0.0.2: icmp_seq=2 ttl=63 time=20.5 ms\n64 bytes from 10.0.0.2: icmp_seq=3 ttl=63 time=20.2 ms\n64 bytes from 10.0.0.2: icmp_seq=4 ttl=63 time=20.8 ms\n64 bytes from 10.0.0.2: icmp_seq=5 ttl=63 time=21.9 ms\n64 bytes from 10.0.0.2: icmp_seq=8 ttl=63 time=22.7 ms\n64 bytes from 10.0.0.2: icmp_seq=9 ttl=63 time=22.4 ms\n64 bytes from 10.0.0.2: icmp_seq=10 ttl=63 time=20.3 ms\n\n--- 10.0.0.2 ping statistics ---\n10 packets transmitted, 8 received, 20% packet loss, time 9064ms\nrtt min/avg/max/mdev = 20.188/21.143/22.717/0.967 ms\nThis section will cover running this sample tutorial using the gRPC python script and providing mobility over the gRPC interface.
sudop core-daemon\ncore-gui\n/opt/core/venv/bin/python scenario.py\n"},{"location":"tutorials/tutorial2.html#running-software","title":"Running Software","text":"
We will now leverage the installed Chat App software to stand up a server and client within the nodes of our scenario. You can use the bases of the running scenario from either scenario.xml or the scenario.py gRPC script.
export PATH=$PATH:/usr/local/bin\nchatapp-server\nexport PATH=$PATH:/usr/local/bin\nchatapp-client -a 10.0.0.4\n>>hello world\nchat server listening on: :9001\n[server] 10.0.0.2:53684 joining\n[10.0.0.2:53684] hello world\nThis tutorial will cover using a 3 node scenario in CORE with basic mobility. Mobility can be provided from a NS2 file or by including mobility commands in a gRPC script.
"},{"location":"tutorials/tutorial3.html#files","title":"Files","text":"Below is the list of files used for this tutorial.
This section will cover running this sample tutorial using the XML scenario file, leveraging an NS2 file for mobility.
sudop core-daemon\ncore-gui\n$node_(1) set X_ 208.1\n$node_(1) set Y_ 211.05\n$node_(1) set Z_ 0\n$ns_ at 0.0 \"$node_(1) setdest 208.1 211.05 0.00\"\n$node_(2) set X_ 393.1\n$node_(2) set Y_ 223.05\n$node_(2) set Z_ 0\n$ns_ at 0.0 \"$node_(2) setdest 393.1 223.05 0.00\"\n$node_(4) set X_ 499.1\n$node_(4) set Y_ 186.05\n$node_(4) set Z_ 0\n$ns_ at 0.0 \"$node_(4) setdest 499.1 186.05 0.00\"\n$ns_ at 1.0 \"$node_(1) setdest 190.1 225.05 0.00\"\n$ns_ at 1.0 \"$node_(2) setdest 393.1 225.05 0.00\"\n$ns_ at 1.0 \"$node_(4) setdest 515.1 186.05 0.00\"\n$ns_ at 2.0 \"$node_(1) setdest 175.1 250.05 0.00\"\n$ns_ at 2.0 \"$node_(2) setdest 393.1 250.05 0.00\"\n$ns_ at 2.0 \"$node_(4) setdest 530.1 186.05 0.00\"\n$ns_ at 3.0 \"$node_(1) setdest 160.1 275.05 0.00\"\n$ns_ at 3.0 \"$node_(2) setdest 393.1 275.05 0.00\"\n$ns_ at 3.0 \"$node_(4) setdest 530.1 186.05 0.00\"\n$ns_ at 4.0 \"$node_(1) setdest 160.1 300.05 0.00\"\n$ns_ at 4.0 \"$node_(2) setdest 393.1 300.05 0.00\"\n$ns_ at 4.0 \"$node_(4) setdest 550.1 186.05 0.00\"\n$ns_ at 5.0 \"$node_(1) setdest 160.1 275.05 0.00\"\n$ns_ at 5.0 \"$node_(2) setdest 393.1 275.05 0.00\"\n$ns_ at 5.0 \"$node_(4) setdest 530.1 186.05 0.00\"\n$ns_ at 6.0 \"$node_(1) setdest 175.1 250.05 0.00\"\n$ns_ at 6.0 \"$node_(2) setdest 393.1 250.05 0.00\"\n$ns_ at 6.0 \"$node_(4) setdest 515.1 186.05 0.00\"\n$ns_ at 7.0 \"$node_(1) setdest 190.1 225.05 0.00\"\n$ns_ at 7.0 \"$node_(2) setdest 393.1 225.05 0.00\"\n$ns_ at 7.0 \"$node_(4) setdest 499.1 186.05 0.00\"\n"},{"location":"tutorials/tutorial3.html#running-with-the-grpc-script","title":"Running with the gRPC Script","text":"
This section covers using a gRPC script to create and provide scenario movement.
sudop core-daemon\n/opt/core/venv/bin/python scenario.py\ncore-gui\nIn the terminal running the scenario.py, hit a key to start motion
Observe the link between n3 and n4 is shown and then as motion continues the link breaks
This section covers using one of the above 2 scenarios to run software within the nodes.
export PATH=$PATH:/usr/local/bin\nchatapp-server\nexport PATH=$PATH:/usr/local/bin\nchatapp-client -a 10.0.0.4\n>>hello world\nchat server listening on: :9001\n[server] 10.0.0.2:53684 joining\n[10.0.0.2:53684] hello world\nThis section provides an example for running a script within a node, that leverages a control network in CORE for issuing mobility using the gRPC API.
grpcaddress = 0.0.0.0\n/opt/core/venv/bin/python move-node2.py\n"},{"location":"tutorials/tutorial4.html","title":"Tutorial 4 - Tests","text":""},{"location":"tutorials/tutorial4.html#overview","title":"Overview","text":"
A use case for CORE would be to help automate integration tests for running software within a network. This tutorial covers using CORE with the python pytest testing framework. It will show how you can define tests, for different use cases to validate software and outcomes within a defined network. Using pytest, you would create tests using all the standard pytest functionality. Creating a test file, and then defining test functions to run. For these tests, we are leveraging the CORE library directly and the API it provides.
Refer to the pytest documentation for indepth information on how to write tests with pytest.
"},{"location":"tutorials/tutorial4.html#files","title":"Files","text":"A directory is used for containing your tests. Within this directory we need a conftest.py, which pytest will pick up to help define and provide test fixtures, which will be leveraged within our tests.
Below are the definitions for fixture you can define to facilitate and make creating CORE based tests easier.
The global session fixture creates one CoreEmu object for the entire test session, yields it for testing, and calls shutdown when everything is over.
@pytest.fixture(scope=\"session\")\ndef global_session():\n core = CoreEmu()\n session = core.create_session()\n session.set_state(EventTypes.CONFIGURATION_STATE)\n yield session\n core.shutdown()\nThe regular session fixture leverages the global session fixture. It will set the correct state for each test case, yield the session for a test, and then clear the session after a test finishes to prepare for the next test.
@pytest.fixture\ndef session(global_session):\n global_session.set_state(EventTypes.CONFIGURATION_STATE)\n yield global_session\n global_session.clear()\nThe ip prefixes fixture help provide a preconfigured convenience for creating and assigning interfaces to nodes, when creating your network within a test. The address subnet can be whatever you desire.
@pytest.fixture(scope=\"session\")\ndef ip_prefixes():\n return IpPrefixes(ip4_prefix=\"10.0.0.0/24\")\nWithin a pytest test file, you have the freedom to create any kind of test you like, but they will all follow a similar formula.
In the test below, we create a simple 2 node wired network and validate node1 can ping node2 successfully.
def test_success(self, session: Session, ip_prefixes: IpPrefixes):\n # create nodes\n node1 = session.add_node(CoreNode)\n node2 = session.add_node(CoreNode)\n\n # link nodes together\n iface1_data = ip_prefixes.create_iface(node1)\n iface2_data = ip_prefixes.create_iface(node2)\n session.add_link(node1.id, node2.id, iface1_data, iface2_data)\n\n # ping node, expect a successful command\n node1.cmd(f\"ping -c 1 {iface2_data.ip4}\")\nSince we are running an automated test within CORE, we will need to install pytest within the python interpreter used by CORE.
sudo /opt/core/venv/bin/python -m pip install pytest\nYou can run your own or the provided tests, by running the following.
cd <test directory>\nsudo /opt/core/venv/bin/python -m pytest -v\nIf you run the provided tests, you would expect to see the two tests running and passing.
tests/test_ping.py::TestPing::test_success PASSED [ 50%]\ntests/test_ping.py::TestPing::test_failure PASSED [100%]\nThis tutorial will cover connecting CORE VM to a Windows host machine using a RJ45 node.
"},{"location":"tutorials/tutorial5.html#files","title":"Files","text":"Below is the list of files used for this tutorial.
This section covers using the saved scenario.xml file to get and up and running.
Configure the Windows host VM to have a bridged network adapter
Make sure the core-daemon is running in a terminal
sudop core-daemon\ncore-gui\nOpen the scenario.xml with the unassigned RJ45 node
Configure the RJ45 node name to use the bridged interface
After configuring the RJ45, run the scenario:
Double click node n1 to open a terminal and add a route to the Windows host
ip route add 192.168.0.0/24 via 10.0.0.20\n# if enp0s3 is ssigned 192.168.0.6/24\nroute add 10.0.0.0 mask 255.255.255.0 192.168.0.6\nC:\\WINDOWS\\system32>ping 10.0.0.20\n\nPinging 10.0.0.20 with 32 bytes of data:\nReply from 10.0.0.20: bytes=32 time<1ms TTL=64\nReply from 10.0.0.20: bytes=32 time<1ms TTL=64\nReply from 10.0.0.20: bytes=32 time<1ms TTL=64\nReply from 10.0.0.20: bytes=32 time<1ms TTL=64\n\nPing statistics for 10.0.0.20:\n Packets: Sent = 4, Received = 4, Lost = 0 (0% loss)\nApproximate round trip times in milli-seconds:\n Minimum = 0ms, Maximum = 0ms, Average = 0ms\nexport PATH=$PATH:/usr/local/bin\nchatapp-server\npython3 client_for_windows.py -a 10.0.0.20\nconnected to server(10.0.0.20:9001) as client(192.168.0.6:49960)\n>> .Hello WORLD\n.Hello WORLD Again\n.\nchat server listening on: :9001\n[server] 192.168.0.6:49960 joining\n[192.168.0.6:49960] Hello WORLD\n[192.168.0.6:49960] Hello WORLD Again\nroute delete 10.0.0.0\nThis section covers leveraging the gRPC script to get up and running.
Configure the Windows host VM to have a bridged network adapter
Make sure the core-daemon is running in a terminal
sudop core-daemon\ncore-gui\n# use the desired interface name, in this case enp0s3\n/opt/core/venv/bin/python scenario.py enp0s3\nIn the core-gui connect to the running session that was created
Double click node n1 to open a terminal and add a route to the Windows host
ip route add 192.168.0.0/24 via 10.0.0.20\n# if enp0s3 is ssigned 192.168.0.6/24\nroute add 10.0.0.0 mask 255.255.255.0 192.168.0.6\nC:\\WINDOWS\\system32>ping 10.0.0.20\n\nPinging 10.0.0.20 with 32 bytes of data:\nReply from 10.0.0.20: bytes=32 time<1ms TTL=64\nReply from 10.0.0.20: bytes=32 time<1ms TTL=64\nReply from 10.0.0.20: bytes=32 time<1ms TTL=64\nReply from 10.0.0.20: bytes=32 time<1ms TTL=64\n\nPing statistics for 10.0.0.20:\n Packets: Sent = 4, Received = 4, Lost = 0 (0% loss)\nApproximate round trip times in milli-seconds:\n Minimum = 0ms, Maximum = 0ms, Average = 0ms\nexport PATH=$PATH:/usr/local/bin\nchatapp-server\npython3 client_for_windows.py -a 10.0.0.20\nconnected to server(10.0.0.20:9001) as client(192.168.0.6:49960)\n>> .Hello WORLD\n.Hello WORLD Again\n.\nchat server listening on: :9001\n[server] 192.168.0.6:49960 joining\n[192.168.0.6:49960] Hello WORLD\n[192.168.0.6:49960] Hello WORLD Again\nroute delete 10.0.0.0\nThis tutorial will cover changing the node icons, changing the background, and changing or hiding links.
"},{"location":"tutorials/tutorial6.html#files","title":"Files","text":"Below is the list of files used for this tutorial.
This section will cover running this sample tutorial that develops a scenario file.
sudop core-daemon\ncore-gui\nCreate three MDR nodes
Double click on each node for configuration, click the icon and set it to use the drone.png image
Use Session -> Options and set Control Network 0 to 172.16.0.0./24
Link the three prior MDR nodes to the WLAN node
Click play to start the scenario
Observe wireless links being created
Click stop to end the scenario
Click Canvas -> Wallpaper to set the background to terrain.png
Click play to start the scenario again
# node id is first parameter, second is total nodes\n/opt/core/venv/bin/python demo.py 1 3\nLet it run to see the link break as the node 1 drone approches the right side
Repeat for other nodes, double click on n2 and n3 and run the demo.py script
# n2\n/opt/core/venv/bin/python demo.py 2 3\n# n3\n/opt/core/venv/bin/python demo.py 3 3\n
This tutorial will cover basic usage and some concepts one may want to use or leverage when working with and creating EMANE based networks.
For more detailed information on EMANE see the following:
Below is a list of the files used for this tutorial.
This section covers interactions that can be carried out for this scenario.
Our scenario has the following nodes and addresses:
All usages below assume a clean scenario start.
"},{"location":"tutorials/tutorial7.html#using-ping","title":"Using Ping","text":"Using the command line utility ping can be a good way to verify connectivity between nodes in CORE.
sudop core-daemon\ncore-gui\nIn the GUI menu bar select File->Open..., then navigate to and select scenario.xml
You can now click on the Start Session button to run the scenario
Open a terminal on n2 by double clicking it in the GUI
ping -c 3 10.0.0.2\nPING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.\n64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=7.93 ms\n64 bytes from 10.0.0.2: icmp_seq=2 ttl=64 time=3.07 ms\n64 bytes from 10.0.0.2: icmp_seq=3 ttl=64 time=3.05 ms\n\n--- 10.0.0.2 ping statistics ---\n3 packets transmitted, 3 received, 0% packet loss, time 2000ms\nrtt min/avg/max/mdev = 3.049/4.685/7.932/2.295 ms\nUsing tcpdump can be very beneficial for examining a network. You can verify traffic being sent/received among many other uses.
sudop core-daemon\ncore-gui\nIn the GUI menu bar select File->Open..., then navigate to and select scenario.xml
You can now click on the Start Session button to run the scenario
Open a terminal on n2 by double clicking it in the GUI
tcpdump -lenni eth0\nping -c 1 10.0.0.2\ntcpdump: verbose output suppressed, use -v[v]... for full protocol decode\nlistening on eth0, link-type EN10MB (Ethernet), snapshot length 262144 bytes\n14:56:25.414283 02:02:00:00:00:01 > 02:02:00:00:00:02, ethertype IPv4 (0x0800), length 98: 10.0.0.1 > 10.0.0.2: ICMP echo request, id 64832, seq 1, length 64\n14:56:25.414303 02:02:00:00:00:02 > 02:02:00:00:00:01, ethertype IPv4 (0x0800), length 98: 10.0.0.2 > 10.0.0.1: ICMP echo reply, id 64832, seq 1, length 64\nWe will now leverage the installed Chat App software to stand up a server and client within the nodes of our scenario.
sudop core-daemon\ncore-gui\nIn the GUI menu bar select File->Open..., then navigate to and select scenario.xml
You can now click on the Start Session button to run the scenario
Open a terminal on n2 by double clicking it in the GUI
export PATH=$PATH:/usr/local/bin\nchatapp-server\nexport PATH=$PATH:/usr/local/bin\nchatapp-client -a 10.0.0.1\nchat server listening on: :9001\n[server] 10.0.0.1:44362 joining\nhello world\nchat server listening on: :9001\n[server] 10.0.0.2:44362 joining\n[10.0.0.2:44362] hello world\nIn this case we are using the service based scenario. This will automatically start and run the Chat App Server on n2 and log to a file. This case will demonstrate using tail -f to observe the output of running software.
sudop core-daemon\ncore-gui\nIn the GUI menu bar select File->Open..., then navigate to and select scenario_service.xml
You can now click on the Start Session button to run the scenario
Open a terminal on n2 by double clicking it in the GUI
tail -f chatapp.log\nexport PATH=$PATH:/usr/local/bin\nchatapp-client -a 10.0.0.1\nchat server listening on: :9001\n[server] 10.0.0.2:44362 joining\nhello world\nchat server listening on: :9001\n[server] 10.0.0.2:44362 joining\n[10.0.0.2:44362] hello world\nThis section will cover some high level topics and examples for running and using EMANE in CORE. You can find more detailed tutorials and examples at the EMANE Tutorial.
Note
Every topic below assumes CORE, EMANE, and OSPF MDR have been installed.
Scenario files to support the EMANE topics below will be found in the GUI default directory for opening XML files.
Topic Model Description XML Files RF Pipe Overview of generated XML files used to drive EMANE GPSD RF Pipe Overview of running and integrating gpsd with EMANE Precomputed RF Pipe Overview of using the precomputed propagation model EEL RF Pipe Overview of using the Emulation Event Log (EEL) Generator Antenna Profiles RF Pipe Overview of using antenna profiles in EMANE"},{"location":"tutorials/tutorial7.html#grpc-python-scripts","title":"gRPC Python Scripts","text":"You can also run the same steps above, using the provided gRPC script versions of scenarios. Below are the steps to run and join one of these scenario, then you can continue with the remaining steps of a given section.
sudop core-daemon\n/opt/core/venv/bin/python scenario.py\ncore-gui\n
You can also run the same steps above, using the provided gRPC script versions of scenarios. Below are the steps to run and join one of these scenario, then you can continue with the remaining steps of a given section.
sudop core-daemon\n/opt/core/venv/bin/python scenario.py\ncore-gui\n
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 +the services that they run.
+Services may be customized for each node, or new custom services can be +created. New node types can be created each having a different name, icon, and +set of default services. Each service defines the per-node directories, +configuration files, startup index, starting commands, validation commands, +shutdown commands, and meta-data associated with a node.
+Note
+Network namespace nodes do not undergo the normal Linux boot process +using the init, upstart, or systemd frameworks. These +lightweight nodes use configured CORE services.
+| Service Group | +Services | +
|---|---|
| BIRD | +BGP, OSPF, RADV, RIP, Static | +
| EMANE | +Transport Service | +
| FRR | +BABEL, BGP, OSPFv2, OSPFv3, PIMD, RIP, RIPNG, Zebra | +
| NRL | +arouted, MGEN Sink, MGEN Actor, NHDP, OLSR, OLSRORG, OLSRv2, SMF | +
| Quagga | +BABEL, BGP, OSPFv2, OSPFv3, OSPFv3 MDR, RIP, RIPNG, XPIMD, Zebra | +
| SDN | +OVS, RYU | +
| Security | +Firewall, IPsec, NAT, VPN Client, VPN Server | +
| Utility | +ATD, Routing Utils, DHCP, FTP, IP Forward, PCAP, RADVD, SSF, UCARP | +
| XORP | +BGP, OLSR, OSPFv2, OSPFv3, PIMSM4, PIMSM6, RIP, RIPNG, Router Manager | +
Here are the default node types and their services:
+| Node Type | +Services | +
|---|---|
| router | +zebra, OSFPv2, OSPFv3, and IPForward services for IGP link-state routing. | +
| host | +DefaultRoute and SSH services, representing an SSH server having a default route when connected directly to a router. | +
| PC | +DefaultRoute service for having a default route when connected directly to a router. | +
| mdr | +zebra, OSPFv3MDR, and IPForward services for wireless-optimized MANET Designated Router routing. | +
| prouter | +a physical router, having the same default services as the router node type; for incorporating Linux testbed machines into an emulation. | +
Configuration files can be automatically generated by each service. For +example, CORE automatically generates routing protocol configuration for the +router nodes in order to simplify the creation of virtual networks.
+To change the services associated with a node, double-click on the node to +invoke its configuration dialog and click on the Services... button, +or right-click a node a choose Services... from the menu. +Services are enabled or disabled by clicking on their names. The button next to +each service name allows you to customize all aspects of this service for this +node. For example, special route redistribution commands could be inserted in +to the Quagga routing configuration associated with the zebra service.
+To change the default services associated with a node type, use the Node Types +dialog available from the Edit button at the end of the Layer-3 nodes +toolbar, or choose Node types... from the Session menu. Note that +any new services selected are not applied to existing nodes if the nodes have +been customized.
+A service can be fully customized for a particular node. From the node's +configuration dialog, click on the button next to the service name to invoke +the service customization dialog for that service. +The dialog has three tabs for configuring the different aspects of the service: +files, directories, and startup/shutdown.
+Note
+A yellow customize icon next to a service indicates that service +requires customization (e.g. the Firewall service). +A green customize icon indicates that a custom configuration exists. +Click the Defaults button when customizing a service to remove any +customizations.
+The Files tab is used to display or edit the configuration files or scripts that +are used for this service. Files can be selected from a drop-down list, and +their contents are displayed in a text entry below. The file contents are +generated by the CORE daemon based on the network topology that exists at +the time the customization dialog is invoked.
+The Directories tab shows the per-node directories for this service. For the +default types, CORE nodes share the same filesystem tree, except for these +per-node directories that are defined by the services. For example, the +/var/run/quagga directory needs to be unique for each node running +the Zebra service, because Quagga running on each node needs to write separate +PID files to that directory.
+Note
+The /var/log and /var/run directories are
+mounted uniquely per-node by default.
+Per-node mount targets can be found in /tmp/pycore.
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
+to the other services enabled for this node; a service with a lower startup
+index value is started before those with higher values. Because shell scripts
+generated by the Files tab will not have execute permissions set, the startup
+commands should include the shell name, with
+something like sh script.sh.
Shutdown commands optionally terminate the process(es) associated with this +service. Generally they send a kill signal to the running process using the +kill or killall commands. If the service does not terminate +the running processes using a shutdown command, the processes will be killed +when the vnoded daemon is terminated (with kill -9) and +the namespace destroyed. It is a good practice to +specify shutdown commands, which will allow for proper process termination, and +for run-time control of stopping and restarting services.
+Validate commands are executed following the startup commands. A validate +command can execute a process or script that should return zero if the service +has started successfully, and have a non-zero return value for services that +have had a problem starting. For example, the pidof command will check +if a process is running and return zero when found. When a validate command +produces a non-zero return value, an exception is generated, which will cause +an error to be displayed in the Check Emulation Light.
+Note
+To start, stop, and restart services during run-time, right-click a +node and use the Services... menu.
+Services can save time required to configure nodes, especially if a number +of nodes require similar configuration procedures. New services can be +introduced to automate tasks.
+The easiest way to capture the configuration of a new process into a service +is by using the UserDefined service. This is a blank service where any +aspect may be customized. The UserDefined service is convenient for testing +ideas for a service before adding a new service type.
+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.
+Modify the example service shown below + to do what you want. It could generate config/script files, mount per-node + directories, start processes/scripts, etc. sample.py is a Python file that + defines one or more classes to be imported. You can create multiple Python + files that will be imported.
+Put these files in a directory such as /home/<user>/.coregui/custom_services
+ Note that the last component of this directory name custom_services should not
+ be named the same as any python module, due to naming conflicts.
Add a custom_services_dir = /home/<user>/.coregui/custom_services entry to the
+ /etc/core/core.conf file.
Restart the CORE daemon (core-daemon). Any import errors (Python syntax) + should be displayed in the daemon output.
+Start using your custom service on your nodes. You can create a new node + type that uses your service, or change the default services for an existing + node type, or change individual nodes.
+If you have created a new service type that may be useful to others, please +consider contributing it to the CORE project.
+Below is the skeleton for a custom service with some documentation. Most +people would likely only setup the required class variables (name/group). +Then define the configs (files they want to generate) and implement the +generate_config function to dynamically create the files wanted. Finally +the startup commands would be supplied, which typically tends to be +running the shell files generated.
+"""
+Simple example custom service, used to drive shell commands on a node.
+"""
+from typing import Tuple
+
+from core.nodes.base import CoreNode
+from core.services.coreservices import CoreService, ServiceMode
+
+
+class ExampleService(CoreService):
+ """
+ Example Custom CORE Service
+
+ :cvar name: name used as a unique ID for this service and is required, no spaces
+ :cvar group: allows you to group services within the GUI under a common name
+ :cvar executables: executables this service depends on to function, if executable is
+ not on the path, service will not be loaded
+ :cvar dependencies: services that this service depends on for startup, tuple of
+ service names
+ :cvar dirs: directories that this service will create within a node
+ :cvar configs: files that this service will generate, without a full path this file
+ goes in the node's directory e.g. /tmp/pycore.12345/n1.conf/myfile
+ :cvar startup: commands used to start this service, any non-zero exit code will
+ cause a failure
+ :cvar validate: commands used to validate that a service was started, any non-zero
+ exit code will cause a failure
+ :cvar validation_mode: validation mode, used to determine startup success.
+ NON_BLOCKING - runs startup commands, and validates success with validation commands
+ BLOCKING - runs startup commands, and validates success with the startup commands themselves
+ TIMER - runs startup commands, and validates success by waiting for "validation_timer" alone
+ :cvar validation_timer: time in seconds for a service to wait for validation, before
+ determining success in TIMER/NON_BLOCKING modes.
+ :cvar validation_period: period in seconds to wait before retrying validation,
+ only used in NON_BLOCKING mode
+ :cvar shutdown: shutdown commands to stop this service
+ """
+
+ name: str = "ExampleService"
+ group: str = "Utility"
+ executables: Tuple[str, ...] = ()
+ dependencies: Tuple[str, ...] = ()
+ dirs: Tuple[str, ...] = ()
+ configs: Tuple[str, ...] = ("myservice1.sh", "myservice2.sh")
+ startup: Tuple[str, ...] = tuple(f"sh {x}" for x in configs)
+ validate: Tuple[str, ...] = ()
+ validation_mode: ServiceMode = ServiceMode.NON_BLOCKING
+ validation_timer: int = 5
+ validation_period: float = 0.5
+ shutdown: Tuple[str, ...] = ()
+
+ @classmethod
+ def on_load(cls) -> None:
+ """
+ Provides a way to run some arbitrary logic when the service is loaded, possibly
+ to help facilitate dynamic settings for the environment.
+
+ :return: nothing
+ """
+ pass
+
+ @classmethod
+ def get_configs(cls, node: CoreNode) -> Tuple[str, ...]:
+ """
+ Provides a way to dynamically generate the config files from the node a service
+ will run. Defaults to the class definition and can be left out entirely if not
+ needed.
+
+ :param node: core node that the service is being ran on
+ :return: tuple of config files to create
+ """
+ return cls.configs
+
+ @classmethod
+ def generate_config(cls, node: CoreNode, filename: str) -> str:
+ """
+ Returns a string representation for a file, given the node the service is
+ starting on the config filename that this information will be used for. This
+ must be defined, if "configs" are defined.
+
+ :param node: core node that the service is being ran on
+ :param filename: configuration file to generate
+ :return: configuration file content
+ """
+ cfg = "#!/bin/sh\n"
+ if filename == cls.configs[0]:
+ cfg += "# auto-generated by MyService (sample.py)\n"
+ for iface in node.get_ifaces():
+ cfg += f'echo "Node {node.name} has interface {iface.name}"\n'
+ elif filename == cls.configs[1]:
+ cfg += "echo hello"
+ return cfg
+
+ @classmethod
+ def get_startup(cls, node: CoreNode) -> Tuple[str, ...]:
+ """
+ Provides a way to dynamically generate the startup commands from the node a
+ service will run. Defaults to the class definition and can be left out entirely
+ if not needed.
+
+ :param node: core node that the service is being ran on
+ :return: tuple of startup commands to run
+ """
+ return cls.startup
+
+ @classmethod
+ def get_validate(cls, node: CoreNode) -> Tuple[str, ...]:
+ """
+ Provides a way to dynamically generate the validate commands from the node a
+ service will run. Defaults to the class definition and can be left out entirely
+ if not needed.
+
+ :param node: core node that the service is being ran on
+ :return: tuple of commands to validate service startup with
+ """
+ return cls.validate
+The BIRD Internet Routing Daemon is a routing +daemon; i.e., a software responsible for managing kernel packet forwarding +tables. It aims to develop a dynamic IP routing daemon with full support of +all modern routing protocols, easy to use configuration interface and powerful +route filtering language, primarily targeted on (but not limited to) Linux and +other UNIX-like systems and distributed under the GNU General Public License. +BIRD has a free implementation of several well known and common routing and +router-supplemental protocols, namely RIP, RIPng, OSPFv2, OSPFv3, BGP, BFD, +and NDP/RA. BIRD supports IPv4 and IPv6 address families, Linux kernel and +several BSD variants (tested on FreeBSD, NetBSD and OpenBSD). BIRD consists +of bird daemon and birdc interactive CLI client used for supervision.
+In order to be able to use the BIRD Internet Routing Protocol, you must first +install the project on your machine.
+sudo apt-get install bird
+You can download BIRD source code from its +official repository.
+./configure
+make
+su
+make install
+vi /etc/bird/bird.conf
+The installation will place the bird directory inside /etc where you will +also find its config file.
+In order to be able to do use the Bird Internet Routing Protocol, you must +modify bird.conf due to the fact that the given configuration file is not +configured beyond allowing the bird daemon to start, which means that nothing +else will happen if you run it.
+ + + + + + +EMANE related services for CORE.
+Helps with setting up EMANE for using an external transport.
+ + + + + + +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:
+Ubuntu 19.10 and later
+sudo apt update && sudo apt install frr
+Ubuntu 16.04 and Ubuntu 18.04
+sudo apt install curl
+curl -s https://deb.frrouting.org/frr/keys.asc | sudo apt-key add -
+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
+sudo apt update && sudo apt install frr frr-pythontools
+Fedora 31
+sudo dnf update && sudo dnf install frr
+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.
+git clone https://github.com/FRRouting/frr.git
+Change into your FRR source directory and issue:
+./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. Once you have chosen your configure +options, run the configure script and pass the options you chose:
+./configure \
+ --prefix=/usr \
+ --enable-exampledir=/usr/share/doc/frr/examples/ \
+ --localstatedir=/var/run/frr \
+ --sbindir=/usr/lib/frr \
+ --sysconfdir=/etc/frr \
+ --enable-pimd \
+ --enable-watchfrr \
+ ...
+After configuring the software, you are ready to build and install it in your system.
+make && sudo make install
+If everything finishes successfully, FRR should be installed.
+ + + + + + +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:
+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.
+Download MGEN from the NRL MGEN Repo, unpack it and copy the +protolib library into the main folder mgen. Execute the following commands to build the protocol.
+cd mgen/makefiles
+make -f Makefile.{os} mgen
+Download NHDP from the NRL NHDP Repo.
+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
+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
+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.
+cd nhdp/unix
+make -f Makefile.{os}
+Download SMF from the NRL SMF Repo , unpack it and place the +protolib library inside the smf main folder.
+cd mgen/makefiles
+make -f Makefile.{os}
+To install the OLSR protocol, download their source code from +their NRL OLSR Repo. Unpack it and place the previously +downloaded protolib library inside the nrlolsr main directory. Then execute the following commands:
+cd ./unix
+make -f Makefile.{os}
+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. +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.
+sudo apt-get install quagga
+First, download the source code from their official webpage.
+sudo apt-get install gawk
+Extract the tarball, go to the directory of your currently extracted code and issue the following commands.
+./configure
+make
+sudo make install
+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.
+sudo apt-get install gcc python-dev libffi-dev libssl-dev libxml2-dev libxslt1-dev zlib1g-dev
+pip install ryu
+git clone git://github.com/osrg/ryu.git
+cd ryu
+pip install .
+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.
+Libraries needed for some security services.
+sudo apt-get install ipsec-tools racoon
+Below is a set of instruction for running a very simple OpenVPN client/server scenario.
+# install openvpn
+sudo apt install openvpn
+
+# retrieve easyrsa3 for key/cert generation
+git clone https://github.com/OpenVPN/easy-rsa
+# navigate into easyrsa3 repo subdirectory that contains built binary
+cd easy-rsa/easyrsa3
+
+# initalize pki
+./easyrsa init-pki
+
+# build ca
+./easyrsa build-ca
+
+# generate and sign server keypair(s)
+SERVER_NAME=server1
+./easyrsa get-req $SERVER_NAME nopass
+./easyrsa sign-req server $SERVER_NAME
+
+# generate and sign client keypair(s)
+CLIENT_NAME=client1
+./easyrsa get-req $CLIENT_NAME nopass
+./easyrsa sign-req client $CLIENT_NAME
+
+# DH generation
+./easyrsa gen-dh
+
+# create directory for keys for CORE to use
+# NOTE: the default is set to a directory that requires using sudo, but can be
+# anywhere and not require sudo at all
+KEYDIR=/etc/core/keys
+sudo mkdir $KEYDIR
+
+# move keys to directory
+sudo cp pki/ca.crt $KEYDIR
+sudo cp pki/issued/*.crt $KEYDIR
+sudo cp pki/private/*.key $KEYDIR
+sudo cp pki/dh.pem $KEYDIR/dh1024.pem
+Add VPNServer service to nodes desired for running an OpenVPN server.
+Modify sampleVPNServer for the +following
+Add VPNClient service to nodes desired for acting as an OpenVPN client.
+Modify sampleVPNClient for the +following
+Variety of convenience services for carrying out common networking changes.
+The following services are provided as utilities:
+To install the functionality of the previously metioned services you can run the following command:
+sudo apt-get install isc-dhcp-server apache2 libpcap-dev radvd at
+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.
+sudo apt-get install ucarp
+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'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 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.
+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.
+In order to be able to install the XORP Routing Suite, you must first install scons in order to compile it.
+sudo apt-get install scons
+Then, download XORP from its official release web page.
+http://www.xorp.org/releases/current/
+cd xorp
+sudo apt-get install libssl-dev ncurses-dev
+scons
+scons install
+You can also run the same steps above, using the provided gRPC script versions of scenarios. +Below are the steps to run and join one of these scenario, then you can continue with +the remaining steps of a given section.
+sudop core-daemon
+/opt/core/venv/bin/python scenario.py
+core-gui
+
+ 
+
These tutorials will cover various use cases within CORE. These +tutorials will provide example python, gRPC, XML, and related files, as well +as an explanation for their usage and purpose.
+These are the items you should become familiar with for running all the tutorials below.
+ +We assume the prior installation of CORE, using a virtual environment. You can +then adjust your PATH and add an alias to help more conveniently run CORE +commands.
+This can be setup in your .bashrc
+export PATH=$PATH:/opt/core/venv/bin
+alias sudop='sudo env PATH=$PATH'
+There is a simple TCP chat app provided as example software to use and run within +the tutorials provided.
+The following will install chatapp and its scripts into /usr/local, which you +may need to add to PATH within node to be able to use command directly.
+sudo python3 -m pip install .
+Note
+Some Linux distros will not have /usr/local in their PATH and you +will need to compensate.
+export PATH=$PATH:/usr/local
+The server will print and log connected clients and their messages.
+usage: chatapp-server [-h] [-a ADDRESS] [-p PORT]
+
+chat app server
+
+optional arguments:
+ -h, --help show this help message and exit
+ -a ADDRESS, --address ADDRESS
+ address to listen on (default: )
+ -p PORT, --port PORT port to listen on (default: 9001)
+The client will print and log messages from other clients and their join/leave status.
+usage: chatapp-client [-h] -a ADDRESS [-p PORT]
+
+chat app client
+
+optional arguments:
+ -h, --help show this help message and exit
+ -a ADDRESS, --address ADDRESS
+ address to listen on (default: None)
+ -p PORT, --port PORT port to listen on (default: 9001)
+custom_config_services_dir = <path for service>
+This tutorial will cover some use cases when using a wired 2 node +scenario in CORE.
+
+ 
+
Below is the list of files used for this tutorial.
+This section covers interactions that can be carried out for this scenario.
+Our scenario has the following nodes and addresses:
+All usages below assume a clean scenario start.
+Using the command line utility ping can be a good way to verify connectivity +between nodes in CORE.
+sudop core-daemon
+core-gui
+In the GUI menu bar select File->Open..., then navigate to and select scenario.xml
+
+
+ 
+
You can now click on the Start Session button to run the scenario
+
+
+
+
Open a terminal on n1 by double clicking it in the GUI
+ping -c 3 10.0.0.21
+PING 10.0.0.21 (10.0.0.21) 56(84) bytes of data.
+64 bytes from 10.0.0.21: icmp_seq=1 ttl=64 time=0.085 ms
+64 bytes from 10.0.0.21: icmp_seq=2 ttl=64 time=0.079 ms
+64 bytes from 10.0.0.21: icmp_seq=3 ttl=64 time=0.072 ms
+
+--- 10.0.0.21 ping statistics ---
+3 packets transmitted, 3 received, 0% packet loss, time 1999ms
+rtt min/avg/max/mdev = 0.072/0.078/0.085/0.011 ms
+Using tcpdump can be very beneficial for examining a network. You can verify +traffic being sent/received among many other uses.
+sudop core-daemon
+core-gui
+In the GUI menu bar select File->Open..., then navigate to and select scenario.xml
+
+
+
+
You can now click on the Start Session button to run the scenario
+
+
+
+
Open a terminal on n1 by double clicking it in the GUI
+tcpdump -lenni eth0
+ping -c 1 10.0.0.21
+tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
+listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
+10:23:04.685292 00:00:00:aa:00:00 > 00:00:00:aa:00:01, ethertype IPv4 (0x0800), length 98: 10.0.0.20 > 10.0.0.21: ICMP echo request, id 67, seq 1, length 64
+10:23:04.685329 00:00:00:aa:00:01 > 00:00:00:aa:00:00, ethertype IPv4 (0x0800), length 98: 10.0.0.21 > 10.0.0.20: ICMP echo reply, id 67, seq 1, length 64
+You can edit links between nodes in CORE to modify loss, delay, bandwidth, and more. This can be +beneficial for understanding how software will behave in adverse conditions.
+sudop core-daemon
+core-gui
+In the GUI menu bar select File->Open..., then navigate to and select scenario.xml
+
+
+
+
You can now click on the Start Session button to run the scenario
+
+
+
+
Right click the link between n1 and n2
+Select Configure
+
+
+ 
+
Update the loss to 25
+
+
+ 
+
Open a terminal on n1 by double clicking it in the GUI
+ping -c 10 10.0.0.21
+--- 10.0.0.21 ping statistics ---
+10 packets transmitted, 6 received, 40% packet loss, time 9000ms
+rtt min/avg/max/mdev = 0.077/0.093/0.108/0.016 ms
+We will now leverage the installed Chat App software to stand up a server and client +within the nodes of our scenario.
+sudop core-daemon
+core-gui
+In the GUI menu bar select File->Open..., then navigate to and select scenario.xml
+
+
+
+
You can now click on the Start Session button to run the scenario
+
+
+
+
Open a terminal on n1 by double clicking it in the GUI
+export PATH=$PATH:/usr/local/bin
+chatapp-server
+export PATH=$PATH:/usr/local/bin
+chatapp-client -a 10.0.0.20
+chat server listening on: :9001
+[server] 10.0.0.21:44362 joining
+hello world
+chat server listening on: :9001
+[server] 10.0.0.21:44362 joining
+[10.0.0.21:44362] hello world
+In this case we are using the service based scenario. This will automatically start
+and run the Chat App Server on n1 and log to a file. This case will demonstrate
+using tail -f to observe the output of running software.
sudop core-daemon
+core-gui
+In the GUI menu bar select File->Open..., then navigate to and select scenario_service.xml
+
+
+
+
You can now click on the Start Session button to run the scenario
+
+
+
+
Open a terminal on n1 by double clicking it in the GUI
+tail -f chatapp.log
+export PATH=$PATH:/usr/local/bin
+chatapp-client -a 10.0.0.20
+chat server listening on: :9001
+[server] 10.0.0.21:44362 joining
+hello world
+chat server listening on: :9001
+[server] 10.0.0.21:44362 joining
+[10.0.0.21:44362] hello world
+You can also run the same steps above, using the provided gRPC script versions of scenarios. +Below are the steps to run and join one of these scenario, then you can continue with +the remaining steps of a given section.
+sudop core-daemon
+/opt/core/venv/bin/python scenario.py
+core-gui
+
+
+
This tutorial will cover the use of a 3 node scenario in CORE. Then +running a chat server on one node and a chat client on the other. The client will +send a simple message and the server will log receipt of the message.
+Below is the list of files used for this tutorial.
+This section will cover running this sample tutorial using the +XML scenario file, leveraging an NS2 mobility file.
+sudop core-daemon
+core-gui
+You can now click play to start the session
+
+
+ 
+
Note that OSPF routing protocol is included in the scenario to provide routes to other nodes, as they are discovered
+ping -c 2 10.0.0.2
+PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.
+64 bytes from 10.0.0.2: icmp_seq=1 ttl=63 time=20.2 ms
+64 bytes from 10.0.0.2: icmp_seq=2 ttl=63 time=20.2 ms
+
+--- 10.0.0.2 ping statistics ---
+2 packets transmitted, 2 received, 0% packet loss, time 1000ms
+rtt min/avg/max/mdev = 20.168/20.173/20.178/0.005 ms
+Right click on the wlan1 node and select WLAN Config, then set delay to 500000
+
+
+ 
+
Using the open terminal for node n4, ping n2 again, expect about 2 seconds delay +
ping -c 5 10.0.0.2
+64 bytes from 10.0.0.2: icmp_seq=1 ttl=63 time=2001 ms
+64 bytes from 10.0.0.2: icmp_seq=2 ttl=63 time=2000 ms
+64 bytes from 10.0.0.2: icmp_seq=3 ttl=63 time=2000 ms
+64 bytes from 10.0.0.2: icmp_seq=4 ttl=63 time=2000 ms
+64 bytes from 10.0.0.2: icmp_seq=5 ttl=63 time=2000 ms
+
+--- 10.0.0.2 ping statistics ---
+5 packets transmitted, 5 received, 0% packet loss, time 4024ms
+rtt min/avg/max/mdev = 2000.176/2000.438/2001.166/0.376 ms, pipe 2
+Right click on the wlan1 node and select WLAN Config, set delay back to 5000 and loss to 10
+
+
+ 
+
Using the open terminal for node n4, ping n2 again, expect to notice considerable loss +
ping -c 10 10.0.0.2
+PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.
+64 bytes from 10.0.0.2: icmp_seq=1 ttl=63 time=20.4 ms
+64 bytes from 10.0.0.2: icmp_seq=2 ttl=63 time=20.5 ms
+64 bytes from 10.0.0.2: icmp_seq=3 ttl=63 time=20.2 ms
+64 bytes from 10.0.0.2: icmp_seq=4 ttl=63 time=20.8 ms
+64 bytes from 10.0.0.2: icmp_seq=5 ttl=63 time=21.9 ms
+64 bytes from 10.0.0.2: icmp_seq=8 ttl=63 time=22.7 ms
+64 bytes from 10.0.0.2: icmp_seq=9 ttl=63 time=22.4 ms
+64 bytes from 10.0.0.2: icmp_seq=10 ttl=63 time=20.3 ms
+
+--- 10.0.0.2 ping statistics ---
+10 packets transmitted, 8 received, 20% packet loss, time 9064ms
+rtt min/avg/max/mdev = 20.188/21.143/22.717/0.967 ms
+This section will cover running this sample tutorial using the +gRPC python script and providing mobility over the gRPC interface.
+sudop core-daemon
+core-gui
+/opt/core/venv/bin/python scenario.py
+
+
+
We will now leverage the installed Chat App software to stand up a server and client +within the nodes of our scenario. You can use the bases of the running scenario from +either scenario.xml or the scenario.py gRPC script.
+export PATH=$PATH:/usr/local/bin
+chatapp-server
+export PATH=$PATH:/usr/local/bin
+chatapp-client -a 10.0.0.4
+>>hello world
+chat server listening on: :9001
+[server] 10.0.0.2:53684 joining
+[10.0.0.2:53684] hello world
+This tutorial will cover using a 3 node scenario in CORE with basic mobility. +Mobility can be provided from a NS2 file or by including mobility commands in a gRPC script.
+Below is the list of files used for this tutorial.
+This section will cover running this sample tutorial using the XML scenario +file, leveraging an NS2 file for mobility.
+sudop core-daemon
+core-gui
+$node_(1) set X_ 208.1
+$node_(1) set Y_ 211.05
+$node_(1) set Z_ 0
+$ns_ at 0.0 "$node_(1) setdest 208.1 211.05 0.00"
+$node_(2) set X_ 393.1
+$node_(2) set Y_ 223.05
+$node_(2) set Z_ 0
+$ns_ at 0.0 "$node_(2) setdest 393.1 223.05 0.00"
+$node_(4) set X_ 499.1
+$node_(4) set Y_ 186.05
+$node_(4) set Z_ 0
+$ns_ at 0.0 "$node_(4) setdest 499.1 186.05 0.00"
+$ns_ at 1.0 "$node_(1) setdest 190.1 225.05 0.00"
+$ns_ at 1.0 "$node_(2) setdest 393.1 225.05 0.00"
+$ns_ at 1.0 "$node_(4) setdest 515.1 186.05 0.00"
+$ns_ at 2.0 "$node_(1) setdest 175.1 250.05 0.00"
+$ns_ at 2.0 "$node_(2) setdest 393.1 250.05 0.00"
+$ns_ at 2.0 "$node_(4) setdest 530.1 186.05 0.00"
+$ns_ at 3.0 "$node_(1) setdest 160.1 275.05 0.00"
+$ns_ at 3.0 "$node_(2) setdest 393.1 275.05 0.00"
+$ns_ at 3.0 "$node_(4) setdest 530.1 186.05 0.00"
+$ns_ at 4.0 "$node_(1) setdest 160.1 300.05 0.00"
+$ns_ at 4.0 "$node_(2) setdest 393.1 300.05 0.00"
+$ns_ at 4.0 "$node_(4) setdest 550.1 186.05 0.00"
+$ns_ at 5.0 "$node_(1) setdest 160.1 275.05 0.00"
+$ns_ at 5.0 "$node_(2) setdest 393.1 275.05 0.00"
+$ns_ at 5.0 "$node_(4) setdest 530.1 186.05 0.00"
+$ns_ at 6.0 "$node_(1) setdest 175.1 250.05 0.00"
+$ns_ at 6.0 "$node_(2) setdest 393.1 250.05 0.00"
+$ns_ at 6.0 "$node_(4) setdest 515.1 186.05 0.00"
+$ns_ at 7.0 "$node_(1) setdest 190.1 225.05 0.00"
+$ns_ at 7.0 "$node_(2) setdest 393.1 225.05 0.00"
+$ns_ at 7.0 "$node_(4) setdest 499.1 186.05 0.00"
+
+ 
+
This section covers using a gRPC script to create and provide scenario movement.
+sudop core-daemon
+/opt/core/venv/bin/python scenario.py
+core-gui
+In the terminal running the scenario.py, hit a key to start motion
+
+
+ 
+
Observe the link between n3 and n4 is shown and then as motion continues the link breaks
+
+
+ 
+
This section covers using one of the above 2 scenarios to run software within +the nodes.
+export PATH=$PATH:/usr/local/bin
+chatapp-server
+export PATH=$PATH:/usr/local/bin
+chatapp-client -a 10.0.0.4
+>>hello world
+chat server listening on: :9001
+[server] 10.0.0.2:53684 joining
+[10.0.0.2:53684] hello world
+This section provides an example for running a script within a node, that +leverages a control network in CORE for issuing mobility using the gRPC +API.
+grpcaddress = 0.0.0.0
+/opt/core/venv/bin/python move-node2.py
+
+ 
+
A use case for CORE would be to help automate integration tests for running +software within a network. This tutorial covers using CORE with the python +pytest testing framework. It will show how you can define tests, for different +use cases to validate software and outcomes within a defined network. Using +pytest, you would create tests using all the standard pytest functionality. +Creating a test file, and then defining test functions to run. For these tests, +we are leveraging the CORE library directly and the API it provides.
+Refer to the pytest documentation for indepth +information on how to write tests with pytest.
+A directory is used for containing your tests. Within this directory we need a +conftest.py, which pytest will pick up to help define and provide +test fixtures, which will be leveraged within our tests.
+Below are the definitions for fixture you can define to facilitate and make +creating CORE based tests easier.
+The global session fixture creates one CoreEmu object for the entire +test session, yields it for testing, and calls shutdown when everything +is over.
+@pytest.fixture(scope="session")
+def global_session():
+ core = CoreEmu()
+ session = core.create_session()
+ session.set_state(EventTypes.CONFIGURATION_STATE)
+ yield session
+ core.shutdown()
+The regular session fixture leverages the global session fixture. It +will set the correct state for each test case, yield the session for a test, +and then clear the session after a test finishes to prepare for the next +test.
+@pytest.fixture
+def session(global_session):
+ global_session.set_state(EventTypes.CONFIGURATION_STATE)
+ yield global_session
+ global_session.clear()
+The ip prefixes fixture help provide a preconfigured convenience for +creating and assigning interfaces to nodes, when creating your network +within a test. The address subnet can be whatever you desire.
+@pytest.fixture(scope="session")
+def ip_prefixes():
+ return IpPrefixes(ip4_prefix="10.0.0.0/24")
+Within a pytest test file, you have the freedom to create any kind of +test you like, but they will all follow a similar formula.
+In the test below, we create a simple 2 node wired network and validate +node1 can ping node2 successfully.
+def test_success(self, session: Session, ip_prefixes: IpPrefixes):
+ # create nodes
+ node1 = session.add_node(CoreNode)
+ node2 = session.add_node(CoreNode)
+
+ # link nodes together
+ iface1_data = ip_prefixes.create_iface(node1)
+ iface2_data = ip_prefixes.create_iface(node2)
+ session.add_link(node1.id, node2.id, iface1_data, iface2_data)
+
+ # ping node, expect a successful command
+ node1.cmd(f"ping -c 1 {iface2_data.ip4}")
+Since we are running an automated test within CORE, we will need to install +pytest within the python interpreter used by CORE.
+sudo /opt/core/venv/bin/python -m pip install pytest
+You can run your own or the provided tests, by running the following.
+cd <test directory>
+sudo /opt/core/venv/bin/python -m pytest -v
+If you run the provided tests, you would expect to see the two tests +running and passing.
+tests/test_ping.py::TestPing::test_success PASSED [ 50%]
+tests/test_ping.py::TestPing::test_failure PASSED [100%]
+This tutorial will cover connecting CORE VM to a Windows host machine using a RJ45 node.
+Below is the list of files used for this tutorial.
+This section covers using the saved scenario.xml file to get and up and running.
+Configure the Windows host VM to have a bridged network adapter
+
+
+ 
+
Make sure the core-daemon is running in a terminal +
sudop core-daemon
+core-gui
+Open the scenario.xml with the unassigned RJ45 node
+
+
+ 
+
Configure the RJ45 node name to use the bridged interface
+
+
+ 
+
After configuring the RJ45, run the scenario:
+
+
+ 
+
Double click node n1 to open a terminal and add a route to the Windows host +
ip route add 192.168.0.0/24 via 10.0.0.20
+# if enp0s3 is ssigned 192.168.0.6/24
+route add 10.0.0.0 mask 255.255.255.0 192.168.0.6
+C:\WINDOWS\system32>ping 10.0.0.20
+
+Pinging 10.0.0.20 with 32 bytes of data:
+Reply from 10.0.0.20: bytes=32 time<1ms TTL=64
+Reply from 10.0.0.20: bytes=32 time<1ms TTL=64
+Reply from 10.0.0.20: bytes=32 time<1ms TTL=64
+Reply from 10.0.0.20: bytes=32 time<1ms TTL=64
+
+Ping statistics for 10.0.0.20:
+ Packets: Sent = 4, Received = 4, Lost = 0 (0% loss)
+Approximate round trip times in milli-seconds:
+ Minimum = 0ms, Maximum = 0ms, Average = 0ms
+export PATH=$PATH:/usr/local/bin
+chatapp-server
+python3 client_for_windows.py -a 10.0.0.20
+connected to server(10.0.0.20:9001) as client(192.168.0.6:49960)
+>> .Hello WORLD
+.Hello WORLD Again
+.
+chat server listening on: :9001
+[server] 192.168.0.6:49960 joining
+[192.168.0.6:49960] Hello WORLD
+[192.168.0.6:49960] Hello WORLD Again
+route delete 10.0.0.0
+This section covers leveraging the gRPC script to get up and running.
+Configure the Windows host VM to have a bridged network adapter
+
+
+
+
Make sure the core-daemon is running in a terminal +
sudop core-daemon
+core-gui
+# use the desired interface name, in this case enp0s3
+/opt/core/venv/bin/python scenario.py enp0s3
+In the core-gui connect to the running session that was created
+
+
+
+
Double click node n1 to open a terminal and add a route to the Windows host +
ip route add 192.168.0.0/24 via 10.0.0.20
+# if enp0s3 is ssigned 192.168.0.6/24
+route add 10.0.0.0 mask 255.255.255.0 192.168.0.6
+C:\WINDOWS\system32>ping 10.0.0.20
+
+Pinging 10.0.0.20 with 32 bytes of data:
+Reply from 10.0.0.20: bytes=32 time<1ms TTL=64
+Reply from 10.0.0.20: bytes=32 time<1ms TTL=64
+Reply from 10.0.0.20: bytes=32 time<1ms TTL=64
+Reply from 10.0.0.20: bytes=32 time<1ms TTL=64
+
+Ping statistics for 10.0.0.20:
+ Packets: Sent = 4, Received = 4, Lost = 0 (0% loss)
+Approximate round trip times in milli-seconds:
+ Minimum = 0ms, Maximum = 0ms, Average = 0ms
+export PATH=$PATH:/usr/local/bin
+chatapp-server
+python3 client_for_windows.py -a 10.0.0.20
+connected to server(10.0.0.20:9001) as client(192.168.0.6:49960)
+>> .Hello WORLD
+.Hello WORLD Again
+.
+chat server listening on: :9001
+[server] 192.168.0.6:49960 joining
+[192.168.0.6:49960] Hello WORLD
+[192.168.0.6:49960] Hello WORLD Again
+route delete 10.0.0.0
+This tutorial will cover changing the node icons, changing the background, and changing or hiding links.
+Below is the list of files used for this tutorial.
+This section will cover running this sample tutorial that develops a scenario file.
+sudop core-daemon
+core-gui
+Create three MDR nodes
+
+
+ 
+
Double click on each node for configuration, click the icon and set it to use the drone.png image
+
+
+ 
+
Use Session -> Options and set Control Network 0 to 172.16.0.0./24
+Link the three prior MDR nodes to the WLAN node
+
+
+ 
+
Click play to start the scenario
+Observe wireless links being created
+
+
+ 
+
Click stop to end the scenario
+
+ 
+
Click Canvas -> Wallpaper to set the background to terrain.png
+
+
+ 
+
Click play to start the scenario again
+
+ 
+
# node id is first parameter, second is total nodes
+/opt/core/venv/bin/python demo.py 1 3
+Let it run to see the link break as the node 1 drone approches the right side
+
+
+ 
+
Repeat for other nodes, double click on n2 and n3 and run the demo.py script +
# n2
+/opt/core/venv/bin/python demo.py 2 3
+# n3
+/opt/core/venv/bin/python demo.py 3 3
+
+ 
+
This tutorial will cover basic usage and some concepts one may want to +use or leverage when working with and creating EMANE based networks.
+
+ 
+
For more detailed information on EMANE see the following:
+ +Below is a list of the files used for this tutorial.
+This section covers interactions that can be carried out for this scenario.
+Our scenario has the following nodes and addresses:
+All usages below assume a clean scenario start.
+Using the command line utility ping can be a good way to verify connectivity +between nodes in CORE.
+sudop core-daemon
+core-gui
+In the GUI menu bar select File->Open..., then navigate to and select scenario.xml
+
+
+
+
You can now click on the Start Session button to run the scenario
+
+
+
+
Open a terminal on n2 by double clicking it in the GUI
+ping -c 3 10.0.0.2
+PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data.
+64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=7.93 ms
+64 bytes from 10.0.0.2: icmp_seq=2 ttl=64 time=3.07 ms
+64 bytes from 10.0.0.2: icmp_seq=3 ttl=64 time=3.05 ms
+
+--- 10.0.0.2 ping statistics ---
+3 packets transmitted, 3 received, 0% packet loss, time 2000ms
+rtt min/avg/max/mdev = 3.049/4.685/7.932/2.295 ms
+Using tcpdump can be very beneficial for examining a network. You can verify +traffic being sent/received among many other uses.
+sudop core-daemon
+core-gui
+In the GUI menu bar select File->Open..., then navigate to and select scenario.xml
+
+
+
+
You can now click on the Start Session button to run the scenario
+
+
+
+
Open a terminal on n2 by double clicking it in the GUI
+tcpdump -lenni eth0
+ping -c 1 10.0.0.2
+tcpdump: verbose output suppressed, use -v[v]... for full protocol decode
+listening on eth0, link-type EN10MB (Ethernet), snapshot length 262144 bytes
+14:56:25.414283 02:02:00:00:00:01 > 02:02:00:00:00:02, ethertype IPv4 (0x0800), length 98: 10.0.0.1 > 10.0.0.2: ICMP echo request, id 64832, seq 1, length 64
+14:56:25.414303 02:02:00:00:00:02 > 02:02:00:00:00:01, ethertype IPv4 (0x0800), length 98: 10.0.0.2 > 10.0.0.1: ICMP echo reply, id 64832, seq 1, length 64
+We will now leverage the installed Chat App software to stand up a server and client +within the nodes of our scenario.
+sudop core-daemon
+core-gui
+In the GUI menu bar select File->Open..., then navigate to and select scenario.xml
+
+
+
+
You can now click on the Start Session button to run the scenario
+
+
+
+
Open a terminal on n2 by double clicking it in the GUI
+export PATH=$PATH:/usr/local/bin
+chatapp-server
+export PATH=$PATH:/usr/local/bin
+chatapp-client -a 10.0.0.1
+chat server listening on: :9001
+[server] 10.0.0.1:44362 joining
+hello world
+chat server listening on: :9001
+[server] 10.0.0.2:44362 joining
+[10.0.0.2:44362] hello world
+In this case we are using the service based scenario. This will automatically start
+and run the Chat App Server on n2 and log to a file. This case will demonstrate
+using tail -f to observe the output of running software.
sudop core-daemon
+core-gui
+In the GUI menu bar select File->Open..., then navigate to and select scenario_service.xml
+
+
+
+
You can now click on the Start Session button to run the scenario
+
+
+
+
Open a terminal on n2 by double clicking it in the GUI
+tail -f chatapp.log
+export PATH=$PATH:/usr/local/bin
+chatapp-client -a 10.0.0.1
+chat server listening on: :9001
+[server] 10.0.0.2:44362 joining
+hello world
+chat server listening on: :9001
+[server] 10.0.0.2:44362 joining
+[10.0.0.2:44362] hello world
+This section will cover some high level topics and examples for running and +using EMANE in CORE. You can find more detailed tutorials and examples at +the EMANE Tutorial.
+Note
+Every topic below assumes CORE, EMANE, and OSPF MDR have been installed.
+Scenario files to support the EMANE topics below will be found in +the GUI default directory for opening XML files.
+| Topic | +Model | +Description | +
|---|---|---|
| XML Files | +RF Pipe | +Overview of generated XML files used to drive EMANE | +
| GPSD | +RF Pipe | +Overview of running and integrating gpsd with EMANE | +
| Precomputed | +RF Pipe | +Overview of using the precomputed propagation model | +
| EEL | +RF Pipe | +Overview of using the Emulation Event Log (EEL) Generator | +
| Antenna Profiles | +RF Pipe | +Overview of using antenna profiles in EMANE | +
You can also run the same steps above, using the provided gRPC script versions of scenarios. +Below are the steps to run and join one of these scenario, then you can continue with +the remaining steps of a given section.
+sudop core-daemon
+/opt/core/venv/bin/python scenario.py
+core-gui
+
+
+