forked from uw-psych/hyakvnc
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
8 additions
and
169 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -80,7 +80,7 @@ ssh [email protected] | |
| 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 | ||
| eval "$(curl -fsSL https://raw.githubusercontent.com/maouw/hyakvnc/main/install.sh)" | ||
| eval "$(curl -fsSL https://raw.githubusercontent.com/maouw/hyakvnc/add-local-backend/install.sh)" | ||
| ``` | ||
|
|
||
| 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. | ||
|
|
@@ -140,159 +140,12 @@ ssh -f -o StrictHostKeyChecking=no -L 5901:/mmfs1/home/your-uw-netid/.hyakvnc/jo | |
| ## 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: ) | ||
| Advanced options: | ||
| --no-ghcr-oras-preload Don't preload ORAS GitHub Container Registry images | ||
| 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/hyakvnc-vncserver-ubuntu22.04: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/runner/.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 | ||
| ``` | ||
|
|
||
| ### Update hyakvnc | ||
|
|
||
| ```text | ||
| Usage: hyakvnc update [update options...] | ||
| Description: | ||
| Update hyakvnc. | ||
| Options: | ||
| -h, --help Show this help message and exit | ||
| Examples: | ||
| # Update hyakvnc | ||
| hyakvnc update | ||
| ``` | ||
|
|
||
| ### 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 | ||
|
|
@@ -312,37 +165,23 @@ 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_CHECK_UPDATE_FREQUENCY: How often to check for updates in `[d]`ays or `[m]`inutes (default: `0` for every time. Use `1d` for daily, `10m` for every 10 minutes, etc. `-1` to disable.) | ||
| - 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_JOBS_DIR: Directory to store job data (default: `$HYAKVNC_DIR/jobs`) | ||
| - HYAKVNC_CHECK_UPDATE_FREQUENCY: How often to check for updates in `[d]`ays or `[m]`inutes (default: `0` for every time. Use `1d` for daily, `10m` for every 10 minutes, etc. `-1` to disable.) | ||
| - HYAKVNC_SSH_HOST: Default SSH host to use for connection strings (default: (autodetected)) | ||
| - HYAKVNC_DEFAULT_TIMEOUT: Seconds to wait for most commands to complete before timing out (default: `30`) | ||
| - HYAKVNC_BACKEND: Backend to use (default: (autodetected, can be `klone`, `apptainer`)) | ||
| - HYAKVNC_SSH_HOST: Default SSH host to use for connection strings (default: `localhost` if backend is apptainer or docker, `klone.hyak.uw.edu` if backend is `klone`) | ||
| - HYAKVNC_VNC_PASSWORD: Password to use for new VNC sessions (default: `password`) | ||
| - HYAKVNC_VNC_DISPLAY: VNC display to use (default: `:1`) | ||
| - HYAKVNC_APPTAINER_CONTAINERS_DIR: Directory to look for apptainer containers (default: (none)) | ||
| - HYAKVNC_APPTAINER_GHCR_ORAS_PRELOAD: Whether to preload SIF files from the ORAS GitHub Container Registry (default: `0`) | ||
| - 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`) | ||
| - HYAKVNC_JOB_PREFIX: Prefix to use for hyakvnc job names (default: `hyakvnc-`) | ||
| ## License | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters