Citrix maintenance mode via PowerShell

This is a task you will have likely carried out, on a regular basis during your day to day Citrix farm administration. You have Citrix VDA machines that you need to put in maintenance mod. Maybe it’s one machine, maybe it’s a dozen. The reasons can be to carry out maintenance, or upgrades. Whatever the reason, yes you can do it via Studio, but what about PowerShell?

Of course you can do it via PowerShell too! If you’re like me and more interested in getting comfortable with PowerShell then here’s a little note on how to put machines in maintenance mode via PowerShell with a few example scenarios.

Firstly, launch PowerShell either via studio or by running Add-PSSnapin Citrix.* within your PowerShell console.

Machines used in scenarios:

  1. CitrixDesktop1
  2. CitrixDesktop2
  3. CitrixDesktop3

Scenario 1 – Put CitrixDesktop1 in to maintenance mode

  1. Set-BrokerMachineMaintenanceMode -InputObject DOMAIN\CitrixDesktop1 $true
  2. Get-BrokerMachine -MachineName DOMAIN\CitrixDesktop1 | fl InMaintenanceMode

The first command sets the machine in maintenance mode. The second queries for the end result.

1

Scenario 2 – Put CitrixDesktop1 and CitrixDesktop2 in to maintenance mode

  1. Set-BrokerMachineMaintenanceMode -InputObject DOMAIN\CitrixDesktop1, DOMAIN\CitrixDesktop2 $true

Scenario 3 – Put all three machines in to maintenance mode

  1. $machines = Get-BrokerMachine -MachineName DOMAIN\CitrixDesktop*
  2. Set-BrokerMachineMaintenanceMode -InputObject $machines $true

The first command gets a list of machines with CitrixDesktop in their name. The second puts them in to maintenance mode.


