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.
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.
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 LiveRecorder 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 |
|
Linux |
AMD/Intel x86-64 |
|
Note
In previous versions of UDB, the remote debugging server was called
undodb-server
(and the executables were called undodb-server_<arch>
,
where arch
is the program’s architecture).
For compatibility, the old executable names are still available but are
now symbolic links to the udbserver_<arch>
executables.
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:
$ udbserver_x64 --connect-port 0 examples/cache &
udbserver 6.11.0. Copyright 2023 Undo Ltd.
Using inferred keyfile: key
Control-C is ignored. To suspend, type control-Z. To quit, type control-\.
Listening on port 40193...
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:40193
Remote debugging using localhost:40193
Connection established
Connection established
not running> start
Temporary breakpoint 1 at 0x1309: 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 629695
$ udbserver_x64 --pid 629695 --connect-port 0 &
udbserver 6.11.0. Copyright 2023 Undo Ltd.
Using inferred keyfile: key
Control-C is ignored. To suspend, type control-Z. To quit, type control-\.
Listening on port 44149...
Command-line options¶
- --autostart¶
Automatically start the program as soon as UDB connects. For example:
$ udbserver_x64 --autostart --connect-port 0 examples/cache & udbserver 6.11.0. Copyright 2023 Undo Ltd. Using inferred keyfile: key Control-C is ignored. To suspend, type control-Z. To quit, type control-\. Listening on port 33281... $ udb examples/cache Reading symbols from examples/cache... not running> target remote localhost:33281 Remote debugging using localhost:33281 Have reached start of recorded history. 0x00007fba457b3100 in ?? () 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.
- --keyfile KEYFILE¶
Use the license key from
KEYFILE
. By default, use the file namedkey
in the same directory as udbserver.
- --load-file RECORDING¶
Load the LiveRecorder 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 then 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
Linux
ARMv8 AArch64 (enabled licenses only)
aarch64
show architecture¶
Show the target architecture.
IDE remote debugging¶
IDEs, including Eclipse and CLion, make certain assumptions about the behaviour of the remote debugging server. These assumptions are based on vanilla gdb’s behaviour. 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>