Skip To Content

Migrate ArcGIS Enterprise with WebGISDR

Organizations may want to migrate an existing ArcGIS Enterprise organization from one machine (or set of machines) to another. Among the reasons to do this are to migrate to newer hardware or a newer operating system. There are a few common methods for conducting this type of migration, including:

The WebGISDR tool is commonly used as it doesn't impact the work in your production environment. Although the steps involved with this method will likely take more time than the Join Site approach, it is considered a safer method.

Carefully review the following considerations and Migration strategies to ensure you choose the method that best suits your deployment.

Considerations for using the WebGISDR tool

Before deciding to migrate using the WebGISDR tool, it is important to ensure that it is the best method for your organization. Carefully review the following:

  • Administrators can migrate existing machines to new machines without making any changes to their production environment.
  • The success of a migration can be validated before switching over to a new environment.
  • The tool supports moving between any combination of single machine and highly available deployments.
  • This migration method cannot be used to migrate to a different operating system.
  • Your original and new environment must meet the prerequisites for running the WebGISDR tool. The organization URL and services URLs must be identical across environments, which is addressed in Host name resolution methods.

To use the WebGISDR tool to migrate your organization, first determine your workflow. The steps will be dependent on your current and desired deployment types and your organization's needs. Your chosen method of host name resolution will impact your workflow, so ensure that you review each method before starting.

Host name resolution methods

To set up a second environment, the components in the new environment must be configured with the same public URLs as the primary environment. There are a few ways you can do this:

  • Use an \etc\hosts entry to resolve the fully qualified domain name (FQDN) of the public URLs to a different endpoint
  • Redirect traffic until the software is configured
  • Configure your DNS so that the standby machines resolve the public URL to a different IP address than the primary machines

The included workflows for migrating machines will follow the first option of using the \etc\hosts file. See the following sections for more information on each method.

Option 1: Modify the \etc\hosts file

You can take advantage of the \etc\hosts file on the new machines to resolve the FQDN of the desired public URL to a different component, such as another Web Adaptor or reverse proxy. The \etc\hosts file, located under C:\Windows\System32\drivers\etc, is used to resolve host names by entering IP addresses and associating the IP address to host names.

For example, if the machine name has an IP address of and is resolved to through DNS, you can add an entry to the \etc\hosts file on the machine to resolve the machine's IP address to a different hostname,

If you ping in a command prompt, the \etc\hosts file resolves to, which is If a web server is running on the machine, it can be reached through or

Option 2: Redirect traffic until the software is configured

If you are able to redirect traffic away from your production environment for a short period of time, configure the component that is directing traffic to your production environment to send traffic to your non-production environment.

This may mean that you need to re-register the Web Adaptor with the new machines or update your reverse proxy or load balancer to send traffic to the new machines within the non-production environment. This only needs to be done when you are ready to federate and set the server as the hosting server.

This approach may be considered the easiest, but it can present issues for organizations who cannot easily make changes to their production environment.

To follow this workflow, you must have provisioned your new machines with the non-production environment and installed and configured Portal for ArcGIS, ArcGIS Server, and ArcGIS Data Store. After you register ArcGIS Data Store with the server site, you can complete the following steps:

  1. Redirect traffic to the non-production environment.
    • If you're using ArcGIS Web Adaptor, register the Web Adaptor with the new machines.
    • If you're using a reverse proxy or load balancer, update the configuration to send traffic to new machines.
  2. Federate the portal and server sites in the non-production environment by using the same public URL for the services URL as the production environment.

    The administration URL used during federation must be a URL that only resolves to the non-production machines. The administration URL can also be updated following the migration with no interruption in service.

  3. Set the federated server as the hosting server in the target portal.
  4. Redirect traffic back to the production environment.
    • If you're using the Web Adaptor, register the Web Adaptor with the original machines.
    • If you're using a reverse proxy or load balancer, update the configuration to send traffic to the original machines.

Option 3: Configure your DNS so that the standby machines resolve the organization URL to a different IP address than the primary machines

Alternatively, you can configure the standby environment DNS to resolve the FQDN of the public URLs differently depending on if you're on the primary machines or the standby machines. This is commonly referred to as a split DNS or split-horizon DNS. An additional Web Adaptor, reverse proxy, or load balancer is required for this method, as the public URL has to be accessible to federate the portal and server site.

This approach is functionally equivalent to modifying the \etc\hosts files, but managed through DNS rather than an \etc\hosts file.