You copied the Doc URL to your clipboard.

3 Connecting to a remote system

Often you will need to login to a remote system in order to run a job. For example you may use SSH to login from your desktop machine mydesktop to the login node mycluster-login and then start a job using the queue submission command qsub.


Figure 6: Connecting to a Remote System

The Arm Forge GUI can connect to remote systems using SSH, typically to a login node. It can also connect using Reverse Connect, typically to a batch compute node. See 3.3 Reverse Connect for more information on Reverse Connect. The remote client allows you to run the user interface on your local machine without the need for X forwarding. Native remote clients are available for Windows, Mac OS X and Linux.

No license file is required by a remote client. The license of the remote system will be used once connected.


The same versions of Arm Forge must be installed on the local and remote systems in order to use DDT or MAP remotely.


Figure 7: Remote Launch-Configure

To connect to a remote system click on the Remote Launch drop down list and select Configure… The Remote connections dialog will open where you can edit the necessary settings.

3.1 Remote connections dialog

The Remote Connections Dialog allows you to add, remove and edit connections to remote systems.


Figure 8: Remote Connections Dialog

When adding or editing a host, you are presented with the Remote launch settings for that host.

You may also remove a remote host from the list by clicking the Remove button, or duplicate an existing host using the Duplicate button.

You can also change the ordering of the hosts using the Move Up or Move Down buttons.

3.2 Remote launch settings


Figure 9: Remote Launch Options

Connection Name: An optional name for this connection. If no name is specified, the Host Name is used.

Host Name: The host name of the remote system you wish to connect to.

The syntax of the host name field is:


username is an optional user name to use on the remote system. If not specified your local user name is used instead.

hostname is the host name of the remote system.

port is the optional port number that the remote host's SSH daemon is listening on. If not specified the default of 22 is used.

To login via one or more intermediate hosts (for example, a gateway) enter the host names in order, separated by spaces, for example, cluster.lan


You must be able to login to the third and subsequent hosts without a password.

Additional SSH options may be specified in the remote-exec script covered in section A.4 Connecting to remote programs (remote-exec).

Remote Installation Directory: The full path to the Arm Forge installation on the remote system.

Remote Script: This optional script will be run before starting the remote daemon on the remote system. You may use this script to load the required modules for DDT and MAP, your MPI and compiler. See the following sections for more details. The script is usually not necessary when using Reverse Connect.

Always look for source files locally: Check this box to use the source files on the local system instead of the remote system.

KeepAlive Packets: Check this box to enable KeepAlive packets. These are dummy packets sent on regular intervals to keep some SSH connections from timing out. The interval can be configured from the spin box below.

Proxy through login node: Check this box to use the local RSA key to connect to both the login and the batch nodes. This is equivalent to not setting ALLINEA_NO_SSH_PROXYCOMMAND.

When this option is not set, DDT will first connect to the login node using your local RSA key and then use the key on the remote SSH configuration folder to connect to the batch node. This is equivalent to setting ALLINEA_NO_SSH_PROXYCOMMAND=1.

3.2.1 Remote script

The script may load modules using the module command or otherwise set environment variables. Arm Forge will source this script before running its remote daemon (your script does not need to start the remote daemon itself).

The script will be run using /bin/sh (usually a Bourne-compatible shell). If this is not your usual login shell, make allowances for the different syntax it might require.

You may install a site-wide script that will be sourced for all users at

You may also install a user-wide script that will be sourced for all of your connections at


$ALLINEA_CONFIG_DIR will default to $HOME/.allinea if not set.

Example Script


This script file should be created on the remote system and the full path to the file entered in the Remote Script field box.

   module load allinea-forge 
module load mympi
module load mycompiler

3.3 Reverse Connect

3.3.1 Overview

The Reverse Connect feature allows you to submit your job from a shell terminal as you already do and with a small tweak to your mpirun (or equivalent) allow that job to connect back to Arm Forge GUI.

Reverse Connect makes it easy to debug and profile jobs with the right environment. You can easily load the required modules and prepare all setup steps necessary before launching your job.

Please note that node-locked licenses such as workstation or Arm DDT Cluster licenses do not include the Reverse Connect feature.

