Have you ever forgotten your Azure VM password or SSH key and lost access? The VMAccess extension enables you to reset the password, SSH key, or the SSH configurations, so you can regain access to your VM. You can also add a new user with password or SSH key, or delete a user using this extension. This extension targets Linux VMs, for Windows VMs, click here for details. If this is your first time using VM extensions, you might want to check here for some background information.
Pre-Requisites
- Microsoft Azure Linux Agent version 2.0.6 or later. Note most Azure VM Linux gallery images included version 2.0.6 above. You can run waagent -version to confirm the version installed in the VM. If the VM is running a version earlier than 2.0.6 you can follow these instructions to update it.
- Cross-Platform CLI or Azure PowerShell.
- A new password or SSH key you want to reset or add along with the new user for your VM.
Updates in December 2015:
VMAccess Extension for Linux is now supporting Azure Resource Manager model, for sample Powershell and CLI scripts on running VMAccess Extension for Linux under ARM model, please see the Github release document here https://github.com/Azure/azure-linux-extensions/blob/master/VMAccess/README.md
Use the VMAccess Extension through Xplat CLI
Please follow this Guidance to setup the cross-platform cli environment on your machine. Once the xplat-cli is installed, you will be able to use the azure command from your command-line interface (Bash, Terminal, Command prompt) to access the xplat-cli commands. For example, run ‘azure vm extension set –help’ for detailed extension usage. There are 6 scenarios where you might use VMAccess to gain your access to your VM. The following are scenarios and the corresponding sample scripts.
1. Resetting the password
Step 1: Create a file named PrivateConf.json with following content:
{
"username":"currentusername",
"password":"newpassword",
"expiration":"2016-01-01"
}
Step 2: Run ‘azure vm extension set vmname VMAccessForLinux Microsoft.OSTCExtensions 1.* –private-config-path PrivateConf.json’
2. Resetting the SSH key
Step 1: Create a file named PrivateConf.json with following content:
{
"username":"currentusername",
"ssh_key":"contentofsshkey",
}
Step 2: Run ‘azure vm extension set vmname VMAccessForLinux Microsoft.OSTCExtensions 1.* –private-config-path PrivateConf.json’
3. Resetting the password and the SSH key
Step 1: Create a file named PrivateConf.json with following content:
{
"username":"currentusername",
"ssh_key":"contentofsshkey",
"password":"newpassword",
}
Step 2: Run ‘azure vm extension set vmname VMAccessForLinux Microsoft.OSTCExtensions 1.* –private-config-path PrivateConf.json’
4. Creating a new sudo user account
If you forget your user name, you can use VMAccess to create a new one with the sudo authority. In this case, your existing user name and credentials will not be modified. To create a new sudo user with password access, use the script in scenario 1; to create a new sudo user with SSH key access, use the script in scenario 2; you can also use scenario 3 to create a new user with both password and key access. Please note that for the “UserName” field, you need to enter a new user name.
5. Resetting the SSH configuration
If the SSH configuration is in an undesired state, you might also lose access to the VM. You can use the VMAccess extension to reset the configuration to default. To do so, you just need to set the “reset_ssh” key to “True”. The extension will restart the SSH server, open the SSH port on your VM, and reset the SSH configuration to default. The user account (name, password or SSH keys) will not be changed. Note: The SSH configuration file that gets reset is located at /etc/ssh/sshd_config.
Step 1: Create a file named PrivateConf.json with following content:
{
"reset_ssh":"True",
}
Step 2: Run ‘azure vm extension set vmname VMAccessForLinux Microsoft.OSTCExtensions 1.* –private-config-path PrivateConf.json’
6. Removing an existing user
If you want to delete a user account without logging into to the VM directly, you can utilize following script:
Step 1: Create a file named PrivateConf.json with following content:
{
"remove_user":"usertoberemoveed",
}
Step 2: Run ‘azure vm extension set vmname VMAccessForLinux Microsoft.OSTCExtensions 1.* –private-config-path PrivateConf.json’
Use the VMAccess Extension through PowerShell
There are 6 scenarios where you might use VMAccess to gain your access to your VM. The following are scenarios and the corresponding sample PowerShell scripts. Note that you only need to specify different parameters for each scenario, the section after “Begin execution” is the same regardless of the below scenario.
1. Resetting the password
$vm = Get-AzureVM -ServiceName 'MyServiceName' -Name 'MyVMName'
#Enter your current user name and new password
$UserName = "MyCurrentUserName"
$Password = "MyNewPassWord"
[hashtable]$Param=@{};
$Param['username'] = $UserName;
$Param['password'] = $Password;
$Param['expiration'] = '2016-01-01';
$PrivateConfig = ConvertTo-Json $Param;
#Begin execution
$ExtensionName = 'VMAccessForLinux'
$Publisher = 'Microsoft.OSTCExtensions'
$Version = '1.*'
Set-AzureVMExtension -ExtensionName $ExtensionName -VM $vm -Publisher $Publisher -Version $Version -PrivateConfiguration $PrivateConfig | Update-AzureVM
2. Resetting the SSH key
#Sample script for you to reset your SSH keys
#Identify the VM
$vm = Get-AzureVM -ServiceName 'MyServiceName' -Name 'MyVMName'
#Enter the current user name and the path of your new public SSH key
$UserName = "CurrentName"
$cert = Get-Content "CertPath"
$PrivateConfig = '{"username":"' + $UserName + '", "ssh_key":"' + $cert + '"}'
# Begin execution
$ExtensionName = 'VMAccessForLinux'
$Publisher = 'Microsoft.OSTCExtensions'
$Version = '1.X'
Set-AzureVMExtension -ExtensionName $ExtensionName -VM $vm -Publisher $Publisher -Version $Version -PrivateConfiguration $PrivateConfig | Update-AzureVM
3. Resetting the password and the SSH key
#Sample script to reset your password and SSH key
#Identify the VM
$vm = Get-AzureVM -ServiceName 'MyServiceName' -Name 'MyVMName'
#Enter the new password, and cert path of the new SSH public key, with the current user name
$UserName = "CurrentName"
$Password = "NewPassword"
$cert = Get-Content "CertPath"
$PrivateConfig = '{"username":"' + $UserName + '", "password": "' + $Password + '", "ssh_key":"' + $cert + '"}'
# Begin execution
$ExtensionName = 'VMAccessForLinux'
$Publisher = 'Microsoft.OSTCExtensions'
$Version = '1.*'
Set-AzureVMExtension -ExtensionName $ExtensionName -VM $vm -Publisher $Publisher -Version $Version -PrivateConfiguration $PrivateConfig | Update-AzureVM
4. Creating a new sudo user account
If you forget your user name, you can use VMAccess to create a new one with the sudo authority. In this case, your existing user name and credentials will not be modified. To create a new sudo user with password access, use the script in scenario 1; to create a new sudo user with SSH key access, use the script in scenario 2; you can also use scenario 3 to create a new user with both password and key access. Please note for the“UserName” field, you need to enter a new user name.
5. Resetting the SSH configuration
If the SSH configuration is in an undesired state, you might also lose access to the VM. You can use the VMAccess extension to reset the configuration to default. To do so, you just need to set the “reset_ssh” key to “True”. The extension will restart the SSH server, open the SSH port on your VM, and reset the SSH configuration to default. The user account (name, password or SSH keys) will not be changed. Note: The SSH configuration file that gets reset is located at /etc/ssh/sshd_config.
#Sample script to reset the SSH configuration on your VM
#Identify the VM
$vm = Get-AzureVM -ServiceName 'MyServiceName' -Name 'MyVMName'
$PrivateConfig = '{"reset_ssh": "True"}'
# Begin execution
$ExtensionName = 'VMAccessForLinux'
$Publisher = 'Microsoft.OSTCExtensions'
$Version = '1.*'
Set-AzureVMExtension -ExtensionName $ExtensionName -VM $vm -Publisher $Publisher -Version $Version -PrivateConfiguration $PrivateConfig | Update-AzureVM
6. Removing an existing user
If you want to delete a user account without logging into to the VM directly, you can utilize following script:
#Sample script to delete the a user account
#Identify the VM
$vm = Get-AzureVM -ServiceName 'MyServiceName' -Name 'MyVMName'
#Identify the user account you want to delete
$UserName = "SomeUser"
$PrivateConfig = '{"remove_user": "' + $UserName + '"}'
# Begin execution
$ExtensionName = 'VMAccessForLinux'
$Publisher = 'Microsoft.OSTCExtensions'
$Version = '1.*'
Set-AzureVMExtension -ExtensionName $ExtensionName -VM $vm -Publisher $Publisher -Version $Version -PrivateConfiguration $PrivateConfig | Update-AzureVM
Query the results
The status of the VMAccess extension could be retrieved using the xplat command ‘azure vm extension get’ or PowerShell cmdlet Get-AzureVM, Get-Deployment.
Access the VM after resetting
After the VMAccess Extension completes, you can log on to the instance using the new account name, password or SSH key.
Additional Notes
If you only want to reset the password or SSH key for the existing user account, you need to make sure the user name you entered matches the original user name. If you enter a name that is different from your original name, the VMAccess extension will treat this as a “Creating a new user” scenario, and will create a new user account with the specified password or key.
Known issue
When you run the PowerShell command “Set-AzureVMExtension” on a Linux VM, you may hit the following error: “Provision Guest Agent must be enabled on the VM object before setting IaaS VM Access Extension”. Note that this issue will not occur on the new portal.
Root Cause: when you create an image via the Azure portal, the value of the guest agent on the VM is not always set to “True”. If your VM is created using PowerShell, you will not see this issue.
Resolution: Add the following PowerShell command to set the ProvisionGuestAgent to “True”;
$vm = Get-AzureVM -ServiceName 'MyServiceName' -Name 'MyVMName' $vm.GetInstance().ProvisionGuestAgent = $true