NanaBox Configuration File Reference

Overview

File Extension: .7b
Save Encoding: UTF-8 with BOM as mandatory
Configuration Format: JSON (JavaScript Object Notation)
JSON Schema: https://raw.githubusercontent.com/M2Team/NanaBox/main/Documents/ConfigurationSchema.json

{
    "NanaBox": {
        "Type": "VirtualMachine",
        "Version": 1,
        "GuestType": "Windows",
        "Name": "DemoVM",     
        "ProcessorCount": 4,
        "MemorySize": 2048,
        "ComPorts": {
            "UefiConsole": "ComPort1",
            "ComPort1": "\\\\.\\pipe\\vmpipe1",
            "ComPort2": "\\\\.\\pipe\\vmpipe2"
        },
        "Gpu": {
            "AssignmentMode": "List",
            "SelectedDevices": [
                "\\\\?\\PCI#VEN_10DE&DEV_1C82&SUBSYS_11BF1B4C&REV_A1#4&38ab2860&0&0008#{064092b3-625e-43bf-9eb5-dc845897dd59}\\GPUPARAV"
            ]
        },     
        "NetworkAdapters": [
            {
                "Connected": true,
                "MacAddress": "00-15-5D-64-2F-AB",
                "EndpointId": "f2288275-6c30-47d4-bc24-293fa9c9cb12"
            }
        ],
        "ScsiDevices": [
            {
                "Type": "VirtualDisk",
                "Path": "Test.vhdx"
            },
            {
                "Type": "VirtualImage",
                "Path": ""
            }
        ],
        "SecureBoot": true,
        "Tpm": true,
        "GuestStateFile": "Test.vmgs",
        "RuntimeStateFile": "Test.vmrs",
        "SaveStateFile": "Test.SaveState.vmrs",
        "ExposeVirtualizationExtensions": true
    }
}

Reference

NanaBox (Object)
- Type (String)
- Version (Number)
- GuestType (String)
- Name (String)
- ProcessorCount (Number)
- MemorySize (Number)
- ComPorts (Object)
  - UefiConsole (String)
  - ComPort1 (String)
  - ComPort2 (String)
- Gpu (Object)
  - AssignmentMode (String)
  - EnableHostDriverStore (Boolean)
  - SelectedDevices (String or Object Array)
    - DeviceInterface (String, Object Array Only)
    - PartitionId (String, Object Array Only)
- NetworkAdapters (Object Array)
  - Connected (Boolean)
  - MacAddress (String)
  - EndpointId (String)
- ScsiDevices (Object Array)
  - Type (String)
  - Path (String)
- SecureBoot (Boolean)
- Tpm (Boolean)
- GuestStateFile (String)
- RuntimeStateFile (String)
- SaveStateFile (String)
- ExposeVirtualizationExtensions (Boolean)
- Keyboard (Object Array)
  - RedirectKeyCombinations (Boolean)
  - FullScreenHotkey (Number)
  - CtrlEscHotkey (Number)
  - AltEscHotkey (Number)
  - AltTabHotkey (Number)
  - AltShiftTabHotkey (Number)
  - AltSpaceHotkey (Number)
  - CtrlAltDelHotkey (Number)
  - FocusReleaseLeftHotkey (Number)
  - FocusReleaseRightHotkey (Number)
- EnhancedSession (Object Array)
  - RedirectAudio (Boolean)
  - RedirectAudioCapture (Boolean)
  - RedirectDrives (Boolean)
  - RedirectPrinters (Boolean)
  - RedirectPorts (Boolean)
  - RedirectSmartCards (Boolean)
  - RedirectClipboard (Boolean)
  - RedirectDevices (Boolean)
  - RedirectPOSDevices (Boolean)
  - RedirectDynamicDrives (Boolean)
  - RedirectDynamicDevices (Boolean)
  - Drives (String Array)
  - Devices (String Array)
- ChipsetInformation (Object)
  - BaseBoardSerialNumber (String)
  - ChassisSerialNumber (String)
  - ChassisAssetTag (String)
  - Manufacturer (String)
  - ProductName (String)
  - Version (String)
  - SerialNumber (String)
  - Family (String)
  - UUID (String)
  - SKUNumber (String)

NanaBox

The parent object for all types of NanaBox Configuration File.

Type

The type of configuration.

Available values: "VirtualMachine"

Version

The version of virtual machine configuration. Only 1 is available.

Available values: 1

GuestType

The guest OS type of virtual machine.

Available values: "Windows", "Linux" and "Unknown"

Name

The unique name of virtual machine.

Example value: "TestVM"

ProcessorCount

The processor count of virtual machine, in cores.

Example value: 2

MemorySize

The memory size of virtual machine, in MB.

Example value: 2048

Note: You can update the memory size at runtime starting with NanaBox 1.1.

ComPorts

The COM ports setting object of virtual machine.

UefiConsole

The UEFI serial console setting of virtual machine.

Available values: "Disabled", "Default", "ComPort1" and "ComPort2"

ComPort1

(Optional) The named pipe path of guest COM1 of virtual machine.

Example value: "\\.\pipe\vmpipe1"

Note: You can update the named pipe path at runtime starting with NanaBox 1.1.

ComPort2

(Optional) The named pipe path of guest COM2 of virtual machine.

Example value: "\\.\pipe\vmpipe2"

