Arm Forge Remote Client Setup and Usage

The Arm Forge remote client allows debugging (via DDT) or profiling (via MAP) of remote jobs, while running the GUI on your local machine. This is faster than X11 (particularly for slow connections), and provides a native GUI.

In additional, the client can be used as a viewer for collected MAP profiles. See the Arm Forge page for more information.

Remote clients are available for Windows, Mac, and Linux, and can be used without an additional license.

The OLCF User Group Webinar recording below demonstrates configuration of the remote client and Reverse Connect setup.

Download

You can download the Arm Forge client from the Arm website.

Note: The version of the remote client should match the version of the installation on the system you wish to use as closely as possible. If the current version of the client is too recent, you may download an older version.

Installation

Windows: Execute the .exe installer downloaded from the website.

Mac: Open the DMG file with finder. From here you can drag the application to your “Applications” folder. (For older versions, you can launch the installer.)

Linux: Extract the tarball; run installer for a GUI installer, or textinstall.sh for a text-based install.

Configuration

  1. Once installed, launch Forge on your local machine.
  2. You can ignore any information about the lack of license file, as the license on the remote machine will be used.
  3. When you reach the welcome screen, you should see a “Remote Launch” combo box (with “Off” selected). Select the “Configure” option.
  4. Click the “Add” button
  5. Enter the details of your remote host:
    • (Optionally) enter a name for your remote connection (otherwise the host name will be used)
    • Enter your username and hostname (e.g. user@<host>.ccs.ornl.gov)
      • If the host you wish to connect to requires connecting through a gateway machine, you can enter user@hostname1 user@hostname2 (where hostname1 is the gateway and hostname2 is the final destination).
    • Enter the remote path to the Arm Forge installation (To find the path for a version of Forge, load the appropriate module file in a terminal and echo $DDT_HOME)
    • For the remaining fields, the default values will work for the vast majority of setups. See the Arm Forge userguide for more information on these.
  6. You may click the “Test Remote Launch” button to test your configuration. or click OK to connect to save your changes.
  7. Return to the welcome dialog, and select your new host from the “Remote Launch” combo box.(You will be asked for your PASSCODE).

Once connected, Forge will look and behave as usual, but will launch jobs, browse for files, and use/set the configuration on the remote system. In additional, the “Reverse Connect” feature, described below, is also available.

Reverse Connect

Once connected to a remote host, “Reverse Connect” allows launching of jobs to be launched with DDT and MAP from your usual launch environment, with a minor modification to your existing launch command.

For example, if you have a batch script containing:

jsrun -n 24 -g 1 ./a.out

You could edit this to:

module load forge
ddt --connect jsrun -n 24 -g 1 ./a.out

When your job is executed, the ddt --connect command will establish a connection with your already-running remote client, before launching the job. This provides a convenient way for the remote client to access a job within the batch system, and more importantly, avoids the need to explicitly tell DDT or MAP about any program parameters, environment variables, or module files required.

Reverse Connect Setup Instructions
  1. Launch the Forge remote client and connect to a remote host using the steps above. Once connected, this client will monitor for new connections.
  2. In a separate terminal, load the “forge” module, and run a ddt --connect command via the batch system (e.g. by editing and running a job script, or running with an interactive shell). 
    $ module load forge
$ ddt --connect jsrun -n 24 -g 1 ./miniWeather
  3. The remote client will notify you of a new connection.
  4. Once accepted, you can configure some final debugging options before launching the program.
  5. Click “Run”, and DDT will start your session.

If you have questions regarding the documentation above, please contact OLCF Support at help@olcf.ornl.gov.

Last updated August 1, 2019