@ -0,0 +1,3 @@ |
||||
site/ |
||||
/venv/ |
||||
*.swp |
@ -0,0 +1,20 @@ |
||||
# docs |
||||
This is the repository for [https://docs.cloud.csclub.uwaterloo.ca](https://docs.cloud.csclub.uwaterloo.ca). |
||||
|
||||
## Contributing |
||||
This is a [MkDocs](https://www.mkdocs.org) site, so all pages are writen in Markdown. |
||||
|
||||
Install the prerequisites: |
||||
```sh |
||||
pip install mkdocs mkdocs-material pymdown-extensions |
||||
``` |
||||
|
||||
Start a local web server (http://localhost:8000): |
||||
```sh |
||||
mkdocs serve |
||||
``` |
||||
|
||||
Building the site: |
||||
``` |
||||
mkdocs build |
||||
``` |
@ -0,0 +1,167 @@ |
||||
# CloudStack |
||||
|
||||
[Apache CloudStack](https://cloudstack.apache.org/) is an open-source |
||||
cloud computing platform which we use to allow members to create their |
||||
own virtual machines (VMs). |
||||
|
||||
## Activating your cloud account |
||||
Before using CloudStack, you must activate your cloud account. |
||||
Log into any [general-use machine](https://wiki.csclub.uwaterloo.ca/Machine_List) |
||||
and run the following: |
||||
```sh |
||||
ceo cloud account activate |
||||
``` |
||||
Now visit [https://cloud.csclub.uwaterloo.ca](https://cloud.csclub.uwaterloo.ca) |
||||
and login with your CSC username and password. For the domain, just enter 'Members' |
||||
(no quotes). |
||||
|
||||
<img src="../img/cloudstack_login.png" alt="CloudStack login" width="400" /> |
||||
|
||||
## Account resource limits |
||||
As of this writing, the CloudStack resource limits for each member are: |
||||
|
||||
* 8 CPU cores |
||||
* 8 GB of RAM |
||||
* 40 GB of disk space |
||||
|
||||
If you wish to acquire more resources, please send an email to the Systems Committee |
||||
with a brief justification. |
||||
|
||||
## Adding your SSH key |
||||
You will want to do this *before* creating a VM. |
||||
|
||||
!!! note |
||||
|
||||
The rest of this section assumes that you already have an SSH key pair. |
||||
If you do not have one yet, please create one first; there are plenty |
||||
of good tutorials online on how to do this |
||||
([here](https://www.howtogeek.com/762863/how-to-generate-ssh-keys-in-windows-10-and-windows-11/) |
||||
is one example). |
||||
|
||||
Once you've logged into CloudStack, click on the 'Compute' button on the left-hand |
||||
panel (depending on how wide your screen is, you may only see a cloud icon), |
||||
then click 'SSH key pairs'. Click the 'Create a SSH Key Pair' button. |
||||
|
||||
<img src="../img/cloudstack_ssh_key_pair_button.png" alt="CloudStack SSH key pair button" width="800" /> |
||||
|
||||
Now you will need to add your public key (this is the contents of the file which ends |
||||
with '.pub'). |
||||
|
||||
You can name the key pair anything you like; just make sure you remember the name. |
||||
|
||||
<img src="../img/cloudstack_add_ssh_key_pair.png" alt="CloudStack add SSH key pair" width="400" /> |
||||
|
||||
Click OK once you have pasted your public key into the text box. |
||||
|
||||
## Creating a VM |
||||
Click on the 'Compute' button on the left-hand panel, then click 'Instances'. Click |
||||
the 'Add Instance' button. |
||||
|
||||
<img src="../img/cloudstack_add_instance_button.png" alt="CloudStack Add Instance button" width="800" /> |
||||
|
||||
Under the 'Template/ISO' section, choose the OS which you want your VM to run. |
||||
|
||||
!!! tip |
||||
|
||||
Don't see your favourite OS listed? No problem! Just send an email to the |
||||
[Systems Committee](mailto:syscom@csclub.uwaterloo.ca) requesting your OS |
||||
to be added. We require that the OS must already have a publically available |
||||
cloud image which has been prepared with [cloud-init](https://cloud-init.io/). |
||||
|
||||
**Important**: Make sure to toggle the 'Override Root Disk Size' option and set it |
||||
to something reasonable (see [Account resource limits](#account-resource-limits) for |
||||
the maximum disk space which you can use.) The default root disk size for cloud |
||||
images is usually very small (e.g. 2GB), so you will definitely want to change it. |
||||
|
||||
<img src="../img/cloudstack_root_disk_size.png" alt="CloudStack Root Disk Size" width="700" /> |
||||
|
||||
Now you need to choose a Compute Offering. If you are sure not sure how much |
||||
you need, we recommend that you start off with a Small or Medium instance; you |
||||
can always upgrade later if necessary. |
||||
|
||||
|
||||
<img src="../img/cloudstack_compute_offering.png" alt="CloudStack Compute Offering" width="700" /> |
||||
|
||||
You probably do not need to add an external disk. Be aware that if you do add one, |
||||
this counts towards your total disk quota. |
||||
|
||||
|
||||
<img src="../img/cloudstack_data_disk.png" alt="CloudStack Data Disk" width="700" /> |
||||
|
||||
Make sure that you do **NOT** place the VM in the default security group, because |
||||
this blocks all ingress traffic by default. |
||||
|
||||
<img src="../img/cloudstack_security_groups.png" alt="CloudStack Security Groups" width="700" /> |
||||
|
||||
Choose the SSH keypair which you created earlier: |
||||
|
||||
<img src="../img/cloudstack_choose_ssh_keypair.png" alt="CloudStack Choose SSH keypair" width="700" /> |
||||
|
||||
Enter a name for your VM: |
||||
|
||||
<img src="../img/cloudstack_vm_details.png" alt="CloudStack VM details" width="700" /> |
||||
|
||||
Now press 'Launch Virtual Machine'. |
||||
|
||||
If all goes well, you should see your VM running from the 'Instances' dashboard: |
||||
<img src="../img/cloudstack_running_instances.png" alt="CloudStack running instances" width="800" /> |
||||
|
||||
## Accessing your VM |
||||
All VMs will obtain an IP address from the 172.19.134.0/24 subnet (MC VLAN 425). |
||||
As this is a private IP range, you can only access this *directly* from on campus. If you |
||||
are not on campus, you can still access your VM via the following methods: |
||||
|
||||
* use the [Campus VPN](https://uwaterloo.ca/information-systems-technology/services/virtual-private-network-vpn) |
||||
* use a general-use CSC machine as a jump host |
||||
|
||||
The second option is generally more convenient. The idea is to SSH into a CSC |
||||
general-use machine first, then SSH from there into your VM. |
||||
|
||||
On any CSC general-use machine, copy your SSH key to the `.ssh` folder in your |
||||
home directory (e.g. via scp). Make sure that it is only readable by you (e.g. |
||||
run `chmod 600` on it). Running `ls -l ~/.ssh` should show something like this: |
||||
|
||||
total 16 |
||||
-rw-r--r-- 1 ctdalek ctdalek 918 Oct 14 12:05 authorized_keys |
||||
-rw-r--r-- 1 ctdalek ctdalek 25 Oct 27 14:03 config |
||||
-rw------- 1 ctdalek ctdalek 1896 Sep 3 18:23 id_rsa |
||||
-rw-r----- 1 ctdalek ctdalek 415 Sep 3 18:23 id_rsa.pub |
||||
-rw-r--r-- 1 ctdalek ctdalek 459 Nov 24 12:29 known_hosts |
||||
|
||||
Note how the `id_rsa` file is not world-readable. |
||||
|
||||
Now, from the CSC machine, you can SSH into your VM by running a command like the following: |
||||
```sh |
||||
ssh debian@172.19.134.121 |
||||
``` |
||||
Replace `172.19.13.121` with the IP address of your VM, and replace `debian` with the |
||||
default username of the OS which you chose: |
||||
|
||||
* Debian: `debian` |
||||
* Ubuntu: `ubuntu` |
||||
* CentOS: `centos` |
||||
|
||||
Once you have logged in, you can run `sudo -s` to become the root user. |
||||
|
||||
See [SSH tricks](../ssh-tricks) for some useful SSH tricks. |
||||
|
||||
## Next steps |
||||
Congratulations, you've created your VM! ...So what do you do now? |
||||
|
||||
That's completely up to you! Since you can become the root user inside the |
||||
VM, you can install and run any software you want (just keep in mind that |
||||
you must still follow the |
||||
[Machine Usage Agreement](https://csclub.uwaterloo.ca/resources/machine-usage-agreement/)). |
||||
|
||||
Here are some ideas to get you started: |
||||
|
||||
* Install [Docker](https://docs.docker.com/engine/install/) and run some containers |
||||
* Install [Apache](https://httpd.apache.org/) or [NGINX](http://nginx.org/) and |
||||
serve a static website (e.g. a blog) |
||||
* Run a Node.js/Python/Golang/whatever web application |
||||
* Install [k0s](https://k0sproject.io/) and run a small Kubernetes cluster |
||||
|
||||
The world's your oyster! 😊 |
||||
|
||||
If you plan on hosting a publicly available website, you will want to create |
||||
a virtual host. See [Virtual Hosting](../vhosts) for details. |
After Width: | Height: | Size: 42 KiB |
After Width: | Height: | Size: 76 KiB |
After Width: | Height: | Size: 32 KiB |
After Width: | Height: | Size: 67 KiB |
After Width: | Height: | Size: 46 KiB |
After Width: | Height: | Size: 45 KiB |
After Width: | Height: | Size: 54 KiB |
After Width: | Height: | Size: 46 KiB |
After Width: | Height: | Size: 33 KiB |
After Width: | Height: | Size: 36 KiB |
After Width: | Height: | Size: 37 KiB |
@ -0,0 +1,28 @@ |
||||
# Welcome to the CSC Cloud! |
||||
|
||||
The CSC cloud is a collection of compute, network and storage services |
||||
available to CSC members. |
||||
|
||||
## Available services |
||||
|
||||
* [CloudStack](cloudstack) - Virtual machines on demand. |
||||
* [Virtual hosting](vhosts) - Virtual domain name hosting for websites. |
||||
* Kubernetes (coming soon!) |
||||
|
||||
## Getting Started |
||||
|
||||
First, make sure that [you are a CSC member](https://csclub.uwaterloo.ca/get-involved/) |
||||
and that your membership has not expired. |
||||
|
||||
Here is a list of general-use CSC machines which you may SSH into after becoming |
||||
a member: |
||||
[https://wiki.csclub.uwaterloo.ca/Machine_List](https://wiki.csclub.uwaterloo.ca/Machine_List) |
||||
|
||||
If you wish to see the terms for which your membership is valid, you can run the |
||||
following command from any general-use machine: |
||||
```sh |
||||
ceo members get <your_username> |
||||
``` |
||||
|
||||
To start creating your own virtual machines, please see the [CloudStack](cloudstack) |
||||
page for more details. |
@ -0,0 +1,99 @@ |
||||
# SSH Tricks |
||||
|
||||
Here are some useful SSH tricks for accessing your VM. |
||||
|
||||
The commands below assume that the SSH public key on your personal machine |
||||
has already been copied to two places: |
||||
|
||||
1. the `~/.ssh/authorized_keys` file in your CSC home directory |
||||
2. the `~/.ssh/authorized_keys` file of the default user in your VM |
||||
|
||||
!!! Note |
||||
If you are having trouble with any of the commands below, please don't |
||||
hesitate to ask the [Systems Committee](mailto:syscom@csclub.uwaterloo.ca) |
||||
for assistance. |
||||
|
||||
Most of the "tricks" below require ProxyJump to have been setup, so we suggest |
||||
reading that first. |
||||
|
||||
## ProxyJump |
||||
To avoid having to manually SSH to a CSC machine before SSH'ing to your |
||||
VM, you can use the ProxyJump directive. For example, let's say your VM's |
||||
IP address is `172.19.134.121`, and you want to use `corn-syrup` as a jump |
||||
host. |
||||
|
||||
Add a snippet similar to the following in your `~/.ssh/config` (on your |
||||
personal machine): |
||||
```sh |
||||
Host corn-syrup |
||||
HostName corn-syrup.csclub.uwaterloo.ca |
||||
# Replace this with your username |
||||
User ctdalek |
||||
Host ctdalek-vm1 |
||||
# Replace this with the IP address of your VM |
||||
HostName 172.19.134.121 |
||||
ProxyJump corn-syrup |
||||
# Replace this with the default user in your VM |
||||
User debian |
||||
``` |
||||
|
||||
Now you can connect to your VM by running |
||||
```sh |
||||
ssh ctdalek-vm1 |
||||
``` |
||||
|
||||
!!! Note |
||||
If the name of your SSH key is not one of the default names (e.g. id_rsa, |
||||
id_ed25519), you may also need to specify the `IdentityFile` option. |
||||
|
||||
## Port forwarding |
||||
Let's say you have a process bound to `localhost:8000` in your VM, and you'd like |
||||
to access it from your personal machine. Then you just need to run the following: |
||||
```sh |
||||
ssh -L 8000:localhost:8000 ctdalek-vm1 |
||||
``` |
||||
This will forward requests to `localhost:8000` on your personal machine to |
||||
`localhost:8000` on your VM. |
||||
|
||||
If you want to fork the process to the background, here's one way to do it: |
||||
```sh |
||||
ssh -L 8000:localhost:8000 -CNfq ctdalek-vm1 |
||||
``` |
||||
Explanation: |
||||
|
||||
* `-C`: compress (saves bandwidth) |
||||
* `-N`: don't execute a command on the server |
||||
* `-f`: fork the SSH process to the background |
||||
* `-q`: quiet (silences output) |
||||
|
||||
## Reverse port forwarding |
||||
Let's say you have a process bound to `localhost:8000` on your personal machine, |
||||
and you'd like to access it from your VM. Instead of using `-L`, you want to use |
||||
`-R` instead: |
||||
```sh |
||||
ssh -R 8000:localhost:8000 -CNfq ctdalek-vm1 |
||||
``` |
||||
This will forward requests to `localhost:8000` in the VM to `localhost:8000` on |
||||
your personal machine. |
||||
|
||||
## SOCKS proxy |
||||
You probably won't need this one, but it's good to know. This basically allows |
||||
you to use a CSC machine as a proxy for *all* of your Internet traffic for a |
||||
particular application. It's useful when you need to access a website which |
||||
is only available from the campus network. |
||||
|
||||
First, let's run a SOCKS proxy on e.g. `localhost:8132`: |
||||
```sh |
||||
ssh -D 8132 -CNfq corn-syrup |
||||
``` |
||||
You now need to configure your application to use the proxy. For example, in |
||||
Firefox, you can do the following: |
||||
|
||||
* Visit `about:preferences` in the URL bar |
||||
* Scroll to the bottom, and click the Settings button under 'Network Settings' |
||||
* Select 'Manual proxy configuration' |
||||
* Enter 'localhost' as the SOCKS Host, and 8132 for the port. Also make sure |
||||
'SOCKS v5' is selected. |
||||
|
||||
After pressing 'OK', you should now be able to visit websites using a campus |
||||
IP address. |
@ -0,0 +1,65 @@ |
||||
# Virtual Hosting |
||||
|
||||
[Virtual hosting](https://en.wikipedia.org/wiki/Virtual_hosting) is a method |
||||
for hosting multiple websites with different domain names on a single web |
||||
server. The idea is to redirect external traffic from the CSC web server to |
||||
your VM based on the domain name. If you are hosting a website on your VM |
||||
and you would like it to be publically accessible, you will need to create |
||||
a vhost record for your VM. |
||||
|
||||
## Domain limitations |
||||
Each member may create up to 10 vhosts whose domains end with |
||||
`<username>.csclub.cloud`. |
||||
|
||||
For example, if your username is `ctdalek`, then the following vhost domains |
||||
are all valid: |
||||
|
||||
* ctdalek.csclub.cloud |
||||
* www.ctdalek.csclub.cloud |
||||
* abc.def.ctdalek.csclub.cloud |
||||
|
||||
## Creating a vhost record |
||||
Let's say your VM's IP address is 172.19.134.121 and you wish to use the domain |
||||
`ctdalek.csclub.cloud`. You must already have an application running on port 80 |
||||
in your VM (e.g. NGINX). |
||||
|
||||
Login to a [CSC general-use machine](https://wiki.csclub.uwaterloo.ca/Machine_List) |
||||
and run the following: |
||||
```sh |
||||
ceo cloud vhosts add ctdalek.csclub.cloud 172.19.134.121 |
||||
``` |
||||
In addition to creating the vhost record, this command will also provision a TLS |
||||
certificate for your website (from either [ZeroSSL](https://zerossl.com/) or |
||||
[Let's Encrypt](https://letsencrypt.org/)). You should now be able to visit your |
||||
website over HTTPS from your browser, e.g. `https://ctdalek.csclub.cloud`. |
||||
|
||||
!!! warning |
||||
To avoid having to reload our web server too frequently, and to reduce the risk |
||||
of getting banned by our ACME service provider, we have set a rate limit on the |
||||
command above for **once every five minutes**. We apologize for the inconvnience. |
||||
|
||||
To view your vhost records, run the following: |
||||
```sh |
||||
ceo cloud vhosts list |
||||
``` |
||||
|
||||
To delete a vhost record, run the following: |
||||
```sh |
||||
ceo cloud vhosts delete ctdalek.csclub.cloud |
||||
``` |
||||
|
||||
!!! info |
||||
Multiple domain names can point to the same IP address, but a single domain name |
||||
can only point to one IP address. |
||||
|
||||
## Using a custom domain name |
||||
If you wish to use a custom domain name which you have purchased from an external |
||||
registrar, please make it point to the IP addresses of `csclub.cloud`. As of this writing, |
||||
this is: |
||||
|
||||
* IPv4: `129.97.134.10` |
||||
* IPv6: `2620:101:f000:4901:c5c::10ad` |
||||
|
||||
Then, please send an email to the [Systems Committee](mailto:syscom@csclub.uwaterloo.ca) |
||||
requesting a vhost record for your domain. Make sure to also provide the IP address |
||||
of your VM. |
@ -0,0 +1,34 @@ |
||||
site_name: CSC Cloud Docs |
||||
site_url: https://docs.cloud.csclub.uwaterloo.ca/ |
||||
nav: |
||||
- Home: index.md |
||||
- CloudStack: cloudstack.md |
||||
- Virtual Hosting: vhosts.md |
||||
- SSH Tricks: ssh-tricks.md |
||||
|
||||
# pip install pymdown-extensions |
||||
markdown_extensions: |
||||
- admonition |
||||
- pymdownx.details |
||||
- pymdownx.superfences |
||||
- pymdownx.highlight |
||||
- pymdownx.inlinehilite |
||||
|
||||
# pip install mkdocs-material |
||||
theme: |
||||
name: material |
||||
favicon: https://git.csclub.uwaterloo.ca/public/csc-propaganda/raw/branch/master/csc-logos/csc-logo.svg |
||||
palette: |
||||
- scheme: default |
||||
toggle: |
||||
icon: material/toggle-switch-off-outline |
||||
name: Switch to dark mode |
||||
- scheme: slate |
||||
toggle: |
||||
icon: material/toggle-switch |
||||
name: Switch to light mode |
||||
|
||||
repo_url: https://git.csclub.uwaterloo.ca/cloud/docs |
||||
repo_name: cloud/docs |
||||
|
||||
copyright: Copyright © 2021 Computer Science Club of the University of Waterloo |