Bring Your Own macOS Serial Number

📘

Orka 2.4.x content

This page has not been updated to reflect the changes introduced in Orka 3.0. Some of the information might be outdated or incorrect. Use 2.4.x to 3.0.0: API Mapping and 2.4.x to 3.0.0: CLI Mapping to figure out the correct endpoints and commands.

🚧

Intel Nodes Only

This guide is applicable to VMs deployed on Intel nodes only. Read more about Apple ARM-based Support to see which commands and options are supported for VMs deployed on Apple ARM-based nodes.

🚧

Quick Navigation

Jump to: Overview | Creating a VM Configuration | Deploying a VM | Using the Orka API

Overview

Starting with Orka 1.6.0, you have the option to provide a system serial number for your macOS virtual machine. Serial numbers are assigned on a per-VM basis and can either be provided when creating a VM configuration or set at the time of deployment. If a serial number is provided when creating a VM configuration, any VM deployed using that configuration will share that serial number.

📘

IMPORTANT

You must own the provided serial number. This feature is provided in good faith and positive intent is assumed!

Creating a VM Configuration

From the command line create a new VM config, passing the --system-serial flag:

orka vm create-config --system-serial <serial-number>

Make sure to provide your custom serial number after the --system-serial flag.

You can verify the serial number was added to the VM configuration by running the command orka vm configs:

Deploying a VM

A serial number can also be provided at the time of deployment:

orka vm deploy --vm <vm-config-name> --system-serial <serial-number> -y

or

orka vm deploy --vm <vm-config-name> --system-serial <serial-number> --json

📘

NOTE

The --system-serial flag is also available for the orka vm create command, which will perform both tasks of creating a configuration and deploying a VM using that configuration.

Example:

After connecting to the VM via VNC, the serial number can be verified by viewing  → About This Mac:

📘

NOTE

If VNC is not enabled for the VM, the serial number can be verified using the command system_profiler SPHardwareDataType over an SSH connection.

Using the Orka API

When calling the Orka API directly, use the key system_serial in the JSON body as shown below:

curl --location --request POST 'http://<orka-api-ip>/resources/vm/deploy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
	"orka_vm_name": "my-vm",
	"system_serial": "C02Z90WPHX87"
}'

Replace <orka-api-ip> with 10.221.188.20, 10.221.188.100, or your Orka domain, or your external custom domain. Note that for Orka and custom domains you need to switch to https.

Limitations

• Assigning different serial numbers to VMs which use saved state is not possible.