Remote debugging

Remote debugging is used in situations where a program must be run on a different machine to where it is developed; in these cases it’s typically convenient to run the debugger on the development machine and have it control a program running on the test machine.

Note

See the documentation for the replay service for an alternative approach to debugging recordings that require specific hardware capabilities.

Installing udbserver on the target

udbserver is the component of UDB which tightly controls the program and enables it to be recorded and rewound. For those familiar with remote debugging via GDB, it is analogous to gdbserver. As such it must be installed on the target machine.

Installing can be as simple as copying the Undo release directory to the target machine, or making it available via a file-sharing mechanism such as NFS. Where storage space on the target is limited, the only required files are the version of udbserver appropriate to your target (see below) and the key file.

It is important that the date and time on the target device are set (approximately) correctly, otherwise udbserver will refuse to run.

The correct udbserver executable depends on the architecture for which your program was compiled:

OS	Architecture	udbserver executable
Linux	ARM (ARMv8-A / AArch64)	tools/udbserver_arm64
Linux	Intel i386	tools/udbserver_x32
Linux	AMD/Intel x86-64	tools/udbserver_x64

Not all architectures are available in every Undo release archive. If you require support for an architecture that is not included in your release archive, please contact Undo Support.

Note

The version of udbserver installed on the target must match the version of UDB used on the development machine.

Choosing the appropriate udbserver executable

Your Undo Suite download contains a number of udbserver executables. The correct executable depends on the architecture for which the program was compiled, as follows:

OS	Architecture	udbserver executable
Linux	Intel i386	udbserver_x32
Linux	AMD/Intel x86-64	udbserver_x64
Linux	ARMv8 AArch64 (enabled licenses only)	udbserver_arm64

Basic usage

Start udbserver, using the --connect-port 0 option to request it to choose a TCP/IP port to listen on, and specifying the program and arguments to be debugged:

$ tools/udbserver_x64 --connect-port 0 examples/cache &
udbserver 8.2.0. Copyright 2025 Undo.
Using inferred keyfile: key
Control-C is ignored. To suspend, type control-Z. To quit, type control-\.
Listening on port 45267...

Connect to the server in UDB using the target remote command, for example:

$ udb examples/cache
Reading symbols from examples/cache...
not running> target remote localhost:45267
Remote debugging using localhost:45267
Connection established
Connection established
not running> start
Temporary breakpoint 1 at 0x131f: file cache.c, line 65.
Starting program: examples/cache

Temporary breakpoint 1, main () at cache.c:65
65          cache_init();

If the program is already running, use the --pid option, for example:

$ examples/deadlock &
Running as pid 94
$ tools/udbserver_x64 --pid 94 --connect-port 0 &
udbserver 8.2.0. Copyright 2025 Undo.
Using inferred keyfile: key
Control-C is ignored. To suspend, type control-Z. To quit, type control-\.
Listening on port 34435...

Command-line options

--autostart

Automatically start the program as soon as UDB connects. For example:

$ tools/udbserver_x64 --autostart --connect-port 0 examples/cache &
udbserver 8.2.0. Copyright 2025 Undo.
Using inferred keyfile: key
Control-C is ignored. To suspend, type control-Z. To quit, type control-\.
Listening on port 34751...
$ udb examples/cache
Reading symbols from examples/cache...
not running> target remote localhost:34751
Remote debugging using localhost:34751
0x00007ffff7fe4540 in _start () from /lib64/ld-linux-x86-64.so.2
Connection established
Connection established

Note

Autostart is required for remote debugging to work correctly from some IDEs, including CLion and Eclipse, and is implicit in the suggested command-line when launching for IDE remote debugging.

--connect-port PORT

Listen for new connections on PORT. Specify port 0 to choose an available port.

--defer-recording

Start the program in deferred-recording mode.

--help, -h

Display help and exit.

--keepalive 0

Don’t use SO_KEEPALIVE.

--keepalive 1 KEEPIDLE KEEPINTVL KEEPCNT

Set up sockets to use SO_KEEPALIVE with the specified values for TCP_KEEPIDLE, TCP_KEEPINTVL and TCP_KEEPCNT. Specify zero for any value to use the system default for that value.

--keyfile KEYFILE

Use the license key from KEYFILE. By default, use the file named key in the same directory as udbserver.

--load-file RECORDING

Load the Undo recording named by RECORDING.

--pid PID

Attach to the process with id PID.

--tmpdir-root DIRECTORY

The directory used by udbserver for its temporary files. See Temporary directory root.

--version, -v

Print version information and exit.

Cross-architecture debugging

A common case in remote debugging is to have a developer machine running udb, connected over a network to a test machine running udbserver, and where the developer and test machines have different CPU architectures. In this case, use the set architecture command to tell udb the architecture of the program being debugged.

set architecture arch

Set the target architecture to arch. Supported architectures are:

OS	Architecture	Architecture
Linux	Intel i386	i386
Linux	AMD/Intel x86-64	i386:x86-64

show architecture

Show the target architecture.

IDE remote debugging

IDEs, including Eclipse and CLion, make certain assumptions about the behavior of the remote debugging server. These assumptions are based on the behavior of gdbserver. In order to match those expectations, the suggested command-line when launching the server for remote debugging within an IDE is:

udbserver_<arch> <port-number> <full-path-to-program>