Labtainers Student Guide

Fully provisioned cybersecurity labs

July 6, 2021
1 Introduction
This manual is intended for use by students performing lab exercises with Labtainers. Labtain-
ers provide a fully provisioned execution environment for performing cybersecurity laboratory
exercises, including network topologies that include several different interconnected computers.
Labtainers assume you have a Linux system, e.g., a virtual machine appliance described
below. If you are accessing a Labtainers VM via a web browser, you can skip to section 3.

1.1 Obtaining and installing Labtainers

Labtainers requires an x86-based computer. It will not run on ARM-based processors such as
Mac M1-based Powerbooks.
The easiest way to obtain Labtainers is to download one of the pre-configured virtual ma-
chines from https://nps.edu/web/c3o/virtual-machine-images, and import it into either
VirtualBox or VMWare. Follow the brief instructions on that download page. When you first
boot the resulting VM, Labtainers will take a moment to update itself. You are then provided
a terminal that includes some hints, and can be used to run Labtainers.
Note that the VM’s Ubuntu Linux distribution is configured to NOT automatically perform
system updates. It may prompt you to download and install updates. That is typically not
necessary and may tie up your network bandwidth. Yes, we are suggesting you not update your
Linux VM unless and until you have the time and the bandwidth.
You may now skip to section 3.

1.2 Alternatives to the Labtainers VM Appliance

Skip this section and go to section 2 if you are using a Labtainers VM appliance or accessing
Labtainers remotely via a browser.
Please note that Docker runs as a privileged service on your computer, and Labtainers
containers run as privileged containers. If you have sensitive data on your computer, you should
understand the isolation provided by Dockers on your system. An alternative is to use one of
our virtual machine appliances rather than running Docker directly on your computer.

1.2.1 Installing Labtainers on an existing Linux system

The Labtainer framework is distributed as a tarball from: https://nps.edu/web/c3o/labtainers
Click the link named: “Download the Labtainer framework”, and untar the resulting file into a
permanent directory on your Linux system, e.g., into ~/home. For example, if you downloaded
the file from a browser on your Linux system:

cd
tar -xf ~/Downloads/labtainer.tar

From the directory into which you untarred the tarball start the installer script:

cd labtainer
./install-labtainer.sh

This script will install the latest version of Docker and packages required by the Labtainer
framework. It will cause your Linux host to reboot when it completes.
After the Linux host reboots, open a terminal to your Linux host and change directory to
wherever you untarred the tarball, e.g., your HOME directory.

1
1.2.2 Docker Desktop on Mac and Windows
NOTE: Labs that include GUI’s such as Wireshark do not currently work on Docker Desktop.
This option assumes you have installed Docker Desktop and are familiar with its operation
and its security considerations. Instead of using the window manager of your computer, this
option lets you use a web browser to interact with windows managed by the NOVNC program.
The window manager appears in your browser.
Download the script from https://raw.githubusercontent.com/mfthomps/Labtainers/
master/headless-lite/headless-labtainers.sh, make it executable and run it (first make
sure Docker is running). On a Mac, this would be done from a terminal. On Windows, use
Powershell with the sh command. Open a browser and goto http://localhost:6901/vnc.
html?password= No password is needed, if prompted, simply click the submit button.
In addition to starting the Labtainers, the script will create a $HOME/headless-labtainers
directory.

To start Labtainers from Docker Desktop:

• Open a terminal (Powershell on Windows)

• cd $HOME/headless-labtainers

• ./headless-labtainers.sh
That $HOME/headless-labtainers directory will also contain persistent data, including results
stored in the labtainer xfer subdirectory. Note: Where lab messages and lab manuals
indicate results are found in $HOME/labtainer xfer, your results will be in
$HOME/headless-labtainers/labtainer\_xfer
Use ctrl-c to quit Labtainers.
The password for the labtainer user on the Labtainer computer is labtainer.

2 Selecting a Lab
All labs are run from the same Labtainer workspace directory, which is typically at:
cd $LABTAINER_DIR/scripts/labtainer-student
The prepackaged virtual machines automatically start a terminal in this directory.
To see a list of available labs, run the labtainer command with no arguments:
labtainer
Use the -k option to see a list of searchable keywords, and the -f <keyword> option to view a
summary of labs having that keyword.
Lab exercises are also organized into Labpacks that are a collection multiple related labs
that you may wish to perform in sequence (e.g., based on direction from your instructor.) Use
the
labpack
to view a list of Lab Packs, and provide the name of a Labpack as an argument to see a list of
the labs within a Labpack. That command output also includes an indication ([Y] or [N])
of whether you’ve generated any results from each lab. Your instructor may provide you with
custom Labpacks in the form of a URL. You may add those to your system by using the

