This document is a guide to accessing the Atos Quantum Learning Machine. We are going to use a lot of SSH. For GNU/Linux and Mac users, the command-line client of OpenSSH is pre-installed and you only need to open a Terminal and follow our instructions. Windows users will have to install an SSH client. Perhaps the most popular one is PuTTY , another alternative is MobaXterm .

If you are an institutional user with VPN access (TUM, LMU, Hochschule München, WMI, ...) and without LinuxCluster access you need to be in the VPN network to be able to reach your login node. Documentation of VPN access can be found here.

We strongly recommend using SSH keys instead of pure password login. Documentation about SSH keys in general can be found here

Step 1 - ssh via Login Nodes

Access to the QLM works via a login node. Your login node might depend on your institution. If you already have LinuxCluster access, you can use one of the LinuxCluster login nodes, such as lxlogin2.lrz.de. If you are an institutional user with VPN access , you can use qclogin.srv.lrz.de. If you are an external user (DLR, UniBw, ...), you will need to use tx1.lrz.de as a proxy to reach qclogin.

Mac and Linux users, or if you use MobaXterm on Windows

Users with LinuxCluster access can use the following ssh command to connect to the QLM, doing a jump (-J) via a LinuxCLuster login node:

$ ssh -J <username>@lxlogin2.lrz.de <username>@qlm.for.lrz.de

Institutional users with VPN access should replace lxlogin2.lrz.de above with qclogin.srv.lrz.de.

$ ssh -J <username>@qclogin.srv.lrz.de <username>@qlm.for.lrz.de

External users need to login via tx1.lrz.de

$ ssh -J <username>@tx1.lrz.de <username>@qlm.for.lrz.de


Windows users with PuTTY

PuTTY users need to first configure a connection to the login node:

Users with LinuxCluster access to a LinuxCLuster login node, e.g. lxlogin2.lrz.de.

Institutional users with VPN access connect to qclogin.srv.lrz.de.

External users need to login to tx1.lrz.de

Then, use an ssh command on the login node to connect to qlm.

Regardless of which login node you are connected to, continue to login to the QLM:

$ ssh qlm.for.lrz.de

Step 2 - Jupyter Notebooks

If you want to use Jupyter notebooks on the QLM, you will have to first launch the notebook within the SSH session you already opened.

Then you will need to start a second SSH session that creates the tunnel so that your web browser can reach the QLM.

The QLM will tell you which port to use (starting at 8888) after running the command qlm_notebooks/launch_qlm_notebooks.

[qlm] (di29koy) ~> qlm_notebooks/launch_qlm_notebooks

QLM JUPYTER NOTEBOOKS SERVER

IPYTHONDIR=/home/di29koy/qlm_notebooks/notebooks_1.2.1/.ipython
JUPYTER_CONFIG_DIR=/home/di29koy/qlm_notebooks/notebooks_1.2.1/.jupyter
JUPYTER_DATA_DIR=/home/di29koy/qlm_notebooks/notebooks_1.2.1/.local/share/jupyter

JUPYTER_PORT=8888
JUPYTER_OPTS=

config:
    /home/di29koy/qlm_notebooks/notebooks_1.2.1/.jupyter
    /usr/etc/jupyter
    /usr/local/etc/jupyter
    /etc/jupyter
data:
    /home/di29koy/qlm_notebooks/notebooks_1.2.1/.local/share/jupyter
    /usr/local/share/jupyter
    /usr/share/jupyter
runtime:
    /home/di29koy/qlm_notebooks/notebooks_1.2.1/.local/share/jupyter/runtime

> jupyter notebook

[I 13:36:19.233 NotebookApp] The port 8888 is already in use, trying another port.
[I 13:36:19.233 NotebookApp] The port 8889 is already in use, trying another port.
[I 13:36:19.233 NotebookApp] The port 8890 is already in use, trying another port.
[I 13:36:19.233 NotebookApp] The port 8891 is already in use, trying another port.
[I 13:36:19.233 NotebookApp] The port 8892 is already in use, trying another port.
[I 13:36:19.248 NotebookApp] [jupyter_nbextensions_configurator] enabled 0.4.1
[I 13:36:19.249 NotebookApp] Serving notebooks from local directory: /home/di29koy/qlm_notebooks/notebooks_1.2.1
[I 13:36:19.249 NotebookApp] Jupyter Notebook 6.1.5 is running at:
[I 13:36:19.249 NotebookApp] http://qlm.for.lrz.de:8793/?token=db37cc2f5ec9f084c7e1e8ad5af8ea213baaad5fdc3e3a91
[I 13:36:19.249 NotebookApp]  or http://127.0.0.1:8793/?token=db37cc2f5ec9f084c7e1e8ad5af8ea213baaad5fdc3e3a91
[I 13:36:19.249 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmati                            on).
[C 13:36:19.252 NotebookApp]

    To access the notebook, open this file in a browser:
        file:///home/di29koy/qlm_notebooks/notebooks_1.2.1/.local/share/jupyter/runtime/nbserver-385871-open.html
    Or copy and paste one of these URLs:
        http://qlm.for.lrz.de:8793/?token=db37cc2f5ec9f084c7e1e8ad5af8ea213baaad5fdc3e3a91
     or http://127.0.0.1:8793/?token=db37cc2f5ec9f084c7e1e8ad5af8ea213baaad5fdc3e3a91
