Engine configuration

This section focusses on the amd_setup command.

Note: All CLI commands must be executed either using sudo or logged in as root.

The Engine CLI is primarily concerned with sandbox management. Sandbox environments are instantiated to detonate samples for particular machine types. The amd_setup utility supports the sandbox command.

root@amd-mgr:~# amd_setup sandbox -h
usage: amd_setup sandbox [-h] [--vms] [--vmbuild] [--vmstatus] [--fetch]
                         [--win7] [--win10] [--win10v2004] [--linux] [--android]
                         [--instances INSTANCES] [--autosize]
                         [--msofficekey MSOFFICEKEY | --office365] [--kms KMS] [--vmtimezone TIMEZONE]
                         
                         
optional arguments:
  -h, --help            show this help message and exit
  --vms
  --vmbuild
  --vmstatus
  --fetch
  --win7
  --win10
  --win10v2004
  --linux
  --android
  --instances INSTANCES
  --autosize
  --msofficekey MSOFFICEKEY
  --office365
  --kms KMS
  --vmtimezone TIMEZONE

 timezone for the sandbox virtual machine (e.g. America/Chicago ; see tzselect(8))

Configuring Windows VMs

amd_setup sandbox --win7
amd_setup sandbox --win10v2004

Configuring Linux VMs
```
amd_setup sandbox --linux
```
Configuring Android VMs
```
amd_setup sandbox --android
```
Sandbox engine capacity:
The Engine is capable of running a number of sandbox virtual machine environments in parallel. This capacity is determined primarily by the number of CPUs on the engine and was automatically configured by amd_register. Each virtual machine environment is called an instance.
Tailoring the instance count:
You can specify an explicit instance count for a machine type (For example: win10v2004) by supplying the --instances parameter. In the following example, the Linux machine templates will be instantiated specifying 4 instances per machine type (Ubuntu, Debian, etc.).

Alternatively, you can specify the --autosize parameter to consider all the machines listed on the command line and balance the available resource among them.
Note: Machines not listed in the command are not considered.
```
amd_setup sandbox --linux --instances 4
```

Autosize option:

The --autosize sandbox option can be used to balance the available parallel instance capacity among the machine types listed on the command line.

Note: --autosize will overwrite any existing sandbox machine configurations, so is best used during initial provisioning of the engine.

For example, to create a balanced configuration for all the available sandbox types use the following commands. First we check the status; the status will indicate the parallel instance capacity of the engine.

root@amd-eng:~# amd_setup sandbox --vmstatus
Instance capacity: 7
Total instances: 0
VM status:
 
No desired VMs configured.

Next, we create the basic configuration for each desired sandbox environment:

root@amd-eng:~# amd_setup sandbox --win7 --win10 --win10v2004 --linux --android --autosize
Instance capacity: 7
Added instances:
        win10:      1
        win10v2004: 1
        win7:       1
        android9:   1
        android10:  1
        android11:  1
        ubuntu1804: 1
Total instances: 7
Warning: Windows options require a Microsoft Office license to ensure efficacy for analysis 
of Office documents; supply --msofficekey or --office365
Warning: Windows options require a Microsoft Office license to ensure efficacy for analysis 
of Office documents; supply --msofficekey or --office365

For any sandbox environment requiring additional options such as a license or office, take note of the instance count for that machine type and reissue the setup command with an explicit instance count observed from the --autosize command (1 in this example):

root@amd-eng:~# amd_setup sandbox --win10v2004 --office365 --vmtimezone America/Chicago --instances 1
Instance capacity: 7
Added instances:
        win10v2004: 1
Total instances: 7

Building VMs:
To initiate a build of the configured sandbox VM types, use the --vmbuild option for the sandbox command. The build will create the VM environments for each newly configured or modified machine type. The build will also update sandbox VM environments if there has been a software update applied.
Note: Building sandbox VMs can be a time consuming operation and may take several hours to complete. Once the build has started, check the status with --vmstatus option to see if it has completed.
```
# amd_setup sandbox --vmbuild --vmstatus
```
Checking VM build status:
After allocating a virtual machine type (For example: --win10v2004), the corresponding virtual machine environment will need to be built. You can test the status of the build with the --vmstatus option. If the environment has not yet been built for that type or has changes pending due to a software update, the status will indicate "Build action recommended". The version will indicate "UNAVAILABLE" until the build action has completed (see Building VMs section above).
```
# amd_setup sandbox --vmstatus
sandbox: VM status:  VM: win10v2004
Latest version: UNAVAILABLE
Build action recommended
```
Note: If the build status indicates "UNAVAILABLE" the VM has not been built yet. Whenever a VM configuration has been changed or the base ISO has been updated, a build action is indicated. To start the build, run amd_setup sandbox with a --vmbuild option.