21 Remote Debugging

This chapter describes debugging programs running on remote systems. A remote debugger consists of a server running on the target system and a client (the debugger) running on the host system. Once connected to the target system, you use Ladebug to debug your program in the same way you debug your programs running locally.

For a detailed description of writing a remote debugger server, see Appendix B.

21.1 Remote Debugging Environment

The remote debugging environment consists the following components that interact through the remote debugger protocol:

The functionality available in a remote debugging session depends in part on which debugger server you are using. For Digital UNIX Version 4.0-6, this server is the server for the EB64 Alpha Evaluation Board (see Section 21.6) or Digital UNIX, or a server that you write for your own Alpha environment (see Appendix B).

The Ladebug server provided with Digital UNIX Version 4.0-6 (or later) is not compatible with versions of the debugger earlier than Version 4.0-6. (This incompatibility affects you only if you use remote debugging.) The incompatibility stems from a security enhancement introduced in Version 4.0-6: The server checks that a connect request is from a privileged port.

21.2 Reasons for Remote Debugging

There are several cases in which you would use a remote debugger:

  1. The target system does not have (or cannot run) a local debugger.

    The target system may be an embedded system that cannot support a debugger. You also may be debugging a part of the target's software that has to work before you can support a local debugger. A remote debugger server (that is, the software) requires less and different support from the target's operating system (if one exists) than the support required by a local debugger.

  2. The target system does not have the resources to run a local debugger.

    The target system may not be able to run a local debugger and simultaneously run the program being debugged. The remote debugger server uses less resources (particularly memory) than a resident Ladebug debugger.

  3. The source files for the program being debugged are not accessible from the target system.

    These sources are accessible from a host system from which you can remotely debug the target system.

  4. The target system's screen or keyboard cannot be used for debugging.

    A screen or keyboard interface may not exist because they are used by the program being debugged. Another possibility is that the target system's physical location is different from the user's.

  5. A local debugger may interfere with window-interface applications.

    On many interactive systems, it may be best to run a remote debugger. Alternatively, you may be able to run a local debugger that directs its input/output (I/O) to a screen on the remote system.

  6. You may want to debug a process running on another machine.

21.3 Client/Server Model for Remote Debugging

Remote debugging with Ladebug uses a client/server model. In this model, the host system, or client, initiates a connection to the target hardware and server software, which processes client requests.

Ladebug supports remote debugging in various client/server configurations. Figure 21-1 shows two configurations that use a single file system.

Figure 21-1 Client/Server Model with a Single or a Shared File System

In configuration A, the client and server are implemented on a single machine which connects to a file system.

In configuration B, a host system client is connected to a remote server through TCP/IP. Both host and target systems share the same file system.

A host system client can also be connected to a remote server in a configuration that employs separate file systems, as shown in Figure 21-2.

In this case, you must specify the -rfn option with the remote file name and have a locally accessible binary with debugger information.

Figure 21-2 Client/Server Model with Separate File Systems

In configurations A, B, and C in Figure 21-1 and Figure 21-2, the user program resides on the target system. The host machine interacts with the target system in the following way:

  1. After starting the server deamon, a remote session is established when the host system connects to the target system.

  2. The Ladebug client on the host system interacts with the server on the target system to debug the user program. A new server is started for each user program being debugged.

  3. The debugger terminates the remote server when you end the debugging session.

Table 21-1 describes the client/server concepts for remote debugging. Section 21.4 describes the tasks for remote debugging.

Table 21-1 Client/Server Concepts for Remote Debugging

Client  Server 
Is Ladebug debugger.  Is remote debugger server. 
Runs on host system.  Runs on target hardware (for example, EB64 or Digital UNIX Alpha. ) 
Makes requests to server.  Controls the process being debugged. 
Is responsible for all access to source files and symbol table.   Is not responsible. 
Uses debug protocol; sends protocol commands to the server.  Uses debug protocol; receives protocol commands and sends responses. 
Contains information about the process being debugged.  Contains information about the processes' environment. 
Does not control processes.  Server controls a single process; server deamon controls multiple processes (messages to the server containing a server ID). 

21.4 Tasks for Remote Debugging

This section describes general tasks to debug programs running on remote systems. The tasks include:

  1. Starting the server daemon

  2. Starting the debugger, user program, and connecting to the server

  3. Debugging the user program

  4. Exiting the debugger and disconnecting from the server

21.4.1 Starting the Server Daemon

The server daemon must be running on the target system before you can remotely debug programs on that target. You can start the server daemon either from a system startup file or interactively from the command line.

Under certain conditions, running the server daemon negatively affects the security of your system. If you are running an old server, there may be a security problem (see the documentation for that server). An individual user ID can be protected by prohibiting remote access from a particular host (or from all hosts) in the .rhosts and the hosts.equiv files. On Digital UNIX machines, .rhosts must have rw privileges only for the owner, with no privileges for the group and others.

For example, to start the server daemon interactively and output system messages to a log file, log in as superuser then start the server daemon as follows:

