Advanced configuration - MacStadium Docs

This page covers advanced configuration topics for production MacStadium VDI environments. These are optional enhancements beyond the initial deployment. You don’t need them to get started, but they unlock performance, scale, and automation capabilities.

Performance optimization

Bridged networking configuration

When using bridged networking, VMs connect directly to your physical network as native devices, receiving their own IP address from your network’s DHCP server. This enables direct communication with other network devices without NAT. Requirements:

A working DHCP server on your network that can assign IPs to VMs
Sufficient IP addresses in your subnet (one per VM)
All existing VMs must be deleted before switching modes
MacStadium VDI running Orka Engine 3.5+

Important limitations:

You cannot run NAT and bridged networking simultaneously
All VMs in your cluster must use the same networking mode
Switching modes requires deleting all VMs first

CVAD (on-prem Citrix) deployments require bridge networking for VDA enrollment. Without it, VMs receive NAT IPs (192.168.64.x) that the Citrix Delivery Controller cannot reach for enrollment, unless custom port-forwarding is configured on the customer side. For Citrix DaaS or Workspace/VDA testing without CVAD, NAT mode is sufficient.

Configuration: Bridged networking is configured in your MacStadium VDI cluster configuration files before deploying VMs. Step 1: Configure cluster-wide bridge mode Edit cluster.yml on your MacStadium VDI management node:

vm_network_mode: bridge

Step 2: Configure host network interface Specify which physical network interface on your Orka hosts connects to your DHCP-enabled network. Option A: Same interface on all hosts. Edit nodes.yml:

osx_node_vm_network_interface: en0 # or vlan0, en1, etc.

Option B: Different interfaces per host. Edit your hosts inventory file:

[arm-nodes]
221.188.30 osx_node_vm_network_interface=vlan0
221.188.31 osx_node_vm_network_interface=vlan1
221.188.32 osx_node_vm_network_interface=en0

To determine the correct interface, SSH to each Orka host and check:

ssh admin@10.221.188.30 "ifconfig | grep -E '^[a-z]|inet '"

Look for the interface with an IP in your corporate network range. Step 3: Delete all existing VMs

You cannot switch networking modes with VMs running. Delete all VMs before proceeding.

ansible-playbook -i inventory list.yml
ansible-playbook -i inventory delete.yml -e "vm_name=<vm-name>"

Run the delete command once for each VM. Step 4: Apply configuration changes

ansible-playbook -i inventory configure-hosts.yml

Step 5: Deploy VMs with bridged networking

ansible-playbook -i inventory deploy.yml -e "vm_name=citrix-vda-finance-01" -e "vm_image=registry.example.com/citrix-vda/sonoma-finance:v2.0"

Step 6: Verify VMs received DHCP addresses

ansible-playbook -i inventory list.yml

VMs should show IP addresses from your corporate network range, not 192.168.64.x. Troubleshooting bridged networking: If VMs have 192.168.64.x addresses instead of corporate IPs, bridge mode isn’t configured correctly:

Verify vm_network_mode: bridge is set in cluster.yml
Verify osx_node_vm_network_interface is set correctly in nodes.yml or hosts
Confirm the interface name is correct: SSH to host and run ifconfig
Rerun host configuration: ansible-playbook -i inventory configure-hosts.yml
Delete and redeploy affected VMs

If VMs can’t reach network services after getting DHCP addresses, verify your DHCP server provides valid gateway and DNS settings:

ssh admin@<vm-ip> "route -n get default"
ssh admin@<vm-ip> "cat /etc/resolv.conf"

For complex bridged networking issues, contact MacStadium Support.

HDX tuning for latency-sensitive workloads