3.3.2 Usage

  1. Start Arm Forge and let it connect to your remote system (typically a login node) with SSH.
  2. Modify your current mpirun (or equivalent) command line inside your interactive queue allocation or queue submission script to enable Reverse Connect. In most of the cases it is sufficient to prefix it with ddt/map --connect. Almost all Arm Forge arguments beside --offline and --profile are supported by Reverse Connect.


       $ mpirun -n 512 ./examples/wave_f

    To debug the job using Reverse Connect and 5.2 Express Launch run:

       $ ddt --connect mpirun -n 512 ./examples/wave_f

    To profile the job using Reverse Connect and 16.1 Express Launch run:

       $ map --connect mpirun -n 512 ./examples/wave_f

    If your MPI is not yet supported by Express Launch mode you can use Compatibility Mode.


       $ ddt --connect -n 512 ./examples/wave_f


       $ map --connect -n 512 ./examples/wave_f
  3. After a short period of time the Arm Forge GUI will show the Reverse Connect request including the host (typically a batch compute node) from where the request was made and a command line summary.


    Figure 10: Reverse Connect request
  4. You can accept the request with a click on Accept. Arm Forge will then connect to the specified host and execute what you specified with the command line. If you do not want to accept the request just click on Reject.

3.3.3 Connection details

If a Reverse Connect is initiated, for example with ddt --connect, Arm Forge starts a server listening on a port in the range between 4201 and 4240. If this port range is not suitable for some reason, such as ports are already taken by other services, you can override the port range with the environment variable ALLINEA_REMOTED_PORTS.

   $ export ALLINEA_REMOTED_PORTS=4400-4500 
$ ddt --connect

The server will now pick a free port between 4400 and 4500 (inclusive).

This connection is between the batch or submit node (where ddt -connect is run from) and the login node. This connection can also be to a compute node if for example, you are running ddt --connect mpirun on a single node.

3.4 Treeserver or general debugging ports

Connections are made in the following ways, depending on the use case:

Using a queue submission or using X-forwarding:

  • A connection is made between the login node and the batch or submit node using ports 4242-4262.
  • Connections are made between the batch or submit node and the compute nodes using ports 4242-4262.
  • Connections are made from compute nodes to other compute nodes using ports 4242-4262.

Using reverse connect:

  • See section 3.3.3 for details about login node to batch/submit node ports.
  • Connections are made between the batch or submit node and the compute nodes using ports 4242-4262.
  • Connections are made from compute nodes to other compute nodes using ports 4242-4262.

3.5 Using X forwarding or VNC

If you do not want to use the Remote Launch feature there are two other methods for running DDT or MAP on a remote system:

  1. X forwarding is effective when the network connection is low latency, such as when the network spans a single physical site.
  2. VNC (or similar Unix-supporting remote desktop software) is strongly recommended when the network connection is moderate or slow.
  • Mac OS X users accessing a Linux or other Unix machine while using a single-button mouse should be advised that pressing the Command key and the single mouse button will have the same effect as right clicking on a two button mouse. Right-clicking allows access to some important features in DDT and MAP.

    You can use X forwarding to access the Arm Forge instance running on a remote Linux/Unix system from a Mac OS X system:

    • Start the X11 server (available in the X11User.pkg).
    • Set the display variable correctly to allow X applications to display by opening a terminal in Mac OS X and typing:
         export DISPLAY=:0
    • Then ssh to the remote system from that terminal, with ssh options -X and -C (X forwarding and compression). For example:
         ssh -CX
    • Now start DDT or MAP on the remote system and the window will be displayed on your Mac.
  • Windows users can use any one of a number of commercial and open source X servers, but may find VNC a viable alternative ( which is available under free and commercial licensing options.
  • VNC allows users to access a desktop running on a remote server (for example, a cluster login node or front end) and is more suitable than X forwarding for medium to high latency links. By setting up an SSH 'tunnel' users are usually able to securely access this remote desktop from anywhere.

    To use VNC and Arm Forge:

    • Log in to the remote system and set up a tunnel for port 5901 and 5801. On Mac OS X or any Linux/Unix systems use the ssh command. If you are using Putty on Windows use the GUI to setup the tunnel.
         ssh -L 5901:localhost:5901 -L 5801:localhost:5801 \
    • At the remote prompt, start vncserver. If this is the first time you have used VNC it asks you to set an access password.

      The output from vncserver will tell you which ports VNC has started on-5800+n and 5900+n, where n is the number given as hostname:n in the output. If this number, n, is not 1, then another user is already using VNC on that system, and you should set a new tunnel to these ports by logging in to the same host again and changing the settings to the new ports (or use SSH escape codes to add a tunnel, see the SSH manual pages for details).

    • Now, on the local desktop or laptop, either use a browser and access the desktop within the browser by entering the URL http://localhost:5801/, or you may use a separate VNC client such as krdc or vncviewer.
         krdc localhost:1


         vncviewer localhost:1

      If n is not 1, as described above, use :2, :3 etc. as appropriate instead.

  • Note: A bug in the browser-based access method means the Tab key does not work correctly in VNC, but krdc or vncviewer users are not affected by this problem.
  • VNC frequently defaults to an old X window manager (twm) which requires you to manually place windows. This behavior can be changed by editing the ~/.vnc/xstartup file to use KDE or GNOME and restarting the VNC server.