Connect to an Azure Local VM using SSH, RDP over SSH, or VM Connect (preview)

Applies to: Hyperconverged deployments of Azure Local

This article describes how to connect to an Azure Local VM in two scenarios:

1. Use SSH and Remote Desktop Protocol (RDP) over SSH to connect to an Azure Local VM enabled by Azure Arc.
2. Use VM Connect (preview) to connect to an Azure Local VM that doesn't have network connectivity or has boot failures.

Connect to an Azure Local VM using SSH and RDP over SSH

Azure Arc uses the SSH service (sshd) running inside the VM, but you establish connections through Azure Arc rather than directly over the network. You don't need to open any public IP address or inbound SSH ports on the VM for connectivity. For more information, see SSH access to Azure Arc-enabled servers.

The SSH server extension provides access to both Windows and Linux Azure Local VMs.

SSH prerequisites

Before you begin, make sure that you:

1. Have access to Azure Local that's running the latest version of software.

2. Install the OpenSSH server extension via Azure portal or via PowerShell. We recommend that you install the extension via Azure portal.

   Note

   Starting with Windows Server 2025, OpenSSH is installed by default.

Install the OpenSSH server extension through Azure portal

To install the extension through Azure portal, go to Extensions and select the OpenSSH for Windows - Azure Arc option.

Install the OpenSSH server extension by using PowerShell

Follow these steps to install the OpenSSH Server Extension by using PowerShell:

1. Run PowerShell as an administrator.

2. Run the following cmdlets to ensure that the required Azure CLI Extensions are installed:

   az extension add --upgrade --name connectedmachine
   az extension add --upgrade --name ssh
   

3. Sign in to Azure:

   az login --use-device-code
   

4. Set appropriate parameters:

   $resourceGroup="<your resource group>"
   $serverName = "<your server name>"
   $location = "<your location>"
   $localUser = "<your username>" # Use a local admin account for testing        
   

5. Install the OpenSSH Arc Extension:

   az connectedmachine extension create --name WindowsOpenSSH 
   --type WindowsOpenSSH --publisher Microsoft.Azure.OpenSSH --type-handler-version 3.0.1.0 --machine-name $serverName --resource-group $resourceGroup
   

   Here's a sample output:

   PS C:\Users\labadmin> az connectedmachine extension create --name WindowsOpenSSH --location westeurope --type WindowsOpenSSH --publisher Microsoft.Azure.OpenSSH --type-handler-version 3.0.1.0 --machine-name $serverName --resource-group $resourceGroup
   {
      "id": "/subscriptions/<SubscriptionName>/resourceGroups/<ResourceGroupName>/providers/<ProviderName>/machines/<MachineName>/extensions/WindowsOpenSSH",
      "location": "westeurope",
      "name": "WindowsOpenSSH",
      "properties": {
         "autoUpgradeMinorVersion": false,
         "enableAutomaticUpgrade": true,
         "instanceView": {
         "name": "WindowsOpenSSH",
         "status": {
            "code": "0",
            "level": "Information",
            "message": "Extension Message: OpenSSH Successfully enabled"
         },
         "type": "WindowsOpenSSH",
         "typeHandlerVersion": "3.0.1.0"
         },
         "provisioningState": "Succeeded",
         "publisher": "Microsoft.Azure.OpenSSH",
         "type": "WindowsOpenSSH",
         "typeHandlerVersion": "3.0.1.0",
      },
      "resourceGroup": "<ResourceGroupName>",
      "type": "Microsoft.HybridCompute/machines/extensions"
   }
   PS C:\Users\labadmin>
   

6. You can see WindowsOpenSSH Extension in the Azure portal Extensions list view.

   

Use SSH to connect to an Azure Local VM

Use the following steps to connect to an Azure Local VM.

1. Run the following command to launch Arc SSH and sign in to the server:

   az ssh arc --resource-group $resourceGroup --name $serverName --local-user $localUser
   

   You're now connected to an Azure Local VM over SSH:

   

Use RDP over SSH to connect to an Azure Local VM

For Windows VMs only, you can use RDP over SSH to connect to an Azure Local VM. Linux VMs don't support RDP over SSH.

1. Run the following command with the RDP parameter:

   az ssh arc --resource-group $resourceGroup --name $serverName --local-user $localUser --rdp
   

2. Sign in to the local server for RDP over SSH.

   

3. Sign in to authenticate for RDP.

   

4. You can see the desktop for the remote desktop connection.

   

Connect to an Azure Local VM using VM Connect (preview)

About VM Connect

