VMAccess Extension for Linux

Article
08/22/2024

The VMAccess Extension is used to manage administrative users, configure SSH, and check or repair disks on Azure Linux 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 CLI and through an Azure Resource Manager template. This article also provides troubleshooting steps for Linux systems.

Note

If you use the VMAccess extension to reset the password of your VM after you install the Microsoft Entra Login extension, rerun the Microsoft Entra Login extension to re-enable Microsoft Entra Login for your VM.

Prerequisites

Supported Linux distributions

Linux Distro	x64	ARM64
Alma Linux	9.x+	9.x+
Debian	10+	11.x+
Flatcar Linux	3374.2.x+	3374.2.x+
Azure Linux	2.x	2.x
openSUSE	12.3+	Not Supported
Oracle Linux	6.4+, 7.x+, 8.x+	Not Supported
Red Hat Enterprise Linux	6.7+, 7.x+, 8.x+	8.6+, 9.0+
Rocky Linux	9.x+	9.x+
SLES	12.x+, 15.x+	15.x SP4+
Ubuntu	18.04+, 20.04+, 22.04+	20.04+, 22.04+

Tips

VMAccess was designed for regaining access to a VM given that access is lost. Based on this principle, it grants sudo permission to account specified in the username field. If you don't wish a user to gain sudo permissions, log in to the VM and use built-in tools (for example, usermod, chage, etc.) to manage unprivileged users.
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.
During a user update, VMAccess alters the sshd_config file and takes a backup of it beforehand. To restore the original backed-up SSH configuration, run VMAccess with restore_backup_ssh set to True.

Extension schema

The VMAccess Extension configuration includes settings for username, passwords, SSH keys, etc. You can store this information in configuration files, specify it on the command line, 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.OSTCExtensions",
    "type": "VMAccessForLinux",
    "typeHandlerVersion": "1.5",
    "autoUpgradeMinorVersion": true,
    "settings": {
      "check_disk": true,
      "repair_disk": false,
      "disk_name": "<disk-name>",
    },
    "protectedSettings": {
      "username": "<username>",
      "password": "<password>",
      "ssh_key": "<ssh-key>",
      "reset_ssh": false,
      "remove_user": "<username>",
      "expiration": "<expiration>",
      "remove_prior_keys": false,
      "restore_backup_ssh": true
    } 
  }
}

Property values

Name	Value / Example	Data Type
apiVersion	2023-09-01	date
publisher	Microsoft.OSTCExtensions	string
type	VMAccessForLinux	string
typeHandlerVersion	1.5	int

Settings property values

Name	Data Type	Description
check_disk	boolean	Whether or not to check disk (optional). Only one between `check_disk` and `repair_disk` can be set to true.
repair_disk	boolean	Whether or not to check disk (optional). Only one between `check_disk` and `repair_disk` can be set to true.
disk_name	string	Name of disk to repair (required when `repair_disk` is true).
username	string	The name of the user to manage (required for all actions on a user account).
password	string	The password to set for the user account.
ssh_key	string	The SSH public key to add for the user account. The SSH key can be in `ssh-rsa`, `ssh-ed25519`, or `.pem` format.
reset_ssh	boolean	Whether or not to reset the SSH. If `true`, it replaces the sshd_config file with an internal resource file corresponding to the default SSH config for that distro.
remove_user	string	The name of the user to remove. Can't be used with `reset_ssh`, `restore_backup_ssh`, and `password`.
expiration	string	Expiration to set to for the account, in the form of `yyyy-mm-dd`. Defaults to never.
remove_prior_keys	boolean	Whether or not to remove old SSH keys when adding a new one. Must be used with `ssh_key`.
restore_backup_ssh	boolean	Whether or not to restore the original backed-up sshd_config.

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. You can find a sample template that includes the VMAccess extension on GitHub.

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.

Azure CLI deployment

Using Azure CLI VM user commands