$ /usr/bin/ladebug-server > ladebug-server.log &
Ladebug remote debug server deamon starting
/usr/bin/ladebug-server : server is servdb.ptl.dss.com (

21.4.2 Starting Ladebug

When you start Ladebug you also start the user program and connect to the server.

Use the -rn command-line option, which specifies the IP name or address of the machine on which the server deamon is running and on which you want your user program to run. Specifying this command-line option is the only difference between starting Ladebug to debug a remote application and starting Ladebug to debug a local one.

If you start Ladebug without specifying the process ID (- pid ) , it starts a debuggee process in the remote node running the indicated image file. If you do not specify the user name on the remote node (-ru ) , it uses the local user name.

For example, if you are connecting to the target system servdb to debug the user program ~/work/test/hello and the file system is shared:

$  ladebug -rn servdb ~/work/test/hello
Welcome to the Ladebug Debugger Version 3.0
object file name: /usr/users/dss/work/test/hello
machine name: servdb
Reading symbolic information ...done

If you start Ladebug and specify a process ID, Ladebug connects to the process in the remote node running the process. If the specified process ID does not exist, the server returns an error and refuses connection.

If you are connecting to a server that does not share the same file system, specify the -rfn option with the -rn option. See Section 21.5 for detailed descriptions of all the remote debugging command-line options.

21.4.3 Debugging the User Program

You debug a user program running on the target system the same way as you would a local program. Note the following differences:

The following example shows the result of running user program ~/work/test/hello on remote node servdb:

(ladebug)  stop in main; run
[#1: stop in main ]
[1] stopped at [main:6 0x120001fa0]
      6   (void) printf("Hello, world !\n");
(ladebug)  cont
Thread has finished executing

Note that the output of the program is not displayed after the cont command. With remote debugging, the program output is displayed on the target system. You can also redirect the output of the application to a log file.

The same program run locally would look like this:

$  ladebug ~/work/test/hello
Welcome to the Ladebug Debugger Version 3.0
object file name: /usr/users/dss/work/test/hello
Reading symbolic information ...done
(ladebug) stop in main; run
[#1: stop in main ]
s[1] stopped at [main:6 0x120001fa0]
      6   (void) printf("Hello, world !\n");
(ladebug) cont
Hello, world !
Thread has finished executing

21.4.4 Exiting the Debugger and Disconnecting from the Server

The Ladebug quit command ends the remote debugger session and automatically disconnects from the server.

The quit command does not terminate the process running on the target system. Use the kill command to terminate a running process and end the remote debugger session.

21.5 Command-Line Options for Remote Debugging

Table 21-2 lists the Ladebug command-line options that support remote debugging.

Table 21-2 Command Line Options for Remote Debugging

Option/Qualifier  Meaning /Conditions 
-rn [1] node_or_address [,udp_port [2]]  Specifies the internet node name or IP address of the machine on which the remote debugger server is running (that is, the node running the program to be debugged); optionally specifies the UDP port on which to connect the server. Either the node name or IP address is required; there is no default. 
-pid process_id   Specifies the process ID of the process to be debugged. When you specify this option, Ladebug debugs a running process rather than loading a new process. 
-rfn [1] arbitrary_string   Specifies the file name (or other identifier) of the image to be loaded on a remote system. This option defaults to the local image file name and it is passed to the remote system uninterpreted. Use only with - rn ; do not combine with -pid
-rinsist   Connects to a running remote process using the connect insist protocol message instead of the connect protocol message. This option functions as a request to the server to connect to the client, even if another client is already connected. (The previously connected client is disconnected.) Use only with with -rn and - pid
-ru username   Specifies the user name to be used on the remote system. The default is the local user name.  

[1] Depending on your shell, it may be necessary to enclose this option in quotes to prevent the shell from interpreting the punctuation characters in the parameter.

[2] Current remote debugger servers use UDP port 410 (the default); older releases might use UDP port 21511.

The following examples show how to use the remote debugger command- line options.

Example 1

$  ladebug -rn -ru brown program1

Connects to the server on the node with IP address and asks the server to load a process called program1. The local copy of the object file is also called program1. The user name on the remote node is brown.

Example 2

$  ladebug -rn EB64 -rfn '**process name A**' program3

Connects to the server on the node with IP name EB64 and asks it to load the process called '**process name A**'. The local object file is called program3.

21.6 Example Remote Debugger Session Using the Evaluation Board Server

This section describes the steps you need to perform to debug remote processes running on the Evaluation Board Server [1]. The procedures described in Section 21.6.1 through Section 21.6.3 describe the simplest procedure for using Ladebug with the Evaluation Board Server. Since Ladebug can be started at any monitor breakpoint (not only when the program is at its initial entry point), many variations are possible.

[1] The server includes the EB64, EB64+, and EB66 evaluation boards.

21.6.1 Building an Executable File

To build the executable file for remote debugging:

  1. Compile your source files using the -g option to save symbolic information.

  2. Link the source files with the -N and -Tx options, where x is the load address for the executable file.

  3. Use the cstrip utility to strip the coff header from the executable file. Keep the unstripped executable file.

21.6.2 Loading the Executable File and Starting the Server

To load the executable file and start the Ladebug server:

  1. Set up the host Digital UNIX Alpha machine as the bootp server for the Evaluation Board Server (for example, the EB64).

  2. Start the server.

  3. Use the bootadr command on the monitor to set the boot address to the load address that was used when linking the executable file.

  4. Use the netload command to load the stripped executable file across the ethernet.

  5. Set a breakpoint at the entry point to the program with the stop command.

  6. Start the program with the go command.

  7. When the program reaches the breakpoint, enter the LADBX command to start the Ladebug server.

21.6.3 Starting Ladebug on the Host System

After starting the server, to start the Ladebug debugger on the host system:

  1. Enter the following command:
    ladebug -rn <EB64> -pid 0 <exe> 

    In this command, <exe> is the file name of the unstripped executable file and <EB64> is the internet name or address of the Evaluation Board Server.

  2. After you finish debugging or want to return to the monitor's local command interface, enter the quit command. The quit command closes Ladebug and returns the monitor to its command prompt. The state of the program you are debugging is not affected by this action.

21.6.4 Special Conditions

The following conditions may arise when remote debugging using the Evaluation Board Server: