Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/mkreadme-gha' into mkreadme-gha
Browse files Browse the repository at this point in the history
  • Loading branch information
@maouw
maouw committed Oct 24, 2023
2 parents df705b6 + 6c65b3c commit 5227f10
Showing 1 changed file with 0 additions and 326 deletions.
326 changes: 0 additions & 326 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,326 +0,0 @@
# hyakvnc

hyakvnc -- A tool for launching VNC sessions on Hyak.

`hyakvnc` is a command-line tool that makes it easy to start a graphical [VNC](https://en.wikipedia.org/wiki/Virtual_Network_Computing) session on the University of Washington [Hyak](https://hyak.uw.edu/) cluster, allowing you to interact with the system in a point-and-click environment, with support for graphical applications such as [Freesurfer](https://surfer.nmr.mgh.harvard.edu/). `hyakvnc` sessions run in [Apptainer](https://apptainer.org) containers, which provide reproducible environments that can run anywhere and be shared with other researchers.

## Prerequisites

Before running `hyakvnc`, you'll need the following:

- A Linux, macOS, or Windows machine
- The OpenSSH client (usually included with Linux and macOS, and available for Windows via [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) or [Cygwin](https://www.cs.odu.edu/~zeil/cs252/latest/Public/loggingin/cygwin.mmd.html) [note that the Windows 10+ built-in OpenSSH client will not work])
- A VNC client/viewer ([TurboVNC viewer](https://www.turbovnc.org) is recommended for all platforms)
- HYAK Klone access with compute resources
- A private SSH key on your local machine which has been added to the authorized keys on the login node of the HYAK Klone cluster (see below)
- A HyakVNC-compatible Apptainer container image in a directory on Hyak (usually with the file extension `.sif`) or the URL to one (e.g,., `oras://ghcr.io/maouw/hyakvnc_apptainer/ubuntu22.04_turbovnc:latest`)

Follow the instructions below to set up your machine correctly:

### Installing OpenSSH and TurboVNC

#### Linux

If you are using Linux, OpenSSH is probably installed already -- if not, you can install it via `apt-get install openssh-client` on Debian/Ubuntu or `yum install openssh-clients` on RHEL/CentOS/Rocky/Fedora. To open a terminal window, search for "Terminal" in your desktop environment's application launcher.

To install TurboVNC, download the latest version from [here](https://sourceforge.net/projects/turbovnc/files). On Debian/Ubuntu, you will need to download the file ending with `arm64.deb`. On RHEL/CentOS/Rocky/Fedora, you will need to download the file ending with `x86_64.rpm`. Then, install it by running `sudo dpkg -i <filename>` on Debian/Ubuntu or `sudo rpm -i <filename>` on RHEL/CentOS/Rocky/Fedora.

#### macOS

If you're on macOS, OpenSSH will already be installed. To open a terminal window, open `/Applications/Utilities/Terminal.app` or search for "Terminal" in Launchpad or Spotlight.

To install TurboVNC, download the latest version from [here](https://sourceforge.net/projects/turbovnc/files). On an M1 Mac (newer), you will need to download the file ending with `arm64.dmg`. On an Intel Mac (older), you will need the file ending with `x86_64.dmg`. Then, open the `.dmg` file and launch the installer inside.

#### Windows

Windows needs a little more setup. You'll need to install a terminal emulator as well as the OpenSSH client. The easiest way to do this is to install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) (recommended for Windows versions 10+, comes with the OpenSSH client already installed) or [Cygwin](https://www.cs.odu.edu/~zeil/cs252/latest/Public/loggingin/cygwin.mmd.html) (not recommended, needs additional setup). See the links for instructions on how to install these. You can start a terminal window by searching for "Terminal" in the Start menu.

To install TurboVNC, download the latest version from [here](https://sourceforge.net/projects/turbovnc/files). You will need the file ending with `x64.exe`. Run the program to install TurboVNC.

### Setting up SSH keys to connect to Hyak compute nodes

Before you are allowed to connect to a compute node where your VNC session will be running, you must add your SSH public key to the authorized keys on the login node of the HYAK Klone cluster.

If you don't, you will receive an error like this when you try to connect:

```text
Permission denied (publickey,gssapi-keyex,gssapi-with-mic)
```

To set this up quickly on Linux, macOS, or Windows (WSL2/Cygwin), open a new terminal window on your machine and enter the following 2 commands before you try again. Replace `your-uw-netid` with your UW NetID:

```bash
[ ! -r ~/.ssh/id_rsa ] && ssh-keygen -t rsa -b 4096 -N '' -C "[email protected]" -f ~/.ssh/id_rsa
ssh-copy-id -o StrictHostKeyChecking=no -i ~/.ssh/id_rsa "your-uw-netid"@klone.hyak.uw.edu
```

See https://hyak.uw.edu/docs/setup/intracluster-keys for more information.

### Finding a HyakVNC-compatible container image

You'll need to find a HyakVNC-compatible container image to run your VNC session in. The following images are provided by us and can be used with `hyakvnc` by copying and pasting the URL into the `hyakvnc create` command:

- `oras://ghcr.io/maouw/hyakvnc_apptainer/ubuntu22.04_turbovnc:latest` -- Ubuntu 22.04 with TurboVNC
- `oras://ghcr.io/maouw/ubuntu22.04_freesurfer:latest` -- Ubuntu 22.04 with TurboVNC and Freesurfer

## Installing `hyakvnc`

`hyakvnc` should be installed on the login node of the HYAK Klone cluster.

To connect to the login node, you'll need to enter the following command into a terminal window (replacing `your-uw-netid` with your UW NetID) and provide your password when prompted:

```bash
ssh [email protected]
```

### Quick install

After you've connected to the login node, you can download and install `hyakvnc` by running the following command. Copy and paste it into the terminal window where you are connected to the login node and press enter:

```bash
curl -o ~/.local/bin/hyakvnc --create-dirs -fsSL https://raw.githubusercontent.com/maouw/hyakvnc/main/hyakvnc && chmod +x ~/.local/bin/hyakvnc && [[ ":${PATH}:" != *":$HOME/.local/bin:"* ]] && export PATH="$HOME/.local/bin:$PATH" && [-n "${ZSH_VERSION:-}" ] && rehash
```

This will download and install `hyakvnc` to your `~/.local/bin` directory and add it to your `$PATH` so you can run it by typing `hyakvnc` into the terminal window.

### Installing manually

In a terminal window connected to a login node, enter this command to clone the repository and navigate into the repository directory:

```bash
git clone https://github.com/maouw/hyakvnc && cd hyakvnc
```

Then, run the following command to install `hyakvnc`:

```bash
./hyakvnc install
```

If you prefer, you may continue to use `hyakvnc` from the directory where you cloned it by running `./hyakvnc` from that directory instead of using the command `hyakvnc`.
started

## Getting started

### Creating a VNC session

Start a VNC session with the `hyakvnc create` command followed by arguments to specify the container. In this example, we'll use a basic container for a graphical environment from the HyakVNC GitHub Container Registry:

```bash
hyakvnc create --container oras://maouw/hyakvnc_apptainer/ubuntu22.04_turbovnc:latest
```

It may take a few minutes to download the container if you're running it the first time. If successful, `hyakvnc` should print commands and instructions to connect:

```text
==========
Copy and paste these instructions into a command line terminal on your local machine to connect to the VNC session.
You may need to install a VNC client if you don't already have one.
NOTE: If you receive an error that looks like "Permission denied (publickey,gssapi-keyex,gssapi-with-mic)", you don't have an SSH key set up.
See https://hyak.uw.edu/docs/setup/intracluster-keys for more information.
To set this up quickly on Linux, macOS, or Windows (WSL2/Cygwin), open a new terminal window on your machine and enter the following 2 commands before you try again:
[ ! -r ~/.ssh/id_rsa ] && ssh-keygen -t rsa -b 4096 -N '' -C "[email protected]" -f ~/.ssh/id_rsa
ssh-copy-id -o StrictHostKeyChecking=no [email protected]
---------
LINUX TERMINAL (bash/zsh):
ssh -f -o StrictHostKeyChecking=no -L 5901:/mmfs1/home/your-uw-netid/.hyakvnc/jobs/15042104/vnc/socket.uds -J [email protected] your-uw-netid@g3053 sleep 20 && vncviewer localhost:5901 || xdg-open vnc://localhost:5901 || echo 'No VNC viewer found. Please install one or try entering the connection information manually.'
MACOS TERMINAL
ssh -f -o StrictHostKeyChecking=no -L 5901:/mmfs1/home/your-uw-netid/.hyakvnc/jobs/15042104/vnc/socket.uds -J [email protected] your-uw-netid@g3053 sleep 20 && open -b com.turbovnc.vncviewer.VncViewer --args localhost:5901 2>/dev/null || open -b com.realvnc.vncviewer --args localhost:5901 2>/dev/null || open -b com.tigervnc.vncviewer --args localhost:5901 2>/dev/null || open vnc://localhost:5901 2>/dev/null || echo 'No VNC viewer found. Please install one or try entering the connection information manually.'
WINDOWS
ssh -f -o StrictHostKeyChecking=no -L 5901:/mmfs1/home/your-uw-netid/.hyakvnc/jobs/15042104/vnc/socket.uds -J [email protected] your-uw-netid@g3053 sleep 20 && cmd.exe /c cmd /c "$(cmd.exe /c where "C:\Program Files\TurboVNC;C:\Program Files(x86)\TurboVNC:vncviewerw.bat")" localhost:5901 || echo 'No VNC viewer found. Please install one or try entering the connection information manually.'
==========
```

## Usage

`hyakvnc` is command-line tool that only works on the login node of the Hyak cluster.

### Create a VNC session on Hyak

```text
Usage: hyakvnc create [create options...] -c <container> [extra args to pass to apptainer...]
Description:
Create a VNC session on Hyak.
Options:
-h, --help Show this help message and exit
-c, --container Path to container image (required)
-A, --account Slurm account to use (default: )
-p, --partition Slurm partition to use (default: )
-C, --cpus Number of CPUs to request (default: 4)
-m, --mem Amount of memory to request (default: 4G)
-t, --timelimit Slurm timelimit to use (default: 12:00:00)
-g, --gpus Number of GPUs to request (default: )
Extra arguments:
Any extra arguments will be passed to apptainer run.
See 'apptainer run --help' for more information.
Examples:
# Create a VNC session using the container ~/containers/mycontainer.sif
hyakvnc create -c ~/containers/mycontainer.sif
# Create a VNC session using the URL for a container:
hyakvnc create -c oras://ghcr.io/maouw/hyakvnc_apptainer/ubuntu22.04_turbovnc:latest
# Use the SLURM account escience, the partition gpu-a40, 4 CPUs, 1GB of memory, 1 GPU, and 1 hour of time:
hyakvnc create -c ~/containers/mycontainer.sif -A escience -p gpu-a40 -C 4 -m 1G -t 1:00:00 -g 1
```

### Show the status of running HyakVNC sessions

```text
Usage: hyakvnc status [status options...]
Description:
Check status of VNC session(s) on Hyak.
Options:
-h, --help Show this help message and exit
-d, --debug Print debug info
-j, --jobid Only check status of provided SLURM job ID (optional)
Examples:
# Check the status of job no. 12345:
hyakvnc status -j 12345
# Check the status of all VNC jobs:
hyakvnc status
```

### Show connection information for a HyakVNC sesssion

```text
Usage: hyakvnc show <jobid>
Description:
Show connection information for a HyakVNC sesssion.
If no job ID is provided, a menu will be shown to select from running jobs.
Options:
-h, --help Show this help message and exit
Examples:
# Show connection information for session running on job 123456:
hyakvnc show 123456
# Interactively select a job to show connection information for:
hyakvnc show
# Show connection information for session running on job 123456 for macOS:
hyakvnc show -s mac 123456
```

### Stop a HyakVNC session

```text
Usage: hyakvnc stop [-a] [<jobids>...]
Description:
Stop a provided HyakVNC sesssion and clean up its job directory.
If no job ID is provided, a menu will be shown to select from running jobs.
Options:
-h, --help Show this help message and exit
-n, --no-cancel Don't cancel the SLURM job
-a, --all Stop all jobs
Examples:
# Stop a VNC session running on job 123456:
hyakvnc stop 123456
# Stop a VNC session running on job 123456 and do not cancel the job:
hyakvnc stop --no-cancel 123456
# Stop all VNC sessions:
hyakvnc stop -a
# Stop all VNC sessions but do not cancel the jobs:
hyakvnc stop -a -n
```

### Show the current configuration for hyakvnc

```text
Usage: hyakvnc config [config options...]
Description:
Show the current configuration for hyakvnc, as set in the user configuration file at /home/altan/.hyakvnc/hyakvnc-config.env, in the current environment, or the default values set by hyakvnc.
Options:
-h, --help Show this help message and exit
Examples:
# Show configuration
hyakvnc config
```

### Install the hyakvnc command

```text
Usage: hyakvnc install [install options...]
Description:
Install hyakvnc so the "hyakvnc" command can be run from anywhere.
Options:
-h, --help Show this help message and exit
-i, --install-dir Directory to install hyakvnc to (default: ~/.local/bin)
-s, --shell [bash|zsh] Shell to install hyakvnc for (default: $SHELL or bash)
Examples:
# Install
hyakvnc install
# Install to ~/bin:
hyakvnc install -i ~/bin
```

## Configuration

The following [environment variables](https://wiki.archlinux.org/title/environment_variables) can be used to override the default settings. Any arguments passed to `hyakvnc create` will override the environment variables.

You can modify the values of these variables by:

- Setting and exporting them in your shell session, e.g. `export HYAKVNC_SLURM_MEM='8G'` (which will only affect the current shell session)
- Setting them in your shell's configuration file, e.g. `~/.bashrc` or `~/.zshrc` (which will affect all shell sessions)
- Setting them by prefixing the `hyakvnc` command with the variable assignment, e.g. `HYAKVNC_SLURM_MEM='8G' hyakvnc create ...` (which will only affect the current command)
- Setting them in the file `~/.hyakvnc/hyakvnc-config.env` (which will affect all `hyakvnc` commands)

When you set an environment variable, it is advisable to surround the value with single quotes (`'`) to prevent your shell from interpreting special characters. There should be no spaces between the variable name, the equals sign, and the value.

The following variables are available:

- HYAKVNC_DIR: Local directory to store application data (default: `$HOME/.hyakvnc`)
- HYAKVNC_CONFIG_FILE: Configuration file to use (default: `$HYAKVNC_DIR/hyakvnc-config.env`)
- HYAKVNC_LOG_FILE: Log file to use (default: `$HYAKVNC_DIR/hyakvnc.log`)
- HYAKVNC_LOG_LEVEL: Log level to use for interactive output (default: `INFO`)
- HYAKVNC_LOG_FILE_LEVEL: Log level to use for log file output (default: `DEBUG`)
- HYAKVNC_SSH_HOST: Default SSH host to use for connection strings (default: `klone.hyak.uw.edu`)
- HYAKVNC_DEFAULT_TIMEOUT: Seconds to wait for most commands to complete before timing out (default: `30`)
- HYAKVNC_VNC_PASSWORD: Password to use for new VNC sessions (default: `password`)
- HYAKVNC_VNC_DISPLAY: VNC display to use (default: `:1`)
- HYAKVNC_APPTAINER_BIN: Name of apptainer binary (default: `apptainer`)
- HYAKVNC_APPTAINER_CONTAINER: Path to container image to use (default: (none; set by `--container` option))
- HYAKVNC_APPTAINER_APP_VNCSERVER: Name of app in the container that starts the VNC session (default: `vncserver`)
- HYAKVNC_APPTAINER_APP_VNCKILL: Name of app that cleanly stops the VNC session in the container (default: `vnckill`)
- HYAKVNC_APPTAINER_WRITABLE_TMPFS: Whether to use a writable tmpfs for the container (default: `1`)
- HYAKVNC_APPTAINER_CLEANENV: Whether to use a clean environment for the container (default: `1`)
- HYAKVNC_APPTAINER_ADD_BINDPATHS: Bind paths to add to the container (default: (none))
- HYAKVNC_APPTAINER_ADD_ENVVARS: Environment variables to add to before invoking apptainer (default: (none))
- HYAKVNC_APPTAINER_ADD_ARGS: Additional arguments to give apptainer (default: (none))
- HYAKVNC_SLURM_JOB_PREFIX: Prefix to use for hyakvnc SLURM job names (default: `hyakvnc-`)
- HYAKVNC_SLURM_SUBMIT_TIMEOUT: Seconds after submitting job to wait for the job to start before timing out (default: `120`)
- HYAKVNC_SLURM_OUTPUT_DIR: Directory to store SLURM output files (default: `$HYAKVNC_DIR/slurm-output`)
- HYAKVNC_SLURM_OUTPUT: Where to send SLURM job output (default: `$HYAKVNC_SLURM_OUTPUT_DIR/job-%j.out`)
- HYAKVNC_SLURM_JOB_NAME: What to name the launched SLURM job (default: (set according to container name))
- HYAKVNC_SLURM_ACCOUNT: Slurm account to use (default: (autodetected))
- HYAKVNC_SLURM_PARTITION: Slurm partition to use (default: (autodetected))
- HYAKVNC_SLURM_CLUSTER: Slurm cluster to use (default: (autodetected))
- HYAKVNC_SLURM_GPUS: Number of GPUs to request (default: (none))
- HYAKVNC_SLURM_MEM: Amount of memory to request, in [M]egabytes or [G]igabytes (default: `4G`)
- HYAKVNC_SLURM_CPUS: Number of CPUs to request (default: `4`)
- HYAKVNC_SLURM_TIMELIMIT: Time limit for SLURM job (default: `12:00:00`)

## License

`hyakvnc` is licensed under [MIT License](LICENSE).

0 comments on commit 5227f10

Please sign in to comment.