Latest Contributions by DannyKrouk

Introduction This article addresses a basic use case like you might have in a pre-production environment.  All the ArcGIS Enterprise components (Portal, Server, and Data Store) exist on a single machine on an internal network.  The BIG-IP reverse proxy allows the system to be presented to another network (could be an internal client network or a public network) with all client traffic routed through the BIG-IP appliance.    This article is divided into three main sections.  The first section is intended for the ArcGIS Enterprise administrators and orienting them to their tasks in the language and terms they understand.  The second section is intended for the BIG-IP administrator, hopefully speaking to them in the language and terms that they understand.  The final section addresses additional options and details appropriate to both sets of administrators.  The goal of this article is to help ArcGIS and F5 administrators to work together by describing a proven set of procedures around which to collaborate.  This article does not seek to enable ArcGIS administrators to configure F5 themselves (or vice versa).  It is assumed that ArcGIS administrators are experts in ArcGIS and rely upon Esri documentation for details.  Similarly, it is assumed that F5 administrators are experts in BIG-IP and rely upon F5 documentation for details. While the use case is “basic”, the undertaking is not “simple”.  Success requires integrating technology and knowledge from several specialized domains (Esri technology, F5 technology, networking, certificates, etc.).  If the procedures in this article are not clear enough for action in your organizational context, it may be an indication that outside consulting support would be beneficial. This article is built on the following use case specifics: Use of F5’s BIG-IP as a “OSI Layer 7” or “full proxy” Use of ArcGIS Enterprise where the Web Adaptor is deployed with IIS on the Windows operating system ArcGIS Administrator Instructions The focus of the ArcGIS administrator is to deploy the ArcGIS Enterprise such that it is ready to be proxied by the F5 BIG-IP reverse proxy.  The deployment objective is depicted in the diagram below.   Depending on the specific requirements, it may not be necessary to deploy Web Adaptors when using a reverse proxy.  However, it is recommended that you do so for the following reasons: Using Web Adaptors reduces the configuration complexity in the BIG-IP reverse proxy. Web Adaptors allow you to validate the correctness of the ArcGIS Enterprise system independent of the reverse proxy; this can be very valuable in the case of troubleshooting. While Web Adaptors can be deployed on Linux-based systems using a Java Web Server, the frequency of deployment on Windows with IIS is why this initial guide focuses on that pattern. Step One: Design Decisions and Communication with F5 Administrators In this configuration, clients will address ArcGIS Enterprise through the reverse proxy.  The reverse proxy presents a CNAME (“DNS alias”, shown in green in the diagram below) which terminates the HTTPS sessions from the clients.  It then re-initiates new HTTPS sessions from itself to the web server that hosts the web adaptors.  The web server usually presents a certificate with the subject name of the A record (the host name, shown in red in the diagram) which terminates the incoming HTTPS sessions from the BIG-IP reverse proxy.   Before deploying your system, you need to make the following decisions: What is the CNAME (“DNS Alias”) under which the reverse proxy will represent the ArcGIS Enterprise system? What are the “contexts” (“Web Adaptor names”, shown in blue in the diagram) for the Portal for ArcGIS and ArcGIS Server Sites? You likely need to cooperate with your F5 administrators to agree upon the CNAME and ensure that they have a TLS certificate appropriate to terminate HTTPS communications on that CNAME.  At the same time, you can share with the F5 administrators the name (the A RECORD) of the machine on which your web server will operate and to which requests should be forwarded. Step Two: Deploy a Web Server with TLS Certificate It is useful to deploy your web server and configure it with a TLS certificate for HTTPS traffic before you do anything with ArcGIS Enterprise directly.  This allows you to make sure HTTPS is working with your web server, and it allows F5 administrators to configure the reverse proxy for the web server early in the process.  This allows early validation of the TLS certificate and HTTPS pathways. Configure HTTPS on Your Web Server Configuration steps to enable HTTPS with web servers vary by web server brand.  Since IIS is a very common web server, Esri has provided instructions for how to configure it for HTTPS as part of its Web Adaptor installation guide: https://enterprise.arcgis.com/en/web-adaptor/latest/install/iis/enable-https-on-your-web-server-server-.htm. When you enable HTTPS on your web server, you will need to provide a TLS certificate.  Among other attributes, certificates have Subjects and Subject Alternative Names (SAN’s).  The Subject of the certificate should match the name that the BIG-IP reverse proxy will use to address the web server.  This is often the A RECORD (machine1.domain.local in the diagram).  The SAN is a list of alternative names.  A good practice for SAN’s is to include: The Subject name (e.g., machine1.domain.local) The short version of the subject name (e.g., machine1) The CNAME that the reverse proxy will present (e.g., gis.domain.com), if possible Depending on your organization’s certificate authority and policies, you may or may not be able to put the CNAME in the SAN.  The benefit of doing so is that it allows you greater ability to validate the ArcGIS Enterprise independent of the reverse proxy. Validate Once your web server is configured for HTTPS, you should validate your configuration.  First, you should validate by navigating to your web server directly in a browser using the HTTPS protocol.  Second, if your F5 administrators have configured the BIG-IP reverse proxy to forward traffic to your web server, you can then navigate to the reverse proxy’s virtual server endpoint in a browser, also using HTTPS.   In each case, you want to confirm that you get no certificate warnings, and the target page draws correctly. Typically, web servers will have a default page which is returned when you go to the web server root.  That is a good option.  A better option is to deploy a web page that allows you to see more about what is going on.  The showHeaders pages (one for ASPX/IIS and one for JSP: https://github.com/dannykrouk/showHeaders) will echo back many useful details as shown below:   Consider deploying and using the showHeaders page to your web server and using it as the target for both your web server and reverse proxy tests.  If you deploy the page to the root of your web server, you can test with these requests: https://machine1.domain.local/showHeaders.aspx https://gis.domain.com/showHeaders.aspx Step Three: Deploy and Configure ArcGIS Enterprise  The ArcGIS Enterprise deployment here is a “single-machine base deployment” (https://enterprise.arcgis.com/en/get-started/latest/windows/base-arcgis-enterprise-deployment.htm#ESRI_SECTION1_690F8D4A3ABE4FB8AE926C118E9F8299).  Install and Configure the Basics Documentation to take you through the installation steps is available on Esri’s web site: https://enterprise.arcgis.com/en/documentation/install/. In this article, the Portal for ArcGIS’s Web Adaptor name (“context”) is “/portal” and the Hosting Server’s Web Adaptor name is “/server”.  When you federate your Hosting Server Site with your Portal for ArcGIS, you may use the Web Adaptor for both the Services URL and the Administration URL (https://enterprise.arcgis.com/en/portal/latest/administer/windows/configure-servers.htm), so long as you are not using Web Tier authentication.  If you are using Web Tier authentication, your Administration URL should follow this pattern:  https://machine1.domain.local:6443/arcgis. Validate the Basics; "System Confidence Check" Once you have your Web Adaptors configured and your Hosting Server federated, you should perform a brief “system confidence check” of the system to make sure the core functions work correctly.  A typical system confidence check would involve: Login to /portaladmin Validate Federation Publish a service Share the service The “confidence” that one establishes with these steps is that the deployed system does not have any fundamental configuration flaw that would prevent basic operation. Whatever you create (e.g. a published service) in the system confidence check should be deleted before you continue. Final Configuration for the Reverse Proxy The final configuration step is to configure the WebContextURL for the Portal and the Hosting Server.  This property is how each Esri server knows the name by which clients will address it through the BIG-IP reverse proxy. Portal for ArcGIS: https://enterprise.arcgis.com/en/portal/latest/administer/windows/using-a-reverse-proxy-server-with-portal-for-arcgis.htm#ESRI_SECTION1_7C753FB1F19349A398E5FFCC6079A821 {    "WebContextURL": "https://gis.domain.com/portal" } ArcGIS for Server: https://enterprise.arcgis.com/en/server/latest/deploy/linux/using-a-reverse-proxy-server-with-arcgis-server.htm#ESRI_SECTION1_13680C9069E14B1F8AE5793BE1ED25A6 {    "WebContextURL": "https://gis.domain.com/server" } Step Four: System Validation The fourth and final step for the ArcGIS administrator is “system validation”, independent of the BIG-IP reverse proxy.  If you validate this way, and something doesn’t work when requests flow through the reverse proxy, then the reverse proxy configuration is what needs attention.  If you do not validate this way, it can be much more complicated to establish the source of the problem. Temporarily Change Name Resolution on the Web Server Machine The trick to this validation is to temporarily convince the system that the CNAME (gis.domain.com) is at the ArcGIS Enterprise machine (machine1.domain.local).  If you have local administrator permissions on the machine1.domain.local machine, you can edit the hosts file.  If machine1.domain.local has the IP address 10.0.0.10, then the host file entry would look like this: 10.0.0.10        gis.domain.com This says, “gis.domain.com can be found at 10.0.0.10”. When you complete your edit to this file (which is usually found here: C:\Windows\System32\drivers\etc\hosts), open a command prompt and confirm that your setting is effective with ping: C:\>ping gis.domain.com Pinging gis.domain.com [10.0.0.10] with 32 bytes of data: Reply from <IP Address of machine1>: bytes=32 time=22ms TTL=124 … The result from the ping command should be the IP address in your hosts file, the placeholder value highlighted above for clarity. Test in a Browser on the Web Server Machine Now, open a web browser on machine1.domain.local and run your “system confidence check” again, this time addressing the system by its CNAME (https://gis.domain.com/portal/home/).   If your system functions correctly this way, back-out the hosts file change and ask the F5 administrators to complete their configuration work. F5 Administrator Instructions From a BIG-IP perspective, this is a simple configuration.  The ArcGIS Enterprise system has several components.  But, from the standpoint of the reverse proxy, there is a single back-end web server node listening on HTTPS/443.  The one configuration element that may be different to other systems is that ArcGIS Enterprise requires the reverse proxy to include an X-Forwarded-Host header. At a high level, your proxy configuration will be terminating all HTTPS traffic to the gis.domain.com CNAME and re-initiating HTTPS to the single back-end node, machine1.domain.local.  The web server at this address supports two “contexts”, one for each major component of the ArcGIS Enterprise system (Portal for ArcGIS and ArcGIS Server): /portal and /server.   As described in the introduction of this article, we assume that you have three networks associated with your BIG-IP proxy, a client network, a server network, and your administration network. This article assumes you are an expert in BIG-IP administration and only need cues to the steps to configure this virtual server and backend pool in the optimal order. Step One: Proxy the Web Server The CNAME for this system should have been established with you or communicated to you.  A matching TLS certificate for that CNAME should also be provided.  The certificate authority must be one that is trusted by the clients of this system. Install the TLS Certificate Install the TLS certificate for the Virtual Server in BIG-IP (e.g., Subject gis.domain.com) System > Certificate Management > Traffic Certificate Management > SSL Certificate List > Import SSL Certificate Create Client SSL Profile Create a client profile to terminate client TLS connections on the certificate for the gis.domain.com name. Local Traffic > Profiles > SSL > Client > Create   Create a Pool with a Simple Monitor Create a backend Pool for the web server (e.g. https://machine1.domain.local/ ) with a Simple Monitor to determine whether the node resource is “up” or “down”. Local Traffic > Pools > Pool List > Create   Create an HTTP Services Profile (Add the X-Forwarded-Host Header) The X-Forwarded-Host header allows ArcGIS Enterprise to know the value of the Host header that arrived at BIG-IP.  The ArcGIS Enterprise system will check this value against its configuration to ensure that clients have addressed it in an appropriate way.  If the X-Forwarded-Host header is not present, or contains a wrong value, ArcGIS Enterprise will issue an HTTP redirect to signal how it believes it should be addressed.  This can result in redirect loops.  In the case that ArcGIS Enterprise detects a redirect loop, it will break it and return an error. An X-Forwarded-Host header can be included with an iRule: when HTTP_REQUEST {         HTTP::header insert X-Forwarded-Host [HTTP::host] }   This directive takes the value of the arriving request’s Host header and sets it as the X-Forwarded-Host header value to the default pool. Create the Virtual Server Local Traffic > Virtual Servers > Create Select “Standard” for Type of Virtual Server.  Specify your SSL Profile (Client) you created earlier with your SSL certificate.  In specifying a Server profile, the configuration objective is to achieve a TLS tunnel to the backend.   This can be accomplished with the default “serverssl” setting within BIG-IP.  Set “Source Address Translation” to Auto Map.  On the Resources tab, select your pool that you created before.   Step Two: Validate Proxying Through to ArcGIS Enterprise There are two steps to validate the effectiveness of this configuration.  Validate Trust and Headers Assuming the showHeaders.aspx page was deployed on the backend web server, use a web browser to navigate to https://gis.domain.com/showHeaders.aspx.  The browser should be free of certificate trust warnings.  The page response body should prove-out the effectiveness of the X-Forwarded-Host header aspect of your configuration.     At this point, with the header flow through to the backend confirmed, there is no longer a need for the showHeaders.aspx tool.  If your system is intended for PRODUCTION, or any environment where the information exposes should not be exposed, the tool should be removed. Validate Effectiveness with ArcGIS Enterprise In a web browser, navigate to https://gis.domain.com/portal/home/ and click the “Sign in” link.  If you see a page in which credentials can be provided, this validates the effectiveness of the X-Forwarded-Host header relative to the ArcGIS Enterprise configuration.  If this test fails, the most likely cause is a disagreement between the value of the header and the corresponding WebContextURL configuration in ArcGIS Enterprise. Optional validation steps include: Confirm that the second ArcGIS Enterprise server role (ArcGIS Server) is accessible: https://gis.domain.com/server/rest/services. Determine the behavior when an unsupported context is used such as https://gis.domain.com/not-a-real-context/.  In this case, we expect an HTTP 404 code from the web server in the pool. At this point, the configuration of the system is complete, and it may be passed on for acceptance testing. Final Thoughts Having completed the instructions thus far, you should have a fully functional ArcGIS Enterprise system accessible via F5’s BIG-IP reverse proxy.  Congratulations.  This article offers the following closing thoughts. Testing These instructions stipulated “system confidence checks” and validations throughout the deployment/configuration process.  These measures were meant to determine whether it was reasonable to continue to the next step in the instructions.  These measures do not prove that the system is acceptable.  By the end, we assume that the entire system functions.  In other words, these tests establish that the system has functional coherence. Passing the system on for acceptance testing is the appropriate next step.  The goal of acceptance testing is to measure the deployed system against the business goals it must support. Health Checking The Simple Monitoring included in the instructions to the F5 administrators allows the BIG-IP to stop forwarding requests to the ArcGIS Enterprise system if the node (i.e., machine1.domain.local) is down or inaccessible.  For a system like this, with only one back-end Pool member, this (a Simple Monitor) is the full extent of the recommended health checking.  In principle, BIG-IP can be configured with out-of-band health checks that ask the ArcGIS Enterprise software to confirm its health or validate that specific HTTPS requests succeed with particular response payloads.  For example, the Portal for ArcGIS component of ArcGIS Enterprise exposes this endpoint: https://developers.arcgis.com/rest/enterprise-administration/portal/health-check-portal.htm.  In a single node system, the response to a health check problem essentially eliminates all access to the system.  The upside of this is that the reverse proxy can provide a generic error to clients that the system is down.  The downside of this is that a temporary problem, partial problem, or misinterpretation through the health check eliminates all access to the system when it might be still serviceable for many use cases.  The probability of false negatives (unhealthy findings) associated with formal/complex health checks may result in less system reliability to end users relative to the false positives (healthy findings) associated with the simple node monitoring.  In other words, for a single-node system complexity is the enemy of reliability; stick to a Simple Monitor. Credits This article was produced based on the work of Roger Schlogel, a consultant with Esri’s Professional Services.     ... View more

