Environments

In FlowEmu, an environment is the configuration for how the emulator is started and connected to the outside world. Environments are configured in the config/environments directory. Here, each subdirectory specifies an environment using the following files:

• config.toml is the main configuration file for the environment in TOML format.
• build.sh is a script that builds FlowEmu for the environment from the current source tree.
• setup.sh is a script that sets up the environment by starting containers and configuring network interfaces.
• cleanup.sh is a script that cleans up the environment by reverting the changes done during setup.

The included environments also contain a config.sh file that sets environment variables and is sourced in every script.

config.toml

An example of a config.toml file is shown below:

[metadata]
name = "Docker"
description = "Docker environment"

[operating_modes]
testcase = true
interactive = true

[config]
mqtt.host = "172.17.0.1"

interface.source = "in"
interface.sink = "out"

docker_container.source = "source"
docker_container.channel = "channel"
docker_container.sink = "sink"

#run_prefix.control = ""
#run_prefix.source = ""
#run_prefix.channel = ""
#run_prefix.sink = ""

The [metadata] section contains general human-readable information about the environment, such as its name and a description.

The [operating_modes] section defines for which operating modes the environment can be used. The testcase operating mode means that the environment can be used for running automated experiments. The interactive operating mode means that the environment can be used interactively via the graphical user interface.

The [config] section defines general options for FlowEmu and the run script. mqtt.host defines the host where the MQTT broker is running on from the perspective of the emulator. As in this example, the emulator is executed inside a Docker container and the MQTT broker is executed on the host, the address of the host in the default Docker network is used. The parameters interface.source and interface.sink set the names of the network interfaces from the perspective of the emulator. docker_container.source, docker_container.channel and docker_container.sink specify the names of the Docker containers used for the emulator itself (channel) and the program under test (source & sink). Via the run_prefix.control, run_prefix.source, run_prefix.channel and run_prefix.sink parameters, a command-line prefix can be set that is used when starting the respective component.

Included Environments

FlowEmu comes with two different types of environments:

Docker Environment

In the Docker environment, FlowEmu is executed inside a Docker container (channel). The environment also starts a source and a sink container that are connected to the channel container via bridge network interfaces. These interfaces are accessible via the raw socket modules in FlowEmu. The source interface is connected to the left-hand side raw socket module (with the ports on the right-hand side), while the sink interface is connected to the right-hand side raw socket module (with the ports on the left-hand side).

The bridge network interface in the source container has the IPv4 address 10.0.1.1, while the interface in the sink container has the address 10.0.2.1.

When the environment is started, a command can be executed in the source/sink container from the host using the following commands:

docker exec -it source COMMAND
docker exec -it sink COMMAND

By default, the source and sink containers use the FlowEmu Docker image, which comes with some tools like ping and iperf. However, for more complex use cases, another Docker image should be used. Therefore, the Docker image that is used for the source and sink container can be changed in the config.sh file of the Docker environment.

Bridge Environment

In the bridge environment, FlowEmu is also executed inside a Docker container (channel). However, the bridge environment does not start containers for the program under test. Instead, it maps two network interfaces of the host inside the channel container. These interfaces are accessible via the raw socket modules in FlowEmu. The source interface is accessible via the left-hand side raw socket module (with the ports on the right-hand side), while the sink interface is accessible via the right-hand side raw socket module (with the ports on the left-hand side).

The bridge environment can only be used interactively via the graphical user interface and does not support running automated experiments.

To use the bridge environment, the names of the source and sink network interfaces have to be specified in the environment configuration. There are two places where these names have to be set, in the config.toml and in the config.sh. To find out the names of the network interfaces on your machine, you can use ip addr or ifconfig. Please be aware that the interfaces cannot be used by the system as long as the emulator is running.