Edit

Bagikan melalui

Troubleshoot SSH connections to an Azure Linux VM that fails, errors out, or is refused

  • Artikel

Applies to: ✔️ Linux VMs

This article helps you find and correct the problems that occur due to Secure Shell (SSH) errors, SSH connection failures, or SSH is refused when you try to connect to a Linux virtual machine (VM). You can use the Azure portal, Azure CLI, or VM Access Extension for Linux to troubleshoot and resolve connection problems.

Note

Was this article helpful? Your input is important to us. Please use the Feedback button on this page to let us know how well this article worked for you or how we can improve it.

Quick troubleshooting steps

After each troubleshooting step, try reconnecting to the VM.

  1. Reset the SSH configuration.
  2. Reset the credentials for the user.
  3. Verify the network security group rules permit SSH traffic and role assignment.
    • Ensure that a Network Security Group rule exists to permit SSH traffic (by default, TCP port 22).
    • You cannot use port redirection / mapping without using an Azure load balancer.
    • If you are using Microsoft Entra ID to manage SSH logins, the user must be assigned the Virtual Machine Administrator Login or Virtual Machine User Login role on the resource group that contains the VM and its associated resources. Otherwise, the "Permission denied (publickey)" error will be received. For more information, see Configure role assignments for the VM that uses Microsoft Entra login.
  4. Check the VM resource health.
    • Ensure that the VM reports as being healthy.
    • If you have boot diagnostics enabled, verify the VM is not reporting boot errors in the logs.
  5. Restart the VM.
  6. Redeploy the VM.

Continue reading for more detailed troubleshooting steps and explanations.

Available methods to troubleshoot SSH connection issues

You can reset credentials, SSH configuration, or troubleshoot the status of the SSH service by using one of the following methods:

  • Azure portal - great if you need to quickly reset the SSH configuration or SSH key and you don't have the Azure tools installed.
  • Azure VM Serial Console - the VM serial console will work regardless of the SSH configuration, and will provide you with an interactive console to your VM. In fact, "can't SSH" situations are specifically what the serial console was designed to help solve. More details below.
  • Use Run Command through Azure portal - You can run basic commands by using the Run Command functionality through the Azure portal. The output will be returned to the portal.
  • Azure CLI - if you are already on the command line, quickly reset the SSH configuration or credentials.
  • Azure VMAccessForLinux extension - create and reuse json definition files to reset the SSH configuration or user credentials.

After each troubleshooting step, try connecting to your VM again. If you still cannot connect, try the next step.

Use the Azure portal

The Azure portal provides a quick way to reset the SSH configuration or user credentials without installing any tools on your local computer.

To begin, select your VM in the Azure portal. Scroll down to the Help section and select Reset password as in the following example:

Screenshot to reset the SSH configuration or credentials in the Azure portal.

Reset the SSH configuration

To reset the SSH configuration, select Reset configuration only in the Mode section as in the preceding screenshot, then select Update. Once this action has completed, try to access your VM again.

Reset SSH credentials for a user

To reset the credentials of an existing user, select either Reset SSH public key or Reset password in the Mode section as in the preceding screenshot. Specify the username and an SSH key or new password, then select Update.

You can also create a user with sudo privileges on the VM from this menu. Enter a new username and associated password or SSH key, and then select Update.

Check security rules

Use IP flow verify to confirm if a rule in a network security group is blocking traffic to or from a virtual machine. You can also review effective security group rules to ensure inbound "Allow" NSG rule exists and is prioritized for SSH port (default 22). For more information, see Using effective security rules to troubleshoot VM traffic flow.

Check routing

Use Network Watcher's Next hop capability to confirm that a route isn't preventing traffic from being routed to or from a virtual machine. You can also review effective routes to see all effective routes for a network interface. For more information, see Using effective routes to troubleshoot VM traffic flow.

Use the Azure VM Serial Console

The Azure VM Serial Console provides access to a text-based console for Linux virtual machines. You can use the console to troubleshoot your SSH connection in an interactive shell. Ensure you have met the prerequisites for using Serial Console and try the commands below to further troubleshoot your SSH connectivity.

Check that SSH service is running

