SSH Target Naming and Port Forwarding¶

This wiki page describes how to provide names for ssh targets so that the target IP address can be associated with a name that 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 remember the specific IP address. Another option is to set up a name for the ssh target and then you don't have to remember the specific IP address when needed in different places.

This page shows how to set up such a target name. Many of the wiki pages that make connections to targets will assume that a name of target_62x has been set up. 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.

Setting up an ssh target name¶

Setting up a name for a ssh 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

This specifies the target name as target_62x. The actual IP address in this case is 10.0.100.102. And the login user is set to root.

GDB access to a gdbserver on the target using ssh port forwarding¶

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. You can use 10000 on both the local development host and the target. 10001 was used to make it more obvious which system was which. The advantage of using 10000 is that it is often the default port suggested by some of the tools so fewer changes 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 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.

Adding port forwarding to host config¶

Let's add the port forwarding to the previous setup ssh target.

Host target_62x
    HostName 10.0.100.102
    User root
    LocalForward 10000 localhost:10000

The LocalForward line says to forward any traffic to the local development host port address of 10000 to localhost:10000 on the target. Note that 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.

For 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

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.

ssh over USB rndis¶

The filesystems have a network config 50-usb-dhcpserver.network which creates a static point to point network link over the USB micro port. Creating an ssh target for this address can make it easier to use. See Example RNDIS

 Host target_usb
   HostName 10.1.47.2
   Port 22
   User root
   StrictHostKeyChecking no
   UserKnownHostsFile /dev/null

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.