VM Connect allows you to connect to both Windows and Linux Azure Local VMs that don't have network connectivity or have boot failures. Use it for troubleshooting and recovery scenarios. VM Connect is in preview starting with Azure Local version 2601.

VM Connect requires line-of-sight from the client machine running Azure CLI to the Azure Local instance hosting the VM. This requirement means that the client machine must have a VPN connection to the Azure Local instance or be on the same network.

For more information about the VM Connect commands, see Azure Local VM Connect Azure CLI reference.

VM Connect prerequisites

Before you begin, make sure that you:

1. Have access to Azure Local that's running version 2601 or later.
2. Install the latest version of Azure CLI and the stack-hci-vm extension. For more information, see Install Azure CLI.
3. Assign the Azure Stack HCI Administrator role or higher to the Azure CLI user in the Azure subscription that contains the Azure Local VM and Azure Local instance.
4. Have line-of-sight from the client machine running Azure CLI to the Azure Local instance hosting the VM.
5. Have local administrator credentials for both the Azure Local instance hosting the VM and the VM itself. You need these credentials to authenticate when connecting to the VM by using VM Connect.

Use VM Connect to connect to an Azure Local VM

Follow these steps to connect to an Azure Local VM by using VM Connect.

1. Sign in to Azure CLI by using the following command:

   az login --use-device-code
   

2. Set appropriate parameters:

   $vmName="<your VM name>"
   $resourceGroup="<your resource group of the VM>"
   $clusterName="<your Azure Local instance name>"
   $rdpFilePath="<path to save RDP file>" # Optional, will be saved in current directory if not specified
   

   Note

   VM Connect currently only supports VMs that are located in the same resource group as the Azure Local instance. Ensure that the VM is in the same resource group as the Azure Local instance.

3. Run the following command to enable VM Connect and connect to the VM. Optionally, you can specify the path to save the generated RDP file by using the --path parameter.

   az stack-hci-vm vmconnect enable --name $vmName --resource-group $resourceGroup --cluster-name $clusterName
   

   Running this command can take up to 10 minutes to complete. This command performs the following actions:

   • Locates the Azure Local machine hosting the desired VM.
   • Opens port 2179 on the VM host machine to allow VM Connect traffic for eight hours by default.
   • Generates an RDP file with VM host machine IP and details configured to connect to the VM.

4. After the command completes, go to the location of the generated RDP file and open it to connect to the VM. If you didn't specify a path for the RDP file, it's saved in the current directory. Ensure that you have line-of-sight from the client machine to the Azure Local instance hosting the VM when opening the RDP file, otherwise the connection fails.

5. You see two authentication prompts with this RDP file:

   • The first prompt authenticates to the VM host machine. Use the credentials of a local administrator account on the Azure Local instance hosting the VM.
   • The second prompt authenticates to the VM itself. Use the credentials of a local administrator account on the VM.
     • If you need to press Ctrl + Alt + Delete to unlock, you can do so by pressing Ctrl + Alt + End on your keyboard, which sends the Ctrl + Alt + Delete command through the RDP session. You can also use the on-screen keyboard to send the Ctrl + Alt + Delete command.

6. You're now connected to the Azure Local VM by using VM Connect. You can use this connection to troubleshoot and recover the VM as needed.

7. When you're done using VM Connect, disable VM Connect to close the opened port on the VM host machine. Run the following command:

   
    az stack-hci-vm vmconnect disable --name $vmName --resource-group $resourceGroup --cluster-name $clusterName
   

Known limitations

• VM Connect requires VMs to be in the same resource group as the Azure Local instance.
  VM Connect doesn't work in the current release if the VM is in a different resource group than the Azure Local instance.

• VM Connect occasionally fails if the Azure Local host machine has multiple network interfaces.
  In some cases, VM Connect fails when executing the RDP file if the Azure Local host machine has multiple network interfaces. This problem happens because the RDP file contains an IP address that isn't reachable from the client machine. As a workaround, you can manually edit the RDP file to replace the IP address with one that's reachable from the client machine before opening it. To do this:

  1. Find the correct IP address of the Azure Local host machine that's reachable from the client machine by navigating in the Azure portal to the Azure Local instance > Infrastructure > Machines > select the host machine > Properties > Networking.
  2. Open the generated RDP file in a text editor.
  3. Locate the line that starts with full address:s: and replace the IP address with the correct one.
  4. Save the changes to the RDP file and then open it to connect to the VM.

VM Connect feedback

The product team appreciates your feedback on VM Connect. If you encounter any problems or have suggestions for improvement, provide your feedback through the Azure Local VM Connect Feedback Forum.

Next steps

• Once you connect, learn how to Manage Azure Local VMs.