Batch Deploying ArcGIS Monitor 2024.0 Agents

[GeoJosh]

• Introduction
• Requirements
• Usage
• InstallAgents
• ConfigureAgents

Introduction

ArcGIS Monitor 2024.0 was released on August 27th, 2024. One major change in this version is that the ArcGIS Monitor Agent software is required on all machines in the ArcGIS Enterprise environment that you wish to collect metrics on. This is different from previous releases, where metrics could be collected on all components using a single agent.

To make the deployment of agents across the environment quicker, my colleague @GeoJen and I have written a set of scripts to automate the process.

The first script, InstallAgents, takes a list of machines, connects to the targets remotely, and installs the ArcGIS Monitor Agent 2024.0 software. The second, ConfigureAgents, takes a list of machines, connects remotely, completes the Agent post-installation steps, and completes registration with your ArcGIS Monitor Server.

The scripts can be downloaded here.

Requirements

To use these scripts, you must:

• Be running Windows
• Have ArcGIS Monitor Server 2024.0 installed and configured.
• Have the ArcGIS Monitor Agent 2024.0 installer downloaded on a central location.
• Be running Powershell 5.1 or above
• Be an administrator on the machine where the script is run and on the machines targeted for Agent configuration.
• Have credentials for an ArcGIS Monitor Server user with the Administrator role.

Usage

InstallAgents

1. Open a Powershell 5.1 prompt and change directories to the folder where you downloaded the scripts to.

2. Launch the script:

.\InstallAgents.ps1

3. Provide a commas-separated list of machines where Agents should be installed:

Target Machines (comma-separated list): machine1.esri.com,machine2.esri.com,machine3.esri.com

4. Enter the credentials for the account that will be used to run the ArcGIS Monitor Agent service:

Connection Credentials
Enter credentials for a user who is an administrator on all target machines
User: myDomain\josh
Password for user myDomain\josh: ****************

5. Provide the path to the ArcGIS Monitor Agent installer directory. This should be the folder that contains Setup.exe:

ArcGIS Monitor Agent Installer: C:\Users\<username>\Documents\ArcGIS Monitor 2024.0\MonitorAgent

After completing these steps, the script will create a remote Powershell connection to each machine specified and install the software. The output will look like this for successful installations:

*********************
machine1.esri.com
*********************
Creating remote session...
Copying installer to remote destination...
Installing ArcGIS Monitor Agent 2024.0...
Installation successful!
*********************
machine2.esri.com
*********************
Creating remote session...
Copying installer to remote destination...
Installing ArcGIS Monitor Agent 2024.0...
Installation successful!

ConfigureAgents

1. Open a Powershell 5.1 prompt and change directories to the folder where you downloaded the scripts to.

2. Launch the script:

.\ConfigureAgents.ps1

3. Provide a commas-separated list of machines where Agents are installed and need to be configured with ArcGIS Monitor Server:

Target Machines (comma-separated list): machine1.esri.com,machine2.esri.com,machine3.esri.com

 4. Enter the ArcGIS Monitor Server URL that the targeted Agents should be configured with:

ArcGIS Monitor Server URL: https://monitorserver.esri.com:30443/arcgis

5. Enter the username and password of an ArcGIS Monitor Server user that has the Administrator role:

ArcGIS Monitor Server Credentials
Enter credentials for an administrator user in ArcGIS Monitor Server
User: adminuser
Password for user adminuser: *************************

After completing these steps, the script will create a remote Powershell connection to each machine specified and configure the ArcGIS Monitor Agent software with ArcGIS Monitor Server. The output will look like this for successful configurations:

*********************
machine1.esri.com
*********************
Creating remote session...
Checking for ArcGIS Monitor Agent installation...
Trying to reach ArcGIS Monitor Agent via HTTP...
ArcGIS Monitor Agent reachable!
Configuring with ArcGIS Monitor Server...
[ success ]  Successfully authenticated to ArcGIS Monitor Server
[ success ]  Successfully registered to ArcGIS Monitor Server
*********************
machine2.esri.com
*********************
Creating remote session...
Checking for ArcGIS Monitor Agent installation...
Trying to reach ArcGIS Monitor Agent via HTTP...
ArcGIS Monitor Agent reachable!
Configuring with ArcGIS Monitor Server...
[ success ]  Successfully authenticated to ArcGIS Monitor Server
[ success ]  Successfully registered to ArcGIS Monitor Server

[HannahHe1]

The system requirements for the agent remain unchanged from the previous release? 

[GeoJosh]

@HannahHe1, the system requirements for Monitor 2024.0 can be found here.

[JeffMertzXcel]

