Skip to content

GNS3 Simulation

Jump to bottom
Jack Wampler edited this page Oct 25, 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

VM Environments

While GNS3 does support Virtualbox, this is as of yet, untested and the current simulation instructions use VMware Workstation.

Note: It is suggested to use the GNS3 VM to run network topologies, 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

Heading

  1. A numbered
  2. list
    • With some
    • Sub bullets
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

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

Conjure Tap Topology

Simple Simulation Topology

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

Environment Prep

Linking Docker images

Changes will NOT persist whenever the appliance is rebooted

Linking Local Virtual Machines

Unlike linked Docker images, changes will persist across appliance reboots.

Instantiating and configuring linked appliances

Connecting to the internet

Building a Tap using an Ethernet Hub

Configuring Network Connections

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 configured 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.

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. Enable SSH to the GNS3 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
Clone this wiki locally