Introduction GIS Enterprise Reporter now has a companion application “er_compare.exe” that allows you to compare two ArcGIS Enterprise systems. This is the fourth article in the GIS Enterprise Reporter series.  If you are not familiar with the series, this is the first article: Introducing the GIS Enterprise Reporter.  Why is Comparison Useful? There are many reasons why you might want to compare two ArcGIS Enterprise systems.  GIS Enterprise Reporter envisions the following motivations: You are setting up a Disaster Recovery Site.  In this case, you may wish to understand that the deployments and configuration are sufficiently compatible to allow you to use the webgisdr tool to synchronize the content. You have a Production and one or more lower environments.  In this case, it may be useful to understand the nature and extent of the differences between the Production environment system and the other(s). How to Compare Comparison is a three-step process: Use GIS Enterprise Reporter to generate outputs (“admin” and/or “content” at the initial release of this tool) for the two systems you wish to compare. Run “er_compare.exe” against those output files. Open the resulting Excel document and review its comparison notes Step #1, the use of the GIS Enterprise Reporter tool, has been described in other blog articles in this series.  Please refer to those if you would like more guidance on how to generate outputs for an ArcGIS Enterprise system. The remainder of this blog article will focus on steps #2 and #3. Run "er_compare.exe" The application can be run by double-clicking on the er_compare.exe executable.  When run in this way, you may briefly see a command window appear.  It will be replaced with a graphical user interface as shown here. Navigate to the two output files that you wish to compare from the two systems; those will be your “File One” and “File Two”.  You can compare the “admin” outputs of two systems to see how the administrative configurations and services inventories compare.  Or, you can compare the “content” outputs of two systems to see the differences/similarities between the Portal content. “File One” is typically the “source” system, the one that you consider to be the standard against which you want to measure the other system.  For example, if you have a primary data center and a stand-by data center, the primary data center would be “File One”.  Or, if you have a Production system and a Pre-Production system, Production would be “File One”. The application will suggest an output file location and name based on your inputs.  But, you may name it and place it wherever you like.  Then, click the “Compare” button. The tool will report its progress in the lower status pane of the application.  When it is complete, it will change the “Compare” button into a “Dismiss” button. Note that you can also run the tool on the command-line.  If you do so, provide three space-delimited arguments for “File One”, “File Two”, and “Output File” and the application will do the same thing as it does from the graphical user interface. Review the Comparison Excel Document The application accepts Excel inputs and creates a new Excel output.  The output Excel will have one sheet for each pair of input file sheets that it attempted to compare.  If the input files do not have the same number or kind of sheets, the output will note the “missing” sheets from “File Two” relative to “File One”.  Note that the application does a logical comparison of sheets based on what they represent, not their literal names.  It uses the GIS Enterprise Reporter “site number” to know, in the case of multiple federated ArcGIS Server Sites, which sites are logically comparable. The first sheet is always “Comparison_Metadata”.  It has the structure show below: An "Admin" Comparison Example The remaining sheets will be named for the input sheets that they compare.  For example, “portalAdmin” compares the Admin API sheet from each Portal.  An example of a comparison output for it appears here The column layout is the same for all sheets.  The columns are: DifferenceSeverity The likely relative importance of the difference. DifferenceComment A brief description of what is found to be different. TypeOfSource This is somewhat redundant with the name of the sheet. RecordOne The information that it found in “File One”. RecordTwo The compared information that it found in “File Two”. ProcessingErrorInformation In the case that the application is not able to make the comparison it intends for some reason, there may be additional information about why in this column.   The portalAdmin example above shows that the tool has identified one “Error” and three “Warnings” (the rows in all sheets are color-coded by these classifications).  The Error shown here is that there are a different number of “redirectURI’s” for the “arcgisonline appId”.  These appId’s are used as part of the ArcGIS Enterprise OAuth security implementation.   Note that the application is not comparing the values.  The values across two systems can be different.  Instead, it is comparing the number of redirectURI’s.  It does not know how many there should be.  But, it assumes that the “source system” (“File One”) has been configured according to your intent and the other system should be a numerical match for the number of redirectURI’s.  The first Warning is reporting on a difference in the number of licensed members between the two systems.  The second system may or may not have “enough” licensed members; that is for you to decide.  All this tool can do is note that there are different numbers. The second and third Warnings are noting that the source system is configured for Windows users whereas the second system is configured for “Built-In” users. These are just examples.  The tool does not report on any comparisons for which it does not find a difference of concern.  In other words, in perfectly matched systems, the comparison sheets will be empty.  The screen capture below shows another example; a comparison of the Server Admin API for matching federated Server Sites between the two ArcGIS Enterprise systems. The first Warning is that the number of platform services between the two ArcGIS Server Sites is different.  It is not easy to see what the difference is in the “RecordOne” and “RecordTwo” cells.  But, if you were to study the JSON there carefully, you would see that the “source” system has a “Message Bus” platform service, in addition to a “Synchronization” and a “Compute Platform”.  The other system has only “Synchronization” and “Compute Platform”.  Likely, this indicates some difference in what has been installed or licensed for this Site between the compared systems. The second Warning is that the “source” system supports HTTP_and_HTTPS whereas the other system supports only HTTPS.  This might be because the “source” system was upgraded from a prior release whereas the other system was a fresh installation.  Or, it might be an indication that the “source” system has the preferred configuration and the other one should be matched to it. The third and fourth Warnings aggregate the member and processor resources across all of the machines in the Sites and report differences.  Again, these differences may be intentional or not, the application cannot know.  But, a common source of problems is an inadvertent difference in machine resources.  Note that the tool sums the memory and cpu from all of the machines in the Site.  So, if you have different numbers of machines, these aggregates will have different values even if the per-machine resources are identical. In the final row, there is an example of an “Information” difference.  The log settings (the “logLevel”) are different between the two systems.  This should not cause a problem for most use cases.  But, it may be relevant to know. The final example here shows the “Information” comparisons of the service “analytics”. In this case, the application is reporting that the numbers of services of various kinds, their instancing, etc. is a match between the compared systems.  A "Content" Comparison Example The sheets in the “content” comparison output are likely easier to understand.  Below is an example which shows the sheets you can expect and an example of one of the sheets. As you might expect, the “Users” sheet will report on any users in “File One” that are not in “File Two” … and vice verse.  The same is true for “Groups” and the other sheets. The InventoryAnalytics detail shown here is comparing the aggregate counts and sums of the content in each system.  In the case of Production and Pre-Production environments, this can be useful to get a sense of “how different” the content is.  And, in the case of a Disaster Recovery content synchronization, this can be useful to confirm that all of the content is the same between the two systems after the synchronization. Understanding Comparison The preceding examples of the sheets and comparison rows are a small sample of what the application does.  You should bear in mind that the application does not compare everything.  It only compares differences that are likely to be meaningful or interesting in some way.  The application does not, for example, compare the names of the machines between systems.  However, it will report if the count of machines is different.  And, for similar reasons, it does not compare the subjects of self-signed certificates when comparing certificates.  Rather, it matches the serial numbers of all the non-self-signed certificates on the assumption that the certificates that have been imported in one system should also be in the other system. You should not expect the application to catch all meaningful differences.  The comparison logic is based upon the real-life experiences of Esri Professional Services in helping customers with “Enterprise Migration”, “Disaster Recovery”, “Content Promotion”, “Lower Environment Usage Protocols”, etc.  So, the body of knowledge changes over time based on experience.  At this time the comparison logic is not documented.  If you have an interest in a particular type of comparison, feel free to send an email inquiry to dkrouk@esri.com.  I can report on the nature of the comparison that is currently implemented in the application.  And, if an additional comparison is appropriate, I can plan a new comparison feature. You should also expect “false negatives”; differences that are not important to you.  You should think of all differences, even “Error” differences as potentially significant, but not necessarily significant.  You must use your judgement to determine whether a difference is meaningful to your situation. The output rows have classifications like “Error”, “Warning”, and “Information” in the normal cases.  However, you may also see classifications like “ProcessingConcern”, “ProcessingWarning”, or “ProcessingError”.  These indicate either insufficient input information for the tool to carry-out its intended comparison or an internal error in executing its comparison logic.  In the former case, this typically indicates a difference between your systems or differences in the parameters used when you ran GIS Enterprise Reporter.  In the latter case, an internal error, the ProcessingErrorInformation column will have information about the internal error.  This is, essentially, a log of sorts that can be used to help me troubleshoot the internal error.  So, when you see this kind of issue, please bring it to my attention so I can troubleshoot: dkrouk@esri.com. What to do with the Comparison The best practice pattern with comparison is to do it at least twice: The first comparison is to discover the differences and decide whether and what to do about them. The second comparison is to confirm that the differences you chose to address were, in fact, successfully addressed. Final Thought Hopefully, this tool helps you in your ArcGIS Enterprise administration work.  If you have questions or ideas for improvement, please be in contact: dkrouk@esri.com.             ... View more

