Set up a reverse proxy server with ArcGIS Notebook Server

A reverse proxy server is a computer that is deployed within a perimeter network (also known as a demilitarized zone [DMZ] or screened subnet) that handles requests from the Internet and forwards them to the machines in your internal network. By forwarding requests, the reverse proxy server masks the identity of the machines behind your organization's firewall, protecting internal machines from direct attack by Internet users. Additional security functions can be implemented in the reverse proxy server to further protect your internal network from outside users.

You can configure your ArcGIS Notebook Server site to use your organization's reverse proxy server. This is optional. If your organization does not use a reverse proxy, or if you don't want to configure your ArcGIS Notebook Server site to use one, you can proceed to configure your site with a portal.

Add ArcGIS Notebook Server to your reverse proxy server

Your organization's reverse proxy server must be configured to communicate with ArcGIS Web Adaptor by adding the corresponding URLs to the proxy directives.

For example, if you're using Apache as a reverse proxy server, you need to add the ArcGIS Web Adaptor URL to the ProxyPass directives in the Apache web server configuration file httpd.conf as follows:

ProxyPass /notebook https://notebookserver.domain.com/notebook
ProxyPassReverse /notebook https://notebookserver.domain.com/notebook

Most reverse proxy servers have a configurable client connection timeout. The websocket connections used by ArcGIS Notebook Server to communicate with the Python kernel will be disconnected when the connection timeout is reached, and a notification will appear within the notebook. If this happens at a consistent interval, for instance every 1, 3, or 5 minutes after reconnecting to the kernel, the connection timeouts to the network path should be investigated and increased accordingly.

Set the WebContextURL property

If you're using a reverse proxy server and the URL to your site does not end with the default string /arcgis (all lowercase), you should also set the ArcGIS Notebook Server WebContextURL property. This helps ArcGIS Notebook Server construct the correct URLs on the resources it sends to the end user.

Note:

Use the WebContextURL property to set the ArcGIS Notebook Server URL to match that of its ArcGIS Web Adaptor (such as /notebook).

Do the following to change the WebContextURL property:

1. Sign in to the ArcGIS Notebook Server Administrator Directory at https://notebookserver.domain.com:11443/arcgis/admin as a user with administrator privileges.
2. Click system > properties > update.
3. In the Properties text box, insert the following JSON, substituting your own ArcGIS Notebook Server URL as seen by users outside your organization's firewall:

   {
      "WebContextURL": "https://notebookserver.domain.com/notebook"
   }

4. Click Update.
5. Restart ArcGIS Notebook Server. On Linux, execute the stopnotebookserver.sh and startnotebookserver.sh scripts located in the installation folder.

Reverse proxy headers and ArcGIS Notebook Server

When integrating your reverse proxy with ArcGIS Web Adaptor, the following property must be set in the header sent by the reverse proxy server:

X-Forwarded-Host=<FQDN of reverse proxy server>

If this property is set in the header, ArcGIS Web Adaptor will return requests to the reverse proxy server that match the reverse proxy server's URL. For example, a request to the ArcGIS Notebook Server Services Directory (https://reverseproxy.domain.com/arcgis/rest/services) will be returned to the client as the same URL.

If the X-Forwarded-Host header property is not set, ArcGIS Web Adaptor may return the URL of the internal machine where the request was directed, for example, https://notebookserver.domain.com/arcgis/rest/services instead of https://reverseproxy.domain.com/arcgis/rest/services. This is problematic, as clients will not be able to access this URL (commonly noted as a browser 404 error). Also, the client will gain some knowledge about the internal machine.

When troubleshooting communication between clients and ArcGIS Web Adaptor, it is recommended that you set the X-Forwarded-Host header property in the reverse proxy server, as this is a common cause of communication failures. The way you set this header varies depending on your reverse proxy server implementation.

For guidance on how to pass the original host header, see the product documentation for your reverse proxy server.

Configuring your reverse proxy server for a highly available ArcGIS Notebook Server site

When implementing a reverse proxy server that has multiple backend targets running ArcGIS Web Adaptor registered with a single ArcGIS Notebook Server site, there are additional considerations that must be taken into account.

