Merge pull request #2 from tkphd/default-snippets

Defaults

Author: ocaisa

MAINTENANCE.md

@@ -1,4 +1,6 @@
-# Site Structure and Maintenance
+---
+title: "Site Structure and Maintenance"
+---
 
 This site depends strongly on GitHub infrastructure, and a number of
 operational decisions have been made during the development process

config.yaml

@@ -20,7 +20,7 @@ carpentry: 'cp'
 title: 'Introduction to High-Performance Computing'
 
 # Date the lesson was created (YYYY-MM-DD, this is empty by default)
-created: 2017-03-24 
+created: 2017-03-24
 
 # Comma-separated list of keywords for the lesson
 keywords: 'software, data, lesson, The Carpentries'
@@ -64,29 +64,26 @@ contact: '[email protected]'
 # - another-learner.md
 
 # Order of episodes in your lesson
-episodes: 
-- 10-hpc-intro.md
-- 11-connecting.md
-- 12-cluster.md
-- 12-epcc-cluster.Rmd
-- 13-scheduler.md
-- 13-hpcc-scheduler.Rmd
-- 13-epcc-scheduler.Rmd
-- 14-environment-variables.md
-- 15-modules.md
-- 16-transferring-files.md
-- 17-parallel.md
-- 18-resources.md
-- 19-responsibility.md
+episodes:
+  - 10-hpc-intro.md
+  - 11-connecting.Rmd
+  - 12-cluster.Rmd
+  - 13-scheduler.Rmd
+  - 14-environment-variables.Rmd
+  - 15-modules.Rmd
+  - 16-transferring-files.Rmd
+  - 17-parallel.Rmd
+  - 18-resources.Rmd
+  - 19-responsibility.Rmd
 
 # Information for Learners
-learners: 
+learners:
 
 # Information for Instructors
-instructors: 
+instructors:
 
 # Learner Profiles
-profiles: 
+profiles:
 
 # Customisation ---------------------------------------------
 #

episodes/10-hpc-intro.md

@@ -54,7 +54,7 @@ problems in parallel**.
 
 ## Jargon Busting Presentation
 
