Menu Close

Assigning Gateways and Agents to Management Servers using PowerShell


Just publishing some common PowerShell agent and Gateway assignment commands I use on a frequent basis for SCOM:


A common issue I find in customer environments, is that they do not set their agents to be able to fail over to multiple Gateways, or they do not set their Gateway servers to be able to fail over to multiple management servers.

When you assign an agent to a gateway – by default it will ONLY talk to that one GW.  If you deploy multiple GW servers for failover – you must configure this failover using the SDK (PowerShell)

When you assign a Gateway to a Management Server – by default that Gateway server will ONLY talk to that one Management Server.  You should always configure Gateway Failover otherwise you will issue hundreds or thousands of Heartbeat failures should you ever take the Management Server down for planned or unplanned maintenance.


########### Gateway to Management Server Assignment # Get a specific gateway server object by name $Gateway = Get-SCOMManagementServer | where {$_.Name –eq ""} # Show the gateway server assignments for primary and failover $Gateway.GetPrimaryManagementServer().DisplayName $Gateway.GetFailoverManagementServers().DisplayName # Set the gateway server to a specific primary $Primary = Get-SCOMManagementServer | where {$_.Name –eq ""} Set-SCOMParentManagementServer -GatewayServer $Gateway -PrimaryServer $Primary # Set the gateway server to a specific failover $Failover = Get-SCOMManagementServer | where {$_.Name –eq ""} Set-SCOMParentManagementServer -GatewayServer $Gateway -FailoverServer $Failover # Set the gateway server to a list of management servers for failover $FailoverList = Get-SCOMManagementServer | where {$_.Name –ne "" -and $_.IsGateway -eq $false} Set-SCOMParentManagementServer -GatewayServer $Gateway -FailoverServer $FailoverList ########### End

