Before you begin

• Verify Callback was installed using the same host/FQDN used when creating the SSL certificate.
• Verify the valid SSL certificate was created using the Subject Alternative Name (SAN) attribute that permits the specification of multiple host/FQDN and IP addresses. The certificate request should contain a SAN attribute similar to the following: san:ipaddress=ip_address&dns=ip_address&dns=host/FQDN.
• Verify the IIS contains a valid SSL certificate for the host/FQDN and IP address on all servers.
• Verify the Core servers have Ruby 1.9.3 installed.

Installing NGINX with created certificate

Use the following instructions to copy certificates and work with NGINX.

Copying the certificate, creating the cert and key for NGINX

Follow these steps to copy the certificate.

• Open IIS Manager and navigate to server certificates. Right-click on the certificate, and export it to a .pfx file.

Note

Note the export path and password used. They will be referenced later.

• Install the OpenSSL Windows client:
  • Download the openssl-xxxx-setup.exe (complete package, except sources) from http://gnuwin32.sourceforge.net/packages/openssl.htm
  • Select FullInstallation.
  • Complete the installation.
• Open a command prompt from the bin folder where the SSL Client was installed and enter the following:

openssl pkcs12 -in Input.pfx -clcerts -nokeys -out vht_callback_ssl.crtopenssl pkcs12 -in Input.pfx -nocerts -nodes  -out vht_callback_ssl.key

Where Input is the name and file path of the pfx file.

Verify the files use the naming convention vht_callback_ssl.crt and vht_callback_ssl.key

See the following example for reference:

openssl pkcs12 -in "C:\user\TLS 1.2\cert.pfx" -clcerts -nokeys -out vht_callback_ssl.crt

If the path contains a space, enclose the path and filename in quotes.

• Note the directory where the files in Step 3 were created.

For more information, reference the OpenSSL documentation or the Stack Overflow discussion.

Installing, configuring, running, and removing NGINX

Professional Services provide a single zip file with all components necessary for installing NGINX and running it as a Windows service. Within this package, NGINX is already configured for a normal Callback system.

• Copy the NGINX zip file to the Management Instance.
• Unzip the file to the directory where Callback is installed. This creates a folder called proxy with several subfolders. Do NOT modify any of the unzipped files.
• Copy the certificates created in Copying the certificate, creating the cert and key for NGINX to the \proxy\nginx\confdirectory.
  • Verify the files use the naming convention vht_callback_ssl.key and vht_callback_ssl.crt.

Naming these files incorrectly or copying them to the wrong folder prevents NGINX from working.

