Monthly Linux Tip: Troubleshooting ArcGIS Web Adaptor on Linux

“How do I troubleshoot this?” If you have ever asked this question when registering the Web Adaptor in a Linux environment, then this blog is for you. This blog will provide a comprehensive troubleshooting guide to help when registering the Web Adaptor on Linux.

Specifically, we will investigate the following two common errors:

• “Unable to configure the [Portal | ArcGIS Server] with the Web Adaptor. Please make sure that the server machine is running and that the account specified has administrative privileges to the site”.
• “Unable to connect to Portal URL: https://<MachineName>:7443”.

The troubleshooting investigated is broken down into the following four sections: Preliminary, Logging. Networking, Web Server.

NOTE: This blog assumes that you have previously installed and configured Portal for ArcGIS and/or ArcGIS Server.

1. Preliminary

With both of these errors, some preliminary first steps can be taken. Below are some options:

• Is Portal for ArcGIS and/or ArcGIS Server even running? In your Linux terminal, run the command top -c to see if the expected process is running.
• Is a GUI accessible on the Linux machine? If so, try accessing the Web Adaptor Configuration page (https://WebServerURL/webadaptorname/webadaptor) in the browser and see if the error persists.
• If you are silently configuring, verify that your syntax is correct in the ./configurewebadaptor.sh. Linux is sensitive, one-character mismatch will result in an error being thrown back.
• Are you entering the right credentials when registering? For example, in a browser, navigate to ArcGIS Server Manager and enter the same credentials you are using to register the Web Adaptor. Do these exact same credentials allow you to log in?
• Do you have firewall settings that are blocking a successful registration of the Web Adaptor?

If none of the above seem to work, looking at the logs is out next line of defense.

2. Logging

As with any error, one of the first troubleshooting measures is to start with the logs. Depending on your web server, the process of troubleshooting logs will differ. We will focus specifically with Tomcat in this blog.

Catalina is Tomcat’s internal servlet container and is responsible for several of Tomcat’s key functions, including logging. With that said, investigating the Catalina logs will be helpful in troubleshooting. To do so, navigate to <Tomcat installation directory>/logs. By default, Tomcat’s logs are defined at the level “FINE”.

Below is an example of my Tomcat logs after receiving the error “Unable to connect to Portal URL”:

As we can see, there are multiple instances where my Portal machine was not found. Going back to my ./configurewebadaptor.sh command and my syntax, I was incorrectly typing my machine name. Once fixed, now the logging shows that the “PortalWebAdaptorConfig.updateConfigFile Properties file is updated” translating to a successful registration of my Portal Web Adaptor.

Tomcat logs can help to determine factors such as if the ArcGIS Web Adaptor is not successfully deployed to Tomcat, if Tomcat can properly connect to ArcGIS Server or Portal for ArcGIS, and other useful information.

If the logs don’t help, try seeing if there are any underlying network issues.

3. Networking

When exploring networking, many factors play a part, but we will focus on a few.

• Domain Name System (DNS). When silently configuring, the ./configurewebadaptor.sh mandates using the -w flag. This flag handles the Web Server URL. If the DNS being used for the Web Server URL is not properly configured, then you will not be able to configure the Web Adaptor. Run the command nslookup <DNSAlias> to verify if your DNS is valid.
• Ensure that there are no disruptions going on with the network. It is not uncommon for discrepancies in the network to cause an error while registering the Web Adaptor.
• Per best practice, Web Adaptors typically reside in a demilitarized zone (DMZ), away from other ArcGIS Enterprise components. Because of this, it is critical to ensure your DMZ can communicate to the machine where ArcGIS Server or Portal for ArcGIS is installed on. Running a simple ping command on both of these machines will verify if the machines can successfully communicate.

If the network appears to check out, try investigating the actual Web Server itself for any configuration issues.

4. Web Server

Sometimes the issue may not be the Web Adaptor, but with the Web Server itself. While every environment is unique, there are general troubleshooting steps that can be taken on your web server.

• Are you using a supported Web Server? If you are attempting to register a Web Adaptor with a Web Server that isn’t listed in the System Requirements, there is no guarantee that it’ll work. The same principle applies for supported Web Servers with a version BELOW the minimum listed version.
• Does the Web Server have the appropriate permissions to allow for the Web Adaptor to be registered properly? Before registering the Web Adaptor, you have to ensure the Web Adaptor is properly deployed to your Web Server. If the Web Server lacks permissions for the Web Adaptor, this can cause an issue.
• Have there been changes to your Web Server lately? If you restart the Web Server, does registering the Web Adaptor work?

Conclusion

These methods do not encompass all of the options available to help register your Web Adaptor on Linux. However, hopefully this has given you further insight on how to better troubleshoot.

Feel free to let me know your thoughts in the comments below and thank you for reading this Monthly Linux Tip!