{"id":16494547,"url":"https://github.com/portellam/libvirt-hooks","last_synced_at":"2025-10-27T21:31:16.207Z","repository":{"id":184591644,"uuid":"672164299","full_name":"portellam/libvirt-hooks","owner":"portellam","description":"Install scripts (hooks) of which extend and enhance the functionality of Virtual Machines (VMs) on Linux. Hooks may run at either VM start or stop, and/or be VM-specific. Develop your own, too!","archived":false,"fork":false,"pushed_at":"2024-07-04T18:33:16.000Z","size":230,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-01T08:41:38.623Z","etag":null,"topics":["bash","bash-script","hugepages","kvm","libvirt","libvirt-hooks","pci-passthrough","qemu","ram","script","vfio","vfio-pci","vfio-setup","virtual-machine","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/portellam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-29T06:10:35.000Z","updated_at":"2024-07-21T14:26:37.000Z","dependencies_parsed_at":"2024-01-01T10:03:30.663Z","dependency_job_id":"0d7f918c-a734-4367-bda4-5ece5607528e","html_url":"https://github.com/portellam/libvirt-hooks","commit_stats":{"total_commits":106,"total_committers":2,"mean_commits":53.0,"dds":0.08490566037735847,"last_synced_commit":"168b2e87710fb5e66f974ec4b3964405f8e41604"},"previous_names":["portellam/libvirt-hooks"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portellam%2Flibvirt-hooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portellam%2Flibvirt-hooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portellam%2Flibvirt-hooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/portellam%2Flibvirt-hooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/portellam","download_url":"https://codeload.github.com/portellam/libvirt-hooks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238560933,"owners_count":19492611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bash-script","hugepages","kvm","libvirt","libvirt-hooks","pci-passthrough","qemu","ram","script","vfio","vfio-pci","vfio-setup","virtual-machine","virtualization"],"created_at":"2024-10-11T14:14:19.822Z","updated_at":"2025-10-27T21:31:16.201Z","avatar_url":"https://github.com/portellam.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Libvirt Hooks\n### v1.0.2\nInstall scripts (hooks) of which extend and enhance the functionality of Libvirt\nVirtual Machines (VMs). Hooks may run at either VM start or stop, and/or be\nVM-specific. Develop your own, too!\n\n## [Download](#4-download)\n#### View this repository on [Codeberg][01] or [GitHub][02].\n[01]: https://codeberg.org/portellam/libvirt-hooks\n[02]: https://github.com/portellam/libvirt-hooks\n##\n\n## Table of Contents\n- [1. Why?](#1-why)\n- [2. Related Projects](#2-related-projects)\n- [3. Documentation](#3-documentation)\n- [4. Download](#4-download)\n- [5. Usage](#5-usage)\n- [6. Current Features](#6-current-features)\n- [7. Planned Features](#7-planned-features)\n- [8. Credits](#8-credits)\n- [9. Disclaimer](#9-disclaimer)\n- [10. Contact](#10-contact)\n- [11. References](#11-references)\n\n## Contents\n### 1. Why?\nLibvirt is a tool which manages guests (VMs) and the platforms which run those\nVMs (example: QEMU, KVM). Libvirt includes logic to watch for specific events\non the Host OS (ex: Linux) to allow for script execution.\n\nScripts are not available out-of-the-box in Libvirt, but are possible if you\nunderstand Linux, `systemd`, and a scripting language (ex: Bash, Python).\n**This is not acceptable** should we as a community wish to attract newcomers to\nVMs, VFIO, and Linux as a whole.\n\nTo assist beginners (and others), included are some useful scripts for VMs.\n\n### 2. Related Projects\nTo view other relevant projects, visit [Codeberg][21]\nor [GitHub][22].\n\n[21]: https://codeberg.org/portellam/vfio-collection\n[22]: https://github.com/portellam/vfio-collection\n\n### 3. Documentation\n- What is VFIO?[\u003csup\u003e[9]\u003c/sup\u003e](#9)\n- VFIO Discussion and Support[\u003csup\u003e[8]\u003c/sup\u003e](#8)\n- Hardware-Passthrough Guide[\u003csup\u003e[7]\u003c/sup\u003e](#7)\n\n### 4. Download\n- Download the Latest Release:\u0026ensp;[Codeberg][51] or [GitHub][52].\n\n- Download the `.zip` file:\n    1. Viewing from the top of the repository's (current) webpage, click the\n        drop-down icon:\n        - `···` on Codeberg.\n        - `\u003c\u003e Code ` on GitHub.\n    2. Click `Download ZIP` and save.\n    3. Open the `.zip` file, then extract its contents.\n\n- Clone the repository:\n    1. Open a Command Line Interface (CLI) or Terminal.\n        - Open a console emulator (for Debian systems: Konsole).\n        - **Linux only:** Open an existing console: press `CTRL` + `ALT` + `F2`,\n        `F3`, `F4`, `F5`, or `F6`.\n            - **To return to the desktop,** press `CTRL` + `ALT` + `F7`.\n            - `F1` is reserved for debug output of the Linux kernel.\n            - `F7` is reserved for video output of the desktop environment.\n            - `F8` and above are unused.\n    2. Change your directory to your home folder or anywhere safe:\n        - `cd ~`\n    3. Clone the repository:\n        - `git clone https://www.codeberg.org/portellam/libvirt-hooks`\n        - `git clone https://www.github.com/portellam/libvirt-hooks`\n\n[51]: https://codeberg.org/portellam/libvirt-hooks/releases/latest\n[52]: https://github.com/portellam/libvirt-hooks/releases/latest\n\n### 5. Usage\n#### 5.1. Verify Installer is Executable\n1. Open the CLI (see [Download](#4-download)).\n\n2. Go to the directory of where the cloned/extracted repository folder is:\n`cd name_of_parent_folder/libvirt-hooks//`\n\n3. Make the installer script file executable: `chmod +x installer.bash`\n    - Do **not** make any other script files executable. The installer will perform\n  this action.\n    - Do **not** make any non-script file executable. This is not necessary and\n  potentially dangerous.\n\n#### 5.2. `installer.bash`\n- From within project folder, execute: `sudo bash installer.bash`\n\n  ```xml\n  -h, --help               Print this help and exit.\n  -i, --install            Install Libvirt Hooks to system.\n  -u, --uninstall          Uninstall Libvirt Hooks from system.\n  ```\n  - The installer will place Libvirt Hooks in `/etc/libvirt/hooks/`.\n  - The installer will place all project script files in `/usr/local/bin/`.\n\n### 6. Current Features\n#### 7.1. `cfscpu`\n- Set CPU thread priority in CPU scheduler.\n- [Source](#6)\n\n#### 6.2. `hugepages`\n- Allocate Host RAM to pages for Guest(s).\n- [Documentation](#5)\n- [Source](#6)\n\n#### 6.3. `isolcpu`\n- Isolate CPU threads from Host, to allocate to Guest(s).\n- [Documentation](#2)\n\n#### 6.4. `nosleep`\n- Prevent Host sleep if Guest is running.\n- [Documentation](#3)\n\n#### 6.5. `dosleep`\n- Sleep Guest at Host sleep.\n- Stops [`nosleep`] service.\n\n### 7. Planned Features\n#### 7.1. `ddcutil`\n- Switch active monitor input at VM start.\n- [Source](#6)\n\n#### 7.2. `beforeoff-dohibernate`\n- Hibernate Guest at Host shutdown.\n- Stops [`nosleep`] service.\n\n#### 7.3. `dohibernate`\n- Hibernate Guest at Host sleep.\n- Stops [`nosleep`] service.\n\n#### 7.4. `virtual-nas`\n- Share designated Host directory storage to Guest, on a file server over a\nLibvirt virtual network.\n- Helpful for circumstances where a given Guest cannot be trusted with direct\naccess to storage.\n    - For Read-Write permissions: ensure file system integrity.\n    - For Read-only permissions: preventing malware transmission.\n    - Virtualizing an untrusted or legacy OS (example: Windows XP).\n\n[`nosleep`]: #64-nosleep\n\n### 8. Credits\nSome of what you see here is directly inspired by others' work, from either the\n[Arch Wiki](#7) or the [Reddit forum](#8).\n\n### 9. Disclaimer\nUse at your own risk. As stated in [this article](#4), avoid recursion in\nyour Hooks. This can lead to at worst a deadlock of the Host (and all Guests) or\nat best the failure of a single Guest to start.\n\n### 10. Contact\nDo you need help? Please visit the [Issues][101] page.\n\n[101]: https://github.com/portellam/libvirt-hooks/issues\n\n### 11. References\n#### 1.\n\u0026nbsp;\u0026nbsp;**Calling libvirt functions from within a hook script**. Hooks for Specific\nSystem Management - libvirt. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://libvirt.org/hooks.html#calling-libvirt-functions-from-within-a-hook-script.\u003c/sup\u003e\n\n#### 2.\n\u0026nbsp;\u0026nbsp;**CPU Pinning**. PCI passthrough via OVMF - ArchWiki. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#CPU_pinning.\u003c/sup\u003e\n\n#### 3.\n\u0026nbsp;\u0026nbsp;**Hooks for Specific System Management**. libvirt. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://libvirt.org/hooks.html.\u003c/sup\u003e\n\n#### 4.\n\u0026nbsp;\u0026nbsp;**Host lockup if Guest is left running during sleep**. PCI passthrough via OVMF\nArchWiki. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#Host_lockup_if_Guest_is_left_running_during_sleep.\u003c/sup\u003e\n\n#### 5.\n\u0026nbsp;\u0026nbsp;**Huge memory pages**. PCI passthrough via OVMF - ArchWiki. Accessed June 14,\n2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#Huge_memory_pages.\u003c/sup\u003e\n\n#### 6.\n\u0026nbsp;\u0026nbsp;**PassthroughPOST/VFIO-Tools: A Collection of Tools and Scripts That Aim to**\n**MakePCI Passthrough a Little Easier**. GitHub. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://github.com/PassthroughPOST/VFIO-Tools.\u003c/sup\u003e\n\n#### 7.\n\u0026nbsp;\u0026nbsp;**PCI passthrough via OVMF**. ArchWiki. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://wiki.archlinux.org/title/PCI_passthrough_via_OVMF.\u003c/sup\u003e\n\n#### 8.\n\u0026nbsp;\u0026nbsp;**r/VFIO**. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://www.reddit.com/r/VFIO/.\u003c/sup\u003e\n\n#### 9.\n\u0026nbsp;\u0026nbsp;**VFIO - ‘Virtual Function I/O’ - The Linux Kernel Documentation**.\nThe linux kernel. Accessed June 14, 2024.\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u003csup\u003ehttps://www.kernel.org/doc/html/latest/driver-api/vfio.html.\u003c/sup\u003e\n##\n\n#### Click [here](#libvirt-hooks) to return to the top of this document.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fportellam%2Flibvirt-hooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fportellam%2Flibvirt-hooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fportellam%2Flibvirt-hooks/lists"}