ArcGIS Notebook Server uses websocket connections to communicate with the Python kernel. These websocket connections create a stateful session that must be maintained by the reverse proxy configuration. This is referred to as session stickiness, and it requires a layer 7 (application) load balancer to achieve.

Correct session stickiness can be achieved in Apache with the following:

Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED

<Proxy balancer://web_adaptors_https>
    BalancerMember https://notebook1.domain.com:443 route=notebook1
    BalancerMember https://notebook2.domain.com:443 route=notebook2
    BalancerMember https://notebook3.domain.com:443 route=notebook3

    ProxySet lbmethod=byrequests
    ProxySet stickysession=ROUTEID
</Proxy>

It is also important to proxy the secure websocket (WSS) connections to the same backend targets:

<Proxy balancer://web_adaptors_wss>
    BalancerMember wss://notebook1.domain.com:443 route=notebook1
    BalancerMember wss://notebook2.domain.com:443 route=notebook2
    BalancerMember wss://notebook3.domain.com:443 route=notebook3

    ProxySet lbmethod=byrequests
    ProxySet stickysession=ROUTEID
</Proxy>

Example: Configure Apache and Tomcat with ArcGIS Notebook Server

You can configure a reverse proxy with ArcGIS Notebook Server using any web server software. The following sample workflow describes the steps to set up a reverse proxy using Apache HTTP Server and Apache Tomcat. This is one example of a reverse proxy configuration, not definitive instructions.

This sample workflow uses the following software and versions, all installed on the same machine as ArcGIS Notebook Server:

• Red Hat Enterprise Linux Server 7.5
• Apache HTTP Server , httpd 2.4.6
• Apache Tomcat 9.0.20 / OpenJDK 1.8.0

These software components can also be in a distributed architecture, with ArcGIS Notebook Server, Apache HTTP Server , and Apache Tomcat all on separate machines.

The following steps begin after ArcGIS Notebook Server and Mirantis Container Runtime have been installed and configured, and an instance of ArcGIS Web Adaptor has been installed on a Java web server but has not been configured.

1. Install Tomcat to run on port 8080 using the Apache JServ Protocol (AJP), which is enabled by default.
2. Because port 8443 is not enabled by default on Tomcat, enable SSL and add a connector for port 8443.

   This involves generating an SSL certificate and editing the Tomcat configuration file to add the connector. As a security best practice, only TLS version 1.2 should be enabled.

   ...
   sslProtocol="TLS" SSLProtocol="TLSv1.2"
   ...

3. Deploy the arcgis.war file for the existing ArcGIS Web Adaptor (Java Platform) to Tomcat.

   For this example, the ArcGIS Web Adaptor URL is /nbs.

4. Install Apache HTTP Server .

   For this example, the yum package manager is used. The SSL capabilities are also installed using yum.

   yum install httpd -y
   yum install mod_ssl -y

5. Configure an SSL certificate for the Apache HTTP Server in its ssl.conf file.
6. Modify the Apache httpd.conf file using proxy rules (as discussed in the previous section) to proxy ArcGIS Web Adaptor calls to the AJP port of Tomcat.

   ProxyPass /nbs ajp://myserver.acme.com:8009/nbs
   ProxyPassReverse /nbs ajp://myserver.acme.com:8009/nbs

7. In the Apache HTTP Server ssl.conf file, use proxy rules to proxy ArcGIS Web Adaptor SSL calls to the AJP port of Tomcat. It's important to also proxy WebSocket requests, which are used by ArcGIS Notebook Server; if WebSocket requests are not handled properly, ArcGIS Notebooks will not open properly.

   SSLProxyEngine On
   # Use RewriteEngine to handle WebSocket connection upgrades
   RewriteEngine On
   RewriteCond %{HTTP:Connection} Upgrade [NC]
   RewriteCond %{HTTP:Upgrade} websocket [NC]
   RewriteRule /(.*) wss://myserver.acme.com:8443/$1 [P,L]
   <Location "/nbs">
       ProxyPreserveHost On
       ProxyPass ajp://myserver.acme.com:8009/nbs
       ProxyPassReverse ajp://myserver.acme.com:8009/nbs
   </Location>

8. Restart the Apache HTTP Server service for the configuration changes to take effect.
9. Configure ArcGIS Web Adaptor with ArcGIS Notebook Server.