Labs

Creating a Lab

To turn the current directory into a Koble lab:

koble lab init

or to create a new directory for the lab:

koble lab init --name newlab

To see more options, check out the manpage.

lab.yml

The lab config is stored in lab.yml, in the root of the lab directory.

An example config could be:

lab.yml
authors:
- John Doe
created_at: 15-12-2021
driver:
  name: uml
koble_version: 0.0.1
machines:
  a:
    networks:
    - ar

  • created_at - date in the format DD-MM-YYYY

  • koble_version - version of Koble that the lab was created with

  • description - a short description of the lab

  • authors - a list of lab authors

  • emails - a list of lab authors' email addresses

  • web - a list of URIs associated with the lab (e.g. git repo / documentation page)

  • machines - a map of lab machines. All machines in the lab must be declared in lab.yml.

  • networks - a map of lab networks. If a network is attached to a machine but does not have an entry in networks it will be a simple network with no external access, no set subnet / gateway etc.

lab.yml example machine
machines:
  m1:
    networks:
    - ext
    hosthome: false
    hostlab: true
    depends_on:
    - m2

  • networks - a list of network names to join machine to.

  • hosthome - whether to mount $HOME on the host to /hosthome in the virtual machine.

  • hostlab - whether to mount the lab directory on the host to /hostlab in the virtual machine. If this is false then startup scripts and machine directories won’t be available inside the VM.

  • depends_on - machines that need to finish booting before this machine starts.

lab.yml example network
networks:
  ext:
    external: true
    gateway: 10.16.55.254
    subnet: 10.16.55.0/24

  • external - whether this machine should have external network access. If the host machine has internet access then setting external to true will give the VM internet access.

  • gateway - the gateway address to use for the network

  • subnet the subnet to use for the network

Adding Machines

To add a machine to a lab:

koble machine add newmachine --network firstnet --network another

This will add an entry to the machines in lab.yml, create a folder for the machine contents and create a machine startup file.

Adding Networks

To add a network to a lab:

koble net add firstnet

Lab Commands

You can perform some of the commands that can be used for single machines against a whole lab. These include:

  • start

  • stop

  • remove

  • destroy

For example in a lab with machines a and b:

koble lab stop

Is equivalent to doing

koble stop a
koble stop b

Advanced Configuration

lab.yml
driver:
  name: uml

Additional configuration in lab.yml can be used to override global Koble settings. For example we can use the driver option to override the driver used for the lab.

You should only run trusted labs where you have read the code and configuration. Arbitrary code can be run using some of the overrides, such as a lab adding an additional terminal with a reverse shell in the command 😎