Skip to main content

Installation

Customers manually deploying the SGA will follow the instructions below to install an SGA instance in their infrastructure:

Prerequisites

Nutanix Frame Streaming Gateway Appliance 3.x prerequisites are as follows:

  • Download the Frame SGA disk image from the Nutanix Portal for the hypervisor/infrastructure on which you wish to deploy the SGA.
  • Download the SGA Toolbox for your desired operating system from the Nutanix Portal.
  • Configure networking and firewall to support additional FQDNs and protocols/ports to support FRP8 if necessary. For FRP8, each SGA VM must have its own public IP address, in addition to the load balancer public virtual IP address.
  • Ensure you have obtained a public key certificate, private key, wildcard subdomain, and public IP address for wildcard subdomain.
Warning

Customers must contact Nutanix Frame Support after installing SGA 3.x to finalize SGA registration.

Step 1: SGA Subdomain

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, Secure WebSocket connections (for FRP7) and WebRTC (for FRP8) must be able to resolve to a public IP address on your organization's firewall. From there, 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 on 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 ensure that:

*.sga.company.com resolves 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.

Warning

Do not use the company domain as the SGA domain (e.g., "company.com") and the company wildcard certificate (e.g., "*.company.com") for the SGA certificate.

Step 2: 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 Let's Encrypt.

Warning

Free Let's Encrypt certificates have a ninety-day lifetime. 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 company.com).

  1. From any secure computer or VM, generate a CSR file and Private key. The CSR will be given to your certificate provider, the key must be kept safe. The command below will create 2 files: PRIVATEKEY.key which will contain your key, and MYCSR.csr which will need to be delivered to the certificate provider.

    Example Using OpenSSL

    Run the following command and fill in the required information:

    openssl req -newkey rsa:2048 -keyout PRIVATEKEY.key -out MYCSR.csr
  2. Deliver the CSR file generated in the step above to a CA-certified provider. The provider will give you files that contain your wildcard certificate, a root certificate, and intermediate certificates. You can open them with Notepad to copy them as needed.

  3. If you need to verify which files are which certificates, you can save the pasted certificate as a .crt file and open it (do not install it). Under the “Certification Path” tab in the file's properties:

    • If you see only 1 level in the path hierarchy, then you are looking at the root certificate.
    • If you see only 2 levels in the path hierarchy, then you are looking at an intermediate certificate.
    • If you see all 3 levels in the path and the name of your wildcard, you are seeing the wildcard certificate.

    SGA Wildcard Certificate

    SGA Wildcard Certificate

Step 3: Configuration File

  1. Run the SGA Toolbox (“sga_toolbox.exe”) to generate the SGA configuration file. The SGA Toolbox will need to be connected to a network that has access to public DNS servers in order to validate that the SGA wildcard subdomain has an associated public IP address.

    SGA Toolbox Executable

    SGA Toolbox Executable
  2. From the top menu of the SGA Toolbox, select “Tools” and then “Generate SGA configuration”

    SGA Toolbox - Generate SGA Configuration

    SGA Toolbox - Generate SGA Configuration
  3. Next, enter the required information into the corresponding fields:

    SGA Toolbox - Configuration Parameters

    SGA Toolbox - Configuration Parameters
ParameterDescription
Base domain nameEnter the base domain name for the subdomain that matches the wildcard certificate.
Frame workloads VLAN CIDREnter the VLAN CIDR range for your workload VMs.
Frame Platform instancesSelect the Frame Platform version you wish to use.
SGA versionEnsure the SGA version to be installed matches the SGA version specified in the SGA Toolbox.
Public IP addressSpecify the public IP address of the SGA.
SSL certificate chainEnter your SSL certificate chain in the following order: Wildcard SGA certificate, Intermediate CA certificate, and Trusted Root CA certificate.
SSL certificate private keyEnter the matching private key for the certificate.
  1. Once all of the information has been entered correctly, click “Generate” and SGA Toolbox will produce your SGA configuration file. You can use the icons above the SGA configuration box to either copy the SGA configuration data to your clipboard or save the file for AHV.
Considerations
  • If you are creating an SGA VM on ESXi, you must save the SGA configuration data as an ISO file (to be mounted as a CD-ROM when creating the SGA VM).
  • If you are creating an SGA VM on Azure infrastructure, you must copy the SGA configuration data directly from the tool into the Azure console referenced in later steps. Copy the data to your clipboard before moving forward.
Attention

As a best practice, Nutanix Frame strongly advises administrators to save the valid configuration file for troubleshooting purposes, or in scenarios where more than one SGA VM is required.

The “Generate SGA configuration log” window will provide you with additional details in the event that the file generation fails.

Once created, you can customize the SGA configuration file as needed. The default username, password and port number to access the SGA Management Console can be changed by setting the configuration parameters WEB_MGMT_USERNAME, WEB_MGMT_PASSWORD, and WEB_MGMT_PORT. You can also add an SSH public key for the nutanix user account by setting the configuration parameter SSH_MGMT_PUB_KEY to an SSH public key you created previously to access the SGA VM using SSH.

These SGA configuration parameters, along with any additional SGA configuration parameters and their values, are added below the bootcmd: block of the SGA configuration file:

