From 3ab4ccc7329a6308f51801354f409a7446ff1233 Mon Sep 17 00:00:00 2001 From: Marton Balazs Date: Wed, 16 Aug 2023 17:17:15 +0100 Subject: [PATCH 1/7] Added interactive.md and ssh_tunnel.md --- source/index.md | 4 ++- source/mathematics/interactive.md | 53 +++++++++++++++++++++++++++++++ source/ssh_tunnel.md | 39 +++++++++++++++++++++++ 3 files changed, 95 insertions(+), 1 deletion(-) create mode 100644 source/mathematics/interactive.md create mode 100644 source/ssh_tunnel.md diff --git a/source/index.md b/source/index.md index 3b1b47a..078aa7e 100644 --- a/source/index.md +++ b/source/index.md @@ -32,6 +32,8 @@ maxdepth: 2 caption: "Contents:" --- engineering/index +mathematics/interactive +ssh_tunnel ``` # Credits and licenses @@ -53,4 +55,4 @@ See [LICENSE.md][acrc-hpc-community-docs-license] in the [GitHub repository][acr [humanstxt-file]: https://acrc.github.io/HPC-community-docs/humans.txt "humans.txt" [humanstxt-website]: https://humanstxt.org "Humans TXT website" [cc-by-sa-4]: https://creativecommons.org/licenses/by-sa/4.0/ "CC BY-SA 4.0 license" -[acrc-hpc-community-docs-license]: https://github.com/ACRC/HPC-community-docs/blob/main/LICENSE.md "ACRC HPC community documentation LICENSE.md" \ No newline at end of file +[acrc-hpc-community-docs-license]: https://github.com/ACRC/HPC-community-docs/blob/main/LICENSE.md "ACRC HPC community documentation LICENSE.md" diff --git a/source/mathematics/interactive.md b/source/mathematics/interactive.md new file mode 100644 index 0000000..64d813c --- /dev/null +++ b/source/mathematics/interactive.md @@ -0,0 +1,53 @@ +--- +title: "Interactive sessions" +--- + +These are instructions on getting quick interactive sessions on BluePebble, assuming you already have login to this cluster and a project code. As this is primarily aimed for the School of Mathematics, we'll refer to the project code to be in the form MATHXXXXXX, but this could be in other format. + +The School of Mathematics ringfenced a few of its nodes with the software Magma installed on them into the "magma" partition, and we also use this partition for quick interactive testing. + +:::{important} +If you need to run something heavy that takes hours or days please remove any reference to the "magma" partition from the below. +::: + +We use maple/xmaple as an example but comsol, magma, math/mathematica, etc work similarly. + +- **If you don't need a graphical interface:** +1. Connect to the login node, as described [here](https://www.acrc.bris.ac.uk/protected/hpc-docs/connecting/index.html). For this your don't need X11 forwarding. +2. Once you are on the login node, do +```console +$ srun --account=MATHXXXXXX --partition=magma --mem=1gb --time=00:01:00 --pty bash -i +``` +to get an interactive session on one of our ringfenced nodes for quick interactive sessions. (No heavy jobs are allowed to be run on the login node, hence this command.) Notice that the above gives you a terminal for 1 minute, obviously change this to what time you need and save your work often as your terminal will be killed after the requested time. +:::{tip} +Without `--partition=magma` you are in the general BluePebble pool with far more nodes but usually longer waiting times, but this is the place to submit longer, heavy computations rather than our "magma" partition. +::: +3. In the interactive session do +```console +$ module load apps/maple +``` +(tab works for autocompletions). Then launch +```console +$ maple +``` +- **For graphical interface (GUI):** +1. Connect to the login node, as described [here](https://www.acrc.bris.ac.uk/protected/hpc-docs/connecting/index.html) including the X11 bits. +2. Once on the login node, do +```console +salloc --account=MATHXXXXXX --partition=magma --mem=1gb --time=00:01:00 +``` +again adjust the time from 1 minute to what you need, and please remove `--partition=magma` if you have a heavy job to run for hours or days. This will say something like +```console +salloc: Nodes bp1-compute169 are ready for job +``` +3. Do +```console +ssh -X bp1-compute169 +``` +(or whichever node was allocated to you in the previous step); tab completion works. Then +```console +$ module load apps/maple +``` +```console +$ xmaple +``` diff --git a/source/ssh_tunnel.md b/source/ssh_tunnel.md new file mode 100644 index 0000000..999d9a1 --- /dev/null +++ b/source/ssh_tunnel.md @@ -0,0 +1,39 @@ +--- +title: "An ssh alternative to VPN" +--- + +Below is an alternative way to connect to BlueCrystal or BluePebble from outside campus without the use of VPN. The specifics are for Linux but similar solutions seem to exist for Windows or Mac. We will make use of some nice features of ssh and the bastion server `seis.bris.ac.uk`. Everyone with a UoB username has access to this server, and it can be connected directly from outside. + +On your local machine, create or add to the file `~/.ssh/config` the following lines: +```console +Host bp1-login.acrc.bris.ac.uk + User [username] + ProxyCommand ssh [username]@seis.bris.ac.uk nc bp1-login.acrc.bris.ac.uk 22 + +Host bc4login.acrc.bris.ac.uk + User [username] + ProxyCommand ssh [username]@seis.bris.ac.uk nc bc4login.acrc.bris.ac.uk 22 +``` + +Once this is done, everything works as usual (except password is asked twice, once by `seis` and then by `bp1-login.acrc`/`bc4login.acrc`). E.g., +```console +$ ssh [username]@bp1-login.acrc.bris.ac.uk +``` +```console +$ ssh -X [username]@bp1-login.acrc.bris.ac.uk +``` +```console +$ sshfs [username]@bp1-login.acrc.bris.ac.uk:/home/[username]/ ~/local_mount_point/ +``` +```console +$ scp [file] [username]@bp1-login.acrc.bris.ac.uk:/home/[username] +``` +```console +$ rsync -[options] -e ssh [local dir]/ [username]@bp1-login.acrc.bris.ac.uk:/home/[username]/[remote dir]/ +``` +:::{tip} +An alternative to ProxyCommand is ProxyJump, see e.g., [here](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Proxies_and_Jump_Hosts#Passing_Through_One_or_More_Gateways_Using_ProxyJump). +::: +:::{tip} +You can use ssh keys, and possibly `ssh-agent`, to avoid entering your password several times. In this case **a strong passphrase for ssh keys and a time limit on ssh-agent is strongly advised**. +::: From 32059a9432fb81e8ec24b60339584d30dd5ea542 Mon Sep 17 00:00:00 2001 From: Marton Balazs Date: Wed, 16 Aug 2023 17:19:32 +0100 Subject: [PATCH 2/7] ... and the humans.txt file. --- humans.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/humans.txt b/humans.txt index f314cc7..15aaa3d 100644 --- a/humans.txt +++ b/humans.txt @@ -14,3 +14,9 @@ Role: PhD student Contributions: OpenFOAM user documentation GitHub: https://github.com/chen0mou0mou + + Name: Marton Balazs + Role: IT-rep for the School of Mathematics + Contributions: Interactive sessions and ssh tunneling documentation + GitHub: https://github.com/martonbalazs + Site: https://people.maths.bris.ac.uk/~mb13434/ From 57c69be6d81febff2da4d589d6aa814f01bbf2a2 Mon Sep 17 00:00:00 2001 From: Marton Balazs Date: Thu, 17 Aug 2023 11:29:36 +0100 Subject: [PATCH 3/7] Removed all references to ssh tunnelling. :-( --- humans.txt | 2 +- source/index.md | 1 - source/mathematics/interactive.md | 6 ++--- source/ssh_tunnel.md | 39 ------------------------------- 4 files changed, 4 insertions(+), 44 deletions(-) delete mode 100644 source/ssh_tunnel.md diff --git a/humans.txt b/humans.txt index 15aaa3d..6f6886b 100644 --- a/humans.txt +++ b/humans.txt @@ -17,6 +17,6 @@ Name: Marton Balazs Role: IT-rep for the School of Mathematics - Contributions: Interactive sessions and ssh tunneling documentation + Contributions: Interactive sessions documentation GitHub: https://github.com/martonbalazs Site: https://people.maths.bris.ac.uk/~mb13434/ diff --git a/source/index.md b/source/index.md index 078aa7e..6d50e9a 100644 --- a/source/index.md +++ b/source/index.md @@ -33,7 +33,6 @@ caption: "Contents:" --- engineering/index mathematics/interactive -ssh_tunnel ``` # Credits and licenses diff --git a/source/mathematics/interactive.md b/source/mathematics/interactive.md index 64d813c..ae37c69 100644 --- a/source/mathematics/interactive.md +++ b/source/mathematics/interactive.md @@ -34,7 +34,7 @@ $ maple 1. Connect to the login node, as described [here](https://www.acrc.bris.ac.uk/protected/hpc-docs/connecting/index.html) including the X11 bits. 2. Once on the login node, do ```console -salloc --account=MATHXXXXXX --partition=magma --mem=1gb --time=00:01:00 +$ salloc --account=MATHXXXXXX --partition=magma --mem=1gb --time=00:01:00 ``` again adjust the time from 1 minute to what you need, and please remove `--partition=magma` if you have a heavy job to run for hours or days. This will say something like ```console @@ -42,9 +42,9 @@ salloc: Nodes bp1-compute169 are ready for job ``` 3. Do ```console -ssh -X bp1-compute169 +$ ssh -X bp1-compute169 ``` -(or whichever node was allocated to you in the previous step); tab completion works. Then +(with whichever node was allocated to you in the previous step); tab completion works. Then ```console $ module load apps/maple ``` diff --git a/source/ssh_tunnel.md b/source/ssh_tunnel.md deleted file mode 100644 index 999d9a1..0000000 --- a/source/ssh_tunnel.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "An ssh alternative to VPN" ---- - -Below is an alternative way to connect to BlueCrystal or BluePebble from outside campus without the use of VPN. The specifics are for Linux but similar solutions seem to exist for Windows or Mac. We will make use of some nice features of ssh and the bastion server `seis.bris.ac.uk`. Everyone with a UoB username has access to this server, and it can be connected directly from outside. - -On your local machine, create or add to the file `~/.ssh/config` the following lines: -```console -Host bp1-login.acrc.bris.ac.uk - User [username] - ProxyCommand ssh [username]@seis.bris.ac.uk nc bp1-login.acrc.bris.ac.uk 22 - -Host bc4login.acrc.bris.ac.uk - User [username] - ProxyCommand ssh [username]@seis.bris.ac.uk nc bc4login.acrc.bris.ac.uk 22 -``` - -Once this is done, everything works as usual (except password is asked twice, once by `seis` and then by `bp1-login.acrc`/`bc4login.acrc`). E.g., -```console -$ ssh [username]@bp1-login.acrc.bris.ac.uk -``` -```console -$ ssh -X [username]@bp1-login.acrc.bris.ac.uk -``` -```console -$ sshfs [username]@bp1-login.acrc.bris.ac.uk:/home/[username]/ ~/local_mount_point/ -``` -```console -$ scp [file] [username]@bp1-login.acrc.bris.ac.uk:/home/[username] -``` -```console -$ rsync -[options] -e ssh [local dir]/ [username]@bp1-login.acrc.bris.ac.uk:/home/[username]/[remote dir]/ -``` -:::{tip} -An alternative to ProxyCommand is ProxyJump, see e.g., [here](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Proxies_and_Jump_Hosts#Passing_Through_One_or_More_Gateways_Using_ProxyJump). -::: -:::{tip} -You can use ssh keys, and possibly `ssh-agent`, to avoid entering your password several times. In this case **a strong passphrase for ssh keys and a time limit on ssh-agent is strongly advised**. -::: From 2b477cb9a496e20038e65fed535bc8ed0687f036 Mon Sep 17 00:00:00 2001 From: Marton Balazs Date: Mon, 18 Sep 2023 13:20:46 +0100 Subject: [PATCH 4/7] Implemented changes suggested by James. --- source/index.md | 2 +- source/mathematics/index.md | 12 +++++ source/mathematics/interactive.md | 80 +++++++++++++++++-------------- 3 files changed, 56 insertions(+), 38 deletions(-) create mode 100644 source/mathematics/index.md diff --git a/source/index.md b/source/index.md index 6d50e9a..3cade9f 100644 --- a/source/index.md +++ b/source/index.md @@ -32,7 +32,7 @@ maxdepth: 2 caption: "Contents:" --- engineering/index -mathematics/interactive +mathematics/index ``` # Credits and licenses diff --git a/source/mathematics/index.md b/source/mathematics/index.md new file mode 100644 index 0000000..4f3b66a --- /dev/null +++ b/source/mathematics/index.md @@ -0,0 +1,12 @@ +--- +title: "Mathematics" +--- + +```{toctree} +--- +includehidden: true +maxdepth: 1 +caption: "Contents:" +--- +interactive +``` diff --git a/source/mathematics/interactive.md b/source/mathematics/interactive.md index ae37c69..88ac74e 100644 --- a/source/mathematics/interactive.md +++ b/source/mathematics/interactive.md @@ -2,52 +2,58 @@ title: "Interactive sessions" --- -These are instructions on getting quick interactive sessions on BluePebble, assuming you already have login to this cluster and a project code. As this is primarily aimed for the School of Mathematics, we'll refer to the project code to be in the form MATHXXXXXX, but this could be in other format. +These are instructions on getting quick interactive sessions on BluePebble, assuming you already have login to this cluster and a project code. As this is primarily aimed for the School of Mathematics, we'll refer to the HPC project code to be in the form MATHXXXXXX, but this could be in a different format for other faculties/departments. -The School of Mathematics ringfenced a few of its nodes with the software Magma installed on them into the "magma" partition, and we also use this partition for quick interactive testing. +The School of Mathematics ringfenced a few of its nodes with the software [Magma](http://magma.maths.usyd.edu.au/magma/) installed on them into the "magma" partition, and we also use this partition for quick interactive testing. :::{important} -If you need to run something heavy that takes hours or days please remove any reference to the "magma" partition from the below. +The "magma" partition is for quick interactive testing besides making the software Magma available here. If you need to run a large or long-running job (e.g. that takes hours or days) that does not require the Magma package, please remove any reference to the "magma" partition from the below and use one of the other partitions on BluePebble, such as the default "compute" partition. ::: We use maple/xmaple as an example but comsol, magma, math/mathematica, etc work similarly. -- **If you don't need a graphical interface:** -1. Connect to the login node, as described [here](https://www.acrc.bris.ac.uk/protected/hpc-docs/connecting/index.html). For this your don't need X11 forwarding. +## If you don't need a graphical interface +1. Connect to the login node, as described [here](https://www.acrc.bris.ac.uk/protected/hpc-docs/connecting/index.html). For this you don't need X11 forwarding. 2. Once you are on the login node, do -```console -$ srun --account=MATHXXXXXX --partition=magma --mem=1gb --time=00:01:00 --pty bash -i -``` -to get an interactive session on one of our ringfenced nodes for quick interactive sessions. (No heavy jobs are allowed to be run on the login node, hence this command.) Notice that the above gives you a terminal for 1 minute, obviously change this to what time you need and save your work often as your terminal will be killed after the requested time. -:::{tip} -Without `--partition=magma` you are in the general BluePebble pool with far more nodes but usually longer waiting times, but this is the place to submit longer, heavy computations rather than our "magma" partition. -::: + ```console + $ srun --account=MATHXXXXXX --partition=magma --mem=1G --time=00:01:00 --pty bash -i + ``` + to get an interactive session on one of our ringfenced nodes for quick interactive sessions. Login nodes are intended for small scale interactive work. This command allows us to create an interactive session on a compute node for more intensive interactive work. Notice that the above gives you a terminal for 1 minute with 1 GB memory and the default number of CPU cores (1) -- please change this to specify the time and resources you need. Also, remember to save your work often as your terminal will be killed after the requested time. + :::{tip} + Without `--partition=magma` you are in the general BluePebble pool with far more nodes but usually longer waiting times, but this is the place to submit longer, heavy computations rather than our "magma" partition. + ::: 3. In the interactive session do -```console -$ module load apps/maple -``` -(tab works for autocompletions). Then launch -```console -$ maple -``` -- **For graphical interface (GUI):** + ```console + $ module load apps/maple + ``` + (tab works for autocompletions). Then launch + ```console + $ maple + ``` +## For graphical interface (GUI) 1. Connect to the login node, as described [here](https://www.acrc.bris.ac.uk/protected/hpc-docs/connecting/index.html) including the X11 bits. 2. Once on the login node, do -```console -$ salloc --account=MATHXXXXXX --partition=magma --mem=1gb --time=00:01:00 -``` -again adjust the time from 1 minute to what you need, and please remove `--partition=magma` if you have a heavy job to run for hours or days. This will say something like -```console -salloc: Nodes bp1-compute169 are ready for job -``` + ```console + $ salloc --account=MATHXXXXXX --partition=magma --mem=1G --time=00:01:00 + ``` + again adjust the command to request the time and resources to what you need, and please remove `--partition=magma` if you have a heavy job to run for hours or days. This will say something like + ```console + salloc: Pending job allocation 6434337 + salloc: job 6434337 queued and waiting for resources + salloc: job 6434337 has been allocated resources + salloc: Granted job allocation 6434337 + salloc: Waiting for resource configuration + salloc: Nodes bp1-compute169 are ready for job + ``` + In some cases you may need to wait for this allocation to start (e.g., if not using the "magma" partition). 3. Do -```console -$ ssh -X bp1-compute169 -``` -(with whichever node was allocated to you in the previous step); tab completion works. Then -```console -$ module load apps/maple -``` -```console -$ xmaple -``` + ```console + $ ssh -X bp1-compute169 + ``` + (using whichever node was allocated to you in the previous step); tab completion works here too. Then + ```console + $ module load apps/maple + ``` + ```console + $ xmaple + ``` From c8fb157b90b3af745e25a0b7ccd3794a4c85ba79 Mon Sep 17 00:00:00 2001 From: "James C. Womack" Date: Tue, 26 Sep 2023 13:14:23 +0100 Subject: [PATCH 5/7] Warning / caveat about interactive sessions Requested by HPC team --- source/mathematics/interactive.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/source/mathematics/interactive.md b/source/mathematics/interactive.md index 88ac74e..3a151aa 100644 --- a/source/mathematics/interactive.md +++ b/source/mathematics/interactive.md @@ -2,6 +2,15 @@ title: "Interactive sessions" --- +:::{warning} +Interactive sessions should only be used by users or groups who require interactive access to compute nodes and have access to sufficient resources (e.g. a private partition) to support interactive use. +Interactive sessions **do not** bypass the job scheduler and should not be expected to start immediately. + +The ACRC HPC team recommend the use of non-interactive batch jobs where possible, since these facilitate efficient job scheduling. The team will not provide support for interactive sessions when non-interactive batch jobs are a viable alternative. + +Jobs that waste cluster resources may be held or deleted, according to the [ACRC HPC usage policy](https://www.bristol.ac.uk/acrc/high-performance-computing/hpc-systems-policy/acrc-hpc-usage-policy/). This includes interactive jobs. Please ensure you use cluster resources responsibly and efficiently. +::: + These are instructions on getting quick interactive sessions on BluePebble, assuming you already have login to this cluster and a project code. As this is primarily aimed for the School of Mathematics, we'll refer to the HPC project code to be in the form MATHXXXXXX, but this could be in a different format for other faculties/departments. The School of Mathematics ringfenced a few of its nodes with the software [Magma](http://magma.maths.usyd.edu.au/magma/) installed on them into the "magma" partition, and we also use this partition for quick interactive testing. From ca7ea1ce543cccba47eb95f67c5b4d5ea6d7300b Mon Sep 17 00:00:00 2001 From: "James C. Womack" Date: Tue, 26 Sep 2023 16:00:39 +0100 Subject: [PATCH 6/7] Update warning / caveat about interactive sessions Based on feedback from HPC team --- source/mathematics/interactive.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/source/mathematics/interactive.md b/source/mathematics/interactive.md index 3a151aa..7b0a24f 100644 --- a/source/mathematics/interactive.md +++ b/source/mathematics/interactive.md @@ -3,12 +3,11 @@ title: "Interactive sessions" --- :::{warning} -Interactive sessions should only be used by users or groups who require interactive access to compute nodes and have access to sufficient resources (e.g. a private partition) to support interactive use. -Interactive sessions **do not** bypass the job scheduler and should not be expected to start immediately. +The ACRC HPC team recommend the use of non-interactive batch jobs where possible, since these facilitate efficient job scheduling. Interactive sessions on compute nodes are not supported on ACRC HPC systems unless submitted to private partitions, or following discussion with the [HPC team](mailto:hpc-help@bristol.ac.uk). -The ACRC HPC team recommend the use of non-interactive batch jobs where possible, since these facilitate efficient job scheduling. The team will not provide support for interactive sessions when non-interactive batch jobs are a viable alternative. +Interactive sessions **do not** bypass the job scheduler and should not be expected to start immediately. -Jobs that waste cluster resources may be held or deleted, according to the [ACRC HPC usage policy](https://www.bristol.ac.uk/acrc/high-performance-computing/hpc-systems-policy/acrc-hpc-usage-policy/). This includes interactive jobs. Please ensure you use cluster resources responsibly and efficiently. +Jobs that waste cluster resources may be held or deleted, in accordance with the [ACRC HPC usage policy](https://www.bristol.ac.uk/acrc/high-performance-computing/hpc-systems-policy/acrc-hpc-usage-policy/). This includes interactive jobs. Please ensure you use cluster resources responsibly and efficiently. ::: These are instructions on getting quick interactive sessions on BluePebble, assuming you already have login to this cluster and a project code. As this is primarily aimed for the School of Mathematics, we'll refer to the HPC project code to be in the form MATHXXXXXX, but this could be in a different format for other faculties/departments. From d637032fe27720ecc66dbe12504fe6b22ea71a52 Mon Sep 17 00:00:00 2001 From: "James C. Womack" Date: Tue, 26 Sep 2023 16:03:35 +0100 Subject: [PATCH 7/7] Update warning / caveat about interactive sessions Improve wording --- source/mathematics/interactive.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/mathematics/interactive.md b/source/mathematics/interactive.md index 7b0a24f..c5d2046 100644 --- a/source/mathematics/interactive.md +++ b/source/mathematics/interactive.md @@ -3,9 +3,9 @@ title: "Interactive sessions" --- :::{warning} -The ACRC HPC team recommend the use of non-interactive batch jobs where possible, since these facilitate efficient job scheduling. Interactive sessions on compute nodes are not supported on ACRC HPC systems unless submitted to private partitions, or following discussion with the [HPC team](mailto:hpc-help@bristol.ac.uk). +Interactive sessions on compute nodes are not supported on ACRC HPC systems unless submitted to private partitions, or following discussion with the [ACRC HPC team](mailto:hpc-help@bristol.ac.uk). -Interactive sessions **do not** bypass the job scheduler and should not be expected to start immediately. +The ACRC HPC team recommend the use of non-interactive batch jobs where possible, since these facilitate efficient job scheduling. Interactive sessions **do not** bypass the job scheduler and should not be expected to start immediately. Jobs that waste cluster resources may be held or deleted, in accordance with the [ACRC HPC usage policy](https://www.bristol.ac.uk/acrc/high-performance-computing/hpc-systems-policy/acrc-hpc-usage-policy/). This includes interactive jobs. Please ensure you use cluster resources responsibly and efficiently. :::