To check the service status, use the following command, which is available in most current Linux distributions:

sudo systemctl status sshd.service

See the following output example. Check the service status from the Active line in the output. The output also shows the port and IP addresses being listened to.

user@hostname:~$ sudo systemctl status sshd.service
● ssh.service - OpenBSD Secure Shell server
     Loaded: loaded (/lib/systemd/system/ssh.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2022-06-23 17:44:36 UTC; 1 day 3h ago
       Docs: man:sshd(8)
             man:sshd_config(5)
   Main PID: 829 (sshd)
      Tasks: 1 (limit: 9535)
     Memory: 5.1M
     CGroup: /system.slice/ssh.service
             └─829 sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups

Jun 23 17:44:35 ubu2004 systemd[1]: Starting OpenBSD Secure Shell server...
Jun 23 17:44:36 ubu2004 sshd[829]: Server listening on 0.0.0.0 port 22.
Jun 23 17:44:36 ubu2004 sshd[829]: Server listening on :: port 22.
Jun 23 17:44:36 ubu2004 systemd[1]: Started OpenBSD Secure Shell server.

If this command isn't available or returns unexpected results, use other available commands. You can use the ss command either as root or via the sudo command to verify whether the SSH service is running on your VM.

The following example shows how to run the ss command through sudo:

sudo ss --listen --tcp --process --numeric | grep sshd

Note

We recommend the ss command because the netstat command is deprecated and not always available in modern distributions.

If there is any output, SSH is up and running. See the following output example:

$ sudo ss -ltpn | grep sshd
LISTEN    0         128                0.0.0.0:22               0.0.0.0:*        users:(("sshd",pid=829,fd=3))
LISTEN    0         128                   [::]:22                  [::]:*        users:(("sshd",pid=829,fd=4))

-ltpn is the shortened form of the --listen --tcp --process –numeric arguments. The output shows that the SSHD process 829 is listening on both IPv4 and IPv6 addresses.

Check which port SSH is running on

The command output above shows that the SSHD process is listening on port 22. When the SSHD process is configured to run on another port, the port will be displayed in the output. To check if the change was made in the standard configuration file, examine the default configuration file, /etc/ssh/sshd_config by using one of the following commands:

grep -i port /etc/ssh/sshd_config

or

grep -i listen /etc/ssh/sshd_config

The output will look like the following:

Port 22

Any line that begins with # in the output is a comment and can be safely ignored. If nothing is returned, or the lines are comments, the default configuration is used. The default configuration is to listen to all IP addresses on the system, on port 22.

Use Run Command through Azure portal

If you are not able to run commands through the Serial Console, for example when only SSH keys are used for authentication, the Run Command feature can be used to issue commands and view the output. All commands that were previously run from the Serial Console can be run non-interactively in the Run Command section in the Azure portal. The output will be returned to the Azure portal. There is no need to use sudo to run commands in the Run Command context.

Use the Azure CLI

If you haven't already, install the latest Azure CLI and sign in to an Azure account using az login.

If you created and uploaded a custom Linux disk image, make sure the Microsoft Azure Linux Agent version 2.0.5 or later is installed. For VMs created using Gallery images, this access extension is already installed and configured for you.

Reset SSH configuration

You can initially try resetting the SSH configuration to default values and rebooting the SSH server on the VM. This does not change the user account name, password, or SSH keys. The following example uses az vm user reset-ssh to reset the SSH configuration on the VM named myVM in myResourceGroup. Use your own values as follows:

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

Reset SSH credentials for a user

The following example uses az vm user update to reset the credentials for myUsername to the value specified in myPassword, on the VM named myVM in myResourceGroup. Use your own values as follows:

az vm user update --resource-group myResourceGroup --name myVM \
     --username myUsername --password myPassword

If using SSH key authentication, you can reset the SSH key for a given user. The following example uses az vm access set-linux-user to update the SSH key stored in ~/.ssh/id_rsa.pub for the user named myUsername, on the VM named myVM in myResourceGroup. Use your own values as follows:

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

Use the VMAccess extension

The VM Access Extension for Linux reads in a json file that defines actions to carry out. These actions include resetting SSHD, resetting an SSH key, or adding a user. You still use the Azure CLI to call the VMAccess extension, but you can reuse the json files across multiple VMs if desired. This approach allows you to create a repository of json files that can then be called for given scenarios.

Reset SSHD

Create a file named settings.json with the following content:

{
    "reset_ssh":True
}

Using the Azure CLI, you then call the VMAccessForLinux extension to reset your SSHD connection by specifying your json file. The following example uses az vm extension set to reset SSHD on the VM named myVM in myResourceGroup. Use your own values as follows:

az vm extension set --resource-group philmea --vm-name Ubuntu \
    --name VMAccessForLinux --publisher Microsoft.OSTCExtensions --version 1.2 --settings settings.json

Reset SSH credentials for a user

If SSHD appears to function correctly, you can reset the credentials for a giver user. To reset the password for a user, create a file named settings.json. The following example resets the credentials for myUsername to the value specified in myPassword. Enter the following lines into your settings.json file, using your own values:

{
    "username":"myUsername", "password":"myPassword"
}

Or to reset the SSH key for a user, first create a file named settings.json. The following example resets the credentials for myUsername to the value specified in myPassword, on the VM named myVM in myResourceGroup. Enter the following lines into your settings.json file, using your own values:

{
    "username":"myUsername", "ssh_key":"mySSHKey"
}

After creating your json file, use the Azure CLI to call the VMAccessForLinux extension to reset your SSH user credentials by specifying your json file. The following example resets credentials on the VM named myVM in myResourceGroup. Use your own values as follows:

az vm extension set --resource-group philmea --vm-name Ubuntu \
    --name VMAccessForLinux --publisher Microsoft.OSTCExtensions --version 1.2 --settings settings.json

Reset SSH configuration

The SSHD configuration itself may be misconfigured or the service encountered an error. You can reset SSHD to make sure the SSH configuration itself is valid. Resetting SSHD should be the first troubleshooting step you take.

The following example resets SSHD on a VM named myVM in the resource group named myResourceGroup. Use your own VM and resource group names as follows:

azure vm reset-access --resource-group myResourceGroup --name myVM \
    --reset-ssh

Reset SSH credentials for a user

If SSHD appears to function correctly, you can reset the password for a giver user. The following example resets the credentials for myUsername to the value specified in myPassword, on the VM named myVM in myResourceGroup. Use your own values as follows:

azure vm reset-access --resource-group myResourceGroup --name myVM \
     --user-name myUsername --password myPassword

If using SSH key authentication, you can reset the SSH key for a given user. The following example updates the SSH key stored in ~/.ssh/id_rsa.pub for the user named myUsername, on the VM named myVM in myResourceGroup. Use your own values as follows:

azure vm reset-access --resource-group myResourceGroup --name myVM \
    --user-name myUsername --ssh-key-file ~/.ssh/id_rsa.pub

Restart a VM

If you have reset the SSH configuration and user credentials, or encountered an error in doing so, you can try restarting the VM to address underlying compute issues.

Azure portal

To restart a VM using the Azure portal, select your VM and then select Restart as in the following example:

Screenshot to restart a virtual machine in the Azure portal.

Azure CLI

The following example uses az vm restart to restart the VM named myVM in the resource group named myResourceGroup. Use your own values as follows:

az vm restart --resource-group myResourceGroup --name myVM

Redeploy a VM

You can redeploy a VM to another node within Azure, which may correct any underlying networking issues. For information about redeploying a VM, see Redeploy virtual machine to new Azure node.

Note

After this operation finishes, ephemeral disk data is lost and dynamic IP addresses that are associated with the virtual machine are updated.

Azure portal

To redeploy a VM using the Azure portal, select your VM and scroll down to the Help section. Select Redeploy as in the following example:

Screenshot to redeploy a virtual machine in the Azure portal.

Azure CLI

The following example use az vm redeploy to redeploy the VM named myVM in the resource group named myResourceGroup. Use your own values as follows:

az vm redeploy --resource-group myResourceGroup --name myVM

Additional resources

Contact us for help

If you have questions or need help, create a support request, or ask Azure community support. You can also submit product feedback to Azure feedback community.