cleanup: remove redundant whitespace and migrate to callouts

redbrick · Jan 30, 2024 · 75523ae · 75523ae
1 parent 4401438
commit 75523ae
Show file tree

Hide file tree

Showing 9 changed files with 91 additions and 156 deletions.
diff --git a/docs/aperture/about.md b/docs/aperture/about.md
@@ -1,18 +1,18 @@
+
 # About Aperture
 
-Aperture is Redbrick's fleet of hardware that was installed in May 2022 by `distro`, `pints`, `skins`, `cawnj`, `ymacomp`
-and `arkues`.
+Aperture is Redbrick's fleet of hardware that was installed in May 2022 by `distro`, `pints`, `skins`, `cawnj`, `ymacomp` and `arkues`.
 
 It consists of:
 
-- 3x Dell R6515
+- 3x Dell R6515 - [`glados`](/hosts/aperture/glados), [`wheatley`](/hosts/aperture/wheatley), [`chell`](/hosts/aperture/chell)
 
-    | CPU                                       | RAM                               | Storage                          |
-    | ----                                      | ----                              | -------                          |
-    | AMD 7302P 3GHz, 16C/32T, 128M, 155W, 3200 | 2x 16GB RDIMM, 3200MT/s Dual Rank | 4x 2TB SATA HDDs (hardware RAID) |
+ |                    CPU                    |                RAM                |             Storage              |
+ |:-----------------------------------------:|:---------------------------------:|:--------------------------------:|
+ | AMD 7302P 3GHz, 16C/32T, 128M, 155W, 3200 | 2x 16GB RDIMM, 3200MT/s Dual Rank | 4x 2TB SATA HDDs (hardware RAID) |
 
-- 2x Ubiquiti USW Pro
-- 1x Ubiquiti UDM Pro
+- 2x Ubiquiti USW Pro - `rivendell`, `isengard`
+- 1x Ubiquiti UDM Pro - `mordor`
 
 ## Servers
 
@@ -26,39 +26,36 @@ The firewall is called [`mordor`](firewall.md), and the two 24-port switches are
 
 The IP address range for the [`aperture`](index.md) subnet is `10.10.0.0/24`, with `10.10.0.0/16` being used for user VMs.
 
-| Hostname    | Internal Address | External Address | Purpose  |
-| --------    | ----------       | --------         | -------  |
-| `mordor`    | 10.10.0.1        | N/A              | Firewall |
-| `rivendell` | 10.10.0.2        | N/A              | Switch   |
-| `isengard`  | 10.10.0.3        | N/A              | Switch   |
-| `glados`    | 10.10.0.4        | 136.206.16.4     | Server   |
-| `wheatley`  | 10.10.0.5        | 136.206.16.5     | Server   |
-| `chell`     | 10.10.0.6        | 136.206.16.6     | Server   |
+|  Hostname   | Internal Address | External Address | Purpose  |
+|:-----------:|:----------------:|:----------------:|:--------:|
+|  `mordor`   |    10.10.0.1     |       N/A        | Firewall |
+| `rivendell` |    10.10.0.2     |       N/A        |  Switch  |
+| `isengard`  |    10.10.0.3     |       N/A        |  Switch  |
+|  `glados`   |    10.10.0.4     |   136.206.16.4   |  Server  |
+| `wheatley`  |    10.10.0.5     |   136.206.16.5   |  Server  |
+|   `chell`   |    10.10.0.6     |   136.206.16.6   |  Server  |
 
-!!! note
-    **Blue** cables are used for **production network**.
+> [!NOTE] Note!
+> **Blue** cables are used for **production network**.
 
 ## KVM
 
 `nexus` is the name of the KVM switch. It's internal IP address is `10.10.0.10`.
 
 [`glados`](../hosts/aperture/glados.md) is connected on port 1, [`wheatley`](../hosts/aperture/wheatley.md) on port 2, and [`chell`](../hosts/aperture/chell.md) on port 3.
 
-!!! note
-    **Yellow** cables are used for **KVM network**.
+> [!WARNING] Note!
+> **Yellow** cables are used for **KVM network**.
 
 ## IDRAC
 
 The new servers are all equipped with IDRACs. These still need to be configured.
 
-!!! note
-    **Red** cables are used for **IDRAC network**.
+> [!ERROR] Note!
+> **Red** cables are used for **IDRAC network**.
 
 ## [Images (click me)](images.md)
 
-## Switching from the old network to the new
+## Switching from the Old Network to the New
 
