diff --git a/README.md b/README.md index a2ffb1d..6c0e8f3 100644 --- a/README.md +++ b/README.md @@ -1,157 +1,215 @@ -## kvm-install-vm +# kvm-install-vm -A bash wrapper around virt-install to build virtual machines on a local KVM -hypervisor. You can run it as a normal user which will use `qemu:///session` to -connect locally to your KVM domains. +A Bash wrapper around `virt-install` to quickly spin up and manage local KVM virtual machines. -Tested on the latest Fedora. +## Table of Contents -### Prerequisites +1. [Features](#features) +2. [Prerequisites](#prerequisites) +3. [Installation](#installation) +4. [Quick Start](#quick-start) +5. [Installation](#installation) +6. [Usage](#usage) + - [Create a VM](#create-a-vm) + - [Delete a VM](#delete-a-vm) + - [Attach a Disk](#attach-a-disk) +7. [Configuration](#configuration) +8. [Hostname Resolution (optional)](#hostname-resolution-optional) +9. [Troubleshooting](#troubleshooting) +10. [Testing](#testing) +11. [Contributing](#contributing) +12. [License](#license) -You need to have the KVM hypervisor installed, along with a few other packages (naming of packages can differ on other distributions): +## ✨ Features -- virt-install >= 3.0.0 -- libguestfs-tools-c -- qemu-img -- libvirt-client -- libosinfo +- 🚀 One-command VM provisioning with sensible defaults +- 🌐 Support for multiple distro cloud-images (AlmaLinux, Debian, Rocky, Ubuntu, and more) +- 🔧 Customize CPU, RAM, disk size, architecture, and timezone +- 💾 Attach additional disks on the fly +- ⚙️ Persist your favorite defaults via `~/.kivrc` -To install the dependencies, run: +## 🔧 Prerequisites -- Fedora example: +You’ll need a working KVM/libvirt setup and these utilities: -``` -sudo dnf -y install virt-install libguestfs-tools-c qemu-img libvirt-client wget libosinfo +
+Install on Fedora + +```bash +sudo dnf install -y \ + virt-install \ + libguestfs-tools-c \ + qemu-img \ + libvirt-client \ + libosinfo \ + wget ``` -- Ubuntu example: +
-``` -sudo apt install -y virtinst libguestfs-tools qemu-utils libvirt-clients wget libosinfo-bin +
+Install on Ubuntu/Debian + +```bash +sudo apt update && sudo apt install -y \ + virtinst \ + libguestfs-tools \ + qemu-utils \ + libvirt-clients \ + libosinfo-bin \ + wget ``` -If you want to resolve guests by their hostnames, install the `libvirt-nss` package: +
-- Fedora example: +## 🚀 Quick Start -``` -sudo dnf -y install libvirt-nss +**Create your first VM** + +```bash +# Rocky Linux 9 VM named "myvm" with defaults +./kvm-install-vm create myvm ``` -- Ubuntu example: +Connect via `ssh myvm` once cloud-init finishes. Run the help command to see all options: ```bash -sudo apt install -y libnss-libvirt +kvm-install-vm help ``` -Then, add `libvirt` and `libvirt_guest` to list of **hosts** databases in -`/etc/nsswitch.conf`. See [here](https://libvirt.org/nss.html) for more -information. +## Installation -### Usage +Copy the script to a folder in your PATH, and the config file to your HOME directory: ```bash -./kvm-install-vm help +cp kvm-install-vm $HOME/local/bin/ +cp .kivrc $HOME ``` -#### Creating Guest VMs +Optionally, you may instead copy the script globally: ```bash -# Create VM with the default parameters: Rocky Linux 9, 1 vCPU, 1.5GB RAM, 10GB disk capacity, x86_64 arch -kvm-install-vm create myvm +sudo cp kvm-install-vm /usr/local/bin +``` -# Create VM with custom parameters: 2 vCPUs, 2GB RAM, and 20GB disk capacity. -kvm-install-vm create -c 2 -m 2048 -d 20 myvm +## 💻 Usage -# Create a Debian 12 VM with the default parameters. -kvm-install-vm create -t debian12 myvm +### Create a VM +```bash +kvm-install-vm create [OPTIONS] +``` -# Create a default VM with UTC timezone. -kvm-install-vm create -T UTC myvm +```bash +# Defaults: Rocky Linux 9, 1 vCPU, 1536 MB RAM, 10 GB disk, x86_64 +kvm-install-vm create myvm ``` -#### Deleting a Guest Domain +**Common flags:** +- `-c, --cpus ` Set vCPUs (default: 1) +- `-m, --memory ` RAM in MB (default: 1536) +- `-d, --disk ` Disk size in GB (default: 10) +- `-A, --arch ` Architecture (x86_64 or aarch64) +- `-t, --distro ` Distro key (see BUILTIN_VMS) +- `-T, --tz ` Timezone (default: host timezone) + +### Delete a VM ```bash -# Remove (destroy and undefine) a guest domain. WARNING: This will delete the guest domain and any changes made inside it! +# Destroys domain and deletes its storage! kvm-install-vm remove myvm ``` -#### Attaching a new disk +### Attach a Disk + +```bash +kvm-install-vm attach-disk \ + -d \ + -s .qcow2 \ + -t \ + +``` + +## ⚙️ Configuration + +You can override defaults by creating a `~/.kivrc` file: ```bash -# Attach a 10GB disk device named example-5g.qcow2 to the myvm guest domain. -kvm-install-vm attach-disk -d 10 -s example-5g.qcow2 -t vdb myvm +# Example ~/.kivrc +# Default vCPUs and RAM +VCPUS=2 +MEMORY=2048 ``` -### Setting Custom Defaults +Order of precedence: -Copy the `.kivrc` file to your $HOME directory to set custom defaults. This is -convenient if you find yourself repeatedly setting the same options on the -command line, like the distribution or the number of vCPUs. +1. Built‑in script defaults +2. `.kivrc` settings +3. Command‑line flags -Options are evaluated in the following order: +### Using other images -- Default options set in the script -- Custom options set in `.kivrc` -- Option flags set on the command line +Use the BUILTIN_VMS array in `.kivrc` to add new images: -### Notes +```bash +BUILTIN_VMS+=("almalinux9:AlmaLinux 9 cloud image:x86_64:https://repo.almalinux.org/almalinux/9/cloud/images/AlmaLinux-9-cloud.qcow2|almalinux") +``` -1. This script will download a qcow2 cloud image from the respective - distribution's download site. See script for URLs. +You may add multiple lines to include multiple VMs. See `.kivrc` for more details. -2. If using libvirt-nss, keep in mind that DHCP leases take some time to - expire, so if you create a VM, delete it, and recreate another VM with the - same name in a short period of time, there will be two DHCP leases for the - same host and its hostname will likely not resolve until the old lease - expires. +## 🌐 Hostname Resolution (optional) -3. The Operating System information database (osinfo-db) provides Operating - System specific information needed to create guests for the various systems - supported by `kvm-install-vm`. The database files provided by your package - manager may be out of date and not provide definitions for recent Operating - System versions. If you encounter the following error message, you may need - to update the database files: - `ERR: Unknown OS variant ''. Please update your osinfo-db.` - If you have already updated your system, and the osinfo-db is still to old, - then you can use the `osinfo-db-import` tool with the `--local` option, to - install an up-to-date database in your home directory which will not - conflict with your package manager files. The `osinfo-db-import` tool is - provided by the rpm/deb packages `osinfo-db-tools`. - See https://libosinfo.org/download for more information. +To resolve your VMs by hostname, install the `libvirt-nss` plugin and update `/etc/nsswitch.conf`: -### Testing +```bash +# Fedora +sudo dnf install -y libvirt-nss +# Ubuntu/Debian +sudo apt install -y libnss-libvirt +``` -Tests are written using [Bats](https://github.com/sstephenson/bats). To -execute the tests, run `./test.sh` in the root directory of the project. +Then add `libvirt` and `libvirt_guest` to the hosts line in `/etc/nsswitch.conf`: -### Use Cases +``` +hosts: files mdns4_minimal [NOTFOUND=return] libvirt libvirt_guest dns myhostname +``` -If you don't need to use Docker or Vagrant, don't want to make changes to a -production machine, want to tinker with the kernel or systemd, or just want to spin up one or more VMs locally to test things like: +See the [libvirt NSS docs](https://libvirt.org/nss.html) for details. -- high availability -- clustering -- package installs -- preparing for exams -- checking for system defaults -- anything else you would do with a VM +## 🐞 Troubleshooting -...then this wrapper could be useful for you. +- **Unknown OS variant**: -### Troubleshooting + ``` + ERR: Unknown OS variant ''. Please update your osinfo-db. + ``` -If you will encounter something similar: + Download the latest database: -``` -ERR: Unknown OS variant 'fedora31'. Please update your osinfo-db. See https://libosinfo.org/download for more information. -``` + ```bash + wget -O /tmp/osinfo-db.tar.xz https://releases.pagure.org/libosinfo/osinfo-db-$(date +%Y%m%d).tar.xz + osinfo-db-import --local /tmp/osinfo-db.tar.xz + ``` -Then you need to update the DB in libosinfo. -Check the url and select the latest date ( https://releases.pagure.org/libosinfo/ ) +- **DHCP hostname collisions**:\ + If you recreate a VM with the same name quickly, an old lease may linger—wait for it to expire or clear `/var/lib/libvirt/dnsmasq/*.leases`. +## 🧪 Testing + +Tests are powered by [Bats](https://github.com/bats-core/bats-core).\ +Run: + +```bash +./test.sh ``` -wget -O "/tmp/osinfo-db.tar.xz" https://releases.pagure.org/libosinfo/osinfo-db-20200515.tar.xz -sudo osinfo-db-import --local "/tmp/osinfo-db.tar.xz" -``` + +## 🤝 Contributing + +1. Fork the repo +2. Create a feature branch +3. Open a pull request + +Please follow the existing code style and add tests where possible. + +## 📄 License + +This project is licensed under the [MIT License](LICENSE).