Accessing your VM

Various ways to access your VM

Prerequisites

  1. You’ve installed the Anka Virtualization package.
  2. You’ve created and prepared your first VM Template.

Defaults and Expectations

  • Inside of the VMs created with anka create, you will find Screen Sharing and Remote Login enabled automatically. In shared networking mode (the default), it allows you to access SSH and VNC using the VM’s IP directly from the host running the VM. To access the VM VNC and SSH outside of the host, you’ll need to forward the ports from the VM to the host or enable bridge networking mode to get an IP from DHCP in your network.
  • Anka Addons are installed into your VM and support anka run.
  • With anka view, the clipboard is not supported. We currently recommend VNC instead.

Anka Run

Requires addons are installed inside of the VM. You can check if they are installed with the anka show {vmName} command.

With anka run, you can execute commands inside of a VM.

> anka run --help
usage: run [options] vmid

   Run a command inside of a VM

arguments:
  vmid                     VM name or identifier (will be started if needed)

options:
  -D,-w,--workdir <val>    Working directory inside the VM
  -E                       Inherit the entire environment in non-overriding mode
  -e <val>                 Provide an environment variable in overriding mode
  -f,--env-file <val>      Provide environment variables from file
  -q,--quiet               Suppress the stdout from the command
  -b,--background          Background the command inside of VM, returning inner VM PID
If the VM is in a stopped state, anka run will automatically start it.

For example you can use anka run on the host terminal to validate networking inside of the VM:

❯ anka run 12.6 bash -c "hostname && ls -l && ping -c 5 google.com"
12-2-0-arm.local
total 0
drwx------+  3 anka  staff    96 Oct 14 09:35 Desktop
drwx------+  3 anka  staff    96 Oct 14 09:35 Documents
drwx------+  3 anka  staff    96 Oct 14 09:35 Downloads
drwx------@ 74 anka  staff  2368 Oct 19 11:31 Library
drwx------   4 anka  staff   128 Oct 19 11:14 Movies
drwx------+  3 anka  staff    96 Oct 14 09:35 Music
drwx------+  3 anka  staff    96 Oct 14 09:35 Pictures
drwxr-xr-x+  4 anka  staff   128 Oct 14 09:35 Public
PING google.com (142.251.35.174): 56 data bytes
64 bytes from 142.251.35.174: icmp_seq=0 ttl=108 time=10.316 ms
64 bytes from 142.251.35.174: icmp_seq=1 ttl=108 time=10.270 ms
64 bytes from 142.251.35.174: icmp_seq=2 ttl=108 time=10.163 ms
64 bytes from 142.251.35.174: icmp_seq=3 ttl=108 time=10.305 ms
64 bytes from 142.251.35.174: icmp_seq=4 ttl=108 time=10.281 ms

--- google.com ping statistics ---
5 packets transmitted, 5 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 10.163/10.267/10.316/0.055 ms
(SIP enabled users) You may see the anka run command hang when using, for example, find. Opening the Anka Viewer or VNCing in will show a user approval dialog box saying “ankarund would like access to” a certain path on the VM. This is due to new security policies Apple is enforcing by default. This is obviously a problem for automation, but, fortunately, there is a solution. You’ll need to either avoid using commands that recursively look at the file system locations, or, place the files you wish to find under a “resource” folder under /Users/anka. Executing find inside of the folder will not trigger the approval dialog box.

Shell Configuration Files / Environment

The anka run command uses the “default shell” that Apple’s API provides inside of macOS. It will NOT source any configuration by default. However, you can use bash and zsh command with anka run to source them:

❯ anka run "${VM_NAME}" bash -c "echo 'export TEST_ZSHRC=yes' >> ~/.zshrc"
anka run "${VM_NAME}" bash -c "echo 'export TEST_ZPROFILE=yes' >> ~/.zprofile"
anka run "${VM_NAME}" bash -c "echo 'export TEST_PROFILE=yes' >> ~/.profile"
anka run "${VM_NAME}" bash -c "echo 'export TEST_BASH_PROFILE=yes' >> ~/.bash_profile"

❯ anka run "${VM_NAME}" env
XPC_SERVICE_NAME=com.veertu.anka.addons.ankarun
SSH_AUTH_SOCK=/private/tmp/com.apple.launchd.y6GCwIr092/Listeners
PATH=/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin
XPC_FLAGS=0x0
LOGNAME=anka
USER=anka
HOME=/Users/anka
SHELL=/bin/bash
TMPDIR=/var/folders/01/58yvsx8s4f79plzlx2_rcvp40000gn/T/
__CF_USER_TEXT_ENCODING=0x1F5:0x0:0x0
SHLVL=1

❯ anka run "${VM_NAME}" bash -c "env | grep TEST_"

❯ anka run "${VM_NAME}" bash -ic "env | grep TEST_"

❯ anka run "${VM_NAME}" bash -lc "env | grep TEST_"
TEST_BASH_PROFILE=yes

❯ anka run "${VM_NAME}" zsh -c "env | grep TEST_"

❯ anka run "${VM_NAME}" zsh -ic "env | grep TEST_"
TEST_ZSHRC=yes