-We have two address ranges that come in on a single redundant link, so we're exchanging that redundant link for two
-separate links, each taking responsibility for an address range (`136.26.15.0/24` and `136.206.16.0/24`). So we're surrendering
-redundancy to gain uptime/connectivity during the switchover only. Once the new servers are production ready, we can
-recombine the link to regain the redundancy.
+We have two address ranges that come in on a single redundant link, so we're exchanging that redundant link for two separate links, each taking responsibility for an address range (`136.26.15.0/24` and `136.206.16.0/24`). So we're surrendering redundancy to gain uptime/connectivity during the switchover only. Once the new servers are production ready, we can recombine the link to regain the redundancy.
diff --git a/docs/aperture/ansible.md b/docs/aperture/ansible.md
@@ -1,7 +1,6 @@
 # Ansible
 
-Redbrick uses ansible to manage its infrastructure. This document describes the procedures and some tips to get the most
-out of it.
+Redbrick uses ansible to manage its infrastructure. This document describes the procedures and some tips to get the most out of it.
 
 ## Getting started
 
@@ -15,8 +14,7 @@ pip install ansible
 
 ### Add an SSH key
 
-Ansible uses ssh to connect to the remote hosts. You'll need to set up your ssh key so that you can connect to the hosts
-without constant prompts for passwords.
+Ansible uses ssh to connect to the remote hosts. You'll need to set up your ssh key so that you can connect to the hosts without constant prompts for passwords.
 
 ### Create a hosts file
 
@@ -44,8 +42,7 @@ This should connect to all the hosts in the `aperture` group, and run the `ping`
 
 ## Playbooks
 
-Ansible playbooks are a set of instructions for ansible to run. They're written in YAML, and are usually stored in a file
-called `playbook.yml`.
+Ansible playbooks are a set of instructions for ansible to run. They're written in YAML, and are usually stored in a file called `playbook.yml`.
 
 ### Writing a playbook
 
