Run PowerShell script to deploy

PowerShell scripts prepare your environment with all the configuration settings. When you run the PowerShell script to deploy Unified Access Gateway, the solution is ready for production on first system boot.

Important: With a PowerShell deployment, you can provide all the settings in the INI file, and the Unified Access Gateway instance is production-ready as soon as it is booted up. If you do not want to change any settings post-deployment, you need not provide the Admin UI password.

However, both Admin UI and the API are not available if the Admin UI password is not provided during deployment. If you do not provide the Admin UI password at the time of deployment, you cannot add a user later to enable access to either the Admin UI or the API. You must redeploy your Unified Access Gateway.

You can include the parameters in the INI file for creating low-priviledged admin users with monitoring roles. Creating superuser admin user is not supported. You can configure the password policies for the root user and admin user before deploying the Unified Access Gateway instance.

For more information about the parameters, you can see the section in which the equivalent admin UI parameter is used. For example: some of the deployment parameters are described in PowerShell deployment parameters and Deploying to vSphere using the OVF Template Wizard, for information about parameters used in system configuration, syslog server settings, network settings, and so on, see Advanced settings, and for information about parameters used in edge services and other use cases of Unified Access Gateway such as Workspace ONE Intelligence and Identify Bridging, see Edge Service settings.

Prerequisites

• For a Hyper-V deployment, and if you are upgrading Unified Access Gateway with static IP, delete the older appliance before deploying the newer instance of Unified Access Gateway.
• Verify that the system requirements are appropriate and available for use.

Procedure

1. Download the Unified Access Gateway OVA from the Customer Connect portal to your machine.

2. Download the uagdeploy-XXX.zip files into a folder on the machine.

   The ZIP files are available at the Customer Connect page for Unified Access Gateway.

3. Open a PowerShell script and modify the directory to the location of your script.

