Troubleshoot issues using the diagnostic tool or the ADM GUI
The diagnostic tool is applicable only for the ADC instances onboarded or to be onboarded using the Citrix ADM connect based low-touch onboarding.
For more information, see Low-touch onboarding of Citrix ADC instances using Citrix ADM connect.
When you onboard an ADC instance onto Citrix ADM, you might experience a few issues that prevent the ADC instance from successfully onboarding. As an administrator, you must know the reason for the onboarding failure. You can perform diagnostic checks using the diagnostic tool when you:
Experience any issues during auto-onboarding or script-based onboarding
Want to ensure if the ADC instance is ready to onboard
Want to analyze issues for the already onboarded ADC instances that show “Down” status in the Citrix ADM GUI
If ADM service connect is enabled on the ADC instance, the diagnostic details are automatically sent to Citrix and you can view details in the ADM GUI. If ADM service connect is not enabled, you can manually use the diagnostic tool.
Manually use the diagnostic tool
The diagnostic tool is available as part of the
mastools upgrade (13.1-2.x or later) and accessible at
/var/mastools/scripts. You can verify the
mastools version by running the
cat /var/mastools/version.txt command in the ADC instance.
To run the diagnostic tool:
Using an SSH client, log on to the ADC instance.
Type shell and press Enter to switch to bash mode.
The tool starts and displays the results for the following diagnostic checks:
Instance to ADM connection
If the issues still persist even after troubleshooting, you can contact Citrix support. When you contact Citrix support, you must provide the ADM connect configuration information that is displayed after you run the diagnostic tool.
The following is an example of diagnostic results for an ADC instance that has no issues:
1 – Displays the type of diagnostic check
2 – Displays the diagnostic check results either in green or in red. Green indicates the result is successful and red indicates the result is not successful.
3 – Displays the Citrix ADM configuration information in yellow each time you run the diagnostic tool. If you want to contact Citrix support, you must provide this information.
Validate the ADC instance readiness for onboarding using the diagnostic tool
Before you onboard the ADC instance to Citrix ADM, you can check the readiness of the ADC instance, by running the diagnostic tool on the ADC instance. If the ADC instance has no issues and ready to onboard, the tool displays the device not claimed on ADM message.
View ADC diagnostic information in ADM GUI
Navigate to Infrastructure > Instances > Citrix ADC and click Asset Inventory to see the newly added Onboarding Readiness option that provides the ADC instance onboarding readiness status such as Needs Review or OK.
Needs Review. The ADC instance has issues that need to be fixed.
OK. The ADC instance is ready to onboard.
If the Onboarding Readiness appears blank, it means the ADC instance is not running with the latest image that has diagnostic support.
If the ADC instance has any issues, the Needs Review option appears, and you can click to view more details.
After you click Needs Review, the ADC Diagnostics Details page displays the issue details.
Category. Provides the issue category.
Status. Provides the issue status such as Needs Review, OK, or Not Applicable.
Recommendation. Provides the required recommendation to troubleshoot the issue.
After you fix the issue, the status in the Onboarding Readiness gets changed to OK.
The following are some of the ADC instance issues and their troubleshooting steps:
Invalid user name or password
Workaround: Ensure the user name and password provided in the Admin profile are correct. If you have modified the ADC instance password, you must modify the admin profiles of the instances. For more information, see Modify the admin profile.
DNS configuration error
Workaround: Ensure the DNS is configured or the DNS IP address is valid. For more information, see DNS configuration.
No internet connection
Workaround: Ensure that the firewall setting is not blocking the internet access and the required proxy is configured.
No connection to Citrix ADM endpoint
Workaround: Ensure to check firewall settings and the following Citrix ADM endpoints are not blocked in the firewall:
ADM_GRP_EP = "adm.cloud.com" ADM_AGENT_EP = "agent.adm.cloud.com" ADM_TRUST_EP = "trust.citrixnetworkapi.net" ADM_DOWNLOAD_EP = "download.citrixnetworkapi.net" <!--NeedCopy-->
If no issue found in the diagnostic checks and the no connection issue still persists, make a note of the Citrix ADM configuration information (available in yellow) and contact Citrix support.
When you perform a test run to ensure that the ADC instance is ready to onboard, the following issues maybe seen:
Built-in agent dry run timeout
If the results of the dry run are not fetched within 5 minutes, a Timeout message appears.
Recommendation: It is recommended that you verify whether the ADC instance is running with the latest image that has diagnostic support. Also, in the Asset Selection table, the Onboarding Readiness column appears blank.
Red outline on the device profile dropdown
ADC authentication fails during the dry run and a red outline appears on the device profile dropdown.
Recommendation: Re-enter the ADC user admin credentials again, create the device profile and click Test to run the dry run again.