Anka Flow

Installation and Configuration

Anka when activated with the Anka Flow license enables installation of Anka package on the developer mac machines. It enables the developers to create and work inside Anka macOS VMs on their local machines. Developers can use the anka run interface to work inside Anka Vms in a container like manner.

You can also use Anka Flow in combination with Anka Build and enable your developers to pull the build environments from the central registry on their local machines.

Install

Install Anka package on the mac developer machine. Note Anka Flow is only supported on macbook models and iMac.

Installing the Anka Hypervisor binary is remarkably simple, just download it from Anka Flow Download page.
Run the anka.pkg installer. The Anka package includes the Core hypervisor and anka guest Add-ons.

Note In order to create VMs with nested feature enabled, select nested virtualization checkbox in Customizations while installing Anka through the GUI method.
If using command line, use the following command sudo installer -applyChoiceChangesXML nanka.xml -pkg Ankaxx.pkg -target /.

After running the installer package, anka is found at /usr/local/bin/anka.

Verify the installation by running anka version command.

After install, if the users want to, they can change the location of this default Anka install location link manually.

Execute sudo mv /usr/local/bin/anka /to/any/other/location/.

Verify the installation by running anka version command.

View all settings for Anka installation on the host with anka config -l command.

anka config --help
Usage: anka config [OPTIONS] [PARAM]...

  Manage Anka configuration

Options:
  -l, --list   List value parameter(s)
  -r, --reset  Reset value of parameter(s)
  --help       Show this message and exit.

Activate with your Anka Flow license key.

sudo anka license activate <key>

Upgrading the Anka Package

  1. Download the latest version of Anka package (.pkg) and stop all running VMs.
  2. Before upgrading, you will also need to force stop any suspended VMs with the anka stop -f vmname command.

Note For major Anka releases, it maybe required to upgrade guest addons in existing Anka VMs. Check the release notes to identify if this step is required or not.

  1. Upgrade guest addons on the VM. Execute the following command to upgrade guest addons in existing VMs to the current release.
anka stop -f vmname
anka start -u vmname
Preparing update configuration
Installing updates
Suspending
update succeeded

If you are not able to upgrade the guest add-ons tool using the anka start -u vmname command, then you have a very old version of guest addon tools on your VM. You will first need to manually update them. Contact Veertu support. 4. Push your upgraded VMs to the Registry.

Uninstall

From the command line, execute the following command. Make sure all your VMs are stopped.

sudo /Library/Application\ Support/Veertu/Anka/tools/uninstall.sh

Create VM

Anka makes it very simple manage your macOS CI infrastructure-as-a-code.

Use anka create command to create macOS VMs from the .app installer app. anka create --ram-size 4G --cpu-count 2 --disk-size 80G --app /Applications/Install\ macOS\ High\ Sierra.app Hisierravm

Note For Catalina Anka VMs, --ram-size value should be 4G and --disk-size should be 80G.

By default anka create creates macOS VM with administrative user - anka and password - admin. You can change this default user by using these ENV variables with anka create command.

ANKA_DEFAULT_PASSWD=passwd ANKA_DEFAULT_USER=usrname anka create --ram-size 4G --cpu-count 2 --disk-size 60G -a /Applications/Install\ macOS\ High\ Sierra.app HiSierravm

anka create --help
Usage: anka create [OPTIONS] VMNAME

  Creates a VM

Options:
  -m, --ram-size TEXT      ram size in G  [default: 4G]
  -c, --cpu-count INTEGER  the number of cpu cores  [default: 2]
  -d, --disk-size TEXT     sets the disk size when creating a new disk, G/M suffix needed  [default: 80G]
  -a, --app PATH           Path to Install macOS Application (downloadable from AppStore)
  -p, --pkg PATH           Additional package to be installed
  -s, --postinstall PATH   Postinstall scripts (to run with root credentials at first boot)
  -P, --profile PATH       Install configuration profile(s) alongside macOS installation
  --interactive            Perform default interactive installation instead of the automated one
  --help                   Show this message and exit.

