az ssh

  • Reference

Note

This reference is part of the ssh extension for the Azure CLI (version 2.45.0 or higher). The extension will automatically install the first time you run an az ssh command. Learn more about extensions.

SSH into resources (Azure VMs, Arc servers, etc) using AAD issued openssh certificates.

SSH into Arc-enabled servers without requiring a public IP address or SSH into Azure Virtual Machines. AAD issued openssh certificates for authentication currently only supported for Linux.

Commands

Name Description Type Status
az ssh arc

SSH into Azure Arc Servers.

 Extension GA
az ssh cert

Create an SSH RSA certificate signed by AAD.

 Extension GA
az ssh config

Create an SSH config for resources (Azure VMs, Arc Servers, etc) which can then be used by clients that support OpenSSH configs and certificates.

 Extension GA
az ssh vm

SSH into Azure VMs or Arc Servers.

 Extension GA

az ssh arc

SSH into Azure Arc Servers.

Users can login using AAD issued certificates or using local user credentials. We recommend login using AAD issued certificates. To SSH using local user credentials you must provide the local user name using the --local-user parameter.

az ssh arc [--certificate-file]
           [--local-user]
           [--name]
           [--port]
           [--private-key-file]
           [--public-key-file]
           [--rdp]
           [--resource-group]
           [--resource-type]
           [--ssh-client-folder]
           [--ssh-proxy-folder]
           [--yes]
           [<SSH_ARGS>]

Examples

Give a resource group name and machine name to SSH using AAD issued certificates

az ssh arc --resource-group myResourceGroup --name myMachine

Using a custom private key file

az ssh arc --resource-group myResourceGroup --name myMachine --private-key-file key --public-key-file key.pub

Using additional ssh arguments

az ssh arc --resource-group myResourceGroup --name myMachine -- -A -o ForwardX11=yes

Give a local user name to SSH with local user credentials using certificate based authentication.

az ssh arc --local-user username --resource-group myResourceGroup --name myMachine --certificate-file cert.pub --private-key-file key

Give a local user name to SSH with local user credentials using key based authentication.

az ssh arc --local-user username --resource-group myResourceGroup --name myMachine --private-key-file key

Give a local user name to SSH with local user credentials using password based authentication.

az ssh arc --local-user username --resource-group myResourceGroup --name myMachine

Give a SSH Client Folder to use the ssh executables in that folder, like ssh-keygen.exe and ssh.exe. If not provided, the extension attempts to use pre-installed OpenSSH client (on Windows, extension looks for pre-installed executables under C:\Windows\System32\OpenSSH).

az ssh arc --resource-group myResourceGroup --name myMachine --ssh-client-folder "C:\Program Files\OpenSSH"

Open RDP connection over SSH. Useful for connecting via RDP to Arc Servers with no public IP address. Currently only supported for Windows clients.

az ssh arc --resource-group myResourceGroup --name myVM --local-user username --rdp

Optional Parameters

--certificate-file -c

Path to certificate file.

--local-user

The username for a local user.

--name --vm-name -n

The name of the Arc Server.

--port

Port to connect to on the remote host.

--private-key-file -i

The RSA private key file path.

--public-key-file -p

The RSA public key file path.

--rdp --winrdp

Start RDP connection over SSH.

default value: False
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--resource-type

Resource type should be either Microsoft.HybridCompute/machines or Microsoft.ConnectedVMwareSphere/virtualMachines.

--ssh-client-folder

Folder path that contains ssh executables (ssh.exe, ssh-keygen.exe, etc). Default to ssh pre-installed if not provided.

--ssh-proxy-folder

Path to the folder where the ssh proxy should be saved. Default to .clientsshproxy folder in user's home directory if not provided.

--yes --yes-without-prompt -y

Update service configuration without prompting user.

default value: False
<SSH_ARGS>

Additional arguments passed to OpenSSH.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ssh cert

Create an SSH RSA certificate signed by AAD.

az ssh cert [--file]
            [--public-key-file]
            [--ssh-client-folder]

Examples

Create a short lived ssh certificate signed by AAD

az ssh cert --public-key-file ./id_rsa.pub --file ./id_rsa-aadcert.pub

