Modifying your VM
Modify your VM using the Anka Virtualization CLI
Prerequisites
The rest of this Getting Started guide focuses heavily on the (Command-Line Interface). These will be performed from within your macOS Terminal. For all available CLI commands, flags, and options, see the Command Reference.
> anka modify --help
usage: modify vmid <command>
Modify a VM parameters
arguments:
vmid Virtual machine to modify
commands:
add Add new items to a VM configuration
delete Remove items from a VM configuration
name Set new name for the VM
cpu Set number of vcpu cores and frequency
ram Set RAM size and parameters
network Modify network card settings
port Add port forwarding rule
disk Modify hard drive settings
display Configure displays
label Assign labels to a VM in key/value form
Recommended VM Resources
Over time, this information may become out of date. The goal is to provide you with an idea of the CPU and RAM to set for VMs depending on the amount you wish to run. Note that Apple does not permit more than 2 VMs per machine (this is only a strict limitation on ARM machines currently).
Intel
To calculate the cores available for VMs, you’ll take the number of physical cores and then multiply it by 2. Once you have the total virtual cores, you can assign all of them (maybe - 1 or 2 CPUs to give the host breathing room) if you plan to run a single VM on the host. Otherwise, if you want to run two VMs at once, you’ll divide the total virtual cores by 2 and then assign this number to the VM Template. RAM follows a similar pattern, giving 2GB for the host: totalRAMGB - 2GB and (totalRAMGB / 2) - 2GB.
ARM
Things are similar with slightly different CPUs calculations due to the different CPU types:
| Apple/ARM | 1 VM | 2 VMs |
| Mac Mini, M1/M2 8-core | CPUs: 6 or 8-cores RAM: totalRAMGB - 2GB | CPUs: 4-cores RAM: (totalRAMGB / 2) - 2GB |
| Mac Mini, M2 Pro 10-core | CPUs: 8 or 10-cores RAM: totalRAMGB - 2GB | CPUs: 6-cores RAM: (totalRAMGB / 2) - 2GB |
| Mac Mini, M2 Pro 12-core | CPUs: 10 or 12-cores RAM: totalRAMGB - 2GB | CPUs: 8-cores RAM: (totalRAMGB / 2) - 2GB |
| Mac Studio, M2 Max 12-core | CPUs: 10 or 12-cores RAM: totalRAMGB - 2GB (max of 60GB) | CPUs: 8-cores RAM: (totalRAMGB / 2) - 2GB (max of 60GB) |
| Mac Studio, M2 Ultra 24-core | CPUs: 10 or 12-cores RAM: totalRAMGB - 2GB (max of 60GB) | CPUs: 10 or 12-cores RAM: (totalRAMGB / 2) - 2GB (max of 60GB) |
| Mac Studio, M1 Max, 2022 10-core | CPUs: 8-cores RAM: totalRAMGB - 2GB (max of 60GB) | CPUs: 6 or 8-cores RAM: (totalRAMGB / 2) - 2GB (max of 60GB) |
| Mac Studio, M1 Ultra, 2022 20-core | CPUs: 10-cores RAM: totalRAMGB - 2GB (max of 60GB) | CPUs: 6 or 8-cores RAM: (totalRAMGB / 2) - 2GB (max of 60GB) |
Due to Ultra using the NUMA architecture, VMs/virtualization will only ever use 8 performance cores at a time.
Common Examples
VM Resources
CPU
> anka modify 14.3.1-arm64 cpu --help
usage: cpu [options] [vcpu]
Set number of vcpu cores and frequency
arguments:
vcpu Number of vcpu cores
options:
-c,--cores <val> Number of vcpu cores
-f,--frequency <val> Set the base vcpu frequency (Hz)
❯ anka show 12.6 cpu
+-------+---+
| cores | 4 |
+-------+---+
❯ anka modify 12.6 cpu 5
❯ anka show 12.6 cpu
+-------+---+
| cores | 5 |
+-------+---+
RAM
> anka modify 14.3.1-arm64 ram --help
usage: ram [size]
Set RAM size and parameters
arguments:
size Size of RAM (supported suffixes: T|G|M|K)
❯ anka show 12.6 ram
+------+------+
| size | 4GiB |
+------+------+
❯ anka modify 12.6 ram 6G
❯ anka show 12.6 ram
+------+------+
| size | 6GiB |
+------+------+
DISK
> anka modify 14.3.1-arm64 disk --help
usage: disk [options]
Modify hard drive settings
options:
-c,--controller <val> set controller: sata/virtio-blk
-s,--size <val> set disk size (supported suffixes: T|G|M|K)
-f,--file <val> assign external image or device
--ro mark the image as read-only for the VM
--rw mark the image as writable (default) for the VM
Post-modify, you need to tell disk utility to modify the VM’s disk to consume the new free space: anka run {vmNameOrUUID} sudo diskutil apfs resizeContainer disk0s2 0It’s currently impossible to downsize a VM’s hard-drive. We suggest creating your initial VM Template with a smaller amount of available disk and then increase in subsequent Tags.
Port forwarding from guest to host
> anka modify 14.3.1-arm64 port --help
usage: port [options] name [rule]
Add port forwarding rule
arguments:
name Rule name
rule Port forwarding rule: guest-port[:host-ip][:host-port]
options:
-g,--guest-port <val> The port inside of the VM that the host-port connects to
-p,--host-port <val> The host port to listen on (assigns dynamically if not specified)
-l,--host-ip <val> Listen address (defaults to any)
-d,--delete Delete the rule
--set-name <val> Rename the rule
We do not recommend setting--host-port, as it will cause collisions if two VMs attempt to use the same port. If no--host-portis specified, we will dynamically assign them starting from 10000 and incrementing (10001, 10002, etc) depending on if there are other VMs running and consuming ports from the range already.
❯ anka modify 12.6 port --help
usage: port [options] name [rule]
Add port forwarding rule
arguments:
name Rule name
rule Port forwarding rule: guest-port[:host-ip][:host-port]
options:
-g,--guest-port <val> The port inside of the VM that the host-port connects to
-p,--host-port <val> The host port to listen on (assigns dynamically if not specified)
-l,--host-ip <val> Listen address (defaults to any)
-d,--delete Delete the rule
--set-name <val> Rename the rule
❯ anka modify 12.6 port ssh 22:0.0.0.0
❯ anka start 12.6
❯ anka show 12.6 network
. . .
port_forwarding_rules:
+------+----------+------------+-----------+
| name | protocol | guest_port | host_port |
+------+----------+------------+-----------+
| ssh | tcp | 22 | 10000 |
+------+----------+------------+-----------+
❯ ssh anka@localhost -p 10000
(anka@localhost) Password:
Last login: Fri Oct 14 06:37:54 2022
anka@Ankas-Virtual-Machine ~ %
Changing your VM’s network configuration
Depending on your network topology, there are instances where you might need to use a bridge mode and assign your VM a unique IP address instead of the default shared IP of the host:
> anka modify 14.3.1-arm64 network --help
usage: network [options]
Modify network card settings
options:
-t,--mode <val> network mode: shared/host/bridge/disconnected
-b,--bridge <val> host interface name to bridge with in the bridge mode, or "auto"
-m,--mac <val> specify fixed MAC address, or "auto"
-v,--vlan <val> assign VLAN ID, 0 to deassign
-c,--controller <val> set controller: anet, virtio-net
-f,--filter <val> filtering rules file to inject on VM start, or embed in VM config (with '-f- < rules.txt'), or use 'off' to disable
| Type | Description |
|---|---|
shared | The default network type operating as NAT + DHCP. Every VM after the start/resume gets an IP address assigned by the internal DHCP server in range 192.168.64.2 - 192.168.64.254. Programs inside a VM can access external networks (outside the host) and the internet directly. Also, other VMs on the host are also accessible. |
host | Not currently supported. |
bridge | The Bridged type will cause the VM to show in the network as an individual device and receive a unique IP separate from the host.An ENV is available to set the interface name: When using the bridge, port-forwarding is not necessary as the VM will receive a unique IP that will be accessible directly to all other devices on the network. By default, DHCP will not see your VM’s MAC address. You’ll need to enable |
disconnected | The VM will have a disconnected network cable. |
nat | Experimental network mode for Apple Silicon/ARM, allowing ~10x the speed compared to the shared mode. Does not support VM to Host isolation or ARP Spoofing prevention. |
❯ anka --machine-readable show 13.1 network | jq '.body'
{
"mode": "shared",
"controller": "virtio-net",
"port_forwarding_rules": [
{
"name": "ssh",
"protocol": "tcp",
"guest_port": 22
}
]
}
❯ anka modify 13.1 network --mode bridge
❯ anka --machine-readable show 13.1 network | jq '.body.mode'
"bridge"
Modify the hardware UUID and Serial with custom-variable (intel only)
At times you might need to modify the hardware serial or UUID to run proper builds/tests that require specific hardware to function properly:
> sudo anka modify 12.3.1 set custom-variable --help
Usage: anka modify set custom-variable [OPTIONS] KEY VALUE
Set custom nvram & smb variables (Example: . . . set custom-variable hw.serial "<SERIAL>"
Options:
--help Display usage information
sudo anka modify {vmNameOrUUID} set custom-variable hw.uuid "GUID"
sudo anka modify {vmNameOrUUID} set custom-variable hw.serial 'MySerial'