Offline Azure VM Agent Installation: A Comprehensive Guide for Virtual Machines

Updated: 11 Mar, 2025 • 0 • min read

Table of Contents

The Azure Virtual Machine Agent (VM Agent) is a crucial component that empowers you with essential functionalities for managing your Azure Virtual Machines (VMs). These capabilities include local administrator password resets, script execution, and the seamless operation of Azure extensions, significantly enhancing the manageability and automation of your virtual infrastructure. This article provides a detailed walkthrough on how to install the VM Agent on an offline Windows virtual machine (VM), ensuring you can regain control and management capabilities even when direct access is limited.

When to Use the VM Agent in Offline Mode¶

Installing the VM Agent in offline mode becomes necessary in scenarios where the VM Agent is not already installed on your virtual machine, and you are unable to establish a Remote Desktop Protocol (RDP) connection to the VM. This situation often arises due to misconfigurations, system errors, or during the initial setup of a VM that wasn’t provisioned with the agent pre-installed.

If you can successfully connect to your VM via RDP, a simpler approach is available. You can directly download and manually install the VM Agent from within the operating system. This online method is generally preferred for its straightforward nature and ease of execution. However, when RDP access is compromised, the offline installation method becomes indispensable for regaining management access to your Azure VM.

How to Install the VM Agent in Offline Mode¶

The offline installation of the VM Agent requires a methodical approach involving mounting the affected VM’s OS disk to a functioning “troubleshooter” VM. This process allows you to directly modify the offline OS disk and install the necessary agent components. Follow these step-by-step instructions to install the VM Agent in offline mode:

Step 1: Attach the OS Disk of the VM to Another VM as a Data Disk¶

This initial step involves preparing a working Azure VM to act as a troubleshooter and attaching the OS disk of the problematic VM to it. This allows us to access and modify the file system of the offline VM.

Create a Snapshot and Disk: Begin by taking a snapshot of the OS disk from the affected virtual machine. From this snapshot, create a new disk. This ensures that you have a backup of the original OS disk in case any issues arise during the process.
Attach the Disk to a Troubleshooter VM: Attach the newly created disk to a healthy, functioning Azure VM. This VM will serve as your troubleshooter. For detailed guidance on this process, refer to the Azure documentation on troubleshooting Windows VMs by attaching the OS disk to a recovery VM using the Azure portal.
Verify Disk Online and Drive Letters: Connect to the troubleshooter VM using RDP. Once inside, open Computer Management and navigate to Disk Management. Verify that the attached OS disk is online and that drive letters have been automatically assigned to its partitions. This ensures that the disk is properly mounted and accessible for modification.

Step 2: Modify the OS Disk to Install the Azure VM Agent¶

With the OS disk attached and accessible, the next crucial step is to modify it by installing the Azure VM Agent components. This involves manipulating the registry and file system of the attached disk.

Remote Desktop Connection: Ensure you are connected to the troubleshooter VM via Remote Desktop. This provides the environment to perform the necessary modifications.
Backup Registry Files: Within the troubleshooter VM, browse to the attached OS disk. Navigate to the \windows\system32\config folder. Critically, copy all files within this folder to a backup location. This backup is essential for rollback purposes should any issues occur during the registry modification process.
Open Registry Editor: Launch the Registry Editor by typing regedit.exe in the Run dialog or search bar and pressing Enter.
Load Registry Hive: In the Registry Editor, select the HKEY_LOCAL_MACHINE key. From the menu bar, click File and then Load Hive…
Select SYSTEM Hive and Name It: Browse to the \windows\system32\config\SYSTEM folder on the attached OS disk. In the “File name” field, type SYSTEM and click Open. For the “Key Name”, enter BROKENSYSTEM. This action loads the SYSTEM hive from the offline OS disk into the registry under the HKEY_LOCAL_MACHINE\BROKENSYSTEM key.
Backup Existing VM Agent Configuration (If Present): Check if the attached OS disk already has a VM agent installed. If it does, it’s important to back up its current configuration before proceeding. If no VM agent is found, you can skip to the next step.
- Rename WindowsAzure Folder: Rename the \windowsazure folder on the attached OS disk to \windowsazure.old. This effectively backs up the existing agent installation directory.
- Export Registry Keys: Export the following registry keys as .reg files to a safe location:
  - HKEY_LOCAL_MACHINE\BROKENSYSTEM\ControlSet001\Services\WindowsAzureGuestAgent
  - HKEY_LOCAL_MACHINE\BROKENSYSTEM\ControlSet001\Services\RdAgent
    These exported files serve as a backup of the existing VM Agent registry settings.