Introduction GIS Enterprise Reporter provides a lot of information about the content and configuration of an ArcGIS Enterprise.  Among the outputs available is an "admin" Excel workbook.  That workbook's sheets contain information available from the Admin API's of each server role in the ArcGIS Enterprise (Portal and all of the federated ArcGIS Server Sites).  For each federated ArcGIS Server Site, there are several sheets that describe aspects of the services inventory. This is the third article in the GIS Enterprise Reporter series.  If you are not familiar with the series, this is the first article: Introducing the GIS Enterprise Reporter.  Generating the "Admin" Excel The default execution parameters of GIS Enterprise Reporter will generate the "Admin" Excel output.  The "Admin + Services Inventory" checkbox creates and populates the workbook from the Admin API.  The "With Analytics" checkbox will calculate a variety of aggregate statistics and other information of interest from the raw outputs, placing them in additional sheets in the same Excel workbook.   The workbook will be placed in the output directory and will bear a name indicating the name of the ArcGIS Enterprise followed by "_admin_" and a timestamp as shown here: Understanding the Services Content Within the Admin Excel workbook, each federated ArcGIS Server site will have a series of tabs that begins with a number, the name of the site, and a suffix.  Finding the Basics An example of the main sheets for a federated Site appears below: Each federated Site is given a number by GIS Enterprise Reporter.  In this example, we are looking at site number "1".  And, the site name is dannyk_esri_com (the DNS name by which the Site is known).  The suffixes have the following meanings: serveradm: Information extracted from the Admin API about how the Site is configured. serverdat: If the site is a Hosting Server Site, this sheet will provide a little bit of additional information about the Data Store. serversvc: An exhaustive list of all of the properties of all of the services in the ArcGIS Server Site.  If you need to know any particular fact about a service that ArcGIS Server knows, it can be found here. serversvn: A "normalized" listing of the most commonly used properties of the services in the ArcGIS Server Site.  The sheet is more useful to understand the services inventory over-all. The "Normalized" Services Listing The "normalized" services listing is a good place to start.  Each line is a service and some essential pieces of information about it. The first row has filters that can be used to focus on information of particular interest. The Detail in "serversvc" The "serversvc" sheet has one line per service property.  This makes it less convenient for understanding the big picture.  But, if you want to know the recycleStartTime, the portalProperties, or the referenced datasets, they are available here. Exploring the Analytics If you selected "With Analytics" there will be two additional sheets for each federated ArcGIS Server Site.  Their names include only the site number assigned by GIS Enterprise Reporter and a suffix indicating their content. svc_datasets The svc_datasets sheet is a listing of all of the datasets referenced by the dedicated instance services in the Site (Hosted Services and Shared Instance services do not include this information in the ArcGIS Server Admin API).  As with the other sheets, it is filterable if you wish to focus on particular services or datasets. The dataset information is formatted as it is in ArcGIS Server: datasetname followed by the workspace from where it comes. svc_analytics "svc_analytics" contains a variety of calculated statistics about the services (and the service instances) in the Site. The first few statistics are about the services over-all.  However, most of the statistics are focused on only those services that are running. The "Total Minimum Instances Per Node (started)" is of interest because this is the number of instances that exist as soon as ArcGIS Server starts.  The "maximum" statistic is the upper limit.  However, it is almost never the case that all services have their maximum instantiation at the same time. Statistics are presented by "provider" (indicating something about how the service was published and how it runs) and "type" (indicating something about what it can do).  As noted, these statistics focus on the services that are running, and their min/max instancing. Conclusion Hopefully, these Excel worksheets provide information that help you better understand and manage the services in your ArcGIS Enterprise.  If you have ideas for improved information, please share it with me: Danny Krouk (dkrouk@esri.com). The next article in this series explores how to compare GIS Enterprise Reporter outputs to gain insight into meaningful differences between systems: Comparing ArcGIS Enterprise Systems.               ... View more