For users editing video, audio, or using graphics-intensive applications who report lag or stuttering: 1. Enable Adaptive Transport (Framehawk) for high-latency connections: Citrix Cloud Console → Policies → Create new policy → HDX Adaptive Transport → set “Adaptive Transport” to “Preferred” → apply to affected Delivery Groups. 2. Adjust visual quality settings: For users on high-bandwidth connections: Policies → Visual Display → Visual Quality → “Build to Lossless” For users on low-bandwidth connections: Policies → Visual Display → Visual Quality → “Medium” 3. Enable GPU acceleration (M4 Macs): M4 Macs support GPU passthrough for VMs. Requirements: Orka 3.5+, macOS 15.5+ on the host, specific VM configuration.

GPU acceleration is not yet automated in the Orka Engine Ansible playbooks. Contact MacStadium support for GPU-enabled VM deployment guidance.

4. Test with Citrix HDX Monitor: Download the Citrix HDX Monitor tool to identify bottlenecks: network latency, bandwidth constraints, and frame rate drops. Use results to fine-tune HDX policies further.

Resource allocation (CPU, memory, storage)

Default VM resources are inherited from the golden image, typically 4 CPU cores, 8 GB RAM, 90 GB storage. To change resources, modify the VM configuration and create a new golden image:

# SSH into the Orka node
ssh admin@10.0.100.10

# Stop the VM
orka-engine vm stop <vm-name>

# Resize (6 CPU cores, 16 GB memory)
orka-engine vm resize <vm-name> --cpu 6 --memory 16

# Start the VM
orka-engine vm start <vm-name>

Then create a new golden image from the resized VM:

ansible-playbook -i inventory create_image.yml -e "vm_image=<resized-vm-name>" -e "remote_image_name=registry.example.com/citrix-vda/sonoma-highspec:v1.0"

Recommended high-spec configuration for power users: 8+ CPU cores, 32 GB RAM, 500 GB storage.

Overprovisioning resources reduces VM density on hosts. Monitor host utilization to ensure you’re not running fewer VMs than capacity allows.

Automation enhancements

Extending Ansible playbooks

The orka-engine-orchestration playbooks provide core functionality. Common extensions include: Automated image update workflow:

# update-golden-image.yml
---
- name: Automated image update workflow
  hosts: localhost
  tasks:
    - name: Deploy test VM
      command: >
        ansible-playbook -i inventory deploy.yml
        -e "vm_name=image-test-01"
        -e "vm_image=[CURRENT_IMAGE]"

    - name: Wait for VM to be ready
      pause:
        minutes: 3

    # Note: OS update installation still requires manual intervention via VNC

    - name: Create new golden image
      command: >
        ansible-playbook -i inventory create_image.yml
        -e "vm_image=[CURRENT_IMAGE]"
        -e "remote_image_name=[NEW_IMAGE]"
        -e "registry_username=[REGISTRY_USER]"
        -e "registry_password=[REGISTRY_PASS]"

    - name: Clean up test VM
      command: >
        ansible-playbook -i inventory delete.yml
        -e "vm_name=image-test-01"

Scheduled capacity scaling:

# Scale up at 7 AM weekdays
0 7 * * 1-5 /path/to/scale-up.sh

# Scale down at 7 PM weekdays
0 19 * * 1-5 /path/to/scale-down.sh

Health check automation:

# health-check.yml
---
- name: VM health check
  hosts: hosts
  tasks:
    - name: Check VMs are running
      shell: orka-engine vm list --format json
      register: vm_list

    - name: Alert if VMs are down
      debug:
        msg: "WARNING: [VM_LIST_STDOUT___FROM_JSON___SELECTATTR'] VMs are not running"
      when: (vm_list.stdout | from_json | selectattr('status', 'ne', 'running') | list | length) > 0

Schedule this every 15 minutes and pipe output to your monitoring system.

Integrating with CI/CD pipelines

Automatically build and deploy updated golden images when application code changes. Example: GitHub Actions workflow:

# .github/workflows/deploy-vdi-image.yml
name: Deploy Updated VDI Image

