Basic troubleshooting

This topic list some of the errors that you might come across while or after setting up Secure Private Access.

Certificate errors

Database creation errors

StoreFront failures

Public gateway/callback gateway failures

Secure Private Access Server not reachable

Certificate errors

Error message: Unable to get the certificates automatically from one or more gateway servers.

This error message appears when you try to add a public NetScaler Gateway address and there is an issue fetching the certificate. This issue can occur when setting up Secure Private Access or updating settings after the setup is complete.

Workaround: Update the gateway certificate the same way in which you would for Citrix Virtual Apps and Desktops.

Database creation errors

• Error message: Failed to create database

  Resolution: For Automatic case - The machine must have READ, WRITE, UPDATE permissions to create tables within the database on the SQL server.

• Error message: Failed to create database: A database already exists.

  This error message might appear in any of the following scenarios.

  • If the Automatic configuration option is selected while configuring the databases.

  • If the admin is creating a database, it must be an empty database. This error message can appear if the database is a non-empty database.

    Resolution: You must create an empty database.

  • You uninstall Secure Private Access and retry the setup with the same site name. In this case, the database from the previous installation would not have been deleted.

    Resolution: You must manually delete the database.

  • You choose to set up the database manually (by selecting Manual Configuration in the Configuring Databases page) by using the script, and then change to the Automatic Configuration option but use the same site name. In this case, a database with the same name is already created while running the script.

    Resolution: You must rename the site and then run the script again.

  • The machine does not have the READ, WRITE, UPDATE permissions to create tables within the database on the SQL server.

    Resolution: Enable appropriate permissions on the machine. For details, see Permissions required to set up databases.

• Error message: Failed to create database: Connection failed

  Resolution:

  • Check database network connectivity from your machine. Ensure that the SQL server port is open on the firewall.
  • If using a remote SQL server, check if the SQL server has login created with the Secure Private Access machine identity, Domain\hostname$.
  • If using a remote SQL server, confirm that the machine identity has the correct role assigned, system administrator role.
  • If using a Local SQL server (not from the installer), check if the NT AUTHORITY\SYSTEM user must have a login created.

StoreFront failures

• Error message: Failed to create StoreFront entry for: <Store URL>

  Update the StoreFront entries from the Settings tab if it is not visible. After you have set up Secure Private Access using the wizard, you can edit StoreFront entries from the Settings tab. Note down the StoreFront Store URL for which this error occurred.

  Resolution:

  1. Click Settings and then click the Integrations tab.
  2. In StoreFront Store URL, add the StoreFront entry if it is not visible.

• Error message: Failed to configure StoreFront entry for: <Store URL>

  Resolution:

  1. There might be a PowerShell execution policy restriction in place. Run the PowerShell script command Get-ExecutionPolicy for details.

  2. If it is restricted, you must bypass this and run a StoreFront configuration script manually.
  3. Click Settings and then click the Integrations tab.
  4. In StoreFront Store URL, identify the StoreFront URL entry for which the error occurred.
  5. Click the Download Script button next to this Store URL and run this PowerShell script with admin privileges on the machine on which the corresponding StoreFront installation is present. This script must be run on all the StoreFront machines.

  Note:

  If you are retrying the installation after uninstalling, ensure that you don’t have an entry with the name “Secure Private Access” in the StoreFront configuration (StoreFront > store> Delivery Controller -> Secure Private Access). If Secure Private Access is present, delete this entry. Manually download and run the script from the Settings > Integrations page.

• Error message: StoreFront configuration is not local for: <Store URL>

  After you have set up Secure Private Access using the wizard, you can edit gateway entries from the Settings tab. Note down the StoreFront Store URL for which this error occurred.

  Resolution:

  This issue occurs if StoreFront is not installed on the same machine as Secure Private Access. You must manually run the StoreFront configuration on the machine where you have installed StoreFront.

  1. Click Settings and then click the Integrations tab.
  2. In StoreFront Store URL, identify the StoreFront URL entry for which the error occurred.
  3. Click the Download Script button next to this Store URL and run this PowerShell script with admin privileges on the machine on which the corresponding StoreFront installation is present. This script must be run on all the StoreFront machines.

  Note:

  To run the StoreFront PowerShell script, open the Windows x64 compatible PowerShell window with admin privileges and then run ConfigureStorefront.ps1. StoreFront script is not compatible with Windows PowerShell (x86).

• Error message: “Get-STFStoreService : Exception of type ‘Citrix.DeliveryServices.Framework.Feature.Exceptions.RegistryKeyNotFoundException’ was thrown.” while running StoreFront script using PowerShell.

  This error occurs when the StoreFront script is run on a x86-compatible PowerShell window.

  Resolution:

  To run the StoreFront PowerShell script, open the Windows x64 compatible PowerShell window with admin privileges and then run ConfigureStorefront.ps1.

Public gateway/callback gateway failures

Error message: Failed to create Gateway entry for: <Gateway URL> OR Failed to create Callback Gateway entry for: <Callback Gateway URL>

Resolution:

Note the Public Gateway or Callback Gateway URL for which the failure occurred. After you have set up Secure Private Access using the wizard, you can edit gateway entries from the Settings tab.

1. Click Settings and then click the Integrations tab.
2. Update the public gateway address or the callback gateway address and the virtual IP address for which the failure occurred.

