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.

Note: Support for Windows 11 version 21H2 ‘--win11v21h2’ and --vmdelete require python3-amd-config version 2.0.4 or newer.

root@amd-mgr:~# amd_setup sandbox -h
usage: amd_setup sandbox [-h] [--vms] [--vmbuild] [--vmstatus] [--fetch]
                         [--win7] [--win10] [--win10v2004] [--win11v21h2][--linux] [--android]
                         [--instances INSTANCES] [--autosize]
                         [--msofficekey MSOFFICEKEY | --office365] [--kms KMS] [--vmtimezone TIMEZONE] [--vmdelete VM_TYPE]
                         
                         
optional arguments:
  -h, --help            show this help message and exit
  --vms
  --vmbuild
  --vmstatus
  --fetch
  --win7
  --win10
  --win10v2004
  --win11v21h2
  --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))
  --vmdelete VM_TYPE    Delete both VM resources and configuration for the specified VM type

Configuring Windows VMs

amd_setup sandbox --win7
amd_setup sandbox --win10v2004
amd_setup sandbox --win11v21h2

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: 8
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 --win11v21h2 --linux --android --autosize
Instance capacity: 8
Added instances:
        win10:      1
        win10v2004: 1
        win11v21h2: 1
        win7:       1
        android9:   1
        android10:  1
        android11:  1
        ubuntu1804: 1
Total instances: 8
Warning: Windows options require a Microsoft Office license to ensure efficacy for analysis 
of Office documents; supply --msofficekey (supported for win7, win10, win10v2004, 
win11v21h2) or --office365 (only supported for win10v2004)
Warning: Windows options require a Microsoft Office license to ensure efficacy for analysis 
of Office documents; supply --msofficekey (supported for win7, win10, win10v2004, 
win11v21h2) or --office365 (only supported for win10v2004)
Warning: Windows options require a Microsoft Office license to ensure efficacy for analysis 
of Office documents; supply --msofficekey (supported for win7, win10, win10v2004, 
win11v21h2) or --office365 (only supported for win10v2004)
Warning: Windows options require a Microsoft Office license to ensure efficacy for analysis 
of Office documents; supply --msofficekey (supported for win7, win10, win10v2004, 
win11v21h2) or --office365 (only supported for win10v2004)

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
Instance capacity: 7
Total instances: 1
VM status:

VM: win10v2004
Latest version: UNAVAILABLE
Latest version is not up to date with current config
🚧 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.

Deleting a VM (requires python3-amd-config version 2.0.4 or newer):

Once a VM is either configured to be built or is successfully built or its build has failed, if there is a need to delete it to change its configuration, like the number of instances or the office license or to build another type of VM, use the --vmdelete option. This option frees up the resources being used by the specified VM and its configuration as well. This option cannot be used on a VM during build.

Note: VM_TYPE arguments supported for --vmdelete option are: win7, win10, win10v2004, win11v21h2, linux, android.

For example, consider that a Linux VM is successfully built:

# amd_setup sandbox --vmstatus
Instance capacity: 15
Total instances: 1
VM status:

VM: ubuntu1804-amd64
Latest version: 20250714
Resource: ubuntu1804-amd64-20250714-en

To delete it, use the --vmdelete option as below:

# amd_setup sandbox --vmdelete linux
Instance capacity: 15
Total instances: 1
Successfully deleted VM resources & configuration for: ubuntu1804-amd64

Check the VM build status to confirm deletion:

# amd_setup sandbox --vmstatus
Instance capacity: 15
Total instances: 0
VM status:

No desired VMs configured.

For a VM during the build, the --vmdelete option cannot be used.

# amd_setup sandbox --vmstatus
Instance capacity: 15
Total instances: 1
VM status:

VM: ubuntu1804-amd64
Latest version: UNAVAILABLE
Latest version is not up to date with current config
Undesired resource: ubuntu1804-amd64-20250723-en
🏗 Build active

# amd_setup sandbox --vmdelete linux
Instance capacity: 15
Total instances: 1
ERROR:root:Failed to delete VM resources for ubuntu1804-amd64: Error: HTTP 500 (INTERNAL): Cannot modify VM during build