Creating student VMs

This repository provides a template for creating student VMs for GNS3 courses using Packer and Openstack. The template includes a base Ubuntu image with pre-installed GNS3 server and necessary configurations, as well as scripts to create multiple VMs with user-specific access rights.

Forking

This repository should be forked and customized for each specific course. In order to pull updates from this original repository, the following sequence of commands can be used. This will ensure that local changes in the forked repository are prioritized.

Add the upstream repository once:
- If using HTTPS: git remote add upstream https://git.ntnu.no/ie-iik/gns3-labs-course-template.git
- If using SSH: git remote add upstream git@git.ntnu.no:ie-iik/gns3-labs-course-template.git

Run the following commands for every update:

git fetch upstream
git merge --no-commit -X ours upstream/main || true

# If no conflict, only run this:
git commit -m "chore: Merge upstream/main"

# If conflict:
git checkout --ours .
git add -u
git commit -m "chore: Merge upstream/main"

Prerequisites

Install the packer tool: https://developer.hashicorp.com/packer/install

Install the Openstack CLI tools:

sudo apt update && sudo apt upgrade
sudo apt install python3-dev
sudo apt install python3-pip
sudo apt install python3-designateclient
sudo pip3 install python-openstackclient
packer plugins install github.com/hashicorp/openstack

Ensure clean Openstack environment
- Remove any unused VMs that are no longer needed, as duplicate names will cause conflicts.
- Remove any old version of the course image if reusing the image name.
- Ensure that a course network exists, with a corresponding gateway router.
- Ensure that a course DNS Zone exists, without any unused records.

Defining the Variables

Change the variables in the variables.py file to your preferred values.

Course specific customization

Modify the course_image/course/setup.sh to include the necessary packages for your course.
- Note: Add lines in the designated area, denoted by ### ADD ANY COURSE-SPECIFIC SETUP BELOW THIS LINE ###.
Add any needed GNS3 devices to the course_image/course/devices folder.
- Devices should be structured in subfolders, with each subfolder containing the files for a single device. Names of the subfolders are not important.
- Supported devices are QEMU (.qcow2 or .iso), Docker (Dockerfile or image tarball), and Dynamips (IOS images).
  - Note: Devices provided as Dockerfiles may also have associated scripts to facilitate installation of additional packages.
  - Note: Devices provided as tarballs should be configured to run interactively, as no additional configuration is performed when importing the device. The provided example Alpine device does not run interactively, and is only provided as an example of how to package a Docker image as a tarball.
- A single meta.json should be included in each device subfolder, containing the device metadata.
  - Note: Examples of meta.json files can be found in the existing template devices. Properties above the empty line can be modified as needed. Additional valid properties can be added if required.
  - Common properties:
    - name: Name of the device as it will appear in GNS3.
    - category: Category of the device as it will appear in GNS3, e.g., "router", "guest".
    - adapters: Number of network adapters for the device. (Not available for Dynamips devices)
    - default_name_format: Format for default naming of devices when added to a project. Use {0} as a placeholder for an incrementing number.
  - Device specific properties:
    - Docker: image property should only be provided if a Dockerfile is used, and will define the tag of the built image. If a Docker tarball is used, the image property will be inferred from the tarball.
    - QEMU: ram, cpus, and adapter_type properties should be provided to define default resource allocation and adapter type.
    - Dynamips: platform property should be provided to define the platform/model of the IOS image. ram should also be provided to define default resource allocation.
You may change course_image/course/course.pkr.hcl to change the script execution behavior.
- In order to add any additional files to the course image, add a new file provisioner in the build section. You should provide a full path to the source file/directory on the local machine, and a destination path inside the VM. As long as the provisioner is added before the final shell provisioner, the files will be available for use in the setup.sh script.
  - Note: If uploading directories, the provisioner need to follow the rules defined here.
  - Note: To avoid ambiguity in the full path, it is possible to add a variable for the source path through the variables.py file, similar to PATH_DEVICES_DIR. The variable should then be passed through the course_image/course_create.py script by importing it and adding to the vars_map dictionary. You should also define the variable in the course_image/course/course.pkrvars.hcl file, similar to the devices_directory variable.
- Note: This file also handles the reassigning of the ubuntu home folder to a shared home folder. If separate home folders are required, this file will need to be modified accordingly.
You may change create_vms/ldap_template.txt in order to setup specific permission configuration.
- Note: This file is partially managed by the create_vms/edit_ldap.py script, changes in the ldap_template.txt file may need to be reflected in the script as well.

Creating the course image

Navigate to the course_image directory.
Run the image creation script:
```
python3 course_create.py
```

Creating the VMs

Navigate to the create_vms directory.
Populate the users.txt file with the desired users.
One line equals a set of users, seperated by a space, belonging to the same group. Admin VMs are created from a line containing a single admin user.
- Example:
```
user1 user2 user3
user4 user5 user6
admin1
admin2
```
Run the VM creation script:
```
python3 vms_create.py
```

Tools

`edit_users.py`

Used to edit the user access rights to the VMs. Can be used to add or remove ssh and sudo rights.

Usage:

python3 edit_users.py <username>@<vm_ip> <add/remove> <comma separated list of users>

Example:

python3 edit_users.py johndoe@1.2.3.4 add user1,user2,user3

ie-iik/2026-thesis-thaasebo

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages