nexus-client

Introduction

nexus-client is the client component of the Nexus project, a VDI (Virtual Desktop Infrastructure) written from scratch in Go and based on Linux/KVM + QEMU.

Concept

Components

The full project, nexus_vdi, is made of 2 software components:

1. nexus-server: the server program (backend) that runs on the server
   • Exposes a REST API to manage VMs and users
2. nexus-client: the end-user program or "user interface" to manage VMs and users
   • It uses REST messages to communicate with the server
   • It can be run anywhere (locally or remotely) as long as it can communicate with the server
   • Users must use the client to authentify themselves and manage/use their VMs
   • Currently, 2 clients are provided:
     • nexus-client: a CLI client to be used from a terminal; it features bulk operations to automate operations such as creating/starting/stop/destroying many VMs at once (useful for live exams for instance)
     • nexus-client-exam: a GUI client to be used during live exams
   • A future client (nexus-client-gui) featuring a GUI is in the work, but it's not ready yet
   • All clients feature an "attach" function which lets users interact with their VM's desktop
     • this feature requires remote-viewer which is part of the virt-viewer project

nexus-client

nexus-client is a single executable featuring the commands listed below. Most commands supports regular expressions (regex) in order to perform actions on multiple VMs at once.

Usage: nexus-client CMD
CMD is the Command to run. Except for "login", all Commands require an access token.
The access token is read from the env. variable "NEXUS_TOKEN".
List of supported Commands:
    login               Login and obtain an access token.
    whoami              Display the current user's details.
    passwd              Update the current user's password.
    userlist            List users (regex matching).
    useradd             Add a user.
    userdel             Delete one or more users.
    usersetcaps         Set a user's capabilities.
    vmlist              List VMs that can be listed (regex matching).
    vmliststart         List VMs that can be started (regex matching).
    vmlistattach        List VMs that can be attached to (regex matching).
    vmliststop          List VMs that can be stopped (regex matching).
    vmlistedit          List VMs that can be edited (regex matching).
    vmlisteditaccess    List VMs that can have their VM access edited (regex matching).
    vmlistdel           List VMs that can be deleted (regex matching).
    vmcred2pdf          Create a PDF with the credentials required to attach to running VMs (regex matching).
    vmstart             Start one or more VMs (regex matching).
    vmstop              Stop one or more VMs (regex matching).
    vmattach            Attach to one or more VMs in order to use their desktop environment (regex matching).
    vmcreate            Create one or more VMs (regex matching).
    vmedit              Edit one or more VMs' properties: name, cpus, ram or nic (regex matching).
    vmdel               Delete one or more VMs (regex matching).
    vmsetaccess         Set a user's VM access in one or more VMs (regex matching).
    vmdelaccess         Delete a user's VM access in one or more VMs (regex matching).
    tpllist             List available templates (regex matching).
    tplcreate           Create a template, either from an existing VM or from a .qcow file.
    tpldel              Delete one or more templates (regex matching).

When attached to a VM's desktop (vmattach command), ctrl+F12 toggles between fullscreen/non-fullscreen modes.

Compiling nexus-client

The nexus-client's source code must be obtained from its git repository with the following command using ssh key-pair authentication:

git clone ssh://git@ssh.hesge.ch:10572/flg_projects/nexus_vdi/nexus-client.git nexus-client.git

If you didn't set up a public key in your gitlab account, then you can obtain the sources through https with:

git clone https://gitedu.hesge.ch/flg_projects/nexus_vdi/nexus-client.git nexus-client.git

To build and run nexus-client, go into nexus-client.git/src/client_cli and run:

go run .

To build the nexus-client executable, run:

go build .

Running nexus-client

nexus-client requires two environment variables:

• NEXUS_SERVER: defines the Nexus server to connect to along the port number.
• NEXUS_CERT: defines the path to the public certificate required for encrypted communication (TLS) with the Nexus server.

Example of variables initialization:

export NEXUS_SERVER=192.168.1.42:1077
export NEXUS_CERT=ca-cert.pem

nexus-client usage examples

List all available commands:

nexus-client

Display the help for the vmcreate command:

nexus-client vmcreate

Authentify user janedoe@nexus.org and obtain an access token:

export NEXUS_TOKEN=`nexus-client login janedoe@nexus.org pipomolo`

Check who I am:

nexus-client whoami

List all users:

nexus-client userlist .

List users matching the "jane" pattern:

nexus-client userlist jane

Add new user lukesky@force.org with a list of capabilities:

nexus-client useradd lukesky@force.org Luke Skywalker pipomolo USER_CREATE USER_DESTROY USER_LIST USER_SET_CAPS VM_CREATE

