VMAccess Extension for Windows

The VMAccess Extension is used to manage administrative users, configure RDP, and check or repair disks on Azure Windows virtual machines. The extension integrates with Azure Resource Manager templates. It can also be invoked using Azure CLI, Azure PowerShell, the Azure portal, and the Azure Virtual Machines REST API.

This article describes how to run the VMAccess Extension from the Azure PowerShell and through an Azure Resource Manager template. This article also provides troubleshooting steps for Windows systems.

Prerequisites

Supported Windows versions

Tips

• VMAccess is designed for regaining access to a VM when access is lost. Based on this principle, it grants administrator privileges to the specified account in the username field. If you don't want a user to have admin permissions, log in to the VM and use built-in tools (such as net user and Local Users and Groups) to manage user privileges.
• You can only have one version of the extension applied to a VM. To run a second action, update the existing extension with a new configuration.
• When updating a user, VMAccess modifies the Remote Desktop settings to allow login.
• Not supported on Domain Controllers

Extension schema

The VMAccess Extension configuration includes settings for username, passwords, and resetting the administrator password. You can store this information in configuration files, specify it in PowerShell, or include it in an Azure Resource Manager (ARM) template. The following JSON schema contains all the properties available to use in public and protected settings.

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "<name>",
  "apiVersion": "2023-09-01",
  "location": "<location>",
  "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
  ],
  "properties": {
    "publisher": "Microsoft.Compute",
    "type": "VMAccessAgent",
    "typeHandlerVersion": "2.4",
    "autoUpgradeMinorVersion": true,
    "settings": {
      "username": "<username>"
    },
    "protectedSettings": {
      "password": "<password>"
    } 
  }
}

Property values

Settings property values

Template deployment

Azure VM Extensions can be deployed with Azure Resource Manager (ARM) templates. The JSON schema detailed in the previous section can be used in an ARM template to run the VMAccess Extension during the template's deployment.

The JSON configuration for a virtual machine extension must be nested inside the virtual machine resource fragment of the template, specifically "resources": [] object for the virtual machine template and for a virtual machine scale set under "virtualMachineProfile":"extensionProfile":{"extensions" :[] object.

PowerShell

Set-AzVMAccessExtension - Reset Password

Set-AzVMAccessExtension

Set-AzVMAccessExtension `
    -ResourceGroupName "myRG" `
    -Location "myLocation" `
    -VMName "myVM" `
    -Credential (get-credential) `
    -typeHandlerVersion "2.0" `
    -Name VMAccessAgent

Set-AzVMAccessExtension - Reset RDP Configuration

Set-AzVMAccessExtension `
    -ResourceGroupName "myRG" `
    -VMName "myVM" `
    -Name "myVMAccess" `
    -Location "myLocation" `
    -typeHandlerVersion "2.0" `
    -ForceRerun $true

Set-AzVMExtension - Reset Password

Set-AzVMExtension

$Publicsettings = '{"UserName": "myuser"}'
$protectedSettings = '{"Password": "myPassWord"}'

Set-AzVMExtension `
  -ResourceGroupName "myRG" `
  -VMName "myVM" `
  -Location "myLocation" `
  -Name "VMAccessAgent" `
  -Publisher "Microsoft.Compute" `
  -ExtensionType "VMAccessAgent" `
  -TypeHandlerVersion "2.0" `
  -ProtectedSettingString $PrivateConf `
  -SettingString $settings

Set-AzVMExtension - Reset RDP Configuration

Set-AzVMExtension

Set-AzVMExtension `
  -ResourceGroupName "myRG" `
  -VMName "myVM" `
  -Location "myLocation" `
  -Name "VMAccessAgent" `
  -Publisher "Microsoft.Compute" `
  -ExtensionType "VMAccessAgent" `
  -TypeHandlerVersion "2.0" `
  -SettingString '{}' `
  -ForceRerun $true

CLI

Azure CLI - Reset Password

az vm extension set

az vm extension set --name VMAccessAgent --publisher Microsoft.Compute --version 2.0 --vm-name "myVM" --resource-group "myRG" --settings '{"username":"myuser"}' --protected-settings '{"password":"myPassWord"}'

Azure CLI - Reset RDP Configuration

az vm extension set --name VMAccessAgent --publisher Microsoft.Compute --version 2.0 --vm-name "myVM" --resource-group "myRG" --settings '{}'

Virtual machine scale sets

PowerShell

$resourceGroupName = "<resource-group>"
$vmssName = "<vmss-name>"

$settings = @{"UserName"= "myuser"}
$protectedSettings = @{"Password"= "myPassWord"}

$vmss = Get-AzVmss `
    -ResourceGroupName $resourceGroupName `
    -VMScaleSetName $vmssName

Add-AzVmssExtension -VirtualMachineScaleSet $vmss `
    -Name "VMAccessAgent" `
    -Publisher "Microsoft.Compute" `
    -Type "VMAccessAgent" `
    -TypeHandlerVersion "2.0" `
    -AutoUpgradeMinorVersion $true `
    -ProtectedSetting $protectedSettings
    -Setting $settings

Update-AzVmss `
    -ResourceGroupName $resourceGroupName `
    -Name $vmssName `
    -VirtualMachineScaleSet $vmss

CLI

az vmss extension set --vmss-name my-vmss --name VMAccessAgent --resource-group my-group --version 2.0 --publisher Microsoft.Compute --settings '{"username":"myuser"}' --protected-settings '{"password":"myPassWord"}'

Troubleshoot and support

The VMAccess extension logs exist locally on the VM and are particularly useful for troubleshooting.

You can also retrieve the execution state of the VMAccess Extension by running the following command:

Get-AzVMExtension -ResourceGroupName "RG Name" -VMName "VM Name" -Name "Extension Name"

Error messages

For more help, you can file an Azure support incident. Go to Azure support and select Get support. For more information about Azure Support, read the Azure support plans FAQ.