Extensão VMAccess para Linux

2025-05-03

A Extensão VMAccess é usada para gerenciar usuários administrativos, configurar SSH e verificar ou reparar discos em máquinas virtuais Linux do Azure. A extensão integra-se com modelos do Azure Resource Manager. Ele também pode ser invocado usando a CLI do Azure, o Azure PowerShell, o portal do Azure e a API REST das Máquinas Virtuais do Azure.

Este artigo descreve como executar a extensão VMAccess a partir da CLI do Azure e através de um modelo do Azure Resource Manager. Este artigo também fornece etapas de solução de problemas para sistemas Linux.

Nota

Se você usar a extensão VMAccess para redefinir a senha da sua VM depois de instalar a extensão Microsoft Entra Login, execute novamente a extensão Microsoft Entra Login para reativar o Microsoft Entra Login para sua VM.

Pré-requisitos

Distribuições Linux suportadas

Linux Distro	x64	ARM64
Alma Linux	9.x+	9.x+
Debian	Mais de 10	11.x+
Flatcar Linux	3374.2.x+	3374.2.x+
Azure Linux	2.x	2.x
openSUSE	12.3+	Não suportado
Oracle Linux	6,4+, 7,x+, 8,x+	Não suportado
Red Hat Enterprise Linux	6,7+, 7,x+, 8,x+	8.6+, 9.0+
Linux rochoso	9.x+	9.x+
SLES	12,x+, 15,x+	15.x SP4+
Ubuntu	18.04+, 20.04+, 22.04+	20.04+, 22.04+

Sugestões

O VMAccess foi projetado para recuperar o acesso a uma VM dado que o acesso é perdido. Com base neste princípio, ele concede permissão sudo para a conta especificada no campo nome de usuário. Se você não deseja que um usuário obtenha permissões sudo, faça login na VM e use ferramentas internas (por exemplo, usermod, chage, etc.) para gerenciar usuários sem privilégios.
Você só pode ter uma versão da extensão aplicada a uma VM. Para executar uma segunda ação, atualize a extensão existente com uma nova configuração.
Durante uma atualização do usuário, o VMAccess altera o sshd_config arquivo e faz um backup dele previamente. Muda ChallengeResponseAuthentication para no e PasswordAuthentication para yes. Para restaurar a configuração SSH original de backup, execute VMAccess com restore_backup_ssh definido como True.

Esquema de extensão

A configuração VMAccess Extension inclui definições para nome de usuário, senhas, chaves SSH, etc. Você pode armazenar essas informações em arquivos de configuração, especificá-las na linha de comando ou incluí-las em um modelo do Azure Resource Manager (ARM). O esquema JSON a seguir contém todas as propriedades disponíveis para uso em configurações públicas e protegidas.

{
  "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
    } 
  }
}

Valores de propriedade

Nome	Valor / Exemplo	Tipo de Dados
Versão da API	2023-09-01	data
editora	Microsoft.OSTCExtensions	cadeia de caracteres
tipo	VMAccessForLinux	cadeia de caracteres
typeHandlerVersion	1.5	número inteiro

Valores das propriedades de definições

Nome	Tipo de Dados	Descrição
verificar_disco	Booleano	Verificar ou não o disco (opcional). Apenas um entre `check_disk` e `repair_disk` pode ser definido como true.
reparar_disco	Booleano	Verificar ou não o disco (opcional). Apenas um entre `check_disk` e `repair_disk` pode ser definido como true.
nome_disco	cadeia de caracteres	Nome do disco a reparar (necessário quando `repair_disk` for verdadeiro).
nome de utilizador	cadeia de caracteres	O nome do usuário a ser gerenciado (necessário para todas as ações em uma conta de usuário).
palavra-passe	cadeia de caracteres	A senha a ser definida para a conta de usuário.
ssh_key	cadeia de caracteres	A chave pública SSH a ser adicionada para a conta de usuário. A chave SSH pode estar em `ssh-rsa`, `ssh-ed25519`ou `.pem` formato.
reset_ssh	Booleano	Se deve ou não redefinir o SSH. Se `true`, ele substitui o arquivo sshd_config por um arquivo de recurso interno correspondente à configuração SSH padrão para essa distro.
remove_user	cadeia de caracteres	O nome do usuário a ser removido. Não pode ser usado com `reset_ssh`, `restore_backup_ssh`e `password`.
expiração	cadeia de caracteres	Expiração a definir para a conta, na forma de `yyyy-mm-dd`. O padrão é nunca.
remove_prior_keys	Booleano	Remover ou não chaves SSH antigas ao adicionar uma nova. Deve ser utilizado com `ssh_key`.
restore_backup_ssh	Booleano	Restaurar ou não o sshd_config originalmente guardado como backup.

