Creating your first Deputy Package

A new package can be initialized using the deputy create command. This command will prompt for basic information about the package.

Since a Virtual Machine is the basis for most exercises, let us create a VM (Virtual Machine) package for our first exercise.

deputy create

When prompted, select vm for the package type. All of this can be later changed manually as well.

After it has been created, by navigating to the package directory we can see that the package has been initialized with a src folder for our package files, a README.md which should contain an overview of the package that is also displayed on the Deputy website after it has been published, and a package.toml file that contains the package metadata.

my-first-package
├── package.toml
├── README.md
└── src
    └── // package files //

Before we can publish the package, we need to add some files to it. And fill out the remaining metadata. For this example, we will export a pre-made VM from our vSphere environment and add it to the package. To create your own, you can either make a VM from scratch or modify an existing one to your liking.

Exporting a VM from VirtualBox or VMware Workstation

Exporting a virtual machine (VM) can be done efficiently in VirtualBox and VMware Workstation with the following steps:

1. VirtualBox:

   • Right-click the VM in VirtualBox and select "Export to OCI" to launch the export wizard. Follow the prompts to save the VM as an OVA file.

2. VMware Workstation:

   • In VMware Workstation, right-click the VM and choose "Export to OVF". This will start a wizard that guides you through exporting your VM in OVF or OVA format.

Make sure to detach any unnecessary virtual disks, such as ISO files, unless they are essential for the VM’s operation to avoid increasing the export file size.

Finalizing the package

Armed with our OVA file, we can now copy it to our package. The location is not important as long as its path is described in the package.toml file, but for this example we will copy it to the src folder of our package.

After our OVA has been copied, we need to fill out the following fields in the package.toml file:

• operating_system - the operating system of the VM. Supported values are:

AlmaLinux,
AmazonLinux,
Asianux,
CentOS,
Debian,
DebianGNULinux,
EComStation,
Fedora,
Flatcar,
FreeBSD,
KylinLinuxAdvancedServer,
MacOs,
MiracleLinux,
NeoKylinLinuxAdvancedServer,
OpenSuse,
OracleLinux,
OSX,
Pardus,
Photon,
RedHatEnterpriseLinux,
RockyLinux,
SCOOpenServer,
SCOUnixWare,
Solaris,
SUSELinuxEnterprise,
Ubuntu,
Windows10,
Windows11,
Windows2000,
Windows7,
Windows8,
WindowsServer2003,
WindowsServer2008,
WindowsServer2012,
WindowsServer2016,
WindowsServer2019,
WindowsServer2022,
WindowsVista,
WindowsXP

• architecture - the architecture of the VM. Supported architectures are: amd64, arm64, armhf, i386
• file_path - the relative path to the OVA file
• accounts - the available accounts for the VM. This does not need to be an extensive list, just the ones the exercise manager wishes to use in the exercise.
• default_account - the default account for the VM. - Deprecated, soon to be removed.
• categories - Optional. Add categories to the package to make it easier to find.

In the end the package.toml file should look something like this:

[package]
name = "debian11-network-manager"
description = "Debian11 CLI with network-manager, curl, wget installed."
version = "0.3.0"
authors = ["Developers developers@cyber-range.no"]
license = "MIT"
readme = "README.md"
categories = ["debian", "nmcli"]

[content]
type = "vm"

[virtual-machine]
accounts = [
    { name = "root", password = "password" },
    { name = "user", password = "password" },
]
default_account = "root"
operating_system = "Debian"
architecture = "amd64"
type = "OVA"
file_path = "src/debian11-network-manager.ova"
readme_path = "README.md"

The package is now ready to be published. To do so, we need to first login to Deputy CLI using our unique Deputy Token with the deputy login command.

Note: This package already exists in the Digital Library and a new version of it cannot be uploaded unless you are assigned ownership of the package. However, a new package with a new name can readily be made.

• Acquiring a Deputy Token

  • Login to the Deputy website and navigate to the User > Tokens page. Click on the Create Token button and give it a name. Copy the token to your clipboard.

• Note: As with other tokens, it can only be viewed once. If you lose it, you will have to create a new one.

• Logging in to Deputy CLI

  • Run the deputy login command and paste the token when prompted.

• Publishing the package

  • Run the deputy publish command in the package's directory. This will upload the package to the Digital Library and can be viewed on the Deputy website.
  • If you wish to update the package. You have to change to version number in the package.toml file and run the deputy publish command again.
  • If you wish to remove the package, you can do so by running the deputy yank command.