SSH access to Azure Arc-enabled servers
SSH for Arc-enabled servers enables SSH based connections to Arc-enabled servers without requiring a public IP address or additional open ports. This functionality can be used interactively, automated, or with existing SSH based tooling, allowing existing management tools to have a greater impact on Azure Arc-enabled servers.
Key benefits
SSH access to Arc-enabled servers provides the following key benefits:
- No public IP address or open SSH ports required
- Access to Windows and Linux machines
- Ability to log in as a local user or an Azure user (Linux only)
- Support for other OpenSSH based tooling with config file support
Prerequisites
To enable this functionality, ensure the following:
- Ensure the Arc-enabled server has a hybrid agent version of "1.31.xxxx" or higher. Run:
azcmagent show
on your Arc-enabled Server. - Ensure the Arc-enabled server has the "sshd" service enabled. For Linux machines
openssh-server
can be installed via a package manager and needs to be enabled. SSHD needs to be enabled on Windows. - Ensure you have the Owner or Contributer role assigned.
Authenticating with Microsoft Entra credentials has additional requirements:
aadsshlogin
andaadsshlogin-selinux
(as appropriate) must be installed on the Arc-enabled server. These packages are installed with theAzure AD based SSH Login - Azure Arc
VM extension.Configure role assignments for the VM. Two Azure roles are used to authorize VM login:
- Virtual Machine Administrator Login: Users who have this role assigned can log in to an Azure virtual machine with administrator privileges.
- Virtual Machine User Login: Users who have this role assigned can log in to an Azure virtual machine with regular user privileges.
An Azure user who has the Owner or Contributor role assigned for a VM doesn't automatically have privileges to Microsoft Entra login to the VM over SSH. There's an intentional (and audited) separation between the set of people who control virtual machines and the set of people who can access virtual machines.
Note
The Virtual Machine Administrator Login and Virtual Machine User Login roles use
dataActions
and can be assigned at the management group, subscription, resource group, or resource scope. We recommend that you assign the roles at the management group, subscription, or resource level and not at the individual VM level. This practice avoids the risk of reaching the Azure role assignments limit per subscription.
Availability
SSH access to Arc-enabled servers is currently supported in all regions supported by Arc-Enabled Servers.
Getting started
Register the HybridConnectivity resource provider
Note
This is a one-time operation that needs to be performed on each subscription.
Check if the HybridConnectivity resource provider (RP) has been registered:
az provider show -n Microsoft.HybridConnectivity -o tsv --query registrationState
If the RP hasn't been registered, run the following:
az provider register -n Microsoft.HybridConnectivity
This operation can take 2-5 minutes to complete. Before moving on, check that the RP has been registered.
Create default connectivity endpoint
Note
The following step will not need to be run for most users as it should complete automatically at first connection. This step must be completed for each Arc-enabled server.
az rest --method put --uri https://management.chinacloudapi.cn/subscriptions/<subscription>/resourceGroups/<resourcegroup>/providers/Microsoft.HybridCompute/machines/<arc enabled server name>/providers/Microsoft.HybridConnectivity/endpoints/default?api-version=2023-03-15 --body '{"properties": {"type": "default"}}'
Note
If using Azure CLI from PowerShell, the following should be used.
az rest --method put --uri https://management.chinacloudapi.cn/subscriptions/<subscription>/resourceGroups/<resourcegroup>/providers/Microsoft.HybridCompute/machines/<arc enabled server name>/providers/Microsoft.HybridConnectivity/endpoints/default?api-version=2023-03-15 --body '{\"properties\":{\"type\":\"default\"}}'
Validate endpoint creation:
az rest --method get --uri https://management.chinacloudapi.cn/subscriptions/<subscription>/resourceGroups/<resourcegroup>/providers/Microsoft.HybridCompute/machines/<arc enabled server name>/providers/Microsoft.HybridConnectivity/endpoints/default?api-version=2023-03-15
Install local command line tool
This functionality is currently packaged in an Azure CLI extension and an Azure PowerShell module.
az extension add --name ssh
Note
The Azure CLI extension version must be greater than 2.0.0.
Enable functionality on your Arc-enabled server
In order to use the SSH connect feature, you must update the Service Configuration in the Connectivity Endpoint on the Arc-Enabled Server to allow SSH connection to a specific port. You may only allow connection to a single port. The CLI tools attempt to update the allowed port at runtime, but the port can be manually configured with the following:
Note
There may be a delay after updating the Service Configuration until you are able to connect.
az rest --method put --uri https://management.chinacloudapi.cn/subscriptions/<subscription>/resourceGroups/<resourcegroup>/providers/Microsoft.HybridCompute/machines/<arc enabled server name>/providers/Microsoft.HybridConnectivity/endpoints/default/serviceconfigurations/SSH?api-version=2023-03-15 --body "{\"properties\": {\"serviceName\": \"SSH\", \"port\": 22}}"
If you're using a nondefault port for your SSH connection, replace port 22 with your desired port in the previous command.
Optional: Install Azure AD login extension
The Azure AD based SSH Login - Azure Arc
VM extension can be added from the extensions menu of the Arc server. The Azure AD login extension can also be installed locally via a package manager via: apt-get install aadsshlogin
or the following command.
az connectedmachine extension create --machine-name <arc enabled server name> --resource-group <resourcegroup> --publisher Microsoft.Azure.ActiveDirectory --name AADSSHLogin --type AADSSHLoginForLinux --location <location>
Examples
To view examples, view the Az CLI documentation page for az ssh or the Azure PowerShell documentation page for Az.Ssh.
Next steps
- Learn about OpenSSH for Windows
- Learn about troubleshooting SSH access to Azure Arc-enabled servers.
- Learn about troubleshooting agent connection issues.