on:
  push:
    branches: [main]
    paths:
      - 'app/**'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build application
        run: ./build.sh

      - name: Deploy test VM
        run: |
          ansible-playbook -i inventory deploy.yml -e "vm_name=image-test-01" -e "vm_image=registry.example.com/citrix-vda/dev-base:latest"

      - name: Copy application to test VM
        run: scp -r ./dist admin@<vm-ip>:/Applications/YourApp.app

      - name: Run automated tests
        run: ssh admin@<vm-ip> "./run-tests.sh"

      - name: Create new golden image if tests pass
        run: |
          ansible-playbook -i inventory create_image.yml -e "vm_image=image-test-abc123" -e "remote_image_name=registry.example.com/citrix-vda/dev-tools:[GITHUB_SHA]" -e "registry_username=[SECRETS_REGISTRY_USER]" -e "registry_password=[SECRETS_REGISTRY_PASS]"

      - name: Deploy to production
        run: |
          ansible-playbook -i inventory deploy.yml -e "vm_name=citrix-vda-dev-01" -e "vm_image=registry.example.com/citrix-vda/dev-tools:[GITHUB_SHA]"

Scheduled maintenance tasks

Use this schedule as a baseline:

Frequency	Tasks
Daily	Capacity check, VM health check (VMs registered with Citrix)
Weekly	Review capacity trends, check for macOS updates, review user feedback
Monthly	Image security patches, Citrix policy review, backup verification
Quarterly	Major application updates, Citrix VDA updates, DR test, host hardware maintenance

Multi-tenant considerations

Isolation strategies

Option 1: Delivery Group separation Deploy all VMs from shared infrastructure. Separate users into different Citrix Delivery Groups with different policies per group. Simple and resource-efficient, but teams share hardware and one team’s resource spike affects others. Option 2: VM group separation Deploy separate VM groups per tenant (citrix-vda-finance, citrix-vda-engineering), each with its own golden image. Groups still share Orka hosts. Option 3: Host-level separation Allocate specific Orka hosts to specific tenants:

[finance_hosts]
mac-node-1 ansible_host=10.0.100.10
mac-node-2 ansible_host=10.0.100.11

[engineering_hosts]
mac-node-3 ansible_host=10.0.100.12
mac-node-4 ansible_host=10.0.100.13

Deploy tenant VMs only to their assigned hosts:

ansible-playbook -i inventory deploy.yml -e "vm_name=citrix-vda-finance-01" -e "vm_image=registry.example.com/citrix-vda/sonoma-finance:latest" --limit finance_hosts

Complete resource isolation with no noisy-neighbor problems, but reduced flexibility and potential underutilization.

Chargeback and cost allocation

Track resources per tenant:

# Count finance VMs
ansible-playbook -i inventory list.yml | grep citrix-vda-finance | wc -l

# Count engineering VMs
ansible-playbook -i inventory list.yml | grep citrix-vda-engineering | wc -l

Calculate per-VM cost: divide host cost (hardware + MacStadium hosting) by VMs per host, then multiply by VM count per tenant.

Tenant-specific policies

Apply different Citrix policies per tenant:

Create separate Delivery Groups per tenant
Create policies with appropriate settings per tenant (for example, Finance: no clipboard, no file transfer; Engineering: full access)
Filter policies by Delivery Group name

Each tenant gets appropriate controls without affecting others.

​Performance optimization

​Bridged networking configuration

​HDX tuning for latency-sensitive workloads

​Resource allocation (CPU, memory, storage)

​Automation enhancements

​Extending Ansible playbooks

​Integrating with CI/CD pipelines

​Scheduled maintenance tasks

​Multi-tenant considerations

​Isolation strategies

​Chargeback and cost allocation

​Tenant-specific policies

Performance optimization

Bridged networking configuration

HDX tuning for latency-sensitive workloads

Resource allocation (CPU, memory, storage)

Automation enhancements

Extending Ansible playbooks

Integrating with CI/CD pipelines

Scheduled maintenance tasks

Multi-tenant considerations

Isolation strategies

Chargeback and cost allocation

Tenant-specific policies