Note - anka create supports macOS manual setup. Use the --interactive flag. Note - While creating VM with anka create, make sure to specify enough --disk-size.

anka create --ram-size 4G --cpu-count 2 --disk-size 80G --app /Applications/Install\ macOS\ High\ Sierra.app build73sierra
Installing macOS 10.13...
Preparing target disk...
Copying addons...
Converting to ANKA format...
Waiting for installation to complete in the guest (about thirty minutes approx.)...
vm created successfully with uuid: 8f0e1111-a14b-11e7-aaa4-003ee1cbb8b4

The output of anka create command is a VM created and it’s in suspended state. anka start from suspended state bypasses the full boot and starts the Vm in 1-2 seconds.

Note VMs are created with SIP/Kext Consent disabled by default. It’s strongly advised to keep these settings for optimal Anka performance.

If you need to re-enable SIP/Kext Consent, then use this command anka modify VMNAME set custom-variable sys.csr-active-config 0.

Note VMs created are in suspended mode to enable fast boot/Instant Start.

Run VM

The VM can now be successfully started. The VM is preconfigured with a default administrative username anka and password admin. You will see the VM boot up and have to complete the macOS keypad setup steps.

anka start 133b387
+-----------------------+--------------------------------------+
| uuid                  | 49b35a9c-1659-11e8-a71d-003ee1cde439 |
+-----------------------+--------------------------------------+
| name                  | 133b387 (20rel)                      |
+-----------------------+--------------------------------------+
| description           | nineteen                             |
+-----------------------+--------------------------------------+
| created               | Jul 01 07:24                         |
+-----------------------+--------------------------------------+
| cpu_cores             | 4                                    |
+-----------------------+--------------------------------------+
| ram                   | 8G                                   |
+-----------------------+--------------------------------------+
| display               | 1                                    |
+-----------------------+--------------------------------------+
| hard_drive            | 40Gi (43.8Gi on disk)                |
+-----------------------+--------------------------------------+
| addons_version        | 2.0.0.107 (update recommended)       |
+-----------------------+--------------------------------------+
| status                | running                              |
+-----------------------+--------------------------------------+
| vnc_connection_string | vnc://:admin@xxx.xxx.xx.xxx:5901     |
+-----------------------+--------------------------------------+

Validate by running the following command anka run VMNAME ls -l from the host. It should display ls -l contents of the host current directory. The VM is correctly created. You can manually work within the VM with anka view sierravm. This will open the VM window.

Do anka show vmname to view IP and other runtime details of the VM.

anka show 133b387
+-----------------------+--------------------------------------+
| uuid                  | 49b35a9c-1659-11e8-a71d-003ee1cde439 |
+-----------------------+--------------------------------------+
| name                  | 133b387 (20rel)                      |
+-----------------------+--------------------------------------+
| description           | nineteen                             |
+-----------------------+--------------------------------------+
| created               | Jul 01 07:24                         |
+-----------------------+--------------------------------------+
| cpu_cores             | 4                                    |
+-----------------------+--------------------------------------+
| ram                   | 8G                                   |
+-----------------------+--------------------------------------+
| display               | 1                                    |
+-----------------------+--------------------------------------+
| hard_drive            | 40Gi (44.1Gi on disk)                |
+-----------------------+--------------------------------------+
| addons_version        | 2.0.0.107 (update recommended)       |
+-----------------------+--------------------------------------+
| status                | running                              |
+-----------------------+--------------------------------------+
| ip                    | 192.168.64.38                        |
+-----------------------+--------------------------------------+
| vnc_connection_string | vnc://:admin@xxx.xxx.xx.xxx:5901     |
+-----------------------+--------------------------------------+

port_forwarding

+--------------+------------+---------+-------------+-------------+-----------+
|   guest_port | protocol   | name    |   host_port |   time_sync | host_ip   |
+==============+============+=========+=============+=============+===========+
|           22 | tcp        | jenkins |       10000 |           0 | 0.0.0.0   |
+--------------+------------+---------+-------------+-------------+-----------+

Upgrading macOS VM inside Anka VM

