|
|
This page describes the _intermediate definition_ generation process. The intermediate definition is the output of the Cyber Sandbox Creator, and it serves as input to Sandbox Manager, which builds and configures the virtual machines.
|
|
|
|
|
|
# Generating the Intermediate Definition
|
|
|
|
|
|
Before generating the intermediate definition, complete the [Installation steps](3.0/Installation). Moreover, a topology definition file is required. It can be one of the provided [example topologies](3.0/Example-Topologies) or a new one, which can be created using the [Sandbox Definitions](3.0/Sandbox-Definitions) page.
|
|
|
|
|
|
After a successful installation, the command `create-sandbox` is usable from any location. It is a command-line tool for generating `intermediate definitions` from `sandbox definitions`.
|
|
|
|
|
|
The command
|
|
|
|
|
|
`$ create-sandbox <topology-file-location>`
|
|
|
|
|
|
generates the intermediate definition in the `sandbox` directory on the same location as the topology definition. If the directory does not exist, it is created. If it exists, the intermediate definition will be regenerated (except user provisioning files - see later on this page).
|
|
|
|
|
|
The output location can be controlled using the option `-o` or `--output-dir`. It expects an absolute or relative path to a directory. The intermediate definition is generated inside that directory. If the directory does not exist, it is created.
|
|
|
|
|
|
By default, the intermediate definitions are generated so that Ansible installed on virtual machines will be used for provisioning. The option `--ansible-installed` can be used to generate intermediate definitions that use Ansible installed on the host machine for provisioning. These intermediate definitions, however, cannot be used on Windows machines.
|
|
|
|
|
|
# Command line options
|
|
|
|
|
|
```
|
|
|
usage: create-sandbox [-h] [-o OUTPUT_DIR] [-a] [--rewrite-provisioning]
|
|
|
[--provisioning-dir PROVISIONING_DIR]
|
|
|
[--extra-vars EXTRA_VARS] [--verbose-ansible]
|
|
|
topology_file
|
|
|
```
|
|
|
|
|
|
## Positional arguments
|
|
|
|
|
|
There is one required positional argument, the path to the definition YAML file.
|
|
|
|
|
|
## Optional arguments
|
|
|
|
|
|
| Short arguments | Long arguments | Description |
|
|
|
| :---: | :---: | :--- |
|
|
|
| -h | --help | Shows a help message. |
|
|
|
| -o | --output-dir OUTPUT_DIR| Path to the directory where the intermediate definition should be generated. |
|
|
|
| -a | --ansible-installed | Uses Ansible installed on the host machine instead of trying to install it to the virtual machines. This option cannot be used on host machines running Windows. |
|
|
|
| | --provisioning-dir PROVISIONING_DIR | Path to user provisioning directory. If defined, the contents of this directory will be copied to the `provisioning` subdirectory of the intermediate definition. |
|
|
|
| |--extra-vars EXTRA_VARS| Path to a YAML file with additional keys and values for the Ansible attribute `extra_vars`. |
|
|
|
| | --verbose-ansible | Sets verbose mode for Ansible output (-vv). Useful for debugging. |
|
|
|
|
|
|
# Advanced functionality
|
|
|
|
|
|
## Adding user provisioning files
|
|
|
|
|
|
The generated sandbox directory contains directories `preconfig` and `provisioning`. `preconfig` contains files for the basic configuration of the created devices, like network configuration. These files should not be edited. `provisioning`, however, is a directory for user Ansible files. Cyber Sandbox Creator typically generates an example for user provisioning files. If the user wants to use other, already prepared configuration files, the command line attribute `--provisioning-dir` can be used. In this argument, one can specify the location of a directory where the provisioning files are located. These files (with all subdirectories) will be copied to the `provisioning` directory of the intermediate definition (example provisioning files will not be generated). The provisioning directory must contain an Ansible playbook called `playbook.yml`. This playbook will be loaded after the basic configuration of the virtual machine is done.
|
|
|
|
|
|
By default (without using the `--provisioning-dir` option), when a new intermediate definition is generated, it rewrites the old definition (if it exists on the same location). The only exception is the `provisioning` subdirectory, which is left untouched. The option `--rewrite-provisioning` can be used to force the regeneration of the provisioning directory. If the `--provisioning-dir` option is used, the directory is always overwritten by the user-provided provisioning files.
|
|
|
|
|
|
## Adding extra_vars for Ansible
|
|
|
|
|
|
Sometimes there is a need to pass additional arguments to Ansible to its variable `extra_vars`. This can be achieved by the command line argument `--extra-vars`. This argument expects a path to a YAML file with the required keys and values, which will be added to the generated Vagrantfile. The file should have the following structure:
|
|
|
```
|
|
|
attribute_name: value
|
|
|
another_attribute: another_value
|
|
|
``` |
|
|
\ No newline at end of file |