# qemu-web-desktop: Managing Virtual machines

<br>
<img src="../html/desktop/images/darts_logo.png" height=200>
<br>

This documentation assumes you already have installed and configured the service. Refer to the [INSTALL.md](INSTALL.md) and [CONFIGURE.md](CONFIGURE.md). You should as well have pushed some virtual machines in production, following the [VIRTUAL_MACHINES.md](VIRTUAL_MACHINES.md) page.

Table of contents:

1. [Starting, sharing, stopping, re-connecting](#starting-sharing-stopping-re-connecting-normal-use)
1. [Starting sessions manually (command-line)](#starting-sessions-manually-command-line)
1. [Starting sessions via the web service (REST API)](#starting-sessions-via-the-web-service-rest-api)


### Starting, sharing, stopping, re-connecting (normal use)

Once installed (see [INSTALL.md](INSTALL.md)), connect to e.g.:

- http://localhost/qemu-web-desktop

Basically a user can enter some login/password or email. The user can click on "Create".
It is also possible to select the type of machine (system), and what resources are needed (cpu, memory).

<br>
<img src="../html/desktop/images/machine-specs.png">
<br>

When authentication is successful, a virtual machine is launched and can be displayed in the browser window. 

<br>
<img src="../html/desktop/images/create.png">
<br>

Just click the link, and you will access the virtual machine remote desktop. Use full screen, adapt screen resolution and keyboard layout, and you'll be good to go !

<br>
<img src="../html/desktop/images/virtualmachines.png">
<br>

From the service landing page (login, machine specifications), you may also access the **[Manage sessions]** monitoring page to list running sessions.

<br>
<img src="../html/desktop/images/monitor.png">
<br>

The `qemu-web-desktop` service allows to connect and re-connect to active sessions (except for one-shot sessions). Each session is by default a **copy** of the given VM, so that changes are not kept (this behaviour can be changed with the `snapshot_use_master=1` option). It is also possible to share the connection link for an active session, so that multiple users can see and interact on the same environment. Last, sessions can be ended either from the sessions themselves (find the 'Shutdown' item), or aborted with the 'Stop' button shown in the session information page.

All of these actions are possible when selecting the **[Manage sessions]** button on the right of the service page, with proper credentials. Only your sessions will be listed. Service administrators can list all running sessions.

Once the maximum life-time is over, the session is automatically stopped and cleaned-up. There is no way to recover a cleared session.

### Starting sessions manually (command-line)

You can manually start a session from the terminal with command:
```
qwdctl start VM
```
Additional arguments override the default configuration, such as:

`qwdctl start VM [option...]` | Description
------------------------------|------------------
`--snapshot_alloc_cpu=VALUE`  | Number of CPU cores to use. Default: 1 (qemu equivalent: `-smp VALUE`)
`--snapshot_alloc_disk=VALUE` | Disk size to create for ISO's, in GB. Default: 10 
`--snapshot_alloc_mem=VALUE`  | Memory to allocate to session, in GB. Default: 4 (qemu equivalent: `-m VALUE*1024`)
`--snapshot_use_master=VALUE` | When 1, do NOT create a snapshot, so that all changes are written to the master VM (not for ISO's). Default: 0 (changes are lost)

The full list of additional arguments can be obtained with command `qwdctl start` without providing a VM.
The `VM` argument can be a virtual machine installed for the service file, or any other local file (full path).

A URL is shown. Open a browser to view the session. 
```
$ qwdctl start /var/lib/qemu-web-desktop/machines/TinyCore-current.iso
http://localhost:6005/vnc.html?resize=scale&autoconnect=true&host=localhost&port=6005
```

The sessions are launched with your current user credentials, not by the web service.

:warning: All sessions are started in one-shot mode, i.e. closing the browser will end the session. Except when starting with the `--snapshot_use_master=1` option (not for ISO's), the session and the associated snapshot/qcow2 file will be lost. Copy the qcow2 file before ending the session. There is no upport for GPU pass-through with this manual launch.

You can force a local session to stop with any of:
```bash
qwdctl stop PID|TOKEN
```

And you can stop and clear all local sessions with any of:
```bash
qwdctl stop
```

Last, you can monitor all running sessions, with:
```bash
qwdctl
```

## Starting sessions via the web service (REST API)

To launch a session from the command line, but going through the web service (REST API), use e.g.:

```
curl -X POST \
  http://server/cgi-bin/qemu-web-desktop.pl \
  -F "user=farhi" \
  -F "password=XXXXX" \
  -F "machine=slax.iso" \
  -F "cpu=2" \
  -F "memory=2" \
  -F "snapshot_lifetime=43200" \
  -F "create=Create" | grep -E 'Connect to your machine|session_stop'
```
A line containing "Connect to your machine" shows the URL to connect to.
The session name is also indicated:
```
<td><a href="http://localhost/darts/vnc.html?resize=remote&autoconnect=true&path=?token=n9W6wkOdOltxPCiEhgoG" target=_blank class="btn connect" title="Connect to your machine">&#9654;&nbsp;Connect</a>
<input type=hidden name=session_stop value="qemu-web-desktop_jG24xFUh">
```

To stop the corresponding session, use:
```
curl -X POST \
  http://server/cgi-bin/qemu-web-desktop.pl \
  -F "session_stop=qemu-web-desktop_jG24xFUh" | grep -E 'Stopped'
```
which results in:
```
<h1>Data Analysis Remote Treatment Service: -</h1><ul class='status'></ul></div><div class='card'><p><span class="badge ok">OK</span> Stopped <b>qemu-web-desktop_jG24xFUh slax.iso</b> that was started on [Fri Jul 17 11:09:44 2026] by farhi </p></div>
```

