Skip to main content

Remote Debugging

Remote debugging involves debugging a program running on a different machine than the debugger. This technique is extremely beneficial when debugging applications executing on servers, embedded systems, or mobile devices. Most of the time this involves opening a port to the debug server running on a different machine. This is a security risk and should be done with caution and only in a trusted environment.

Webrelay can be used to create a secure connection to the remote machine, allowing you to debug the application as if it were running locally. This example will show you how to do this with Node.js. We will open no ports on the remote machine,Instead we will create a secure connection to the remote machine and debug the application as if it were running locally.

General Overview of Remote Debugging​

The typical remote debugging process involves:

  1. The debuggable code runs on a remote machine, alongside a debug server. This debug server is a small program that awaits a connection from the debugger.

  2. The developer uses a local machine equipped with a debugger to connect to this debug server over a network.

  3. The debugger and debug server communicate, allowing the developer to control the program's execution on the remote machine.

Remote Debugging example​

Node.js​

Node.js has built-in debugging support using the Chrome DevTools protocol.

  1. Run Node.js with the --inspect or --inspect-brk flag on the remote machine.
  2. Use Webrelay to create a secure connection from the remote machine to your local machine
  3. Debug the application as if it were running locally.

On the Remote Machine​

Download the latest version of Webrelay from here, and login using webrelay login <your-email-id>. Note that the same account should be used on the local machine as well.

Create an express server and start it in debug mode​

const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
    let name = req.query.name || 'Guest';
    res.send(`Hello, ${name}!`);
});

app.listen(port, () => {
    console.log(`Example app listening at http://localhost:${port}`);
});

Paste this into a file called app.js

Make sure you have express installed

npm install express

Run the app in debug mode

node --inspect=0.0.0.0:9229 app.js

Start the services​

Let's start two services in Webrelay. One for the debug server and one for the express server.

webrelay service start -n nodeapp -u 127.0.0.1 -p 3000 -t http

and

webrelay service start -n nodeappdebug -u 127.0.0.1 -p 9229 -t tcp

On Your Local Machine​

Connect your clients​

Now let's connect our clients. We'll connect the express server and the debug server to our local machine.

List the services

webrelay service list

You should see your services listed

service list

Connect a http port to the express server

webrelay client -n nodeapp -p 9001

Connect a TCP port to the debug server

webrelay client -n nodeappdebug -p 9000

Your express should now be available at http://localhost:9001 and your debug server will be available at localhost:9000

You can verify this in Chrome by navigating to chrome://inspect.

Click on "Configure" button and add your remote server's IP address and port - localhost:9000.

You should now see your remote Node.js application under "Remote Target". Click on "inspect" to open a DevTools instance.

In the new DevTools window, you can set breakpoints, step through your code, inspect variables, and see console output.