Note Don’t use the System Preference installer to update macOS inside Anka VM. Use the softwareupdate -Ri command line tool to upgrade macOS inside Anka VM. Stop the Vm and then restart it.

Work inside the VM

There are multiple methods to install various software packages and work inside the VM.

Manual method

You can manually work within the VM with anka view sierravm. This will open the VM view window. anka view supports working in full screen and also retina mode. Retina mode is supported for Anka Vms running Mojave or later.

Automated methods

SSH to the VM and execute commands

SSH into the VM from the host where its running with the following command. ssh anka@ip, where ip is the Vm IP shown in anka show vmname command.

To SSH into the VM from another host, first enable ssh port forwarding. Use anka modify command.

anka modify vmname add port-forwarding --host-port 0 --guest-port 22 ssh
rule added successfully

When the port forwarding rule is successfully added, you will see the following in the anka show vmname output.

port_forwarding

+--------------+------------+---------+-------------+-------------+-----------+
|   guest_port | protocol   | name    |   host_port |   time_sync | host_ip   |
+==============+============+=========+=============+=============+===========+
|           22 | tcp        | ssh     |       10000 |           1 | 0.0.0.0   |
+--------------+------------+---------+-------------+-------------+-----------+

Access it with ssh anka@hotsip -p host_port

Use anka run and execute commands Anka command line contains anka run command (similar to docker run) to execute commands inside the VM directly from the host.

Example

anka run -n -N vmname ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
anka run -n vmname sudo gem install xcode-install

#saving user/pass of app store
echo FASTLANE_USER=user >> appstore_login
echo FASTLANE_PASSWORD=password >> appstore_passwd

anka run -f appstore_login -nE vmname xcversion install 10.1

Refer here for more details on how to use anka run command.

Using an ISO file to create Anka VM - Yosemite & ElCapitan VMs

Use create_macos_install_image.sh included in the Anka package to first create an .iso from your Yosemite and ElCapitan .app installer. If you already have .iso file, you don’t need to execute this step.

/Library/Application\ Support/Veertu/Anka/tools/create_macos_install_image.sh
Usage: create_macos_install_image.sh install_macos.app [OPTIONS]...

Options:
--g,--guest-addons       Embed Anka guest addons in the installer
--o,--output output.iso       Specify output image file, if not specified the image will be created in working directory                  
--p,--pkg path/to/pkg Specify additional packages to include into the installer

For example:

/Library/Application\ Support/Veertu/Anka/tools/create_macos_install_image.sh /Applications/Install\ macOS\ Sierra.app

To create a VM from .iso, you will use anka create command as you typically would. It will create an empty VM. Note - > While creating VM with anka create, make sure to specify enough --disk-size parameter. Currently, it’s not possible to change the disk size for an existing VM.

anka create --ram-size 2G --cpu-count 2 --disk-size 60G sierravm
vm created successfully with uuid: dfaa97c5-2154-11e8-881d-acbc32ad1d59

Then, start the VM with the sierra ISO attached.

anka start -v -o sierra.iso sierravm
+-----------------------+--------------------------------------+
| uuid                  | dfaa97c5-2154-11e8-881d-acbc32ad1d59 |
| name                  | sierravm                             |
| cpu_cores             | 2                                    |
| ram                   | 2G                                   |
| hard_drive            | 60 GB (11.2 MB on disk)              |
| addons_version        | not found                            |
| status                | running                              |
| vnc_connection_string | vnc://:admin@10.0.1.12:5900          |
| view_vm_display       | anka view sierravm                   |
+-----------------------+--------------------------------------+

Complete the macOS setup inside the VM. Then, stop the VM.

Start the VM again with guest addons ISO installed.

anka start -v -o /Library/Application\ Support/Veertu/Anka/guestaddons/anka-addons-mac.iso sierravm

Complete the guest addons installation inside the VM. Shutdown the VM with anka stop VMNAME.

Validate by running the following command anka run VMNAME ls -l from the host. It should display ls -l contents of the VM. The VM is correctly created.

Anka Guest Add-ons also create a default user - anka, passwd - admin for the VM.

Anka CLI Operations

