Skip to content

Improve Teleport usage instructions ECFLOW-1965 #396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcosbento merged 2 commits into from
Jul 21, 2026
Merged

Improve Teleport usage instructions ECFLOW-1965 #396

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fad34eb
Add note regarding the limitation of proxychains
marcosbento Jul 21, 2026
95c8f68
Overall review of Teleport usage instructions
marcosbento Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 75 additions & 56 deletions docs/ug/ecflow_ui/using_ecflowui_via_the_ecmwf_teleport_gateway.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,91 +4,110 @@ Using ecFlowUI via the ECMWF Teleport gateway
/////////////////////////////////////////////


You can use the native ecFlowUI client on your End User device to access
remote servers via an SSH tunnel. The recommended way is using dynamic
The native ecFlowUI client can run on an End User device to access
remote servers via an SSH tunnel. The recommended approach uses dynamic
port forwarding.

.. warning::

This will require at least ecFlow version 5.7.0. Some advanced
features are only available in version **5.9.0**.
This requires at least ecFlow version 5.7.0, with some advanced features available only in version **5.9.0**.

.. note::

You can install ecFlowUI on MacOS platforms using
:ref:`brew`, or the full ecFlow from :ref:`conda-forge`.
ecFlowUI can be installed on MacOS platforms using
:ref:`brew`, or the full ecFlow from :ref:`conda-forge`.

Dynamic port forwarding
=======================

Authenticate via teleport
Authenticate via Teleport
-------------------------

First you need to authenticate via
The first step is to authenticate via
`Teleport <https://confluence.ecmwf.int/display/UDOC/Teleport+SSH+Access>`__
on your End User device.
on the End User device.

Set up dynamic port forwarding
------------------------------

The next step is to start dynamic port forwarding using the SOCKS
(Secure Socket) protocol. Let us suppose the target host you want to
access is hpc-login. In a terminal on your End User device type::
(Secure Socket) protocol. Assuming the target host is
``hpc-login``, type the following command in a terminal:

ssh -v -C -N -D 9050 myecuser@hpc-login
.. code-block:: bash

and keep it running. This will forward all network traffic from local
port 9050 to the target SOCKS host (hpc-login). This assumes
`Teleport <https://confluence.ecmwf.int/display/UDOC/Teleport+SSH+Access>`_
ssh -v -C -N -D 9050 <user>@hpc-login
# -v enables verbose output
# -C enables data compression
# -N disables opening a shell on the remote host
# -D 9050 enables dynamic port forwarding on local port 9050
# Adjust `<user>` to match the username on the remote host

This will open an SSH connection with dynamic port forwarding enabled,
from local port 9050 to the target host (hpc-login), that must be kept
running while ecFlowUI is used. Keeping the command in the foreground is
recommended, so that its status can be monitored.

This assumes `Teleport <https://confluence.ecmwf.int/display/UDOC/Teleport+SSH+Access>`_
has been configured correctly as described in the ECMWF User Documentation.
The port does not have to be 9050, but this is the default port
used by the proxychains tool (see below) so it is the most convenient
option for us.

The port does not have to be 9050, but this is the default port used by
the proxychains tool (see below), so it is the most convenient option.

Run ecFlowUI via proxychains
----------------------------

Applications which want to use dynamic port forwarding must speak SOCKS
protocol. ecFlowUI can be SOCKS-ified using a third party tool called
`proxychains <https://github.com/rofl0r/proxychains-ng>`__.
Applications that use dynamic port forwarding must speak the SOCKS
protocol. ecFlowUI can be made to use the SOCKS protocol with a third party
tool called `proxychains <https://github.com/rofl0r/proxychains-ng>`__.

.. important::

This is only possible on macOS platforms.

Unfortunately, Linux platforms are *not* supported, because proxychains
does not intercept the ``epoll_*`` system calls used by ecflow clients
to communicate with the ecflow servers.

Installing proxychains
~~~~~~~~~~~~~~~~~~~~~~

You need to install proxychains in your  End User device. On MacOS, you
can do it with "brew install proxychains-ng". Some Linux distributions
come with proxychains tool pre-installed.
The proxychains tool must be installed on the End User device.
On macOS, this can be done with ``brew install proxychains-ng``.

Start ecFLowUI
~~~~~~~~~~~~~~

Start ecFlowUI with this command if you are using version **>= 5.9.0**::
Start ecFlowUI with the following command (when using version **>= 5.9.0**):

