Citrix Gateway Connector
Citrix Gateway Connector is a Citrix component which serves as a channel of communication between Cloud services (Citrix Gateway service, ADM, and so on) and on-premises components such as Web servers. It is a virtual appliance compatible with Citrix Hypervisor, VMware ESXi, and Microsoft Hyper-V with a small form factor. Citrix Gateway Connector facilitates the remote access to the Enterprise web apps.
How it works
Citrix Gateway Connector authenticates and encrypts all communication between Citrix Cloud and your resource locations. The communication between the Citrix Gateway Connector and Citrix Cloud is outbound. All connections are established from the Citrix Gateway Connector to the cloud using the standard HTTPS port (443) and the TCP protocol. No incoming connections are accepted. TCP port 443, with the following FQDNs are permitted outbound:
Important: If there are SSL intercepting devices in the on-premises data center where the Citrix Gateway Connector must be deployed, the connector registration does not succeed if SSL interception is enabled for these FQDNs. The SSL interception must be disabled for these FQDNs for successful connector registration.
Capabilities of Citrix Gateway Connector
The following are some of the capabilities of Citrix Gateway Connector.
- Acts as a reverse proxy – Citrix Gateway Connector acts as a reverse proxy to Enterprise Web apps. The required web application ports must be opened from the Gateway Connector to the apps.
- Enables single sign-on: The Citrix Gateway Connector provides the following single sign-on capabilities with Citrix Gateway service
- Basic SSO
- No SSO
- Enables application of optional security policies through Access Control – The Citrix Gateway Connector provides enhanced security capabilities through Citrix Access Control service. For example,
- Restrict clipboard access
- Restrict printing
- Restrict navigation
- Restrict downloads
- Display watermark
- App protection policies
- Enforce policy on mobile device
Citrix Gateway Connector is a virtual appliance. The minimum system requirements for the Citrix Gateway Connector are as follows:
- Number of vCPUs must be exactly 2.
4 GB RAM minimum.
Important: The new minimum system requirement for RAM has changed. If you have an existing Citrix Gateway Connector, upgrade the system memory of your virtual machines to match the new requirement of 4 GB RAM.
For details, see Upgrade the system memory of Citrix Gateway Connector virtual machines.
- 1 Network Adapter (virtual NIC). You can add an extra virtual NIC upon requirement.
- UDP port 53 to DNS server
- TCP and UDP port 389 to Active Directory Domain Controllers (optional
* - *is described at the end of the page)
- TCP port 636 to Active Directory Domain Controllers (optional
- TCP port 3268 to Active Directory Domain Controllers (optional
- TCP port 3269 to Active Directory Domain Controllers (optional
- TCP port 443, with the following FQDNs are permitted outbound:
- TCP ports (**) to Web servers accessed using Citrix Gateway Connector
Open port 8443 inbound for web-based management
*- Required to perform domain-based single sign-on to Web applications
**- Ports determined by the customers’ environment – ports 80 and 443 are typical
Recommended: Network with DHCP enabled to simplify the initial configuration.
Ways to install Citrix Gateway Connector
Citrix Gateway Connector can be installed in one of the following ways.
In both cases, you must create a new virtual machine as described in the following section.
Create a new virtual machine
- Sign in to Citrix Cloud.
- From the menu in the top-left of the screen, select Resource Locations.
- If you have no existing resource locations, click Download on the Resource Locations page. When prompted, save the cwcconnector.exe file. For details, see Cloud Connector Installation.
- If you have a resource location but no Cloud Connectors installed in it, click the Cloud Connectors bar and then click Download. When prompted, save the cwcconnector.exe file.
Click Gateway Connectors.
Select the hypervisor and click Download Image. Import the locally downloaded image to your hypervisor and create a new virtual machine (Citrix Gateway Connector).
Click Get Activation Code.
The activation code is generated as follows.
Once the installation is complete, Click Detect.
Install Citrix Gateway Connector by using the Citrix Cloud user interface
The following are the steps to set up a resource location and install Citrix Gateway Connector using Citrix Cloud user interface:
On top left of the Citrix Cloud screen, click the hamburger icon and select Resource Locations. Click the plus icon next to Resource Locations.
Provide a name for the resource location and click Save.
Double-click the plus icon next to Citrix Gateway Connectors under the newly created resource location.
Complete the steps as described in Create a new virtual machine.
Install Citrix Gateway Connector while adding an Enterprise Web app
While adding an Enterprise Web app using the Citrix Gateway service user interface, you can set up a new resource location and download connectors. For details on adding an Enterprise Web app, see Support for Enterprise web apps.
To set up a resource location and download connectors, perform the following steps:
In the Web app connectivity section, select the Create New radio button. Provide a name for the resource location and click Save.
Click Install Citrix Gateway Connector.
Complete the steps as described in Create a new virtual machine.
Access Citrix Gateway Connector user interface by using the URL
You can access the Citrix Gateway Connector user interface by using the URL that is displayed in one of the messages on the newly installed Citrix Gateway Connector VM. You can also log on to the Citrix Gateway Connector CLI as an administrator and execute the
show ipcommand for viewing the IP address assigned to the Citrix Gateway Connector through DHCP. Then you can open
https://<IP address>:8443 on your browser to access the Citrix Gateway Connector admin user interface.
Log on and set up the Citrix Gateway Connector
After the Citrix Gateway Connector installation is complete, look for the following message on the newly installed VM (Citrix Gateway Connector).
Type the mentioned URL in a browser to access the Citrix Gateway Connector user interface. You can also log on to the Citrix Gateway Connector CLI as an administrator and execute the
show ipcommand. The command displays the IP address assigned to the Citrix Gateway Connector through DHCP. Then open
<https://IP address:8443> on your browser to access the Citrix Gateway Connector admin user interface.
The user name and password for the following screen is
administratorfor the first time user.
Change the password by providing a password of your choice in Set administrator password section and click Continue.
- Enter the following configuration details in System settings section and click Continue.
- Connector IP Address – IP address of Gateway Connector.
- Subnet Mask – Subnet mask of the Gateway Connector IP address.
- Default Gateway – IP address of the default gateway.
- DNS Server – IP address of the DNS server. Starting from Citrix Gateway Connector release 13.0, there is a change in the DNS server configuration. For details, see the section Changes to the DNS server settings.
- Proxy IP – Your internal proxy server IP address.
- Proxy Port – Port of the proxy server.
Changes to the DNS server settings:
Starting from Citrix Gateway Connector 13.0.400.xxx, the DNS configuration for both UDP and TCP protocol on the connector appliance is updated automatically when it is set in the System Settings section. However if you upgrade your connector from earlier versions, you have to manually delete the DNS setting and read it again. To do so, perform the following.
- Navigate to the Citrix Gateway Connector dashboard > Edit Settings.
- Click the delete icon next to the first DNS Server field and click Continue.
- Navigate to the Edit Settings page, read the same DNS server, and click Continue.
- Repeat the steps for the second DNS server.
- You do not have to perform these steps for new instances of 13.0 Citrix Gateway Connector.
- You need not perform the earlier mentioned steps immediately after the upgrade. There is no loss of functionality if this is not done. These steps must be performed for enterprise customers who require DNS over TCP Functionality to make Enterprise Web apps to function correctly.
- In the Single sign on section, check Enable Kerberos Single Sign On for capabilities beyond the basic authentication. Enter the following Kerberos configuration details and click Continue.
- Active Directory Domain – Active Directory domain for the users to be granted access.
- Service Account Name – Delegated user name for authentication.
- Service Account Password – Delegated password for Service Account.
Click Connectivity Test. (This step is optional)
The Connectivity Test option enables you to confirm that there are no errors in the Gateway Connector configuration and the Gateway Connector is able to connect to the URLs. This step is optional. You can skip this step and proceed with activating the Gateway Connector.
When you click Connectivity Test, a set of URLs is executed in the back end to ensure that the connector is able to connect to those URLs. If all the URLs are successfully executed, connectivity test success message appears. The following FQDNs are executed when you click Connectivity Test.
If any of these URLs do not respond, an error message appears and the corresponding URL is displayed. The error messages are classified under three categories.
- DNS error
- Server error
- SSL exception
The following images display sample error messages.
Finally enter the activation code to register the connector with Citrix Cloud and click Save and Finish.
For details on how to get the activation code, see Create a new virtual machine.
Troubleshoot Citrix Gateway Connector registration issues
You can use the Trace feature and the Download Logs feature to troubleshoot Citrix Gateway Connector registration issues
While registering Citrix Gateway Connector, you might come across issues because of which the registration might not be successful. To troubleshoot these issues, you can use the Trace Info link that appears the first time you register the connector. You can download the trace files and share it with the administrators for troubleshooting. Trace files are in an encrypted format. The Trace Info link is also available in the Gateway Connector dashboard even after the registration. You can also capture and download trace files from the dashboard for debugging issues.
How to download trace files
Click Trace Info.
In the Trace dialog box, select the duration that you want to run the trace and then click Start. The Trace dialog box displays the progress.
You can stop the trace that is in progress before it is complete. You can then download the trace files by clicking the Download button. You can also start a new trace from the dialog box.
Note: For debugging registration failures, first start a trace with a given pre-set interval, enter the activation code and submit for registration.
- If the registration fails, you can click the Trace info link to bring up the Trace dialog again, stop the trace, and then download the trace files.
- If the registration succeeds, then the Dashboard console comes up and the trace stops automatically in the background.
- Closing the Trace window before the trace is complete does not stop the trace. The trace keeps running in the background until it is completed.
- If you refresh or close the browser when the trace is in progress, you must manually stop the trace by clicking the Trace Info link to prevent the trace from running indefinitely. In this scenario, the Trace Info link displays only the Stop button and does not display the Download button. Therefore, you cannot download the captured trace. To capture the trace again, click Start new trace.
Download logs option is available in Gateway Connector from version 401.251. If you are on an earlier version of connector and you upgrade the connector to version 401.251, you still cannot download the logs even though the Download Logs link is available.
How to download logs
Click Download Logs.
The Download Logs link is available even during the first time use to help setup the connector.
A log file is generated. Generation of log file takes some time. Once the log file if generated, a message with the link to download file appears.
Click Download. A .tgz file is downloaded.
All files in the download folder are in an encrypted format. Contact the Citrix Cloud support team for help.
Delete a Citrix Gateway Connector
Perform the following to delete a Citrix Gateway Connector.
Sign in to Citrix Cloud.
Select Resource Locations from the menu in the top-left of the screen.
In the Resource Locations page, click Gateway Connectors for a specific resource location.
Select the Gateway Connector that you want to delete and click the ellipsis menu.
Select Remove Connector.
A confirmation dialog box appears.
Note: It might take a couple of minutes for the gateway Connector to be removed from the Resource Locations page. Also, it might take sometime for the Gateway Connector to unregister from the gateway controller.
Upgrade the system memory of Citrix Gateway Connector virtual machines
Gateway connector RAM size is 2 GB, by default. Therefore, it is recommended that you increase the RAM size to 4 GB for optimal performance. This recommendation is applicable for new or existing connector installations.
If you have two connectors per resource location for high availability, perform the following to upgrade the connector virtual machines.
- From the hypervisor, shut down one of the connector virtual machines.
- Edit the hardware configuration or settings of the virtual machine depending on the type of hypervisor.
- Navigate to Memory tab.
- If the RAM size is 2048 MB, increase it to 4096 MB and save the configuration.
- Power up the virtual machine.
- Repeat these steps on the second connector virtual machine as well.
IMPORTANT: Ensure that you upgrade one connector at a time to avoid any outages.
Continuous availability of the Citrix Gateway Connector
As long as you ensure continuous availability of the Citrix Gateway Connector in each resource location, you can manage the machines where they are installed one at a time to avoid outage periods.
For continuous availability, install multiple Citrix Gateway Connectors in each of your resource locations. Citrix recommends at least two (2) Citrix Gateway Connectors in each resource location. If one Citrix Gateway Connector is unavailable for any time, the other Citrix Gateway Connectors can maintain the connection. As long as there is one Citrix Gateway Connector available, there is no loss in communication with Citrix Cloud. Citrix Gateway Connectors can be restricted to upgrade during a specified maintenance window every 24 hour, controlled per Resource Location.
Manage load by installing multiple Citrix Gateway Connectors in each resource location. Since each Citrix Gateway Connector is stateless, the load can be distributed across all available Citrix Gateway Connectors. There is no need to configure this load balancing function. It is automated.
Citrix Gateway Connector
In this article
- How it works
- Capabilities of Citrix Gateway Connector
- System requirements
- Ways to install Citrix Gateway Connector
- Troubleshoot Citrix Gateway Connector registration issues
- Upgrade the system memory of Citrix Gateway Connector virtual machines
- Continuous availability of the Citrix Gateway Connector
- Load management