List all listable VMs:

nexus-client vmlist .

List all listable VMs with more details ("long output"):

nexus-client vmlist -l .

List listable VMs matching the "ubuntu" pattern:

nexus-client vmlist ubuntu

List listable VMs matching the "ubuntu" pattern and also the VM with ID 6713ce26-941e-4d95-8e92-6b71d44bf75a:

nexus-client vmlist ubuntu 6713ce26-941e-4d95-8e92-6b71d44bf75a

List all VMs that can be started:

nexus-client vmliststart .

Start VM 6713ce26-941e-4d95-8e92-6b71d44bf75a:

nexus-client vmstart 6713ce26-941e-4d95-8e92-6b71d44bf75a

Start VMs matching the "exam ISC_433 PCO" pattern:

nexus-client vmstart "exam ISC_433 PCO"

List all VMs that can be attached to:

nexus-client vmlistattach .

Attach to VM 6713ce26-941e-4d95-8e92-6b71d44bf75a and all VMs matching the pattern "zorglub":

nexus-client vmattach 6713ce26-941e-4d95-8e92-6b71d44bf75a zorglub

List all VMs that can be stopped:

nexus-client vmliststop .

Stop VMs matching the "exam ISC_433 PCO" pattern:

nexus-client vmstop "exam ISC_433 PCO"

Stop VM 6713ce26-941e-4d95-8e92-6b71d44bf75a:

nexus-client vmstop 6713ce26-941e-4d95-8e92-6b71d44bf75a

Create a VM named "Doom", based on the fbccb584-9ea6-40f7-926d-dabf3970525e (Doom) template, with 4 CPUs, 4GB RAM, and a network interface with NAT translation:

nexus-client vmcreate Doom 4 4096 user fbccb584-9ea6-40f7-926d-dabf3970525e

Create 50 VMs with the base name "ISC_433 Exam" based on the 6713ce26-941e-4d95-8e92-6b71d44bf75a template, with 2 CPUs, 2GB RAM, and no network interface:

nexus-client vmcreate "ISC_433 Exam" 2 2048 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 [50]

List all VMs that can be edited:

nexus-client vmlistedit .

Edit VM 6713ce26-941e-4d95-8e92-6b71d44bf75a by changing its name to "Tagada VM", changing it to 1 CPU and no network interface (none):

nexus-client vmedit 6713ce26-941e-4d95-8e92-6b71d44bf75a name="Tagada VM" cpus=1 nic=none

Edit VMs matching the "PCO lab2" pattern by changing their CPU to 1 core and a network interface with NAT translation (user):

nexus-client vmedit "PCO lab2" cpus=1 nic=user

List all VMs that can be deleted:

nexus-client vmlistdel .

Delete VM 6713ce26-941e-4d95-8e92-6b71d44bf75a:

nexus-client vmdel 6713ce26-941e-4d95-8e92-6b71d44bf75a

Delete VMs matching the "exam ISC_433 PCO" pattern:

nexus-client vmdel "exam ISC_433 PCO"

List all VMs that can have their access edited:

nexus-client vmlisteditaccess .

Set the VM access for VM 89649fe3-4940-4b77-929e-50903789cd87 with: VM_LIST and VM_DESTROY for user student@nexus.org:

nexus-client vmsetaccess 89649fe3-4940-4b77-929e-50903789cd87 student@nexus.org VM_LIST VM_DESTROY

Set VM access for VMs matching the "alpine" pattern with: VM_START and VM_STOP for user student@nexus.org:

nexus-client vmsetaccess alpine student@nexus.org VM_START VM_STOP

Remove VM access for student@nexus.org from VM 89649fe3-4940-4b77-929e-50903789cd87:

nexus-client vmdelaccess 89649fe3-4940-4b77-929e-50903789cd87 student@nexus.org

Remove VM access for student@nexus.org from VMs matching the "lab2" pattern:

nexus-client vmdelaccess lab2 student@nexus.org

Generate exam_vms.pdf with the credentials required to connect to all running VMs matching "exam prog sys":

nexus-client vmcred2pdf "exam prog sys" output.pdf

List all available templates:

nexus-client tpllist .

List templates matching the "ubuntu" pattern:

nexus-client tpllist ubuntu

Create a new public template, named "Xubuntu 22.04 + golang toolchain" based on VM 89649fe3-4940-4b77-929e-50903789cd87 (public templates are accessible to everyone while private templates are only accessible to their creators):

nexus-client tpllist 89649fe3-4940-4b77-929e-50903789cd87 "Xubuntu 22.04 + golang toolchain" public

Delete template 8ae56a30-3195-4aea-960d-abb45c47f99e:

nexus-client tpldel 8ae56a30-3195-4aea-960d-abb45c47f99e

Delete all templates matching the "test" pattern:

nexus-client tpldel test

nexus-client-exam

Compiling nexus-client-exam

Get the source code with:

git clone ssh://git@ssh.hesge.ch:10572/flg_projects/nexus_vdi/nexus-client.git

To build and run nexus-client-exam, go into src/client_exam and run:

go run .

To build the nexus-client-exam executable, run:

go build .

Running nexus-client-exam

nexus-client-exam requires two command line arguments:

Usage: nexus-client-exam server cert
server is the ip address of the nexus server.
cert is the path to the public certificate required to communicate with the nexus server.

Tutorial: creating a live exam

Let's say you want to create an exam for the class "ISC_433_PCO". Let's assume 50 students are enrolled in the class.

First, you need to create the VM that will be used by the students during the exam. Typically, this VM will contain the exam environment (compilers, editors, tools, etc.) along the description of the exam, for instance as a PDF on the desktop.

1. First, authenticate onto the nexus server (make sure the NEXUS_SERVER and NEXUS_CERT environment variables are properly initialized - if not read the beginning of this document):

   export NEXUS_TOKEN=`nexus-client login your_user_email@domain.org`

2. List the available templates and choose the one you wish to use for your exam VM:

   nexus-client tpllist .

   Let's assume template 8ae56a30-3195-4aea-960d-abb45c47f99e (Xubuntu_22.04), is the one you would like to use.

3. Create the VM based on the chosen template. Let's say you want the VM to be named "Exam Oct2022 ISC_433_PCO" and you want it to have 2 CPUs, 4GB of RAM and access to the Internet (for now):

   nexus-client vmcreate "Exam Oct2022 ISC_433_PCO" 2 4096 user 8ae56a30-3195-4aea-960d-abb45c47f99e

4. Now that the VM is created, you need to start it, connect to it, and configure it to fit your needs. First, start it with (you can also start it by specifying its VM ID):

   nexus-client vmstart "Exam Oct2022 ISC_433_PCO"

5. Attach to the VM in order to configure it to your needs (you can also attach to it by specifying its VM ID):

   nexus-client vmattach "Exam Oct2022 ISC_433_PCO"

6. Configure the VM to your needs, by:

   • upgrading the system with sudo apt-get update && apt-get upgrade
   • installing the applications, compilers, tools, editors, etc. that are required for the exam
   • copying to the desktop the file describing the exam's objectives Once done, you can shutdown the VM.

7. Now that the VM is ready for the exam (its ID is 62856385-4797-4f0f-b840-2e050c05a0a8), you must create a template from it. This template must be private as we don't want anyone else to access it. Let's choose "Exam Oct2022 ISC_433_PCO" as the template name (template creation takes several minutes, the larger the VM, the longer):

   nexus-client tplcreate 62856385-4797-4f0f-b840-2e050c05a0a8 "Exam Oct2022 ISC_433_PCO" private

   Once done, the new template ID is displayed. Let's say its ID is 540a3f8b-daa9-4ea7-9d33-e9fcaa7c9c3a

8. You can now create the VMs for your 50 students using the freshly created template. Let's say the base name for the 50 VMs to create is "Exam Oct2022 ISC_433_PCO". You want the VMs to have: 2 CPUs, 4GB of RAM and no network interface to prevent any fraud. The 50 VMs can be created with:

   nexus-client vmcreate "Exam Oct2022 ISC_433_PCO" 2 4096 none 540a3f8b-daa9-4ea7-9d33-e9fcaa7c9c3a 50

   It should take a few seconds to generate these 50 VMs.

9. The day of the exam, you'll have to start the 50 VMs and generate a PDF with the credentials required to connect to each VM. To start the 50 VMs, run (the added \[ at the end is to avoid starting the VM that was used to create the template):

   nexus-client vmstart "Exam.*PCO \["

10. Finally, to produce the PDF containing all the credentials to attach to each VM, run (important: the VM must be running):

    nexus-client vmcred2pdf "Exam.*PCO \[" creds.pdf

    creds.pdf contains a table, where each line provides access to a VM: the VM name, the port, the password and a blank cell that should be filled by the student using this VM during the exam. The students must use nexus-client-exam to connect to their VM using the VM's credentials (port and password).

11. You can now print the PDF above, cut each line and give each student the strip of paper for a VM's credentials. Don't forget to tell the students to fill out the blank cell with their names! Once a student has completed the exam, they should shutdown the VM and give you the strip of paper back. Note that you can force stopping a VM with nexus-client vmstop although it's not clean and might corrupt the VM's filesystem.