Secure Private Access Server not reachable

Error message: Failed to update IIS pool. Failed to restart IIS pool

Resolution:

Go to Application pools in Internet Information Services (IIS) and check that the following application pools have started and are running:

• Secure Private Access Runtime Pool
• Secure Private Access Admin Pool

Also check that the default IIS site "Default Web Site" is up and running.

Database connectivity check failures

Error Message: Connectivity check failed

Database connectivity check can fail due the multiple reasons:

• The database server is not reachable from the Secure Private Access plug-in host machine due to a firewall.

  Resolution: Check if the database port (default port 1433) is open on the firewall.

• The Secure Private Access plug-in host machine does not have the permission to connect to the database.

  Resolution: See SQL database permissions for Secure Private Access.

Gateway connectivity check failed. Unable to fetch public certificate

Error Message: Post installation configuration fails with the error “Gateway connectivity check failed. Unable to fetch a public certificate….”

Resolution:

• Upload the gateway public certificate to the Secure Private Access database manually using the config tool.
• Open the PowerShell or the command prompt window with admin privileges.
• Change the directory to the Admin\AdminConfigTool folder under the Secure Private Access installation folder (for example, cd “C:\Program Files\Citrix\Citrix Access Security\Admin\AdminConfigTool”)

• Run the following command:

  .\AdminConfigTool.exe /UPLOAD_PUBLIC_GATEWAY_CERTIFICATE <PublicGatewayUrl> <PublicGatewayCertificatePath>

Application enumeration failure

Application enumeration breaks if the StoreFront URL or the NetScaler Gateway URL contains a trailing slash (/).

Resolution:

Delete the trailing slash in the StoreFront store URL or the NetScaler Gateway URL. For details, see Update StoreFront or the NetScaler Gateway server details after the setup.

Miscellaneous

First-time setup cannot be completed

You might not be able to re-configure license server if the Director configuration failed during the first-time setup.

Resolution:

Manually clean up the license_server table.

Create Secure Private Access diagnostics support bundle

Perform the following steps to create a Secure Private Access diagnostics support bundle:

• Open the PowerShell or the command prompt window with admin privileges.
• Change the directory to the Admin\AdminConfigTool folder under the Secure Private Access installation folder (for example, cd “C:\Program Files\Citrix\Citrix Access Security\Admin\AdminConfigTool”).

• Run the following command:

  .\AdminConfigTool.exe /SUPPORTBUNDLE <output folder>

SQL database permissions for Secure Private Access

For automatic database creation, the Secure Private Access plug-in host machine must have the permissions to connect to the database and create the database schema.

Remote database:

Perform the following steps to set up the permissions for a remote database.

1. Create an empty database with the name syntax CitrixAccessSecurity<Site Name>. Here <Site Name> is the Secure Private Access site name. (for example. CitrixAccessSecuritySPA).

   CREATE DATABASE CitrixAccessSecurity<SiteName>

2. Create an SQL server login for the machine identity for the Secure Private Access virtual machine. For example, if your Secure Private Access broker machine name is HOST1 and the machine domain is DOMAIN1, then the machine identity is “DOMAIN1\HOST1$”. If the login is already created, then you can ignore this step.

   USE CitrixAccessSecurity<SiteName>

   CREATE LOGIN [DOMAIN1\HOST1$] FROM WINDOWS

   Domain name can be found using the following query:

   SELECT DEFAULT_DOMAIN()[DomainName]

3. Assign the db_owner role to the machine identity.

   USE CitrixAccessSecurity<SiteName>

   EXEC sys.sp_addrolemember [db_owner], 'DOMAIN1\HOST1$'

   ALTER USER [DOMAIN1\HOST1$] WITH DEFAULT_SCHEMA = dbo;

Local database:

Perform the following steps to set up the permissions for a local database.

1. Create an empty database with the name syntax CitrixAccessSecurity<Site Name>. Here <Site Name> is the Secure Private Access site name. (for example, CitrixAccessSecuritySPA).

   CREATE DATABASE CitrixAccessSecurity<SiteName>

2. Create an SQL server login for the NT AUTHORITY\SYSTEM user. If the login is already created then you can ignore this step.

   USE CitrixAccessSecurity<SiteName>

   CREATE LOGIN [NT AUTHORITY\SYSTEM] FROM WINDOWS

3. Assign the db_owner role to the “NT AUTHORITY\SYSTEM” user.

   USE CitrixAccessSecurity<SiteName>

   EXEC sys.sp_addrolemember [db_owner], 'NT AUTHORITY\SYSTEM'

   ALTER USER [NT AUTHORITY\SYSTEM] WITH DEFAULT_SCHEMA = dbo;

When you manually create the database, the downloaded database script adds the permissions to the machine identity.

Change log level for troubleshooting logs

Troubleshooting logs are the default error log level.

To change the log level for the troubleshooting logs, in the runtime service appsettings.json (C:\Program Files\Citrix\Citrix Access Security\Runtime\RuntimeService) update restrictedToMinimumLevel for TroubleshootingSql to one of the following values:

-  Information
-  Debug
-  Warning
-  Error

"TroubleshootingSql": {
  "restrictedToMinimumLevel": "Error",
  "batchPostingLimit": 50,
  "batchPeriod": "00:00:05" // 5 seconds
}