Debug remote applications via SSH

Last modified: 26 September 2024

In this tutorial we'll see how to use an SSH tunnel to set up a secure connection between the development machine and a remote host to debug your web application running there.

Set up SSH server on the remote host

Depending on the operating system that the remote host runs, configure SSH access to it.

Install and configure JetBrains SSH server for remote debugging — it will quickly and securely start SSH on a remote host and generate access credentials that you can use to access the host.

  1. Download the JetBrains SSH server executable for 32-bit Windows or for 64-bit Windows.

  2. Run the executable. Optionally, you can specify the desired port with the -port argument (for example, jetbrains_debugger_agent_20240726.40.0 -port=1234) otherwise the port will be randomly selected.

  3. The SSH will start, and you will see the access credentials (Login, Password, and Port) in the output.

  4. Make sure that the port is accessible:

    • either both the development machine and the remote host should be in the same network,

    • or the firewall/port-forwarding should be configured so that the port is accessible from outside the network

Alternatively, you can install and configure OpenSSH For Windows.

Create a web application

If you have a web application, you can go on with it. Otherwise, you can create a sample ASP .NET MVC application — choose File | New from the main menu and use the New Solution wizard:

Creating a new ASP.NET MVC application

Configure connections to the remote host

The connection to the remote host will be used by two subsystems — first, to deploy the application remotely via SFTP and second, to establish a remote debugging session via SSH.

  1. Press or choose File | Settings (Windows and Linux) or JetBrains Rider | Preferences (macOS) from the menu .

  2. Go to Build, Execution, Deployment | Deployment.

  3. Click Add Add , choose SFTP, and specify any name that will help you identify the remote host.

  4. Specify the address and the access credentials for the remote host, as well as the Root path — the path on the remote host where the application will be deployed. Make sure that this directory exists on the remote host. Web server URL that you will use for web browser access will be calculated automatically:

    SSH remote debugging. Deployment settings

  5. Without closing the Settings/Preferences dialog, go to Tools | SSH Configurations.

  6. Click Add Add and specify the SSH access credentials for the remote host. Often they are the same as the SFTP credentials:

    SSH remote debugging. Remote debug settings

  7. Click Save to save the settings and close the dialog

Deploy the application to the remote host

To deploy applications with JetBrains Rider, you need to create and use run configurations.

  1. Open the Run/Debug Configuration dialog in one of the following ways:

    • Select Run | Edit Configurations from the main menu.

    • With the Navigation bar visible (View | Appearance | Navigation Bar), choose Edit Configurations from the run/debug configuration selector.

    • Press and then press .

  2. In the Run/Debug Configuration dialog, click Add New Configuration Add New Configuration , choose the Publish to custom server configuration type, and specify a name that will help you identify this configuration in the future.

  3. Optionally, adjust the common settings of the configuration and configure before launch tasks.

  4. Make sure the project that corresponds to the application is selected correctly.

  5. In the Remote server field, select the SFTP access profile that you created in the previous steps on the Build, Execution, Deployment | Deployment page of JetBrains Rider settings .

  6. Specify other options that could differ depending on the target machine:

    SSH remote debugging. Deployment configuration

  7. Click OK to save the configuration and close the dialog.

Now you will be able to publish your application to the remote host as soon as your application is ready or each time it is modified. As we used a boilerplate project template for the web application, it is ready to be published:

SSH remote debugging. Deployment run

When the application is deployed, we can run it on the remote host.

  1. Select Tools | Start SSH session from the menu and then select the SFTP access profile.

    SSH remote debugging. Start SSH session

  2. A new session will appear in the Terminal window. Assuming that the application root folder is WebApplication, type the following commands:

    • cd /[application path]/WebApplication to go to the application root folder.

    • chmod +x ./WebApplication to add the executable bit if needed.

    • ASPNETCORE_URLS=http://0.0.0.0:5000 ./WebApplication to run the application

    SSH remote debugging. Terminal

Debug the application on the remote host

  1. In your application, set a breakpoint that should be hit when accessing one of its pages. If you created a new sample project in the beginning of the tutorial, you can set a breakpoint at HomeController.cs:28:

    SSH remote debugging. Breakpoint

  2. Select Run | Attach to Remote Process from the menu and choose the remote host and the application:

    SSH remote debugging. Attach

    If the debugger attaches successfully, the breakpoint icon will be marked with a green check mark: breakpoint_valid.png.

  3. Now when the application is running with the debugger connected to it, open the application URL in a browser http://[remote host name]:5000 and try to access the page where the breakpoint is set.

    SSH remote debugging. Opening the application in the browser

As soon as the application execution reaches the breakpoint, it will stop, and you will be able to debug it:

SSH remote debugging. Debugging the application

Optional deployment of remote debug tools

When the debugger connects to a remote host where the target application runs, it relies on the remote debug tools (dotnet executables, Rider agents, and their dependencies) that must be deployed on the remote host.

If there are no remote debug tools found, the debugger will silently deploy them when it connects to the application for the first time.

However, there are scenarios when the target environment is updated on each connection, for example if you debug an application inside a Docker container and the whole Docker image is rebuilt when you rebuild the application.

In such cases, each new debugging session has to start by deploying the remote debug tools, which may be slow.

To avoid this startup delay, you can manually or automatically deploy the remote debugging tools on the target host before connecting with the debugger.

  1. Download the remote debug tools for Windows using one of the following links:

  2. Unzip the tools to the RiderRemoteDebugger directory on the target machine or Docker image. For example %LOCALAPPDATA%\JetBrains\RiderRemoteDebugger\2022.1.1

See also

External Links