Streaming Gateway Appliance on AHV¶
The Nutanix Frame Streaming Gateway Appliance (SGA) is a secure reverse proxy that supports the Frame Remoting Protocol (FRP). The SGA allows organizations to securely grant users access to virtualized applications and/or desktops without requiring a VPN. This guide is intended for customers using Frame on Nutanix Acropolis Hypervisor (AHV) infrastructure wishing to install and configure the SGA on their AHV cluster. Before an SGA can be deployed, the customer must have an established Frame customer or organization entity with a registered AHV Cloud Account, plans to deploy the SGA in a DMZ VLAN on an AHV cluster, and has at least one existing Frame account on the AHV cluster.
SGA Network Architecture¶
To deploy an SGA, the company’s network must allow Internet traffic to reach the SGA VM in the DMZ on tcp/443 (HTTPS and Secure WebSockets) and from the SGA VM to the workload VLAN containing the Frame-managed workloads (e.g., Sandbox, production pools, Utility Servers). The SGA VM or VMs (if high-availability is required) are assumed to be deployed in a VLAN on an AHV cluster which is separate from the workload VLANs. This is illustrated in the following diagram:
Customers can deploy the SGA within the workload VM or on non-AHV-hosted VMs, if they wish. If the SGAs are to be deployed on non-AHV-hosted VMs, the general concepts described below apply but the installation and configuraton procedure is slightly different.
Please consult the network protocol and port summary for SGA on AHV to ensure that network routing requirements are satisfied before continuing.
The following prerequisites must be met before starting SGA installation and configuration:
Setting up a Streaming Gateway Appliance on a Frame account consists of 6 major steps to be performed by the customer. A 7th step is performed by Nutanix Support to finalize the setup.
|Step 1||Define the subdomain name (e.g., sga.company.com) and corresponding public IP address for the SGA.|
|Step 2||Obtain the SGA public key certificate.|
|Step 3||Paste the Certificate Bundle (SGA Wildcard Certificate, Intermediate Certificate Authority (CA) Certificate, and then Trusted Root CA Certificate), SGA private key, FQDN, and CIDR into
|Step 4||Create the SGA VM with the Nutanix Frame SGA ISO and YAML file in the DMZ.|
|Step 5||Configure the firewall (including NAT if required) and routing to enable HTTPS requests from the Internet to reach the SGA VM, and traffic originating from the SGA VM to reach the workload VLAN containing the Frame-managed workloads.|
|Step 6||Add the SGA subdomain as a wildcard DNS entry with the corresponding public IP address to the public DNS server.|
|Step 7||Nutanix Support configures the Frame Platform entry for the SGA subdomain for the Frame account.|
Installation and Configuration¶
Step 1: Define the SGA subdomain and corresponding public IP address
End users’ browsers must be able to reach the SGA from the Internet. Since the SGA will be deployed behind your organization’s firewall, the end users’ HTTPS requests and Secure WebSocket connections (for streaming) must be able to resolve to a public IP address on the your organization’s firewall. From that public IP address on your organization’s firewall, the request would need to be forwarded to the private IP address of the SGA and then from the SGA to the workload VMs.
Each Frame-managed workload VM will have an FQDN based the SGA subdomain. Consequently, the SGA subdomain will need to be configured as a wildcard DNS A record. For example, a company would need to make sure that:
*.sga.company.comresolves to the public IP of the SGA.
- The public IP address of the SGA is network address-translated to the private IP address of the SGA by the firewall.
Step 2: Obtain an SGA public key certificate
Generate the wildcard SSL certificate signing request and corresponding private key for the subdomain chosen in the previous step. If this SGA is intended for use in a production environment, please obtain a public wildcard certificate or Subject Alternate Name (SAN) certificate from the certificate authority of your choice. If the SGA is to be used for testing or a proof of concept environment, a free public wildcard certificate can be obtained from LetsEncrypt
Be aware that free Let’s Encrypt certificates have a ninety-day lifetimes.
The SSL certificate must match the DNS subdomain record. For example, if the wildcard SSL certificate is
*.sga.company.com, then the DNS subdomain A record must be
*.sga.company.com (and not
Step 3: Prepare the YAML Configuration File
This configuration file contains the private key of your wildcard certificate. Do not use online YAML validation tools. To safely validate your YAML file, use the methods listed below.
The YAML configuration file is used by Prism Central to configure the VM during the SGA VM creation. Formatting and indentation are very important. Copy the YAML Configuration File Template and edit the renamed file only in the following areas:
- The certificate (Wildcard Certificate, Intermediate CA Certificate, Trusted Root CA Certificate)
- The private key
- The public Fully Qualified Domain Name (FQDN) of the SGA that resolves in public DNS. (Example:
- The workload CIDR from the Frame Account (Example: 172.31.21.0/24)
If the Certificate Authority (CA) provides more than one Intermediate CA certificate, make sure that the order of the certificates in the YAML file is in the order of the certificate chain (e.g., Wildcard Certificate, Intermediate CA Certificate 1, Intermediate CA Certificate 2, Trusted Root Certificate). If the certificate order is not correct, nginx will not start up successfully.
If you have more then one Inermediate CA Certificate each one of them needs to be seperated by a —–BEGIN CERTIFICATE—– and a —–END CERTIFICATE—–
Please validate the YAML file before loading the file into the SGA VM using Prism Central. Pay attention to the text left padding (8 spaces only) and the validity of the Workload VLAN CIDR range. Your Streaming Gateway Appliance will not function correctly if any of the four items listed above are incorrect. Refer to the YAML File Validation section for additional information on how to validate the YAML configuration file.
YAML Configuration File Template
#cloud-config write_files: - path: /opt/server.crt owner: nginx:nginx permissions: '0644' content: | -----BEGIN CERTIFICATE----- Server Cert(wildcard cert) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- Intermediate cert -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- Root cert -----END CERTIFICATE----- - path: /opt/server.key owner: nginx:nginx permissions: '0600' content: | -----BEGIN PRIVATE KEY----- Key -----END PRIVATE KEY----- runcmd: - cd /usr/local/bin && ./gen_proxy_config.py --domain sga.customer.com --cidr 10.0.10.0/24 > /etc/nginx/nginx.conf - systemctl restart nginx
The CIDR must be between /18 and /24
The cert needs to be indented by 8 spaces or it will not work properly
#cloud-config write_files: - path: /opt/server.crt owner: nginx:nginx permissions: '0644' content: | 8 spaces-----BEGIN CERTIFICATE----- 8 spacesServer Cert(wildcard cert) 8 spaces-----END CERTIFICATE-----
Step 4: SGA VM Creation
Upon editing the YAML configuration file with the appropriate formatting, follow the setup tasks below to configure the Streaming Gateway Appliance.
|Description||Example User Interface|
Step 5: Configure Routing to the Workload VMs via the SGA
To ensure external users can reach the SGA and therefore the workload VMs in the private VLAN, verify the following:
- The firewall should be configured to forward port 443 from your SGA public IP address to the SGA private IP address.
- The VLAN that contains the SGA must forward port 443 from the SGA to the workload VLAN.
Step 6: Add SGA subdomain and associated public IP address in public DNS
Create an address (A) record in your public Domain Name Server associating your SGA subdomain with your SGA public IP address.
Step 7: Submit a Support Case
To associate your Frame account(s) with your SGA, submit a support case through the Nutanix Support Portal. Provide the following information in the support ticket:
- Customer name
- Organization name
- Account name(s)
- Wildcard subdomain
- SGA public IP address
SGA Sizing Recommendations¶
As stated previously, organizations can start with a VM configuration of 2 vCPUs and 4 GB RAM for the SGA. A 2 vCPU VM is able to process ~1 Gbps bandwidth of Frame Remoting Protocol data. Nutanix recommends a sizing target of 500 Mbps per 2 vCPUs to allow users to burst their bandwidth consumption.
The total number of concurrent users for the 500 Mbps bandwidth per 2 vCPU budget is dependent on the bandwidth consumed for the Frame sessions. Bandwidth consumption may be estimated based on user workload profiles:
- 1 Mbps per Frame session for office productivity applications, CPU-only VMs, under 30 fps, 2K or less monitors
- 5 Mbps per Frame session for CAD applications, GPU-backed VMs, up to 60 fps, 2K or less monitors
- 10 Mbps or greater per Frame session for video editing/animation/sustained playback, GPU-backed VMs, up to 60 fps, 2K or less monitors
In an office productivity use case, for example, where CPU-only VMs are used with standard 1920 x 1080 displays, the default (2 vCPU, 4 GB RAM) VM configuration could support 500 concurrent users. For 1,000 concurrent users, the same organization would need to leverage at least a 4 vCPU, 8 GB RAM VM. An 8 vCPU, 16 GB RAM VM could support 2,000 concurrent users for this use case.
Frame also supports smaller network CIDR blocks to segment Frame accounts. For more information, please contact Frame Solutions Architecture.
The SGA can be configured for redundancy using a L2 to L4 load balancing solution. The recommended solution is comprised of two (2) Load Balancers, physical or virtual, creating a single inbound load balancer virtual IP address (LBVIP) balancing two (2) Streaming Gateway Appliances. The load balancing solution must have the following configured:
- SSL Passthrough
- Persistent Traffic to LBVIP1 or LBVIP2
- Wildcard DNS entry to LBVIP
User Flow Example:
A Frame user logs in to the Frame Platform via their normal method. When the user clicks the desktop or application requested, Frame Platform directs the user’s browser to an FQDN based on the SGA subdomain, as configured by Nutanix Frame Support, for the Frame account.
For example, if the subdomain was
sga.company.com and the workload VM had a private IP address of 10.2.1.3, the workload FQDN would be
10-2-1-3.sga.company.com. This FQDN points to the inbound LBVIP and the Application Load Balancer decides which SGA to send the traffic to.
SGA for Multiple Frame Accounts¶
An SGA can configured to serve as the reverse proxy for multiple Frame accounts. Use the steps below to configure your SGA for multiple Frame accounts:
- Configure the memory and vCPU using the SGA sizing recommendations above on your SGA to account for scaling up.
- Log in to the SGA as: nutanix, nutanix/4u
- SSH into your SGA or use the AHV console to navigate to
- Verify that from a networking perspective, you can ping/reach/route to the Frame workloads in the other VLANs or subnets from the SGA. Do not continue until you confirm your SGA can reach the additional account workload VLANs.
- Execute the following command as root on the SGA VM:cd /usr/local/bin && ./gen_proxy_config.py --domain sga.company.com --cidr 10.0.1.0/24 10.0.2.0/24 > /etc/nginx/nginx.conf systemctl restart nginx
The command line syntax above assumes that you have Python in your path and the latest gen_proxy_config.py downloaded.
- Submit a support ticket. Follow the instructions in Step 8 in the Installation and Configuration section of this guide.
Troubleshooting the SGA on AHV infrastructure should be started by assessing the public side of the solution, then moving to the SGA command line interface (CLI) to assess traffic flow from the SGA to the Frame workload VMs.
From the public Internet, verify the following to isolate the issue between user’s browser and company SGA:
Wildcard DNS points to the same FQDN as the Wildcard Certificate
- Example: *.sga.company.com
Check the SGA certificate chain validates properly.
- <Trusted, Intermediate, Server Certificate>
Is the SGA reachable at
- You should receive an HTTP Internal Server Error 500.
To verify that HTTPS/Secure WebSocket traffic is working properly from the SGA to the Frame workload VMs, login to SGA with the username:
- Username: nutanix
- Password: nutanix/4u
YAML File Validation¶
To validate that you have a correctly formatted YAML file, you can use Ruby or Python on your local machine.
This configuration file contains the private key of your wildcard certificate, do not use online YAML validation tools. To safely validate your YAML file, use the methods listed below.
If you have Ruby, running the command below will validate your YAML file. In this example, assuming you saved the YAML file as “config.yaml”:
ruby -ryaml -e "p YAML.load(STDIN.read)" < config.yaml
If you do not receive an error, your YAML file is correct. If you do receive an error, the output will tell you where the mistake is. For example:
(<unknown>): mapping values are not allowed in this context at line 2 column 8 (Psych::SyntaxError)
If you have Python, you can verify your YAML file with Python with the following methods:
First, you need to install the Python YAML library. This is done via pip, and all Python versions greater than 2.7.9 have pip by default. Install the YAML library by running:
pip install pyyaml
From there, you can verify you have a correctly formatted YAML configuration with:
python -c 'import yaml, sys; print(yaml.safe_load(sys.stdin))' < config.yaml
There is another tool you can use called “yamllint.” Install yamllint by running:
pip install --user yamllint
Once installed, run: