Skip to main content
Citrix DaaS connects Orka infrastructure with end users. Configuration involves establishing Machine Catalogs to organize macOS VMs, generating enrollment tokens to authenticate VDA registration, and defining Delivery Groups that govern user access and desktop assignment policies within a Citrix Workspace. Before beginning to configure your Citrix DaaS, ensure you have met the following prerequisites:
  • You have an active Citrix DaaS or CVAD subscription (Standard tier or above)
  • Administrative access to Citrix Cloud Console (https://citrix.cloud.com)
  • Your Citrix Cloud Customer ID (visible in the Cloud Console)
  • Completed the environment preparation steps above (Set up an Ansible runner, SSH keys, and network configuration)
  • You have at least one Orka host ready to deploy VMs

​
Create a Machine Catalog

Machine Catalogs are logical groupings of virtual machines in Citrix. When using Orka for VDI, you’ll create a catalog specifically for your macOS desktops. With Orka for VDI, you’ll use the Remote PC Access catalog type since Citrix treats each Mac as a physical device due to Apple’s licensing requirements. Creating the Machine Catalog:
  1. Navigate to Citrix Cloud Console → Web Studio → Machine Catalogs
  2. Click “Create Machine Catalog”
  3. Select catalog type:
    • Choose “Remote PC Access”
    • This type is designed for physical Mac devices and works with Citrix VDA for macOS
    • Select “Machines that are not power managed” (Orka manages the VM lifecycle)
  4. Configure Machine Catalog settings:
    • Catalog name: Use a descriptive name like “Orka-macOS-Sonoma-Standard” or “MacStadium-VDI-Finance”
    • Description: Document the purpose, OS version, and hardware specs (e.g., “macOS Sonoma on M2 Mac mini, 16GB RAM, for finance team”)
    • Session type: Single-session (each user gets their own desktop)
    • User assignment: Choose based on your use case:
      • Random (pooled): Users get any available desktop (non-persistent)
      • Static (dedicated): Users get the same desktop every session (persistent)
  5. Machine accounts:
    • For non-domain-joined Macs, select “No, do not add to Active Directory”
    • This requires Rendezvous protocol for connectivity
  6. Add machines:
    • You’ll add machines to the catalog after deploying VMs with Citrix VDA
    • Machines register automatically using the enrollment token
Machine Catalog naming strategy: Use a consistent naming pattern that reflects:
  • Platform: Orka-macOS
  • OS version: Sonoma, Sequoia, Ventura, Tahoe
  • Hardware profile: Standard, HighPerf, Minimal
  • Department/purpose: Finance, Engineering, Creative
Example: Orka-macOS-Sonoma-HighPerf-Engineering

​
Generating an Enrollment Token

An enrollment token is critical for connecting your Orka-hosted VMs to Citrix Cloud. This token authenticates the VDA during registration and associates the machine with your Citrix DaaS environment. To generate an enrollment token:
  1. Navigate to Citrix Cloud Console → Web Studio → Machine Catalogs
  2. Select your Machine Catalog (created in previous step)
  3. Click “Enable Enrollment Token” or navigate to the enrollment token section
  4. Configure token settings:
    • Token name: Descriptive identifier (e.g., “Orka-Finance-Q1-2026”)
    • Expiration: Set based on your deployment timeline
      • 12 hours: For immediate testing
      • 7 days: Standard deployment window
      • 30 days: Ongoing/phased rollouts
    • Number of uses:
      • Unlimited (default): Token can register multiple VMs
      • Limited: Specify exact number if needed for strict control
  5. Copy the token immediately:
    • The token is displayed only once
    • Store it securely in your Ansible Vault
    • If lost, generate a new token (old token remains valid until expiration)
Adding a token to Ansible configuration: Update your Ansible Vault file: 
vault_citrix_enrollment_token: "your-actual-token-here"
vault_citrix_customer_id: "YOUR_CUSTOMER_ID"
Reference this token in your VDA installation playbooks. The token can be passed to the Citrix VDA installer during VM provisioning. These tokens can be leveraged for automatically registering the VM with your Machine Catalog, with the appropriate scripts or Ansible playbooks in place to invoke Citrix enrollment command: sudo /opt/Citrix/VDA/bin/VdaEnrollmentTool -EnrollmentToken:<token> -Restart Token troubleshooting: If VMs fail to register:
  • Verify that the specified enrollment token hasn’t expired
  • Confirm network connectivity to [customer_ID].xendesktop.net
  • Check token was copied completely (no truncation or extra characters)
  • Ensure that the token is associated with the correct Machine Catalog
  • Review VDA logs at /Library/Application Support/Citrix/VDA/Logs/

​
Configure Delivery Groups

Delivery Groups control which users can access which machines and define the user experience policies. Creating a Delivery Group:
  1. Navigate to Citrix Cloud Console → Web Studio → Delivery Groups
  2. Click “Create Delivery Group”
  3. Select machines:
    • Choose the Machine Catalog created earlier
    • Specify how many machines to include (can be all or a subset)
  4. Configure users:
    • Add users or groups who should have access
    • Options include:
      • Active Directory users/groups (if domain-joined)
      • Azure AD users/groups
      • Individual user accounts
    • For testing, you can use “Allow unauthenticated users” (Note: This is not recommended for production)
  5. Delivery Group name and settings:
    • Name: Descriptive, for example: “Finance-macOS-VDI” or “Engineering-Sonoma-Desktops”
    • Display name: What users see in Citrix Workspace (e.g., “macOS Finance Desktop”)
    • Description: Document purpose and access requirements
    • Time zone: Set to match user locations or leave as client time zone
  6. Configure desktop assignment:
    • For pooled (random) catalogs: Users get any available desktop
    • For dedicated (static) catalogs: Users are permanently assigned to specific desktops
  7. Application and desktop delivery:
    • Published Desktop: Users access a full macOS desktop
    • Published Applications: Specific apps published to users
    • For Citrix + Orka VDI, select the “Add Desktop” delivery type
  8. Session policies:
    • Configure session timeout settings
    • Set idle session behavior
    • Define reconnection policies
    • Enable or disable features like printing, clipboard, USB redirection
Access policy considerations:
  • Authentication method: How users prove their identity
    • Active Directory (traditional)
    • Azure AD / Okta / other SAML providers
    • Multi-factor authentication (MFA) support
  • Access from: Define where users can connect from
    • Internal network only
    • Remote access via Citrix Gateway
    • Both internal and external
  • Device posture: (Optional) Restrict based on device compliance
    • Managed devices only
    • Endpoint security requirements
    • Operating system versions
Multiple Delivery Groups Consider creating several Delivery Groups from the same Machine Catalog:
  • Finance-Standard-Users → Access to M2 Mac mini VMs
  • Engineering-Power-Users → Access to M4 Pro Mac mini VMs
  • Creative-Graphics-Team → Access to Mac Studio M2 Ultra VMs
This allows you to manage access policies and resources granularly while using shared infrastructure.

​
Enable Rendezvous for Non-Domain-Joined Devices

Rendezvous protocol enables HDX connections to VDAs that aren’t joined to an Active Directory domain. When to use Rendezvous: Use Rendezvous when:
  • VMs are not domain-joined
  • Users access from external networks
  • You want simplified firewall configuration
  • VMs are behind NAT or have private IPs
  • You’re deploying cloud-hosted Macs
Don’t use Rendezvous when:
  • All VMs are domain-joined
  • You have on-premises StoreFront and Gateway already deployed
  • Your security policy requires traditional reverse proxy architecture
  • Performance is absolutely critical (Rendezvous adds minimal overhead, but some organizations prefer direct connections)
Enabling Rendezvous: Rendezvous is typically enabled by default for Citrix DaaS environments with non-domain-joined machines. However, you can verify and configure this:
  1. In Citrix Cloud Console → Web Studio → Configuration → Policies
  2. Create or edit a policy for your Delivery Group
  3. Navigate to ICA/HDX settings
  4. Configure Rendezvous settings:
    • HDX Adaptive Transport: Set to “Preferred” or “Server Only”
    • Rendezvous Protocol: Enable
    • WebSocket connections: Allow
  5. On the VDA side:
    • The VDA automatically detects Rendezvous capability
    • Establishes outbound connection to *.*.nssvc.net
    • Maintains persistent WebSocket connection for HDX session brokering
Network requirements for Rendezvous Ensure VMs have outbound access to:
  • *.*.nssvc.net on TCP/UDP port 443
  • If your firewall requires specific subdomains, use:
    • *.g.nssvc.net (Gateway Service)
    • *.c.nssvc.net (Control plane)
No inbound ports required on the VDA when using Rendezvous (major security advantage). Rendezvous Protocol behavior
  1. User launches desktop from Citrix Workspace
  2. Citrix Cloud Delivery Controller selects available VDA
  3. Instead of direct connection, Cloud signals VDA via persistent Rendezvous channel
  4. VDA initiates outbound HDX connection to Citrix Gateway Service
  5. User’s Workspace client connects to Gateway Service
  6. Gateway Service proxies HDX traffic between client and VDA
This architecture allows VMs with private IPs or behind NAT to be accessible without complex port forwarding or VPN requirements. Disabling Rendezvous If you need to disable Rendezvous:
  1. VDA must be domain-joined
  2. Configure traditional StoreFront and NetScaler Gateway
  3. Update VDA configuration:
    • Disable Rendezvous in VDA settings
    • Point VDA to StoreFront servers instead of Cloud Connectors
Keeping Rendezvous enabled is recommended for simplicity and functionality. Testing Rendezvous connectivity After enabling, verify Rendezvous works:
  1. Check VDA registration status in Citrix Cloud Console
  2. Look for Rendezvous connection in VDA logs
  3. Launch a test session from Citrix Workspace
  4. Monitor connection establishment (should not require VPN or special network access)
  5. Verify session performance meets expectations
Rendezvous troubleshooting If Rendezvous connections fail:
  • Verify outbound connectivity to *.*.nssvc.net on port 443
  • Check proxy settings if environment uses HTTP proxy
  • Review VDA logs for Rendezvous registration errors
  • Confirm WebSocket connections aren’t blocked by firewall
  • Test with Citrix Workspace app (ensure version 2402 or later)

​
Deploy Citrix VDA inside VMs

Citrix VDA installation enables macOS VMs to register with Citrix Cloud and deliver desktop sessions to end users. Deployment can be performed manually for small environments or automated via Ansible for scale. Preparation steps:
  1. Download Citrix VDA for macOS:
    • Access Citrix Downloads portal
    • Locate “Citrix VDA for macOS” package
    • Download latest stable version
    • Verify package integrity
  2. Install Microsoft .NET Runtime 8.0:
    • Required dependency for VDA enrollment and registration
    • Download from Microsoft package feed for macOS
    • Reference: Install .NET on macOS - .NET
    • Install on base image or individual VMs
  3. Prepare installation parameters:
    • Citrix enrollment token
    • Customer ID
    • Delivery controller addresses or cloud endpoint
    • Network configuration settings
Manual deployment approach For pilot deployments or troubleshooting:
  1. Deploy test VM from base image:
    • Use Orka Engine to create a VM from a macOS base image 
      # Plan deployment (dry-run)
ansible-playbook -i inventory deploy.yml \
  -e "vm_group=citrix-vda-test" \
  -e "desired_vms=1" \
  --tags plan

# Execute deployment
ansible-playbook -i inventory deploy.yml \
  -e "vm_group=citrix-vda-test" \
  -e "desired_vms=1"
    • Allocate appropriate VM resources (CPU, RAM, storage)
    • Attach VM to correct network bridge
    • Start VM and establish SSH access
  2. Copy VDA installer to VM:
    • Transfer CitrixVDA.pkg to VM via SCP or shared storage
    • Also copy .NET Runtime installer if not in base image
  3. Install prerequisites:
    • Install .NET Runtime 8.0
    • Verify installation successful
    • Restart if required
  4. Install Citrix VDA:
    • Run VDA installer package with administrative privileges
    • Provide enrollment token during installation (note: enrollment can take 5-10 minutes)
    • Specify Citrix Cloud customer ID
    • Configure network settings (Rendezvous enabled if non-domain-joined)
    • Complete installation and restart VM
  5. Initial configuration:
    • VDA service starts automatically after installation
    • Verify VDA service is running
    • Check log files for any errors
    • Confirm network connectivity to Citrix Cloud endpoints
Automated deployment approach For scalable deployments, automate VDA installation via Ansible. Create a golden image using Ansible with Citrix VDA pre-installed:
  1. Deploy a clean VM using Orka Engine 
    ansible-playbook -i inventory.ini create_orka_vm.yml \
  -e "vm_name=quick-vm" \
  -e "image_source=ghcr.io/macstadium/orka-images/sonoma:latest"
  2. Install .NET Runtime 8.0
  3. Install Citrix VDA (without enrolling)
  4. Configure base settings
  5. Commit VM to create image
  6. Push image to OCI registry
  7. Deploy new VMs from this golden image
  8. Each VM enrolls automatically on first boot using your enrollment token
Installation parameters: Key parameters passed during VDA installation:
  • --enrollment-token - Token from Citrix Cloud (stored in Ansible Vault)
  • --customer-id - Your Citrix Cloud customer ID
  • --cloud-connector - Citrix Cloud DaaS endpoint
  • --enable-rendezvous - Enable for non-domain-joined VMs
  • --delivery-controller - For on-premises CVAD (FQDN of controllers)
Post-deployment image management: After successful VDA deployment:
  • Create a golden image from the previously configured VM
  • Tag image with version information
  • Push to private registry 
    ansible-playbook -i inventory.ini publish_orka_image.yml \
  -e "local_image=my-backup" \
  -e "remote_image=myregistry.com/orka/my-image:v1"
  • Document installed software versions
  • Test image deployment before marking as production-ready

​
Verify VDA Registration with an Enrollment Token

Verifying VDA registration ensures that VMs are successfully registered with Citrix Cloud and are available for user sessions. This step is crucial, as it validates the entire integration between Orka, VDA, and Citrix DaaS. Registration process overview:
  1. VDA service initializes on boot
  2. VDA reads configuration (enrollment token, customer ID)
  3. VDA establishes outbound HTTPS connection to Citrix Cloud
  4. VDA authenticates using enrollment token
  5. VDA registers with specified Machine Catalog
  6. Citrix Cloud adds VM to available desktop pool
  7. VDA maintains heartbeat connection to Cloud
Verification methods: Citrix Cloud Console Check registration status in Web Studio:
  1. Navigate to Citrix Cloud Console → Web Studio
  2. Go to Machine Catalogs → Select your catalog
  3. View list of registered machines
  4. Verify your VM appears with:
    • Machine name (hostname)
    • Registration state: “Registered”
    • Power state: “On”
    • Session state: “Available”
VDA logs on VM: Examine VDA log files for registration confirmation:
  • Log location: /Library/Application Support/Citrix/VDA/Logs/
  • Key log files:
    • vda.log - Main VDA service log
    • registration.log - Registration-specific events
    • broker.log - Communication with Citrix Cloud
Look for successful registration messages:
  • “Registration successful”
  • “Broker connection established”
  • “VDA ready to accept sessions”

​
Common registration issues

Enrollment token problems:
  • Expired token: Generate new token, update Ansible Vault, redeploy VDA
  • Invalid token: Verify the token was copied correctly (no truncation or extra characters)
  • Token already used (if tokens are limited): Generate a new token or increase use limit
Network connectivity issues:
  • Cannot reach Citrix Cloud: Verify outbound HTTPS (TCP 443) allowed to *.xendesktop.net
  • Gateway Service unreachable: Confirm access to *.*.nssvc.net on port 443
  • DNS resolution failure: Check VM DNS configuration, test name resolution
Configuration errors:
  • Wrong customer ID: Verify customer ID matches the Citrix Cloud tenant
  • Machine Catalog mismatch: Ensure enrollment token is associated with the correct machine catalog
  • VDA version incompatibility: Update to supported VDA version
Firewall/proxy issues:
  • Corporate firewall blocking: Whitelist required Citrix endpoints
  • Proxy misconfiguration: Configure VDA proxy settings if environment requires proxy
  • SSL inspection interference: Exclude Citrix endpoints from SSL decryption
Troubleshooting commands
Check VDA service status:
ansible mac_vms -i inventory.ini \
  -m shell \
  -a "sudo launchctl list | grep citrix"
Restart VDA service:
ansible mac_vms -i inventory.ini \
  -m shell \
  -a "sudo launchctl kickstart -k system/com.citrix.vda"
View VDA logs:
ansible mac_vms -i inventory.ini \
  -m shell \
  -a "sudo tail -100 /Library/Application\ Support/Citrix/VDA/Logs/vda.log"
Test Citrix Cloud connectivity:
ansible mac_vms -i inventory.ini \
  -m shell \
  -a "curl -v https://[customer_ID].xendesktop.net 2>&1 | grep Connected"
Re-registration scenarios: VMs may need to re-register if:
  • A network outage disconnected the VM from Citrix Cloud
  • The VDA service restarted or crashed
  • The VM was moved to different network segment
  • An enrollment token was rotated/updated
  • Citrix Cloud maintenance occurred
Most re-registration happens automatically. Manual intervention is needed only if automatic recovery fails.