doc: update README (#82)

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
+<details>
+<summary>Install on Fedora</summary>
+
+```bash
+sudo dnf install -y \
+  virt-install \
+  libguestfs-tools-c \
+  qemu-img \
+  libvirt-client \
+  libosinfo \
+  wget
 ```
 
-- Ubuntu example:
+</details>
 
-```
-sudo apt install -y virtinst libguestfs-tools qemu-utils libvirt-clients wget libosinfo-bin
+<details>
+<summary>Install on Ubuntu/Debian</summary>
+
+```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:
+</details>
 
-- 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] <VM_NAME>
+```
 
-# 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 <N>`       Set vCPUs (default: 1)
+- `-m, --memory <MB>`    RAM in MB (default: 1536)
+- `-d, --disk <GB>`      Disk size in GB (default: 10)
+- `-A, --arch <ARCH>`    Architecture (x86_64 or aarch64)
+- `-t, --distro <NAME>`  Distro key (see BUILTIN_VMS)
+- `-T, --tz <ZONE>`      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
-# 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
+kvm-install-vm attach-disk \
+  -d <GB> \
+  -s <FILENAME>.qcow2 \
+  -t <DEVICE_NAME> \
+  <VM_NAME>
 ```
 
-### Setting Custom Defaults
+## ⚙️ Configuration
 
-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.
+You can override defaults by creating a `~/.kivrc` file:
+
+```bash
+# Example ~/.kivrc
+# Default vCPUs and RAM
+VCPUS=2
+MEMORY=2048
+```
 
-Options are evaluated in the following order:
+Order of precedence:
 
-- Default options set in the script
-- Custom options set in `.kivrc`
-- Option flags set on the command line
+1. Built‑in script defaults
+2. `.kivrc` settings
+3. Command‑line flags
 
-### Notes
+### Using other images
 
-1. This script will download a qcow2 cloud image from the respective
-   distribution's download site.  See script for URLs.
+Use the BUILTIN_VMS array in `.kivrc` to add new images:
 
-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.
+```bash
+BUILTIN_VMS+=("almalinux9:AlmaLinux 9 cloud image:x86_64:https://repo.almalinux.org/almalinux/9/cloud/images/AlmaLinux-9-cloud.qcow2|almalinux")
+```
 
-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 '<name>'. 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.
+You may add multiple lines to include multiple VMs. See `.kivrc` for more details.
 
-### Testing
+## 🌐 Hostname Resolution (optional)
 
-Tests are written using [Bats](https://github.com/sstephenson/bats).  To
-execute the tests, run `./test.sh` in the root directory of the project.
+To resolve your VMs by hostname, install the `libvirt-nss` plugin and update `/etc/nsswitch.conf`:
 
-### Use Cases
+```bash
+# Fedora
+sudo dnf install -y libvirt-nss
+# Ubuntu/Debian
+sudo apt install -y libnss-libvirt
+```
 
-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:
+Then add `libvirt` and `libvirt_guest` to the hosts line in `/etc/nsswitch.conf`:
 
-- high availability
-- clustering
-- package installs
-- preparing for exams
-- checking for system defaults
-- anything else you would do with a VM
+```
+hosts: files mdns4_minimal [NOTFOUND=return] libvirt libvirt_guest dns myhostname
+```
 
-...then this wrapper could be useful for you.
+See the [libvirt NSS docs](https://libvirt.org/nss.html) for details.
 
-### Troubleshooting
+## 🐞 Troubleshooting
 
-If you will encounter something similar:
+- **Unknown OS variant**:
 
   ```
-ERR: Unknown OS variant 'fedora31'. Please update your osinfo-db.  See https://libosinfo.org/download for more information.
+  ERR: Unknown OS variant '<name>'. Please update your osinfo-db.
   ```
 
-Then you need to update the DB in libosinfo.
-Check the url and select the latest date ( https://releases.pagure.org/libosinfo/ )
+  Download the latest database:
 
+  ```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
   ```
-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"
+
+- **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
 ```
+
+## 🤝 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).