Skip to main content

imath script

imath-setup.sh# Compute access from your own machine: the imath command

As you have seen on the page Compute resources, the institute's nodes are reachable only through the jump host ssh.math.uzh.ch.

We have created a script that sets up that access for you, together with a few shell shortcuts. With these we simplified the procedure of connecting to the nodes: you can list all machines with a tab, see which GPUs are busy, move files in both directions, update the node list yourself with the refresh command, start a long computation in a detachable session, or open a graphical program such as RStudio on a node. So it is a very handy tool. And if you do not want it after all — remove it again with a single command.

Here is the documentation of the script, for transparency reasons: we do not want to install some bitcoin miner on your machines. If something is not clear from the comments inside the script itself, the sections below explain how it works and what it does.

(These scripts are tested on macOS and Linux devices. The Windows version is not tested — under Windows please use WSL or Git Bash, where the same .sh file runs unchanged.)

How the pieces fit together

imath-architecture.png

Three things are worth keeping apart: the jump host is the only machine you connect to yourself, and nothing runs there; the compute nodes are the actual machines — the wiki page compute resources puts it as “accessed by SSH only and only from inside I-MATH/DM3L”, and the jump host is how you get inside; your home directory lives on a network file system and is identical everywhere, which is why you never have to choose a node when uploading.

You have to be on a UZH network for this. From outside, switch on the UZH VPN first and everything behaves exactly the same.

1. Installation

Be on a UZH network first — eduroam, institute WLAN or cable — or switch on the UZH VPN. The installation talks to ssh.math.uzh.ch, and so does every command afterwards.

Download imath-setup.sh

chmod +x imath-setup.sh
./imath-setup.sh <your-username - https://www.math.uzh.ch/my/setting - Account name  -- or create : https://math.uzh.ch/account>

It asks for a passphrase for the new key, and then once for your I-MATH password — (maybe your MFA too). After that neither is needed in day-to-day work: the key replaces both.

Options:

Command Effect
./imath-setup.sh <user> install, or update an existing installation
./imath-setup.sh --no-xquartz <user> skip the XQuartz step (macOS only)
./imath-setup.sh --uninstall remove everything it installed
./imath-setup.sh --help the comment header of the script itself

It is idempotent. Running it again changes nothing twice: every piece is compared with what belongs there and rewritten only if it differs. That is also how you update to a newer version — just run it again. Every file it touches is backed up as <file>.bak-imath first.

2. The commands you get

Everything goes through one command, imath. The full list is always available with imath help.

imath <TAB>                 # list of all nodes, fetched live from the institute
imath aroca                 # log in to a compute node
imath --visual estonia0     # log in with X11, for graphical programs (then: rstudio)
imath refresh               # fetch the node list again
imath gpus                  # all GPU nodes: card, memory in use, load, who is logged in
imath upload <path...>      # into your cluster home
imath upload --tmp aroca <path>   # onto the local disk of that node
imath download <path>       # back to your own machine
imath help                  # this list

Before every login it prints a short banner:

  aroca
  Reserved a slot?  https://made-fb1.math.uzh.ch   (Compute Host / with GPU)
  Logged in right now: miinei

The second line is the reminder about the reservation, the third shows who else is currently on that machine — worth knowing before you occupy 128 cores.

