Skip to content

GNS3 Simulation

Jump to bottom
Jack Wampler edited this page Oct 26, 2021 · 16 revisions

GNS3 logo

Simulating Conjure in GNS3

GNS3 provides a convenient network simulation platform for testing and developing the Conjure refraction networking system. This page will walk through the setup of GNS3 (and some sharp corners to avoid) as well as the setup of the conjure system.

Note: This is just one way to set up the environment - there are likely other - potentially better - ways to accomplish the same goal. This document is a work in progress. Make a PR if you find an improvement to the setup or workflow involving the GNS3 simulation environment.

GNS3 Overview & installation

The first steps involve getting GNS3 and an emulation platform installed and configured to recognize each other and work together. This page includes some specific suggestions and fixes for problems that encountered along the way.

Rough Steps (Refer to the GNS3 installation guide for comprehensive steps):

  • Install PPA
  • Install GNS3 packages
  • Install Virtualization platform (VMware or virtualbox).
  • Install GNS3 VM and link to GUI using the setup wizard.
  • ssh into GNS3 VM and install Docker.
  • Create/Import VMs/Docker images to be brought into a network.

VM Environments

While GNS3 does support Virtualbox, we have not yet tested gns3 w/ virtualbox. So the current simulation instructions use VMware Workstation. Adapting to virtualbox should be translatably similar.

Note: It is suggested to use the GNS3 VM to run network topologies instead of the local server, however this must be the same version as your local client (major, minor, and patch) - i.e GNS3 VM v2.2.25 will not work with GNS3 client v2.2.26. See the GNS3 page about upgrading the VM if you run into this issue.

VMware sharp edges

Installing VMWare kernel modules w/ secure boot

In some environments vmware-player will complain that the /dev/vmmon and/or /dev/vmnet kernel modules cannot be found. This happens when secure boot is enabled as linux secure boot doesn't allow for unsigned kernel modules. The links below provide steps to sign VMware drivers on Linux host with secure boot enabled, so that VMware Workstation can run VMs successfully.

Enable Promiscuous capture for VMware interfaces.

By default, VMware is configured such that a guest operating system's virtual network adapter only receives frames that are meant for it. This prevents VMs attached in bridge mode from snooping on host or other machine traffic.

However, in order to run a conjure station we require an interface capable of listening in promiscuous mode in order to ingest all tap traffic. To fix this promiscuous mode must be enabled for the virtual network adapter that the tap VM connects to. See this VMware help article for directions.

VMware Player doesn't support VMware VIX Currently VMware Player, VMware VIX, and ubuntu 20.04 don't play well together. This error will occur when attempting to link VMware in the GNS3 gui with a complaint about a missing vmrun or vmnet binary.

This is a known issue which is unsolved (as of last edit). The easiest solution is to install VMware Workstation which bundles VIX properly (instead of relying on independent install).

We are now ready to run a small example GNS3 setup like "Your First GNS3 Topology".

Create / Import VMs / Docker images for topology

Clients and servers run in appliances that GNS3 connects with network backbone.

Linking Local Virtual Machines

GNS3 allows local Virtual Machines to be linked from VMware, virtualbox, and qemu. These VMs are controlled by GNS3 through exposed APIs (e.g. VIX for VMware) and can be linked in Edit-> Preferences->VMware->VMware VMs by clicking New. See the GNS3 GNS3 wiki page for the full walkthrough.

Unlike linked Docker images, changes will persist across appliance reboots. A local VM like this is ideal for our station as we can configure network interfaces (and drivers) in the GNS3 interface and build / configure the station to persistently come up on boot.

Linking Docker images

GNS3 supports docker emulation as an option for running hosts. Docker appliances can be build locally or pulled from a remote repository. To add a docker container as a valid appliance go to Edit->Preferences->Docker->Docker containers and click on New. See the GNS3 wiki page for more details.

This is useful for running simple prepackaged services like servers, clients, etc.

In order to run Docker containers in the GNS3 vm you will need to

  1. ssh to the GNS3 VM - on launch the GNS3 vm presents configuration information to ssh to the VM.
  2. Use the Shell option to install docker.
  3. (optional) Add an ssh public-key to ~/.ssh/authorized_hosts for easier login going forward.

Note: Changes will NOT persist when a docker appliance is rebooted, unless stored in a mounted volume.

Connecting to the internet

When a NAT appliance is included in a GNS3 topology hosts can rely on DHCP or static addressing configured in the gui to acquire address and connect to the internet. Many appliances expose this configuration right-click -> edit config. From here the appliance should be connected once started as the NAT appliance is connected as a bridge interface (or however you configure it) to the host.

GNS3 edit config

Conjure Tap Topology

