Working with the VMAgent on Microsoft Azure IaaS VMs

Published Sep 20 2018 03:49 AM 195 Views

First published on TechNet on Jun 08, 2015

Ahhh, welcome to summer. The cool splashing blue water of the municipal pool. Blue-raz slushies from Tropical Snow. Bright, clear blue skies. Sometimes all that blue makes me think of Azure - the colors of the portal, the logo and the word itself – Azure – is a type of blue.

Gary Green and Mike Hildebrand will be your tour guides today, speaking with you about some very handy Azure IaaS VM management tools and a big "bonus nugget" at the end that almost makes this post a two'fer (no skipping ahead).

As an IT Pro, you're likely getting more and more comfortable with the cloud paradigm and you're brain is sparking with ideas of how your current IT architecture could benefit from integration with cloud services. That's great!

You've signed up for an Azure trial and you quickly blow through the UI wizard to create a VM. Now, you eagerly await the provisioning process to finish. Tick. Tock. This is worse than waiting for the toaster to pop.

You pound a can Mountain Dew KickStart and a few minutes later, you see in the portal that your shiny new VM is up and running. Ohhhh man!! You're like a kid on Christmas. A moth to the flame. A dog to a bone. Hilde to a theater-sized box of Mike and Ikes. You get the idea.

You click the "connect" button at the bottom of the portal and up pops an RDP connection dialog box for your VM.

Then …

Your mind races but it's coming up empty …

"What credentials did I set up on the VM to login?"

Your minds is blank. You try some of your usual suspects for test credentials but none work.

You think out loud, "Seriously?? I don't remember what username and password I specified when I set this thing up two minutes ago?!"

Perhaps you fat-fingered the password the same way twice when you entered it? It certainly can happen. I know sometimes my brain thinks "the" but my fingers type "then" or "they." It's as if my fingers have a mind of their own. Muscle memory is weird.

Maybe you had to choose a VM name that wasn't your 1 st , 2 nd or 12 th choice due to uniqueness requirements of cloud service names? Maybe it's just me; maybe it's early-onset dementia; maybe it's the Azure version of the Jedi Mind-trick.

Maybe you are coming back to a VM that you provisioned a while back and now, your brain draws a blank for the user ID and/or password.