########### Agent to MS/GW Assignment # Get Management Server Object Examples $Primary = Get-SCOMManagementServer | where {$_.Name –eq ""} $Failover = Get-SCOMManagementServer | where {$_.Name –eq ""} $FailoverList = Get-SCOMManagementServer | where {$_.Name –ne "" -and $_.IsGateway -eq $false} # Get a specific agent by name $Agent = Get-SCOMAgent -DNSHostName '' # Get all agents currently assigned to a Management Server or GW $Agents = Get-SCOMAgent -ManagementServer $Primary $AgentsCount = $Agents.Count # Get parent assignments for an agent $Agent.GetPrimaryManagementServer().DisplayName $Agent.GetFailoverManagementServers().DisplayName # Agent set parent Examples Set-SCOMParentManagementServer -Agent $Agent -PrimaryServer $Primary Set-SCOMParentManagementServer -Agent $Agent -FailoverServer $Failover Set-SCOMParentManagementServer -Agent $Agent -FailoverServer $FailoverList # Reassigning all agents in an array of agents $i=0 FOREACH ($Agent in $Agents) { $i++ [string]$AgentName = $Agent.DisplayName Write-Host "`nStarting agent assignment for ($AgentName)" Write-Host "$i of $AgentsCount agents" #$PriBefore = $Agent.GetPrimaryManagementServer().DisplayName $FailBefore = $Agent.GetFailoverManagementServers().DisplayName #Write-Host "Primary before assignment for ($AgentName) is ($PriBefore)" #Write-Host "Failover before assignment for ($AgentName) is ($FailBefore)" IF ($FailBefore) { #You can skip if this is already set correctly or remove what is there and set it correctly Write-Host "Failover already assigned. Skipping." #Optional - remove failover setting and replace with new # We need to remove any failover settings for this agent in case we are setting a primary server already in the failover list #Write-Host "Removing Failover...." #Set-SCOMParentManagementServer -Agent $Agent -FailoverServer $null } ELSE { Write-Host "Failover Assignment starting" #Set-SCOMParentManagementServer -Agent $Agent -PrimaryServer $Primary Set-SCOMParentManagementServer -Agent $Agent -FailoverServer $Failover Write-Host "Failover Assignment complete" #$PriAfter = $Agent.GetPrimaryManagementServer().DisplayName #$FailAfter = $Agent.GetFailoverManagementServers().DisplayName #Write-Host "Primary after assignment for ($AgentName) is ($PriAfter)" #Write-Host "Failover after assignment for ($AgentName) is ($FailAfter)" } } ########### End


  1. Stephan

    Hello Kevin.
    We use Active Directory Integration for agent assignment in our Intranet. We have three Gateway Server (the third is observer) in our DMZ. The Gateway Server are AD Members. It’s no Trust between the Intranet AD and DMZ AD.
    Is it possible to use Active Directory Integration for agent assignment for Gateway Server?
    If yes, how?

  2. Brian

    Looks like the last script in the Agents list “Reassigning all agents in an array of agents” is not complete. Could you update it please? Your blogs on SCOM have been very helpful and appreciated!

  3. James

    Hello Kevin

    I want to test this out on a single server. I tried the script below and get no error but when I check the agent on the client server I see no change. Any ideas?

    I also have an issue trying to get a SCOM Gateway server to work in SCOM Manasgement console. I tried the same steps as the other two which worked correctly. I think I wll remove it again and leave it over night and try again. If there is anything I can try to get it working that would be appreciated.

    $Primary = Get-SCOMManagementServer | where {$_.Name –eq “”}
    $Failover = Get-SCOMManagementServer | where {$_.Name –eq “”}
    # $Primary = “”
    # $Failover = “”

    $MgmtServer = $null
    #$MgmtServer = Get-SCOMManagementServer “”
    # $server = Get-SCOMAgent -ManagementServer $MgmtServer | ? {$_.DisplayName -eq “”}
    $Agent = Get-SCOMAgent -DNSHostName “”


    # Set the agent
    Set-SCOMParentManagementServer -Agent $Agent -PrimaryServer: $Primary
    Set-SCOMParentManagementServer -Agent $Agent -FailOverServer: $FailOver

    • Kevin Holman

      You need to check in SCOM. That’s what matters. The agent assignment on the agent changes over time…. that’s a value taken from the registry. If you want to see the change made on the agent immediately – open the config file in the agent install directory, and find the section, and check which one IsPrimary=True

  4. James

    Thanks Kevin

    I removed the colons from
    Set-SCOMParentManagementServer -Agent $Agent -PrimaryServer: $Primary
    Set-SCOMParentManagementServer -Agent $Agent -FailOverServer: $FailOver

    I think that did the trick

    Many thanks

  5. Steve

    We have 2 1807 management servers, and manage the infrastructure of 50 customers, and 45 Gateway server installed at various customers.
    I was working with another script.

    All Scom agents from all customers are known on the management server. I am not a Powershell guru, but you’re script is probably based on re-assigning scom agents in 1 domain.
    When I run this script on the Management server, it will probably apply to all agents that are known on the MS server.
    I just need to re-assign Customer A agents, and not customer B, C etc

    In the script I posted , you have the choice to re-assign 1 or more agents from a relevant customer, but it does not work because of the missing failover settings.
    Is it possible you can tweak you’re script, to be prompted to enter the name of the management server you want the SCOM Agents set to, and Select the SCOM Agents you want to change the primary management server for.

    I know what you’re thinking.. Do it you’re self 🙂 I’m missing the PS knowledge to tweak the script, and we don’t have a test Scom environment yet. That’s another story..


  6. Vijay

    Hey Kevin,

    I am trying to run below command to set new primary management servers for gateway server but i am getting error “Agent is currently managed through Active Directory. To change the agent assignment, update the Active Directory integration configuration” How can i change this for Gateway server

    Set-SCOMParentManagementServer -GatewayServer $Gateway -PrimaryServer $Primary

  7. Diogo Ribeiro

    Hi There Kevin
    Thanks for the info, but I’m having a problem triing to change my primary and secondary.
    The cenario is this.
    I have scomsrv1 and scomsrv2.
    At the momement, scomsrv1 is the primary and scomsrv2 is the failover.
    I want to change the order, so that scomsrv2 it the primary and scomsrv1 is the failover.
    I’ve read a lot of foruns and technet info, but i can’t change this.
    Can you help me please.
    Thkx in adv.

    • Kevin Holman

      I show examples on how to do that. First – you must set your failover to $null. Then you can change the primary to the failover.

  8. Christian

    Hi Kevin,

    I’ve modified the agent to GW assignment script to check for differences in assignment between two gateways.
    It then makes just enough re-assignments to balance them up again. It works well…so a big thanks for this page.

    I’m just anticipating a possible question from my management though, with regard to leveraging load balancing devices to achieve a similar result.

    If you a load balancer in your environment (something like a Citrix Netscaler), do you know if its possible to put 2 or more SCOM gateways behind it?

    The idea would be that Agents have a single FQDN hard-set in to their config, that pointed at the Virtual IP of a load balanced SCOM gateway service.

    It could then negate the need to run a powershell script to assign primary and failover gateways.

    I’m not sure whether this is a supported configuration though. Any advice appreciated.



    • Kevin Holman

      We do not support using a load balancer for a parent healthservice (GW or MS).

      Load balancing your GW’s isn’t really all that important. If you have a GW pair for high availability, then there isn’t much benefit in load balancing them – they can either run fine all on one, or they cannot. I have put 4000 agents on a single GW and did not see any issues.

  9. Peter

    Hi Kevin
    Great articles as always
    Is there a time period /process, to see when the powershell cmd for failover is active in a linked gateway scenario with /ManagementServerInitiatesConnection=True. I am in doubt beacuse it looks like it take hours. Is it a configuration update to the agent and a Flush/restart agent can help, or a flush/restart on each linked gateway or
    Can you somehow explain how it works

Leave a Reply

Your email address will not be published.