Give a SSH Client Folder to use the ssh executables in that folder, like ssh-keygen.exe. If not provided, the extension attempts to use pre-installed OpenSSH client (on Windows, extension looks for pre-installed executables under C:\Windows\System32\OpenSSH).

az ssh cert --file ./id_rsa-aadcert.pub --ssh-client-folder "C:\Program Files\OpenSSH"

Optional Parameters

--file -f

The file path to write the SSH cert to, defaults to public key path with -aadcert.pub appened.

--public-key-file -p

The RSA public key file path. If not provided, generated key pair is stored in the same directory as --file.

--ssh-client-folder

Folder path that contains ssh executables (ssh.exe, ssh-keygen.exe, etc). Default to ssh pre-installed if not provided.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ssh config

Create an SSH config for resources (Azure VMs, Arc Servers, etc) which can then be used by clients that support OpenSSH configs and certificates.

Other software (git/rsync/etc) that support setting an SSH command can be set to use the config file by setting the command to 'ssh -F /path/to/config' e.g. rsync -e 'ssh -F /path/to/config'. Users can create ssh config files that use AAD issued certificates or local user credentials.

az ssh config --file
              [--certificate-file]
              [--ip]
              [--keys-dest-folder]
              [--local-user]
              [--name]
              [--overwrite]
              [--port]
              [--prefer-private-ip]
              [--private-key-file]
              [--public-key-file]
              [--resource-group]
              [--resource-type]
              [--ssh-client-folder]
              [--ssh-proxy-folder]
              [--yes]

Examples

Give the resource group and machine name for which to create a config using AAD issued certificates, save in a local file, and then ssh into that resource

az ssh config --resource-group myResourceGroup --name myVm --file ./sshconfig
ssh -F ./sshconfig myResourceGroup-myVM

Give the public IP (or hostname) of an Azure VM for which to create a config and then ssh into that VM

az ssh config --ip 1.2.3.4 --file ./sshconfig
ssh -F ./sshconfig 1.2.3.4

Give a local user to create a config using local user credentials, save in local file, and then ssh into that resource

az ssh config --resource-group myResourceGroup --name myMachine --local-user username --certificate-file cert --private-key-file key --file ./sshconfig
ssh -F ./sshconfig MyResourceGroup-myMachine-username

Give Keys Destination Folder to store the generated keys and certificates. If not provided, SSH keys are stored in new folder "az_ssh_config" next to the config file.

az ssh config --ip 1.2.3.4 --file ./sshconfig --keys-destination-folder /home/user/mykeys

Create a generic config for use with any host

#Bash
az ssh config --ip \* --file ./sshconfig
#PowerShell
az ssh config --ip * --file ./sshconfig

Examples with other software

#Bash
az ssh config --ip \* --file ./sshconfig
rsync -e 'ssh -F ./sshconfig' -avP directory/ myvm:~/directory
GIT_SSH_COMMAND="ssh -F ./sshconfig" git clone myvm:~/gitrepo

Give a SSH Client Folder to use the ssh executables in that folder, like ssh-keygen.exe. If not provided, the extension attempts to use pre-installed OpenSSH client (on Windows, extension looks for pre-installed executables under C:\Windows\System32\OpenSSH).

az ssh config --file ./myconfig --resource-group myResourceGroup --name myVM --ssh-client-folder "C:\Program Files\OpenSSH"

Give the Resource Type of the target. Useful when there is an Azure VM and an Arc Server with the same name in the same resource group. Resource type can be either "Microsoft.HybridCompute" for Arc Servers or "Microsoft.Compute" for Azure Virtual Machines.

az ssh config --resource-type [Microsoft.Compute/virtualMachines|Microsoft.HybridCompute/machines] --resource-group myResourceGroup --name myVM --file ./myconfig

Required Parameters

--file -f

The file path to write the SSH config to.

Optional Parameters

--certificate-file -c

Path to certificate file.

--ip

The public IP address (or hostname) of the VM.

--keys-dest-folder --keys-destination-folder

Folder where new generated keys will be stored.

--local-user

The username for a local user.

--name --vm-name -n

The name of the VM.

--overwrite

Overwrites the config file if this flag is set.

default value: False
--port

SSH Port.

--prefer-private-ip

Will use a private IP if available. By default only public IPs are used.

default value: False
--private-key-file -i

The RSA private key file path.

--public-key-file -p