-Open the [HPC Jargon Buster]({{ site.url }}files/jargon#p1)
+Open the [HPC Jargon Buster](../files/jargon#p1)
 in a new tab. To present the content, press `C` to open a **c**lone in a
 separate window, then press `P` to toggle **p**resentation mode.
 

episodes/11-connecting.md episodes/11-connecting.Rmdepisodes/11-connecting.md renamed to episodes/11-connecting.Rmd

@@ -17,6 +17,11 @@ exercises: 10
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
+```{r, echo=FALSE}
+# Source the external configuration script
+source("load_config.R")
+```
+
 ## Secure Connections
 
 The first step in using a cluster is to establish a connection from our laptop
@@ -56,7 +61,7 @@ When logging in to a laptop, tablet, or other personal device, a username,
 password, or pattern are normally required to prevent unauthorized access. In
 these situations, the likelihood of somebody else intercepting your password is
 low, since logging your keystrokes requires a malicious exploit or physical
-access. For systems like {{ site.remote.host }} running an SSH server, anybody
+access. For systems like ``r config$remote$host`` running an SSH server, anybody
 on the network can log in, or try to. Since usernames are often public or easy
 to guess, your password is often the weakest link in the security chain. Many
 clusters therefore forbid password-based login, requiring instead that you
@@ -80,16 +85,18 @@ In this section you will create a pair of SSH keys:
 - a private key which you keep on your own computer, and
 - a public key which can be placed on any remote system you will access.
 
-> ## Private keys are your secure digital passport
-> 
-> A private key that is visible to anyone but you should be considered
-> compromised, and must be destroyed. This includes having improper permissions
-> on the directory it (or a copy) is stored in, traversing any network that is
-> not secure (encrypted), attachment on unencrypted email, and even displaying
-> the key on your terminal window.
-> 
-> Protect this key as if it unlocks your front door. In many ways, it does.
-> {: .caution}
+:::::::::::::::::::::::::::::::::::::::::  caution
+
+## Private keys are your secure digital passport
+
+A private key that is visible to anyone but you should be considered
+compromised, and must be destroyed. This includes having improper permissions
+on the directory it (or a copy) is stored in, traversing any network that is
+not secure (encrypted), attachment on unencrypted email, and even displaying
+the key on your terminal window.
+
+Protect this key as if it unlocks your front door. In many ways, it does.
+::::::::::::::::::::::::::::::::::::::::::::::::::
 
 Regardless of the software or operating system you use, *please* choose a
 strong password or passphrase to act as another layer of protection for your
@@ -111,8 +118,6 @@ common approaches to this:
 3. Nothing is *less* secure than a private key with no password. If you
   skipped password entry by accident, go back and generate a new key pair
   *with* a strong password.
-  
-
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 #### SSH Keys on Linux, Mac, MobaXterm, and Windows Subsystem for Linux
@@ -121,7 +126,7 @@ Once you have opened a terminal, check for existing SSH keys and filenames
 since existing SSH keys are overwritten.
 
 ```bash
-{{ site.local.prompt }} ls ~/.ssh/
+`r config$local$prompt` ls ~/.ssh/
 ```
 
 If `~/.ssh/id_ed25519` already exists, you will need to specify
@@ -140,7 +145,7 @@ produce a stronger key than the `ssh-keygen` default by invoking these flags:
   extension added.
 
 ```bash
-{{ site.local.prompt }} ssh-keygen -a 100 -f ~/.ssh/id_ed25519 -t ed25519
+`r config$local$prompt` ssh-keygen -a 100 -f ~/.ssh/id_ed25519 -t ed25519
 ```
 
 When prompted, enter a strong password with the
@@ -165,7 +170,7 @@ If key generation failed because ed25519 is not available, try using the older
 check for an existing key:
 
 ```bash
-{{ site.local.prompt }} ls ~/.ssh/
+`r config$local$prompt` ls ~/.ssh/
 ```
 
 If `~/.ssh/id_rsa` already exists, you will need to specify choose a different
@@ -177,7 +182,7 @@ name for the new key-pair. Generate it as above, with the following extra flags:
   rather than PEM.
 
 ```bash
-{{ site.local.prompt }} ssh-keygen -a 100 -b 4096 -f ~/.ssh/id_rsa -o -t rsa
+`r config$local$prompt` ssh-keygen -a 100 -b 4096 -f ~/.ssh/id_rsa -o -t rsa
 ```
 
 When prompted, enter a strong password with the
@@ -233,7 +238,7 @@ type it in again.
 Open your terminal application and check if an agent is running:
 
 ```bash
-{{ site.local.prompt }} ssh-add -l
+`r config$local$prompt` ssh-add -l
 ```
 
 - If you get an error like this one,
@@ -245,7 +250,7 @@ Open your terminal application and check if an agent is running:
   ... then you need to launch the agent as follows:
 
   ```bash
-  {{ site.local.prompt }} eval $(ssh-agent)
+  `r config$local$prompt` eval $(ssh-agent)
   ```
 
   :::::::::::::::::::::::::::::::::::::::::  callout
@@ -258,7 +263,7 @@ Open your terminal application and check if an agent is running:
   shell commands that can be used to reach it -- but *does not execute them!*
 
   ```bash
-  {{ site.local.prompt }} ssh-agent
+  `r config$local$prompt` ssh-agent
   ```
 
   ```output
@@ -283,7 +288,7 @@ Open your terminal application and check if an agent is running:
 Add your key to the agent, with session expiration after 8 hours:
 
 ```bash
-{{ site.local.prompt }} ssh-add -t 8h ~/.ssh/id_ed25519
+`r config$local$prompt` ssh-add -t 8h ~/.ssh/id_ed25519
 ```
 
 ```output
@@ -302,27 +307,40 @@ See the [PuTTY documentation][putty-agent].
 
 ### Transfer Your Public Key
 
-{% if site.remote.portal %}
-Visit [{{ site.remote.portal }}]({{ site.remote.portal }}) to upload your SSH
-public key. (Remember, it's the one ending in `.pub`!)
-
-{% else %}
-Use the **s**ecure **c**o**p**y tool to send your public key to the cluster.
-
-```bash
-{{ site.local.prompt }} scp ~/.ssh/id_ed25519.pub {{ site.remote.user }}@{{ site.remote.login }}:~/
+```{r, eval=is.null(config$remote$portal), echo=FALSE, results="asis"}
+cat(
+    paste(
+        "```bash\n",
+        config$local$prompt,
+        " scp ~/.ssh/id_ed25519.pub ",
+        config$remote$user,
+        "@",
+        config$remote$login,
+        ":~/\n```",
+        sep="")
+)
 ```
 
-{% endif %}
+```{r, eval=!is.null(config$remote$portal), echo=FALSE, results="asis"}
+cat(
+    paste(
+        "Visit [",
+        config$remote$portal,
+        "](",
+        config$remote$portal,
+        ") to upload your SSH public key. (Remember, it's the one ending in `.pub`!)",
+        sep="")
+)
+```
 
 ## Log In to the Cluster
 
 Go ahead and open your terminal or graphical SSH client, then log in to the
-cluster. Replace `{{ site.remote.user }}` with your username or the one
+cluster. Replace ``r config$remote$user`` with your username or the one
 supplied by the instructors.
 
 ```bash
-{{ site.local.prompt }} ssh {{ site.remote.user }}@{{ site.remote.login }}
+`r config$local$prompt` ssh `r config$remote$user`@`r config$remote$login`
 ```
 
 You may be asked for your password. Watch out: the characters you type after
@@ -340,9 +358,9 @@ connected to the local system and the remote system will typically be different
 for every user. We still need to indicate which system we are entering commands
 on though so we will adopt the following convention:
 
-- `{{ site.local.prompt }}` when the command is to be entered on a terminal
+- ``r config$local$prompt`` when the command is to be entered on a terminal
   connected to your local computer
-- `{{ site.remote.prompt }}` when the command is to be entered on a
+- ``r config$remote$prompt`` when the command is to be entered on a
   terminal connected to the remote system
 - `$` when it really doesn't matter which system the terminal is connected to.
 
@@ -356,28 +374,28 @@ computer we are logged onto can be checked with the `hostname` command. (You
 may also notice that the current hostname is also part of our prompt!)
 
 ```bash
-{{ site.remote.prompt }} hostname
+`r config$remote$prompt` hostname
 ```
 
 ```output
-{{ site.remote.host }}
+`r config$remote$host`
 ```
 
 So, we're definitely on the remote machine. Next, let's find out where we are
 by running `pwd` to **p**rint the **w**orking **d**irectory.
 
 ```bash
-{{ site.remote.prompt }} pwd
+`r config$remote$prompt` pwd
 ```
 
 ```output
-{{ site.remote.homedir }}/{{ site.remote.user }}
+`r config$remote$homedir`/`r config$remote$user`
 ```
 
 Great, we know where we are! Let's see what's in our current directory:
 
 ```bash
-{{ site.remote.prompt }} ls
+`r config$remote$prompt` ls
 ```
 
 ```output
@@ -390,7 +408,7 @@ other filesystems. If they did not, your home directory may appear empty. To
 double-check, include hidden files in your directory listing:
 
 ```bash
-{{ site.remote.prompt }} ls -a
+`r config$remote$prompt` ls -a
 ```
 
 ```output
@@ -399,13 +417,11 @@ double-check, include hidden files in your directory listing:
 ```
 
 In the first column, `.` is a reference to the current directory and `..` a
-reference to its parent (`{{ site.remote.homedir }}`). You may or may not see
+reference to its parent (``r config$remote$homedir``). You may or may not see
 the other files, or files like them: `.bashrc` is a shell configuration file,
 which you can edit with your preferences; and `.ssh` is a directory storing SSH
 keys and a record of authorized connections.
 
-{% unless site.remote.portal %}
-
 ### Install Your SSH Key
 
 :::::::::::::::::::::::::::::::::::::::::  callout
@@ -416,8 +432,6 @@ Policies and practices for handling SSH keys vary between HPC clusters:
 follow any guidance provided by the cluster administrators or
 documentation. In particular, if there is an online portal for managing SSH
 keys, use that instead of the directions outlined here.
-
-
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 If you transferred your SSH public key with `scp`, you should see
@@ -428,32 +442,28 @@ If the `.ssh` folder was not listed above, then it does not yet
 exist: create it.
 
 ```bash
-{{ site.remote.prompt }} mkdir ~/.ssh
+`r config$remote$prompt` mkdir ~/.ssh
 ```
 
 Now, use `cat` to print your public key, but redirect the output, appending it
 to the `authorized_keys` file:
 
 ```bash
-{{ site.remote.prompt }} cat ~/id_ed25519.pub >> ~/.ssh/authorized_keys
+`r config$remote$prompt` cat ~/id_ed25519.pub >> ~/.ssh/authorized_keys
 ```
 
 That's all! Disconnect, then try to log back into the remote: if your key and
 agent have been configured correctly, you should not be prompted for the
 password for your SSH key.
 
 ```bash
-{{ site.remote.prompt }} logout
+`r config$remote$prompt` logout
 ```
 
 ```bash
-{{ site.local.prompt }} ssh {{ site.remote.user }}@{{ site.remote.login }}
+`r config$local$prompt` ssh `r config$remote$user`@`r config$remote$login`
 ```
 
-{% endunless %}
-
-
-
 [gh-ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
 [keepass]: https://keepass.info
 [bitwarden]: https://bitwarden.com
@@ -463,14 +473,12 @@ password for your SSH key.
 [ssh-agent]: https://www.ssh.com/academy/ssh/agent
 [putty-agent]: https://tartarus.org/~simon/putty-prerel-snapshots/htmldoc/Chapter9.html#pageant
 
-
 :::::::::::::::::::::::::::::::::::::::: keypoints
 
 - An HPC system is a set of networked machines.
 - HPC systems typically provide login nodes and a set of worker nodes.
-- The resources found on independent (worker) nodes can vary in volume and type (amount of RAM, processor architecture, availability of network mounted filesystems, etc.).
+- The resources found on independent (worker) nodes can vary in volume and type
+  (amount of RAM, processor architecture, availability of network mounted
+  filesystems, etc.).
 - Files saved on one node are available on all nodes.
-
 ::::::::::::::::::::::::::::::::::::::::::::::::::
-
-