Note: You can update the named pipe path at runtime starting with NanaBox 1.1.

Gpu

The GPU setting object of virtual machine. You can choose GPU-P (partitioning) and/or GPU-PV (paravirtualization) modes for every specific GPU instance.

Note: Before NanaBox 1.3 Update 1, you can only use GPU-PV (paravirtualization) mode for virtual machines.

Note: You can update GPU setting at runtime starting with NanaBox 1.1.

AssignmentMode

The GPU assignment mode setting of virtual machine.

Available values: "Disabled", "Default", "List" and "Mirror"

"Disabled" mode: Do not assign any GPU to the virtual machine.
"Default" mode: Assign the single default GPU with GPU-PV (paravirtualization) mode to virtual machine, which currently is POST GPU.
"List" mode: Assign the GPU(s)/partition(s) specified in SelectedDevices to virtual machine. If SelectedDevices is empty, do not assign GPU to the virtual machine.
"Mirror" mode: Assign all current and future GPUs with GPU-PV (paravirtualization) mode to virtual machine.

EnableHostDriverStore

(Optional) Set it true if you want to enable HostDriverStore folder readonly share for both Virtual SMB and Plan 9, which can mirror the DriverStore folder from the Host OS. It will be useful when users using GPU paravirtualization feature.

Note: You cannot suspend the virtual machine properly if this option is enabled.

Note: Available starting with NanaBox 1.2.

SelectedDevices

(Optional) The string or object array of selected GPUs used for virtual machine. Set as the object with "DeviceInterface" and "PartitionId" for the specific GPU instance if you want to use GPU-P (partitioning) mode, or set as the string which contains "DeviceInterface" for using GPU-PV (paravirtualization) mode.

Note: Only valid in "List" GPU paravirtualization assignment mode.

Note: Before NanaBox 1.3 Update 1, you can only use GPU-PV (paravirtualization) mode for virtual machines.

Reference: https://docs.microsoft.com/en-us/windows/win32/hyperv_v2/msvm-partitionablegpu

DeviceInterface

The device interface path of the selected GPU used for paravirtualization of virtual machine.

Example value: "\\?\PCI#VEN_10DE&DEV_1C82&SUBSYS_11BF1B4C&REV_A1#4&38ab2860&0&0008#{064092b3-625e-43bf-9eb5-dc845897dd59}\GPUPARAV"

PartitionId

The partition ID of the selected GPU used for paravirtualization of virtual machine. It's actually an uint16 value. Set it 65535 for using GPU-PV (paravirtualization) mode.

NetworkAdapters

The network adapters setting object array of virtual machine.

Note: You can add, remove and update network adapters at runtime starting with NanaBox 1.1.

Connected

Make the current network adapter connected if set it true.

MacAddress

(Optional) The MAC address of the current network adapter.

Note: If value not set, NanaBox will generate a new one for it.

Example value: "00-15-5D-64-2F-AB"

EndpointId

(Optional) The Endpoint GUID of the current network adapter.

Note: If value not set, NanaBox will generate a new one for it.

Note: This option is used for internal implementation.

Example value: "f2288275-6c30-47d4-bc24-293fa9c9cb12"

ScsiDevices

The SCSI devices setting object array of virtual machine.

Note: You can add and update SCSI devices at runtime starting with NanaBox 1.1.

Type

The type of the current SCSI device.

Available values: "VirtualDisk", "VirtualImage" and "PhysicalDevice"

Path

The path of the current SCSI device.

Note: The relative path is supported.

When type is "VirtualDisk", you can use vhdx and vhd files.

When type is "VirtualImage", you can use iso files, and you can make it empty or not set if you want to make a ejected virtual optical drive.

When type is "PhysicalDevice", you can expose your physical drive to virtual machine. you can set it something like "\\.\PhysicalDriveX" where X is an integer that represents the particular enumeration of the physical disk on the caller's system.

SecureBoot

(Optional) The Secure Boot setting of virtual machine.

If you want to enable Secure Boot for your virtual machine, please set it true.

Tpm

(Optional) The Trusted Platform Module (TPM) setting of virtual machine.

If you want to enable Trusted Platform Module (TPM) for your virtual machine, please set it true.

Note: Available starting with NanaBox 1.2 Update 2.

Note: Only the Trusted Platform Module (TPM) 2.0 is supported.

Note: You need Windows 11 Version 24H2 or later Host OS. (Although Windows Server 2022 had introduced the related Host Compute System API interfaces, but it seems doesn't be implemented.)

GuestStateFile

(Optional) The path of guest state file for virtual machine.

Note: The relative path is supported.

Note: If value not set or file not exist, NanaBox will create a new one for it.

Example value: "TestVM.vmgs"

RuntimeStateFile

(Optional) The path of runtime state file for virtual machine.

Note: The relative path is supported.

Note: If value not set or file not exist, NanaBox will create a new one for it.

Example value: "TestVM.vmrs"

SaveStateFile

(Optional) The path of save state file for virtual machine.

Note: The relative path is supported.

Note: This option is used for internal implementation.

Example value: "TestVM.SaveState.vmrs"

ExposeVirtualizationExtensions

(Optional) Expose the virtualization extensions to the virtual machine if set it true.

Note: Some processors don't support exposing the virtualization extensions to the virtual machine.