QEMU-WEB-DESKTOP.PL(1)

📦
version 26.07.23.1 · 6 versions
, in ubuntu stonking

✨ NAME ✨

qemu-web-desktop.pl — bestie, it controls qemu-web-desktop. That's literally the whole job description. 💅

Welcome to the QEMU-WEB-DESKTOP.PL(1) manual, User Commands edition. Grab a snack, we're doing this together. 🍓

🚀 SYNOPSIS 🚀

qwdctl [help|download|refresh|status|start VM|stop|gpu|gpu-unlock|enable|disable|purge|edit] ...

💖 DESCRIPTION 💖

okay so. qwdctl controls the availability of virtual machines for the qemu-web-desktop. That's the main character job. 🎀

But wait, there's more, and it's giving multitool: you can also display the status of the running sessions, and yes you can absolutely start virtual machines manually and display them in a browser. Obsessed. 🦋

🎀 OPTIONS: 🎀

  • --help, help, -h — shows this help. iconic, helpful, we love her. 😌
  • --disable, disable VM, one-shot, gpu — deactivate a [VM] entry. Saying qwdctl --disable one-shot disables the one-shot section in /usr/share/qemu-web-desktop/html/desktop/index.html. Saying qwdctl --disable gpu disables the GPU support (same as --gpu-unlock). 🚫
  • --download, download, update — scans the /etc/qemu-web-desktop/machines.conf file looking for [name.ext] and downloads them when URL are given. a qwdctl --refresh is then performed. Virtual machine images are stored into /var/lib/qemu-web-desktop/machines. Additional machine descriptions can be given in /etc/qemu-web-desktop/config.d/*.ini files. 🫶
  • --edit, edit [machines|config|web|VM] — edit the machines list, the service configuration file or the service web page. In the case of the machines list, the qwdctl --download command is triggered automatically after edit. When given a VM name, the file holding the [VM] entry is edited. Set the $EDITOR variable to select the text editor to use. In case the qwdctl edit machines has no effect on the index.html service landing page, specify set QWDCTL_INSERT=yes or option --machine-insert. It is recommended to use the --enable and --disable to manage the VM/machine list. 📝
ngl, that last sentence is a gentle "please use the other flags bestie" and we should respect it. 🙈
  • --enable, enable VM|FILE|URL|one-shot|gpu {'DESCRIPTION'} — add or (re)activate a [VM] entry, file or URL. Optional description is given as a string. qwdctl --enable one-shot activates the one-shot section in /usr/share/qemu-web-desktop/html/desktop/index.html. qwdctl --enable gpu activates the GPU support (same as --gpu). ✅
  • --gpu, gpu VENDOR:MODEL — configure GPU for pass-through. The GPU_ids are e.g. 10de:1d01. 🔥
  • --gpu-unlock, gpu-unlock — unlock/re-attach all GPU's to server (uninstall pass-through). 🔓
  • --machine-insert — used with --download/--refresh, force to modify the /usr/share/qemu-web-desktop/html/desktop/index.html landing page instead of using an include. Same as QWDCTL_INSERT=yes shell variable. 🧩
  • --refresh, refresh — scan the /etc/qemu-web-desktop/machines.conf file, and generate the /var/lib/qemu-web-desktop/machines.html that lists available images to show in the qemu-web-desktop main form. Additional machine descriptions can be given in /etc/qemu-web-desktop/config.d/*.ini files. 🌸
  • --status, status — list running sessions, as well as enabled and disabled machines. vibe check on everything at once. 👑 (wait, it's not --status listed there... okay yes it is, keep reading)
  • --start, start VM ... — start the given VM or ISO file (full path) in a browser. Connect to it with the displayed URL. Further arguments are passed to the service (see config.pl) e.g. --snapshot_alloc_mem=1 (in GB) and --snapshot_alloc_cpu=2. Changes are lost except when specifying option --snapshot_use_master=1, requiring write access. When running ISO's you may also specify --snapshot_alloc_disk=40 (in GB). Use qwdctl --start to get the full list of default VM settings. 🚀
💀 heads up: changes are lost unless you pass --snapshot_use_master=1, and that one needs write access. no cap.
  • --stop, stop TOKEN — stop sessions matching TOKEN. Some snapshot files may be left-over. 🛑
  • --purge, purge {VMNAME} — remove VM files which are inactive and not used. When VM argument is given, only files starting by VM are checked. 🧹
  • --version, version, -v — show qwdctl version. ⭐
  • --yes, -y — assume yes to questions. Same as QWDCTL_YES=1 shell variable. 🙌

✍️ AUTHOR: ✍️

Written by Roland Mas and Emmanuel Farhi. 🫶

📁 FILES: 📁

The QWD service configuration is defined in:

  • /etc/qemu-web-desktop/config.pl
  • /etc/qemu-web-desktop/config.d/*.pl

The QWD available VM's are defined in:

  • /var/lib/qemu-web-desktop/machines
  • /etc/qemu-web-desktop/machines.conf
  • /etc/qemu-web-desktop/config.d/*.ini

Entries should contain lines:

[name.ext or URL] description=<name of machine to appear in the form>

In addition, any line with:

url=<link>

will retrieve the given file with: qwdctl download

When the description is missing, the VM file name is used. Supported virtual machine formats: ISO, QCOW2, VDI, VMDK, RAW, VHD/VHDX, QED. 🌈

The QWD landing/login page is in:

  • /usr/share/qemu-web-desktop/html/desktop/index.html
  • /var/lib/qemu-web-desktop/machines.html

The QWD service script is in:

🌿 ENVIRONMENT VARIABLES: 🌿

  • EDITOR — Set the text editor to use, e.g. nano. Default is to use nano or $EDITOR. 🖊️
  • QWDCTL_INSERT=yes — is equivalent to setting --machine-insert. 🧩
  • QWDCTL_YES=1 — is equivalent to setting --yes (skip confirm). 🙈

📝 AUTHOR 📝

Written by Emmanuel Farhi <emmanuel.farhi@synchrotron-soleil.fr>. 💌

Copyright © 2020- Synchrotron Soleil, AGPL3. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 💀 (dramatic but fr fr, that's a real caveat, not a bit)

👀 SEE ALSO 👀

The full documentation for qemu-web-desktop.pl is maintained as a Texinfo manual. If the info and qemu-web-desktop.pl programs are properly installed at your site, the command

info qemu-web-desktop.pl

should give you access to the complete manual. 📖✨

okay bestie that's the whole thing, mwah 🫶 — this was qemu-web-desktop.pl version 26.07.23, dated July 2026, and yes I'm adding a little sparkle because it ate and left no crumbs. byeee 💖🎀🦋

📦 where this page comes from