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
Split 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
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
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
# 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 '<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.
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 '<name>'. 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).

Write Preview
Loading…
Cancel
Save