The following CLI commands under az vm user use the VMAccess Extension. To use these commands, you need to install the latest Azure CLI and sign in to an Azure account by using az login.

Update SSH key

The following example updates the SSH key for the user azureUser on the VM named myVM:

az vm user update \
  --resource-group myResourceGroup \
  --name myVM \
  --username azureUser \
  --ssh-key-value ~/.ssh/id_rsa.pub

Note

The az vm user update command appends the new public key text to the ~/.ssh/authorized_keys file for the admin user on the VM. This command doesn't replace or remove any existing SSH keys. This command doesn't remove prior keys set at deployment time or subsequent updates by using the VMAccess Extension.

Reset password

The following example resets the password for the user azureUser on the VM named myVM:

az vm user update \
  --resource-group myResourceGroup \
  --name myVM \
  --username azureUser \
  --password myNewPassword

Restart SSH

The following example restarts the SSH daemon and resets the SSH configuration to default values on a VM named myVM:

az vm user reset-ssh \
  --resource-group myResourceGroup \
  --name myVM

Note

The az vm user reset-ssh command replaces the sshd_config file with a default config file from the internal resources directory. This command doesn't restore the original SSH configuration found on the virtual machine.

Create an administrative/sudo user

The following example creates a user named myNewUser with sudo permissions. The account uses an SSH key for authentication on the VM named myVM. This method helps you regain access to a VM when current credentials are lost or forgotten. As a best practice, accounts with sudo permissions should be limited.

az vm user update \
  --resource-group myResourceGroup \
  --name myVM \
  --username myNewUser \
  --ssh-key-value ~/.ssh/id_rsa.pub

Delete a user

The following example deletes a user named myNewUser on the VM named myVM:

az vm user delete \
  --resource-group myResourceGroup \
  --name myVM \
  --username myNewUser

Using Azure CLI VM/VMSS extension commands

You can also use the az vm extension set and az vmss extension set commands to run the VMAccess Extension with the specified configuration.

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM \
  --name VMAccessForLinux \
  --publisher Microsoft.OSTCExtensions \
  --version 1.5 \
  --settings '{"check_disk":true}'
  --protected-settings '{"username":"user1","password":"userPassword"}'

The --settings and --protected-settings parameters also accept JSON file paths. For example, to update the SSH public key of a user, create a JSON file named update_ssh_key.json and add settings in the following format. Replace the values within the file with your own information:

{
  "username":"azureuser",
  "ssh_key":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCZ3S7gGp3rcbKmG2Y4vGZFMuMZCwoUzZNGxxxxxx2XV2x9FfAhy8iGD+lF8UdjFX3t5ebMm6BnnMh8fHwkTRdOt3LDQq8o8ElTBrZaKPxZN2thMZnODs5Hlemb2UX0oRIGRcvWqsd4oJmxsXa/Si98Wa6RHWbc9QZhw80KAcOVhmndZAZAGR+Wq6yslNo5TMOr1/ZyQAook5C4FtcSGn3Y+WczaoGWIxG4ZaWk128g79VIeJcIQqOjPodHvQAhll7qDlItVvBfMOben3GyhYTm7k4YwlEdkONm4yV/UIW0la1rmyztSBQIm9sZmSq44XXgjVmDHNF8UfCZ1ToE4r2SdwTmZv00T2i5faeYnHzxiLPA3Enub7xxxxxxwFArnqad7MO1SY1kLemhX9eFjLWN4mJe56Fu4NiWJkR9APSZQrYeKaqru4KUC68QpVasNJHbuxPSf/PcjF3cjO1+X+4x6L1H5HTPuqUkyZGgDO4ynUHbko4dhlanALcriF7tIfQR9i2r2xOyv5gxJEW/zztGqWma/d4rBoPjnf6tO7rLFHXMt/DVTkAfn5wxxtLDwkn5FMyvThRmex3BDf0gujoI1y6cOWLe9Y5geNX0oj+MXg/W0cXAtzSFocstV1PoVqy883hNoeQZ3mIGB3Q0rIUm5d9MA2bMMt31m1g3Sin6EQ== azureuser@myVM"
}