Configure the GNS3 Network topology as follows for a simple tap configuration (that doesn't require any knowledge of Cisco IOS).

Simple GNS3 Topology

Rough steps:

  • Link an Ubuntu 20.04 VM for the station.
  • Add an extra interface to the station VM with e1000e driver.
  • Instantiate simple topology with two switches, a hub, and a NAT connection.
  • Connect hub to e1000e station VM interface.
  • Configure all non-tap interfaces to acquire addresses with DHCP.
  • Install docker on station VM and follow Docker station install directions.

Simple GNS3 Topology

Network

Our network topology consists of an extremely simple linear configuration. NAT, Hub, and Switch appliances should be included in the GNS3 client by default. No appliance extensions need to be configured in order to build this topology.

{NAT} ---- {Switch1} ---- [Hub] ---- {Switch2}

The Hub broadcasts all packets over any connected interfaces. In this way we can use it as a duplex network tap by connecting our station and simply listening for broadcast packets routing between Switch1 and Switch2.

Station

The base for our Conjure station will be an Ubuntu 20.04 server running in the Virtualization platform.

  1. Download an ubuntu iso image.

  2. Add a new VM to VMware using the image.

  3. Add the VM as an appliance in GNS3 in Edit-> Preferences->VMware->VMware VMs.

    • Click New -> Run this VM on my local computer -> Select VM -> Finish

  4. Configure Network for VM

    • Go to Edit-> Preferences->VMware->VMware VMs and select the Station VM
    • Click Edit then select the Network tab.
    • Update to 2 adapters and select e1000e as type (gns3 will configure the interface driver for the VM).
    • Check the box allowing GNS3 to override non custom adapters
    • Save and apply the changes

Station VM adapter config

  1. Connect one interface to a switch and the other to the hub
  2. Configure the interface connected to the switch to acquire an address using DHCP. See Above.

Client

The client can be run in a docker environment or a separate linked VM, essentially all that is required is golang. The client appliance(s) should be connected to Switch2 and configured to acquire an address (i.e. using DHCP).

A dockerfile has been added to gotapdance/cli to build a docker appliance for running the gotapdance cli. This can be installed as a GNS3 appliance by following the GNS3 wiki page for linking local docker images. At a high level:

  1. ssh into GNS3 VM
  2. Pull gotapdance repo
  3. Build docker image locally from the gotapdance repository root docker build -t gotapdance/cli -f cli/cli.dockerfile .
  4. Link to GNS3 gui in Edit->Preferences->Docker Containers by adding using New -> Existing
  5. Default configuration options should be fine.
  6. Instantiate the container, connect to a switch, use right-click -> edit config to enable DHCP.
  7. Run and connect to the container to open a shell for building and running the cli.

(Optional) Extra GNS3 topology experiments

This is minimal working example - there are lots of resources for practicing with GNS3. Below are a few demos to get started on more complex environments.

Configuration

Once the network topology is properly connected and the station is built and ingesting packets we can turn to the conjure system to ensure that proxy connections will be picked up by the station.

Rough steps:

  • Ensure network interfaces are configured.
  • Generate conjure keypair and create ClientConf.
  • Share ClienConf to client appliance(s).
  • Test end-to-end connection while watching logs.

Workflow

Station

The station runs on the Ubuntu_20.04_server image in a docker container. The development workflow for station development will typically consist of software updates, followed by a docker build and docker-compose up. To use local changes in the docker build (rather than pulling committed changes) the docker-compose file should be modified to include CUSTOM_BUILD: "1" in the environment args for ALL services.

    service_name:
      ...
      build:
        args:
          CUSTOM_BUILD: "1"

Client

Client testing in this environment should typically consist of building the refraction golang CLI and running either one-off test connections or a socks connection.

This can be done in any environment that supports golang - docker environments such as the alpine linux, ubuntu linux, or golang image make for effective minimal environments. However, it is important to note that unless a shared directory is mapped in, no data is persisted in these images between runs (i.e. image reboots).

Enable SSH to GNS3 appliances

For GNS3 appliances that support ssh (i.e. the ubuntu 20.04 VM that runs the station) the GNS3 VM manages all network connections and packet transfer. Because of this the GNS3 VM can be used as a proxy jump to ssh to any of the appliances in your GNS3 topology.

  1. SSH to the GNS3 VM - on launch the GNS3 vm presents configuration information to ssh to the VM.

  2. Ensure sshd is running on the guest appliance

  3. Determine login credentials for the guest appliance by either:

    i. Ensuring password login is enabled

    ii. Copying a public key in to the guest appliance's .ssh/authorized_hosts file

  4. ssh to the guest appliance using a proxyjump

  5. Add an entry to .ssh/config

    Host gns3
   HostName=192.168.112.128
   User=gns3
   Port=22
   IdentityFile=~/.ssh/id_local_ed25519

Host station1 s1
   HostName=192.168.122.210
   User=ubuntu
   Port=22
   IdentityFile=~/.ssh/id_local_ed25519
   ProxyJump=gns3

Full Environment [WIP]

Simple Simulation Topology

Future Directions

To make this environment easier to use / distribute / work with some future changes that would be nice are:

  • (Pre-configured) Station VM in QEMU for portability
  • GNS3 project export / import
  • Purpose build Docker images for simulation
  • Mapped / Mounted volumes directly from host for easy development -> deployment.
  • Documentation for deploying Tapdance alonside Conjure in the station VM
Clone this wiki locally