34 Comments

  • SunilKumar Botu

    June 9, 2017

    Thanks but how do I put multiple machines with different names in a delivery group. I cant use wild card. thanks in advance. I am looking to give machine list as input file and run a loop.

    Reply
    • George Spiers

      June 9, 2017

      $machines = Get-Content C:\MachineList.txt
      foreach ($machine in $machines) {
      Add-BrokerMachine “DOMAINNAME\$machine” -DesktopGroup “DeliveryGroupName”
      }

      Reply
      • chandra

        July 4, 2018

        Hi George,

        can you help me with the powershell script/command to bring multiple xenapp servers out of maintenance mode.
        emailid:chandraobulreddy9@gmail.com

        Reply
        • George Spiers

          July 4, 2018

          Have a look at the scenarios, there should be enough tips there to help you get started with a script?

          Reply
          • mike

            July 17, 2020

            Hi George, would you be able to provide me with a few good Citirix engineer question and answers? I am a technical recruiter and I am limited as to what I can tech out for. TY in advance!

      • Essie

        January 17, 2019

        Thanks man!
        Easy to adapt to many uses.
        Cheers!

        Reply
  • Santosh Kumar

    October 27, 2017

    How do you send a message to all the connected users using PowerShell script? If the names of the machines are different.

    Reply
    • George Spiers

      October 27, 2017

      Are you using server based hosts or VDI desktops? You know Restart Schedules via Studio can send notifications for you?

      Reply
  • Muthu

    January 31, 2018

    To put list of machines with different names into maintenance mode.

    asnp citrix.*
    Get-Content C:\MachineList.txt
    foreach ($machine in $machines) {Set-BrokerMachineMaintenanceMode -InputObject $machine $true}

    Reply
  • Henk

    August 17, 2018

    I have 5 Citrix servers where users loggin for a 24hour operation tasks. But I would like to restart them randomly once in a week.

    How can I randomly restart 5 Citrix servers without affect the logged in users?

    Reply
    • George Spiers

      August 19, 2018

      You can use tags to restart servers separately without having to create multiple Delivery Groups: https://jgspiers.com/create-multiple-restart-schedules-xenapp-xendesktop-7-12/

      You can also send a message to users instructing them to log off in X minutes due to an upcoming restart.

      Reply
      • Anonymous

        January 20, 2020

        Hi George,
        Please help me with monthly or 15 days reboot schedule reboot command lets only have for weekly/Daily . How do i achieve it.

        New-BrokerRebootScheduleV2 -DesktopGroupUid 1 -Frequency Weekly -Name WeeklyRebootSchedule-HR -RestrictToTag HR -StartTime 01:00:00 -RebootDuration 0 -WarningDuration 15 -WarningMessage “Please log off as this machine will restart in 15 minutes”

        thanks in advance, appreciate your help

        Reply
        • George Spiers

          February 17, 2020

          That is the limitation, you have to use scripts to achieve something different

          Reply
  • John

    December 13, 2018

    There are several ways to do this. Of course you can write your own… But the wheel is invented more than once…
    George have one..
    I ‘m happy to use the one provided by Miguel Contreras from Citrix with a few modifications
    https://www.citrix.com/blogs/2017/06/19/xenapp-7-x-reboot-schedules-2017-edition/
    It staged (even and uneven) with drain mode and reboot countdown 😉 so your DG is always up.

    Some one ( or 2-3 liners) to get inspired 🙂

    $drainTimer 180
    $deliveryGroup = “Delivery group name”
    Get-BrokerMachine -DesktopGroupName $deliveryGroup -InMaintenanceMode 0 -PowerState On -MaxRecordCount 5000 | Set-BrokerMachine -InMaintenanceMode 1

    $drainTimer = $drainTimer * 60
    Start-Sleep $drainTimer

    # Herstart after 30 min (note start-sleep in seconds, You have to get to 1800 s)
    $drainTimer = $drainTimer * 10
    Start-Sleep $drainTimer
    Get-BrokerMachine -DesktopGroupName $deliveryGroup -InMaintenanceMode 1 -PowerState On -MaxRecordCount 5000 | New-BrokerHostingPowerAction -Action ‘Restart’

    Get-BrokerMachine -DesktopGroupName $deliveryGroup -InMaintenanceMode 1 -PowerState On -MaxRecordCount 5000 | Set-BrokerMachine -InMaintenanceMode 0

    John

    Reply
  • Joevany

    February 5, 2019

    Nice script, however can you please help ?
    I only want to place my VDI into maintenance mode if AD user Account is either inactive/disabled. Do you have a script for that? Thanks

    Reply
  • Teague Williams

    July 18, 2019

    George. I am deploying multiple independent sites and using resource aggregation for failover. I have a DG (primary) with all the desktops in an unregistered/faulted state. when I attempt to launch the desktop, I get “no-available-workstation”. when I put the DG into maintenance mode, the desktop launches from the DR site. it works properly when I down the DDCs at the primary site as well. I would think that the “no-available-workstation” should lead to a resource launch from teh DR site as well. Unfortunately, that is not the case.

    I was thinking about writing a PS script using Get-BrokerDesktopGroup to detect if there are “no-available-workstations” and set the DG to maintenance mode using Set-DesktopDeliveryGroup. What combinations of the following properties would satisfy the conditions. I was thinking something like this:

    if desktopsavailable = 0 then set DG maintenance mode
    -or-
    if SUM(DesktopsFaulted+DesktopsInUse+DesktopsNeverRegistered+DesktopsPreparing+DesktopsUnregistered) = TotalDesktops then set DG maintenance mode

    DesktopsAvailable : 0
    DesktopsDisconnected : 0
    DesktopsFaulted : 5
    DesktopsInUse : 0
    DesktopsNeverRegistered : 0
    DesktopsPreparing : 0
    DesktopsUnregistered : 5
    TotalDesktops : 5

    Do you have any recommendations? Thanks.

    Reply
    • George Spiers

      July 20, 2019

      Sounds like you are on the right track at least. If these are VDI desktops then you could use the “DesktopsAvailable” property.

      You could alternatively look at doing something with “Get-BrokerDesktop” and the “RegistrationState” property which will have a value of Unregistered, Initializing, Registered or Agent Error.
      So for desktops detected not to be registered, place them into maintenance mode.

      Also the Delivery Controller is supposed to place VMs in maintenance mode after so many registration failures. See here at some of the registry edits you might be able to make to help: https://support.citrix.com/article/CTX126704

      Reply
  • kartik

    August 15, 2019

    George I have mutiple Sites configured in my environment per datacenter. How can i get the consolidated report of all Site how many machines are unregistered and how many machines are in maintenance mode through powershell tool.

    Reply
  • Sakthi

    February 11, 2020

    Hey George,

    How we put multiple machine in maintenance if they are unregistered state ?

    Reply
    • Anonymous

      February 17, 2020

      HI Goege,

      I would like to have a script to check the which are in Maintenance Moe and who move it to MM mode.
      Thanks
      Sur

      Reply
    • George Spiers

      May 10, 2020

      For example:
      $machines = ‘JGSPIERS\VDA01′,’JGSPIERS\VDA02’
      Set-BrokerMachineMaintenanceMode $machines $true

      Reply
      • Inay

        June 30, 2020

        Hello George,
        Need your assistance on the below..
        I have a set of VDA servers running on 7.15 controller that needs to be placed in maintenance, so i have below edited script

        **********************************************************************
        asnp Citrix*

        $machines = Get-Content C:\temp\Temp\Servers.txt

        foreach($machine in $machines) {

        Set-BrokerMachineMaintenanceMode -InputObject $machine $true}
        ************************************************************************
        But when i execute the above script, it is giving the below error, could you please assist me

        Set-BrokerMachineMaintenanceMode : No items match the supplied pattern

        At C:\temp\Script.ps1:4 char:1

        + Set-BrokerMachineMaintenanceMode -InputObject $machine $true}

        + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        + CategoryInfo : InvalidArgument: (:) [Set-BrokerMachineMaintenanceMode], SdkOperationException

        + FullyQualifiedErrorId : Citrix.XDPowerShell.Broker.NoMatchingItems,Citrix.Broker.Admin.SDK.SetBrokerMachineMaintenanceModeCommand

        Reply
  • Anonymous

    June 30, 2020

    Hello George

    Reply
  • Anonymous

    June 30, 2020

    Hello George,
    I have edited the script in such a way that it can place a set of servers in maintenance mode
    Controller is 7.15, Kindly let me know if you need any other details.
    ****************************************************************
    asnp Citrix*

    $machines = Get-Content C:\temp\Temp\Servers.txt

    foreach($machine in $machines) {

    Set-BrokerMachineMaintenanceMode -InputObject $machine $true}
    ************************************************************************
    But I am getting the below error

    Set-BrokerMachineMaintenanceMode : No items match the supplied pattern

    At C:\temp\Temp\AE Script.ps1:4 char:1

    + Set-BrokerMachineMaintenanceMode -InputObject $machine $true}

    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    + CategoryInfo : InvalidArgument: (:) [Set-BrokerMachineMaintenanceMode], SdkOperationException

    + FullyQualifiedErrorId : Citrix.XDPowerShell.Broker.NoMatchingItems,Citrix.Broker.Admin.SDK.SetBrokerMachineMaintenanceModeCommand

    Thanks
    Inay

    Reply
  • Dibakar Basu

    July 23, 2020

    in the Servers.txt update the machines names as Domain\ machine name, save and then run the below command

    asnp Citrix*
    $machines = Get-Content D:\Servers.txt
    foreach ($machine in $machines) {Set-BrokerMachineMaintenanceMode -InputObject $machine $true}

    Reply
    • Anonymous

      July 29, 2022

      Could you please tell how to delete multiple virtual desktops/laptops from Citrix using powershell script

      Reply
  • RV

    December 29, 2020

    Hello George,

    How do I get the report/list of policies with Name and its settings which will be shown in the Policies tab in Studio with PowerShell?

    Reply
  • MDroege

    January 11, 2021

    Hello George,
    when I run the script i get the error “The term ‘Set-BrokerMachineMaintenanceMode’ is not recognized as the name of a cmdlet”
    I added the

    Reply
    • Anonymous

      January 11, 2021

      Cmdlet before

      Reply
  • Reda.DZ

    September 8, 2021

    here how I do it:

    asnp citrix*
    $VMs = (Get-BrokerMachine | Where-Object {$_.InMaintenanceMode -eq $True}).MachineName
    foreach ($VM in $VMs){
    Set-BrokerMachineMaintenanceMode -InputObject $VM $false

    }

    Reply
  • Naresh K

    March 14, 2022

    Hi George ,

    I have some 30 machines in our studio, at sometimes the servers are going into unregistered state due to the heavy load index on the server. I am planning to implement a task in which when the load index of the server reaches maximum load the server has to undergo maintenance mode until and unless the load decreases on it. After a while when the load decreases the server automatically has to come out of maintenance mode. Could you pleas suggest me here. How can I proceed with the things.

    Reply
  • James K

    July 25, 2022

    Hello,

    I am struggling mightily with a script that should be working and I can’t figure out why it’s not.

    It’s a script to power on any machines that are powered off in the environment.

    Set-ExecutionPolicy Unrestricted
    asnp citrix*
    $Servers = Get-BrokerDesktop | Where-Object {$_.PowerState -eq “off”} | Select MachineName
    $Servers | ForEach-Object {
    New-BrokerHostingPowerAction -Action TurnOn -MachineName $_
    }

    I have two machines powered off in the environment specifically to test this, and I confirmed that the $_ variable contains two items.

    MachineName
    ———————
    Test\Test01
    Test\Test02

    But when I run the script, I get this error twice:
    New-BrokerHostingPowerAction : Machine not found
    At C:\scripts\Citrix-Restart-Unregistered.ps1:9 char:1
    + New-BrokerHostingPowerAction -Action TurnOn -MachineName $_
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : ObjectNotFound: (:) [New-BrokerHostingPowerAction], SdkOperationException
    + FullyQualifiedErrorId : Citrix.XDPowerShell.Broker.UnknownMachine,Citrix.Broker.Admin.SDK.NewBrokerHostingPowerActionCommand

    For some reason it appears that the variable isn’t being passed. I do not understand what is happening here at all.
    Any help you can provide would be greatly appreciated.

    Reply
  • Vincent S.

    December 27, 2022

    I ran in the same issue and know $VM has a value “domain\VMname”.

    $svr = Get-BrokerDesktop -Filter {DesktopGroupName -eq ‘CitrixDesktop’} -PowerState off | select MachineName
    foreach ($vm in $svr){
    #New-BrokerHostingPowerAction -MachineName $vm -Action Reset
    Write-Output $VM
    }
    Results:
    New-BrokerHostingPowerAction : Machine not found
    At line:1 char:1
    + New-BrokerHostingPowerAction -MachineName ‘$vm’ -Action Reset
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : ObjectNotFound: (:) [New-BrokerHostingPowerAction], SdkOperationException
    + FullyQualifiedErrorId : Citrix.XDPowerShell.Broker.UnknownMachine,Citrix.Broker.Admin.SDK.NewBrokerHostingPowerA
    ctionCommand

    Thanks,

    Reply
  • Anonymous

    September 20, 2023

    I am trying to figure a way to put VDA in Maintenance mode by Restricted Tag

    Reply

Leave a Reply