Share via

Things You Should Know: Web Apps and SSH

  • Article

If you're hosting your Web App in App Service on a Linux machine, you will likely want to SSH into your app's container at some point. In this post, I'll walk you through how you can do that. By the way, this procedure also enables remote debugging of your Node.js apps and SFTP access to your Web App!

The steps here apply to both App Service on Linux and Web App for Containers. However, if you're using Web App for Containers, you'll need to follow some additional steps to ensure that your custom image is configured correctly. You can find those steps in our documentation.

Disclaimer:  I'm giving you a detailed step-by-step here. Because of that, this process looks complicated. I promise that's just an illusion. Once you go through it, you'll realize how easy it is! You will only need to go through Steps 1-4 one time, assuming you don't close the console window where you're running the Azure CLI.

Important Stuff:  

  • Follow all of these steps on the local machine you will be using to SSH into your Web App.
  • If any of the commands don't work, please ensure that you have the latest Azure CLI installed as per Step 1.
  • If you are updating an existing install of the Azure CLI, it's recommended that you uninstall the existing version before installing the new version.
  • If you're using a custom Docker image with Web App for Containers, you need to ensure that it's properly configured. See this for more information on that.

Step 1: Ensure you have the latest Azure CLI installed.

You can install the Azure CLI from /en-us/cli/azure/install-azure-cli?view=azure-cli-latest. Note that you can install this on Windows, macOS, and just about any flavor of Linux.

Step 2: Run the Azure CLI and log into your Azure account.

Once you've installed the CLI, open a command prompt, terminal, or PowerShell and run the following command to log into your Azure account.

az login

This will walk you through the process of authenticating to Azure using a website and connecting the CLI to your Azure account.

Step 3: If you have multiple Azure subscriptions, set the active subscription.

If you don't have multiple subscriptions under your account, go ahead and skip to Step 4.

If you have multiple subscriptions, you'll want to make sure that you set your Web App's subscription as the active subscription. To do that, use the following command.

az account set -s subscription_name_or_ID

By the way, it's convenient to set the display name for your subscription before you run this command. You can then use the display name to set the active subscription.

Step 4: Install or update the webapp CLI extension.

The webapp CLI extension allows you to manage Web Apps using the Azure CLI. You will want to ensure you have the latest version of the webapp extension installed.

If you have not installed the webapp extension, install it using the following command. (If you run this and the extension is already installed, the command will notify you it's already installed.)

az extension add -n webapp

If you already have the extension installed, use the following command to update it to the latest version.

az extension update -n webapp

All of the steps above this line only need to be followed once. After you've done them, as long as you leave the console open where you're running the Azure CLI, the following steps will allow you to easily SSH into any of your Web Apps.

Step 5: Open a TCP Tunnel from your local machine.

We use a TCP tunnel to connect to your Web App over an authenticated web socket. To create that TCP tunnel, run the following command.

az webapp remote-connection create -g ResourceGroup -n WebAppName -p LocalPortNumber

The resource group must be the resource group your Web App is in. The local port number can be any ephemeral port (usually between 1,024 and 65,535) that is unused on your local machine. (If you don't specify a port, we'll auto-select a port for you.) So as an example, if I want to create a TCP tunnel for a Web App named MyWebApp running in a resource group named MyRG and I want the tunnel on port 9000, I would run the following command.

az webapp remote-connection create -g MyRG -n MyWebApp -p 9000

When you run this, you will see output like the following.

Port 9000 is open SSH is available { username: root, password: Docker! } Start your favorite client and connect to port 9000

Note:  If you see an error when you run this command indicating that it can't find the resource group you specified, it could be that the resource group exists in a different subscription. See Step 3 for information on setting the active subscription.

Note for Deployment Slots:  If you're opening a remote connection to a deployment slot, the command is slightly different. If I have a deployment slot called "staging" for the MyWebApp app, I would open a remote connection to that deployment slot using this command.

az webapp remote-connection create -g MyRG -n MyWebApp -p 9000 --slot staging

Step 6: SSH into your Web App.

Now that the TCP tunnel is open, you are ready to SSH into your Web App. Open your favorite SSH client and connect to either localhost or 127.0.0.1 on the port you opened. (Remember, we're using a TCP tunnel to connect to Azure App Service and that tunnel is open on a local port on your machine. Therefore, you'll connect to the port at localhost.)

Note that the Azure CLI window needs to remain open while you are using SSH. It's also helpful to note that the Azure CLI window will display diagnostic information if things go wrong.

Troubleshooting Note: If you see information in the CLI window that says that the connection was terminated or other errors and you're using Web App for Containers, make sure that you followed the steps for custom images carefully!

In the screenshot below, you can see that I have successfully connected via SSH to my Web App from my Mac.

SSH from macOS

One note for macOS High Sierra users. You might see an error that says, "Unable to negotiate with 127.0.0.1 port ####: no matching cipher found. Their offer: aes128-cbc,3des-cbc,aes256-cbc." This error means that SSH on your Mac isn't configured to use one of the ciphers that we offer in App Service. To fix this, you can follow the steps here to add one of the ciphers that we offer.