4. Open the INI configuration file for the Unified Access Gateway virtual appliance. See PowerShell deployment parameters.

   For example: Deploy a new Unified Access Gateway appliance UAG1. The configuration file is named uag1.ini. This file contains all the configuration settings for UAG1. You can use the sample INI files in the uagdeploy.ZIP file to create the INI file and modify the settings appropriately.

   Note:

   • You can have unique INI files for multiple Unified Access Gateway deployments in your environment. You must change the IP Addresses and the name parameters in the INI file appropriately to deploy multiple appliances.

   • To convert the private key from PKCS8 to PKCS1, thats is, from the BEGIN PRIVATE KEY format to BEGIN RSA PRIVATE KEY format, run the following openssl command:

     openssl rsa -in key.pem -out keyrsa.pem

     To convert PKCS#12 format file with either a .p12 or .pfx file extension and to ensure the key is an RSA key, run the following commands:

     openssl pkcs12 -in cert.pfx -nokeys -out cert.pem

     openssl pkcs12 -in cert.pfx -nodes -nocerts -out key.pem

     openssl rsa -in key.pem -check -out keyrsa.pem

   Example of the INI File to modify.

   
   [General]
   adminCertRolledBack=false
   adminDisclaimerText=
   adminMaxConcurrentSessions=5
   adminPasswordExpirationDays=90
   adminPasswordPolicyFailedLockoutCount=3
   adminPasswordPolicyMinLen=8
   adminPasswordPolicyUnlockTime=5
   adminSessionIdleTimeoutMinutes=10
   authenticationTimeout=300000
   bodyReceiveTimeoutMsec=15000
   ceipEnabled=true
   cipherSuites=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
   , TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
   clientConnectionIdleTimeout=180
   cookiesToBeCached=none
   defaultGateway=10.108.120.125
   deploymentOption=threenic
   diskMode=
   dns = 192.0.2.1 192.0.2.2
   dnsSearch = example1.com example2.com
   ds=
   dsComplianceOS=false
   eth0CustomConfig=DHCP^UseDNS=false
   eth1CustomConfig=DHCP^UseDNS=false
   extendedServerCertValidationEnabled=false
   fallBackNtpServers=ipOrHostname1 ipOrHostname2
   fipsEnabled=false
   healthCheckUrl=/favicon.ico
   hostClockSyncEnabled=false
   httpConnectionTimeout=120
   ip0=10.108.120.119
   ipMode=DHCPV4_DHCPV6
   ipModeforNIC2=DHCPV4_DHCPV6
   ipModeforNIC3=DHCPV4_DHCPV6
   isCiphersSetByUser=false
   isTLS11SetByUser=false
   locale=en_US
   monitoringUsersPasswordExpirationDays=90
   monitorInterval=60
   name=
   netBackendNetwork=
   netInternet=
   netManagementNetwork=
   ntpServers=ipOrHostname1 ipOrHostname2
   osLoginUsername= 
   osMaxLoginLimit=10
   outboundCipherSuites=
   passwordPolicyFailedLockout=3
   passwordPolicyMinClass=1
   passwordPolicyMinLen=6
   passwordPolicyUnlockTime=900
   quiesceMode=false
   requestTimeoutMsec=10000
   rootPasswordExpirationDays=365
   rootSessionIdleTimeoutSeconds=300
   secureRandomSource=
   sessionTimeout=36000000
   snmpEnabled= TRUE | FALSE
   source=
   sshEnabled=
   sshInterface=eth0
   sshKeyAccessEnabled=
   sshLoginBannerText= EUC Unified Access Gateway
   sshPasswordAccessEnabled=
   sshPort=22
   sshPublicKey1=
   ssl30Enabled=false
   sslprovider=
   target=
   tls10Enabled=false
   tls11Enabled=false
   tls12Enabled=true
   tlsNamedGroups=
   tlsPortSharingEnabled=true
   tlsSignatureSchemes=
   uagName=UAG1
   
   
   [WorkspaceOneIntelligenceSettings1]
   encodedCredentialsFile=
   name=TEST1
   trustedCert1=
   urlThumbprints=bed22939bf8546d15de2136f4c33f48f31d44e71
   
   [WorkspaceOneIntelligenceSettings2]
   encodedCredentialsFile=
   name=RISK_SCORE
   
   [SnmpSettings]
   version= v3
   usmUser=SAM_SNMP_V3
   securityLevel=
   authAlgorithm=
   authPassword=
   privacyAlgorithm=
   privacyPassword=
   engineID=uag1.example.com
   
   [SnmpSettings]
   version=V1+V2c
   communityName=abc
   
   [WebReverseProxy1]
   proxyDestinationUrl=https://10.108.120.21
   trustedCert1=
   instanceId=view
   healthCheckUrl=/favicon.ico
   userNameHeader=AccessPoint-User-ID
   proxyPattern=/(.*)
   landingPagePath=/
   hostEntry1=10.108.120.21 HZNView.uagqe.auto.com
   
   [Horizon]
   endpointComplianceCheckProvider=Workspace_ONE_Intelligence_Risk_Score
   proxyDestinationUrl=https://enterViewConnectionServerUrl
   trustedCert1=
   gatewayLocation=external
   disableHtmlAccess=true
   healthCheckUrl=/favicon.ico
   proxyDestinationIPSupport=IPV4
   smartCardHintPrompt=false
   queryBrokerInterval=300
   proxyPattern=(/|/view-client(.*)|/portal(.*)|/appblast(.*))
   matchWindowsUserName=false
   windowsSSOEnabled=false
   complianceCheckOnAuthentication=true
   proxyDestinationUrlThumbprints=
   proxyDestinationPreLoginMessageEnabled=true
   customExecutable1=WEBEXVDIPLUGIN
   
   [CustomExecutableSettings1]
   name=OPSWAT2
   osType=
   trustedSigningCertificates1=
   url=<<URL to custom executable file>>
   urlResponseRefreshInterval=
   isObtainedFromURL=
   
   [Airwatch]
   tunnelGatewayEnabled=true
   disableAutoConfigUpdate=false
   pacFilePath=
   pacFileURL=
   credentialFilePath=
   apiServerUsername=domain\apiusername
   apiServerPassword=*****
   proxyDestinationUrl=https://null
   ntlmAuthentication=false
   healthCheckUrl=/favicon.ico
   organizationGroupCode=
   apiServerUrl=https://null
   outboundProxyHost=1.2.3.4
   outboundProxyPort=3128
   outboundProxyUsername=proxyuser
   outboundProxyPassword=****
   reinitializeGatewayProcess=false
   airwatchServerHostname=tunnel.acme.com
   trustedCert1=c:\temp\CA-Cert-A.pem
   hostEntry1=1.3.5.7 backend.acme.com
   tunnelConfigurationId=
   
   [AirwatchSecureEmailGateway]
   memConfigurationId=abc123
   apiServerUsername=domain\apiusername
   healthCheckUrl=/favicon.ico
   apiServerUrl=https://null
   outboundProxyHost=1.2.3.4
   outboundProxyPort=3128
   outboundProxyUsername=proxyuser
   outboundProxyPassword=****
   reinitializeGatewayProcess=false
   airwatchServerHostname=serverNameForSNI
   apiServerPassword=****
   trustedCert1=c:\temp\CA-Cert-A.pem
   pfxCerts=C:\Users\admin\My Certs\mycacerts.pfx
   hostEntry1=1.3.5.7 exchange.acme.com
   
   [AirWatchContentGateway]
   cgConfigId=abc123
   apiServerUrl=https://null
   apiServerUsername=domain\apiusername
   apiServerPassword=*****
   outboundProxyHost=
   outboundProxyPort=
   outboundProxyUsername=proxyuser
   outboundProxyPassword=*****
   hostEntry1=192.168.1.1 cgbackend.acme.com
   trustedCert1=c:\temp\CA-Cert-A.pem
   ntlmAuthentication=false
   reinitializeGatewayProcess=false
   airwatchServerHostname=cg.acme.com
   
   [SSLCert]
   pemPrivKey=
   pemCerts=
   pfxCerts=
   pfxCertAlias=
   
   [SSLCertAdmin]
   pemPrivKey=
   pemCerts=
   pfxCerts=
   pfxCertAlias=
   
   [WorkspaceONEIntelligenceRiskScoreEndpointComplianceCheckSettings]
   allowLow=true
   allowMedium=true
   allowHigh=true
   allowOthers=false
   complianceCheckInterval=5
   name=Workspace_ONE_Intelligence_Risk_Score
   workspaceOneIntelligenceSettingsName=RISK_SCORE
   
   [JWTSettings1]
   publicKey1=
   publicKey2=
   publicKey3=
   name=JWT_1
   
   [JWTSettings2]
   publicKey1=
   publicKey2=
   name=JWT_2
   
   [JWTIssuerSettings1]
   issuer=issuer-1
   jwtType=PRODUCER
   name=issuerJWT_1
   pemPrivKey=
   pemCerts=
   pfxCerts=
   pfxCertAlias=
   
   [JWTIssuerSettings2]
   issuer=issuer-2
   jwtType=PRODUCER
   name=issuerJWT_2
   pemPrivKey=
   pemCerts=
   pfxCerts=
   pfxCertAlias=
   
   [AdminUser1]
   enabled=true
   name=monitoringUser1
   
   [AdminUser2]
   enabled=true
   name=monitoringUser2
   
   [OutboundProxySettings1]
   proxyUrl=
   name=
   proxyType=HTTP
   includedHosts1=
   includedHosts2=
   trustedCert1=
   
   [OutboundProxySettings2]
   proxyUrl=
   name=
   proxyType=HTTP
   includedHosts1=
   includedHosts2=
   trustedCert1=
   
   [adminSAMLSettings]
   enable=true
   entityId=https://www.entityid.com
   
   [IDPExternalMetadata1]
   allowUnencrypted=false
   certChainPem=
   encryptionCertificateType=
   entityID=<entityID>
   forceAuthN=false
   metadataXmlFile=<Path of IDP metadata xml file>
   privateKeyPem=
   
   [OPSWATEndpointComplianceCheckSettings]
   allowInCompliance=
   allowEndpointUnknown=
   complianceCheckFastInterval=
   complianceCheckInitialDelay=
   complianceCheckInterval=
   allowNotInCompliance=
   allowOutOfLicenseUsage=
   allowAssessmentPending=
   allowOthers=
   hostName=
   name=
   clientSecret=
   clientKey=
   
   [PackageUpdates]
   packageUpdatesScheme=OFF|ON_NEXT_BOOT|ON_EVERY_BOOT
   packageUpdatesOSURL=
   packageUpdatesURL=
   trustedCert1=
   
   [SyslogServerSettings1]
   sysLogType=TCP
   syslogCategory=ALL
   syslogFormat=TEXT
   syslogSettingName=
   syslogSystemMessagesEnabledV2=true
   syslogUrl=
   
   [SyslogServerSettings2]
   hostname=
   port=6515
   sysLogType=TLS
   syslogCategory=ALL
   syslogClientCertKeyPemV2=
   syslogClientCertPemV2=
   syslogServerCACertPemV2=
   syslogFormat=TEXT
   syslogSettingName=
   syslogSystemMessagesEnabledV2=false
   
   [SyslogServerSettings3]
   mqttClientCertCertPem=
   mqttClientCertKeyPem=
   mqttServerCACertPem=
   mqttTopic=
   sysLogType=MQTT
   syslogCategory=ALL
   syslogFormat=TEXT
   syslogSettingName=
   syslogSystemMessagesEnabledV2=true
   syslogUrl=
   

   Note:

   • The [adminSAMLSettings] included in the INI file is for configuring the SAML authentication method used to authenticate the users with administrator access to the admin UI. Here, entityId refers to the external metadata provider entity id.
   • Passwords for the low-privileged admin users with monitoring roles are provided as parameter to the PowerShell script. If the password is not provided, then the user is prompted to enter the password. Provide the parameter as newAdminUserPwd and the parameter value similar to monitoringUser1:P@ssw0rd1;monitoringUser2:P@ssw0rd2. The enabled parameter in the INI file is optional and defaults to true if the parameter is unavailable.

5. To make sure that the script execution is not restricted., type the PowerShell set-executionpolicy command.

   set-executionpolicy -scope currentuser unrestricted
   

   You only need to do this once to remove the restriction.

   1. If there is a warning for the script, run the following command to unblock the warning: unblock-file -path .\uagdeploy.ps1

6. Run the command to start the deployment. If you do not specify the .INI file, the script defaults to ap.ini.

   .\uagdeploy.ps1 -iniFile uag1.ini
   

7. Enter the credentials when prompted and complete the script.

   Note: If you are prompted to add the fingerprint for the target machine, enter yes.

   Unified Access Gateway appliance is deployed and available for production.

What to do next

If you want to upgrade Unified Access Gateway while preserving the existing settings, edit the .ini file to change the source reference to the new version and rerun the .ini file: uagdeploy.ps1 uag1.ini. This process can take up to 3 minutes.

[General]
name=UAG1
source=C:\temp\euc-unified-access-gateway-3.2.1-7766089_OVF10.ova

If you want to upgrade with zero service interruption, see Upgrade with Zero Downtime.