|
|
This page describes the structure and attributes of topology definition files.
|
|
|
|
|
|
The same topology definition files can be used to build sandboxes in cloud environments using the [KYPO Cyber Range Platform](https://docs.crp.kypo.muni.cz/). Because cloud environments need a slightly different set of arguments, some of them are ignored by CSC, and some are used only by CSC. This guide includes every possible argument, which helps to build compatible definitions for local and cloud environments. The [KYPO platform guide](https://docs.crp.kypo.muni.cz/user-guide-advanced/sandboxes/topology-definition/) can also be helpful when creating compatible definitions.
|
|
|
|
|
|
# Definitions file structure
|
|
|
|
|
|
## Basic attributes
|
|
|
|
|
|
- `name`: short name of the topology (required)
|
|
|
- `hosts`: a list of host devices. All attributes of the virtual machines that will be created are defined here. Every host must have a `name`, which must be unique within the definition, and a `base_box`. (required)
|
|
|
- `name`: unique name of the device (required)
|
|
|
- `base_box`:
|
|
|
- `image`: an OS image that will be installed on the machine (required)
|
|
|
- `mgmt_user`: OS image management user for cloud environment - ignored by CSC (optional)
|
|
|
- `mgmt_protocol`: communication protocol `ssh` or `winrm` - Linux images use `ssh` and Windows images use `winrm` (default: `ssh`) (optional)
|
|
|
- `extra`: special attributes used only by CSC (optional)
|
|
|
- `cpus`: number of CPU units - overwrites the value specified in `flavor` (optional)
|
|
|
- `memory`: required memory size in MB - overwrites the value specified in `flavor` (optional)
|
|
|
- `usb_passthrough`: hardware USB devices will be usable on the virtual machine regardless of its value (details about this feature follows after this section) (optional)
|
|
|
- `flavor`: a quick definition of memory and CPUs (details below) (required)
|
|
|
- `hidden`: ignored by CSC (optional)
|
|
|
|
|
|
- `routers`: a list of routers. (required, can be empty)
|
|
|
- `name`: a unique router name (required)
|
|
|
- `base_box`:
|
|
|
- `image`: an OS image that will be installed on the machine (required)
|
|
|
- `mgmt_user`: ignored by CSC (optional)
|
|
|
- `mgmt_protocol`: CSC can work only with `ssh` routers (optional)
|
|
|
- `flavor`: a quick definition of memory and CPUs (details below) (required)
|
|
|
|
|
|
- `wan`: A special network for routers. All routers are assigned to this network and they communicate with each other and the Internet through it. (optional)
|
|
|
- `name`: name of the network (default: `wan`)(optional)
|
|
|
- `cidr`: network address range in cidr notation `(default: `100.100.100.0/24`)(optional)
|
|
|
|
|
|
- `networks`: list of networks (required)
|
|
|
- `name`: unique name of the network (required)
|
|
|
- `cidr`: IP address of the network in cidr notation (required)
|
|
|
- `accessible_by_user`: ignored by CSC (optional)
|
|
|
|
|
|
- `net_mappings`: mappings of host machines to a network. This list defines the IP addresses of hosts in the networks (required - can be empty)
|
|
|
- `host`: name of an existing host (required)
|
|
|
- `network`: name of an existing network (required)
|
|
|
- `ip`: IP address of the host in the network (required)
|
|
|
|
|
|
- `router_mappings`: similar to net_mappings. It defines the addresses of routers inside networks. (required - can be empty)
|
|
|
- `router`: name of an existing router (required)
|
|
|
- `network`: name of an existing network (required)
|
|
|
- `ip`: IP address of the router in the network (required)
|
|
|
|
|
|
- `groups`: list of additional groups for ansible. Groups `all`, `routers`, `hosts`, `ssh` and `winrm` are available without additional definition. (required - can be empty)
|
|
|
- `name`: name of the group (required)
|
|
|
- `nodes`: list of device names in the group (required)
|
|
|
|
|
|
|
|
|
## Flavors
|
|
|
|
|
|
Flavors provide a quick way to choose hardware specs (like the number of CPUs and memory) for a virtual machine. These attributes can also be specified separately by `extra` attributes `memory` and `cpus`. The values of `memory` and/or `cpus` always override the values specified in the `flavor`.
|
|
|
|
|
|
Flavors are always required because they are the only means to specify memory and the number of CPUs on cloud environments. CSC has more flexible attributes for this, so `flavor` can be seen as a "fallback" if the sandbox is built in the cloud.
|
|
|
|
|
|
### Supported flavors
|
|
|
| flavor | cpus | memory |
|
|
|
| ------------------ |:--:|:-----:|
|
|
|
| csirtmu.tiny1x2 | 1 | 2048 |
|
|
|
| csirtmu.tiny1x4 | 1 | 4096 |
|
|
|
| csirtmu.small2x4 | 2 | 4096 |
|
|
|
| csirtmu.small2x8 | 2 | 8192 |
|
|
|
| csirtmu.medium4x8 | 4 | 8192 |
|
|
|
| csirtmu.medium4x16 | 4 | 16384 |
|
|
|
| csirtmu.large8x16 | 8 | 16384 |
|
|
|
| csirtmu.large8x32 | 8 | 32768 |
|
|
|
| csirtmu.jumbo16x32 | 16 | 32768 |
|
|
|
| csirtmu.jumbo16x64 | 16 | 65536 |
|
|
|
|
|
|
## USB passthrough
|
|
|
|
|
|
The USB passthrough is only usable on virtual machines with a GUI at the moment. After adding the required attribute to a host, VirtualBox will enable USB passthrough to the given virtual machine during the instantiation. After starting the VM, the USB devices can be connected using the GUI options under `Devices/USB`. A single USB device cannot be connected to multiple virtual machines at once.
|
|
|
|
|
|
## Windows box support
|
|
|
|
|
|
Windows box support is only experimental at this stage. Currently, only `munikypo/windows-server-2019` box is supported. Unless `--ansible-installed` is used, during the instantiation, an additional virtual machine is created (controller) for the provisioning.
|
|
|
|
|
|
## Supported vagrant boxes
|
|
|
| Box name | Minimum required memory|
|
|
|
| ------------------ |:-----:|
|
|
|
| munikypo/debian-10 | 128 MB |
|
|
|
| munikypo/kali-2019.4 | 512 MB |
|
|
|
| munikypo/kali-2020.4 | 512 MB |
|
|
|
| munikypo/windows-server-2019 | 1024 MB | |
|
|
\ No newline at end of file |