Implementação de modelos

As Extensões de VM do Azure podem ser implantadas com modelos do Azure Resource Manager (ARM). O esquema JSON detalhado na seção anterior pode ser usado em um modelo ARM para executar a extensão VMAccess durante a implantação do modelo. Você pode encontrar um modelo de exemplo que inclui a extensão VMAccess no GitHub.

A configuração JSON para uma extensão de máquina virtual deve ser inserida dentro do fragmento de recurso de máquina virtual do modelo, especificamente no objeto "resources": [] para o modelo de máquina virtual e sob o objeto "virtualMachineProfile":"extensionProfile":{"extensions" :[] para um conjunto de dimensionamento de máquina virtual.

Implementação da CLI do Azure

Usando comandos de usuário da VM da CLI do Azure

Os seguintes comandos da CLI em az vm user usam a extensão VMAccess. Para usar esses comandos, você precisa instalar a CLI do Azure mais recente e entrar em uma conta do Azure usando az login.

Update SSH key (Atualizar as chaves de SSH)

O exemplo a seguir atualiza a chave SSH para o usuário azureUser na VM chamada myVM:

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

Nota

O az vm user update comando acrescenta o novo texto de chave pública ao ~/.ssh/authorized_keys arquivo para o usuário administrador na VM. Este comando não substitui nem remove nenhuma chave SSH existente. Este comando não remove chaves anteriores definidas no momento da implantação ou atualizações subsequentes usando a extensão VMAccess.

Repor palavra-passe

O exemplo a seguir redefine a senha do usuário azureUser na VM chamada myVM:

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

Reiniciar SSH

O exemplo a seguir reinicia o daemon SSH e redefine a configuração SSH para valores padrão em uma VM chamada myVM:

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

Nota

O az vm user reset-ssh comando substitui o arquivo sshd_config por um arquivo de configuração padrão do diretório de recursos internos. Este comando não restaura a configuração SSH original encontrada na máquina virtual.

Criar um utilizador administrativo/sudo

O exemplo a seguir cria um usuário nomeado myNewUser com permissões sudo. A conta usa uma chave SSH para autenticação na VM chamada myVM. Esse método ajuda você a recuperar o acesso a uma VM quando as credenciais atuais são perdidas ou esquecidas. Como prática recomendada, as contas com permissões sudo devem ser restritas.

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

Eliminar um utilizador

O exemplo a seguir exclui um usuário nomeado myNewUser na VM chamada myVM:

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

Usando comandos de extensão VM/VMSS da CLI do Azure

Você também pode usar os comandos az vm extension set e az vmss extension set para executar a VMAccess Extension com a configuração especificada.

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"}'

Os --settings parâmetros e --protected-settings também aceitam caminhos de arquivo JSON. Por exemplo, para atualizar a chave pública SSH de um usuário, crie um arquivo JSON chamado update_ssh_key.json e adicione configurações no formato a seguir. Substitua os valores dentro do arquivo por suas próprias informações:

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

Execute a extensão VMAccess através do seguinte comando:

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

Implantação do Azure PowerShell

O Azure PowerShell pode ser usado para implantar a Extensão VMAccess em uma máquina virtual existente ou em um conjunto de dimensionamento de máquina virtual. Você pode implantar a extensão em uma VM executando:

$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

Você também pode fornecer e modificar configurações de extensão usando cadeias de caracteres:

$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

Para implementar num conjunto de escalonamento de máquinas virtuais, execute o seguinte comando:

$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

Solução de problemas e suporte

Os logs de extensão do VMAccess existem localmente na VM e são mais informativos quando se trata de solução de problemas.

Localização	Descrição
/var/log/waagent.log	Contém logs do Agente Linux e mostra quando ocorreu uma atualização para a extensão. Podemos verificá-lo para garantir que a extensão funcionou.
/var/log/azure/Microsoft.OSTCExtensions.VMAccessForLinux/*	A extensão VMAccess produz logs, que podem ser encontrados aqui. O diretório contém `CommandExecution.log` onde você pode encontrar cada comando executado junto com seu resultado, juntamente com `extension.log`, que contém logs individuais para cada execução.
/var/lib/waagent/Microsoft.OSTCExtensions.VMAccessForLinux-<versão mais recente>/config/*	A configuração e os binários para VMAccess VM Extension.

Você também pode recuperar o estado de execução da extensão VMAccess, juntamente com outras extensões em uma determinada VM, executando o seguinte comando:

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

Mensagens de erro

Erro	Descrição
O provisionamento da extensão VM enablevmaccess expirou. O provisionamento de extensão levou muito tempo para ser concluído. A extensão não informou uma mensagem. Mais informações sobre solução de problemas estão disponíveis em https://aka.ms/vmextensionlinuxtroubleshoot.	A mensagem de erro indica que o provisionamento da extensão de VM 'enablevmaccess' expirou devido a demorar muito para ser concluído. Além disso, a extensão não forneceu nenhuma mensagem de status durante o processo. Para resolver esse problema, considere verificar o desempenho da VM e as condições de rede e tente novamente a operação de provisionamento. Para obter mais informações, consulte Solucionar problemas de extensões de VM.
A VM relatou uma falha ao processar a extensão 'enablevmaccess' (editor 'Microsoft.OSTCExtensions' e tipo 'VMAccessForLinux'). Mensagem de erro: 'Falha ao ativar: nenhuma senha ou ssh_key é especificada.'. Mais informações sobre solução de problemas estão disponíveis em https://aka.ms/vmextensionlinuxtroubleshoot .	A mensagem de erro indica que a VM falhou ao processar a extensão 'enablevmaccess' porque nenhuma senha ou chave SSH foi especificada. Esta falha está associada ao editor 'Microsoft.OSTCExtensions' e ao tipo 'VMAccessForLinux'. Para resolver esse problema, verifique se uma senha ou uma chave SSH é fornecida durante a configuração da extensão.

Erro

Descrição

O provisionamento da extensão VM enablevmaccess expirou. O provisionamento de extensão levou muito tempo para ser concluído. A extensão não informou uma mensagem. Mais informações sobre solução de problemas estão disponíveis em https://aka.ms/vmextensionlinuxtroubleshoot.

A mensagem de erro indica que o provisionamento da extensão de VM 'enablevmaccess' expirou devido a demorar muito para ser concluído. Além disso, a extensão não forneceu nenhuma mensagem de status durante o processo. Para resolver esse problema, considere verificar o desempenho da VM e as condições de rede e tente novamente a operação de provisionamento. Para obter mais informações, consulte Solucionar problemas de extensões de VM.

A VM relatou uma falha ao processar a extensão 'enablevmaccess' (editor 'Microsoft.OSTCExtensions' e tipo 'VMAccessForLinux'). Mensagem de erro: 'Falha ao ativar: nenhuma senha ou ssh_key é especificada.'. Mais informações sobre solução de problemas estão disponíveis em https://aka.ms/vmextensionlinuxtroubleshoot .

A mensagem de erro indica que a VM falhou ao processar a extensão 'enablevmaccess' porque nenhuma senha ou chave SSH foi especificada. Esta falha está associada ao editor 'Microsoft.OSTCExtensions' e ao tipo 'VMAccessForLinux'. Para resolver esse problema, verifique se uma senha ou uma chave SSH é fornecida durante a configuração da extensão.

Para obter mais ajuda, pode contactar os especialistas do Azure em Suporte da Comunidade do Azure. Como alternativa, você pode registrar um incidente de suporte do Azure. Vá para Suporte do Azure e selecione Obter suporte. Para obter mais informações sobre o Suporte do Azure, leia as Perguntas frequentes sobre planos de suporte do Azure.

Próximos passos

Para ver o código, as versões atuais e mais documentação, consulte VMAccess Linux - GitHub.

Partilhar via

Extensão VMAccess para Linux

Pré-requisitos

Distribuições Linux suportadas

Sugestões

Esquema de extensão

Valores de propriedade

Valores das propriedades de definições

Implementação de modelos

Implementação da CLI do Azure

Usando comandos de usuário da VM da CLI do Azure

Update SSH key (Atualizar as chaves de SSH)

Repor palavra-passe

Reiniciar SSH

Criar um utilizador administrativo/sudo

Eliminar um utilizador

Usando comandos de extensão VM/VMSS da CLI do Azure

Implantação do Azure PowerShell

Solução de problemas e suporte

Mensagens de erro

Próximos passos

Comentários

Recursos adicionais