Run the VMAccess Extension through the following command:

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM \
  --name VMAccessForLinux \
  --publisher Microsoft.OSTCExtensions \
  --version 1.5 \
  --protected-settings update_ssh_key.json

Azure PowerShell deployment

Azure PowerShell can be used to deploy the VMAccess Extension to an existing virtual machine or virtual machine scale set. You can deploy the extension to a VM by running:

$username = "<username>"
$sshKey = "<cert-contents>"

$settings = @{"check_disk" = $true};
$protectedSettings = @{"username" = $username; "ssh_key" = $sshKey};

Set-AzVMExtension -ResourceGroupName "<resource-group>" `
    -VMName "<vm-name>" `
    -Location "<location>" `
    -Publisher "Microsoft.OSTCExtensions" `
    -ExtensionType "VMAccessForLinux" `
    -Name "VMAccessForLinux" `
    -TypeHandlerVersion "1.5" `
    -Settings $settings `
    -ProtectedSettings $protectedSettings

You can also provide and modify extension settings by using strings:

$username = "<username>"
$sshKey = "<cert-contents>"

$settingsString = '{"check_disk":true}';
$protectedSettingsString = '{"username":"' + $username + '","ssh_key":"' + $sshKey + '"}';

Set-AzVMExtension -ResourceGroupName "<resource-group>" `
    -VMName "<vm-name>" `
    -Location "<location>" `
    -Publisher "Microsoft.OSTCExtensions" `
    -ExtensionType "VMAccessForLinux" `
    -Name "VMAccessForLinux" `
    -TypeHandlerVersion "1.5" `
    -SettingString $settingsString `
    -ProtectedSettingString $protectedSettingsString

To deploy to a virtual machine scale set, run the following command:

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

$protectedSettings = @{
  "username" = "azureUser"
  "password" = "userPassword"
}

$publicSettings = @{
  "repair_disk" = $true
  "disk_name" = "<disk_name>"
}

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

Add-AzVmssExtension -VirtualMachineScaleSet $vmss `
    -Name "<extension-name>" `
    -Publisher "Microsoft.OSTCExtensions" `
    -Type "VMAccessForLinux" `
    -TypeHandlerVersion "1.5"" `
    -AutoUpgradeMinorVersion $true `
    -Setting $publicSettings `
    -ProtectedSetting $protectedSettings

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

Troubleshoot and support

The VMAccess extension logs exist locally on the VM and are most informative when it comes to troubleshooting.

Location	Description
/var/log/waagent.log	Contains logs from the Linux Agent and shows when an update to the extension occurred. We can check it to ensure the extension ran.
/var/log/azure/Microsoft.OSTCExtensions.VMAccessForLinux/*	The VMAccess Extension produces logs, which can be found here. The directory contains `CommandExecution.log` where you can find each command executed along with its result, along with `extension.log`, which contains individual logs for each execution.
/var/lib/waagent/Microsoft.OSTCExtensions.VMAccessForLinux-<most recent version>/config/*	The configuration and binaries for VMAccess VM Extension.

You can also retrieve the execution state of the VMAccess Extension, along with other extensions on a given VM, by running the following command:

az vm extension list --resource-group myResourceGroup --vm-name myVM -o table

For more help, you can contact the Azure experts at Azure Community Support. Alternatively, 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.

Next steps

To see the code, current versions, and more documentation, see VMAccess Linux - GitHub.

Share via

VMAccess Extension for Linux

Prerequisites

Supported Linux distributions

Tips

Extension schema

Property values

Settings property values

Template deployment

Azure CLI deployment

Using Azure CLI VM user commands

Update SSH key

Reset password

Restart SSH

Create an administrative/sudo user

Delete a user

Using Azure CLI VM/VMSS extension commands

Azure PowerShell deployment

Troubleshoot and support

Next steps

Feedback

Additional resources