@@ -70,8 +67,7 @@ Ansible playbooks are written in YAML. The basic structure is:
         state: present
 ```
 
-This playbook will connect to all the hosts in the `aperture` group, and run the `apt` module with the `name` and `state`
-options.
+This playbook will connect to all the hosts in the `aperture` group, and run the `apt` module with the `name` and `state` options.
 
 ### Running a playbook
 
@@ -81,8 +77,7 @@ ansible-playbook playbook.yml -i hosts
 
 ## More Information
 
-Redbrick's ansible configuration is stored in the [ansible](https://github.com/redbrick/ansible) repository. There's
-some more documentation there on each playbook.
+Redbrick's ansible configuration is stored in the [ansible](https://github.com/redbrick/nomad/tree/master/ansible) folder in the `redbrick/nomad` repository. There's some more documentation there on each playbook.
 
 Ansible's documentation is available [here](https://docs.ansible.com/ansible/latest/index.html).
 

diff --git a/docs/aperture/firewall.md b/docs/aperture/firewall.md
@@ -4,7 +4,8 @@
 
 ## Setup
 
-The firewall is set up using the personal setup type, using the [email protected] account (stored in pwsafe
+The firewall is set up using the personal setup type, using the [email protected] account (stored in `pwsafe`
+
 2FA is stored on the same device as the Github 2FA code.
 
 ### Automatic Updates
@@ -17,44 +18,34 @@ We have a 10 GB/s link to DCU's core.
 
 ### Users
 
-The current elected admins should all have access to the rbadmin account on the firewall. Rootholders **should not** have
-access to the firewall unless they are explicity granted access.
+The current elected admins should all have access to the rbadmin account on the firewall. Rootholders **should not** have access to the firewall unless they are explicity granted access.
 
-The owner account of the unifi equipment is `rbadmins` (email: [email protected]) with the password stored
-in pwsafe under `unifi`.
+The owner account of the unifi equipment is `rbadmins` (email: [email protected]) with the password stored in pwsafe under `unifi`.
 
-There is a "super admin" account that can be used for **local access only**, details are stored in pwsafe under
-`udmpro-super-admin`.
+There is a "super admin" account that can be used for **local access only**, details are stored in pwsafe under `udmpro-super-admin`.
 
 ### Updates
 
-The UDM Pro should be kept up to date at all times using the web interface. Please ensure there are no breaking changes before
-updating.
+The UDM Pro should be kept up to date at all times using the web interface. Please ensure there are no breaking changes before updating.
 
-!!! error
-    ### AUTO UPDATES SHOULD NEVER BE ENABLED!
 
-    This is to prevent a bad update from breaking the UDM Pro and thus the entire network.
-    If you are confident that Unifi can produce stable updates, you may turn it on, however please let the next admins 
-    know that you have done this (and update these docs with a comment!).
+> [!ERROR] AUTO UPDATES SHOULD NEVER BE ENABLED!
+> This is to prevent a bad update from breaking the UDM Pro and thus the entire network. 
+> If you are confident that Unifi can produce stable updates, you may turn it on, however please let the next admins know that you have done this (and update these docs with a comment!).
 
 ### Advanced Settings
 
-SSH is enabled to allow for rollbacks in case of a bad update (I warned you!).
+SSH is enabled to allow for rollbacks in case of a bad update *(I warned you!)*.
 
-Remote access is disabled as it should not be needed, the admin vpn should provide enough access for you.
-If it is enabled in future, please update these docs with your reasons.
+Remote access is disabled as it should not be needed, the admin [`VPN`](./vpn.md) should provide enough access for you. If it is enabled in future, please update these docs with your reasons.
 
 ### Backups
 
-Backups are configured to run every week at 1am on a Sunday. 20 backups are stored at a time, therefore storing 20 weeks
-of configuration. This should be plenty of time to recover from a bad configuration change.
+Backups are configured to run every week at 1am on a Sunday. 20 backups are stored at a time, therefore storing 20 weeks of configuration. This should be plenty of time to recover from a bad configuration change.
 
 ## External Addresses
 
-`Mordor` is natted when it accesses the Internet. This is because the link address between it and DCU is on a private address.
-This natting is used *only* for the UDM pro device itself, not for the 136.206.16.0/24 network, and is to allow the UDM
-box itself to access the Internet.
+`Mordor` is NATted when it accesses the Internet. This is because the link address between it and DCU is on a private address.
+This NATting is used *only* for the UDM pro device itself, not for the `136.206.16.0/24` network, and is to allow the UDM box itself to access the Internet.
 
-The 136.206.16.0/24 network is routed down to the UDM pro box, within the DCU network. Essentially there is a route in
-DCU's network that says "if you want to access 136.206.16.0/24 go to mordor".
+The `136.206.16.0/24` network is routed down to the UDM pro box, within the DCU network. Essentially there is a route in DCU's network that says "if you want to access `136.206.16.0/24` go to `mordor`".
diff --git a/docs/aperture/icecast.md b/docs/aperture/icecast.md
@@ -10,33 +10,32 @@ The configuration file for icecast is located in the [nomad config repo](https:/
 
 It should just be a case of running `nomad job plan clubs-socs/dcufm.hcl` to plan and run the job.
 
-!!!note
-    The job may bind to either the internal or external address. Ensure that if you make a change to the config, you
-    inform DCUfm that they may need to switch which server they use.
+
+> [!NOTE] Note
+> The job may bind to either the internal or external address. Ensure that if you make a change to the config, you inform DCUfm that they may need to switch which server they use.
 
 ## Streaming to Icecast
 
 DCUfm use [butt](https://danielnoethen.de/butt/) on a desktop in their studio to stream to Icecast.
 
-The desktop must be connected to the VPN to ensure the stream stays up, and traefik doesn't reset the connection every
-10 seconds. The current icecast configuration for the server is 10.10.0.5:2333 or 136.206.16.5:2333 (see above note).
+The desktop must be connected to the VPN to ensure the stream stays up, and traefik doesn't reset the connection every 10 seconds. The current icecast configuration for the server is `10.10.0.5:2333` or `136.206.16.5:2333` (see above note).
 Read more about it in [this issue](https://github.com/redbrick/issue-tracker/issues/4).
 
 A shortcut to the VPN is available on the desktop (change a shortcut to the binary to include `--connect profile.ovpn`.
 See [here](https://munkjensen.net/wiki/index.php/Connect_OpenVPN_on_Windows_startup)).
 
 ## DCUfm Cheat Sheet
 
-This is a cheat sheet for DCUfm to help them stream to icecast.
+This is a cheat sheet for DCUfm to help them stream to `icecast`.
 
 ### Connecting to the VPN
 
-You'll need to connect to the Redbrick VPN to stream to icecast. You can do this by double clicking the shortcut on the desktop.
+You'll need to connect to the Redbrick VPN to stream to `icecast`. You can do this by double clicking the shortcut on the desktop.
+
 You'll then need to go to bottom right corner of the screen and right click this icon:
 ![Disconnected OpenVPN icon](https://i.dbyte.xyz/2022-11-I9.png)
 
-A popup will appear, click connect. This will connect you to the VPN. It may take a second, but a window will pop up with
-a lot of text. The VPN will connect and then it'll close.
+A popup will appear, click connect. This will connect you to the VPN. It may take a second, but a window will pop up with a lot of text. The VPN will connect and then it'll close.
 ![Connect to OpenVPN](https://i.dbyte.xyz/2022-11-AV.png)
 
 You should end up with an icon like this:
@@ -46,23 +45,17 @@ You're now connected to the VPN.
 
 ### Connecting to Icecast
 
-You'll need to connect to icecast to stream to it. BUTT is the software we use to stream to icecast. You'll also find this
-on the desktop. Once its open, (and you're connected to the VPN), press the small "play" button in the top left corner. This
-will start your stream to the server.
+You'll need to connect to `icecast` to stream to it. BUTT is the software we use to stream to `icecast`. You'll also find this on the desktop. Once its open, (and you're connected to the VPN), press the small "play" button in the top left corner. This will start your stream to the server.
+
+The username and password should already be configured in the software. If not, ask a [redbrick sysadmin](../contact.md) for the login details.
 
-The username and password should already be configured in the software. If not, ask a [redbrick sysadmin](../contact.md)
-for the login details.
 
-!!! warning
-    If you find that butt is not connecting, then you may need to switch which server you're connecting to. To do this,
-    go to settings, and then the "Main" tab. In the dropdown, select either DCUfm 1 or DCUfm 2 (try both,
-    one will definitely work).
+> [!WARNING] Warning!
+> If you find that butt is not connecting, then you may need to switch which server you're connecting to. To do this, go to settings, and then the "Main" tab. In the dropdown, select either DCUfm 1 or DCUfm 2 (try both, one will definitely work).
 
 ### Saving your stream
 
-Your stream will be saved automatically onto the desktop into a folder called `Recordings YYYY` (where `YYYY` is the
-current year), with the date and time of the recording, and the format `.mp3`. Take this file with you (via a USB or similar)
-if you want to keep it for later, it will not be kept on the desktop for long!
+Your stream will be saved automatically onto the desktop into a folder called `Recordings YYYY` (where `YYYY` is the current year), with the date and time of the recording, and the format `.mp3`. Take this file with you (via a USB or similar) if you want to keep it for later, it will not be kept on the desktop for long!
 
 ### Further Information
 

diff --git a/docs/aperture/index.md b/docs/aperture/index.md
@@ -1,6 +1,6 @@
 # Aperture
 
-### What is aperture?
+## What is aperture?
 It's nothing to do with cameras. See [about](about.md) for more information on the hardware.
 
 ## New Admins

diff --git a/docs/aperture/vpn.md b/docs/aperture/vpn.md
@@ -1,13 +1,12 @@
 # Admin VPN
 
-The admin VPN is set up to allow admins to access the network from outside of DCU, giving them an IP address on the
-internal network for troubleshooting, testing and integrating.
+The admin VPN is set up to allow admins to access the network from outside of DCU, giving them an IP address on the internal network for troubleshooting, testing and integrating.
 
 If you just want to create a new client configuration, go here: [adding a new client](#adding-a-new-client)
 
 ## Setup
 
-Installed OpenVPN using [this script](https://github.com/Nyr/openvpn-install) on Glados.
+Installed OpenVPN using [this script](https://github.com/Nyr/openvpn-install) on [`glados`](../hosts/aperture/glados.md).
 
 ## Adding a new client
 
@@ -33,5 +32,4 @@ You will be prompted to revoke a client, enter the name of the client you want t
 
 ## Connecting to the VPN
 
-To connect to the VPN, you will need to download the client configuration file from [glados](../hosts/aperture/glados.md) and then import it into your
-OpenVPN client.
+To connect to the VPN, you will need to download the client configuration file from [glados](../hosts/aperture/glados.md) and then import it into your OpenVPN client.
diff --git a/docs/hosts/index.md b/docs/hosts/index.md
@@ -7,10 +7,13 @@
 ## [NixOS](../procedures/nixos.md) Boxes
 - [**hardcase**](nix/hardcase.md)
 - [**motherlode**](nix/motherlode.md)
-- [icarus](nix/icarus.md)
+- [**icarus**](nix/icarus.md)
+
+- [**paphos**](paphos.md)
+- [**zeus**](zeus.md)
 
 ## [Aperture](../aperture/index.md)
 - [**glados**](aperture/glados.md)
 - [**wheatley**](aperture/wheatley.md)
 - [**chell**](aperture/chell.md)
-- [**johnson**](aperture/johnson.md)
+- [**johnson**](aperture/johnson.md)
diff --git a/docs/procedures/handover.md b/docs/procedures/handover.md
@@ -4,9 +4,7 @@ When a new committee is elected, there are many things to hand over. This is a l
 
 ## Passwords
 
-All passwords should be rotated as soon as possible. This is to ensure that passwords are rotated, and that the old
-committee can no longer access Redbrick using the old passwords. The passwords are stored in Bitwarden, and the master
-password should be rotated first and foremost.
+All passwords should be rotated as soon as possible. This is to ensure that passwords are rotated, and that the old committee can no longer access Redbrick using the old passwords. The passwords are stored in Bitwarden, and the master password should be rotated first and foremost.
 
 ## 2-Factor Authentication