imath gpus looks like this:

  NODE       GPU                      IN-USE           VRAM GB   LOAD  LOGGED IN
  --------------------------------------------------------------------------------
  aroca      0 RTX 6000 Ada           [..........]    0.0/48.0    0 %  ******
  bellow     0 L40S                   [..........]    0.0/45.0    0 %  -
             1 L40S                   [..........]    0.0/45.0    0 %
  sulem      0 A40                    [#########.]   39.6/45.0    0 %  ******
             1 A40                    [########..]   37.5/45.0    0 %

Two numbers matter: memory (does your model fit?) and load (is somebody computing right now?).

Idle is not the same as free. This list says what is running, not who is allowed to run. A node that looks empty may be booked by somebody else. The portal decides, this command only tells you whether the machine is actually busy. (RESERVE!)

3. Documentation: what the script does

3.1 What it creates

Location Contents
~/.ssh/id_imath A dedicated ed25519 key, used only for the cluster. Your other keys are untouched.
~/.ssh/config A Host imath block with your username, that key and connection options. It is placed at the top of the file, because in ssh_config the first matching entry wins.
~/.config/imath/imath.sh The imath command itself — all functions and the tab completion.
~/.zshrc or ~/.bashrc Five lines, which do nothing but load the file above. Nothing else is added to your startup file.
~/.cache/imath/ The cached node list and the GPU classification. Pure cache, can be deleted at any time.
macOS only Homebrew and XQuartz, if they are missing and you did not pass --no-xquartz. 
  YOUR MACHINE                                        THE CLUSTER
  ────────────────────────────────────────────        ──────────────────────────────
  ~/.ssh/id_imath          key, cluster only          ~/.ssh/authorized_keys
  ~/.ssh/config            Host imath  ───────────────▶  your public key appended
  ~/.config/imath/imath.sh the imath command
  ~/.zshrc (or .bashrc)    5 lines, loads the file    ~/.bashrc
  ~/.cache/imath/          node list (cache only)       └─ marked PATH block for R
  [macOS] Homebrew, XQuartz  for imath --visual

Everything the script writes into an existing file sits between two marker comments:

# >>> imath-setup >>>
...
# <<< imath-setup <<<

Those markers are how it finds its own text again — it never touches a line outside them. If it notices that you have your own imath(), gpus() or upload() defined elsewhere in your startup file, it only reports that with a line number, so you can decide yourself.

3.2 Step by step, what the installer does

  1. Graphics stack (macOS only). If XQuartz is missing, it installs Homebrew (if that is missing too) and then XQuartz, because imath --visual needs an X server. The cask writes to /Applications, so it asks for your Mac password once — and it asks before starting, not halfway through. --no-xquartz skips this step entirely; on Linux there is nothing to do.
  2. SSH key. Creates ~/.ssh/id_imath if it does not exist yet, and never overwrites an existing one. ed25519, with a comment containing your username and the year/month.
  3. SSH config. Writes the Host imath block described above, or updates it if it has changed (a different username, a different key path).
  4. The imath command. Writes ~/.config/imath/imath.sh and the five-line loader into your startup file.
  5. Public key onto the server. Only if passwordless login does not already work. It uses ssh-copy-id when present, and otherwise appends the public key over a normal SSH session.
  6. One line on the cluster side. Appends the marked PATH block described above to ~/.bashrc in your cluster home. Since the home is shared, it applies on every node at once.

Finally it checks what it built.

3.3 Where the data comes from

Nothing about the institute is hard-coded in the script. Everything is asked for at runtime:

Information Source
The node names /usr/sepp/etc/compute_hosts.lst — the list the institute maintains itself. Filtered to plain lowercase names, exam machines removed. Cached under ~/.cache/imath/nodes.
Which nodes have a GPU nvidia-smi -L on each node, once, then remembered.
GPU load nvidia-smi --query-gpu=index,name,memory.used,memory.total,utilization.gpu
Who is logged in who on that node

That is also why imath refresh exists: when the institute adds a machine, you pick it up yourself without waiting for a new version of the script.

3.4 What happens when you use the commands

  • imath <node> runs ssh -J imath …, that is: a connection to the jump host and from there to the node. Your private key never leaves your own machine. Connections are reused for ten minutes (ControlMaster), which is why the second command is instant.
  • imath --visual <node> opens its own connection with ssh -Y and does not reuse a shared one, because X11 forwarding is negotiated while the connection is built.
  • imath gpus asks at most eight nodes in parallel — the jump host accepts only a limited number of simultaneous connections — and waits only for its own queries, not for other jobs running in your shell.
  • imath upload / download are scp with the right options. Without --tmp everything goes to your cluster home, which is the same file system on every node. With --tmp it goes to /tmp/<user> on one node: local scratch, fast and large, but node-local and wiped eventually.

3.5 What the script does not do

  • No sudo anywhere, except for the XQuartz installation on macOS — and that step can be skipped.
  • No daemon, no login item, nothing that runs in the background. The imath command only exists while you type it.
  • No telemetry, no network access apart from ssh.math.uzh.ch and (macOS only) the Homebrew download.
  • It changes no file it did not write itself. Every modification sits between markers, and every file gets a .bak-imath copy before it is touched.
  • It does not read, copy or send any of your data.

The script is a single file of plain shell, about 980 lines including comments — it can be read in half an hour, and the interesting parts are commented in place.

3.6 Uninstall

./imath-setup.sh --uninstall

Removes the loader line from your startup file, ~/.config/imath/, the marked block in ~/.ssh/config, the cache, and the marked PATH block in ~/.bashrc on the cluster (if the cluster is reachable at that moment; otherwise it says so). It deliberately keeps:

  • Homebrew and XQuartz — other software on your machine uses them.
  • Your key ~/.ssh/id_imath — delete it yourself if you want it gone.
  • Your public key in ~/.ssh/authorized_keys on the cluster.

4. A typical session

  WHERE          WHAT YOU DO                                  WHAT HAPPENS

  laptop    ──▶  imath gpus                                   find a free card
            ──▶  book the slot in the portal                  the node is yours
            ──▶  imath upload ~/project                       code lands in your home
            ──▶  imath aroca                                  banner, then you are in

  node      ──▶  cd project                                   home is already there
            ──▶  tmux new -s run1                             a session that survives
            ──▶  python3 train.py | tee log.txt               the computation starts
            ──▶  Ctrl+B, then D                               detach; it keeps running
            ──▶  exit                                         ... close the laptop

  later     ──▶  imath aroca ; tmux attach -t run1            look in again
  laptop    ──▶  imath download project/result.csv            fetch the result

The same thing as commands to copy:

# --- on your own machine ----------------------------------------------
imath gpus                          # 1. look for a free card
                                    # 2. book a slot: made-fb1.math.uzh.ch
imath upload ~/Documents/project    # 3. code into the cluster home
imath aroca                         # 4. log in

# --- now on aroca -----------------------------------------------------
cd project                          # 5. into the project folder
tmux new -s run1                    # 6. detachable session
python3 train.py | tee log.txt      # 7. start the computation
                                    # 8. Ctrl+B, then D  -> detach
exit                                # 9. close the laptop

# --- later ------------------------------------------------------------
imath aroca
tmux attach -t run1                 # 10. look in again
exit
imath download project/result.csv   # 11. fetch the result

Rule of thumb: anything that runs longer than a couple of minutes goes into tmux. Without it, your computation belongs to the SSH connection and dies when the laptop is closed. exit inside the session ends it together with the computation — to keep it running always use Ctrl+B, D.

5. When something does not work

Symptom Cause and remedy
Connection closed by UNKNOWN port 65535 You are not on a UZH network. Connect to eduroam / the institute WLAN, or switch on the UZH VPN. A phone hotspot or a private connection alone does not reach the jump host.
Permission denied (publickey,…) The key is not on the server yet. Run the setup script again.
The password is asked repeatedly Every repetition is a failed attempt. After five, the institute blocks your IP for five days. Abort and reset the password at math.uzh.ch/my.
'xy' is not in the institute's node list A typo, or the cache is stale: imath refresh.
SEPP Error: Rscript: Command not found The PATH block on the cluster is missing (see 3.1). Run the setup script again.
Node unreachable, jump host fine Your compute access is probably not enabled yet. Short mail to support@math.uzh.ch.
CUDA available: False You are on a CPU node. Pick a GPU node with imath gpus.
Missing X server or $DISPLAY on the node You logged in without --visual. On macOS, XQuartz must be installed, and after a fresh installation you have to log out and back in once.
The computation dies when the laptop closes Started without tmux.
No space left or a quota message The home is full (5 GB). du -sh ~/* and move the large things to /tmp.
imath does not exist after the setup Open a new terminal, or run source ~/.zshrc.

No comments to display

Back to top