2
 labpack -a <url>

Your instructor may direct you to add new or custom lab exercises to your installation by
providing you with a URL of an IModule. To get access to those labs, use:

imodule <url>

Additional lab exercises created by other instructors are available as IModules, whose URLs
are listed at https://nps.edu/web/c3o/imodules.

3 Performing a Lab
To run a specific lab, include the name of the lab in the labtainer command:

labtainer <labname>

where labname is the name of the lab to run.

Most labs direct you to a PDF version of a lab manual, which can usually be viewed by
right clicking on the displayed path, or you can open the file in a browser. Please note that
some of the initial lab instructions repeat the steps you’ve already taken, and you need not
perform those again.
A list of labtainer commands can be found in Appendix A of this document.
Once you start the lab, you will typically see one or more virtual terminals connected to
computers within the lab. While running the lab, if you require more virtual terminals, use:

moreterm.py <labname> <container>

where container is the host name of the component on which to attach a terminal. It can be
omitted for labs having a single component. See Appendix B for information on customizing
terminal window colors and text.
The virtual terminals for most labs present bash shells via which you can interact with the
attached computer, (which is actually a Docker container designed to appear like a separate
computer). A single computer may have multiple virtual terminals attached to it. Each com-
puter is independent, and may use networks to interact with other Labtainer computers within
the lab.
Many labs automatically gather results of your work, which you will provide to your in-
structor. Note that, unless otherwise directed, exploration and experimentation you perform
either before or after performing the expected activity will not diminish or dilute your results.
And you typically do not have to take actions to collect or record your results. This occurs
automatically as noted in the next section.

3.1 Interrupting and Completing Labs

When you want to stop working for a while or are finished and ready to turn it in to your
instructor, type:

stoplab

from the Linux system from which you issued the labtainer command. All changes to the
files, etc. will be preserved and you will be able to resume the lab just the way you started it.
You can resume your work, as needed.
The stoplab command always displays the directory containing a zip file that should be
provided to your instructor. It shows the current results of your work.

3
 The easiest way to forward the complete zip file to the instructor is to start a browser, e.g.,
Firefox, on the VM from which you are running Labtainers. Then use the browser to either
email the zip file, or upload it into an LMS system, e.g., Sakai. Alternately, you can configure
the VM to use a shared folder, and use that to copy the zip file to the host computer.

3.2 Redoing a Lab

Sometimes you might want to redo the lab from the beginning. In this case, type:
labtainer -r <labname>
This will delete any previous containers associated with this lab and start it fresh. Warning:
this will cause all previous data from the named lab to be lost.

3.3 Checking your work

Some labs include criteria by which to automatically assess your progress. Where enabled and
supported, this feature can be utilized by issuing the checkwork command from Linux system.
That command can be run while the lab is still running. If the lab has been stopped, you must
provide the lab name to the checkwork command, e.g.,
checkwork telnetlab

3.4 Submitting your work

The location of your results depends on whether your are using Linux, e.g., the Labtainers VM
appliance, or Docker Desktop.

3.4.1 From the Labtainers VM or Linux

When you’ve completed a lab and run the stoplab command, your results are stored in a zip
file in the directory at:
$HOME/labtainer_xfer/<lab name>
That file should be provided to your instructor. There are several ways to transfer the file.
1. Use the browser on the VM to email the file to your instructor.
2. Use the browser on the VM to access your school’s LMS system such as Saki or Black-
board, and upload the file.
3. Configure the VM to enable drag and drop, then move the file to your host computer to
email or upload to an LMS.
4. Configure the VM and host to share folders and copy the zip file to the shared folder to
email or upload to an LMS.

3.4.2 From Docker Desktop

On Docker Desktop installations of Labtainers, your results are stored in a zip file at:
$HOME/headless-labtainers/labtainer_xfer/<lab nam>
Provide that file to your instructor by email or uploading it to your school’s LMS, e.g, Black-
board or Saki.

4
3.5 Getting Help and Things to Avoid
To get help, type:

labtainer -h

