@@ -144,3 +166,308 @@ To run the tests, make sure the nexus-server for development is running, then ex
```
make tests LOGIN=tests@nexus.org
```
<!--
# Requirements
First and foremost, **nexus-server** requires a Linux kernel with KVM. KVM is a module that provides a userspace API to access hardware-assisted virtualization instructions, thus "transforming" the Linux kernel into a hypervisor. To make sure the KVM module is loaded into the kernel, run:
```
lsmod|grep kvm
```
If you don't get an output similar to the one below, it means the KVM module is not loaded into the kernel. A possible cause for this behavior is if you didn't enable hardware virtualization support in your machine's BIOS/firmware. Note that if you have an AMD CPU, you should see `kvm_amd` in place of `kvm_intel`:
```
kvm_intel 294912 0
kvm 782336 1 kvm_intel
```
The host machine on which **nexus-server** will be running needs the following software:
- QEMU system 6.0.0 or newer
- `qemu-img` to manipulate VM disk images
- `guestfish` to export/import files from VM disk images
- `uuidgen` to generate UUIDs from bash
Note that Ubuntu 20.04 ships with QEMU 4.2 which is too old, but Ubuntu 22.04 ships with QEMU 6.2 and Ubuntu 24.04 with QEMU 8.2.
The latest stable version of QEMU can be downloaded from [https://www.qemu.org/download/](https://www.qemu.org/download/). To compile QEMU from source, read the [Compiling QEMU from source](##Compiling-QEMU-from-source) section at the end of this document.
To obtain, build, and install **nexus-server**, these additionnal software are required:
- git
- golang 1.18 or newer
- GNU make
- certtool
To install all the above-mentioned packages on a Ubuntu system, run:
On Ubuntu 24.04, the following additionnal package must be installed:
```
sudo apt-get install -y qemu-system-modules-spice
```
## Note about Go compilers
To compile **nexus-server**, Go version 1.18 or above is required. Snap and flatpak package repositories provide recent enough versions. Alternatively, a toolchain from the official Go website can be obtained at [https://go.dev/dl/](https://go.dev/dl/).
# Building and installing nexus-server
To make the installation of **nexus-server** as easy as a possible, a `Makefile` is provided. It automates most of the steps required to build and install the service.
Note that `guestfish` (package of the same name) is required. It should normally be ran as a non-root user. However, on Ubuntu, it requires root access due to a side-effect of Ubuntu's wrong file permissions with `/boot/vmlinuz*` files ([more info here](https://libguestfs.org/guestfs-faq.1.html)). Consequently, the command below must be run in order to restore the correct file permissions:
```
sudo chmod 0644 /boot/vmlinuz*
```
**BEWARE**: whenever a new kernel is installed, its permission **must be changed again**, otherwise importing or exporting files from VMs won't work!
## Installation script
As mentioned above, the script is simply a `Makefile` located at the root of the git repository.
## Configuring certificates
Certificates are required to ensure encrypted communication (TLS) with nexus clients. The installation script creates the required certificates, but you must still edit a few fields specific to your system.
Edit `config/certs/nexus-server.info` and change the following fields to your liking: `organization`, `cn`, `dns_name` and `ip_address`.
Also, edit `config/certs/ca.info` and change the `cn` field accordingly.
## Configuring the service
By default, the service listens to port 1077. If you would like the service (API) to listen to a different port, edit `config/systemd/nexus-server.service` and change the line ending in `-p 1077` with a port in the range [1025,1099] inclusive. If you wish to change this range, modify `APIPortMin` and `APIPortMax` in `src/server/consts/consts.go`.
Furthermore, each running VM listens to a port randomly chosen in the range [1100,65535] inclusive. If you wish to change this range, modify `VMSpiceMinPort` and `VMSpiceMaxPort` in `src/server/consts/consts.go`.
## Building nexus-server and installing nexus-server
A `PREFIX` environment variable is used to specify where nexus-server must be installed. Let's assume we want `nexus-server` to reside in `/usr/local/`.
Run the following commands:
```
make build_srv
sudo -E make install_prod_srv PREFIX=/usr/local
```
The last command above:
- Creates a `nexus` user and group to run the service.
- Creates the file/directory hierarchy in the specified directory.
- Creates and signs the certificates.
- Add a crond task required by the service.
- Integrates the service with systemd.
- Creates a `users.json` file with user `admin@nexus.org`, featuring all capabilities. Its default password is `12345678`, therefore it is **highly** recommended to change it as described below.
The `genpwd` tools located in `PREFIX/nexus-server/bin/` can be used to obtain the hash of a password typed on the keyboard. This is very useful when wanting to update a user's password, such as `admin@nexus.org` right after nexus' initial installation.
## Creating initial templates
To create VMs, at least one template is required. However, none is provided in the base install.
The `template_creator` script, located in `PREFIX/nexus-server/bin/`, can be used to create new templates from ISO images:
```
template_creator - a tool to create a VM template from an ISO image.
After the OS installation is completed, a tar archive is created in
the current directory. It can then be unarchived in the nexus-server's
templates directory.
Usage: template_creator name owner vis iso
name name of the template
owner email address of the template's owner
vis visibility of the template, either "public" or "private"
iso ISO image of the OS to install
```
For instance, this would create a template named "Xubuntu 22.04", owned by janedoe@nexus.org, visible to all users (i.e. `public`) and based on the ISO image located in `/tmp/xubuntu-22.04-desktop-amd64.iso`:
```
./template_creator "Xubuntu 22.04" janedoe@nexus.org public /tmp/xubuntu-22.04-desktop-amd64.iso
```
Once the command above is ran, a VM is launched in which you can proceed with the installation of the OS from the ISO image. Install the OS as you would on a physical PC. Once installed, you can beboot (the GUI lets you reboot the VM) and configure the OS to your liking. Once you're happy with the OS, close the VM window and `template_creator` will finish the creation of the template, by producing a `.tar` archive of the freshly created template.
You can now unarchive the archive in `PREFIX/nexus-server/data/templates`, set the proper owner, and delete the archive with (we assume the template archive is `7ac36ad7-a960-4c87-916a-4c1068d19b59.tar`):
```
sudo -s
cd PREFIX/nexus-server/data/templates
tar vfx PREFIX/nexus-server/bin/template_creator/7ac36ad7-a960-4c87-916a-4c1068d19b59.tar
Feel free to repeat the operation above with as many templates as you like.
## Updating a template
The `vm_run` script, located in `PREFIX/nexus-server/bin/`, is a convenience script that runs a VM on the specified image file(s) and it can be used to update a template's disk image. Here is its usage:
```
vm_run - launch a VM on the specified disk image(s).
The VM is configured with 4 CPUs and 4G of RAM.
Usage: vm_run -d disk -i iso
disk the disk image to use (typically a .qcow file)
iso the CD/DVD-ROM image to use (typically an .iso file)
At least one image must be specified.
```
Before updating a template's disk image, **make absolutely sure that it IS NOT used by any VMs**, otherwise all VMs based on this template will be corrupted!
## Copy a template from another server
To copy a template from another nexus server, `rsync` must be used instead of `scp` as it supports sparse files. Sparse files are files where consecutive zeros are not actually stored in data blocks. Template files (qcow) might appear much bigger than they really are as `ls` doesn't show the real block usage. To display the real size of a file, use `du -h FILE` instead.
Use the following recipe to copy a template using `rsync` over ssh (requires ssh key pairs):
```
# On the destination server, create the template directory
You can then use any of the commands below to control your newly created `nexus-server` service. Only the `status` command does not require root privilege.
| Command | Description |
|--- |--- |
| `systemctl status nexus-server` | display the service's status |
| `systemctl start nexus-server` | start the service |
| `systemctl stop nexus-server` | stop the service |
| `systemctl restart nexus-server` | restart the service |
| `systemctl reload nexus-server` | reload the service |
| `systemctl enable nexus-server` | enable the service at boot time |
| `systemctl disable nexus-server` | disable the service at boot time |
| `systemctl daemon-reload` | reload the daemon (to call when service file is updated) |
| `journalctl -f --unit nexus-server` | display the service's log in "following" mode |
## Public key for client access
Make sure to transmit the public key (certificate) located in `PREFIX/nexus-server/certs/ca-cert.pem` to any nexus client as they will need this key to authentify themselves and communicate with the server.
## Updating nexus-server
Whenever a new version of **nexus-server** is released, the binaries must be updated.
Go to the root source directory `nexus-server.git` and as a non-root user, build the binaries:
```
make build_srv
```
Then, as root (or sudo), stop the **nexus-server** systemd service:
```
sudo systemctl stop nexus-server
```
Next, as root (or sudo), update **nexus-server**:
```
sudo -E make update_srv PREFIX=/usr/local
```
Finally, as root (or sudo), start the **nexus-server** systemd service:
```
sudo systemctl start nexus-server
```
## Uninstalling nexus-server
**Beware this will delete ALL installed VMs and templates!**
First, as root (or sudo), stop the **nexus-server** systemd service:
```
sudo systemctl stop nexus-server
```
To uninstall **nexus-server**, go to its root source directory `nexus-server.git` and as sudo (or root), run:
```
sudo -E make uninstall_prod_srv PREFIX=/usr/local
```
-->
<!--
# Compiling QEMU from source
1. Retrieve QEMU' source code from [https://www.qemu.org/download/](https://www.qemu.org/download/)
1. Decompress the archive and go into QEMU' source directory:
1. Enable spice (for remote desktop), virtfs (for shared folders), libusb (for usb passthrough) and usb-redir (for usb redirection over the network) in QEMU's config:
1. Install QEMU system-wide into `/usr/local/bin`:
```
make install
```
-->
<!--
## HOWTO: Exporting a VM disk image
Given each VM's disk is an overlay baked by a template's disk image, exporting a VM's disk image into a dedicated and independant file is slightly tricky. Below are the steps to do so.
Let:
- `base.qcow` be the template's disk image
- `overlay.qcow` be the VM's disk image (baked by `base.qcow`)
We therefore have the following relationship:
```
base.qcow <-- overlay.qcow
```
Steps:
1) Copy the overlay into a new one:
```
cp overlay.qcow new_overlay.qcow
```
2) Rebase the new overlay in order to become a standalone disk file:
```
qemu-img rebase -b "" new_overlay.qcow
```
3) Move the new overlay disk into the template directory:
@@ -252,257 +254,6 @@ Access control [is described here](access_control.md).
The REST API [is described here](rest_api.md).
## Building and installing nexus-server
To make the installation of **nexus-server** as easy as a possible, a `Makefile` is provided which automates most of the steps required to build and install the service.
Note that `guestfish` (package of the same name) is required. It should normally be ran as a non-root user. However, on Ubuntu, it requires root access due to a side-effect of Ubuntu's wrong file permissions with `/boot/vmlinuz*` files ([more info here](https://libguestfs.org/guestfs-faq.1.html)). Consequently, the command below must be run in order to restore the correct file permissions:
```
sudo chmod 0644 /boot/vmlinuz*
```
**BEWARE**: whenever a new kernel is installed, its permission **must be changed again**, otherwise importing or exporting files from VMs won't work!
### Prerequisites
The host machine on which **nexus-server** will be running requires the following software:
- A Linux kernel with the KVM module loaded
- QEMU 6.0.0 or newer (`qemu-system-x86` Ubuntu package)
-`qemu-img` to manipulate VM disk images (`qemu-utils` Ubuntu package)
-`guestfish` to export/import files from VM disk images (`guestfish` Ubuntu package)
-`uuidgen` to generate UUIDs from bash (`uuid-runtime` Ubuntu package)
Note that Ubuntu 20.04 ships with QEMU 4.2.1 which is too old, but Ubuntu 22.04 ships with QEMU 6.2 and Ubuntu 24.04 ships with QEMU 8.2.2.
The latest stable version of QEMU can be downloaded from [https://www.qemu.org/download/](https://www.qemu.org/download/). To compile QEMU from source, read the [Compiling QEMU from source](##Compiling-QEMU-from-source) section at the end of this document.
To get, build, and install **nexus-server**, these additionnal software are required:
- git (`git` Ubuntu package)
- golang 1.18 or newer (`golang-go` Ubuntu package)
- GNU make (`make` Ubuntu package)
- certtool (`gnutls-bin` Ubuntu package)
To install all the above-mentioned packages on a Ubuntu system:
On Ubuntu 24.04, an additionnal package must be installed to support SPICE:
```
sudo apt-get install -y qemu-system-modules-spice
```
To make sure the KVM module is loaded into the kernel, run:
```
lsmod|grep kvm
```
If you don't see something similar to the output below (if you have an AMD CPU, the output is similar with `amd` instead of `intel`), it means the KVM module is not loaded into the kernel:
```
kvm_intel 294912 0
kvm 782336 1 kvm_intel
```
To compile **nexus-server**, a Go compiler version 1.18 or above is required. Snap and flatpak package repositories provide recent enough versions. Alternatively, a go compiler toolchain from the official Go website can be obtained at [https://go.dev/dl/](https://go.dev/dl/). You also need `make` in order to execute the installation script.
The **nexus-server**'s source code must be obtained from its git repository with the following command using ssh key-pair authentication (as a non-root user):
Once the code repository cloned, go into `nexus-server.git`:
```
cd nexus-server.git
```
### Installation script
As mentioned above, the script is simply a `Makefile` located at the root of the git repository.
### Configuring certificates
Certificates are required to ensure encrypted communication (TLS) with nexus clients. The installation script creates the required certificates, but you must still edit a few fields specific to your system.
Edit `config/certs/nexus-server.info` and change the following fields to your liking: `organization`, `cn`, `dns_name` and `ip_address`.
Also, edit `config/certs/ca.info` and change the `cn` field accordingly.
### Configuring the service
By default, the service listens to port 1077. If you would like the service (API) to listen to a different port, edit `config/systemd/nexus-server.service` and change the line ending in `-p 1077` with a port in the range [1025,1099] inclusive. If you wish to change this range, modify `APIPortMin` and `APIPortMax` in `src/server/consts/consts.go`.
Furthermore, each running VM listens to a port randomly chosen in the range [1100,65535] inclusive. If you wish to change this range, modify `VMSpiceMinPort` and `VMSpiceMaxPort` in `src/server/consts/consts.go`.
### Building nexus-server and installing nexus-server
A `PREFIX` environment variable is used to specify where nexus-server must be installed. Let's assume we want `nexus-server` to reside in `/usr/local/`.
Run the following commands:
```
make build_srv
sudo -E make install_prod_srv PREFIX=/usr/local
```
The last command above:
- Creates a `nexus` user and group to run the service.
- Creates the file/directory hierarchy in the specified directory.
- Creates and signs the certificates.
- Add a crond task required by the service.
- Integrates the service with systemd.
- Creates a `users.json` file with user `admin@nexus.org`, featuring all capabilities. Its default password is `12345678`, therefore it is **highly** recommended to change it as described below.
The `genpwd` tools located in `PREFIX/nexus-server/bin/` can be used to obtain the hash of a password typed on the keyboard. This is very useful when wanting to update a user's password, such as `admin@nexus.org` right after nexus' initial installation.
### Creating initial templates
To create VMs, at least one template is required. However, none is provided in the base install.
The `template_creator` script, located in `PREFIX/nexus-server/bin/`, can be used to create new templates from ISO images:
```
template_creator - a tool to create a VM template from an ISO image.
After the OS installation is completed, a tar archive is created in
the current directory. It can then be unarchived in the nexus-server's
templates directory.
Usage: template_creator name owner vis iso
name name of the template
owner email address of the template's owner
vis visibility of the template, either "public" or "private"
iso ISO image of the OS to install
```
For instance, this would create a template named "Xubuntu 22.04", owned by janedoe@nexus.org, visible to all users (i.e. `public`) and based on the ISO image located in `/tmp/xubuntu-22.04-desktop-amd64.iso`:
```
./template_creator "Xubuntu 22.04" janedoe@nexus.org public /tmp/xubuntu-22.04-desktop-amd64.iso
```
Once the command above is ran, a VM is launched in which you can proceed with the installation of the OS from the ISO image. Install the OS as you would on a physical PC. Once installed, you can beboot (the GUI lets you reboot the VM) and configure the OS to your liking. Once you're happy with the OS, close the VM window and `template_creator` will finish the creation of the template, by producing a `.tar` archive of the freshly created template.
You can now unarchive the archive in `PREFIX/nexus-server/data/templates`, set the proper owner, and delete the archive with (we assume the template archive is `7ac36ad7-a960-4c87-916a-4c1068d19b59.tar`):
```
sudo -s
cd PREFIX/nexus-server/data/templates
tar vfx PREFIX/nexus-server/bin/template_creator/7ac36ad7-a960-4c87-916a-4c1068d19b59.tar
Feel free to repeat the operation above with as many templates as you like.
### Updating a template
The `vm_run` script, located in `PREFIX/nexus-server/bin/`, is a convenience script that runs a VM on the specified image file(s) and it can be used to update a template's disk image. Here is its usage:
```
vm_run - launch a VM on the specified disk image(s).
The VM is configured with 4 CPUs and 4G of RAM.
Usage: vm_run -d disk -i iso
disk the disk image to use (typically a .qcow file)
iso the CD/DVD-ROM image to use (typically an .iso file)
At least one image must be specified.
```
Before updating a template's disk image, **make absolutely sure that it IS NOT used by any VMs**, otherwise all VMs based on this template will be corrupted!
### Copy a template from another server
To copy a template from another nexus server, `rsync` must be used instead of `scp` as it supports sparse files. Sparse files are files where consecutive zeros are not actually stored in data blocks. Template files (qcow) might appear much bigger than they really are as `ls` doesn't show the real block usage. To display the real size of a file, use `du -h FILE` instead.
Use the following recipe to copy a template using `rsync` over ssh (requires ssh key pairs):
```
# On the destination server, create the template directory
You can then use any of the commands below to control your newly created `nexus-server` service. Only the `status` command does not require root privilege.
| Command | Description |
|--- |--- |
| `systemctl status nexus-server` | display the service's status |
| `systemctl start nexus-server` | start the service |
| `systemctl stop nexus-server` | stop the service |
| `systemctl restart nexus-server` | restart the service |
| `systemctl reload nexus-server` | reload the service |
| `systemctl enable nexus-server` | enable the service at boot time |
| `systemctl disable nexus-server` | disable the service at boot time |
| `systemctl daemon-reload` | reload the daemon (to call when service file is updated) |
| `journalctl -f --unit nexus-server` | display the service's log in "following" mode |
### Public key for client access
Make sure to transmit the public key (certificate) located in `PREFIX/nexus-server/certs/ca-cert.pem` to any nexus client as they will need this key to authentify themselves and communicate with the server.
### Updating nexus-server
Whenever a new version of **nexus-server** is released, the binaries must be updated.
Go to the root source directory `nexus-server.git` and as a non-root user, build the binaries:
```
make build_srv
```
Then, as root (or sudo), stop the **nexus-server** systemd service:
```
sudo systemctl stop nexus-server
```
Next, as root (or sudo), update **nexus-server**:
```
sudo -E make update_srv PREFIX=/usr/local
```
Finally, as root (or sudo), start the **nexus-server** systemd service:
```
sudo systemctl start nexus-server
```
### Uninstalling nexus-server
**Beware this will delete ALL installed VMs and templates!**
First, as root (or sudo), stop the **nexus-server** systemd service:
```
sudo systemctl stop nexus-server
```
To uninstall **nexus-server**, go to its root source directory `nexus-server.git` and as sudo (or root), run:
1. Enable spice (for remote desktop), virtfs (for shared folders), libusb (for usb passthrough) and usb-redir (for usb redirection over the network) in QEMU's config:
1. Install QEMU system-wide into `/usr/local/bin`:
```
make install
```
<!--
### HOWTO: Exporting a VM disk image
Given each VM's disk is an overlay baked by a template's disk image, exporting a VM's disk image into a dedicated and independant file is slightly tricky. Below are the steps to do so.
Let:
- `base.qcow` be the template's disk image
- `overlay.qcow` be the VM's disk image (baked by `base.qcow`)
We therefore have the following relationship:
```
base.qcow <-- overlay.qcow
```
Steps:
1) Copy the overlay into a new one:
```
cp overlay.qcow new_overlay.qcow
```
2) Rebase the new overlay in order to become a standalone disk file:
```
qemu-img rebase -b "" new_overlay.qcow
```
3) Move the new overlay disk into the template directory:
