Libvirt Hooks

v1.0.1

Install scripts (hooks) of which extend and enhance the functionality of Libvirt Virtual Machines (VMs). Hooks may run at either VM start or stop, and/or be VM-specific. Develop your own, too!

Download

1. Why?
2. Related Projects
3. Documentation
4. Host Requirements
5. Download
6. Usage
- 6.1. Verify Installer is Executable
- 6.2. installer.bash
7. Features
8. Planned Features
9. Credits
10. Disclaimer
11. Contact
12. References

1. Why?

Libvirt is a tool which manages guests (VMs) and the platforms which run those VMs (example: QEMU, KVM). Libvirt includes logic to watch for specific events on the Host OS (ex: Linux) to allow for script execution.

Scripts are not available out-of-the-box in Libvirt, but are possible if you understand Linux, systemd, and a scripting language (ex: Bash, Python). This is not acceptable should we as a community wish to attract newcomers to VMs, VFIO, and Linux as a whole.

To assist beginners (and others), included are some useful scripts for VMs.

2. Related Projects

Project	Codeberg	GitHub
Deploy VFIO	link	link
Auto X.Org	link	link
Generate Evdev	link	link
Guest Machine Guide	link	link
Libvirt Hooks	link	link
Power State Virtual Machine Manager	link	link

4. Host Requirements

4.1. Operating System

Linux.

4.2. Software

Libvirt
QEMU

4.3. Hardware

The following firmware options are supported and enabled (motherboard and CPU):

IOMMU
- For AMD machines: AMD-Vi
- For Intel machines: VT-d
- For ARM architectures: SMMU

5. Download

Download the Latest Release: Codeberg, GitHub
Download the .zip file:
1. Viewing from the top of the repository's (current) webpage, click the drop-down icon:
  - ··· on Codeberg.
  - <> Code on GitHub.
2. Click Download ZIP and save.
3. Open the .zip file, then extract its contents.
Clone the repository:
1. Open a Command Line Interface (CLI).
  - Open a console emulator (for Debian systems: Konsole).
  - Open a existing console: press CTRL + ALT + F2, F3, F4, F5, or F6.
    - To return to the desktop, press CTRL + ALT + F7.
    - F1 is reserved for debug output of the Linux kernel.
    - F7 is reserved for video output of the desktop environment.
    - F8 and above are unused.
2. Change your directory to your home folder or anywhere safe:
  - cd ~
3. Clone the repository:
  - git clone https://www.codeberg.org/portellam/libvirt-hooks
  - git clone https://www.github.com/portellam/libvirt-hooks

6. Usage

6.1. Verify Installer is Executable

Open the CLI (see Download).
Go to the directory of where the cloned/extracted repository folder is: cd name_of_parent_folder/libvirt-hooks/
Make the installer script file executable: chmod +x installer.bash
- Do not make any other script files executable. The installer will perform this action.
- Do not make any non-script file executable. This is not necessary and potentially dangerous.

6.2. `installer.bash`

From within project folder, execute: sudo bash installer.bash
```
-h, --help               Print this help and exit.
-i, --install            Install Libvirt Hooks to system.
-u, --uninstall          Uninstall Libvirt Hooks from system.
```
- The installer will place Libvirt Hooks in /etc/libvirt/hooks/.
- The installer will place all project script files in /usr/local/bin/.

7. Features

7.1. `cfscpu`

Set CPU thread priority in CPU scheduler.
Source

7.2. `hugepages`

Allocate Host RAM to pages for Guest(s).
Documentation
Source

7.3. `isolcpu`

Isolate CPU threads from Host, to allocate to Guest(s).
Documentation

7.4. `nosleep`

Prevent Host sleep if Guest is running.
Documentation

7.5. `dosleep`

Sleep Guest at Host sleep.
Stops nosleep service.

8. Planned Features

8.1. `ddcutil`

Switch active monitor input at VM start.
Source

8.2. `beforeoff-dohibernate`

Hibernate Guest at Host shutdown.
Stops nosleep service.

8.3. `dohibernate`

Hibernate Guest at Host sleep.
Stops nosleep service.

8.4. `virtual-nas`

Share designated Host directory storage to Guest, on a file server over a Libvirt virtual network.
Helpful for circumstances where a given Guest cannot be trusted with direct access to storage.
- For Read-Write permissions: ensure file system integrity.
- For Read-only permissions: preventing malware transmission.
- Virtualizing an untrusted or legacy OS (example: Windows XP).

9. Credits

Some of what you see here is directly inspired by others' work, from either the Arch Wiki or the Reddit forum.

10. Disclaimer

Use at your own risk. As stated in this article, avoid recursion in your Hooks. This can lead to at worst a deadlock of the Host (and all Guests) or at best the failure of a single Guest to start.

11. Contact

Did you encounter a bug? Do you need help? Please visit the Issues page (Codeberg, GitHub).

12. References

1.

Calling libvirt functions from within a hook script. Hooks for Specific System Management - libvirt. Accessed June 14, 2024. ^{https://libvirt.org/hooks.html#calling-libvirt-functions-from-within-a-hook-script.}

2.

CPU Pinning. PCI passthrough via OVMF - ArchWiki. Accessed June 14, 2024. ^{https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#CPU_pinning.}

3.

Hooks for Specific System Management. libvirt. Accessed June 14, 2024. ^{https://libvirt.org/hooks.html.}

4.

Host lockup if Guest is left running during sleep. PCI passthrough via OVMF ArchWiki. Accessed June 14, 2024. ^{https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#Host_lockup_if_Guest_is_left_running_during_sleep.}

5.

Huge memory pages. PCI passthrough via OVMF - ArchWiki. Accessed June 14, 2024. ^{https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#Huge_memory_pages.}

6.

PassthroughPOST/VFIO-Tools. GitHub. Accessed June 14, 2024. ^{https://github.com/PassthroughPOST/VFIO-Tools.}

7.

PCI passthrough via OVMF. ArchWiki. Accessed June 14, 2024. ^{https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF.}

8.

VFIO - ‘Virtual Function I/O’ - The Linux Kernel Documentation. The linux kernel. Accessed June 14, 2024. ^{https://www.kernel.org/doc/html/latest/driver-api/vfio.html.}

9.

VFIO Discussion and Support. Reddit. Accessed June 14, 2024. ^{https://www.reddit.com/r/VFIO/.}

10.

XML Design Format. GitHub - libvirt/libvirt. Accessed June 18, 2024. ^{https://github.com/libvirt/libvirt/blob/master/docs/formatdomain.rst.}

portellam/libvirt-hooks