Troubleshooting Article - Xinet Pilot

Overview

This article explains how to troubleshoot issues related to accessing the Xinet Pilot application correctly. Some of the common symptoms related to this topic are:

• Users see the blue "To use Xinet Pilot, type the URL to your Xinet server in the preferences sheet above" alert, despite having this configured. Removing "/PORTAL/Pilot" from the URL in preferences and then Quitting and Reopening the app provides temporary relief until restarting the computer.

• Within the server access_log, you see a blank GET request when the blue screen appears.

• User is seeing only a White Blank screen when attempting to connect their Xinet Pilot to Portal.

• Seeing the following within error_log: [php7:warn] [pid 1631] [client 172.16.136.1:51099] PHP Warning: templates::create_parser(PORTAL/libs/PILOT.inc.php): failed to open stream: No such file or directory in /usr/etc/portal/PORTAL/libs/STYLES.obj.php on line 168

• Seeing the following when installing Xinet Pilot on macOS Catalina or later, "‘Xinet Pilot’ can’t be opened because Apple cannot check it for malicious software. This software needs to be updated. Contact the developer for more information."

Workflow

Instructions

When an end-user reports any issues with the Xinet Pilot app, taking a few moments to collect screenshots and details about the end-user system before troubleshooting can save time later on. Most trouble can be traced back to configuration trouble on the end user's device. 

1. Verify the macOS version where the installation fails
2. Try to reproduce on the latest release
3. Verify the URL in Pilot Preferences
4. Review the Apache logs

1. Verify the macOS Version where the installation fails

Starting in the most recent releases of Xinet (2021.4), support for the older versions of macOS has been dropped. When seeing issues with Xinet Pilot installations on macOS, this is often the best first thing to check. You can reference the matrix below for quick guidance based on the version they are running:

Running macOS Catalina (10.15) or later

Starting in this version of macOS, Apple has included a number of new security features that may impact your end-users ability to install or launch Xinet Pilot. If you are running an older version of Xinet, you may encounter an alert stating that "‘Xinet Pilot’ can’t be opened because Apple cannot check it for malicious software. This software needs to be updated. Contact the developer for more information."

In the 21.x releases of Xinet Pilot, this security check has been addressed. If you are unable to update Xinet Pilot, see Unable to Install Xinet Pilot 20.x on macOS Catalina or later for guidance on using a workaround to bypass the macOS Gatekeeper security check.

Installation Issues on Older macOS Versions

If you are encountering installation issues with Xinet Pilot on an older release of macOS, it is suggested that you consider updating your end-users machine. As active support for these older versions ended with the most recent releases of Xinet, defects identified within these versions are unlikely to be addressed by Engineering. 

If you are running an older release of Xinet, please open a Support Ticket directly and our Support Team will do our best to assist troubleshooting.

2. Try to reproduce on the latest release

Independent from the Xinet Server and Xinet Portal versions, the Pilot version can also vary. As an initial check, it is always worthwhile to have the end-user verify the behavior on the most recent release of Xinet Pilot.

If the trouble is not present on the latest release, this was likely caused by an addressed defect, and it is suggested that all end-users update to avoid reproducing this trouble.

If the trouble persists on the latest release, consider also verifying whether this is an OS-specific issue.

Isolate to the macOS or Windows release of Pilot

The macOS and Windows versions of the Pilot app are commonly on differing releases due to the variances in their host OS. For this reason, it is possible that the trouble seen can be isolated to a particular OS release of Pilot.

Taking steps to identify the scope of the trouble can assist the Support and Development teams with identifying and developing solutions promptly. This can be a common reason for the inability to reproduce reported issues.

3. Verify the URL in Pilot Preferences

This blue alert often appears during the initial setup of Xinet Pilot; however, if this continues to appear, it may indicate trouble with the HTTP/S or DNS configuration on the client device. 

Check the Server URL, ensuring that HTTPS is being used.

Within the Preferences menu of the Pilot application, double-check that the correct domain has been set, ensuring that HTTPS is being used.

Reference the article below, based on the end user's OS:

• • Configuring Xinet Pilot in Windows
  • Configuring Xinet Pilot for Mac OS

Adjust the domain name to the Xinet Server IP

If the domain name has been correctly set, but the trouble persists, confirm that the issue is not related to DNS Name resolution. To do so, replace the URL domain within the Pilot Preferences with the public IP address of the Xinet Server.

4. Review the Apache Logs

Xinet Pilot acts as a browser connecting directly to your Xinet Portal site. For this reason, you can review the Apache logs to get a better look at any access or errors related to the trouble you are seeing.

• The access_log and ssl_access_log can help understand better where traffic may be failing.
• The error_log and ssl_error_log can help review if any explicit errors are being thrown.

Do you see blank GET Requests?

If adjusting the Server URL values does not resolve the trouble with connecting, it may be related to the Pilot App failing to establish its Portal connection before the network adapters are online. If you see blank HTTP Get requests/redirects as shown below within the Apache Access log, follow the steps within Xinet Pilot continually showing the blue "Configure Xinet Server URL" screen on restart of the computer.

Do you see a blank white screen?

If you see a blank white screen when Pilot connects to your Xinet Portal site, it may result from a defect within certain releases of Xinet Portal.

If you see the error, "PHP Warning: templates::create_parser(PORTAL/libs/PILOT.inc.php): failed to open stream: No such file or directory in /usr/etc/portal/PORTAL/libs/STYLES.obj.php on line 168" within your Apache Error logs, reference the steps within macOS Pilot 21.1.39 loads to a Blank White Screen when connecting to Xinet 2021.1 or 2021.2 to address this trouble.