• If Tomcat/VIS uses 8080 as its default port, update the NGINX port. For a list of Callback ports, see Updated Port List.

  • Open C:\Program Files (x86)\Virtual Hold Technology\proxy\nginx\conf\nginx.conf.
  • Change the listen setting under server to a port number other than 8080, as in the following sample.

     server {    listen       8181 ssl;    server_name  localhost;

When referencing the following Configuring Callback section, use the updated NGINX port number.

• Navigate to the install_path\VirtualHoldTechnology\proxy\bin folder and open a command prompt window.
• Run the following command to install the Reverse Proxy:

nginx_windows_service.cmd install

The command only contains the single argument install.

• On Core servers, install Ruby from the from the installer package. Select the following options:
  • Add Ruby executables to your path
  • Associate .rb and .rbw files with this Ruby installation
• On Core servers, run the \proxy\dependencies\install_dependencies.cmd script.
• After installing the Reverse Proxy, start it using the Windows Services control panel.

nginx_windows_service.cmd uninstall

Configuring Callback

To support HTTPS protocol, run the Core monitor service from the local services account using the following steps.

Modifying the configuration files

On all Management Instances, edit the URLs in the Virtual Hold configuration files to replace http with https. Also update server short names to the fully qualified domain name (FQDN) if the computer and certificate use the FQDN.The following list contains all the files requiring modification:

ConfigurationWizard.exe.config file

install_path\Virtual Hold Technology\VHT_ConfigurationWizard.exe.config

• Update all references to http://FQDN to https://FQDN

ConfigurationTranslationAPI web.config file

install_path\Virtual Hold Technology\VirtualHoldPub\ConfigurationTranslationAPI\web.config

• Update VHQMWS reference to:

<setting name="VHQMWS" serializeAs="String">    <value>https://FQDN/VHQMWS/VHQMWS.asmx</value></setting>

• Update AuthAPI reference to:

<setting name="AuthAPI" serializeAs="String">    <value>https://FQDN:8080/auth</value></setting>

• Update LicenseAPIURL to:

<setting name="LicenseAPIUrl" serializeAs="String">    <value>https://FQDN:8080/mgmt</value></setting>

EyeQueue.url:

install_path\Virtual Hold Technology\VirtualHoldPub\EyeQueue\EyeQueue.url (shortcut to EyeQueue)

• Change the path to https://FQDN/EyeQueue

EyeQueue web.config file:

install_path\Virtual Hold Technology\VirtualHoldPub\EyeQueue\web.config

• Update all references to http://FQDN to https://FQDN
• Modify the following line to use https and NGINX port/path:
  • <add key="ConversationBridgeAuthURL" value="https://FQDN:8080/auth"></add>
• Locate <basicHttpBinding> and modify <security mode="None"> to <security mode="Transport">
• Uncomment the webBindingHttps section
• If removing port 80 or unbinding http from IIS, you must add this to the file:<add key="InternalConversationBridgeURL" value="https://FQDN/"></add>
• If removing port 80 or unbinding http from IIS, add the following under the <EyeQ.Properties.Settings> tag:

<setting name="EyeQ_VHQMWS_VHQMWS" serializeAs="String">     <value>https://FQDN/VHQMWS/VHQMWS.asmx</value></setting> 

Secure cookies over HTTPS

Also performed in install_path\Virtual Hold Technology\VirtualHoldPub\EyeQueue\web.config

• Locate the <system.web> element inside <configuration>
• Add requireSSL=true attribute to the <forms> element

<authentication mode="Forms">
   <forms name=".EyeQCookie" loginUrl="Login.aspx" protection="All" path="/" slidingExpiration="true" timeout="30" requireSSL="true"></forms></authentication>
<!-- for profiling -->
<!-- <anonymousIdentification enabled="true"/> -->
<!-- AUTHORIZATION

• Add a new httpCookies requireSSL="true"/> element to the bottom of the <system.web> element

   <pages theme="Default" controlRenderingCompatibilityVersion="3.5" clientIDMode="AutoID">
      <controls>
         <add tagPrefix="asp" namespace="System.Web.UI.HtmlControls" assembly="System.Web"></add>
      </controls>
   </pages>
   <httpCookies requireSSL="true" />
</system.web><location path="QueueStatistics.aspx">
   <system.web>

CallbackResponse web.config file

install_path\Virtual Hold Technology\VirtualHoldPub\VHCallbackResponse\web.config

• Update all references to http://FQDN to https://FQDN

VHQMWS web.config file

install_path\Virtual Hold Technology\VirtualHoldPub\VHQMWS\web.config

• Update all references to http://FQDN to https://FQDN

VHQWatch web.config file

install_path\Virtual Hold Technology\VirtualHoldPub\VHQWatch\web.config

• Update all references to http://FQDN to https://FQDN

Management API site.config file

install_path\Virtual Hold Technology\Management API\site.config

• Modify the following line to use the local ip address and port:
  • {auth_api_url,"http://127.0.0.1:2800"}

ConfigurationManagement site.config file

install_path\Virtual Hold Technology\ConfigurationManagement\site.config

• Modify the following line to use the local ip address/port:
  • {auth_api_url,"http://127.0.0.1:2800"}

Notification Server site.cofig file

install_path\Virtual Hold Technology\Notification Server\site.config

• Modify the following line to use https:
  • {display_name, "Platform Toolkit"}, {url, "https://FQDN/VHTPlatform...latformWS.asmx"}
• Modify the following line to use https:
  • {display_name, "EyeQueue"}, {url, "https://FQDN/EyeQueue"}

vht_auth_api-config.yml file

install_path\Virtual Hold Technology\Dashboard\vht_auth_api-config.yml

• Modify both lines to use:
  • host: '127.0.0.1'

vht_stats_api.config.yml file

install_path\Virtual Hold Technology\Dashboard\vht_stats_api-config.yml

• Modify this line to use:
  • host: '127.0.0.1'
• Modify this line to use:
  • ws_host: 'FQDN'
• Modify this line to use:
  • ws_port: 443

Additional configuration files

For each of the following files:

install_path\Virtual Hold Technology\VirtualHoldPub\ConfigurationManagement\settings.js

install_path\Virtual Hold Technology\VirtualHoldPub\dashboards\settings.js

install_path\Virtual Hold Technology\VirtualHoldPub\launchpad\settings.js

install_path\Virtual Hold Technology\VirtualHoldPub\LegacyReports\settings.js

install_path\Virtual Hold Technology\VirtualHoldPub\LegacyUsers\settings.js

install_path\Virtual Hold Technology\VirtualHoldPub\Licensing\settings.js

install_path\Virtual Hold Technology\VirtualHoldPub\SystemManagement\settings.js

install_path\Virtual Hold Technology\VirtualHoldPub\SmartRulesEngineUi\settings.js

Update the following, if present:

References of :2800 to :8080/auth

References of :2900 to :8080/stats

References of :8000 to :8080/system

References of :8001 to :8080/config

References of :8002 to :8080/license

References of :8012 to :8080/mgmt

Changing the URL in the WSConfiguration table

Edit the URL in the WSPath entries in the WSConfiguration table in the VHT_Config database to replace the http portion of the URL with https.

Changing the URL in the VHQMWSPath Registry Entry

On every Callback server, edit the URL in the VHQMWSPath registry entry in HKEY_LOCAL_MACHINE\Software\Wow6432Node\Virtual Hold\ and replace the http portion of the URL with https. Also update server short names to the fully qualified domain name (FQDN) if the computer and certificate use the FQDN.

Restarting the Callback components

After the previous procedures are completed on each Management server, restart servers running Callback in order for the changes to take effect.

The services start automatically when Callback starts. If the server cannot be restarted, restart each Callback service on each server.

Next Steps

For a list of Callback ports, see the Updated Port List page.