❯ anka run "${VM_NAME}" zsh -lc "env | grep TEST_"
TEST_ZPROFILE=yes

❯ anka stop "${VM_NAME}"

❯ anka run "${VM_NAME}" bash -c "env | grep TEST_"
TEST_ZPROFILE=yes

❯ anka run "${VM_NAME}" bash -ic "env | grep TEST_"
TEST_ZPROFILE=yes

❯ anka run "${VM_NAME}" bash -lc "env | grep TEST_"
TEST_ZPROFILE=yes
TEST_BASH_PROFILE=yes

❯ anka run "${VM_NAME}" zsh -c "env | grep TEST_"
TEST_ZPROFILE=yes

❯ anka run "${VM_NAME}" zsh -ic "env | grep TEST_"
TEST_ZPROFILE=yes
TEST_ZSHRC=yes

❯ anka run "${VM_NAME}" zsh -lc "env | grep TEST_"
TEST_ZPROFILE=yes
To inherit the host’s environment, use the anka run -E (existing VM variables will not be overridden by host’s variables) or -e MYENV options. You can also pass them inside of a file like anka run --env-file environment.txt, where environment.txt is a text file in the form VARIABLE=VALUE, one variable per line.
Some advanced usage examples of anka run inside of a bash script can be found in our Getting Started repo’s VM Tag creation script.

SSH

By default, SSH is enabled inside of the VM. You can SSH into the VM using the VM’s IP and port 22:

❯ anka show 14.2.1 network
+------------+-------------------+
| mode       | shared            |
+------------+-------------------+
| controller | virtio-net        |
+------------+-------------------+
| ip         | 192.168.64.6      |
+------------+-------------------+
| mac        | ae:86:1c:97:a5:8a |
+------------+-------------------+

❯ ssh anka@$(anka show 14.2.1 network ip)
(anka@192.168.64.6) Password:
Last login: Fri Oct 14 04:25:21 2022
anka@Ankas-Virtual-Machine ~ %

You can also port forward the guest port onto the host so it’s accessible from the host IP:

We do not recommend setting --host-port, as it will cause collisions if two VMs attempt to use the same port. If no --host-port is 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 ~ %

VNC

By default, we enable VNC inside of VMs created with anka create. You can VNC into the VM using the VM’s IP and port 5900:

❯ anka show 12.6 network
+------------+-------------------+
| mode       | shared            |
+------------+-------------------+
| controller | virtio-net        |
+------------+-------------------+
| ip         | 192.168.64.6      |
+------------+-------------------+
| mac        | ae:86:1c:97:a5:8a |
+------------+-------------------+

❯ open vnc://192.168.64.6:5900
To expose the VM VNC port on the Host IP, read more about port forwarding here. You will need to create a rule named vnc with guest port 5900. This is especially important for displaying the VNC url in the Anka Build Cloud Controller’s Instances page.

Anka View

ARM USERS: We recommend using VNC over anka start -v or anka view commands. By default, VMs Anka VMS come with VNC enabled and it’s far more flexible.

Known Issues with anka view

  • Chrome, Edge, and any other GPU accelerated browser will not function due to limitations in Apple’s hypervisor. You would need to launch the browsers without GPU acceleration. For example, with Chrome: /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --disable-gpu.
  • ARM USERS: anka view will not work unless you first started the VM with anka start -v. We enable VNC for the VM by default and recommend this approach instead.

With the CLI

The anka viewer requires an active UI session on the host (VNC is fine).
> anka view --help
usage: view [options] vmid

   Open VM display

arguments:
  vmid                     VM to view

options:
  -d,--display <val>       Specify the display(s) to view
  -s,--screenshot          Take PNG screenshot
  --pbpaste                Get the VM's pasteboard
  --pbcopy                 Send stdin to the VM's pasteboard
  --click <val>            Send HID events
  -o,--output <val>        Specify output file for the view operations

With the App

Instead of launching the viewer with the CLI, you can open the Anka.app under /Applications and then double click on the VM in the list. This will launch the viewer window. This is will NOT work when running VMs under the root user.

Answers to Frequently Asked Questions

  • anka run doesn’t support TTY mode, but you could easily use POSIX streams as with regular bash tool:

    ❯ anka run VNMANE whoami > /dev/null

❯ cat file-on-host.txt | anka run 12.6 md5
ff1a596f13d348b63218078c6598ab5e

  • You can access macOS’ Recovery Mode through the Anka.app menu or with ANKA_START_MODE=2 anka start 12.6.

    recovery-mode

  • Inside of your VM, you can obtain host level details about the VM using nc -U /var/run/anka. You can also set ENVs prefixed with ANKA_HOST_PARAM_ to make them available inside.

    ❯ anka stop 14.3.1-arm64
❯ export ANKA_HOST_PARAM_TEST=123
❯ anka run 14.3.1-arm64 bash -c "nc -U /var/run/anka"
uuid: d792c6f6-198c-470f-9526-9c998efe7ab4
license: com.veertu.anka.entplus,h:255
name: 14.3.1-arm64
TEST: 123
version: 3.3.9

What’s next?