The RSA public key file path.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--resource-type

Resource type should be either Microsoft.Compute/virtualMachines, Microsoft.HybridCompute/machines, or Microsoft.ConnectedVMwareSphere/virtualMachines.

--ssh-client-folder

Folder path that contains ssh executables (ssh.exe, ssh-keygen.exe, etc). Default to ssh pre-installed if not provided.

--ssh-proxy-folder

Path to the folder where the ssh proxy should be saved. Default to .clientsshproxy folder in user's home directory if not provided.

--yes --yes-without-prompt -y

Update service configuration without prompting user.

default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ssh vm

SSH into Azure VMs or Arc Servers.

Users can login using AAD issued certificates or using local user credentials. We recommend login using AAD issued certificates. To SSH using local user credentials, you must provide the local user name using the --local-user parameter.

az ssh vm [--certificate-file]
          [--hostname]
          [--local-user]
          [--name]
          [--port]
          [--prefer-private-ip]
          [--private-key-file]
          [--public-key-file]
          [--rdp]
          [--resource-group]
          [--resource-type]
          [--ssh-client-folder]
          [--ssh-proxy-folder]
          [--yes]
          [<SSH_ARGS>]

Examples

Give a resource group name and machine name to SSH using AAD issued certificates

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

Give the public IP (or hostname) of a VM to SSH using AAD issued certificates

az ssh vm --ip 1.2.3.4
az ssh vm --hostname example.com

Using a custom private key file

az ssh vm --ip 1.2.3.4 --private-key-file key --public-key-file key.pub

Using additional ssh arguments

az ssh vm --ip 1.2.3.4 -- -A -o ForwardX11=yes

Give the Resource Type of the target. Useful when there is an Azure VM and an Arc Server with the same name in the same resource group. Resource type can be either "Microsoft.HybridCompute" for Arc Servers or "Microsoft.Compute" for Azure Virtual Machines.

az ssh vm --resource-type [Microsoft.Compute/virtualMachines|Microsoft.HybridCompute/machines] --resource-group myResourceGroup --name myVM

Give a local user name to SSH with local user credentials using certificate based authentication.

az ssh vm --local-user username --ip 1.2.3.4 --certificate-file cert.pub --private-key-file key

Give a local user name to SSH with local user credentials using key based authentication.

az ssh vm --local-user username --resource-group myResourceGroup --name myVM --private-key-file key

Give a local user name to SSH with local user credentials using password based authentication.

az ssh vm --local-user username --resource-group myResourceGroup --name myArcServer

Give a SSH Client Folder to use the ssh executables in that folder, like ssh-keygen.exe and ssh.exe. If not provided, the extension attempts to use pre-installed OpenSSH client (on Windows, extension looks for pre-installed executables under C:\Windows\System32\OpenSSH).

az ssh vm --resource-group myResourceGroup --name myVM --ssh-client-folder "C:\Program Files\OpenSSH"

Open RDP connection over SSH. Useful for connecting via RDP to Arc Servers with no public IP address. Currently only supported for Windows clients.

az ssh vm --resource-group myResourceGroup --name myVM --local-user username --rdp

Optional Parameters

--certificate-file -c

Path to a certificate file used for authentication when using local user credentials.

--hostname --ip

The public (or reachable private) IP address (or hostname) of the VM.

--local-user

The username for a local user.

--name --vm-name -n

The name of the VM.

--port

SSH port.

--prefer-private-ip

Will prefer private IP. Requires connectivity to the private IP.

default value: False
--private-key-file -i

The RSA private key file path.

--public-key-file -p

The RSA public key file path.

--rdp --winrdp

Start RDP connection over SSH.

default value: False
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--resource-type

Resource type should be either Microsoft.Compute/virtualMachines, Microsoft.HybridCompute/machines, or Microsoft.ConnectedVMwareSphere/virtualMachines.

--ssh-client-folder

Folder path that contains ssh executables (ssh.exe, ssh-keygen.exe, etc). Default to ssh pre-installed if not provided.

--ssh-proxy-folder

Path to the folder where the ssh proxy should be saved. Default to .clientsshproxy folder in user's home directory if not provided.

--yes --yes-without-prompt -y

Update service configuration without prompting user.

default value: False
<SSH_ARGS>

Additional arguments passed to OpenSSH.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.