.. code-block:: bash

ecflow_ui -pc4

ecflow_ui -pc4
Otherwise, use the ``-cmd`` flag:

otherwise you need to use the -cmd flag::
.. code-block:: bash

ecflow_ui -cmd proxychains4
ecflow_ui -cmd proxychains4

ecFlowUI is now behaving (in terms of client/server communication) as if
it were running on the SOCKS host (hpc-login in this case) and you
should be able to interact with all the ecFlow servers available from
that host.
When using the above options, ecFlowUI behaves (in terms of client/server
communication) as if it were running on the remote host, allowing
interaction with all the ecFlow servers available from that host.

Local file access via proxychains (only in version >= 5.9.0)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ecFlowUI accesses certain local files (e.g. output and server logs in
the **Output**, **Timeline** and **Server Load** panels) directly
(standard file I/O) without using the ecFlow client-server
communication. This poses a limitation if we run it via proxychains
because these files are only local on the remote hosts so ecFlowUI
cannot access them. To overcome this difficulty you need to use ecFlowUI
**version >= 5.9.0** and file fetching will automatically work for you.
The only settings that you might need to change is the SOCKS port
number, which by default is assumed to be 9050. Should you set up
dynamic port forwarding and use proxychains with a different port number
you need to set it in **Tools > Preferences > Network**:
communication. This poses a limitation when it runs via proxychains,
because these files are only local on the remote hosts, so ecFlowUI
cannot access them. To overcome this difficulty, ecFlowUI
**version >= 5.9.0** is required and file fetching then works
automatically. The only setting that might need to change is the SOCKS
port number, which by default is assumed to be 9050. When dynamic port
forwarding and proxychains are set up with a different port number,
set it in **Tools > Preferences > Network**:

.. image:: /_static/ecflow_ui/using_ecflowui_via_the_ecmwf_teleport_gateway/image1.png
:width: 3.33333in
Expand All @@ -97,39 +116,39 @@ you need to set it in **Tools > Preferences > Network**:
System server lists via proxychains (only in version >= 5.9.0)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When using ecflowUI outside ECMWF the :ref:`system server list
When using ecflowUI outside ECMWF, the :ref:`system server list
files <system_server_list_files_in_ecflowui>`
are not automatically accessible and you need to configure them
manually. However, when it is done they will be automatically transferred
are not automatically accessible and must be configured
manually. However, once this is done, they are automatically transferred
from the remote SOCKS host and loaded on each start-up. To define the
system server lists probably the best option is to set **Tools >**
system server lists, probably the best option is to set **Tools >**
**Preferences > Server settings > System server list.** The paths
specified here have to be local paths on the remote SOCKS host.  
specified here have to be local paths on the remote SOCKS host.

.. image:: /_static/ecflow_ui/using_ecflowui_via_the_ecmwf_teleport_gateway/image2.png
:width: 4.16667in
:height: 1.91879in

Alternatively, you can use the **ECFLOW_SYSTEM_SERVERS_LIST**
environment variable to specify the very same paths.
Alternatively, the **ECFLOW_SYSTEM_SERVERS_LIST**
environment variable can be used to specify the very same paths.

.. note::

The path to the system server list files for ATOS can be found
`here <https://confluence.ecmwf.int/display/ECFLOW/The+central+ecFlow+server+list+file+on+ATOS>`__.
The path to the system server list files for ATOS can be found
`here <https://confluence.ecmwf.int/display/ECFLOW/The+central+ecFlow+server+list+file+on+ATOS>`__.

Comments
========

- the dynamic port forwarding sometimes stops/hangs and as a result
ecFlowUI loses connection to the servers (it is indicated by the
orange strip on the left and the dotted background):
- In case the dynamic port forwarding stops/hangs, the ecFlowUI
loses connection to the servers, as indicated by the orange strip
on the left and the dotted background:

.. image:: /_static/ecflow_ui/using_ecflowui_via_the_ecmwf_teleport_gateway/image3.png
:width: 2.08333in
:height: 1.19454in

If it happens just go to the terminal where the dynamic port
forwarding was started up, terminate it if it still running and run
the command again. You do not need to exit ecflowUI, just refresh the
servers and the connection will be re-established.
If this happens, go to the terminal where the dynamic port
forwarding was started, terminate it if it is still running, and run
the command again. Exiting ecflowUI is not necessary; just refresh the
servers and the connection is re-established.
Loading