Or, maybe you aren't as absent minded as I am? Maybe you have a solid naming convention for Azure resources that enables you to precisely keep track of and know what's-what (that's a suggestion, by the way… J ).

Well the folks working on Azure aren't a lazy bunch and they created some out-of-band tools to help you manage your VMs. Collectively, these are enabled by an agent you can install on the VM called, creatively enough, the "VM Agent." For you virtualization techs out there, this won't be a foreign idea – it is along the lines of the Hyper-V "Integration services" and the "VMWare Tools." These drivers and other software light up features and functions for virtualized systems. The VM Agent for Azure VMs does the same type of thing for VMs running in Azure.

The focus of this post is IaaS Windows VMs but there is an agent for LINUX VMs, too, and the Agent is always installed on PaaS VMs (where it is known as the "GuestAgent").

If you use the 'quick-create' option, the agent is automatically part of the VM deployment but if you use the gallery to build your VM, you can check the box to install the agent (default) or clear the check to not install it.


NOTE: At the moment, it is not supported to uninstall the VMAgent from a VM after it's been installed. If you don't want the Agent on your VM, don't install it when provisioning the VM.

NOTE: If you don't want the VMAgent on your VM and you're provisioning VMs via Azure PowerShell, you use the –DisableGuestAgent switch with either the New-AzureQuickVM or New-AzureVM/Add-AzureProvisioningConfig


Once installed, there are a few indications the VMAgent is there:

  • The presence of BGInfo details on the desktop – this is one default 'extension' of the VMAgent.

    NOTE: Currently, BGInfo options aren't configurable – you get what you get


  • A specific file/folder structure on the OS drive.


  • A couple of "Windows Azure" Services


If you didn't choose to have the VMAgent installed when you provisioned the VM, you can install it after the fact via an MSI and some Azure PowerShell.

Here's the process to get the VMAgent on an existing VM:

  • RDP into the VM, download the VMAgent MSI and run it within the VM. This installs the client software within the OS of the VM.
  • If you haven't done so in the past, download/update Azure PowerShell from here and install it (can be done on the target VM itself or any Internet-connected workstation/system – you need connectivity to Azure)
  • Open an elevated Azure PowerShell console and connect it to the Azure subscription where the target VM lives by typing the following commands:
    • Get-AzurePublishSettingsFile (then press enter)
      • Provide credentials for the Azure subscription
      • Read, understand and consider the following WARNING

      • Download/save the settings file via the pop-up prompt
    • Import-AzurePublishSettingsFile "C:\users\user03\Downloads\Windows Azure-credentials.publishsettings" (using the name/path to your settings file; press enter)


      !! SECOND WARNING !! This is one of two ways to connect Azure PowerShell to an Azure subscription. The subscription settings file you download contains your Azure credentials and should be well-protected and/or deleted when you're done connecting . Be sure to read more about connection methods and note the bright pink warning here:


  • Now, we use Azure PowerShell to hook into the specific cloud service where the VM resides and update a property of the VM object. This informs the Azure 'Fabric' that this VM now has the VMAgent running/available.
    From your connected Azure PowerShell console, type the following:
    • Get-AzureVM | Select ServiceName,Name (then press enter; this will return the values for your VMs which you can use for the next commands)
    • $vm = Get-AzureVM –ServiceName CloudService01 –Name VM-01 (then press enter)
    • $vm.VM.ProvisionGuestAgent = $true (then press enter)
    • Update-AzureVM –Name VM-01 –VM $vm.VM –ServiceName CloudService01 (then press enter)

You can now use Azure PowerShell to interact with the VM 'out-of-band', via the VMAgent, and perform tasks such as resetting the local admin username and password, re-enabling remote access defaults and turning on/off BGInfo.

NOTE: Most of these actions require a sign-out/sign-in or possibly a reboot of the VM to take effect.

Rename local admin account and reset password

  • Get-AzureVM -ServiceName CloudService01 –Name VM-01 | Set-AzureVMAccessExtension –UserName NewLocalAdminUserName –Password S0meH@rdPassW0rd | Update-AzureVM

    NOTE: If this is performed against a Domain Controller, it will affect the built-in Administrator account of the domain, including enabling it (if it is disabled) and renaming the SAMAccount attribute of that ID. In my testing, doing this against a DC also resulted in the DC being gracefully rebooted.


Reset Remote Access to IaaS defaults (enable RDP and open a firewall port)

  • Get-AzureVM –ServiceName CloudService01 –Name VM-01 | Set-AzureVMAccessExtension | Update-AzureVM
    • NOTE: This enables RDP and opens a firewall port on the Windows Firewall. It does NOT recreate the "End Point" port mapping. If you deleted that, you'll need to manually recreate it.


Disable BGInfo

  • Get-AzureVM -ServiceName CloudService01 -Name VM-01 | Set-AzureVMBGInfoExtension -Disable | Update-AzureVM


Enable BGInfo

  • Get-AzureVM -ServiceName CloudService01 -Name VM-01 | Set-AzureVMBGInfoExtension | Update-AzureVM




Activities are logged to specific logs files on the VM itself:

In this specific log clip, I used Azure PowerShell to rename the local admin account to mhilde and reset the password:


Additionally, there are Azure-specific Event Logs but they don't track specific changes at the moment; these are more about health of the Agent.


Obviously, the OS itself will capture certain changes, too (in this case, as above, an account rename from user-002 to mhilde):

Lastly, there is logging within the Azure Portal:

  • Select "Management Services" from the list of all items (on the left of the portal) then click "Operation Logs"
  • A change can be correlated between the OPERATION ID within the Portal and the OperationId in the Azure PowerShell window:


And now for the bonus nugget/teaser …

In times past, the only choice you had was to use Azure PowerShell to work with most of the VMAgent functions.

However, you can do these things via GUI from the Azure preview portal!


    NOTE: The Azure Preview Portal is NOT currently supported. For your production workloads, obviously we recommend you continue to use the "vCurrent" portal ( ) and/or the PowerShell commands above to avoid any issues where support isn't available. If you like living your Azure-life on the edge, though, or you're interested in a sneak-peek at the near-future, the preview portal is a really good time.

Disable BGInfo

  • Open the details tile/panel (or "blade" as they're called) for your VM and click "All settings" from the VM details
  • Click "Extensions" from the Settings blade
  • Click to select/highlight the BGInfo Extension
  • Click "Delete"
  • Click "Yes" to accept the verification prompt


  • Check the Notifications in the portal


    BGInfo is no longer active…


Enable BGInfo

  • From the "Settings" Blade of the target VM, click "Extensions"
  • Click "Add"
  • Select "BgInfo"
  • Click "Create"
  • Click "OK" on the blade that flies out on the far left – that blade didn't fit in the screen shot


Reset local admin account and password

  • From the "Settings" blade for the VM, click "Password reset"
  • Enter a new local admin account username and password
    • Password requirements are:
      • At least 8 characters long and
      • 3 of the following:
        • Upper
        • Lower
        • Number
        • Special character
    • If you know the current local admin account username and you don't want to change it, simply re-enter that username here.
  • Click "Reset password"

    NOTE: If this is performed against a Domain Controller, it will affect the built-in Administrator account of the domain, including enabling it (if it is disabled) and renaming the SAMAccount attribute of that ID. In my testing, doing this against a DC also resulted in the DC being gracefully rebooted.


Reset Remote Access to IaaS defaults (enable RDP and open a firewall port)

  • From the main blade for the target VM, click "Reset Remote Access"
  • Click "Yes" to the confirmation prompt
    • NOTE: This enables RDP and opens a firewall port on the Windows Firewall. It does NOT recreate the "End Point" port mapping. If you deleted that, you'll need to manually recreate it.




Well, that about does it for today. The Azure VMAgent, along with some Azure PowerShell, can be quite helpful for managing your IaaS VMs if/when you've painted yourself into a corner.

You can perform some of those admin tasks via the preview portal but that UI isn't supported yet.

The addition of these capabilities to the preview portal was a nice surprise to me but, equally as exciting (or more), were the other style changes and feature-adds to the preview portal. If you haven't been out there recently, I URGE you to go have a look ( ).

You'll find a very polished and eye-friendly web UI with a high degree of operational maturity and functionality to manage your Azure VMs. I, for one, am looking forward to GA for the preview portal (no, I don't know when that will be).

Cheers from Gary and Hilde!

Version history
Last update:
‎Feb 20 2020 06:33 AM
Updated by: