Bath Wiki - User contributions [en-gb]

StrongSwan VPN on Linux

2026-06-19T17:24:26Z

Pcs47: Move strongswan package warning higher up.

The GlobalProtect VPN has been decommissioned by DDaT. Unfortunately, this was the only easily working VPN on Linux. The new strongSwan VPN ''should'' just work on popular distros like Mint with the instructions given at https://connect.bath.ac.uk/. Unfortunately, for the rest of us, it often does not “just work”.

This page contains troubleshooting steps for if a basic connection doesn’t work.

= Connect instructions =

'''Before starting''', make sure you have Microsoft Authenticator enabled. Then, navigate to https://mysignins.microsoft.com/security-info. Make sure that the sign-in method fallback is set to "Microsoft Authenticator - notification" (via the "Change" link). This is something not listed on https://connect.bath.ac.uk and may cause later steps to fail.

'''If you're on Ubuntu''', you should also install the following packages that aren't mentioned by the DDaT instructions: <code>libstrongswan-standard-plugins</code> and <code>libstrongswan-extra-plugins</code>.

You should then follow the instructions at https://connect.bath.ac.uk.

The instructions give the following troubleshooting advice:

<blockquote>You may also need to run the command below if you find DNS lookups fail for some university resources:

<syntaxhighlight lang="sh">sudo ln -sfv /run/systemd/resolve/resolv.conf /etc/resolv.conf</syntaxhighlight>
</blockquote>

Though, we’re not sure this is a great idea, and it will not work on any distro. Ubuntu is currently the only distro actively supported by DDaT, though they have been known to respond to tickets for other distros.

== What to expect ==

Now that you’ve followed the university’s instructions, you should be able to connect using the NetworkManager GUI, it should ask you for a username and password (if you haven’t already supplied the username in the configuration), put your university credentials in (the username should be '''without''' the <code>@bath.ac.uk</code>), and you should get a Microsoft authenticator request via the app.

To confirm you are connected to the university VPN correctly, check you can visit any internal site. For example, go to https://2024-25.moodle-archive.bath.ac.uk/. If the page loads, you’re connected! If not, you’ll need to do some troubleshooting.

= Troubleshooting =

First, wipe the slate clean (delete the connection), update your system, and reboot. Once you’ve done that, try again. This should narrow the chances of your system being in some weird state. If it works, great! If not, it’s time to get troubleshooting.

Some of the following sections will require the use of the command line. If you’re unfamiliar, there are plenty of good guides out there and unfortunately teaching the command line is out of scope for this document. We assume basic command line competence from here on out.

== I can’t add the connection whatsoever ==

First of all, check if <code>NetworkManager</code> has the connection saved, you can list connections with:

<syntaxhighlight lang="sh">nmcli connection</syntaxhighlight>
Or, <code>nmcli</code> has short-hand commands:

