mirror
/
kvm-install-vm
mirror of https://github.com/giovtorres/kvm-install-vm.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc: update README (#82)

pull/83/head 1.0.2
Giovanni Torres 8 months ago committed by GitHub
parent
879974377c
commit
555ad6adab
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 154 additions and 96 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 250
      README.md

250
README.md
Unescape View File

@ -1,157 +1,215 @@
## kvm-install-vm # kvm-install-vm
A bash wrapper around virt-install to build virtual machines on a local KVM A Bash wrapper around `virt-install` to quickly spin up and manage local KVM virtual machines.
hypervisor. You can run it as a normal user which will use `qemu:///session` to
connect locally to your KVM domains.
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 - 🚀 One-command VM provisioning with sensible defaults
- libguestfs-tools-c - 🌐 Support for multiple distro cloud-images (AlmaLinux, Debian, Rocky, Ubuntu, and more)
- qemu-img - 🔧 Customize CPU, RAM, disk size, architecture, and timezone
- libvirt-client - 💾 Attach additional disks on the fly
- libosinfo - ⚙️ 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:
``` <details>
sudo dnf -y install virt-install libguestfs-tools-c qemu-img libvirt-client wget libosinfo <summary>Install on Fedora</summary>
```bash
sudo dnf install -y \
virt-install \
libguestfs-tools-c \
qemu-img \
libvirt-client \
libosinfo \
wget
``` ```
- Ubuntu example: </details>
``` <details>
sudo apt install -y virtinst libguestfs-tools qemu-utils libvirt-clients wget libosinfo-bin <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
``` **Create your first VM**
sudo dnf -y install libvirt-nss
```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 ```bash
sudo apt install -y libnss-libvirt kvm-install-vm help
``` ```
Then, add `libvirt` and `libvirt_guest` to list of **hosts** databases in ## Installation
`/etc/nsswitch.conf`. See [here](https://libvirt.org/nss.html) for more
information.
### Usage Copy the script to a folder in your PATH, and the config file to your HOME directory:
```bash ```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 ```bash
# Create VM with the default parameters: Rocky Linux 9, 1 vCPU, 1.5GB RAM, 10GB disk capacity, x86_64 arch sudo cp kvm-install-vm /usr/local/bin
kvm-install-vm create myvm ```
# Create VM with custom parameters: 2 vCPUs, 2GB RAM, and 20GB disk capacity. ## 💻 Usage
kvm-install-vm create -c 2 -m 2048 -d 20 myvm
# Create a Debian 12 VM with the default parameters. ### Create a VM
kvm-install-vm create -t debian12 myvm ```bash
kvm-install-vm create [OPTIONS] <VM_NAME>
```
# Create a default VM with UTC timezone. ```bash
kvm-install-vm create -T UTC myvm # 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 ```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 kvm-install-vm remove myvm
``` ```
#### Attaching a new disk ### Attach a Disk
```bash
kvm-install-vm attach-disk \
-d <GB> \
-s <FILENAME>.qcow2 \
-t <DEVICE_NAME> \
<VM_NAME>
```
## ⚙️ Configuration
You can override defaults by creating a `~/.kivrc` file:
```bash ```bash
# Attach a 10GB disk device named example-5g.qcow2 to the myvm guest domain. # Example ~/.kivrc
kvm-install-vm attach-disk -d 10 -s example-5g.qcow2 -t vdb myvm # 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 1. Built‑in script defaults
convenient if you find yourself repeatedly setting the same options on the 2. `.kivrc` settings
command line, like the distribution or the number of vCPUs. 3. Command‑line flags
Options are evaluated in the following order: ### Using other images
- Default options set in the script Use the BUILTIN_VMS array in `.kivrc` to add new images:
- Custom options set in `.kivrc`
- Option flags set on the command line
### 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 You may add multiple lines to include multiple VMs. See `.kivrc` for more details.
distribution's download site. See script for URLs.
2. If using libvirt-nss, keep in mind that DHCP leases take some time to ## 🌐 Hostname Resolution (optional)
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.
3. The Operating System information database (osinfo-db) provides Operating To resolve your VMs by hostname, install the `libvirt-nss` plugin and update `/etc/nsswitch.conf`:
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.
### 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 Then add `libvirt` and `libvirt_guest` to the hosts line in `/etc/nsswitch.conf`:
execute the tests, run `./test.sh` in the root directory of the project.
### 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 See the [libvirt NSS docs](https://libvirt.org/nss.html) for details.
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:
- high availability ## 🐞 Troubleshooting
- clustering
- package installs
- preparing for exams
- checking for system defaults
- anything else you would do with a VM
...then this wrapper could be useful for you. - **Unknown OS variant**:
### Troubleshooting ```
ERR: Unknown OS variant '<name>'. Please update your osinfo-db.
```
If you will encounter something similar: Download the latest database:
``` ```bash
ERR: Unknown OS variant 'fedora31'. Please update your osinfo-db. See https://libosinfo.org/download for more information. 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. - **DHCP hostname collisions**:\
Check the url and select the latest date ( https://releases.pagure.org/libosinfo/ ) 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).

Write Preview
Loading…
Cancel
Save