#cloud-config
bootcmd:
- set_sga_var WEB_MGMT_USERNAME nutanix
- set_sga_var WEB_MGMT_PASSWORD nutanix/4u
- set_sga_var WEB_MGMT_PORT 8888
- set_sga_var SSH_MGMT_PUB_KEY ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDtfileuEjCuTnWkRR7KpvEQCXIg81Bl7sgmN1WbRqbRRZvNxhD5Z+9qK5vQ2XXwmn3t70RSYIHPjnK4/CGyR4urLUfTdOoNMl3zQv70/trkZ+Y1mRry2JCQEGyf7OIZE01Bw0vYgtS3KETOCQ2PYR8s04Ig0/FRc25UHxVfwKWUD3fu2sScIDmNf/LFXXSCih6bAIP5KmSxRciyt7pdKmjybGneQSc8F8rSiO58zzUb0TLbK0EY5EfCmQeGXDgTynugiwGF6jbCNbyZ68eh8uCsU1JuCjUE73b/jru2jq5Dk4zNh7LK0nth2iHMZJHOzye3+LetsPQ4gVNaW/Ee4pVG18JP4eh44C5MuGNTSJFz6wN06YI0VofdjJ8eDmtl4vkDLvQZCSEKT4C3lq77biR2GJLz76stLW+LcBfyRo4CDg/hjBlidacEf0O3yCplhmm4uC/PMef6yU4LOrVwVpRpDSMli++/tLGNOyy8jxv6ni86Jnpc55xJG2St500p+s= acct@local

Step 4: SGA Creation

After the configuration file has successfully been created, follow the steps below, based on the hypervisor/infrastructure you have chosen, to create and configure the Streaming Gateway Appliance.

The following instructions assume you have already identified the AHV VLAN that the SGA will be placed in. The VLAN will need to be “public” (have a route from/to the Internet) and will need network connectivity to the private VLAN where the workloads are placed.

  1. Create a new VM in Prism Central (or Prism Element), enter a name and set timezone to UTC.

    SGA VM Creation - VM Creation

    SGA VM Creation - VM Creation
Warning

The timezone must be set to UTC.

  1. Configure Compute Details: SGA VMs should have at least two (2) vCPUs and 4GB RAM. This configuration supports up to 500 concurrent user sessions. Click “Save.”

    SGA VM Creation - VM Configuration

    SGA VM Creation - VM Configuration
  2. Add the SGA disk image by clicking “Attach Disk”

    SGA VM Creation - Attach Disk

    SGA VM Creation - Attach Disk
  3. Specify your Frame SGA disk image. Click “Save.”

    SGA VM Creation - Attach Disk

    SGA VM Creation - Attach Disk
  4. Under “Networks,” click “Attach to Subnet” to assign the appropriate VLAN to the new VM. You can set the static IP address at this point.

    SGA VM Creation - Attach Subnet

    SGA VM Creation - Attach Subnet
  5. Once the SGA disk and networks are attached, select “Next.”

    SGA VM Creation - AHV

    SGA VM Creation - VM Configuration
  6. Enable the Custom Script option and paste in the SGA configuration file. The certificate and private key within the configuration file will be loaded into SGA once the VM is created.

    SGA VM Creation - Custom Script

    SGA VM Creation - Custom Script
  7. Select “Next” and then click “Create VM” on the final Review step.

    SGA VM Creation - Create VM

    SGA VM Creation - Create VM
  8. You should now be able to see the newly created VM in Prism.

    SGA VM Creation - SGA VM in Prism

    SGA VM Creation - SGA VM in Prism
  9. Power on the SGA VM. You can connect to the SGA VM by clicking on the “Launch console” button near the top of the Prism dashboard to access the Virtual Network Console (VNC).

    SGA VM Creation - AHV

    SGA VM Creation - VM Configuration
  10. Log in to the SGA VM using the default Nutanix credentials (username: nutanix) and change the password immediately.

Static IP Address Assignment

  1. Next, we'll need to configure a static IP address for SGA. While in the VNC console, run the command sudo nmtui to access the network configuration.

    SGA VM - Login

    SGA VM - Login
  2. In the NetworkManager TUI, select "Edit a connection".

    SGA VM - Network Manager

    SGA VM - Network Manager
  3. Select the connection.

    SGA VM - Select Connection

    SGA VM - Select Connection
  4. Change the IPv4 CONFIGURATION to <Manual>. Enter the static IP address and /mask to the end of the IP address for the SGA VM, the gateway IP address, and at least one DNS server IP address. The DNS server must be able to resolve public FQDNs.

    SGA VM - Edit Connection

    SGA VM - Edit Connection
  5. Use ifconfig to verify the IP address change was saved and that the DNS configuration is valid.

Step 5: SGA Verification

Once the SGA VM is powered up, you should be able to open a web browser and confirm the status of the SGA by going to http://<SGA_IP>:8888/. You must be in your private network and able to route to the private IP address of the SGA. You will be asked to login using the SGA Management Console login credentials that were set in Step 3.

SGA Management Console Login

SGA Management Console Login

Once you reach the management console, you can select the Status report.

SGA Management Console

SGA Management Console

Step 6: SGA Subdomain and IP Address

Create an address (A) record in your public Domain Name Server associating your SGA subdomain with your SGA public IP address for users to be able to reach your SGA from the Internet.

DNS A Record for SGA

DNS A Record for SGAs
note

If your users in your private network need to reach your SGA from within your private network, create an address (A) record in your private Domain Name Server associating your SGA subdomain with your SGA private IP address.

You may choose to install additional SGAs within your private network rather than sending users to the same public-facing SGAs, if that simplifies your network security configuration and routing from the private network where your users are on to your DMZ and back to your private network where the workload VMs are running.

Step 7: Notify Nutanix Frame Support

As mentioned above the deployment instructions, you must contact Nutanix Frame Support to associate your Frame account(s) with your SGA. You can do so by submitting a support case though the Nutanix Support Portal. Please provide the following information in the support ticket:

  • Customer name
  • Organization name
  • Account name(s)
  • Wildcard subdomain
  • SGA public IP address
  • SGA version number (e.g., 3.1, 3.2, 3.4, etc.)

Nutanix Frame support will process your ticket and let you know as soon as the SGA has been associated with your Frame account(s).