Utilize Troubleshooter VM Files as Repository: Leverage the existing files from the troubleshooter VM as a source for the VM Agent installation. Perform the following actions:
- Export Registry Subkeys from Troubleshooter VM: From the troubleshooter VM, export the following registry subkeys in .reg format:
  - HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\WindowsAzureGuestAgent
  - HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\RdAgent
- Modify Registry Files for BROKENSYSTEM: Edit each of the exported .reg files using a text editor like Notepad. Within each file, find and replace every instance of SYSTEM with BROKENSYSTEM. Crucially, note the ImagePath value within the WindowsAzureGuestAgent registry key. You will need this path information in the next substep to locate and copy the correct VM Agent folder. Save the modified .reg files.
```
[HKEY_LOCAL_MACHINE\BROKENSYSTEM\ControlSet001\Services\WindowsAzureGuestAgent]
"ImagePath"=hex(2):25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,00,\
  6f,00,74,00,25,00,5c,00,53,00,79,00,73,00,74,00,65,00,6d,00,33,00,32,\
  00,5c,00,57,00,69,00,6e,00,64,00,6f,00,77,00,73,00,41,00,7a,00,75,00,\
  72,00,65,00,5c,00,47,00,75,00,65,00,73,00,74,00,41,00,67,00,65,00,6e,\
  00,74,00,2e,00,65,00,78,00,65,00
```
- Import Modified Registry Files: Import the modified .reg files into the registry of the troubleshooter VM. Simply double-click each .reg file and confirm the import operation. This merges the VM Agent registry settings into the BROKENSYSTEM hive.
- Verify Registry Import: In the Registry Editor, navigate to HKEY_LOCAL_MACHINE\BROKENSYSTEM\ControlSet001\Services. Confirm that the WindowsAzureGuestAgent and RdAgent subkeys have been successfully imported.
- Copy VM Agent Installation Folder: Copy the VM Agent installation folder from the troubleshooter VM to the attached OS disk.
  1. On the attached OS disk, create a new folder named WindowsAzure in the root directory.
  2. On the troubleshooter VM, navigate to C:\WindowsAzure. Look for folders named in the format C:\WindowsAzure\GuestAgent_X.X.XXXX.XXX. Identify the GuestAgent folder with the latest version number. Copy this specific GuestAgent folder from C:\WindowsAzure on the troubleshooter VM to the WindowsAzure folder you just created on the attached OS disk. If you are unsure which folder is the latest, you can copy all GuestAgent folders; however, copying the latest version is typically sufficient.
    
    Alternative Path Determination: If you cannot locate the GuestAgent folder using the versioned naming convention, refer back to the ImagePath value you noted earlier from the WindowsAzureGuestAgent registry subkey (from the modified .reg file). This ImagePath will precisely indicate the location of the VM Agent executable and its associated folder.
Unload the BROKENSYSTEM Hive: Select the BROKENSYSTEM hive in the Registry Editor. From the menu, click File and then Unload Hive…. This is essential to properly detach the hive and prevent data corruption.
Detach and Swap OS Disk: Detach the modified OS disk from the troubleshooter VM. Then, in the Azure portal, swap the OS disk for the affected VM with the repaired disk. This effectively replaces the original OS disk of the problematic VM with the modified disk containing the newly installed VM Agent.
Access the VM: Start the affected VM. After booting up, attempt to access the VM. Observe if the RdAgent service is running and if logs are being generated. This indicates that the VM Agent installation was successful and is now operational.

If your VM was created using the Resource Manager deployment model, the process is now complete. The VM Agent should be installed and functioning.

Next Steps¶

With the Azure VM Agent successfully installed in offline mode, you can now leverage its capabilities to manage and configure your virtual machine. Explore the following resources for further information and advanced functionalities:

If you encounter any issues or have further questions regarding offline VM Agent installation, please feel free to leave a comment below. Your feedback and experiences are valuable to the community!

Computacionvinchi