<syntaxhighlight lang="sh">nmcli c</syntaxhighlight>
This should list all your connections, look for one with the name you gave it (which would be <code>University of Bath VPN</code> if you followed the instructions in [[#connect-instructions|the first section]]). If it does exist, try connecting with:

<syntaxhighlight lang="sh">nmcli c up "University of Bath VPN" --ask</syntaxhighlight>
You’ll be asked for your password and you should get a Microsoft authenticator request. If you get a successful connection as per [[#what-to-expect|this section]], great! If not and you didn’t get a Microsoft authenticator request, carry on reading this section. If you didn’t get a successful connection but did get a Microsoft authenticator request, check the next section.

First, let’s clean the slate. Check your connections with:

<syntaxhighlight lang="sh">nmcli c</syntaxhighlight>
Then delete the VPN connections by their UUID (UUIDs look something like <code>7abdc95a-4b2a-42bb-9a4a-38104d288737</code>, yours will be different):

<syntaxhighlight lang="sh">nmcli c delete <uuid of the VPN connection></syntaxhighlight>
Now, we’d suggest adding the connection via <code>nmcli</code>, the command line for <code>NetworkManager</code>. To do this, you can use the following command. '''Note that you’ll have replace the placeholder text with your Bath username''':

<syntaxhighlight lang="sh">nmcli connection add \
con-name "University of Bath VPN" \
type vpn \
vpn-type org.freedesktop.NetworkManager.strongswan \
ifname "*" \
ipv4.dns "138.38.1.1,138.38.1.2" \
ipv4.ignore-auto-dns yes \
vpn.data "address=vpn.bath.ac.uk, method=eap, user=<your bath username without the @bath.ac.uk>, encap=yes, virtual=yes"</syntaxhighlight>
This sets up a strongSwan VPN connection using the university’s DNS servers and the <code>vpn.bath.ac.uk</code> VPN server. It should also use your username, set UDP encapsulation enforcement, and should request an inner IP.

You can now attempt to connect again, following the same steps as before. If you get a connection, great! If not, look for the section that best describes your issue.

== I keep getting connection failed for an unknown reason ==

You may want to check the output of the following command (on systemd machines):
<syntaxhighlight lang="sh">
journalctl -u NetworkManager | grep charon
</syntaxhighlight>

If you see anything like <code>EAP/FAIL</code> but certificates are good, you should [[#file-a-ticket|file a ticket]]. If certificates are bad, you can try the instructions in [[StrongSwan VPN on Linux#I’m not getting a Microsoft authenticator request|this section]].

== I’m not getting a Microsoft authenticator request ==

Before you start this section, make sure to follow the instructions in the previous subsection so you’re in a known state.

When you connect with <code>nmcli c up "University of Bath VPN --ask"</code>, if you get an error such as:

<pre>Error: Connection activation failed: No valid secrets</pre>
You might need a certificate, or you may have entered your password incorrectly. To check the latter, delete the VPN connection and try again.

If you’re not getting a Microsoft authenticator request still, you might need a certificate. The university uses Sectigo certificates for the strongSwan VPN. These ''should'' be bundled in your distro’s trust store, but either <code>charon-nm</code> or <code>NetworkManager</code> might not be checking for them properly and so your connection might be failing. Unfortunately, there is no easy way with a VPN connection to get around this.

The following instructions are a bit messy, but are mostly distro-agnostic and ''should'' resolve the issue ''if it is a certificate problem''.

There are some extra steps you can do first to confirm it is a certificate issue, though different distros package software differently and so this isn’t guaranteed to give results:

<syntaxhighlight lang="sh"># look for anything that suggests a certificate is missing or untrusted
journalctl -u NetworkManager | grep charon

# if the above doesn't show anything, try just looking through NetworkManager's logs
journalctl -u NetworkManager

# if that doesn't immediately show anything, you can try the following
journalctl | grep Sectigo</syntaxhighlight>
Anything that ''does'' come up may be useful to DDaT for troubleshooting if our troubleshooting steps don’t resolve the issue.

Firstly, you’ll have to download the <code>Sectigo Public Server Authentication Root R46</code> certificate. This can be found here: https://crt.sh/?d=4256644734. If you don’t trust us or the certificate has changed, find the correct certificate on this page: https://www.sectigo.com/knowledge-base/detail/Sectigo-Public-Intermediates-and-Roots.

Once you’ve got the certificate, move it somewhere you won’t accidentally delete it. We recommend something like <code>~/.uni-vpn/sectigo-root.crt</code>.

Now, delete your VPN connection (again, just to make sure you’re in a known state) and add the following connection. '''You will need to replace your username AND the path to the Sectigo root certificate''':

<syntaxhighlight lang="sh">nmcli connection add \
con-name "University of Bath VPN" \
type vpn \
vpn-type org.freedesktop.NetworkManager.strongswan \
ifname "*" \
ipv4.dns "138.38.1.1,138.38.1.2" \
ipv4.ignore-auto-dns yes \
vpn.data "address=vpn.bath.ac.uk, method=eap, user=<your bath username without the @bath.ac.uk>, encap=yes, virtual=yes, certificate=/full/path/to/sectigo-root.crt"</syntaxhighlight>
If you used our suggested location, you can replace the certificate path with <code>$HOME/.uni-vpn/sectigo-root.crt</code>.

Attempt to connect as before. If you get a Microsoft authenticator request but don’t get a connection afterwards, go to the next section. If you don’t get a Microsoft authenticator request, [[#file-a-ticket|file a ticket]].

== I get a Microsoft authenticator request, but no connection ==

Firstly, try to connect again, accept the Microsoft authenticator request, and then wait ~40-50 seconds without retrying. If you get a secondary Microsoft authenticator request, this may be due to a routing misconfiguration.

First, check for a rule under <code>210</code> or <code>220</code> with the following command:

<syntaxhighlight lang="sh">ip rule</syntaxhighlight>
If you don’t see a line similar to:

<pre>210: not from all fwmark 0xd2 lookup 210</pre>
You may have a configuration or routing issue. Double check you’ve installed all the correct packages for your distro.

To test if routing is your issue, you can add the following route:

<syntaxhighlight lang="sh">ip route add 138.38.3.176/28 via <default gateway> table 210</syntaxhighlight>
Replacing the default gateway with the IP after “default via” from running <code>ip r</code>. Then, try connecting again. If that doesn’t work, [[#file-a-ticket|file a ticket]]. If that works, '''disconnect and delete the route''' by replacing the <code>add</code> with <code>del</code> in the above command. You can configure <code>NetworkManager</code> to create the route for you when you connect to the VPN, this way it won’t be forever lingering on your system.

To do so, you can run the following:

<syntaxhighlight lang="sh">nmcli c modify "University of Bath VPN" ipv4.route-table 210</syntaxhighlight>
You may need to restart the <code>NetworkManager</code> daemon, '''this will temporarily disconnect you'''. On a <code>systemd</code> based system, this can be done with:

<syntaxhighlight lang="sh">systemctl restart NetworkManager.service</syntaxhighlight>
Now, you should be able to connect to the VPN without issues. If not, [[#file-a-ticket|file a ticket]].

= File a ticket =

If the troubleshooting steps given here don’t work, you should file a ticket with DDaT at: https://topdesk.bath.ac.uk/ (<code>DDaT Support: IT & Audio Visual > Report an Issue > Report a Network Issue</code>).

StrongSwan VPN on Linux

2026-06-19T17:20:53Z

Pcs47: Update connect instructions to not restate connect.bath.ac.uk and also add a warning about MS authenticator.

The GlobalProtect VPN has been decommissioned by DDaT. Unfortunately, this was the only easily working VPN on Linux. The new strongSwan VPN ''should'' just work on popular distros like Mint with the instructions given at https://connect.bath.ac.uk/. Unfortunately, for the rest of us, it often does not “just work”.

This page contains troubleshooting steps for if a basic connection doesn’t work.

= Connect instructions =

'''Before starting''', make sure you have Microsoft Authenticator enabled. Then, navigate to https://mysignins.microsoft.com/security-info. Make sure that the sign-in method fallback is set to "Microsoft Authenticator - notification" (via the "Change" link). This is something not listed on https://connect.bath.ac.uk and may cause later steps to fail.

You should then follow the instructions at https://connect.bath.ac.uk.

The instructions give the following troubleshooting advice:

<blockquote>You may also need to run the command below if you find DNS lookups fail for some university resources:

<syntaxhighlight lang="sh">sudo ln -sfv /run/systemd/resolve/resolv.conf /etc/resolv.conf</syntaxhighlight>
</blockquote>

Though, we’re not sure this is a great idea, and it will not work on any distro. Ubuntu is currently the only distro actively supported by DDaT, though they have been known to respond to tickets for other distros.

== What to expect ==

Now that you’ve followed the university’s instructions, you should be able to connect using the NetworkManager GUI, it should ask you for a username and password (if you haven’t already supplied the username in the configuration), put your university credentials in (the username should be '''without''' the <code>@bath.ac.uk</code>), and you should get a Microsoft authenticator request via the app.

To confirm you are connected to the university VPN correctly, check you can visit any internal site. For example, go to https://2024-25.moodle-archive.bath.ac.uk/. If the page loads, you’re connected! If not, you’ll need to do some troubleshooting.

= Troubleshooting =

First, wipe the slate clean (delete the connection), update your system, and reboot. Once you’ve done that, try again. This should narrow the chances of your system being in some weird state. If it works, great! If not, it’s time to get troubleshooting.

Some of the following sections will require the use of the command line. If you’re unfamiliar, there are plenty of good guides out there and unfortunately teaching the command line is out of scope for this document. We assume basic command line competence from here on out.

== I can’t add the connection whatsoever ==

First of all, check if <code>NetworkManager</code> has the connection saved, you can list connections with:

<syntaxhighlight lang="sh">nmcli connection</syntaxhighlight>
Or, <code>nmcli</code> has short-hand commands:

<syntaxhighlight lang="sh">nmcli c</syntaxhighlight>
This should list all your connections, look for one with the name you gave it (which would be <code>University of Bath VPN</code> if you followed the instructions in [[#connect-instructions|the first section]]). If it does exist, try connecting with:

<syntaxhighlight lang="sh">nmcli c up "University of Bath VPN" --ask</syntaxhighlight>
You’ll be asked for your password and you should get a Microsoft authenticator request. If you get a successful connection as per [[#what-to-expect|this section]], great! If not and you didn’t get a Microsoft authenticator request, carry on reading this section. If you didn’t get a successful connection but did get a Microsoft authenticator request, check the next section.

First, let’s clean the slate. Check your connections with:

<syntaxhighlight lang="sh">nmcli c</syntaxhighlight>
Then delete the VPN connections by their UUID (UUIDs look something like <code>7abdc95a-4b2a-42bb-9a4a-38104d288737</code>, yours will be different):

<syntaxhighlight lang="sh">nmcli c delete <uuid of the VPN connection></syntaxhighlight>
Now, we’d suggest adding the connection via <code>nmcli</code>, the command line for <code>NetworkManager</code>. To do this, you can use the following command. '''Note that you’ll have replace the placeholder text with your Bath username''':

<syntaxhighlight lang="sh">nmcli connection add \
con-name "University of Bath VPN" \
type vpn \
vpn-type org.freedesktop.NetworkManager.strongswan \
ifname "*" \
ipv4.dns "138.38.1.1,138.38.1.2" \
ipv4.ignore-auto-dns yes \
vpn.data "address=vpn.bath.ac.uk, method=eap, user=<your bath username without the @bath.ac.uk>, encap=yes, virtual=yes"</syntaxhighlight>
This sets up a strongSwan VPN connection using the university’s DNS servers and the <code>vpn.bath.ac.uk</code> VPN server. It should also use your username, set UDP encapsulation enforcement, and should request an inner IP.

You can now attempt to connect again, following the same steps as before. If you get a connection, great! If not, look for the section that best describes your issue.

== I keep getting connection failed for an unknown reason ==

This may happen on Ubuntu, the https://connect.bath.ac.uk/ instructions only mention installing a few packages, namely: <code>libcharon-extra-plugins</code>, <code>network-manager-strongswan</code>, and possibly <code>network-manager-strongswan-gnome</code>. However, to fetch the Sectigo certificate used for the VPN automatically, you will also need to install the following: <code>libstrongswan-standard-plugins</code> and <code>libstrongswan-extra-plugins</code>.

Try to connect again once installed, and see if you get any further. You may want to check the output of the following command (on systemd machines):
<syntaxhighlight lang="sh">
journalctl -u NetworkManager | grep charon
</syntaxhighlight>

If you see anything like <code>EAP/FAIL</code> but certificates are good, you should [[#file-a-ticket|file a ticket]]. If certificates are bad, you can try the instructions in [[StrongSwan VPN on Linux#I’m not getting a Microsoft authenticator request|this section]].

== I’m not getting a Microsoft authenticator request ==

Before you start this section, make sure to follow the instructions in the previous subsection so you’re in a known state.

When you connect with <code>nmcli c up "University of Bath VPN --ask"</code>, if you get an error such as:

<pre>Error: Connection activation failed: No valid secrets</pre>
You might need a certificate, or you may have entered your password incorrectly. To check the latter, delete the VPN connection and try again.

If you’re not getting a Microsoft authenticator request still, you might need a certificate. The university uses Sectigo certificates for the strongSwan VPN. These ''should'' be bundled in your distro’s trust store, but either <code>charon-nm</code> or <code>NetworkManager</code> might not be checking for them properly and so your connection might be failing. Unfortunately, there is no easy way with a VPN connection to get around this.

The following instructions are a bit messy, but are mostly distro-agnostic and ''should'' resolve the issue ''if it is a certificate problem''.

There are some extra steps you can do first to confirm it is a certificate issue, though different distros package software differently and so this isn’t guaranteed to give results:

<syntaxhighlight lang="sh"># look for anything that suggests a certificate is missing or untrusted
journalctl -u NetworkManager | grep charon

# if the above doesn't show anything, try just looking through NetworkManager's logs
journalctl -u NetworkManager

# if that doesn't immediately show anything, you can try the following
journalctl | grep Sectigo</syntaxhighlight>
Anything that ''does'' come up may be useful to DDaT for troubleshooting if our troubleshooting steps don’t resolve the issue.

Firstly, you’ll have to download the <code>Sectigo Public Server Authentication Root R46</code> certificate. This can be found here: https://crt.sh/?d=4256644734. If you don’t trust us or the certificate has changed, find the correct certificate on this page: https://www.sectigo.com/knowledge-base/detail/Sectigo-Public-Intermediates-and-Roots.

Once you’ve got the certificate, move it somewhere you won’t accidentally delete it. We recommend something like <code>~/.uni-vpn/sectigo-root.crt</code>.

Now, delete your VPN connection (again, just to make sure you’re in a known state) and add the following connection. '''You will need to replace your username AND the path to the Sectigo root certificate''':

<syntaxhighlight lang="sh">nmcli connection add \
con-name "University of Bath VPN" \
type vpn \
vpn-type org.freedesktop.NetworkManager.strongswan \
ifname "*" \
ipv4.dns "138.38.1.1,138.38.1.2" \
ipv4.ignore-auto-dns yes \
vpn.data "address=vpn.bath.ac.uk, method=eap, user=<your bath username without the @bath.ac.uk>, encap=yes, virtual=yes, certificate=/full/path/to/sectigo-root.crt"</syntaxhighlight>
If you used our suggested location, you can replace the certificate path with <code>$HOME/.uni-vpn/sectigo-root.crt</code>.

Attempt to connect as before. If you get a Microsoft authenticator request but don’t get a connection afterwards, go to the next section. If you don’t get a Microsoft authenticator request, [[#file-a-ticket|file a ticket]].

== I get a Microsoft authenticator request, but no connection ==

Firstly, try to connect again, accept the Microsoft authenticator request, and then wait ~40-50 seconds without retrying. If you get a secondary Microsoft authenticator request, this may be due to a routing misconfiguration.

First, check for a rule under <code>210</code> or <code>220</code> with the following command:

<syntaxhighlight lang="sh">ip rule</syntaxhighlight>
If you don’t see a line similar to:

<pre>210: not from all fwmark 0xd2 lookup 210</pre>
You may have a configuration or routing issue. Double check you’ve installed all the correct packages for your distro.

To test if routing is your issue, you can add the following route:

<syntaxhighlight lang="sh">ip route add 138.38.3.176/28 via <default gateway> table 210</syntaxhighlight>
Replacing the default gateway with the IP after “default via” from running <code>ip r</code>. Then, try connecting again. If that doesn’t work, [[#file-a-ticket|file a ticket]]. If that works, '''disconnect and delete the route''' by replacing the <code>add</code> with <code>del</code> in the above command. You can configure <code>NetworkManager</code> to create the route for you when you connect to the VPN, this way it won’t be forever lingering on your system.

To do so, you can run the following:

<syntaxhighlight lang="sh">nmcli c modify "University of Bath VPN" ipv4.route-table 210</syntaxhighlight>
You may need to restart the <code>NetworkManager</code> daemon, '''this will temporarily disconnect you'''. On a <code>systemd</code> based system, this can be done with:

<syntaxhighlight lang="sh">systemctl restart NetworkManager.service</syntaxhighlight>
Now, you should be able to connect to the VPN without issues. If not, [[#file-a-ticket|file a ticket]].

= File a ticket =

If the troubleshooting steps given here don’t work, you should file a ticket with DDaT at: https://topdesk.bath.ac.uk/ (<code>DDaT Support: IT & Audio Visual > Report an Issue > Report a Network Issue</code>).

StrongSwan VPN on Linux

2026-06-19T17:12:54Z

Pcs47: /* I keep getting connection failed for an unknown reason */ Update link

The GlobalProtect VPN has been decommissioned by DDaT. Unfortunately, this was the only easily working VPN on Linux. The new strongSwan VPN ''should'' just work on popular distros like Mint with the instructions given at https://connect.bath.ac.uk/. Unfortunately, for the rest of us, it often does not “just work”.

This page contains troubleshooting steps for if a basic connection doesn’t work.

= Connect instructions =

This section covers the basic connection instructions from https://connect.bath.ac.uk and what to expect for a successful connection. This might help your troubleshooting. If it doesn’t, giving DDaT information about what happens here might be useful.

# Install the correct packages. The name of these packages differs from distro to distro, so you might have to do some searching. These packages (in the Ubuntu <code>apt</code> repositories) are <code>libcharon-extra-plugins</code>, <code>network-manager-strongswan</code>, and possibly <code>network-manager-strongswan-gnome</code> (if you’re using the Gnome desktop environment).
# Using the NetworkManager GUI (might just be called network settings or similar), add a VPN connection with the following:
#* Connection Name: University of Bath VPN
#* Server Name: vpn.bath.ac.uk
#* VPN Type: IKEv2
#* Type of sign-in: Username and Password/EAP-MSCHAPv2 or simply “EAP”
#* Other Options: Request an inner IP address, Enforce UDP encapsulation
# You may need to use the university’s DNS servers (<code>138.38.1.1</code> and <code>138.38.1.2</code>) or a public DNS server like Cloudflare’s <code>1.1.1.1</code>.

The instructions also give the following troubleshooting advice:

<blockquote>You may also need to run the command below if you find DNS lookups fail for some university resources:

<syntaxhighlight lang="sh">sudo ln -sfv /run/systemd/resolve/resolv.conf /etc/resolv.conf</syntaxhighlight>
</blockquote>
Though, we’re not sure this is a great idea, nor are we sure this will work on any distro.

== What to expect ==

Now that you’ve followed the university’s instructions, you should be able to connect using the NetworkManager GUI, it should ask you for a username and password (if you haven’t already supplied the username in the configuration), put your university credentials in (the username should be '''without''' the <code>@bath.ac.uk</code>), and you should get a Microsoft authenticator request via the app.

To confirm you are connected to the university VPN correctly, check you can visit any internal site. For example, go to https://2024-25.moodle-archive.bath.ac.uk/. If the page loads, you’re connected! If not, you’ll need to do some troubleshooting.

= Troubleshooting =

First, wipe the slate clean (delete the connection), update your system, and reboot. Once you’ve done that, try again. This should narrow the chances of your system being in some weird state. If it works, great! If not, it’s time to get troubleshooting.

Some of the following sections will require the use of the command line. If you’re unfamiliar, there are plenty of good guides out there and unfortunately teaching the command line is out of scope for this document. We assume basic command line competence from here on out.

== I can’t add the connection whatsoever ==

First of all, check if <code>NetworkManager</code> has the connection saved, you can list connections with:

<syntaxhighlight lang="sh">nmcli connection</syntaxhighlight>
Or, <code>nmcli</code> has short-hand commands:

<syntaxhighlight lang="sh">nmcli c</syntaxhighlight>
This should list all your connections, look for one with the name you gave it (which would be <code>University of Bath VPN</code> if you followed the instructions in [[#connect-instructions|the first section]]). If it does exist, try connecting with:

<syntaxhighlight lang="sh">nmcli c up "University of Bath VPN" --ask</syntaxhighlight>
You’ll be asked for your password and you should get a Microsoft authenticator request. If you get a successful connection as per [[#what-to-expect|this section]], great! If not and you didn’t get a Microsoft authenticator request, carry on reading this section. If you didn’t get a successful connection but did get a Microsoft authenticator request, check the next section.

First, let’s clean the slate. Check your connections with:

<syntaxhighlight lang="sh">nmcli c</syntaxhighlight>
Then delete the VPN connections by their UUID (UUIDs look something like <code>7abdc95a-4b2a-42bb-9a4a-38104d288737</code>, yours will be different):

<syntaxhighlight lang="sh">nmcli c delete <uuid of the VPN connection></syntaxhighlight>
Now, we’d suggest adding the connection via <code>nmcli</code>, the command line for <code>NetworkManager</code>. To do this, you can use the following command. '''Note that you’ll have replace the placeholder text with your Bath username''':

<syntaxhighlight lang="sh">nmcli connection add \
con-name "University of Bath VPN" \
type vpn \
vpn-type org.freedesktop.NetworkManager.strongswan \
ifname "*" \
ipv4.dns "138.38.1.1,138.38.1.2" \
ipv4.ignore-auto-dns yes \
vpn.data "address=vpn.bath.ac.uk, method=eap, user=<your bath username without the @bath.ac.uk>, encap=yes, virtual=yes"</syntaxhighlight>
This sets up a strongSwan VPN connection using the university’s DNS servers and the <code>vpn.bath.ac.uk</code> VPN server. It should also use your username, set UDP encapsulation enforcement, and should request an inner IP.

You can now attempt to connect again, following the same steps as before. If you get a connection, great! If not, look for the section that best describes your issue.

== I keep getting connection failed for an unknown reason ==

This may happen on Ubuntu, the https://connect.bath.ac.uk/ instructions only mention installing a few packages, namely: <code>libcharon-extra-plugins</code>, <code>network-manager-strongswan</code>, and possibly <code>network-manager-strongswan-gnome</code>. However, to fetch the Sectigo certificate used for the VPN automatically, you will also need to install the following: <code>libstrongswan-standard-plugins</code> and <code>libstrongswan-extra-plugins</code>.

Try to connect again once installed, and see if you get any further. You may want to check the output of the following command (on systemd machines):
<syntaxhighlight lang="sh">
journalctl -u NetworkManager | grep charon
</syntaxhighlight>

If you see anything like <code>EAP/FAIL</code> but certificates are good, you should [[#file-a-ticket|file a ticket]]. If certificates are bad, you can try the instructions in [[StrongSwan VPN on Linux#I’m not getting a Microsoft authenticator request|this section]].

== I’m not getting a Microsoft authenticator request ==

Before you start this section, make sure to follow the instructions in the previous subsection so you’re in a known state.

When you connect with <code>nmcli c up "University of Bath VPN --ask"</code>, if you get an error such as:

<pre>Error: Connection activation failed: No valid secrets</pre>
You might need a certificate, or you may have entered your password incorrectly. To check the latter, delete the VPN connection and try again.

If you’re not getting a Microsoft authenticator request still, you might need a certificate. The university uses Sectigo certificates for the strongSwan VPN. These ''should'' be bundled in your distro’s trust store, but either <code>charon-nm</code> or <code>NetworkManager</code> might not be checking for them properly and so your connection might be failing. Unfortunately, there is no easy way with a VPN connection to get around this.

The following instructions are a bit messy, but are mostly distro-agnostic and ''should'' resolve the issue ''if it is a certificate problem''.

There are some extra steps you can do first to confirm it is a certificate issue, though different distros package software differently and so this isn’t guaranteed to give results:

<syntaxhighlight lang="sh"># look for anything that suggests a certificate is missing or untrusted
journalctl -u NetworkManager | grep charon

# if the above doesn't show anything, try just looking through NetworkManager's logs
journalctl -u NetworkManager

# if that doesn't immediately show anything, you can try the following
journalctl | grep Sectigo</syntaxhighlight>
Anything that ''does'' come up may be useful to DDaT for troubleshooting if our troubleshooting steps don’t resolve the issue.

Firstly, you’ll have to download the <code>Sectigo Public Server Authentication Root R46</code> certificate. This can be found here: https://crt.sh/?d=4256644734. If you don’t trust us or the certificate has changed, find the correct certificate on this page: https://www.sectigo.com/knowledge-base/detail/Sectigo-Public-Intermediates-and-Roots.

Once you’ve got the certificate, move it somewhere you won’t accidentally delete it. We recommend something like <code>~/.uni-vpn/sectigo-root.crt</code>.

Now, delete your VPN connection (again, just to make sure you’re in a known state) and add the following connection. '''You will need to replace your username AND the path to the Sectigo root certificate''':

<syntaxhighlight lang="sh">nmcli connection add \
con-name "University of Bath VPN" \
type vpn \
vpn-type org.freedesktop.NetworkManager.strongswan \
ifname "*" \
ipv4.dns "138.38.1.1,138.38.1.2" \
ipv4.ignore-auto-dns yes \
vpn.data "address=vpn.bath.ac.uk, method=eap, user=<your bath username without the @bath.ac.uk>, encap=yes, virtual=yes, certificate=/full/path/to/sectigo-root.crt"</syntaxhighlight>
If you used our suggested location, you can replace the certificate path with <code>$HOME/.uni-vpn/sectigo-root.crt</code>.

Attempt to connect as before. If you get a Microsoft authenticator request but don’t get a connection afterwards, go to the next section. If you don’t get a Microsoft authenticator request, [[#file-a-ticket|file a ticket]].

== I get a Microsoft authenticator request, but no connection ==

Firstly, try to connect again, accept the Microsoft authenticator request, and then wait ~40-50 seconds without retrying. If you get a secondary Microsoft authenticator request, this may be due to a routing misconfiguration.

First, check for a rule under <code>210</code> or <code>220</code> with the following command:

<syntaxhighlight lang="sh">ip rule</syntaxhighlight>
If you don’t see a line similar to:

<pre>210: not from all fwmark 0xd2 lookup 210</pre>
You may have a configuration or routing issue. Double check you’ve installed all the correct packages for your distro.

To test if routing is your issue, you can add the following route:

<syntaxhighlight lang="sh">ip route add 138.38.3.176/28 via <default gateway> table 210</syntaxhighlight>
Replacing the default gateway with the IP after “default via” from running <code>ip r</code>. Then, try connecting again. If that doesn’t work, [[#file-a-ticket|file a ticket]]. If that works, '''disconnect and delete the route''' by replacing the <code>add</code> with <code>del</code> in the above command. You can configure <code>NetworkManager</code> to create the route for you when you connect to the VPN, this way it won’t be forever lingering on your system.

To do so, you can run the following:

<syntaxhighlight lang="sh">nmcli c modify "University of Bath VPN" ipv4.route-table 210</syntaxhighlight>
You may need to restart the <code>NetworkManager</code> daemon, '''this will temporarily disconnect you'''. On a <code>systemd</code> based system, this can be done with:

<syntaxhighlight lang="sh">systemctl restart NetworkManager.service</syntaxhighlight>
Now, you should be able to connect to the VPN without issues. If not, [[#file-a-ticket|file a ticket]].

= File a ticket =

If the troubleshooting steps given here don’t work, you should file a ticket with DDaT at: https://topdesk.bath.ac.uk/ (<code>DDaT Support: IT & Audio Visual > Report an Issue > Report a Network Issue</code>).

StrongSwan VPN on Linux

2026-06-19T16:57:57Z

Pcs47: Add issues encountered while setting up VPN for someone on Ubuntu.

The GlobalProtect VPN has been decommissioned by DDaT. Unfortunately, this was the only easily working VPN on Linux. The new strongSwan VPN ''should'' just work on popular distros like Mint with the instructions given at https://connect.bath.ac.uk/. Unfortunately, for the rest of us, it often does not “just work”.

This page contains troubleshooting steps for if a basic connection doesn’t work.

= Connect instructions =

This section covers the basic connection instructions from https://connect.bath.ac.uk and what to expect for a successful connection. This might help your troubleshooting. If it doesn’t, giving DDaT information about what happens here might be useful.

# Install the correct packages. The name of these packages differs from distro to distro, so you might have to do some searching. These packages (in the Ubuntu <code>apt</code> repositories) are <code>libcharon-extra-plugins</code>, <code>network-manager-strongswan</code>, and possibly <code>network-manager-strongswan-gnome</code> (if you’re using the Gnome desktop environment).
# Using the NetworkManager GUI (might just be called network settings or similar), add a VPN connection with the following:
#* Connection Name: University of Bath VPN
#* Server Name: vpn.bath.ac.uk
#* VPN Type: IKEv2
#* Type of sign-in: Username and Password/EAP-MSCHAPv2 or simply “EAP”
#* Other Options: Request an inner IP address, Enforce UDP encapsulation
# You may need to use the university’s DNS servers (<code>138.38.1.1</code> and <code>138.38.1.2</code>) or a public DNS server like Cloudflare’s <code>1.1.1.1</code>.

The instructions also give the following troubleshooting advice:

<blockquote>You may also need to run the command below if you find DNS lookups fail for some university resources:

<syntaxhighlight lang="sh">sudo ln -sfv /run/systemd/resolve/resolv.conf /etc/resolv.conf</syntaxhighlight>
</blockquote>
Though, we’re not sure this is a great idea, nor are we sure this will work on any distro.

== What to expect ==

Now that you’ve followed the university’s instructions, you should be able to connect using the NetworkManager GUI, it should ask you for a username and password (if you haven’t already supplied the username in the configuration), put your university credentials in (the username should be '''without''' the <code>@bath.ac.uk</code>), and you should get a Microsoft authenticator request via the app.

To confirm you are connected to the university VPN correctly, check you can visit any internal site. For example, go to https://2024-25.moodle-archive.bath.ac.uk/. If the page loads, you’re connected! If not, you’ll need to do some troubleshooting.

= Troubleshooting =

First, wipe the slate clean (delete the connection), update your system, and reboot. Once you’ve done that, try again. This should narrow the chances of your system being in some weird state. If it works, great! If not, it’s time to get troubleshooting.

Some of the following sections will require the use of the command line. If you’re unfamiliar, there are plenty of good guides out there and unfortunately teaching the command line is out of scope for this document. We assume basic command line competence from here on out.

== I can’t add the connection whatsoever ==

First of all, check if <code>NetworkManager</code> has the connection saved, you can list connections with:

<syntaxhighlight lang="sh">nmcli connection</syntaxhighlight>
Or, <code>nmcli</code> has short-hand commands:

<syntaxhighlight lang="sh">nmcli c</syntaxhighlight>
This should list all your connections, look for one with the name you gave it (which would be <code>University of Bath VPN</code> if you followed the instructions in [[#connect-instructions|the first section]]). If it does exist, try connecting with:

<syntaxhighlight lang="sh">nmcli c up "University of Bath VPN" --ask</syntaxhighlight>
You’ll be asked for your password and you should get a Microsoft authenticator request. If you get a successful connection as per [[#what-to-expect|this section]], great! If not and you didn’t get a Microsoft authenticator request, carry on reading this section. If you didn’t get a successful connection but did get a Microsoft authenticator request, check the next section.

First, let’s clean the slate. Check your connections with:

<syntaxhighlight lang="sh">nmcli c</syntaxhighlight>
Then delete the VPN connections by their UUID (UUIDs look something like <code>7abdc95a-4b2a-42bb-9a4a-38104d288737</code>, yours will be different):

<syntaxhighlight lang="sh">nmcli c delete <uuid of the VPN connection></syntaxhighlight>
Now, we’d suggest adding the connection via <code>nmcli</code>, the command line for <code>NetworkManager</code>. To do this, you can use the following command. '''Note that you’ll have replace the placeholder text with your Bath username''':

<syntaxhighlight lang="sh">nmcli connection add \
con-name "University of Bath VPN" \
type vpn \
vpn-type org.freedesktop.NetworkManager.strongswan \
ifname "*" \
ipv4.dns "138.38.1.1,138.38.1.2" \
ipv4.ignore-auto-dns yes \
vpn.data "address=vpn.bath.ac.uk, method=eap, user=<your bath username without the @bath.ac.uk>, encap=yes, virtual=yes"</syntaxhighlight>
This sets up a strongSwan VPN connection using the university’s DNS servers and the <code>vpn.bath.ac.uk</code> VPN server. It should also use your username, set UDP encapsulation enforcement, and should request an inner IP.

You can now attempt to connect again, following the same steps as before. If you get a connection, great! If not, look for the section that best describes your issue.

== I keep getting connection failed for an unknown reason ==

This may happen on Ubuntu, the https://connect.bath.ac.uk/ instructions only mention installing a few packages, namely: <code>libcharon-extra-plugins</code>, <code>network-manager-strongswan</code>, and possibly <code>network-manager-strongswan-gnome</code>. However, to fetch the Sectigo certificate used for the VPN automatically, you will also need to install the following: <code>libstrongswan-standard-plugins</code> and <code>libstrongswan-extra-plugins</code>.

Try to connect again once installed, and see if you get any further. You may want to check the output of the following command (on systemd machines):
<syntaxhighlight lang="sh">
journalctl -u NetworkManager | grep charon
</syntaxhighlight>

If you see anything like <code>EAP/FAIL</code> but certificates are good, you should [[#file-a-ticket|file a ticket]]. If certificates are bad, you can try the instructions in [[#im-not-getting-a-microsoft-authenticator-request|this section]].

== I’m not getting a Microsoft authenticator request ==

Before you start this section, make sure to follow the instructions in the previous subsection so you’re in a known state.

When you connect with <code>nmcli c up "University of Bath VPN --ask"</code>, if you get an error such as:

<pre>Error: Connection activation failed: No valid secrets</pre>
You might need a certificate, or you may have entered your password incorrectly. To check the latter, delete the VPN connection and try again.

If you’re not getting a Microsoft authenticator request still, you might need a certificate. The university uses Sectigo certificates for the strongSwan VPN. These ''should'' be bundled in your distro’s trust store, but either <code>charon-nm</code> or <code>NetworkManager</code> might not be checking for them properly and so your connection might be failing. Unfortunately, there is no easy way with a VPN connection to get around this.

The following instructions are a bit messy, but are mostly distro-agnostic and ''should'' resolve the issue ''if it is a certificate problem''.

There are some extra steps you can do first to confirm it is a certificate issue, though different distros package software differently and so this isn’t guaranteed to give results:

<syntaxhighlight lang="sh"># look for anything that suggests a certificate is missing or untrusted
journalctl -u NetworkManager | grep charon

# if the above doesn't show anything, try just looking through NetworkManager's logs
journalctl -u NetworkManager

# if that doesn't immediately show anything, you can try the following
journalctl | grep Sectigo</syntaxhighlight>
Anything that ''does'' come up may be useful to DDaT for troubleshooting if our troubleshooting steps don’t resolve the issue.

Firstly, you’ll have to download the <code>Sectigo Public Server Authentication Root R46</code> certificate. This can be found here: https://crt.sh/?d=4256644734. If you don’t trust us or the certificate has changed, find the correct certificate on this page: https://www.sectigo.com/knowledge-base/detail/Sectigo-Public-Intermediates-and-Roots.

Once you’ve got the certificate, move it somewhere you won’t accidentally delete it. We recommend something like <code>~/.uni-vpn/sectigo-root.crt</code>.

Now, delete your VPN connection (again, just to make sure you’re in a known state) and add the following connection. '''You will need to replace your username AND the path to the Sectigo root certificate''':

<syntaxhighlight lang="sh">nmcli connection add \
con-name "University of Bath VPN" \
type vpn \
vpn-type org.freedesktop.NetworkManager.strongswan \
ifname "*" \
ipv4.dns "138.38.1.1,138.38.1.2" \
ipv4.ignore-auto-dns yes \
vpn.data "address=vpn.bath.ac.uk, method=eap, user=<your bath username without the @bath.ac.uk>, encap=yes, virtual=yes, certificate=/full/path/to/sectigo-root.crt"</syntaxhighlight>
If you used our suggested location, you can replace the certificate path with <code>$HOME/.uni-vpn/sectigo-root.crt</code>.

Attempt to connect as before. If you get a Microsoft authenticator request but don’t get a connection afterwards, go to the next section. If you don’t get a Microsoft authenticator request, [[#file-a-ticket|file a ticket]].

== I get a Microsoft authenticator request, but no connection ==

Firstly, try to connect again, accept the Microsoft authenticator request, and then wait ~40-50 seconds without retrying. If you get a secondary Microsoft authenticator request, this may be due to a routing misconfiguration.

First, check for a rule under <code>210</code> or <code>220</code> with the following command:

<syntaxhighlight lang="sh">ip rule</syntaxhighlight>
If you don’t see a line similar to:

<pre>210: not from all fwmark 0xd2 lookup 210</pre>
You may have a configuration or routing issue. Double check you’ve installed all the correct packages for your distro.

To test if routing is your issue, you can add the following route:

<syntaxhighlight lang="sh">ip route add 138.38.3.176/28 via <default gateway> table 210</syntaxhighlight>
Replacing the default gateway with the IP after “default via” from running <code>ip r</code>. Then, try connecting again. If that doesn’t work, [[#file-a-ticket|file a ticket]]. If that works, '''disconnect and delete the route''' by replacing the <code>add</code> with <code>del</code> in the above command. You can configure <code>NetworkManager</code> to create the route for you when you connect to the VPN, this way it won’t be forever lingering on your system.

To do so, you can run the following:

<syntaxhighlight lang="sh">nmcli c modify "University of Bath VPN" ipv4.route-table 210</syntaxhighlight>
You may need to restart the <code>NetworkManager</code> daemon, '''this will temporarily disconnect you'''. On a <code>systemd</code> based system, this can be done with:

<syntaxhighlight lang="sh">systemctl restart NetworkManager.service</syntaxhighlight>
Now, you should be able to connect to the VPN without issues. If not, [[#file-a-ticket|file a ticket]].

= File a ticket =

If the troubleshooting steps given here don’t work, you should file a ticket with DDaT at: https://topdesk.bath.ac.uk/ (<code>DDaT Support: IT & Audio Visual > Report an Issue > Report a Network Issue</code>).

Terraform

2026-06-12T00:49:12Z

Pcs47: Add info about the recreation footgun.

[[BOSS]] uses terraform (actually [https://opentofu.org/ <code>opentofu</code>]) to deploy all the resources onto [[BOSS/Hosting/Cluster|their kubernetes cluster]], which tries to be the language in which you can deploy anything and everything and if you need to quickly redeploy a whole machine you can with a simple command. In practise it doesn’t work like that, but its good enough for our needs.

You can find the [https://gitlab.bath.ac.uk/cs/int/terraform terraform repo on gitlab], this page was originally taken from the README as it got too long.

== Other resources ==

* [https://developer.hashicorp.com/terraform/tutorials Hashicorp (the maker of the closed source terraform) has some good tutorials on their site]

Basically that’s it really, the rest of this will be looking at how to deploy an application with our configuration.

== Terraform and its woes ==

Before we get into making an app, I must briefly explain terraform and its benefits/issues/confusing behaviours.

This expects you to have a rough idea around how terraform works. But here is a quick explainer: terraform is build around '''resources''', provided by '''providers'''. These resources have a state stored locally in a state file, whether they are deployed, generated values etc. (note that these can literally be anything e.g. from random passwords to HTTP reequests to kubernetes resources to DNS records). These resources can then be organised into modules, which (can) have outputs from values generated by the resources. There are also “data”, but this is basically a reference to another resource which doesn’t have the controls.

When deploying, terraform will then check the state of all the current deployed modules (even pinging servers if needed) and find anything that has changed (e.g. new resources or updated values) and deploy everything.

=== Module structure ===

Modules are the core of terraform and can be a bit tricky to get your head around, as initially they are quite limited (e.g. there is no such thing as a global variable).

But basically a module has a list of inputs as and a list of outputs (and then providers). So it is expected that your module deploys some resources which are then used to output something. E.g. in [https://gitlab.bath.ac.uk/cs/int/terraform/-/blob/main/utils/ldap/user|our ldap user module] the module generates a random password, creates the user and assigns them to a group, then outputs the username, email and password to be used later in another resource.

So e.g.

<syntaxhighlight lang="terraform">module "user" {
source = "../../utils/ldap/user"

display = "Example"
username = "example"
group_ids = var.ldap_group_ids

providers = {
// Note passing providers act somewhat like global constants, passing configuration (e.g. what ldap server we mean)
// to the module
lldap = lldap
}
}

// You can then use the email by: module.user.email or password: module.user.password</syntaxhighlight>
'''NOTE''': All files within a module (the folder) are treated as one global space, similar to how Go works. You can reference variables, locals and resources throughout all files within a module which makes it quite difficult to organise nicely.

The modules are usually structure in the way:

* <code>init.tf</code> – Usually where your <code>providers</code> go and if you are lazy (like me), everything else
* <code>vars.tf</code>/<code>variables.tf</code> – Where you put all your variables. As explained in [[#Variable madness|Variable madness]], I really don’t like this and so commonly ignore
* <code>outputs.tf</code> – All your outputs go here
* <code>*.tf</code> – Anything else, if you want to split it out nicely into other files

=== Variable madness ===

Terraform variables suck.

Anyway, so basically terraform requires you do a full definition for every variable:

<syntaxhighlight lang="terraform">variable "my_var" {
type = string

description = "Something"
nullable = false

sensitive = false # If something is sensitive MAKE THIS TRUE
}
// You can then later reference it with var.my_var</syntaxhighlight>
This defines something that must be inputed by the user, either through the module or your <code>tfvars</code> file (if in the root directory).

Due to this verbosity, and sometimes complex nature of the interfaces I like to create, I have used the <code>object</code> type e.g.:

<syntaxhighlight lang="terraform">variable "my_var" {
type = object({
l = list(string)
m = map(bool) # string -> bool. Same syntax as object, just more flexible
s = set(string) # Yes this is different to list but using the same []
option = optional(string, "my_default")
})
// ...
}</syntaxhighlight>
But even then you can’t define nice defaults for each sub item and the description is for the whole variable, so it has to be done as so. This is just raw pain and not particularly great syntax in my opinion. Also you cannot enable/disable sensitive nature of values for sub items, this means the whole object must be defined as sensitive if you have one password.

And due to the lack of global constants, you must define every variable in every sub project and duplicate the types (yes there is '''no''' way to define a type to use throughout the project).

It is also recommended that you put all variables in a <code>vars.tf</code> file. Which sure does make sense for small modules, but if its that small I find it easier to just chuck at the top of the <code>init.tf</code> file (as the terraform syntax highlighter is soooo broken). Then if its large, I find it more useful to put the variables where they are actually used – but then again this is confusing because the syntax and tooling is so bad.

Oh yeah sorry and then there are '''locals''' which are constants you can define from resources/variables and will be calculated when the information is ready. E.g.

<syntaxhighlight lang="terraform">locals {
temp_val = "hi"
}
// Then you can reference with local.temp_val</syntaxhighlight>

=== Depends on and its pains ===

The one issue with terraform is that its really slow with large projects with this. But the nature of the design encourages large projects (as you want to reference things throughout the smaller apps).

This is due to it having to create a dependency graph where objects wait on their dependencies. These dependencies can be defined by <code>depends_on</code> in any resource or just referencing a value from another resource.

This is really useful so deployments are not actually deployed until all the secrets are deployed. Due to my perferable of not repeating myself, I heavily use the inferred dependency from the referring to resource names e.g. <code>kubernetes_secret_v1.secret.metadata[0].name</code> (yes this is why I don’t just do the simple thing and use the shorter name, its good to know where the value comes from).

'''BUT''' you cannot rely on this, as some things take time to actually deploy even if it says its successful. Therefore you may need to use timers instead. I usually don’t bother due to the numerous other issues with terraform making it so its not actually perfect so there’s minimal point actually making it easy to deploy from scratch.

=== Timeouts ===

If something goes wrong during deployment, e.g. you make a typo, you will have to wait the FULL timeout time. This is really painful when you typo the hostname to the db causing the pod to crashloop in a helm config and you have to wait 10 minutes for terraform to give up. You can Ctrl-C, Ctrl-C, but this causes more issues as you will have to manually intervene and delete the helm chart/deployment before you run the command again.

Instead I recommend shortening the timeouts for the deployment/helm to one more applicable to the application. A lot of our first-party stuff usually deploys in a few seconds and if it doesn’t, something has gone very wrong.

=== Commas or no commas? ===

The terraform syntax is… interesting. Commas are optional in most cases. So I would recommend, not typing commas where they optional.

'''BUT''' within lists/sets (basically between <code>[]</code>) you have to type commas, and if this is across multiple lines '''PLEASE ADD TRAILING COMMAS'''. The reason? Git histories look sooooooo much better.

=== The recreation footgun ===

If you are new to terraform, you might make the following change without thinking too much:

<syntaxhighlight lang="terraform">
resource "aws_db_instance" "old_name" {
# configuration goes here
}
</syntaxhighlight>

into

<syntaxhighlight lang="terraform">
resource "aws_db_instance" "cool_new_name" {
# EXACT SAME configuration goes here
}
</syntaxhighlight>

This will actually completely wipe that database instance from the face of the planet if you just blindly run <code>tofu plan</code> then <code>tofu apply</code>.

What terraform actually does is:

# Oh, <code>old_name</code> doesn't exist anymore? I'll delete that instance then.
# Ah, a new <code>cool_new_name</code> instance! I'll make that fresh then.

You are now left with no data (unless you made backups).

To avoid this, we have a couple options. The first and generally preferred option is to use a [https://developer.hashicorp.com/terraform/language/block/moved <code>moved</code> block]. For the above example, we can do:

<syntaxhighlight lang="terraform">
moved {
from = aws_db_instance.old_name
to = aws_db_instance.cool_new_name
}

resource "aws_db_instance" "cool_new_name" {
# original configuration goes here
}
</syntaxhighlight>

These may litter the code and so they should be removed after a while and are only really preferred if multiple people are working on the terraform. For example, it shows a reviewer that you've renamed a resource and if they deploy it, they won't mess it up.

The other option is to rename it in the code and just run:

<syntaxhighlight lang="sh">
tofu state mv aws_db_instance.old_name aws_db_instance.cool_new_name
</syntaxhighlight>

Then, when you <code>tofu plan</code> you shouldn't see any deletion for the old resource.

== How to create a basic project ==

=== Creating a namespace ===

There is a handy util module for this:

<syntaxhighlight lang="terraform">module "example_namespace" {
source = "./utils/namespace"

name = "example"

enable_dns = true
enable_mail = true
enable_lldap = true
bkp = {
// ...
}

providers = {
kubernetes = kubernetes
}
}</syntaxhighlight>
This allows you to enable or disable features for your namespace, e.g. if your pods need to communicate with the outside world, enabling the DNS. All of these features are disabled by default and its heavily encouraged to only enable the features if the namespace needs it.

The next thing is to configure backups through this, to reduce our dependence and costs from our s3 provider, it is recommended that backups are disabled for all namespaces whos data can be regenerated (e.g. froom). If you do enable it, it is then encouraged that you disable backups for any database or pvc that you don’t need backing up with the <code>k8up.io/backup=false</code> annotation (you may notice that all <code>valkey</code> instances set this by default if you are using the <code>app/valkey</code> module).

==== Placement ====

Within this repository, it is tradition to put the namespace creation at the highest level, e.g. <code>20_apps.tf</code>. This means that the apps themselves do not control the namespace they are created in. It is mostly just a personal preference from me after years of configuring k8s on terraform.

=== Using Helm ===

Helm is by far the easiest way to deploy third-party tools, and is used throught this repo despite it’s drawbacks when combined with terraform (it’s just so easy).

You just add helm to the providers list (which defines what terraform modules you are integrating with):

<syntaxhighlight lang="terraform">terraform {
required_providers {
helm = {
source = "hashicorp/helm"
version = "~>3.1.1"
}
}
}</syntaxhighlight>
You can then use the <code>helm_release</code> resource, which takes the form:

<syntaxhighlight lang="terraform">resource "helm_release" "my_app" {
name = "my_app"
namespace = var.namespace

repository = "https://charts.example.com"
chart = "the_app"
version = "version"

values = [yamlencode({
// Values go here written within the terraform config language
})]
}</syntaxhighlight>
This deploys all the resources an application needs and manages and restarting if a secret or config map changes, providing all the configuration at your fingertips.

However this comes at a cost:

* '''SECRETS SHOULD NOT GO IN THE HELM CONFIG'''. This is a big one, all values are easily accessible unencrypted on the cluster, therefore any secrets '''MUST''' go in a <code>kubernetes_secrets_v1</code> object and you should use a <code>secretsRef</code> or similar to link it. If the helm chart does not support this '''DO NOT USE IT'''. Helm also stores the history of all values, therefore if you put it temporarily within helm values for testing, you must to a password rotation.
* You have no power over the types of resources and the structure in which it deploys. This means that if a feature or support for our strict network policies are not implemented, you have to either not use the helm chart completely or fork your own (which we definitely don’t want to do).
* If the helm chart gets deleted, all pvc related ''might'' also get deleted (unless they have the <code>Retain</code> policy, which should be the case for everything).
* Sometimes they don’t have the proper security contexts/network policies by default so you will have to add them youself (see the below section)

Overall, helm is pretty good, just use with caution and understand what templates you are inflicting. Note, you will probably have to get pretty good at reading not only default values, but schemas and the templating language of helm itself, as sometimes the charts are not particularly well documented.

=== Using kubernetes ===

For this you need to understand a bit of structure of how kubernetes works. I will assume that you are deploying a pod. If that pod needs storage attached (and not through SQL or Redis), then you will need to use a [https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/ <code>StatefulSet</code>]. If you have no storage or are just communicating with a postgres server or redis, you can instead use a [https://kubernetes.io/docs/concepts/workloads/controllers/deployment/ <code>Deployment</code>].

The difference between these two concepts are not particularly seen in the world of a single node cluster, but basically deployments are free to spin up another even if the previous one is still terminating or if the node is non responsive. On the other hand, statefulsets must ensure that no two nodes are trying to access the same data, therefore cannot automatically start up if a node goes down.

This also means that it is much easier to scale a deployment to multiple nodes, vs a statefulsets which must have separate volumes per pod.

Anyway, both statefulsets and deployments have a template configuration for creating the pod associated with itself. This pod has a label which is used to monitor and track the associated pods with its parent. So the structure is as follows:

<syntaxhighlight lang="terraform">resource "kubernetes_deployment_v1" "my_deployment" {
metadata {
name = "my_deployment"
namespace = var.namespace
}
spec {
replicas = 1
selector {
match_labels = {
app = "the_deployment"
}
}
// This doesn't really matter in a one node cluster with a replicas = 1
strategy {
type = "RollingUpdate"
}
template {
metadata {
labels = {
app = "the_deployment"
}
}
spec {
container {
name = "my_deployment"
image = "bathbcss/my_image:latest"
image_pull_policy = "Always" // Should only be set if the above is "latest"

// This should be the default security context to comply with our pod security policies
security_context {
run_as_user = 1000
run_as_non_root = true
allow_privilege_escalation = false
seccomp_profile {
type = "RuntimeDefault"
}
capabilities {
drop = ["ALL"]
}
}

// This is how the pod is checked its alive, so if something happens,
// e.g. job which causes it to become unresponsive, it will be automatically killed off and replaced
liveness_probe {
http_get {
path = "/healthz"
port = 8080
}
initial_delay_seconds = 5
period_seconds = 10
}

// This allows the tracking of when the pod starts, so we wait until the pod is ready to receive requests
startup_probe {
http_get {
path = "/healthz"
port = 8080
}
// 3 * 30 = 90 seconds to start
failure_threshold = 30
// If it takes a while to startup, increase this time
period_seconds = 3
}

// If exposing a port the port to expose
port {
container_port = 8080
// Make sure to give it a name so we can use the name in services
name = "web"
}

// env and env_from definitions
}
}
}
}
}</syntaxhighlight>
''Quick side note: <code>kubernetes_\*_v1</code>is the preferred resouce name, any resource that does not have<code>\_v1</code> on the end is deprecated and should not be used.''

It is recommended that the version of the image is actually set and <code>latest</code> is not used, however to reduce the admin overhead, for internal projects it can be easier to set to <code>latest</code> with an image pull policy of <code>Always</code>. However this means if you want the latest version, you must have access to the cluster to restart a pod.

If you are exposing pods, this should be tied with a <code>Service</code>, as seen below.

==== Security context ====

As you will notice in the example above, we have a security context set. This is '''required''' by the pod security contenxt, otherwise it will not deploy. In most cases you can copy either of the two following policies, depending on whether it is within a kubernetes resource or helm/kubernetes manifest resource:

<syntaxhighlight lang="terraform">resource "kubernetes_deployment_v1" "my_deployment" {
// ....

security_context {
run_as_user = 1000
run_as_non_root = true
allow_privilege_escalation = false
seccomp_profile {
type = "RuntimeDefault"
}
capabilities {
drop = ["ALL"]
}
}

// ....
}</syntaxhighlight>
Or

<syntaxhighlight lang="terraform">resource "kubernetes_manifest" "my_deployment" {
manifest = {
// ....

securityContext = {
runAsUser = 1000
runAsNonRoot = true
allowPrivilegeEscalation = false
seccompProfile = {
type = "RuntimeDefault"
}
capabilities = {
drop = ["ALL"]
}
}

// ....
}
}</syntaxhighlight>
Note that we are running as a user (not root), setting the default seccompProfile (you ''should'' only need the default unless you are doing weird things with the host machine) as well as dropping all capabilities (you may need to add some back in but I will leave to you as you probably know more than me – NOTE: Some are disabled by our pod security policy but can be override with <code>baseline</code>).

==== Liveness and startup probe ====

The liveness and startup probes are not necessary, but is a nice to have. The liveness probe allows the cluster to detect if a pod becomes unresponsive and is then able to kill it if that is the case. Whereas a startup probe makes it so the cluster knows exactly when the pod is able to receive responses.

Please see the [https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ kubernetes docs on probes] for more information on the options. But in most cases the HTTP get option should suffice, which just looks for a status 2xx code.

<syntaxhighlight lang="terraform">resource "kubernetes_deployment_v1" "my_deployment" {
// ....

liveness_probe {
http_get {
port = 8080
}
initial_delay_seconds = 5
period_seconds = 10
}

startup_probe {
http_get {
port = 8080
}
failure_threshold = 30
period_seconds = 3
}

// ....
}</syntaxhighlight>
Or

<syntaxhighlight lang="terraform">resource "kubernetes_manifest" "my_deployment" {
manifest = {
// ....

livenessProbe = {
httpGet = {
port = 8080
}
initialDelaySeconds = 5
periodSeconds = 10
}

startupProbe = {
httpGet = {
port = 8080
}
failureThreshold = 30
periodSeconds = 3
}

// ....
}
}</syntaxhighlight>
==== Environmental variables ====

When configuring deployments, you will want to set environmental variables. There are a few ways to do it, but note '''ANY PASSWORDS/API KEYS GO IN SECRETS''' not the environmental variables. As you will see I will example how to do this.

By default the <code>env</code> list can be used to set a single environmental variable e.g.

<syntaxhighlight lang="terraform">resource "kubernetes_deployment_v1" "my_deployment" {
// ....

env {
name = "TEST"
value = "my_value"
}

// ....
}</syntaxhighlight>
However, this is quite verbose and takes a lot of space, so if you are configuring a lot of variables or have secrets, you will want to use the <code>env_from</code> list. This allows you to reference a config map or secrets (this is the most basic form).

These look like:

<syntaxhighlight lang="terraform">resource "kubernetes_secret_v1" "module" {
metadata {
name = "deployment-db"
namespace = var.namespace
}
data = {
DATABASE_URL = module.database.url
}
type = "Opaque"
}

resource "kubernetes_config_map_v1" "module" {
metadata {
name = "deployment-config"
namespace = var.namespace
}
data = {
PUBLIC_VALUE = "yoooo"
ROCKET_ADDRESS = "::"
}
}

resource "kubernetes_deployment_v1" "my_deployment" {
// ....

env_from {
secret_ref {
name = kubernetes_secret_v1.module.metadata[0].name
}
}
env_from {
config_map_ref {
name = kubernetes_config_map_v1.module.metadata[0].name
}
}

// ....
}</syntaxhighlight>
Or

<syntaxhighlight lang="terraform">resource "kubernetes_manifest" "my_deployment" {
manifest = {
// ....

envFrom = [
{
secretRef = {
name = kubernetes_secret_v1.module.metadata[0].name
}
},
{
configMapRef = {
name = kubernetes_config_map_v1.module.metadata[0].name
}
},
]

// ....
}
}</syntaxhighlight>
Note that you can set the value of a environmental variable from a secret on an individual basis, which can be useful if you are storing environmental variables as well as files inside your secret. E.g:

<syntaxhighlight lang="terraform">resource "kubernetes_deployment_v1" "my_deployment" {
// ....

env {
name = "DB_PASSWORD"
value_from {
secret_key_ref {
name = kubernetes_secret_v1.module.metadata[0].name
key = "password"
}
}
}

// ....
}</syntaxhighlight>
==== Third-party CRDs ====

Now this is is where terraform becomes less good. Basically when deploying using the kubernetes API, the checks will make sure the CRDs (so the like api and kind are installed and supported on the kubernetes cluster). This means that you won’t even be able to run.

Basically it means that you need to comment out manifests that reference these resources until the CRDs are deployed (usually though a helm chart or something).

==== PVCs ====

Please remember '''ANY PASSWORDS/API KEYS/CERTIFICATES GO IN SECRETS''' not in the storage (this also means its configurable by us and yes they can be mounted as read only volumes).

So, kubernetes storage works around persistant volumes which are requested by persistant volume claims. On our k3s single node, we are just using the k3s filesystem class. This means it’s a bit basic but does the job.

Things to note:

* You probably should be manually creating persistant volume claims (and definitely not persistant volumes), instead using <code>statefulsets</code>
* It’s really hard to change persistant volumes post fact, so please go through testing phase if you are unsure about anything.
* K3s does not support the storage limit, so please '''DON’T RELY ON IT''' to stop abusive behaviour.
* If you are defining yourself, do not accidentally make your deployment depend on the persistant volume claim, as the pvc will not be created until it is used in something. See [https://gitlab.bath.ac.uk/cs/int/terraform/-/blob/main/services/mail/mailserver.tf|the mailserver module] of how to handle it. '''NOTE''': If you reference the pvc config in your deployment, terraform will add that automatically to the <code>depends_on</code> list.
* If it is critical data you will need to '''manually update the pv to “retain” its data''' if the pvc gets deleted. This just adds a bit of safety if you mess up a deployment. This can be done in <code>k9s</code> by an admin, updating the <code>persistentVolumeReclaimPolicy</code> to <code>Retain</code> instead of <code>Delete</code>.

So how you should be using pvc, in statefulsets:

<syntaxhighlight lang="terraform">resource "kubernetes_stateful_set_v1" "module" {
metadata {
name = var.name
namespace = var.namespace
}
spec {
service_name = var.name
replicas = 1
selector {
match_labels = {
app = var.name
}
}
template {
metadata {
labels = {
app = var.name
}
}
spec {
container {
name = "my_app"
image = "bathbcss/my_app:1.0.0"

// ...

volume_mount {
name = "data"
mount_path = "/data"
}
}
}
}
volume_claim_template {
metadata {
name = "data"
}
spec {
access_modes = ["ReadWriteOnce"]
resources {
requests = {
storage = "10Gi"
}
}
}
}
}
}</syntaxhighlight>
==== Services ====

Servies are the first way to adding an ingress, and helps give a common endpoint if you have multiple pods running (though we don’t do this). If using within the cluster you can access a service with the address <code>service_name.namespace.svc.cluster.local</code>. Note that if you are accessing it from within the same namespace you can just use the <code>service_name</code> as the hostname (and it is better on a network policy basis).

For a namespace you just need a label to select on (note we have to define an <code>app</code> label for the statefulset/deployment anyway so you can just use this).

So it should look like this:

<syntaxhighlight lang="terraform">resource "kubernetes_service_v1" "module" {
metadata {
name = var.name
namespace = var.namespace
}
spec {
port {
port = 8080
name = "web"
}
selector = {
app = var.name
}
type = "ClusterIP"
}
}</syntaxhighlight>
And then you can just access the port by <code>service_name:8080</code>. Note that you can also set a <code>target_port</code> if you want to change the port from the deployment and service (but like why?).

Also giving it a <code>name</code> is important, so in the ingress we can just use the name instead of the port number itself, increasing readability.

==== Network policies ====

Now comes the pain. If a helm chart has a network policy, use that (but please actually read what permissions it gives).

Network policies, either grant, or block network “ingress” (stuff going into the pod) and “egress” (stuff going out of the pod). By default, due to our security, ingress to our pods is denied (so anything in the cluster), but egress to the outside world is allowed.

You then use either pod selectors or namespace selectors to allow traffic from a pod (which is how <code>enable_dns,lldap,mail</code> works). In most cases egress can be left alone, unless you want to block a node from doing something in particular.

As talked about in the next section, for postgres and valkey, we create these policies, limited to pods with the <code>${name}-${service}-client=true</code> label allowing only inter-namespace communication.

If you do have to write one, which I really hope you don’t, please read [https://kubernetes.io/docs/concepts/services-networking/network-policies/ kubernetes documentation on Network Policies].

=== Postgres and Redis/Valkey ===

We have utilities for [https://gitlab.bath.ac.uk/cs/int/terraform/-/blob/main/apps/postgres|postgres] and redis (through [https://gitlab.bath.ac.uk/cs/int/terraform/-/blob/main/apps/valkey|valkey] due to redis being really hard to run).

If you require these, we highly recommend the above (though postgres needs moving away from bitnami due to the requirement of money for stability). These setup the network policies you need as well as generating secure passwords and you can look at the <code>outputs.tf</code> file to see the outputs you can use from a module.

'''NOTE:''' If using this, for any pod accessing the data, it must be in the same namespace and have the labels <code>${name}-postgresql-client=true</code> and/or <code>${name}-valkey-client=true</code>, otherwise the traffic will be denied by the network policies.

E.g.

<syntaxhighlight lang="terraform">module "database" {
source = "../postgres"

namespace = var.namespace
prefix = var.name
username = "user"
database = "db_name"
size = "250Mi"

providers = {
helm = helm
}
}

// Create a secret with module.database.url

resource "kubernetes_deployment_v1" "module" {
metadata {
name = var.name
namespace = var.namespace
}
spec {
selector {
match_labels = {
app = var.name
}
}
template {
metadata {
labels = {
app = var.name
// This **MUST** be defined otherwise you'll get weird errors
froom-pg-postgresql-client = true
}
}
// ...
}
}
}</syntaxhighlight>
Side note: the namespace will also need to have <code>enable_dns</code> to be able to access it

=== Adding ingress ===

Adding ingress to service basically means that you are making it accessible to the outside world.

If you are doing this, please consider security heavily:

* Can any user alter the DB? Are you doing proper type checking on the inputs?
* Do you make sure to not expose any secrets e.g. db urls
* Do you really need to expose this pod? Or can you leave it to k9s port forwarding?

Then you need to ask:

* Just expose it to people within the bath network e.g. on <code>*.k8s.bathcs.com</code>
* Expose it to the whole world <code>*.bathcs.com</code> (note coordination with backstage to get them to update their traefik will be necessary)

Please expose to the utter minimum people.

If exposing to the full network please note the flow is:

* <code>app.bathcs.com</code> <- You should accept this domain in the ingress
* <code>app.bcss.su.bath.ac.uk</code> <- You should accept this domain in the ingress
* <code>app.k8s.bathcs.com</code> <- This is what the certificate you should be giving (due to this is hostname that backstage is requesting)

Depending on the chosen level, please look at the [https://gitlab.bath.ac.uk/cs/int/terraform/-/blob/main/utils/ingress|<code>utils/ingress/*</code> modules] as these handle this most of this flow for you.

E.g. making it internal to bath uni only:

<syntaxhighlight lang="terraform">module "dns" {
source = "../../utils/ingress/dns_flow"

subdomain = var.subdomain
# We don't want public one, so don't specify cloudflare_zone_id
k8s_cloudflare_zone_id = var.cloudflare_zone_id

# Expanded for effect
domains = {
uni = var.domains.uni
k8s = var.domains.k8s
}

providers = {
cloudflare = cloudflare,
}
}

module "ingress" {
source = "../../utils/ingress/tls"

name = var.subdomain
entry_points = ["websecure"]
namespace = var.namespace
host = module.dns.hosts.k8s
additional_ingress_hosts = [module.dns.hosts.uni]
service = {
name = kubernetes_service_v1.module.metadata[0].name
port = "http"
}
cert_issuer = var.cert_issuer

providers = {
kubernetes = kubernetes,
}
}</syntaxhighlight>
If using a helm repo you may have to manually define the certificate, which is quite easy:

<syntaxhighlight lang="terraform">resource "kubernetes_manifest" "cert" {
manifest = {
apiVersion = "cert-manager.io/v1"
kind = "Certificate"
metadata = {
name = "${var.name}-cert"
namespace = var.namespace
}
spec = {
secretName = "${var.name}-cert-secret"
issuerRef = var.cert_issuer
dnsNames = [var.host]
}
}
}</syntaxhighlight>
Which outputs the cert to the secret with name <code>${var.name}-cert-secret</code>. You can also use <code>kubernetes_manifest.cert.manifest.spec.secretName</code> (you can guess what I prefer).

If you are making it publically accessible, you can use the full flow which does both dns and ingress records:

<syntaxhighlight lang="terraform">module "ingress" {
source = "../../utils/ingress/full_flow"

cloudflare_zone_id = var.cloudflare_zone_id
namespace = var.namespace
domains = var.domains
subdomain = var.subdomain

service = {
name = kubernetes_service_v1.module.metadata[0].name
port = "web"
}
cert_issuer = var.cert_issuer

providers = {
kubernetes = kubernetes,
cloudflare = cloudflare
}
}</syntaxhighlight>
==== Putting it behind authelia ====

If the application doesn’t have oauth integration build in and you are wanting to protect it behind authelia you can add middleware of <code>auth-forwardauth-authelia@kubernetescrd</code> to require them to go through authelia.

You will then have to add an access control rule to authelia e.g.

<pre>rules = [
{
domain = "app.k8s.bathcs.com"
subject = ["group:boss-example-group", "user:hw2210"]
},
]</pre>
'''NOTE''': you can create and manage groups on [https://www.bath.ac.uk/groupmanager/ Bath's group manager], which creates a unix group that can be seen in the LDAP server.

=== Cloudflare dns records ===

Cloudflare provider is an actual pain. You would’ve hoped it would be good, but its not amazing (has previously caused updates on every <code>apply</code>). Basically when creating a dns record you should use the whole address e.g. <code>app.bathcs.com</code> instead of <code>app</code>. This is because it will cause an update on the second application, changing the <code>name</code> value (which we use to get the full domain).

It sucks because theres an additional useless variable ontop of the <code>cloudflare_zone_id</code> (yes you can use the “data” thing to solve this but still).

Additionally for long TXT records, it will add additional quotes, and terraform will continually think you need to change that if you don’t yourself add the quotes into the data.

=== Sending mail ===

Sending mail is somewhat weird.

Basically just because I can, the authentication is managed by <code>lldap</code> (a really fast ldap implementation). This should not be confused with the ldap service that Authelia is hooked up with, as it is not.

Once you’ve enabled mail in the namespace you then have to create an ldap user:

<syntaxhighlight lang="terraform">module "user" {
source = "../../utils/ldap/user"

display = "Example"
username = "example"
group_ids = var.ldap_group_ids

providers = {
lldap = lldap
}
}</syntaxhighlight>
You can then use this to access the mail with <code>module.user.name</code>, <code>module.user.password</code> and <code>module.user.email</code>. '''NOTE''' due to it not being exposed, we must use the kubernetes domain certificate, which means that you normally have to disable tls verification it or set the expected domain to <code>bathcs.com</code> (as seen in authelia).

=== Creating an oauth client ===

I have created a [https://gitlab.bath.ac.uk/cs/int/terraform/-/blob/main/utils/oauth/client|OAuth client module] for generating all the secret data you need and generate the client config (under the <code>config</code> output) you can then pass up and then into the authelia module (see <code>grafana</code> as an example).

But basically please read [https://www.authelia.com/integration/openid-connect/introduction/ the authelia oidc docs] for a full explanation of how it works.

Category:Help needed

2026-06-12T00:28:55Z

Pcs47: Init

BOSS/Languages/Rust

2026-06-12T00:25:33Z

Pcs47: Update and add sections on useful tools.

The Rust compiler is pretty pedantic by default, however, we have a few recommendations:

* Change the default check command in VSCode (instead of check use <code>clippy</code>).
* 4 spaces for tabs.
* Macros are cool but don’t overuse them.
* Use rustfmt: <code>cargo fmt</code>.

= Recommended tools =
== Bacon ==
Get [https://github.com/Canop/bacon bacon], open it in another terminal window, leave it running while you edit. It will save you recompiling constantly to get the verbose compiler output.

It also has handy features:

* <code>a</code> - to check all.
* <code>c</code> - to clippy all.
* <code>t</code> - to run tests.
* <code>n</code> - to run tests via [https://nexte.st/ <code>cargo-nextest</code>].

You can also make it run pedantic checks with <code>bacon pedantic</code>.

== Audit ==
<code>cargo install cargo-audit</code> (or use [https://github.com/cargo-bins/cargo-binstall <code>cargo-binstall</code>]).

You can then run <code>cargo audit</code> to audit your dependencies for security vulnerabilities.

== Flamegraph ==
<code>cargo install cargo-flamegraph</code> (or use [https://github.com/cargo-bins/cargo-binstall <code>cargo-binstall</code>]).

You can then use <code>CARGO_PROFILE_RELEASE_DEBUG=true cargo flamegraph [-- args-for-your-project]</code> to generate a [https://www.brendangregg.com/flamegraphs.html Flamegraph] for profiling and optimising your project.

== Machete ==
<code>cargo install cargo-machete</code> (or use [https://github.com/cargo-bins/cargo-binstall <code>cargo-binstall</code>]).

You can then use <code>cargo machete</code> to remove unused dependencies.

Main Page

2026-06-12T00:05:07Z

Pcs47: Remove random tag.

Welcome to the wiki hosted by students of the University of Bath. It is managed by [[Bath Open Source Society]], and any student is free to login and edit pages. This is designed as a space where societies can store knowledge that can easily be passed down, or even students can share fun facts they have learnt while studying at Bath.

There is minimal restriction to what can be uploaded to this wiki, we just ask that you be polite and follow the [https://www.bath.ac.uk/legal-information/dignity-and-respect-policy/ Dignity and Respect policy]. All edits are associated with your University login and we will follow standard University procedures in the event of serious misconduct.

If you would like help with anything, please contact [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk].

== Contributing ==
To get started with this wiki, you just need to log in at the top right. You will then have permission to edit almost any page.

For ideas of places you can contribute, see [[Special:WantedPages]] and [[:Category:Help needed]].

Main Page

2026-06-12T00:04:46Z

Pcs47: Fix link.

Welcome to the wiki hosted by students of the University of Bath. It is managed by [[Bath Open Source Society]], and any student is free to login and edit pages. This is designed as a space where societies can store knowledge that can easily be passed down, or even students can share fun facts they have learnt while studying at Bath.

There is minimal restriction to what can be uploaded to this wiki, we just ask that you be polite and follow the [https://www.bath.ac.uk/legal-information/dignity-and-respect-policy/ Dignity and Respect policy]. All edits are associated with your University login and we will follow standard University procedures in the event of serious misconduct.</nowiki>

If you would like help with anything, please contact [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk].

== Contributing ==
To get started with this wiki, you just need to log in at the top right. You will then have permission to edit almost any page.

For ideas of places you can contribute, see [[Special:WantedPages]] and [[:Category:Help needed]].

Main Page

2026-06-12T00:04:16Z

Pcs47: Add a link to the dignity and respect policy.

Welcome to the wiki hosted by students of the University of Bath. It is managed by [[Bath Open Source Society]], and any student is free to login and edit pages. This is designed as a space where societies can store knowledge that can easily be passed down, or even students can share fun facts they have learnt while studying at Bath.

There is minimal restriction to what can be uploaded to this wiki, we just ask that you be polite and follow the [https://www.bath.ac.uk/legal-information/dignity-and-respect-policy/<nowiki> Dignity and Respect policy]. All edits are associated with your University login and we will follow standard University procedures in the event of serious misconduct.</nowiki>

If you would like help with anything, please contact [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk].

== Contributing ==
To get started with this wiki, you just need to log in at the top right. You will then have permission to edit almost any page.

For ideas of places you can contribute, see [[Special:WantedPages]] and [[:Category:Help needed]].

User:Pcs47

2026-06-11T23:04:45Z

Pcs47: Improve userbox contrast.

= Peter =

{{userbox
| border-c = #000
| border-s = 2
| id = BOSS
| id-c = #CCF
| id-s = 20
| info = ''this user is a [[BOSS]] committee member''
| info-c = #FFC
| info-s = 12
}}

Bath Open Source Society

2026-06-11T23:03:44Z

Pcs47: /* Contributing */

Bath Open Source Society (BOSS), is a society focused on providing computer services to students and societies. Their members and committee build and provide websites and tools which students and societies can use.

All services are hosted under [https://bathcs.com bathcs.com], which is a domain owned by the society, as well as [https://bcss.su.bath.ac.uk bcss.su.bath.ac.uk].

The committee's contact details can be found on their [https://thesubath.com/boss SU page].

== Services ==
There are many services maintained by BOSS, students are free to use most of them, with only a few requiring permission.

=== General ===

* [https://froom.bathcs.com Froom], a tool to help you find free unbookable rooms on campus if you just need a room for brief meetings or some quite time.
* [[Main Page|Wiki]], this mediawiki instance, where students can store general knowledge and information about university life

=== Society tools ===

* [https://vault.bathcs.com VaultTub], a hosted password manager compatible with [https://bitwarden.com/ Bitwarden], allows societies to easily share password's with other committee members and perform handovers relatively simply. If your society wants to use this, please email [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk] and we can set you up with an organisation.

* [https://signin.bathcs.com Sign me in!], a tool created for societies to check and track people signed up for a ticketed event and is compatible with the SU's library card reader for even faster signin process.
* [https://gitlab.bath.ac.uk/cs/services/timetable-heater Timetable Heatmap], a tool to find the best times for weekly events with a chosen audience. Please note that this does require some programming knowledge to be able to use.

=== Departmental tools ===
We also have tools for general departmental student activity, if departments want to use these tools, please contact [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk] and we can set you up with it.

* [https://gitlab.bath.ac.uk/cs/pm/peer-mentor-website Peer Mentor Grouper], this is a basic site that allows freshers to choose preferred peer mentors and then assigns the best combination to achieve most people's preferred choice.

=== Custom ===
If a society wants a custom website or tool for an event they are running, please get in contact with [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk]. Though your dream may not be completely achieved, BOSS will try to fit your needs.

With this, we are able to create and host services such as:

* Basic webpage for advertising your events or just your society
* Websites with integration with [https://auth.bath.ac.uk auth.bath.ac.uk] to provide minimal account system (as long as it complies with GDPR).
* Provide graphs which track website performance
* Send emails from <code>bathcs.com</code> domain, with reduced likelihood of going into spam.
* Websites with restricted user access (e.g. only committee members)

Websites we have previously helped:

* Bath Hack 24-26
* Witathon 25-26

Although, we do have limited resources and so we can only build a few projects from scratch each year, but if you are somewhat technical and have already built a website, we are happy to help you host it.

=== Future ===
BOSS tracks all of its potential future projects on its [https://gitlab.bath.ac.uk/cs/planning/ planning board], which any student can contribute to or discuss the projects.

== Contributing ==
As a society, BOSS members can contribute to any project to help them improve and grow, there are many ways you can contribute, even without any technical knowledge. We track all our issues and store all our code on [https://gitlab.bath.ac.uk/cs Bath's GitLab instance], under the <code>cs</code> organisation and all conversation is done through our hosted Matrix instance.

=== Get Started ===


=== Tester/stakeholder ===
If you want to provide invaluable source of information about up and coming projects, you can get involved by joining our group chats and respond to questions around design. You can checkout current project ideas on our [https://gitlab.bath.ac.uk/cs/planning/ planning board].

This makes sure our new projects are useful and relavent to you as a student.

=== Bug reporter/Feature requester ===
If you find a bug or issue with a service we provide, or even just want to see a specific feature added, please see [[Creating a work item]]. This provides tasks for other students to complete and makes sure that our services are of the highest quality. Please be patient though, development takes time, especially when no one is paid to work on any specific feature.

=== Designer ===
If you are good at art (unlike a lot of Computer Scientists), you can get involved by creating logos or even working with a developer to improve the style of our websites, through CSS and HTML. We are always looking to making our sites more intuitive and this is an invaluable source of help with that.

=== Documenter ===
Computer scientists commonly struggle at writing long essays, though they love talking about their inventions. So you can help out by creating wiki pages about how to use a piece of software, or even read some code that is created and add documentation to the functions explaining what they do and how they work. As students leave every year, we need to make sure our code is as readable as possible.

=== Developer ===
The core of our members, those who are just learning to code for a bit of fun, or wanting to get some practice before going to work at a real company. We work in a range of languages as we believe you should choose the right language for the job, but we tend to use Rust and TypeScript as they are the fun cool languages on the block.

Before you contribute to any of our projects however, you must agree to the [https://boss.bathcs.com/policies/licenses/#developers-certificate-of-origin Developer Certificate of Origin] and understand our [https://boss.bathcs.com/policies/genai/ generative AI Policy]. But you are free to fork any of our projects, make your changes and then submit an MR. If you are wanting to fix an issue, please send a message on that specific work item to state you are working on it, and make sure no one else is doing the same thing.

If it is a large feature that is not an issue, please get in touch with the project owner or committee to discuss if it is wanted, as we do not want to waste your time.

=== Project Owner ===
If you are assigned this role, you will be responsible for managing work items, reviewing merge requests and publishing releases of your projects. This role is not elected as we want the people with the most knowledge and understanding of the project.

Project owners will be chosen each year and trained up before the previous owner leaves.

=== Sysadmin ===
If you much prefer configuring systems, managing deployments and putting out fires (hopefully not literally), you can apply to become a system administrator. We aim to make this role as easy as possible, relying on automated deployments where ever possible. Although, many other factors can go wrong with 4 servers, and so we need people regularly checking in on them and making sure they have not been hacked or something.

You will need specific knowledge of linux commands, ssh and maybe even kubernetes and FreeBSD (but that's generally easy to learn and we offer training). You will get varying levels of access to our production and staging kubernetes clusters as well as the machines that run them.

User:Pcs47

2026-06-11T23:01:21Z

Pcs47: Init user page.

= Peter =

{{userbox
| border-c = #000
| border-s = 2
| id = BOSS
| id-c = #AAF
| id-s = 20
| info = ''this user is a [[BOSS]] committee member''
| info-c = #FFA
| info-s = 12
}}

Template:Userbox

2026-06-11T22:59:56Z

Pcs47: Add link to Mediawiki documentation.

{| cellspacing="0" style="width:238px; background:{{{info-background|{{{2|{{{info-c|#EEE}}}}}}}}}; float:{{{float|none}}}; border:{{{border-width|{{{border-s|1}}}}}}px solid {{{border-color|{{{1|{{{border-c|{{{id-c|#999}}}}}}}}}}}}; margin:1px;" class="wikipediauserbox {{{bodyclass|}}}"
{{#if:{{{logo|{{{3|{{{id|id}}}}}}}}}|
! style="width:{{{logo-width|{{{id-w|45}}}}}}px; height:{{{logo-height|{{{id-h|45}}}}}}px; background:{{{logo-background|{{{1|{{{id-c|#DDD}}}}}}}}}; text-align:{{{id-a|center}}}; font-size:{{{logo-size|{{{5|{{{id-s|14}}}}}}}}}pt; color:{{{logo-color|{{{id-fc|black}}}}}}; padding:{{{logo-padding|{{{id-p|1px}}}}}}; line-height:{{{logo-line-height|{{{id-lh|1.25em}}}}}}; vertical-align: middle; {{{logo-other-param|{{{id-op|}}}}}}" {{!}} {{{logo|{{{3|{{{id|id}}}}}}}}}
}}
| style="text-align:{{{info-a|left}}}; font-size:{{{info-size|{{{info-s|8}}}}}}pt; padding:{{{info-padding|{{{info-p|4px}}}}}}; height:{{{logo-height|{{{id-h|45}}}}}}px; line-height:{{{info-line-height|{{{info-lh|1.25em}}}}}}; color:{{{info-color|{{{info-fc|black}}}}}}; vertical-align: middle; {{{info-other-param|{{{info-op|}}}}}}" | {{{info|{{{4|{{{info|''info''}}}}}}}}}
|}{{#if:{{{nocat|}}}||{{#if:{{{usercategory|}}}|{{#switch:{{NAMESPACE}}
|User = [[Category:{{{usercategory}}}]]
|Template = [[Category:Userboxes{{#translation:}}| ]]
}}}}}}<noinclude>
See [https://www.mediawiki.org/wiki/Template:Userbox] for documentation.
</noinclude>

Template:Userbox

2026-06-11T22:55:43Z

Pcs47: Add userbox template

Git/GitLab

2026-06-11T22:50:58Z

Pcs47: /* Issue + MR Templates */ Add note about BOSS license policy.

We require that the websites hosted on bathcs.com should be stored in [https://gitlab.bath.ac.uk/cs the cs organisation on Bath’s GitLab instance]. Any project used by student-led initiatives can also be stored on here.

GitLab was chosen because it has a lot more (useful) features than GitHub. However this does mean that it is aimed at people who has a basic knowledge of how to properly manage git projects.

Therefore you will need to be able to use GitLab.

{{Note|type=warn|text=
You cannot push or pull to the GitLab outside of the VPN, even though you can access the page.
}}

== Setup ==

You might have set this up when handing over, if you haven’t, here are the instructions. Note you will have to ask an organisation manager to add you to the organisation if you are going to be editing any current projects.

* Go to https://gitlab.bath.ac.uk
* Login with your University credentials
* Setup TOTP as your 2FA (one time codes). See [[2FA#TOTP|our 2FA section]] for more information about what this is and how to add one (you can skip to the section where it says “Once you see a QR code”)

Once you have logged in, your account will be created and so can be added to organisations or tagged (using @username).

=== SSH Keys ===

If you want to commit or clone repos, you will also need to setup an SSH key:

# Create an SSH key: see [[SSH keys|our documentation]] for information on how to set one up.
# Go to your preferences (click profile icon then click preferences).
# Click “SSH Keys”.
# Copy and paste the public key into the “Key” section.
# Give it a title.
# Change usage type to “Authentication only”.
# Click “Add key”.

By default this will expire in a year, after which you will have to add another key in the same way.

=== Extra Emails ===

You may have already set up git with your personal email address or you have a git signing key with a specific email. You probably don’t want to edit the configuration on a per project basis.

To solve this, GitLab and GitHub allow you to have multiple email addresses linked to your account, this can be found by going to preferences (click the profile icon then preferences) then clicking “Emails”.

You can then type in another email into the box and click “Add email address”. You will then have to verify the email by clicking the link it gives you.

== The CS Organisation ==

All Student Led Initiative projects are stored on the [https://gitlab.bath.ac.uk/cs Computer Science SLI organisation]. If you are a committee member you should have been given access to it. If not please contact the current owners, who can be found by going “Group information > Members”.

[[File:git-gitlab_members.gif|Members page on GitLab showing the current owners and maintainers found by going to Members in the navigation group “Group Information”|764x764px]]

The organisation or group has subgroups for all societies or student-led initiatives. You should have developer rights on all initiatives which you are a part of, which allows you to create branches on the existing projects and push to them. If you ask nicely you may get maintainer rights, which will allow you to create new projects and merge MRs into main (however you still can’t push to the <code>main</code> branch).

There are some projects which live outside the subgroups (e.g. this wiki) as they don’t have a organisation apart of. You will have to specifically ask permission to access individual projects for security reasons.

== Issues ==

=== Creating ===

[[File:git-create_issue.gif|gif showing the steps of going to the issues menu under pinned and clicking new issue button|728x728px]]

Creating an issue is easy, you can click on the “Issues” tab under “pinned” and click “New Issue” and start typing. The description is written in markdown. You can [https://docs.gitlab.com/ee/user/markdown.html learn markdown on the GitLab website].

If the project is configured with templates, there should be a dropdown for you to choose the one most relavent to your issue type.

[[File:git-mr_templates.gif|gif showing the dropdown to select the template to use above the description|491x491px]]

You can then assign someone an issue from the menu if you know who will be working on it. Labels are also available, but these are mostly for the maintainers of the project to use.

Once the issue is created, it will assign the issue a number (you can see this in the URL), which you can use to cross-reference issues or MRs by putting a <code>#</code> before it. GitLab will pick this up and turn it into a link (you can also just put the link and it will be sortened). Note that issues on other projects can also be referenced.

=== Managing Issues ===

There is not much to say about managing issues. All conversations about the issue should be done on the issue itself.

Once someone is working on it, they should be assigned the issue and it should be referenced in the MR which fixes it.

If “Closes” is put before the link to the issue on an MR, once it is merged, the issue should automatically be closed (but please always do check all the related issues are closed).

== Forking + Branches ==

If you are a developer or maintainer on a project, you should be able to create a branch on the project (but just not push directly main). Branches should be under the format <code><username>/<fix_summary></code>.

If you are not a developer but would like to contribute to a project, you should be able to fork the repository into your own space to create make any edits you wish.

== Merge Requests ==

=== Creating ===

[[File:git-create_mr.gif|gif showing the steps of going to the merge requests menu under pinned and clicking new merge request button and choosing a branch to merge into main|820x820px]]

Once you have created a fork or branch, you can create a merge request, either by clicking the link which is shown after pushing, or going onto the project and clicking “Merge requests” at the left and choosing “New merge request”. You can then choose the branch you want to merge from and the one you are merging to (most likely <code>main</code>).

The interface is very similar to issues, with the summary written in markdown and templates available.

If the Merge Request is not finished, and so still a work in progress, you can click the “Mark Draft” button or put “DRAFT:” at the start of the summary.

You can then assign the MR to yourself (as you will be managing it). You then also want to set the reviewer to a maintainer who can then merge the issue.

If the MR depends on another MR to be merged beforehand, please add the “blocked” label and mention what its blocked on in a comment or the issue directly.

=== Managing ===

Sadly as the university does not pay for premium GitLab, we have to do most security practices as manual steps. So please do not go against these procedures, we beg of you.

If you are the reviewer of a MR, you can go onto the “Changes” tab where you can see all the differences between this and the main branch. There is a settings button where you can change parts of the look. I recommend enabling “show whitespace changes” to help find where people have accidentally left trailing whitespace.

You can then add a comment on a line by hovering over the line and clicking the comment button on the left hand side. You can also do this on images if you wish.

When adding a comment you have the option to “start a review” which is recommended if you are going to be making multiple comments as it send them out all at once instead of having a separate email for each comment (which is a lot).

If you drag the comment, you can also select multiple lines which is useful for segments of code which need changing.

[[File:git-start_review.gif|gif showing going to commits tab and adding a comment to the review, selecting multiple lines|524x524px]]

It is expected that the assignee will then resolve all of these issues so it is not up to the reviewer (but as we are students they may need chasing).

Once you are happy with the MR, you can then approve the merge request before merging it.

Please make sure that:

* You don’t approve your own MR
* Don’t merge something without approval (if it is going into <code>main</code>)
* Don’t approve without actually reading all the changes

== Creating a new Project ==

Over time we may want to add more projects to the organisation. This page focuses on creating projects from scratch. If you are just wanting to mirror, see the [[Git/Mirrors|page about mirrors]].

When creating a new repo or project, you need to decide which subgroup it should go under. This should be quite simple, however you may decide a new subgroup is required.

If you are not a maintainer in a repository, you will have to find the maintainers of the subgroup and ask one of them to set up the repo for you and then add you to the access list.

Other things to consider when creating a project:

* Name (please make this understandable about what it is for)
* Visibility level:
** '''Private''': only people with access can see it (preferably not), however is understandable if you are just testing out a project.
** '''Internal''': Only bath students can see it when logged in, this is useful for things which interact with University of Bath services which they may not want known to the public.
** '''Public''': This should be used for most projects to encourage the open source nature of the community.

Once a repository is created you can add it as a remote to your repo or clone it.

You should then:

* Go to “Settings > Repository > Protected branches” and change “Allowed to push and merge” to be “No one” and make sure “Merge MRs” is set to “Maintainers only”.
* Add a description or logo in the “Settings > General” tab
* Add a license as explained [[Git/Special files#license|here]].

[[File:git-setup_new_project.gif|gif showing the process of editing the protected branches to only allow maintainers to merge to main and no one to push to the main|627x627px]]

=== Manage Access ===

You can choose who can access the repository in “Manage > Members” if you are a Maintainer or Owner.

To add new person you can click “Invite members” and type in their username (they will need to have signed into GitLab for their username to appear).

You then need to choose their role. It is recommended to put them as “Developer” unless you want them to be able to merge requests into <code>main</code>, then put them as “Maintainer”.

=== Labels ===

Under “Manage > Labels” you can add or create labels which can be used on merge requests or issues. You should inherit any labels from the parent group, and preferably labels should be group wide. But you can create a label and ask an Owner to upgrade the label to a group label by clicking the 3 dots.

=== Issue + MR Templates ===

In your project, you may want to have templates for people creating issues or MRs to save them time and to standardise them.

This is quite simple to do in GitLab as explained [https://docs.gitlab.com/ee/user/project/description_templates.html here].

In short, you need to add markdown files to <code>.gitlab/issue_templates/</code> or <code>.gitlab/merge_request_templates/</code>. The default should be named <code>default.md</code>.

Examples:

<ul>
<li><code>.gitlab/issue_templates/default.md</code>
<pre class="md">### Summary



### Steps to reproduce

</pre></li>
<li><code>.gitlab/merge_request_templates/default.md</code>
<pre class="md">### Related Issue



Closes #

### Summary



### Testing

</pre></li>
<li><code>.gitlab/merge_request_templates/bug_fix.md</code>
<pre class="md">### Summary



### Testing

</pre></li></ul>

For projects specific to [[BOSS]], they must also include a checkbox for [https://developercertificate.org/ DCO] acknowledgement according to the [https://boss.bathcs.com/policies/licenses/ BOSS license policy].

=== CI Pipelines ===

GitLab pipelines are super powerful and I don’t think I could write better documentation than GitLab themselves (which can be found [https://docs.gitlab.com/ee/ci/pipelines/ here]).

This is just here to say they do exist and they should be used for automated testing or even deployment.

The configuration can be found in the <code>.gitlab-ci.yml</code> file.

== See also ==

{{Special:PrefixIndex|prefix=Git|namespace=0|hideredirects=1}}
[[Category:Tutorial]]

BOSS/Languages/Markdown

2026-06-11T22:46:38Z

Pcs47: No longer written in markdown.

This is not a programming language, but all READMEs should be written in markdown.

<ul>
<li>Tab size to 2 spaces</li>
<li>Use <code>-</code> over <code>*</code></li>
<li>Max line length should be 80</li>
<li>Use blank lines to space things out!
<pre class="md">## A title

Some text

- point1
- point2</pre></li>
<li>Code blocks should always have a filetype
<pre class="md">```py
print("Hi")
```</pre></li>
<li>Anything relating to the point above should be indented and blank space left
<pre class="md">- point1

some other paragraph

- point2</pre></li></ul>

Formatters do exist (e.g. [https://prettier.io/ prettier] or [https://biomejs.dev/ biome]) so use them please!

Git/Mirrors

2026-06-11T22:43:44Z

Pcs47: Change from bathcs.com to gitlab.bath.ac.uk.

Some projects could be a student’s heart and soul. We do not want to take this away from them, instead we just want to store a copy of the current version on [https://gitlab.bath.ac.uk the university's Gitlab].

So the solution to this is to have a mirror repo.

There are multiple ways to solve this:

== GitLab Mirror ==

In GitLab go to “Settings > Repository > Mirroring Repositories”, you can see there is an option to “push” to another repo.

This means that if the student has their own GitLab instance where they store their own version, they can setup this pushing feature to push to a repo on the GitLab.

However, due to security restrictions, this only works when the other server is connected to the University Intranet, so it is not feasible.

== Just do it manually ==

When doing it manually, you can just push to two separate repositories when making changes locally, by going:

<syntaxhighlight lang="sh">git add remote bath git@gitlab.bath.ac.uk:cs/wiki
git push
git push bath</syntaxhighlight>
If you were wanting to have a specialised branch which has some extra features, you can do something like:

<syntaxhighlight lang="sh">git checkout branch-name
git push bath HEAD:main</syntaxhighlight>

== See also ==

{{Special:PrefixIndex|prefix=Git|namespace=0|hideredirects=1}}
[[Category:Tutorial]]

VaultTub

2026-06-11T22:38:01Z

Pcs47: /* Rotating passwords */ Add link to passwords page and TL;DR it here.

VaultTub is a password manager managed by [[Bath Open Source Society]] which allows societies to store and share passwords securely. It can be accessed at [https://vault.bathcs.com vault.bathcs.com].

For more detailed instructions, see [https://bitwarden.com/help/ BitWarden’s documentation].

== Quick setup ==

You should be messaged or told by the previous committee that you need to sign up so they can invite you. All Bath students can freely make an account (though we ask you not to store your personal passwords on there).

<ol style="list-style-type: decimal;">
<li>Go to [https://vault.bathcs.com vault.bathcs.com].</li>
<li>Enter your uni email and click "Use single sign-on".</li>
<li>Once redirected to our authentication site (Authelia), enter your University username and password.</li>
<li>You will be redirected back to VaultTub and asked to create a master password. Use a brand new password that you will not forget.{{Note|text=If you lose the master password you will lose all access to VaultTub.|type=warn}}</li>
<li>You may also receive emails during this process, if the email is in '''junk''', there should be a dropdown at the top of the email with the option to make “vault@bathcs.com” never go to your junk folder. Please select this as you will get a lot more emails after this point.</li>
<li>'''Required''': [[#Two-step login|Set up 2FA]]</li>
<li>'''Required''' '''for [[VaultTub#Organisation owners|Owners of organisations]]''': set up [[#Emergency Access|emergency access]]</li></ol>

Outgoing committees/initiatives will add you to the relevant organisation as described in the handover procedure. Please ensure that they do this, otherwise you will lose all access to the society's passwords.

== Recommended Settings ==

Once you have signed up with a password you can remember (but don’t use anywhere else), we recommend updating the following settings:

Settings can be found: “Profile Icon in top right > account settings”.

=== Two-step login ===

{{Note|type=info|text=
Two-factor authentication is '''mandatory''' for everyone.
}}

Go to [https://vault.bathcs.com/#/settings/security/two-factor Two-step login settings] and choose a provider. For the best security we recommend Authenticator app or Passkey.

=== Emergency access ===

{{Note|text=
Emergency access is '''mandatory''' for all [[#Organisation owners|Owners of organisations]].
|type=info}}

We recommend setting up emergency access with at least 1 other person, this is for safety if you lose access to your account.

First, ask your trusted contact to create a VaultTub account. Once they have done that, head to [https://vault.bathcs.com/#/settings/emergency-access Emergency access settings] and click “Add emergency contact”. Enter the user's email and ask them to follow the instructions they receive via email. Once all the steps are complete, go back to the Emergency access tab and verify that they show up as expected.

{{Note|type=warn|text=Make sure you verify that the user was added completely. It is easy to accidentally forget a step.}}

Emergency access is required for users with a significant amount of power due to the risk of losing everything (we cannot recover your passwords).

=== Using the extension/app ===

Bitwarden has a [https://bitwarden.com/download/#downloads-web-browser browser extension] and an [https://bitwarden.com/download/#downloads-mobile app] which support self-hosted instances (and multiple accounts).

{{Note|text=
If you wish, you can also set it up so you can approve sign-in requests when signing in somewhere else, which you may prefer over TOTP 2FA.
}}

To install the app or the extension:

* Download the extension, from [https://bitwarden.com/download/#downloads-web-browser Bitwarden’s download page]
* Open it up
** if you already have an account you can click the profile icon and then click “Add account”.
* Under the input for the email address (set to “bitwarden” by default), you can select “self-hosted”.
* Input “https://vault.bathcs.com” for the server field and hit “Save” in the top right.
* Enter your login details for VaultTub.

==== Recommended settings ====

You may wish to change the default lockout period or add a pin, which can be done in the “Settings tab”. These are handled on a '''per account''' basis.

You can click “unlock with pin” and enter a pin (unchecking “unlock with master on browser restart” if you don’t want that).

You can also change the “Vault timeout”, however this is '''not''' recommended.

==== Adding a Login ====
You can easily add a login by clicking the "New" button within the app, and filling out the details, along with the "website". Please make sure the owner is set to the society this login should live under, as well as a collection set.

From this interface you can also generate a password to fill in. The recommneded settings are:

* >= 25 characters
* include special characters
* min numbers: 2
* min special characters: 2

== Organisation owners ==

Make sure you have at least two owners to an organisation. This is to make sure we don’t lose access to the data.

For societies we recommend roles equivalent to chair and secretary. For other initiatives, we recommend you choose two people to act as the Owner.

{{Note|text=
For security reasons, please do not grant access to external users unless necessary. Make sure to keep data secure, especially where sensitive or personal data is involved.
}}

Owners also require [[#Emergency Access|emergency access]] to be set up with someone who is not another owner of their organisation.

== Organisations ==
To create an organisation, you can go to your “vaults” and click the “New organization” button on the side panel.

Once created you can go to the “Organizations” tab in the top right and choose the organisation to manage, where you can invite new members (via “Members > Invite Member”) or create a new collection (basically a folder which you can choose who has access to it).

For each member you can choose the role and what collections they have permission to access, the rest is up to you on how you organise everything.

{{Note|text=
When adding members, they will have to accept the invitation and then you will have to confirm them in the organisation interface.
}}

== Handover procedures ==
{{Stub}}
We need some instructions here on how to do handover. See the [https://boss.bathcs.com/handover/permissions/ old instructions] in the meantime.

=== Rotating passwords ===

As part of the handover procedures, it is recommended that each initiative rotates all the passwords stored in the organisation.

To do this, please follow these rough instructions:

<ul>
<li>Open the item on VaultTub (either by the extension or website)</li>
<li>Copy the password and temporarily store it somewhere (e.g. in the notes section)</li>
<li>Visit the website</li>
<li>Navigate to the change password section (it’s different for every website)</li>
<li>On the extension, click “edit” on the item and click the “Generate Password” button and confirm that it will override the current stored password. For password security recommendations see [[Passwords]], in general, make passwords long and random (or use passphrases). Password managers are designed to make it easy to use such random passwords.
<li>Click “Save” on the item to save the new password</li>
<li>Paste the new password in the change password fields + change the password</li>
<li>Log out and log in again to make sure the new password has saved correctly</li>
<li>Delete the temporary storage of the old password</li>
<li>Add a line to the notes saying it was updated on the current date and include your name</li></ul>

== How to deal with the worst case scenarios ==

If it is relating to the website being down, please contact [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk] (CC [mailto:pcs47@bath.ac.uk pcs47@bath.ac.uk] if urgent). Note that BOSS do not have any access to any of the data stored as it is all encrypted.

=== I lost my password and don’t have Emergency Access ===

In that case, there is nothing you can do. Your account must be deleted and you will need to be re-invited (this means you WILL lose access to any passwords you have stored outside of organisations). Organisations passwords can be recovered by other members of the organisation.

This is why you MUST either know your password by hand or store your password in your own password manager which also has a proper recovery procedure.

=== The owner of the organisation is not responding ===

If all [[#Quick note on owners|owners of the organisation]] are not responding or have lost access to their account, this is slightly more of an issue so make sure to have multiple owners.

The organisation will have to be deleted and recreated. To save as many passwords as possible, get all other members to see what Collections they have access to and if they have permission to export the vault (found in the settings for the organisation).

You want to then either export the vault data or copy every single password into a new organisation.

== Creating new organisations ==
All student groups (including non-SU groups) are welcome to have organisations to share passwords as we believe in good password policies. However, only BOSS committee can create a new organisation for you, and so please submit a request by emailing [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk].

They can do this through the [https://vault.bathcs.com/admin/users/overview admin interface] in the "Organisation" tab (however this interface is normally turned off and so has to be activated through a redeployment).

== Technical details ==

=== Backups ===

Backups are handled by [[Bath Open Source Society|BOSS]] and is one of the few systems that get a complete off-site backup on a third-party service along with the typical whole cluster backups.

But the basic idea:

* VaultTub get's backed up every 4 hours to our backup server.
* The whole cluster get's backed up every day to our backup server
* The specific VaultTub data (including passwords), gets backed up to [https://www.scaleway.com/en/ Scaleway] every day

Contact [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk] if you have any questions. You can also see [https://gitlab.bath.ac.uk/cs/int/terraform/ our configuration within terraform].

=== Emails ===

Emails are sent through the BOSS SMTP server. If you find they are going to junk, please contact [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk].

VaultTub

2026-06-11T22:32:32Z

Pcs47: /* How to deal with the worst case scenarios */ Add CC to me if urgent.

VaultTub is a password manager managed by [[Bath Open Source Society]] which allows societies to store and share passwords securely. It can be accessed at [https://vault.bathcs.com vault.bathcs.com].

For more detailed instructions, see [https://bitwarden.com/help/ BitWarden’s documentation].

== Quick setup ==

You should be messaged or told by the previous committee that you need to sign up so they can invite you. All Bath students can freely make an account (though we ask you not to store your personal passwords on there).

<ol style="list-style-type: decimal;">
<li>Go to [https://vault.bathcs.com vault.bathcs.com].</li>
<li>Enter your uni email and click "Use single sign-on".</li>
<li>Once redirected to our authentication site (Authelia), enter your University username and password.</li>
<li>You will be redirected back to VaultTub and asked to create a master password. Use a brand new password that you will not forget.{{Note|text=If you lose the master password you will lose all access to VaultTub.|type=warn}}</li>
<li>You may also receive emails during this process, if the email is in '''junk''', there should be a dropdown at the top of the email with the option to make “vault@bathcs.com” never go to your junk folder. Please select this as you will get a lot more emails after this point.</li>
<li>'''Required''': [[#Two-step login|Set up 2FA]]</li>
<li>'''Required''' '''for [[VaultTub#Organisation owners|Owners of organisations]]''': set up [[#Emergency Access|emergency access]]</li></ol>

Outgoing committees/initiatives will add you to the relevant organisation as described in the handover procedure. Please ensure that they do this, otherwise you will lose all access to the society's passwords.

== Recommended Settings ==

Once you have signed up with a password you can remember (but don’t use anywhere else), we recommend updating the following settings:

Settings can be found: “Profile Icon in top right > account settings”.

=== Two-step login ===

{{Note|type=info|text=
Two-factor authentication is '''mandatory''' for everyone.
}}

Go to [https://vault.bathcs.com/#/settings/security/two-factor Two-step login settings] and choose a provider. For the best security we recommend Authenticator app or Passkey.

=== Emergency access ===

{{Note|text=
Emergency access is '''mandatory''' for all [[#Organisation owners|Owners of organisations]].
|type=info}}

We recommend setting up emergency access with at least 1 other person, this is for safety if you lose access to your account.

First, ask your trusted contact to create a VaultTub account. Once they have done that, head to [https://vault.bathcs.com/#/settings/emergency-access Emergency access settings] and click “Add emergency contact”. Enter the user's email and ask them to follow the instructions they receive via email. Once all the steps are complete, go back to the Emergency access tab and verify that they show up as expected.

{{Note|type=warn|text=Make sure you verify that the user was added completely. It is easy to accidentally forget a step.}}

Emergency access is required for users with a significant amount of power due to the risk of losing everything (we cannot recover your passwords).

=== Using the extension/app ===

Bitwarden has a [https://bitwarden.com/download/#downloads-web-browser browser extension] and an [https://bitwarden.com/download/#downloads-mobile app] which support self-hosted instances (and multiple accounts).

{{Note|text=
If you wish, you can also set it up so you can approve sign-in requests when signing in somewhere else, which you may prefer over TOTP 2FA.
}}

To install the app or the extension:

* Download the extension, from [https://bitwarden.com/download/#downloads-web-browser Bitwarden’s download page]
* Open it up
** if you already have an account you can click the profile icon and then click “Add account”.
* Under the input for the email address (set to “bitwarden” by default), you can select “self-hosted”.
* Input “https://vault.bathcs.com” for the server field and hit “Save” in the top right.
* Enter your login details for VaultTub.

==== Recommended settings ====

You may wish to change the default lockout period or add a pin, which can be done in the “Settings tab”. These are handled on a '''per account''' basis.

You can click “unlock with pin” and enter a pin (unchecking “unlock with master on browser restart” if you don’t want that).

You can also change the “Vault timeout”, however this is '''not''' recommended.

==== Adding a Login ====
You can easily add a login by clicking the "New" button within the app, and filling out the details, along with the "website". Please make sure the owner is set to the society this login should live under, as well as a collection set.

From this interface you can also generate a password to fill in. The recommneded settings are:

* >= 25 characters
* include special characters
* min numbers: 2
* min special characters: 2

== Organisation owners ==

Make sure you have at least two owners to an organisation. This is to make sure we don’t lose access to the data.

For societies we recommend roles equivalent to chair and secretary. For other initiatives, we recommend you choose two people to act as the Owner.

{{Note|text=
For security reasons, please do not grant access to external users unless necessary. Make sure to keep data secure, especially where sensitive or personal data is involved.
}}

Owners also require [[#Emergency Access|emergency access]] to be set up with someone who is not another owner of their organisation.

== Organisations ==
To create an organisation, you can go to your “vaults” and click the “New organization” button on the side panel.

Once created you can go to the “Organizations” tab in the top right and choose the organisation to manage, where you can invite new members (via “Members > Invite Member”) or create a new collection (basically a folder which you can choose who has access to it).

For each member you can choose the role and what collections they have permission to access, the rest is up to you on how you organise everything.

{{Note|text=
When adding members, they will have to accept the invitation and then you will have to confirm them in the organisation interface.
}}

== Handover procedures ==
{{Stub}}
We need some instructions here on how to do handover. See the [https://boss.bathcs.com/handover/permissions/ old instructions] in the meantime.

=== Rotating passwords ===

As part of the handover procedures, it is recommended that each initiative rotates all the passwords stored in the organisation.

To do this, please follow this rough instruction list:

<ul>
<li>Open the item on VaultTub (either by the extension or website)</li>
<li>Copy the password and temporarily store it somewhere (e.g. in the notes section)</li>
<li>Visit the website</li>
<li>Navigate to the change password section (it’s different for every website)</li>
<li>On the extension, click “edit” on the item and click the “Generate Password” button and confirm that it will override the current password stored then
Password recommendations:
<ul>
<li>>= 25 characters</li>
<li>include special characters</li>
<li>min numbers: 2</li>
<li>min special characters: 2</li>
<li>uncheck “avoid ambiguous characters”</li></ul></li>
<li>Click “Save” on the item to save the new password</li>
<li>Paste the new password in the change password fields + change the password</li>
<li>Log out and log in again to make sure the new password has saved correctly</li>
<li>Delete the temporary storage of the old password</li>
<li>Add a line to the notes saying it was updated on the current date and include your name</li></ul>

== How to deal with the worst case scenarios ==

If it is relating to the website being down, please contact [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk] (CC [mailto:pcs47@bath.ac.uk pcs47@bath.ac.uk] if urgent). Note that BOSS do not have any access to any of the data stored as it is all encrypted.

=== I lost my password and don’t have Emergency Access ===

In that case, there is nothing you can do. Your account must be deleted and you will need to be re-invited (this means you WILL lose access to any passwords you have stored outside of organisations). Organisations passwords can be recovered by other members of the organisation.

This is why you MUST either know your password by hand or store your password in your own password manager which also has a proper recovery procedure.

=== The owner of the organisation is not responding ===

If all [[#Quick note on owners|owners of the organisation]] are not responding or have lost access to their account, this is slightly more of an issue so make sure to have multiple owners.

The organisation will have to be deleted and recreated. To save as many passwords as possible, get all other members to see what Collections they have access to and if they have permission to export the vault (found in the settings for the organisation).

You want to then either export the vault data or copy every single password into a new organisation.

== Creating new organisations ==
All student groups (including non-SU groups) are welcome to have organisations to share passwords as we believe in good password policies. However, only BOSS committee can create a new organisation for you, and so please submit a request by emailing [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk].

They can do this through the [https://vault.bathcs.com/admin/users/overview admin interface] in the "Organisation" tab (however this interface is normally turned off and so has to be activated through a redeployment).

== Technical details ==

=== Backups ===

Backups are handled by [[Bath Open Source Society|BOSS]] and is one of the few systems that get a complete off-site backup on a third-party service along with the typical whole cluster backups.

But the basic idea:

* VaultTub get's backed up every 4 hours to our backup server.
* The whole cluster get's backed up every day to our backup server
* The specific VaultTub data (including passwords), gets backed up to [https://www.scaleway.com/en/ Scaleway] every day

Contact [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk] if you have any questions. You can also see [https://gitlab.bath.ac.uk/cs/int/terraform/ our configuration within terraform].

=== Emails ===

Emails are sent through the BOSS SMTP server. If you find they are going to junk, please contact [mailto:su-boss@bath.ac.uk su-boss@bath.ac.uk].

Where to go when you don't know where to go

2026-06-08T13:03:18Z

Pcs47: Replace with page from penn/mediawiki generated through pandoc.

== Emergencies ==

If there is an emergency on campus call 01225 38 3999. Anywhere else, call 999. Keep calm and keep safe.


== Mental Health Support ==

The University offers a large variety of support for mental health struggles. This document outlines the services you may want to refer someone to depending on how worried you are about them.

'''If a student seems in any kind of immediate danger, follow the [https://www.bath.ac.uk/guides/supporting-students-in-distress/ supporting students in distress] guide. Keep yourself safe.'''


=== 1. General Support ===

If you feel like a student needs a bit of a cheer up, some advice or something to break them out of a bit of a torrid time, these services may be of help!

<ul>
<li>Director of Studies Team
Academic guidance, as well as a great pillar of support. The DoS team has all the answers to potential academic questions, from guidance on suspensions to further signposting. They are useful for the academic side, but are not mental health professionals.
<ul>
<li>John Bernadis, Director of Studies Year 1 and 2, [https://researchportal.bath.ac.uk/en/persons/john-benardis ib322@bath.ac.uk]</li>
<li>Moody Alam, Director of Studies years 3 and above, [https://researchportal.bath.ac.uk/en/persons/moody-alam ma3145@bath.ac.uk]</li>
<li>[https://www.bath.ac.uk/teams/department-of-computer-science-academic-staff/ Full DoS list]</li></ul></li>
<li>Support Groups
There are multiple support groups available for students going through hardship and feeling isolated but these are poorly advertised. If a student seems to be going through one of these situations, a gentle push in this direction may provide some company in times for which they do not want to be alone.
<ul>
<li>[https://www.bath.ac.uk/campaigns/autism-social-group/ Autism Support Group]</li>
<li>[https://www.bath.ac.uk/campaigns/bereavement-social-group/ Bereavement Social Group]</li>
<li>[https://www.bath.ac.uk/campaigns/social-networking-group/ Loneliness Networking Group]</li>
<li>Low mood (but be aware this could be a sign of a deeper issue):
<ul>
<li>[https://www.bath.ac.uk/guides/social-prescribing-at-bath/ Social prescribing]</li>
<li>[https://www.bath.ac.uk/guides/courses-and-workshops-for-better-mental-health/ Courses and workshops for better mental health]</li></ul></li>
<li>[https://www.bath.ac.uk/guides/getting-support-if-you-or-someone-else-is-feeling-lonely-or-isolated/ More information]</li></ul></li>
<li>The Roper Centre
The Roper Centre in 4 West is open every weekday in term-time, 9am to 5pm. They can provide advice and are very friendly and approachable. If you feel like a student would benefit from support, but they aren’t willing to seek it themselves, you can also go to the Roper Centre to see if there’s anything they can do. they won’t compel anyone to get help, but they can reach out and they can also support you as a Student Leader. Remember if there is a risk of immediate harm you should follow the [https://www.bath.ac.uk/guides/supporting-students-in-distress/ supporting students in distress] guide.</li></ul>


=== 2. Longer Term Support ===

Sometimes students show signs of underlying problems that you feel may warrant some longer-term support, or at the very least a consultation about the topic, and sometimes a student will ask you for this directly. These are the services available to us as students and residents of Bath.

<ul>
<li>The Wellbeing Team
The University’s wellbeing team offers short term counselling sessions after an initial consultation, usually 6 weekly sessions with the hope that these will be enough to help a student. The University has in-house consellors and is partnered with outside organisations as well. These include one that offers culturally-appropriate counselling targeted specifically at students from Black, Asian, and minoritized communities.
<ul>
<li>[https://www.bath.ac.uk/guides/mental-health-support-at-the-university/ University Signposting]</li>
<li>[https://www.bath.ac.uk/guides/talking-therapies-at-the-university/ Bath Talking Therapies]</li>
<li>[https://www.bath.ac.uk/campaigns/culturally-sensitive-counselling/ Culturally Sensitive Counselling (External)]</li>
<li>[https://www.bath.ac.uk/guides/booking-a-wellbeing-appointment/ University Wellbeing Booking]</li></ul></li>
<li>External Methods
Honestly, it’s probably a better idea to point students to university-affiliated services first, but if that fails, Bath has multiple organisations that also offer support, though a lot of them require registration with a local GP.
<ul>
<li>'''BaNES IAPT (Bath and Northeast Somerset Increasing access to psychological therapies)'''
A Bath-based service, similar to the University’s, this service often offers 6-week sessions of 1-on-1 counselling before deciding whether you may need more, but as it is an NHS, may have an annoyingly long waiting list. They focus on Cognitive Behavioural Therapy.
<ul>
<li>[https://iapt.awp.nhs.uk/talking-therapies-banes BaNES IAPT Website]</li></ul></li>
<li>'''Bath Minds'''
Another service that provides similar services to BaNES IAPT, though they are a slightly larger organisation and are a charity that offer more than just counselling, such as wellbeing groups centred around common hobbies like football.
Link: [https://www.bathmind.org.uk/1-to-1-mental-health-support/ Bath Minds website]</li>
<li>'''Off the record'''
A charity that also offers similar counselling services, as well as advocacy groups and LGBTQ+ support, this is sometimes a group that the university refers students to after wellbeing’s initial evaluation.
[https://www.offtherecord-banes.co.uk/ Off the Record’s website]</li>
<li>'''NHS'''
The NHS is also a method for which to pursue counselling and long-term therapies, though the waitlist is long.
[https://www.nhs.uk/mental-health/ NHS Mental Health]</li></ul>

Honestly, there are probably a lot more, but this just goes to show that there is support, though waitlists are a constant annoyance in all such services. The University has a [https://www.bath.ac.uk/guides/counselling-and-therapy-services-in-the-bath-area/ list of services in the area] with many specialised services, located in both Bath and Bristol.</li></ul>


=== 3. Immediate Help ===

There are also services for which a student can get immediate advice and help:

<ul>
<li>[https://www.bath.ac.uk/campaigns/be-well-talk-now/ Be Well - Talk Now]
A phone line that the University has hired a third party to run (they specialise in providing mental health support for businesses and universities). They are open to both call and live chat 24/7 and offer both domestic and international service. They have multilingual advisors and the ability to refer cases that need more help to where they need to go. As they are available by phone, this is a service that could be very useful.
<ul>
<li>Phone in the UK: 0808 196 8046</li>
<li>Phone outside the UK: +44 3 307771499</li>
<li>[https://talknow.spectrum.life/login?org=talknow Live chat] is available</li></ul></li>
<li>[https://giveusashout.org/ Give us a Shout]
A UK text-based support service available [sms://85258?&body=SHOUT texting SHOUT to 85258]. They are available 24/7 but not student focussed.</li>
<li>Campus Security
If things have gotten bad, and practical advice is needed, for example if an ambulance is needed, a student is lost or an accident has occurred, campus security is a good place to call. They will be able to help an ambulance navigate campus better than any student; they are always useful in a pinch.
<ul>
<li>'''Emergency number: 01225 383999'''</li>
<li>'''General number: 01225 385349'''</li></ul></li>
<li>[https://www.papyrus-uk.org/papyrus-HOPELINE247/ Papyrus Hopeline]
Available via either web chat or phone call, Papyrus is a service for anyone experiencing suicidal thoughts; they provide a safe space to talk about anything affecting their ability to stay safe.</li>
<li>999/111
999 and 111 are also an important resource to remember, if things are looking real bleak, 999 offer support in life threatening conditions while 111 offer support in situations of when you’re unsure who to call and how serious things are.</li></ul>


=== 4. Other resources ===

While these are all important, there are other sources of support available to students that may be helpful to know about! For example:

* '''[https://www.bath.ac.uk/guides/courses-and-workshops-for-better-mental-health/ Five-week courses/workshops to improve specific aspects of mental health]'''
* '''[https://www.bath.ac.uk/campaigns/read-well/ Library Mental health reading program]'''
* '''[https://www.talkofftherecord.org/get-info/apps/ A huge variety of support apps, including support for people at risk of self-harm and suicide (as a supplement to support from professionals)]'''
* '''[https://www.thesubath.com/advice/personal/ SU support page (personal issues)]'''
* '''[https://www.bath.ac.uk/professional-services/chaplaincy/ Spiritual guidance]'''
* '''[https://www.thesubath.com/peer-support Peer support]'''
* '''[https://studentspace.org.uk/ Student Space]''' which provides guidance and FAQs for dealing with mental health as a student
* '''[https://www.bath.ac.uk/corporate-information/wellbeing-support-out-of-hours A list of out-of-hours support available]''' maintained by Student Support

-----

Overall, there are so many resources you can point students towards. It is important to remember that as Student Leaders, you may be put in a position where you are asked to provide help. That’s fine, but it’s important not to get out of your depth! There are many professionals we can rely on to help our fellow students work through their problems, and our job on that front is to make sure students can get access to the help they need (even if we are sometimes those students as well)!


== Financial Support ==

The financial support the university offers can mostly be split into advice and money. In general terms, they can offer [https://www.bath.ac.uk/guides/making-an-appointment-or-attending-a-drop-in-session-with-student-money-advice/ 1-on-1 meetings about financing]


=== [https://www.bath.ac.uk/guides/managing-your-money/ Money Advice] ===

There are a lot of resources available, which can be listed on [https://www.bath.ac.uk/guides/managing-your-money/ the Money Advice page]. However, it is very dense, so what follows is a breakdown and grouping of the advice. I’d recommend skimming the page anyway as it’s useful stuff beyond this summary.


==== Funding support ====

The University directs to the various devolved student finance websites:

* [https://www.gov.uk/student-finance England]
* [https://www.studentfinancewales.co.uk/ Wales]
* [https://www.saas.gov.uk/ Scotland]
* [https://www.studentfinanceni.co.uk/ Northern Ireland]

Separate guidance for non-UK students is also given. They also link to support when opening a student bank account:

* [https://www.moneyhelper.org.uk/en/family-and-care/student-and-graduate-money/student-and-graduate-bank-accounts?source=mas money advice service]
* [https://www.moneysavingexpert.com/students/student-bank-account/ money savings expert]

There is further guidance on opening a [https://www.moneyhelper.org.uk/en/savings/types-of-savings/sharia-compliant-savings?source=mas# Shari’a compliant account] for those whose religious beliefs go against the idea of paying or charging interest, such as Islam. The University also offers emergency funds, more of which can be found in the following section.


==== Monetary Aid ====

The university offers funding to students in two forms, '''short term loans''' and the '''hardship fund'''.

The [https://www.bath.ac.uk/campaigns/short-term-loans/ short term loans] can be applied to by students for up to 300 pounds, or 500 pounds if they have dependents. It is discretionary and usually not awarded during the last 2 months of the academic year. They are interest-free and usually due within 2 months, or when the next loan instalment is due, whichever is sooner, although a student can apply for longer through the [https://www.bath.ac.uk/guides/making-an-appointment-or-attending-a-drop-in-session-with-student-money-advice/ money advice team].

The [https://www.bath.ac.uk/guides/applying-for-the-university-of-bath-hardship-fund/ hardship fund] is available to both home and international students, but does require students to have applied for the maximum amount of maintenance available to them. This means that effectively, if you’re a UK student you need to have applied to and achieved the max maintenance loan for your household income. They take about a month to make a decision and the idea is that they help with financial hardship, though for international students this must be considered unexpected, as they don’t help with tuition fees or similar. It’s a tricky process but the maximum award is 3500 pounds.


==== Budgeting ====

There is budgeting support available through the University:

* [https://www.bath.ac.uk/guides/managing-your-money/ blackbullion financial toolkit]
* [https://www.bath.ac.uk/publications/managing-your-money/attachments/managing-your-money-factsheet.pdf money management factsheet]
* and more on [https://www.bath.ac.uk/guides/managing-your-money/ the Money Advice page]


== Dignity and Respect ==

The University has a ''very'' wide range of options available for students who are being made to feel uncomfortable.


=== Mental health support ===

If someone is being made uncomfortable by others this can have a severe impact on their mental health. Read through the signposting steps in the mental health section before progressing.


=== Support and Report ===

Support and Report is a bit of a misnomer: there is no obligation to report anything officially, or to start a formal enquiry.


==== What to report ====

Anything that makes a member of the University uncomfortable can be reported on Support and Report. This includes incidents that occur off campus or online, or involve non-University people. Reports can be made anonymously, by bystanders, through a friend or directly by a student. Reports do not have to be about a specific incident; it could be a repeated pattern of behaviour, or microaggressions.


==== What happens next ====

Each report is handled individually. Making a report does not automatically start a misconduct inquiry. All reports are confidential and are not shared without the explicit permission of the student (except if there is an immediate threat).

Even after making a report through Support and Report, no pressure is applied to continue with any formal or non-formal interventions. The default action is to simply log the incident and take no further action.

Some narrow examples of outcomes could include, but are not limited to:

* Log the incident and take no specific action (the information can be used to focus future preventative work)
* Log the incident and get back in touch if it happens again (including with other students)
* Log the incident and get back in touch after a certain amount of time
* Referral to mental health support
* Action within the academic department (the department is not told of the reason for changes, but this could include separation in group courseworks or lab groups)
* Action with Student Living
* Contact with external organisations and/or the police
* Non-formal interviews
* Imposing mandatory training on people
* Triggering Student Discipline procedures

The key thing is that none of these will happen without the permission of the subject!

If the person who experienced the discomfort does not want to make a report, a committee member can do this, either on behalf of the person, or as a bystander. In the latter case, no action is taken, but options for action can be suggested to the committee member, who can pass this on to the subject.

Git/Advanced

2026-06-08T12:43:50Z

Pcs47: Recommend --force-with-lease (https://gitlab.bath.ac.uk/cs/services/wiki/-/work_items/33)

Git is a really powerful command line tool when you start looking into the advanced things you can do, but when maintaining or developing a project, you are probably not going to touch most of them. This is a list of ones which I use on a regular basis.

It’s important to note that the more advanced commands can have quite powerful functions which can lose code if used incorrectly. However, in most cases git caches a significant amount, so if you lose a commit or some changes, '''don’t panic''' and look up your issue (someone has done this before and found a way to get the changes back).

== More on Commit IDs ==

Where it says to use the <code>commit-id</code>, there are different inputs you can use to specify multiple commits easily.

Let A and B be the ids for two different commits. To reference a range you can do:

* A to B (including A): <code>A^..B</code>
* A to B (excluding A): <code>A..B</code>

Or you can specify the last <code>X</code> commits:

* <code>HEAD~X</code> e.g. <code>git reset --soft HEAD~4</code>

== Stashing ==

Stashing is used when you want to record the current state of the working directory and the index, but want to go back to a clean working directory.

It allows you to set aside some changes for later or just never commit them (without altering the [[Git/Special files#Gitignore|<code>.gitignore</code> file]]).

By stashing your changes, they will be removed so you can no longer see them, but you can always <code>pop</code> or <code>apply</code> the stash to get the back at any point.

=== Commands ===

<syntaxhighlight lang="sh">git stash # Stash current unstaged (but tracked) changes
git stash apply # Restore the last stash without deleting it
git stash pop # Restore the last stash and delete it
git stash list # List the stashed changes
git stash show # Inspect the stashed changes</syntaxhighlight>

{{Note|type=reminder|text=
GUI tools e.g. lazygit or VSCode (with git extension pack) normally have a better interface for adding and removing stashes - so probably use that instead.
}}This is usually used with <code>git switch</code> or <code>git checkout</code> to allow you to switch branches when you still have uncommitted changes that may conflict.

== Reverting vs Resetting ==

To either reset or revert, you need the git commit hash id (or the start of it), this can be done via <code>git log</code>.

Once you have that, the interface is quite similar:

<syntaxhighlight lang="sh">git reset commit-id
git revert commit-id</syntaxhighlight>
They both do the same thing of reverting the changes from the given commit. But the difference is, <code>revert</code> will create a new commit (therefore you can just run <code>git push</code> or merging without any issues), whereas <code>reset</code> will remove those commits outright.

When resetting, the tree (simply, the list of commits) itself is altered. This means that when pushing to a repo which already contains that commit, you have to use <code>git push --force-with-lease</code>. This will cause anyone else working on the same branch to lose their changes, as they are forced to run <code>git pull --force</code>. There also exists <code>git push --force</code>, but <code>--force-with-lease</code> won't apply changes if the remote has commits that you don't have locally. Therefore, <code>--force-with-lease</code> is preferred.

This command is dangerous so make sure you check everything before using it as it forces the upstream to be exactly like your local branch. So if you accidentally removed the wrong commit, you cannot easily get it back.

=== Extra options ===

With <code>reset</code> you also have extra options which you may find useful. You can either use <code>--soft</code> (Put all the changes of the commit in staged) or <code>--hard</code> (which is the default, just forget all changes).

With <code>revert</code> you can use <code>--no-commit</code> which will put the inverse of the changes in staged (and not create a new commit). This allows you to add multiple reverts or more changes in it.

== Rebasing ==

Rebasing is used when commits have been added to <code>main</code> and you want to bring them to your branch (with was branched off of <code>main</code>).

To rebase off of main (when you are in your branch), you can run:

<syntaxhighlight lang="sh">git rebase main</syntaxhighlight>
{{Note|text=
As we are changing the structure of the commit tree, you must then run <code>git push --force-with-lease</code> once you are 100% happy none of your changes have been lost.

As usual, if there is anyone else using your current branch, you shouldn’t do this.
}}

The steps it is takes are:

* Temporarily reset all your commits which you added to this branch
* Apply all the new commits in <code>main</code> (or the given branch)
* Re-apply all of your commits

=== Dealing with Conflicts ===

Sometimes there may be conflicting changes from the changes added to main (e.g. you’ve changed the same line as another change).

This is when it gets quite confusing and dangerous.

If this happens, git will print out an error, saying what files are are in conflict and where to find them.

If you run <code>git status</code> you will see that some files are staged and some are not. The idea for these are:

* '''Staged files''': These are the files which are not conflicting and will be committed on <code>git rebase --continue</code>.
* '''Unstaged files''': These are the files with conflicts

If you open one of the conflicting files you will find that git has altered it where the conflicts are.

The format is:

<pre class="txt"><<<<<<< HEAD
- Auto writing README
- A cool logo - hw
- who's the above guy?
=======
- something
- A cool logo - hw
- other
>>>>>>> 8f309e1 (Test commit)</pre>
{{Note|text= class="note">
VSCode has its own custom interface for this [https://code.visualstudio.com/docs/sourcecontrol/overview#_3way-merge-editor read more here]
}}

You will see the changes you made are below the <code>=======</code> and the (updated) upstream code in <code>main</code> is above it.

What you have to do is, for each of these conflicts, to choose which one to keep (or create a mixture). To do this, you just remove everything that shouldn’t be there (which includes <code><<<<<<< HEAD</code>, <code>=======</code>, etc). For example, in this case it should result in:

<pre class="txt">- Auto writing README
- something
- A cool logo - hw
- other
- who's the above guy?</pre>
Once you are happy an entire file is now conflict-free and correct, you can stage it.

Then once there are no unstaged files left you can run <code>git rebase --continue</code>, which will save the changes under the original commit (sometimes it will ask you to confirm the commit message with your editor, you can just save and exit it).

Once you have finished rebasing, make sure to test that your code still works. It’s common for code to break after rebasing due to unexpected changes made by someone else.

=== Interactive Rebase ===

Interactive rebasing is one of the most powerful and fun commands ever. However it comes with the downside of it being quite dangerous.

It is used for reorganising a merge request and managing commits to clean up the git log.

To use it:

<syntaxhighlight lang="sh">git rebase -i HEAD~X
# Or interactive rebase off of main
git rebase -i main</syntaxhighlight>
This should bring up your default text editor with a list of commits with a list of commands at the end, which looks like:

<pre>pick af44004 Annoying rebasing commit
pick ceb4454 Add quote from Varnie
pick 1f156e8 Test commit

# Rebase 315c076..1f156e8 onto 315c076 (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
# commit's log message, unless -C is used, in which case
# keep only this commit's message; -c is same as -C but
# opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# create a merge commit using the original merge commit's
# message (or the oneline, if no original merge commit was
# specified); use -c <commit> to reword the commit message
# u, update-ref <ref> = track a placeholder for the <ref> to be updated
# to this position in the new commits. The <ref> is
# updated at the end of the rebase
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#</pre>
You can see all the commits which will be re-applied after the branch has been rolled back and commits from main been added.

These all have the word <code>pick</code> infront of them, meaning they will be committed as is, with the same message, and no editing happening.

You can look over the other commands to see what you can do, but how it works is by replacing <code>pick</code> with something else, e.g. <code>fixup</code> or <code>reword</code>.

=== The Fixup Commit ===

This is a weird option when committing, that can be useful when you have an MR and you are wanting to keep a neat commit log, but are responding to review feedback.

How this works, is lets say you’ve fixed something with a previous commit in your MR and were wanting to (when merging) squash this fix into that commit. But you want to have it as a separate commit to help the reviewer to see that you have fixed it.

To do this you simply run:

<syntaxhighlight lang="sh">git commit --fixup="amend:<git_commit_id>"</syntaxhighlight>
Which will create a new commit with the message:

<pre>amend! Add information for publicising events from BCSS and where to go

> Add information for publicising events from BCSS and where to go</pre>
Which you can then push as its own commit.

Then when you come to merge you can run:

<syntaxhighlight lang="sh">git rebase -i main --autosquash</syntaxhighlight>
Which will automatically move your amend commit to be <code>fixup</code> above the commit you were amending.

== Merging ==

Normally merging is done via the interface on the remote repository system you are using. However it can be done in the command line as well (it can also be used in place of <code>rebase</code> so you don’t have to use the dangerous <code>git push --force-with-lease</code>).

It copies all the commits which have been added on a branch to the branch you are currently on (e.g. <code>main</code>).

So the process to merge a branch into main is:

<syntaxhighlight lang="sh">git checkout main
git merge branch-name
git branch -d branch-name # Deletes the branch If you don't need the branch any
# more
git push</syntaxhighlight>
Conflicts can still happen, see [[Git/Advanced#dealing-with-conflicts|above]] for more information about how to manage them.

{{Note|text=
When merging, cherry-picking or other, and you are dealing with conflicts you need to use the subcommand with <code>--continue</code>, for example <code>git merge --continue</code> or <code>git cherry-pick --continue</code>.
}}

== Cherry-picking ==

Cherry picking allows you to bring a single commit (or multiple, see [[#more-on-commit-ids|here]]) from another branch to your current one.

To do this, it is as simple as:

<syntaxhighlight lang="sh">git cherry-pick commit-id
git push</syntaxhighlight>
== Submodules ==

Submodules are normally used in what is called a “monorepo”, a repo which stores multiple difference projects or git repositories.

It is also useful for refactoring some files. E.g. if you need the same files in multiple different projects (e.g. standardised tests or config files), it is common to add a “meta” repo which stores these projects, then add this as a submodule to each project which uses it.

To add a submodule you can run:

<syntaxhighlight lang="sh">git submodule add repo-url folder/to/store</syntaxhighlight>
This will clone the module inside the folder <code>folder/to/store</code> and will add a <code>.gitmodule</code> file in the base of the repo.

When cloning the repo on other devices, you must remember to recursively clone all the submodules as well via:

<syntaxhighlight lang="sh">git clone --recurse-submodules -j8 project-url</syntaxhighlight>

{{Note|text=
<code>-j8</code> is an performance optimisation see [https://stackoverflow.com/questions/3796927/how-do-i-git-clone-a-repo-including-its-submodules#4438292 this Stack Overflow answer]
}}

Or if you have already cloned the repo and were wanting to update all the submodules, you can run:

<syntaxhighlight lang="sh">git submodule update --init --recursive</syntaxhighlight>

=== Managing submodules ===

Once you have cloned a submodule, you will note that any time you pull the latest changes to it, you need to make another commit in the base repo with the update.

This is so that the submodules are locked on specific commits until you specifically say “yes this next commit is fine”.

== Extra Configuration ==

Sometimes there are configuration options that git will recommend when they become a problem, for example:

<syntaxhighlight lang="sh">git config --global pull.rebase true</syntaxhighlight>
This means that when pulling from a branch which has new changes, it will rebase instead of merging the new commits.

=== Commit Signing ===

Commit signing is used to verify if you are who you say you are when committing (e.g. with your email address).

I won’t go into much depth on this, instead just know it exists and is quite good practice to have but not necessary.

You can read more [https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits here].

Be aware that there are some consequences which come along with this:

* If you have setup a strict mode with signing, you cannot commit if you loose access to your signing key
* When rebasing your changes, you have to resign all the commits (meaning you are the only one who can do it)

== See also ==
{{Special:PrefixIndex|prefix=Git|namespace=0|hideredirects=1}}
[[Category:Tutorial]]