Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
You can enable 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, expanding the impact of existing management tools on Azure Arc-enabled servers.
Benefits
SSH access to Arc-enabled servers provides the following 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
- User Permissions: Owner or Contributor role assigned for the target Arc-enabled server.
- Arc-enabled server:
- Hybrid Agent version: 1.31.xxxx or higher
- SSH service ("sshd") must be enabled.
For Linux, install openssh-server via a package manager. You can check whether sshd is running on Linux by running the following command:
ps -aux | grep sshd
For Windows, see Enable OpenSSH. You can check whether ssh is installed and running with the following commands:
Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH*'
# Check the sshd service is running
Get-Service sshd
Microsoft Entra authentication
If you use Microsoft Entra for authentication, you must install aadsshlogin and aadsshlogin-selinux (as appropriate) on the Arc-enabled server. These packages are installed with the AADSSHLoginForLinux VM extension.
You must also configure role assignments for the virtual machine (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 VM with administrator privileges.
- Virtual Machine User Login: Users who have this role assigned can log in to an Azure VM with regular user privileges.
An Azure user with the Owner or Contributor role assigned for a VM doesn't automatically have privileges for 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 cloud regions supported by Arc-enabled servers.
Enable SSH access to Arc-enabled servers
To enable SSH access to Arc-enabled servers, follow the steps in this section.
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 has been registered:
az provider show -n Microsoft.HybridConnectivity -o tsv --query registrationState
If the resource provider hasn't been registered, run the following command to register it:
az provider register -n Microsoft.HybridConnectivity
This operation can take 2-5 minutes to complete. Be sure the registration is complete before proceeding to the next step.
Create default connectivity endpoint
This step must be completed for each Arc-enabled server. However, you may not need to run these commands to do so, as it should complete automatically at first connection.
az rest --method put --uri https://management.azure.com/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.azure.com/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.azure.com/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
SSH functionality is provided in an Azure CLI extension and an Azure PowerShell module. Install the appropriate tool for your environment.
az extension add --name ssh
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 command. If you're using a nondefault port for your SSH connection, replace port 22 with your desired port.
az rest --method put --uri https://management.azure.com/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}}"
Note
There may be a delay after updating the Service Configuration before you're able to connect.
Optional: Install Microsoft Entra login extension
To use Microsoft Entra for authentication on your Linux machines, you must install aadsshlogin and aadsshlogin-selinux (as appropriate) on the Arc-enabled server. These packages are installed with the AADSSHLoginForLinux VM extension.
To add this extension in the Azure portal, navigate to your cluster, then in the service menu, under Settings, select Extensions. Select Add, then select Azure AD based SSH Login – Azure Arc and complete the installation. You can also install the extension locally via a package manager by running 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 and more details, view the Az CLI documentation page for az ssh or the Azure PowerShell documentation page for Az.Ssh.
Disable SSH to Arc-enabled servers
If you need to remove SSH access to your Arc-enabled servers, follow the steps below.
Remove the SSH port and functionality from the Arc-enabled server:
az rest --method delete --uri https://management.azure.com/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\"}}'Delete the default connectivity endpoint:
az rest --method delete --uri https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resourcegroup>/providers/Microsoft.HybridCompute/machines/<arc enabled server name>/providers/Microsoft.HybridConnectivity/endpoints/default?api-version=2023-03-15
Next steps
- Learn about OpenSSH for Windows
- Learn about troubleshooting SSH access to Azure Arc-enabled servers.
- Learn about troubleshooting agent connection issues.