@GeoJosh consider modifying the script to use the INSTALLDIR parameter on the setup command. Most places I have worked at do not install 3rd party software to the C: drive

[CaseyBurns]

First, appreciate @GeoJosh for this information. I have many systems I'll need to push this out to, so this is very helpful. However, it does appear that there is an issue with the ConfigureAgents script.

The first script provided installs the agent and works without any problem. The second script that configures the agent, however, doesn't work well at all and fails on almost all machines. I have identified two problems with the configure agent script, one of which I've fixed. 

Problem 1 = The script is missing a -credential switch in the code. The following line needs to be corrected:

Without this -credential switch, the remote sessions can (and usually) fail if you attempt these scripts separately.

Problem 2 = The ConfigureAgents script is attempting to use an active directory username/password instead of an internal username/password for ArcGIS Monitor. The line below, needs to be changed to reflect internal ArcGIS Monitor user. 

This script requires two methods of Authentication (Active Directory, ArcGIS Monitor application) but only has accounted for one. I am trying to fix this script, and need help understanding the --password switch (can be found in the screenshot above).  I keep receiving errors that say it's requiring a secure string - I know what a string is, but what is the format? Providing the error below.

If you can give me any and all info on the arcgis-monitor-agent.exe command line list, that would be really helpful as I should be able to resolve my issue with that information. Alternatively, you could update the script to include the two details I've mentioned above. Thanks again!

[CaitBoyer]

Hihi-- Just adding my two cents here as I was having trouble getting the tool to run, but I figured it out and hope my experience helps others. I found that even if I provided a correct path to the ArcGIS Monitor Installer, it didn't seem to find the files and was instead looking in the *\DeployAgents\ folder for the Setup.exe and the  (and, obviously, not finding them).

Example error: 
Copy-Item : Cannot find path 'C:\Temp\DeployAgents\Install.htm' because it does not exist.

Copy-Item : Cannot find path 'C:\Temp\DeployAgents\Setup.exe' because it does not exist.

Once I just copied the contents of the MonitorAgent folder (containing all the setup files) into the *\DeployAgents\ folder, it worked like a charm. 

