SSH Target Naming and Port Forwarding¶

This wiki page describes how to providing names for targets so that the target IP address can be associated with a name in a configuration file and then the name can be used instead of the IP address.

When developing code for a target, there are many times when it is necessary to refer to the target IP address, the login user name (i.e. root) and possibly a port. These references can be made directly if you want to remember the specific IP address. Another option is to setup a name for the target and then you don't have to remember the specific IP address when it is needed in different places.

This page shows how to setup such a target name. Many of the wiki pages that make connections to targets will assume that a name of target_62x has been setup. This simplifies the instructions and makes them easier to use via copy/paste.

There are multiple scenarios where a target name can be used.

SSH commands¶

Without a target name, an ssh command is of the form:

ssh root@10.0.100.102

where 10.0.100.102 is the IP address of the target and root is the user name to login as. With a target name of target_62x setup, this connection would be made with:

ssh target_62x

The target name can also be used in other ssh related commands like rsync and scp.

GDB access to a gdbserver on the target¶

For a debugging session, a gdbserver process needs to be started on the target which will wait for a connection from the development host on a specific port. Any unused port on the target can be used, but we frequently assume that the port will be 10000. Getting a debug session going involves two steps:

• First, start the gdbserver on the target.
• Second, start gdb-multiarch on the host and have gdb-multiarch connect to the target at the port specified to gdbserver.

The first step can use the target name used in the ssh commands since the gdbserver can be started from the host with a command like

ssh target_62x gdbserver :10000 ./hello" 

The second step to make the connection to the target is a gdb command and it cannot use the name target_62x. It is possible though to specify the target for gdb to be "localhost" and to have a "port mapping" from a port specified on the development host is forwarded to the target port given to the gdbserver command.

For example, gdbserver could be listening to port 10000. The host could be told to connect to localhost (i.e. the development host) at port 10001 and the configuration entry that sets up the name of the target can be told to forward local traffic to port 10001 to the port 10000 on the target. By using this port forwarding, you don't need to use the IP address of the target in either of the steps. Actually, you can use 10000 on both the local development host and the target. 10001 was used to help keep the systems separate. The advantage of using 10000 is that it is often the default port suggested by some of the tools so there are fewer changes that have to be made.

If you only have one target, then you can use the defaults. If you have multiple targets, then you would need a different local host port for each target. Say the target names are something like target_62x_0, target_62x_1, and so on. You could still use port 10000 on each of the targets for the gdbserver arguments. Each target name would have different port forwarding where target_62x_0 would use a local host port of 10000 and forward this to the target at 10000. The target_62x_1 would use local host port of 10001 and forward this to the second target at 10000. And so on. This means you have to remember which port is being used for which target but the port numbers in use might be more regular than the actual IP addresses and can be easier to remember. And this is only if you are actively using multiple targets. It also turns out that you only have to remember which port is being used for the port forwarding while you are setting up the port forwarding file (~/.ssh/config) and while you are setting up the target launch configurations.

Setting up a target name¶

Setting up a name and the port forwarding for a target is done by making an entry in your ssh config file. This file is located at ~/.ssh/config. Here is an example entry:

Host target_62x
    HostName 10.0.100.102
    User root
    LocalForward 10000 localhost:10000
    StrictHostKeyChecking no
    ForwardAgent no
    ForwardX11 no

This specifies the target name as target_62x. The actual IP address in this case is 10.0.100.102. The user name root should be used. The LocalForward line says to forward the development host port address of 10000 to localhost:10000 on the target. This might be a little confusing since the localhost:10000 is provided to the target and interpreted in the context of the target. In that context, localhost means the target and not the development host.

If you had a second target, you might have a second entry like the following:

Host target_62x_1
    HostName 10.0.101.217
    User root
    LocalForward 10001 localhost:10000
    StrictHostKeyChecking no
    ForwardAgent no
    ForwardX11 no

In this case, the target name is target_62x_1 and the real IP address is 10.0.102.217. Again, the user name to use is root. In this case, the LocalForward line says to forward the development host port address of 10001 to localhost:10000 on the target. A different port on the development host but the same port number on the second target. So the gdbserver line still uses port 10000 on the target. The gdb connection on the development host would use port 10001 and act as if the connection is to the development host (i.e. localhost) instead of the target. The port forwarding will send the traffic from the development host port of 10001 to the actual target port of 10000.

Summary¶

Using this technique lets you use a target name (instead of the IP address) on ssh and ssh-related commands without having to always remember the target IP address. In addition, the gdb commands can be told to connect to a gdbserver running on the development host but through the magic of port-forwarding, the connection is really to the target. The benefit of this is that the target IP address is also not needed for these gdb commands.