Advanced Topics

This section covers rare use cases and aspects related to internal implementation.

Running from the source

The source code is publicly available at github.com/zmumi/netlab-dockerized. The recommended approach to running the checkout-ed project is to use Docker Compose as there is prepared docker-compose.yml. This will result in GUI container image built automatically upon docker-compose up. The created image will be named netlabdockerized_web (if you checkouted the project without specifying destination directory). The GUI webpage will be available at localhost:8000.

Alternative to using Docker Compose involves manual build of the image. Use docker build to construct the image (see Docker CLI reference for details). Use the returned Image ID (it is mentioned in the output of build command) with docker run <ID> command. Alternatively you may assign the name of the image with the build command. If you are using this approach remember about including --privileged -v /var/run/docker.sock:/var/run/docker.sock in your command - otherwise you will not be able to run the environment through the GUI.

Another approach to running the project is to start the GUI webapp directly on your OS. Simply run python manage.py runserver but have in mind, that you have to have Docker Compose (version 1.9.6) installed. In the regular scenario GUI containers provides it for you (and guarantees version compatibility) - now you have to provide it by yourself.

Docker in Docker

Docker in Docker powers the project as it enables managing the environment through dockerized GUI. The --privileged flag in the requirement of this technology - see hub.docker.com/_/docker/ for an excellent explanation. As we prefer launching sibling containers, mounting the Docker socket (-v /var/run/docker.sock:/var/run/docker.sock) is also required. The explanation can be found at the DockerHub page as well. The DockerHub page also mentions a great reference to the article by jpetazzo which provides an insight on Docker in Docker an sibling container approach. Long story short, it:

• saves your space, time and bandwidth as router and client images are stored at your host (not at the container which is short-lived)
• allows easier management as you can attach to the router and client containers directly form your OS

If you do not want to run the GUI container with -privileged you can omit this (and socket mounting as well). The GUI will run and it will provide you with project files but you will not be able to run the environment through the webapp. Yet you can still run the project manually, so this may be a solution for -privileged being a no go.

Adjusting the client image

Sometimes you do the same adjustments over and over again. If you want add something to the initial client configuration, you may want to alter the client image. To do this download the project (see the User Guide) and edit the Dockerfile from the project. For example to preinstall the traceroute program, add RUN apt-get install traceroute to the Dockerfile. The you may have to run docker-compose build (in your project) - this will apply your changes. Further reading on Dockerfile can be found at Docker Docs.

Project generation

The project files used to run the environment are generated through templating procedure. The following figure presents the flow of the generation.

Each generated file has own responsibilities:

• design.json
  • is an intermediate representation of the project
  • it is a complete representation of how the environment looks like
  • can be downloaded/uploaded to save and restore your work
• docker-compose.yml
  • describes what containers are part of the environment
  • describes what networks (lan segments) are part of the environment
  • reserves IP addresses in the networks
  • partially configures the containers (adds the network interfaces, sets memory limits, etc.)
  • is used by up.sh to start the environment
• config.boot
  • router configuration file
  • is used in router interface configuration
  • partially configures the router containers (for instance enables SSH)
• Dockerfile
  • used to create client container image
  • partially configures the client containers (for instance enables SSH)
• up.sh
  • starts the environment (using Docker Compose)
  • injects router configuration (by editing config files after the router is ran)
  • injects client configuration (for instance by setting the IP address and gateway)

All the files form the project which you can download and run manually. This approach might be of use if you want to alter some configuration manually.

Modifying the templates

If you happen to repeatedly download and adjust the project files you may find altering the templates useful. If you are running the project from the sources you can find the templates under /templates/generation/. The templates are named after output files. If you struggle to make your changes work you may want to see generation source file under configurator/logic/generation.py.

Changing container memory limit

To change container memory limits edit mem_limit in the /templates/generation/docker-compose.yml. Once you rebuild GUI image all your generated projects will have changed memory limits. This applies to environments ran from webapp as well

Something does not work

First of all you need to increase sleep periods in template (/templates/generation/up.sh) or in downloaded project (/out/up.sh). On some slower machines the default sleeps may be not sufficient. The sleeps are there as we cannot check when VyOS router finished initialization.

Project running

When the project is run, several steps are taken. The following figure presents what happens upon user 'run' or 'stop' requests.

If you download the project you obtain exactly the same up.sh and the interactions presented above still apply.