The GIS Enterprise Reporter user interface is intended to have few options in the hopes that it is relatively straight-forward to execute.  In principle, you give it a Portal for ArcGIS "Target", with an administrative credential for that Portal, tick some checkboxes, click "Execute", and wait for it to complete.     There are some things that benefit from explanation.  This article will offer information on the following topics: Where should I run this application? How should I run this application? What value should I put in the "Target"? What are some common problems (and solutions)? What do the options (checkboxes) mean? Where Should This Application Be Run? GIS Enterprise Reporter can, in principle, be run from anywhere that it can communicate to your Portal for ArcGIS.  However, there are better and worse locations.  The application works by asking Portal about itself and its federated ArcGIS Servers.  This means that Reporter wants to communicate with the federated Servers in the same way that Portal does.  Various aspects of your configuration and network rules may mean that communicating from your personal computer with Server cannot happen through the same means as Portal.  How would you know?  Not easily.  So, how could you protect yourself against this possibility?  The easiest way to do that is to run the application from within your server network.  For example, you could run it on the machine on which Portal runs. How Should this Application Be Run? It is not necessary to run Reporter as a local machine administrator.  However, doing so will usually allow it to gather more information for you.  And, it may help you to overcome some potential execution challenges. If you wish to run the application as a local machine administrator (assuming you are a member of that local machine Administrators group), right click on the enterprise_reporter.exe executable and select "Run as administrator" from the context menu.   You may or may not receive a message from your operating system or security software that discourages you from running this application.  This application is digitally signed by Esri with a chain of authority from a public Certificate Authority.  So, it is unlikely that the message will mention certificate trust.  But, if it does, you may wish to explore importing the trust chain into your trusted repository.  To initiate the "installation" workflow for the certificate, follow the steps show in the screen capture below :   Selecting "Current User" and "Automatically select the certificate store based on the type of certificate" are the appropriate options on the "Install Certificate" wizard panels.  This may relieve you of the warning. Or, if you are a machine administrator, you may have options to execute the application.  To do so, you may have to click buttons that say things like "More Options", "Run Anyway", etc. ... depending on what is issuing the warning and your rights.  For example:   These technical methods are not offered to circumvent the guidance of your organization with respect to third party executables.  Please use the privileges granted to you by your organization responsibly.   The Reporter application only runs on Windows.  However, you can use it to report on an ArcGIS Enterprise on Windows or Linux.  In the event that your Enterprise is on Linux, running Reporter as a local machine administrator does not produce any additional output information in the report documents.  The only reason to run Reporter as local machine administrator in that case is to give you more options in response to an unsigned application warning if you receive one. What Is the Right Value for "Target"? There are three basic options: The FQDN ('portalmachine.domain.com') of the machine The 7443 endpoint for Portal ('https://portalmachine.domain.com:7443/') The WebContextUrl for Portal ('https://proxy.domain.com/portalcontext') The first two options amount to the same thing.  If you enter the FQDN of your Portal machine (either machine in the case of a two-machine "high-availability" Portal), Reporter will fix-it up into option #2 for you.  In addition to being relatively straight-forwards, this is usually the best option for "Target" value as well.  So, it is recommended that you use the FQDN (fully-qualified domain name) of a Portal machine (the machine's "A RECORD"). Of course, this implies that your network will allow you to get to Portal's 7443 port from where you are running Reporter.  This is why the first tip encourages you to run Reporter on your server network because it is on that network that this network pathway will be allowed. The third option is to provide the WebContextUrl (or Web Adaptor-style address) as the target.  This generally works.  However, Reporter only knows about "Portal tier authentication".  So, if this pathway (WebContextUrl) involves "web tier authentication" or requires SAML, OIDC, etc., Reporter will not be able to authenticate.   As you might be able to infer, the values for "Admin user" and "password" must be a user that has administrative rights on your Portal and is authenticated at the Portal tier.  This certainly includes Portal's "Initial Administrator Account".  But, you can also use any other account that is a Portal administrator and can get a token directly from Portal's 7443 REST endpoints. Common Problems and Solutions The application comes with a Microsoft Word document which includes a section on Troubleshooting.  If you are having a problem, you should consult that first.   The most common problems are usually having to do with access to the token REST endpoint.  Those problems are best avoided by running the application from the server network and using the machine FQDN as the target address.  The message in the application will look like this: Exception while acquiring token. Please use a browser to check the url: https://<f.q.d.n>:7443/arcgis/sharing/rest/generateToken and credentials. As you can see, it asks you to validate that the URL target to get a token is reachable from the machine on which you are running Reporter.  If you can get to that endpoint, then try generating a token.  If you can do both of those things, Reporter will run. What Are the Checkbox Options? At a high-level, the checkboxes have the following implications: "Admin + Services Inventory": This touches all of the REST endpoints in the Admin APIs for your Portal and your federated Servers.  It records all of the configuration information of your Enterprise, lists all of its services and their properties, etc.  The information is quite broad and deep. This makes it very valuable.  But, it can be challenge to get a high-level picture.  The specific contents of this file output will be explored in future articles. "Diagram": The diagram provides a high-level picture of the logical structure of your Enterprise.  This is an example from a very simple (development environment) system: "Certificate Analysis": Reporter does its best to connect to each of the HTTPS endpoints in your Enterprise (i.e. Reverse proxies, Web Adaptors, Portal's on 7443, Server's on 6443, etc.), discovering the certificates and reporting on various facts like certificate subjects, expirations, and trust chains.  There are several sheets in the Excel, each sheet corresponding to a different HTTPS access pathway.  For example: "Portal Content Inventory":  This output is created by stepping through Portal's Sharing API.  It lists all of the content in the Portal, along with its "metadata" (content type, owner, etc.).  And, it can provide lists of users, groups, etc.  This output will also be explored in more detail in future articles. "Migrator Artifacts (advanced)":  This is, as the name implies, an advanced option.  Most users will never need this.  This option does two things.  The first is that it writes out the json from the REST endpoints into a subdirectory.  So, if you are someone that likes working with json, you can find it all there.  Second, when it finds sufficient information in Portal to export out "service definitions", it will do so.  This can be helpful if you wish to re-publish services.  If you published your service through ArcGIS Pro, it was very likely to story the service definitions there such that Reporter can access them.   Conclusion Hopefully, this article has provided a useful orientation to how to run the GIS Enterprise Reporter tool.  As mentioned, it comes with a Microsoft Word document that provides additional information.  Should you run into challenges or have questions that are not clearly addressed, please be in touch through the contact information in that document.  You may post comments questions here also, if you wish. Prior Series Article: Introducing the GIS Enterprise Reporter Next Series Article: GIS Enterprise Reporter: Making the Most of Services Outputs      ... View more