[I 13:40:32.046 NotebookApp] 302 GET /?token=db37cc2f5ec9f084c7e1e8ad5af8ea213baaad5fdc3e3a91 (127.0.0.1) 1.71ms

Note the URL to localhost at the bottom, which contains the port to use and the token you need to authenticate.

http://127.0.0.1:8793/?token=db37cc2f5ec9f084c7e1e8ad5af8ea213baaad5fdc3e3a91

Step 3 - Port Forwarding (aka tunnelling)

Now launch a second SSH session with the -L switch added to the ssh command. 

Mac and Linux users, or if you use MobaXterm on Windows

Users with LinuxCluster access use (replace 8888 with the port you need, in both occurrences)

$ ssh -J <username>@lxlogin2.lrz.de -L 8888:localhost:8888 <username>@qlm.for.lrz.de

So in the example above I would use:

ssh -J di29koy@lxlogin2.lrz.de -L 8793:localhost:8793 di29koy@qlm.for.lrz.de

Institutional users with VPN access use (replace 8888 with the port you need, in both occurrences)

$ ssh -J <username>@qclogin.srv.lrz.de -L 8888:localhost:8888 <username>@qlm.for.lrz.de

So in the example above I would use:

ssh -J di29koy@qclogin.srv.lrz.de -L 8793:localhost:8793 di29koy@qlm.for.lrz.de


External users use (replace 8888 with the port you need, in both occurrences)

$ ssh -J <username>@tx1.lrz.de -L 8888:localhost:8888 <username>@qlm.for.lrz.de

So in the example above I would use:

ssh -J di29koy@tx1.lrz.de -L 8793:localhost:8793 di29koy@qlm.for.lrz.de

Unless your SSH keys are already configured, you will be asked twice for your password - once for the login node, and then for the QLM.

You can then use your browser to connect to the URL as above, e.g. http://127.0.0.1:8793/?token=db37cc2f5ec9f084c7e1e8ad5af8ea213baaad5fdc3e3a91.

Ports and Addresses, the details

Both the browser IP address and the tunnel destination IP address is 127.0.0.1 (=localhost) because the tunnelled port to the QLM has one end on your local machine and the other end is on the QLM. In both cases we're connecting to the local machine, the browser opens the local end of the tunnel, and the other end of the tunnel connects to the notebook running on that machine.

The ports - if you set the tunnel to use your own Notebook port on both ends, then it's nice and uniform all the way through the chain. (e.g. 8793 in the browser connects to the tunnel that exists on port 8793, and the other end of the tunnel connects to port 8793 where the Notebook is running.

If you are using PuTTY and doing a second hop to the QLM, it's especially important to check that your port numbers match all the way along the chain.

In some cases (e.g. in the training from Atos), it is preferred to use the default port 8888 on your local end of the tunnel. In this case you specify the local port is 8888 (e.g. 8888:localhost:8793), and in the browser URL you must also use the port 8888.

Windows users with PuTTY

Windows users with PuTTY need to create the tunnel with two hops. First configure a connection to the login node (lxlogin2, qclogin or tx1) and second, use an ssh command on the login node to connect to qlm.

In this second instance of PuTTY, use the same setup as before, and configure a port forward:

  • Load the session corresponding to your login node.
  • Go to Connection → SSH → Tunnels and add the ports as seen in the screenshot. Do not forget to click on "Add" in the end. Source port corresponds to the first number in the -L argument. For PuTTY, it is required you use 127.0.0.1 instead of localhost for the destination.
  • Start this second SSH session.


Users with LinuxCluster access use lxlogin2.lrz.de as in the screenshot.

Users with institutional VPN use qclogin.srv.lrz.de instead of lxlogin2.

External users use tx1.lrz.de instead of lxlogin2.

For the second hop, once on your login node, you need to connect to QLM with another tunnel.

$ ssh -L 8888:localhost:8888 <username>@qlm.for.lrz.de

Again, replace the port number with the correct port for your Notebook session.

You can then use your browser to connect to the URL as above, e.g. http://127.0.0.1:8793/?token=db37cc2f5ec9f084c7e1e8ad5af8ea213baaad5fdc3e3a91.

FAQ

I can connect to a Notebook, but my token doesn't work and I can't access it.

You are likely connected to someone else's Notebook session. Check that the port numbers you have set all correspond to the port that was assigned to you when you started the Notebook.

I can't connect to the Notebook at all, and I've checked that the ports are all correct.

Here are some possible causes for this issue:

  • Your first SSH session has been closed, so the Notebook session is no longer running.
  • Your browser is configured to use a proxy, and therefore can't be routed via the tunnel on your own machine.
  • In a previous session, you saved the port forwarding tunnel in your PuTTY settings. Now the first or second session is occupying ports that need to be free for your new session.

I connected just fine, but now it's suddenly stopped working.

Ensure that none of your SSH sessions have timed-out and been closed. If your login shell is bash, check that the TMOUT environment variable is set to 0.

Slurm Workload Manager

As an alternative to Jupyter notebooks, you can also use the Slurm Workload Manager to submit jobs to the QLM (on the QLM itself or on qclogin). Users with prior HPC experience might be familiar with Slurm. General documentation is available here.