diff --git a/README.md b/README.md
index 9d8670b309600d600d46965e3549f16eaebe64cc..7270050bf4cc3e29a4630e6ffa6873bfb2b09dcf 100644
--- a/README.md
+++ b/README.md
@@ -68,6 +68,52 @@ Once installed, make sure to add the folder where `remote-viewer.exe` is install
On Mac, `remote-viewer` is part of the `virt-viewer` package from MacPorts that can be installed from here [https://ports.macports.org/port/virt-viewer/](https://ports.macports.org/port/virt-viewer/).
+## Overview of nexus' basic concepts
+
+### Templates
+
+- Templates are immutable OS disk images used to create VMs: a VM is an instance of a specific template.
+- Templates can be `private` or `public`: a private templates is only visible to its owner and a public template is visible to everyone.
+
+### VMs
+
+- A VM is always created from a template
+- A VM's hardware (CPU, RAM, devices, etc.) is completely independant of its disk content
+- Access rights to a VM can be finely controlled by its owner and anyone else allowed (see [Access control](#access-control))
+
+### Users
+
+- What users can or cannot do is defined by their capabilities (see [Access control](#access-control))
+- There are capabilities for template, VM and user management
+
+## Available template images
+
+The table below describes the basic public templates that are currently available. The numbers between parenthesis indicate the year and month of creation (also available in the detailed output of `tpllist -l <template ID>`).
+
+| Template name | Description |
+|--- |--- |
+| Debian 11 xfce (2022.08) | Vanilla Debian 11 system with the XFCE desktop environment |
+| | `nexus` user (`/home/nexus`) with sudo privileges (pwd `nexus`) |
+| Manjaro 21 xfce (2022.08) | Vanilla Manjaro 21 system with the XFCE desktop environment |
+| | `nexus` user (`/home/nexus`) with sudo privileges (pwd `nexus`) |
+| Ubuntu 22.04 (2022.08) | Vanilla Ubuntu 22.04 system with the GNOME desktop environment |
+| | `nexus` user (`/home/nexus`) with sudo privileges (pwd `nexus`) |
+| Xubuntu 22.04 (2022.08) + dev env | Vanilla Ubuntu 22.04 system with the XFCE desktop environment |
+| | + C dev tools (gcc, make, etc.), VScode IDE compiler |
+| | + QEMU system hypervisor |
+| | `nexus` user (`/home/nexus`) with sudo privileges (pwd `nexus`) |
+| Xubuntu 22.04 (2023.02) + dev env/unpriv user | Vanilla Ubuntu 22.04 system with the XFCE desktop environment |
+| | + C dev tools (gcc, make, etc.), VScode IDE compiler |
+| | + QEMU system hypervisor |
+| | `nexus` user (`/home/nexus`) with sudo privileges (pwd `nexus`) |
+| | `student` user (`/home/student`) without any privilege (no pwd) |
+| Xubuntu 22.04 (2023.02) + dev env/unpriv user/pi-hole | Vanilla Ubuntu 22.04 system with the XFCE desktop environment |
+| | + C dev tools (gcc, make, etc.), VScode IDE compiler |
+| | + QEMU system hypervisor |
+| | + Pi-hole domain firewall (see [Domain firewall](#domain-firewall)) |
+| | `nexus` user (`/home/nexus`) with sudo privileges (pwd `nexus`) |
+| | `student` user (`/home/student`) without any privilege (no pwd) |
+
## nexush
`nexush` is a **nexus-client** in the form of a single native executable featuring the commands listed below.
@@ -75,6 +121,14 @@ Most commands support regular expressions (regex) in order to perform actions on
Regular expressions must conform to the RE2 GO syntax described here [https://github.com/google/re2/wiki/Syntax](https://github.com/google/re2/wiki/Syntax).
+`nexush` features commands to manipulate:
+
+- VMs (commands starting with `vm`)
+- templates (commands starting with `tpl`)
+- users (commands starting with `user`)
+
+Example of execution showing all available commands:
+
```
Welcome to nexush, the nexus shell.
Type: "help" for help on commands
@@ -83,14 +137,6 @@ nexush> help
―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
ls List files in the specified dir or in the current dir if no argument is specified.
―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
-refresh Obtains a new access token.
-―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
-version Get nexus server's version.
-―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
-whoami Displays the current user's details.
-―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
-passwd Updates the current user's password.
-―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
userlist Lists users.
Requires USER_LIST user capability.
―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
@@ -210,7 +256,6 @@ Bus 003 Device 006: ID 046d:08e3 Logitech, Inc. C505 HD Webcam
## nexush usage examples
Launch `nexush` and log in as user `janedoe@nexus.org` (note that you will be prompted for your password):
-
```
./nexush janedoe@nexus.org
```
@@ -302,10 +347,10 @@ vmcreate "ISC_433 Exam" 2 2048 none none 6713ce26-941e-4d95-8e92-6b71d44bf75a 50
It takes about 30 seconds and 11MB of disk space to create these 50 VMs.
They will have the following names:
```
-ISC_433 Exam [1]
-ISC_433 Exam [2]
+ISC_433 Exam <1>
+ISC_433 Exam <2>
...
-ISC_433 Exam [50]
+ISC_433 Exam <50>
```
Edit VM `6713ce26-941e-4d95-8e92-6b71d44bf75a` by changing its name to "Tagada VM" and no network interface (`none`):
@@ -373,9 +418,9 @@ Create a new `public` template, named "Xubuntu 22.04 + golang toolchain" based o
tpllist 89649fe3-4940-4b77-929e-50903789cd87 "Xubuntu 22.04 + golang toolchain" public
```
-Delete template `effefb49-0402-4095-a42d-1755937fe4b1`:
+Delete template `3d440a31-17da-423d-8d95-a96b4cecff8b`:
```
-tpldel effefb49-0402-4095-a42d-1755937fe4b1
+tpldel 3d440a31-17da-423d-8d95-a96b4cecff8b
```
Quit `nexush`:
@@ -432,8 +477,7 @@ Below is a screenshot of `nexus-exam`'s graphical interface:
## Tutorial: creating a live exam with nexush
-First and foremost, VM templates for the most popular distributions are available on HEPIA ISC nexus server (Debian, Ubuntu, Xubuntu, Manjaro, Fedora).
-In all templates, the default user/password is `nexus/nexus`. Beware that the user has `sudo` (root) access.
+First and foremost, templates for the most popular distributions are available on HEPIA ISC nexus server. They are described in [Available template images](#available-template-images).
Let's say you want to create an exam for the class "ProgSys". Let's assume 30 students are enrolled in the class.
@@ -447,9 +491,7 @@ First, you need to create the VM that will be used by the students during the ex
```
janedoe@nexus.org's password:
Welcome to nexush, the nexus shell.
- Type: "help" for help on commands
- "ls" to list files in current directory
- "ls dir" to list files in dir
+ Type: "help" for help on commands
"quit" or "exit" to quit nexush
nexush>
```
@@ -460,17 +502,18 @@ First, you need to create the VM that will be used by the students during the ex
```
This command displays the templates you can use:
```
- Debian 11 xfce | 0accbad1-3865-416f-bac7-a2f80ba7f081 | public
- Fedora 36 gnome | 1031124c-e7f1-404f-a35e-a54711998131 | public
- Manjaro 21 xfce | 502c30cb-49ea-4a83-a405-8c9182d9970c | public
- Ubuntu 22.04 | 77518795-31e4-4fba-a160-22aa5d603f3e | public
- Xubuntu 22.04 | effefb49-0402-4095-a42d-1755937fe4b1 | public
+ Debian 11 xfce (2022.08) | 0accbad1-3865-416f-bac7-a2f80ba7f081 | public
+ Manjaro 21 xfce (2022.08) | 502c30cb-49ea-4a83-a405-8c9182d9970c | public
+ Ubuntu 22.04 (2022.08) | 77518795-31e4-4fba-a160-22aa5d603f3e | public
+ Xubuntu 22.04 (2022.08) + dev env | 0fc5c07a-bc36-4583-934f-0cacf030221b | public
+ Xubuntu 22.04 (2023.02) + dev env/unpriv user | 8b746cf9-1a9b-4dec-8f3d-4f7479fafd86 | public
+ Xubuntu 22.04 (2023.02) + dev env/unpriv user/pi-hole | 3d440a31-17da-423d-8d95-a96b4cecff8b | public
```
- Let's assume template `effefb49-0402-4095-a42d-1755937fe4b1` (Xubuntu_22.04), is the one you would like to use.
+ Let's assume template `0fc5c07a-bc36-4583-934f-0cacf030221b` (Xubuntu 22.04 (2022.08) + dev env), is the one you would like to use.
1. Create the VM based on the chosen template. Let's say you want the VM to be named "Exam ProgSys Oct2022" and you want it to have 2 CPUs, 3GB RAM and access to the Internet (for now):
```
- vmcreate "Exam ProgSys Oct2022" 2 3000 user none effefb49-0402-4095-a42d-1755937fe4b1
+ vmcreate "Exam ProgSys Oct2022" 2 3000 user none 0fc5c07a-bc36-4583-934f-0cacf030221b
```
This command displays the name and ID of the created VM(s):
```
@@ -531,14 +574,14 @@ First, you need to create the VM that will be used by the students during the ex
```
This command displays each VM created:
```
- Created VM "Live Exam ProgSys Oct2022 [Alia Friedman]" | 74d8b83d-f59e-4129-bf68-af574968cf48
- Created VM "Live Exam ProgSys Oct2022 [Aria Doyle]" | f3047faa-2f15-4f47-b79f-9acc19751b6c
- Created VM "Live Exam ProgSys Oct2022 [Avah Coffey]" | 3ebd56a2-2c1e-416c-9847-f80ee3efa1c1
- Created VM "Live Exam ProgSys Oct2022 [Briley Brady]" | 245fc5b2-b192-4b41-80be-2d39b5a2cef2
- Created VM "Live Exam ProgSys Oct2022 [Brooklyn Sweeney]" | a9bafd7e-28f0-4f37-8b90-5e3c82d4bbc5
- Created VM "Live Exam ProgSys Oct2022 [Cornelius Simmons]" | 40edb2b1-b4e9-4928-9dea-316ed834bf07
- Created VM "Live Exam ProgSys Oct2022 [Donovan Heath]" | 8ae5c9cd-16f3-4e02-a940-e4209a6d7010
- Created VM "Live Exam ProgSys Oct2022 [Ella Webster]" | 7d16f88f-afb1-4633-a646-57a9c87411d5
+ Created VM "Live Exam ProgSys Oct2022 <Alia Friedman>" | 74d8b83d-f59e-4129-bf68-af574968cf48
+ Created VM "Live Exam ProgSys Oct2022 <Aria Doyle>" | f3047faa-2f15-4f47-b79f-9acc19751b6c
+ Created VM "Live Exam ProgSys Oct2022 <Avah Coffey>" | 3ebd56a2-2c1e-416c-9847-f80ee3efa1c1
+ Created VM "Live Exam ProgSys Oct2022 <Briley Brady>" | 245fc5b2-b192-4b41-80be-2d39b5a2cef2
+ Created VM "Live Exam ProgSys Oct2022 <Brooklyn Sweeney>" | a9bafd7e-28f0-4f37-8b90-5e3c82d4bbc5
+ Created VM "Live Exam ProgSys Oct2022 <Cornelius Simmons>" | 40edb2b1-b4e9-4928-9dea-316ed834bf07
+ Created VM "Live Exam ProgSys Oct2022 <Donovan Heath>" | 8ae5c9cd-16f3-4e02-a940-e4209a6d7010
+ Created VM "Live Exam ProgSys Oct2022 <Ella Webster>" | 7d16f88f-afb1-4633-a646-57a9c87411d5
...
```
@@ -548,14 +591,14 @@ First, you need to create the VM that will be used by the students during the ex
```
This command displays each VM started:
```
- Started VM "Live Exam ProgSys Oct2022 [Alia Friedman]"
- Started VM "Live Exam ProgSys Oct2022 [Aria Doyle]"
- Started VM "Live Exam ProgSys Oct2022 [Avah Coffey]"
- Started VM "Live Exam ProgSys Oct2022 [Briley Brady]"
- Started VM "Live Exam ProgSys Oct2022 [Brooklyn Sweeney]"
- Started VM "Live Exam ProgSys Oct2022 [Cornelius Simmons]"
- Started VM "Live Exam ProgSys Oct2022 [Donovan Heath]"
- Started VM "Live Exam ProgSys Oct2022 [Ella Webster]"
+ Started VM "Live Exam ProgSys Oct2022 <Alia Friedman>"
+ Started VM "Live Exam ProgSys Oct2022 <Aria Doyle>"
+ Started VM "Live Exam ProgSys Oct2022 <Avah Coffey>"
+ Started VM "Live Exam ProgSys Oct2022 <Briley Brady>"
+ Started VM "Live Exam ProgSys Oct2022 <Brooklyn Sweeney>"
+ Started VM "Live Exam ProgSys Oct2022 <Cornelius Simmons>"
+ Started VM "Live Exam ProgSys Oct2022 <Donovan Heath>"
+ Started VM "Live Exam ProgSys Oct2022 <Ella Webster>"
...
```
@@ -578,14 +621,14 @@ First, you need to create the VM that will be used by the students during the ex
```
This command displays each exported file tree:
```
- Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 [Alia Friedman]" into Live Exam ProgSys Oct2022 [Alia Friedman].tar.gz
- Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 [Aria Doyle]" into Live Exam ProgSys Oct2022 [Aria Doyle].tar.gz
- Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 [Avah Coffey]" into Live Exam ProgSys Oct2022 [Avah Coffey].tar.gz
- Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 [Briley Brady]" into Live Exam ProgSys Oct2022 [Briley Brady].tar.gz
- Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 [Brooklyn Sweeney]" into Live Exam ProgSys Oct2022 [Brooklyn Sweeney].tar.gz
- Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 [Cornelius Simmons]" into Live Exam ProgSys Oct2022 [Cornelius Simmons].tar.gz
- Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 [Donovan Heath]" into Live Exam ProgSys Oct2022 [Donovan Heath].tar.gz
- Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 [Ella Webster]" into Live Exam ProgSys Oct2022 [Ella Webster].tar.gz
+ Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 <Alia Friedman>" into Live Exam ProgSys Oct2022 <Alia Friedman>.tar.gz
+ Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 <Aria Doyle>" into Live Exam ProgSys Oct2022 <Aria Doyle>.tar.gz
+ Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 <Avah Coffey>" into Live Exam ProgSys Oct2022 <Avah Coffey>.tar.gz
+ Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 <Briley Brady>" into Live Exam ProgSys Oct2022 <Briley Brady>.tar.gz
+ Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 <Brooklyn Sweeney>" into Live Exam ProgSys Oct2022 <Brooklyn Sweeney>.tar.gz
+ Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 <Cornelius Simmons>" into Live Exam ProgSys Oct2022 <Cornelius Simmons>.tar.gz
+ Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 <Donovan Heath>" into Live Exam ProgSys Oct2022 <Donovan Heath>.tar.gz
+ Successfully exported /home/nexus/Desktop/exam from VM "Live Exam ProgSys Oct2022 <Ella Webster>" into Live Exam ProgSys Oct2022 <Ella Webster>.tar.gz
...
```
@@ -689,6 +732,23 @@ These capabilities are called "VM access capabilities":
- When a user creates a VM, she/he is **automatically granted all VM access capabilities**.
- No other users is granted any access to the created VM. However, the VM owner can add any access type to any users they like.
+## Domain firewall
+
+Some templates come with a domain firewall already installed: [Pi-hole](https://pi-hole.net/).
+
+Pi-hole is a tool that lets you configure which domains are accessible and which are not. It can use whitelists or blacklists to define what's allowed or not and it's highly configurable through either a web interface or the command line.
+
+To configure Pi-hole in the VM:
+
+1. Log on with the `nexus` user as you'll need root privileges
+1. Set the password to access the web interface by running the following in a terminal:
+ ```
+ pihole -a -p
+ ```
+1. Log on Pi-hole's interface by going to `http://pi.hole` in a browser
+1. In the configuration, all domains are blocked except for the ones that are whitelisted; consequently, you must configure the domains you want to allow (you can also disable domain filtering entirely)
+1. Once done, the settings will be persistent
+
## FAQ
### [1] What is QEMU Guest Agent?