Anka package provides an complete set of CLI interface to manage macOS infrastructure as a cloud for CI purposes.

Execute anka help to see a complete list CLI commands available.

anka --help
Usage: anka [OPTIONS] COMMAND [ARGS]...

Options:
  --machine-readable              JSON output format
  --log-level [debug|info|error]
  --debug
  -l, --login TEXT                Specify the vm policy user (if configured)
  --help                          Show this message and exit.

Commands:
  clone     Clones a VM
  config    Manage Anka configuration
  create    Creates a VM
  delete    Deletes a VM (or list of vms)
  describe  Shows VM configuration
  license   licensing commands
  list      List VM library contents
  modify    Modifies a VM settings
  mount     Mounts local folder into VM
  reboot    Restarts a VM(s)
  registry  VMs registry
  run       Run commands inside VM environment
  show      Shows VM runtime properties
  start     Starts or resumes paused VM
  stop      Shuts down a vm
  suspend   Suspends a VM(s)
  unmount   Unmount shared folder (filesystem...
  usb       Do actions on USB devices
  version   prints out version
  view      Open VM display viewer

machine readable output from Anka CLI Commands - Use --machine-readable flag. Example anka --machine-readable clone VMname Vmname2.

Debugging Anka CLI Commands - Use --debug flag. Example anka --debug clone VMname Vmname2.

Create VM - Use anka create command. Go to Create VM section.

Clone VM - Use anka clone command. -c flag consolidates/shrinks all the snapshots and creates an independent copy.

anka clone --help
Usage: anka clone [OPTIONS] VM_ID NEW_VM_NAME

  Clones a VM

Options:
  -c, --copy  Create independent copy instead of clone
  --help      Show this message and exit.

Manage VM configuration - Use anka config command to manage VM configuration.

anka config --help
Usage: anka config [OPTIONS] [PARAM]...

  Manage Anka configuration

Options:
  -l, --list   List value parameter(s)
  -r, --reset  Reset value of parameter(s)
  --help       Show this message and exit.

Delete VM - Use anka delete command to delete one, multiple or all VMs in the local VM directory.

anka delete [OPTIONS] [VMID]...

  Deletes a VM (or list of vms)

Options:
  --yes      flag. don't ask - just delete
  -a, --all  Delete all vms in library
  --help     Show this message and exit.

Show VM configuration - Use anka describe command to view Vm configuration.

anka describe --help
Usage: anka describe [OPTIONS] VM_ID

  Shows VM configuration

Options:
  --help  Show this message and exit.

Manage anka license - Use anka license command to activate, remove and execute other licesing related operations for the host.

anka license --help
Usage: anka license [OPTIONS] COMMAND [ARGS]...

  licensing commands

Options:
  --help  Show this message and exit.

Commands:
  accept-eula  accept EULA (root privileges)
  activate     activate license key (root privileges)
  remove       removes the current license (root privileges)
  show         show license information
  validate     validates the current license

list of all VMs - Use anka list command to view all the VMs available in the local VM directory with their status and other properties.

anka list --help
Usage: anka list [OPTIONS] [VMID]...

  List VM library contents

Options:
  -r, --running  show only running vms
  -s, --stopped  show only stopped vms
  --help         Show this message and exit.

Modify VM properties - Use anka modify command to change VM properties like port-forwarding, vCPU, ram, etc. You can set, add and delete properties.

SET Operations

anka modify vmname/ID set --help
Usage: anka modify set [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  cpu              set number of cpu cores and frequency
  custom-variable  configure variables
  description      set textual description of the VM
  display          configure displays
  hard-drive       modify hard drive settings
  name             set new name for the VM
  nested           enable nested virtualization
  network-card     modify network card settings
  policy           Enable VM access management (available in Anka Secure license)
  ram              set RAM size and parameters

Change the disk space on an existing VM with anka modify vmname set hard-drive 0 <disk size> command and then execute anka run -n VM diskutil apfs resizeContainer disk0s2 <disk size>.

Changing hardware properties for a VM

Use anka modify set custom-variable command. You can set the following custom varibales.

  • boot-args - control the corresponding NVRAM variable
  • hw.uuid - specifies the Hardware UUID
  • hw.serial - specifies the Serial Number (system)
  • hw.manufacturer - SMBIOS parameter (Reserved)
  • hw.product - SMBIOS parameter (Reserved)
  • hw.family - SMBIOS parameter (Reserved)
  • hw.board - SMBIOS parameter (Reserved)
anka modify VM set custom-variable hw.UUID "GUID"
anka modify VM set custom-variable hw.serial 'MySerial'

ADD Operations

sudo anka modify vmname/ID add --help
Usage: anka modify add [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  hard-drive
  network-card
  optical-drive
  port-forwarding
  usb-device (available in enterprise and enterprise plus tiers)

Anka also supports bridge networking configuration for the VMs. The default is shared (VMNet based).

anka modify vmname/ID add network-card --help
Usage: anka modify add network-card [OPTIONS]

Options:
  -t, --type [shared|host|bridge|disconnected]
                                  [default: shared]
  -b, --bridge TEXT
  -m, --mac TEXT
  --help                          Show this message and exit.

DELETE Operations

sudo anka modify vmname/ID delete --help
Usage: anka modify delete [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  custom-variable
  hard-drive
  network-card
  optical-drive
  policy
  port-forwarding
  usb-device (available in enterprise and enterprise plus tiers)

Mount local file system into the VM - Use the anka mount command to mount current local folder from the host inside the VM. Returns 231 on timeout.

anka mount --help
Usage: anka mount [OPTIONS] VM_NAME [DIRS]...

  Mounts local folder into VM

Options:
  --help  Show this message and exit.

Unmount mounted folder - Use the anka unmount to Unmount the locally folder mounting. Returns 231 on timeout.

anka unmount --help
Usage: anka unmount [OPTIONS] VMID [DIR]...

  Unmount shared folder (filesystem pass-through)

Options:
  -a, --all  unmount all mounted folders
  --help     Show this message and exit.

Reboot VM - Use the anka reboot to reboot one, multiple or all Vms in the VM local directory.

anka reboot --help
Usage: anka reboot [OPTIONS] [VMID]...

  Restarts a VM(s)

Options:
  -f, --force  flag. restarts the vm process
  -a, --all    reboot all running vms
  --help       Show this message and exit.

Work with registry - Use the anka registry command for access, push, pull Vms from the registry. See the Manage VM Templates in Registry Manage VM Templates in Registry documentation.

Start VM - Use the anka start coammnd to start VM. use the -u flag to update the guest addons inside the VM. This maybe be required for upgrading Vms for major Anka releases.

anka start --help
Usage: anka start [OPTIONS] VM_ID

  Starts or resumes paused VM

Options:
  -u, --update-addons, --update  Run guest addons update procedure, previous version of the addons should be already
                                 installed
  -f, --force                    Start VM with minimum checks
  -v, --view                     Open display window
  -o, --optical-drive TEXT       Path to ISO file or device
  -d, --usb TEXT                 USB device ID/Location (should be claimed)
  --help                         Show this message and exit.

Stop VM - Use the anka stop command to stop VM.

anka stop --help
Usage: anka stop [OPTIONS] [VMID]...

  Shuts down a vm

Options:
  -f, --force  force the vm process to shut down
  -a, --all    Shutdown all running vms
  --help       Show this message and exit.

Suspend VM - Use anka suspend command to put Vm in Instant Boot state. It’s recommended to suspend VMs before pushing them to the Registry for use in CI.

anka suspend --help
Usage: anka suspend [OPTIONS] [VMID]...

  Suspends a VM(s)

Options:
  -a, --all  suspend all running vms
  --help     Show this message and exit.

Open Vm Window/viewer - Use anka view command to open running VM window. anka viewer supports Retina support for Mojave VMs.

anka view --help
Usage: anka view [OPTIONS] VM_ID

  Open VM display viewer

Options:
  -d, --display INTEGER  Specify the displays to view
  -s, --screenshot       Make png screenshot
  --help                 Show this message and exit.

View Anka version - Use anka version command to view current anka version.

anka version
Anka Build Enterprise version 2.0 (build 108)

Show running VM properties - Use anka show command to view VM properties of running VM.

anka show --help
Usage: anka show [OPTIONS] VM_ID [PROPERTY]...

  Shows VM runtime properties

Options:
  --help  Show this message and exit.

Attach and Detach USB devices to VM - Use anka USB device to attach and work with USB devices inside the VM. The USb devices should be connected to the host. See working with real devices documentation.

Execute operation inside Vm from the host with RUN - Use anka run coammnd, similar to docker run to execute operation inside the Vm from the host where it’s running. Returns 125 on timeout.

anka run --help
Usage: anka run [OPTIONS] VM_NAME COMMAND [ARGS]...

  Run commands inside VM environment

Options:
  -w, --workdir PATH              Working directory inside the VM
  -v, --volumes-from, --volume PATH
                                  Mount host directory (current directory by default) into VM . '--volumes-from' is
                                  deprecated form
  -n, --no-volumes-from, --no-volume
                                  Use this flag to prevent implicit mounting of current folder (see --volume
                                  option). '--no-volumes-from' is deprecated form
  -E, -e, --env                   Inherit environment variables. '-e' is deprecated form
  -f, --env-file PATH             Provide environment variables from file
  -N, --wait-network              Wait till guest network interface up
  -T, --wait-time                 Wait for guest time sync
  --help                          Show this message and exit.

Examples of anka run usage

anka run sierrav40c1 xcodebuild -sdk iphonesimulator -scheme Kickstarter-iOS build will mount the default directory from the host into the sierrav40c1 Vm and execute build.

anka run -w /Applications VMNAME ls -l will pipe the results of ls -l from the VM’s /Applications directory.

anka run -v . VMNAME ls will mount the host current directory inside the VM, execute ls, pipe the results and unmount.

anka run -v . VMNAME xcodebuild ... will mount the current directory from the developer machine(host) to the VM and execute an xcodebuild command and pipe the results back.

anka run sudo ... executes commands inside the VM with sudo privileges. For instance:

anka run VMNAME cp -R simpledir /Users/anka will copy the current host directory to the VM at /Users/anka location

anka run -n sierrav40c1 xcodebuild -sdk iphonesimulator -scheme Kickstarter-iOS build will not mount the curent host directory and execute build in the VM current directory

$ anka run VMNAME sudo whoami
root

It’s also possible to explicitly specify mount directory inside VM, using this syntax -v /host/forlder:/mnt/path, e.g:

anka run -v $PWD:/tmp/mountpoint_1 VMNAME pwd

Currently only single volume could be specified in the run command. If you need more than one folder shared between host and the VM, please use anka mount/unmount commands.

anka mount VMNAME ~/Library/MobileDevice/Provisioning\ Profiles/ /Users/anka/Library/MobileDevice/Provisioning\ Profiles/
anka run VMNAME xcodebuild -exportOptionsPlist exportInfo.plist archive

Please note, VM should be running for mount command. If you need more configuration changes to the VM, before anka run execution, you could start the VM with corresponding parameters, or write the parameters to VM configuration with anka modify command.

Working with environment variables using anka run

anka run command doesn’t use .profile, .bash_profile by itself. To configure the environment variables, you can pass it with anka run -f environment.txt, where environment.txt is a text file in the form VARIABLE=VALUE, one variable per line.

To inherit entire host’s environment, use anka run -E command, but in this case existing guests variables will not be overridden by host’s variables.

In order to use environment variables from VMs .bash_profile, execute the following command via intermediate bash.

anka run ios-temp bash -c 'source ~/.bash_profile; ./iPhone/make_build -b dev -c 1 -d ./build -e Mobile -z'

Few things to note

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

anka run -n VNMANE whoami > /dev/null

cat file.txt | anka run -n VMNAME md5

anka run, when run in default mode with no flags, mounts the current folder from the host into the VM and executes commands on this mount point as current directory.

Accessing the host from within Anka VM

The host from Anka VM has fixed IP address of 192.168.64.1 (or 192.168.128.1 in host-only mode).