from the Linux system from which you issued the labtainer command. A list of useful labtainer
commands will be displayed. Also see our support page at nps.edu/web/c3o/support1
Do not run multiple labs simultaneously. Consistent results cannot be guaranteed when
more than one lab runs at the same time.

4 Other Considerations
4.1 Networking
In addition to network properties defined for the lab, each component /etc/host file includes
a “my host entry” that names the Linux host, e.g., the VM. Most containers will include a
default gateway that leads to the Linux host. This allows students to scp files to/from the
container and Linux host. It also allows the student to reach external networks, e.g., to fetch
additional packages in support of student exploration.
In some instances, the lab requires one or more components to a have different default
route. Typically, these components will include a togglegw.sh script that the student can use
to toggle the default gateway between one that leads to the host, and one defined for the lab.
This allows students to add packages on components having lab-specific default gateways. Use
of the togglegw.sh script is not necessary to reach the Linux host, (e.g., to scp files).

4.2 Installing and Using Labtainers Behind a Web Proxy

If you are not behind a web proxy, ignore this section (most school environments are not behind
proxies). If you are behind a web proxy, Labtainer installation requires that you have configured
your Linux package management configuration to reflect the proxy, e.g., the /etc/atp/apt.conf
or /etc/dnf.conf files.
Additionally, you will need to configure your Docker service as described at: https://
docs.docker.com/engine/admin/systemd/#httphttps-proxy And set the HTTP PROXY
environment variable to your proxy, e.g.,

HTTP_PROXY=http://myproxy:3128

If you wish to use apt-get from within a container to add new software to a container, you must
first modify the container’s /etc/apt/apt.conf file to reflect your proxy.

4.3 Limitations
The Labtainer “computers” are individual Docker containers that are interconnected via virtual
networks. These containers each share the Linux kernel of your host. Thus, a change to the
kernel configuration on one computer, (e.g., enabling ASLR), will be visible on other containers,
as well as your host.
It is suggested that the student’s Linux host be a virtual machine that is not used for
purposes requiring trust. Software programs contained in cybersecurity lab exercises are not,
in general, trusted. And while Docker containers provide namespace isolation between the
containers and the Linux host, the containers run as privileged. Labtainers run as Docker
containers and use the Docker group which is root-equivalent. In other words, even though

5
you start a Docker container as a non-privileged user, software in the resulting container can
modify the Linux host, e.g., the VM.
The computers each include a “local” directory beneath the HOME directory. This is used
by the Labtainer framework and includes results that get packaged up for forwarding to the
instructor. Do not modify any files beneath the .local directory. Otherwise, you can treat those
containers as Linux systems, and explore them.
Pasting multiple commands into a labtainer terminal may result in the not all of the com-
mands being executed.

6
Appendices
Appendix A Labtainer Command Summary
The following labtainer commands are available from the labtainer/labtainer-student di-
rectory. Most of these commands include a -h option for help:

• labtainer <lab> -- Start the named lab. If no name is given, a list of available labs
will be displayed.

• stoplab -- Stop the currently running lab.

• moreterm.py <lab> <container> -- create a new virtual terminal for the container.

• labtainer <lab> -r -- Delete any previous containers associated with this lab and
start it fresh. Warning: this will lose any previous data from the named lab.

• checkwork – Performs automated assessment for selected labs and provides you with
information about your progress.

• quiz – Provides a quiz for selected labs to help prepare you to perform the lab.

• check nets.py – Runs diagnostics to potentially resolve Docker related problems.

Most labs display lab instructions in one of the windows that appears after the lab starts.
If those instructions stop displaying, e.g., because “q” is pressed in that window, then type the
following in a virtual terminal (e.g., in a new terminal created using the moreterm.py script:

less instructions.txt

Appendix B Customizing terminals

Terminal colors and text size can be customized by right clicking on a terminal and selecting
Preferences. From there, select the Unnamed or Default profile and click its down-arrow and
select ”clone”. Give the new profile a name, and then select your new profile. Adjust the colors
and text appearance by selecting the tabs on the top of the window. Experiment by creating
a new terminal window, right-click and select your profile from the Profiles submenus.
If you want all of your terminals to look like a new profile, click the down arrow on your
new profile and make it the “default”.
If you create a terminal profile named labtainers, that profile will be used with Labtainers
lab terminals. This can be helpful to distinguish the Labtainers terminals from other terminals
on your desktop.