diff --git a/README.md b/README.md index a324da9ff9507be42b03559a12cfc444d7cdea75..cfd2b343a68ddb4cadc7688db50d3954021da04b 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Nexus VDI is divided into three components: **[nexus-server](docs/server.md)** -- Documentation about inner working of nexus-server and how to install it [is described here](docs/server.md) +- Documentation about the inner workings of nexus-server [is described here](docs/server.md) - The server program (backend) that runs on a server - Exposes a REST API to manage users, VMs and templates diff --git a/docs/install.md b/docs/install.md index 5bde7af955281b9c060a74b69c82b268e1934a9e..ddae559acda5af82144d07b8d73981e5e8421893 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,10 +1,32 @@ +# Contents + +* [Introduction](#introduction) +* [Installing the required dependencies](#installing-the-required-dependencies) +* [Installing nexus-server for development](#installing-nexus-server-for-development) +* [Installing nexus-server for production](#installing-nexus-server-for-production) +* [Building and running nexus clients](#building-and-running-nexus-clients) + # Introduction This document describes: - How to install nexus-server for development: useful for developping or contributing to nexus as well as easily testing it - How to install nexus-server for production -- How to build and run various nexus clients +- How to build and run nexus clients + +For simplicity, this document describes how to install **nexus** on a GNU/Linux system running Ubuntu. + +# Installing the required dependencies + +On a Ubuntu 24.04 system: +``` +sudo apt-get install -y qemu-system-x86 qemu-utils guestfish uuid-runtime git golang-go make gnutls-bin qemu-system-modules-spice +``` + +On a Ubuntu 22.04 system: +``` +sudo apt-get install -y qemu-system-x86 qemu-utils guestfish uuid-runtime git golang-go make gnutls-bin +``` # Installing nexus-server for development @@ -74,7 +96,7 @@ The installation script creates a systemd service named "nexus-server". It can t sudo systemctl start nexus-server ``` -Furthermore, typical systemd service commands can be used, for instance: +Furthermore, usual systemctl commands can be used to control the service: - `sudo systemctl status nexus-server` to check whether the service is running - `sudo systemctl stop nexus-server` to stop the service @@ -97,7 +119,7 @@ sudo systemctl stop nexus-server sudo -E make uninstall_prod_srv PREFIX=/usr/local ``` -# Building and running various nexus clients +# Building and running nexus clients ## Building nexush for development (dev) @@ -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: +``` +sudo apt-get install -y qemu-system-x86 qemu-utils guestfish uuid-runtime git golang-go make gnutls-bin +``` + +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 +chown -R nexus:nexus 7ac36ad7-a960-4c87-916a-4c1068d19b59 +rm PREFIX/nexus-server/data/templates/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 +mkdir /path_to_templates/4913a2bb-edfe-4dfe-af53-38197a44523b + +# On the source server, copy the template directory to the destination server +rsync -P --sparse -r 4913a2bb-edfe-4dfe-af53-38197a44523b destination_server:/path_to_templates/4913a2bb-edfe-4dfe-af53-38197a44523b + ``` + +## Controlling nexus-server with systemd + +The nexus-server service can now be started with: +``` +sudo systemctl start nexus-server +``` + +To check whether the service is running properly: +``` +systemctl status nexus-server +``` + +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: + ``` + tar vfxJ qemu-7.0.0.tar.xz + cd qemu-7.0.0 + ``` +1. Install the required dependencies: + ``` + sudo apt-get install -y build-essential meson libspice-server-dev libattr1-dev libcap-ng-dev libusb-1.0-0-dev libusbredirparser-dev + ``` +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: + ``` + ./configure --enable-spice --enable-virtfs --enable-libusb --enable-usb-redir + ``` +1. Compile QEMU: + ``` + make + ``` +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: + ``` + mv new_overlay.qcow $NEXUS_DATA_PATH/templates/my_new_template/ + ``` + +After completion of these 3 steps, `new_overlay.qcow` is equivalent to `base.qcow` + `overlay.qcow`. + +Note that step 2) is very slow and can take several minutes given the template file can be very large (> 10GB). +--> diff --git a/docs/server.md b/docs/server.md index 3877e6405e52286dd03aa1b31cf82499aa4be887..0079d4e848e6a84522425f81b092777dd42d0ebb 100644 --- a/docs/server.md +++ b/docs/server.md @@ -71,13 +71,15 @@ Here is an example of `users.json` defining user Jane Doe: "pwd": "$2a$10$3MfOrdLLAEJFu0rZkGxGW.bHGiMC/uRD3B5igg5bvdwUedToRqOdO", "caps": { "TPL_CREATE": 1, - "TPL_EDIT": 1, "TPL_DESTROY": 1, + "TPL_EDIT": 1, "TPL_LIST": 1, "USER_CREATE": 1, "USER_DESTROY": 1, "USER_LIST": 1, + "USER_RESETPWD": 1, "USER_SET_CAPS": 1, + "USER_UNLOCK": 1, "VM_CREATE": 1, "VM_SET_ACCESS": 1 } @@ -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: -``` -sudo apt-get install -y qemu-system-x86 qemu-utils guestfish uuid-runtime git golang-go make gnutls-bin -``` - -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): -```{.shell} -git clone ssh://git@ssh.hesge.ch:10572/flg_projects/nexus_vdi/nexus-server.git nexus-server.git -``` - -If you didn't set up a public key in your gitlab account, then you can obtain the sources through https with: -```{.shell} -git clone https://gitedu.hesge.ch/flg_projects/nexus_vdi/nexus-server.git nexus-server.git -``` - -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 -chown -R nexus:nexus 7ac36ad7-a960-4c87-916a-4c1068d19b59 -rm PREFIX/nexus-server/data/templates/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 -mkdir /path_to_templates/4913a2bb-edfe-4dfe-af53-38197a44523b - -# On the source server, copy the template directory to the destination server -rsync -P --sparse -r 4913a2bb-edfe-4dfe-af53-38197a44523b destination_server:/path_to_templates/4913a2bb-edfe-4dfe-af53-38197a44523b - ``` - -### Controlling nexus-server with systemd - -The nexus-server service can now be started with: -``` -sudo systemctl start nexus-server -``` - -To check whether the service is running properly: -``` -systemctl status nexus-server -``` - -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 -``` - -## Resources - -- QEMU Guest Agent Protocol - - [QEMU Guest Agent Protocol Reference](https://qemu.readthedocs.io/en/latest/interop/qemu-ga-ref.html) - -- QEMU Machine Protocol (QMP) - - [Documentation/QMP](https://wiki.qemu.org/Documentation/QMP) - - [QEMU QMP Reference Manual](https://qemu.readthedocs.io/en/latest/interop/qemu-qmp-ref.html) - - [Features/CPUHotplug](https://wiki.qemu.org/Features/CPUHotplug) - - [qmp-shell](https://github.com/0xef53/qmp-shell) - ## USB redirection ### Introduction @@ -545,63 +296,13 @@ Here is a real-world example that defines three USB redirections and each forbid -device qemu-xhci -chardev spicevmc,name=usbredir,id=usbredir1 -device usb-redir,filter='-1:0x0781:0x5567:-1:1|-1:0x067b:0x2303:-1:1|-1:0x03eb:0x6124:-1:1|-1:-1:-1:-1:0',chardev=usbredir1 -chardev spicevmc,name=usbredir,id=usbredir2 -device usb-redir,filter='-1:0x0781:0x5567:-1:1|-1:0x067b:0x2303:-1:1|-1:0x03eb:0x6124:-1:1|-1:-1:-1:-1:0',chardev=usbredir2 -chardev spicevmc,name=usbredir,id=usbredir3 -device usb-redir,filter='-1:0x0781:0x5567:-1:1|-1:0x067b:0x2303:-1:1|-1:0x03eb:0x6124:-1:1|-1:-1:-1:-1:0',chardev=usbredir3 ``` -## 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: - ``` - tar vfxJ qemu-7.0.0.tar.xz - cd qemu-7.0.0 - ``` -1. Install the required dependencies: - ``` - sudo apt-get install -y build-essential meson libspice-server-dev libattr1-dev libcap-ng-dev libusb-1.0-0-dev libusbredirparser-dev - ``` -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: - ``` - ./configure --enable-spice --enable-virtfs --enable-libusb --enable-usb-redir - ``` -1. Compile QEMU: - ``` - make - ``` -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: +## Resources -``` -base.qcow <-- overlay.qcow -``` +- QEMU Guest Agent Protocol + - [QEMU Guest Agent Protocol Reference](https://qemu.readthedocs.io/en/latest/interop/qemu-ga-ref.html) -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: - ``` - mv new_overlay.qcow $NEXUS_DATA_PATH/templates/my_new_template/ - ``` - -After completion of these 3 steps, `new_overlay.qcow` is equivalent to `base.qcow` + `overlay.qcow`. - -Note that step 2) is very slow and can take several minutes given the template file can be very large (> 10GB). ---> +- QEMU Machine Protocol (QMP) + - [Documentation/QMP](https://wiki.qemu.org/Documentation/QMP) + - [QEMU QMP Reference Manual](https://qemu.readthedocs.io/en/latest/interop/qemu-qmp-ref.html) + - [Features/CPUHotplug](https://wiki.qemu.org/Features/CPUHotplug) + - [qmp-shell](https://github.com/0xef53/qmp-shell)