4369346c30 | ||
---|---|---|
.. | ||
resources | ||
test | ||
CHANGELOG.md | ||
HandlerManifest.json | ||
README.md | ||
extension_shim.sh | ||
manifest.xml | ||
references | ||
vmaccess.py |
README.md
VMAccess Extension
Provide several ways to allow owner of the VM to get the SSH access back and perform additional VM disk check tasks.
Current version is 1.5.
You can read the User Guide below.
VMAccess Extension can:
- Reset the password of the original sudo user
- Create a new sudo user with the password specified
- Set the public host key with the key given
- Reset the public host key provided during VM provisioning if host key not provided
- Open the SSH port(22) and reset the sshd_config if reset_ssh is set to true
- Remove the existing user
- Check disks
- Repair added disk
- Remove prior public keys when a new public key is provided
- Restore the original backup sshd_config if restore_backup_ssh is set to true
Security Notes:
- VMAccess Extension is designed for regaining access to a VM in the event that access is lost.
- Based on this principle, it will grant sudo permission to the account specified in the username field.
- Do not specify a user in the username field if you do not wish that user to gain sudo permissions.
- Instead, login to the VM and use built-in tools (e.g. usermod, chage, etc) to manage unprivileged users.
User Guide
1. Configuration schema
1.1. Public configuration
Schema for the public configuration file looks like:
check_disk
: (optional, boolean) whether or not to check diskrepair_disk
: (optional, boolean) whether or not to repair diskdisk_name
: (boolean) name of disk to repair (required when repair_disk is true)
{
"check_disk": "true",
"repair_disk": "true",
"disk_name": "<disk-name>"
}
1.2. Protected configuration
Schema for the protected configuration file looks like this:
username
: (required, string) the name of the userpassword
: (optional, string) the password of the userssh_key
: (optional, string) the public key of the userreset_ssh
: (optional, boolean) whether or not reset the sshremove_user
: (optional, string) the user name to removeexpiration
: (optional, string) expiration of the account, defaults to never, e.g. 2016-01-01.remove_prior_keys
: (optional, boolean) whether or not to remove old SSH keys when adding a new onerestore_backup_ssh
: (optional, boolean) whether or not to restore original backed-up sshd config
{
"username": "<username>",
"password": "<password>",
"ssh_key": "<cert-contents>",
"reset_ssh": true,
"remove_user": "<username-to-remove>",
"expiration": "<yyyy-mm-dd>",
"remove_prior_keys": true,
"restore_backup_ssh": true
}
ssh_key
supports ssh-rsa
, ssh-ed25519
and .pem
formats.
-
If your public key is in
ssh-rsa
format, for example,ssh-rsa XXXXXXXX
, you can use:"ssh_key": "ssh-rsa XXXXXXXX"
-
If your public key is in
ssh-ed25519
format, for example,ssh-ed25519 XXXXXXXX
, you can use:"ssh_key": "ssh-ed25519 XXXXXXXX"
-
If your public key is in
.pem
format, use the following UNIX command to convert the .pem file to a value that can be passed in a JSON string:awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' myCert.pem
You can use:
"ssh_key": "-----BEGIN CERTIFICATE-----\nXXXXXXXXXXXXXXXXXXXXXXXX\n-----END CERTIFICATE-----"
2. Deploying the Extension to a VM
You can deploy it using Azure CLI, Azure Powershell and ARM template.
2.1. Using Azure CLI
Create a settings.json
(optional) and a protected_settings.json
and run:
$ azure vm extension set \
--resource-group <resource-group> \
--vm-name <vm-name> \
--name VMAccessForLinux \
--publisher Microsoft.OSTCExtensions \
--version 1.5 \
--settings settings.json
--protected-settings protected_settings.json
To retrieve the deployment state of extensions for a given VM, run:
$ azure vm extension list \
--resource-group <resource-group> \
--vm-name <vm-name> -o table
2.2. Using Azure Powershell
You can deploying VMAccess Extension 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 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
2.3. Using ARM Template
{
"type": "Microsoft.Compute/virtualMachines/extensions",
"name": "<extension-deployment-name>",
"apiVersion": "<api-version>",
"location": "<location>",
"dependsOn": [
"[concat('Microsoft.Compute/virtualMachines/', <vm-name>)]"
],
"properties": {
"publisher": "Microsoft.OSTCExtensions",
"type": "VMAccessForLinux",
"typeHandlerVersion": "1.5",
"autoUpgradeMinorVersion": true,
"settings": {},
"protectedSettings": {
"username": "<username>",
"password": "<password>",
"reset_ssh": true,
"ssh_key": "<ssh-key>",
"remove_user": "<username-to-remove>"
}
}
}
Refer to the following sample ARM template.
For more details about ARM template, please visit Authoring Azure Resource Manager templates.
3. Scenarios
3.1 Resetting the password
in the Public Settings
{
"check_disk": "false"
}
VMAccessForLinux resets and restarts the SSH server if a password is specified. This is necessary if the VM was deployed with public key authentication because the SSH server is not configured to accept passwords. For this reason, the SSH server's configuration is reset to allow password authentication, and restarted to accept this new configuration. This behavior can be disabled by setting the reset_ssh value to false.
in the Protected Settings
{
"username": "currentusername",
"password": "newpassword",
"reset_ssh": "false"
}
3.2 Resetting the SSH key
{
"username": "currentusername",
"ssh_key": "contentofsshkey"
}
3.3 Resetting the password and the SSH key
{
"username": "currentusername",
"ssh_key": "contentofsshkey",
"password": "newpassword",
}
3.4 Creating a new sudo user account with the password
{
"username": "newusername",
"password": "newpassword"
}
3.4.1 Creating a new sudo user account with a password and expiration date.
{
"username": "newusername",
"password": "newpassword",
"expiration": "2016-12-31"
}
3.5 Creating a new sudo user account with the SSH key
{
"username": "newusername",
"ssh_key": "contentofsshkey"
}
3.5.1 Creating a new sudo user account with the SSH key
{
"username": "newusername",
"ssh_key": "contentofsshkey",
"expiration": "2016-12-31"
}
3.6 Resetting the SSH configuration
{
"reset_ssh": true
}
3.7 Removing an existing user
{
"remove_user": "usertoberemoveed",
}
3.8 Checking added disks on VM
{
"check_disk": "true"
}
3.9 Fix added disks on a VM
{
"repair_disk": "true",
"disk_name": "userdisktofix"
}
3.10 Removing prior SSH keys (only when provided a new one)
{
"username": "newusername",
"ssh_key": "contentofsshkey",
"remove_prior_keys": true
}
3.11 Restoring original SSH configuration
{
"restore_backup_ssh": true
}
Supported Linux Distributions
- Ubuntu 12.04 and higher
- CentOS 6.5 and higher
- Oracle Linux 6.4.0.0.0 and higher
- openSUSE 13.1 and higher
- SUSE Linux Enterprise Server 11 SP3 and higher
Debug
- The status of the extension is reported back to Azure so that user can see the status on Azure Portal
- The operation log of the extension is
/var/log/azure/<extension-name>/<version>/extension.log
file.