I also had to run it with Set-ExecutionPolicy Unrestricted on (at my SysAdmin's advice). 

Thanks for this awesome tool!

--- 

EDIT TO ADD: I also ran into the same issue as @CaseyBurns but was able to get the script to run further with the suggestions in their post. Thank you!

I tried to be cheeky and add an administrator user into my Monitor application with the same credentials as the Domain account, but I was not so lucky.

Additionally, I had a novel error RE: "Internet Explorer not available" seen here: 

Solved by adding -UseBasicParsing after the Invoke-WebRequest in line 41

[GeoJosh]

Hi@CaseyBurns,

The script is missing a -credential switch in the code. The following line needs to be corrected:

-Credential was deliberately left off because we assume that the user running the script has admin access to the target machine (see bullet point 5 in the original post under "Requirements"). If this is true, then the script block should run as the current user on the remote machine.

The ConfigureAgents script is attempting to use an active directory username/password instead of an internal username/password for ArcGIS Monitor. The line below, needs to be changed to reflect internal ArcGIS Monitor user.

GetNetworkCredential().Username is simply pulling the Username value from the credential object created at the beginning of the script, which do not necessarily have to be domain/network credentials. As long as you provided the username and password for an ArcGIS Monitor Server user with the admin role for that prompt, they should be parsed correctly.

Please try reverting to the original script, run it as a user who is an admin on the local machine and the target remote machines where you wish to configure monitor, and ensure you provide an ArcGIS Monitor Server username and password for the prompt ArcGIS Monitor Server Credentials.

If you're still seeing this failure, send me a DM for further troubleshooting.

Josh

[CaseyBurns]

Hi @GeoJosh , thanks for the response. 

First, I would like to say that I would think that most people using this are probably system admins of some sort, and practice using separate accounts for security purposes. (Standard user accounts for most work performed, admin accounts used to access machines remotely.) This is a standard IT practice, and I would expect that the other users who aren't admins REALLY need to be able to specify simply because they won't have the ability to run the script from an admin account.

After reading your response and looking at it from a different viewpoint, I understood your script and tested it out. It was at exactly a 50% success rate, literally failing every other machine stating username and password was wrong (see below)

This did not make sense, I knew I was logged in as a domain admin account and obviously the script is going to use the same username and password each attempt. I re-ran the scripts, this time running on the leftover machines that failed the first time and still received a 50% failure rate.

My thoughts on that, might be that a quick pause or wait might be needed in between systems. I've seen instances where attempting to login more than once in a quick succession causes problems with other applications. In any case, this is enough for me to work with - I may have to run the script a few times but it's still better than manually installing on each.

Thanks again!!

Casey

[anasga_81182]

Hi @GeoJosh ,

I would like to point out that the script .\InstallAgents.ps1

.\InstallAgents.ps1

does not honor ArcGIS Monitor Agent Installer

ArcGIS Monitor Agent Installer: C:\Users\<username>\Documents\ArcGIS Monitor 2024.0\MonitorAgent

as it assumes that the setup files exist in the same directory as installagent.ps1 if the setupfiles does not exist there it will fail. now when i have copied the setupfiles to the same directory as installagent script the script runs smoothly without a problem 

as i m checking the script, i did not find a problem there as it should be working as expected but i do not why it behaves like this now

Thanks buddy for the script quite helpful 🙂
//Anas 

[AYUSHYADAV]

Hi,

Will it work with ArcGIS Monitor on Windows and agents on Linux?

Thanks

Ayush

[GJameson]

We are having problems with the InstallAgents.ps1 script.
I verified we are running PS v5.1 on our gismonitor server that we are trying to deploy the InstallAgents.ps1 file from.
The script is running as localdomain.local\admin

PS C:\Windows\system32> C:\Users\admin\Documents\ArcGIS Monitor 2024.0.2\MonitorAgent\InstallAgents.ps1
Machines list parsed successfully! Machines:
datastore.localdomain.local,image.localdomain.local,portal.localdomain.local,server.localdomain.local,web.localdomain.local
ArcGIS Monitor Agent Installer: 'C:\Users\admin\Documents\ArcGIS Monitor 2024.0.2\MonitorAgent'
*********************
datastore.localdomain.local
*********************
Creating remote session...
Copying installer to remote destination...
Get-ChildItem : Cannot find drive. A drive with the name ''C' does not exist.
At C:\Users\admin\Documents\ArcGIS Monitor 2024.0.2\MonitorAgent\InstallAgents.ps1:36 char:5
+ Get-ChildItem $InstallerDir | ForEach-Object { Copy-Item -Path $_ ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : ObjectNotFound: ('C:String) [Get-ChildItem], DriveNotFoundException
+ FullyQualifiedErrorId : DriveNotFound,Microsoft.PowerShell.Commands.GetChildItemCommand

Installing ArcGIS Monitor Agent 2024.0...
The term './Setup.exe' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try
again.
+ CategoryInfo : ObjectNotFound: (./Setup.exe:String) [], CommandNotFoundException
+ FullyQualifiedErrorId : CommandNotFoundException
+ PSComputerName : datastore.localdomain.local

I'm feeling a little foolish as we've tried the following for the setup location without success:
"C:\Users\admin\Documents\ArcGIS Monitor 2024.0.2\MonitorAgent"
`C:\Users\admin\Documents\ArcGIS Monitor 2024.0.2\MonitorAgent`

'C:\Users\admin\Documents\ArcGIS Monitor 2024.0.2\MonitorAgent'

SOLVED: One needs to type out the path into powershell without ANY quotes above. Hopefully this helps another powershell novice.

[DEWright_CA]

Does this support doing in-place upgrades for machines also? I have a 2023.1 implementation that we need to upgrade.

[JeffMertzXcel]

@DEWright_CA It *should* as per upgrade instructions, you will not uninstall the previous version. Just change the deployment location of the new installer and running Setup.exe should take care of the rest. I have yet to try this, but we will be upgrading here soon with this procedure. I will post the results. 

[DEWright_CA]

@JeffMertzXcel then it isn't really upgrading, it's installing another instance that you would need to uninstall the older one.

Or am I missing something?

[Mike_Tulis]

Thank you! I was able to use the scripts to automate the upgrade 38 Agents  (2024.0.1 to 2024.1.1). 

[JeffMertzXcel]

@DEWright_CA wow- this post got old really quick! Anyway, yes, it is an upgrade/overwrite/replace operation. You do not uninstall the agent first. The PS script we used worked as advertised. We just replaced with 2025 version in the local "staging" directory and the script pushed and installed just as before. Then we ran the configure agent script. All is well.

[DEWright_CA]

@JeffMertzXcel now I am intrigued; we just had ESRI run us through a 2023 to 2024.1 upgrade.

@GeoJosh ; do you know if this has been tested/used with 2025?

[JeffMertzXcel]

@DEWright_CA we ran into some issues with upgrading to 2024.1 in regard to some rogue items in Monitor database, so we decided to go ahead and start fresh in the lower environments and go ahead and use the latest 2025 version. Regardless, the agents just get replaced via the script. Our old version was 2024.0.1