Skip to content

Latest commit

 

History

History
92 lines (68 loc) · 3.89 KB

README.md

File metadata and controls

92 lines (68 loc) · 3.89 KB
Raw

VmChamp

Simple and fast creation of throwaway VMs on your local machine. Connect via SSH in just a few seconds.

✨ Features

  • Create throwaway VMs on your local machine and connect via SSH in just a few seconds.
  • Fast and easy to use.
  • Fast boot times because by default uses minimal cloud images.
  • On demand download of latest Debian, Ubuntu, Arch, Fedora, CentOS and Alma cloud images.
  • Shell completion.
  • Customizable cloud-init commands if needed.
  • Uses KVM, QEMU and libvirt.

🤔 Why?

Sometimes Docker containers are not sufficient for all use cases. For example when you want to load or unload kernel modules, test grub configs or doing low level networking stuff. Also when Systemd is needed to test unit files or install and test applications that require an init system. In this case a VM is often the better choice. Unfortunately it usually takes far too long to create a local VM for quick tests. Download ISO, create VM, run installer, network config, reboot, ssh login. This usually takes at least 5-15 minutes. VmChamp can create local VMs within seconds and then establish a network connection via SSH.

🔧 Prerequisites

Your local linux machine needs to support virtualization and KVM must be installed and working.

A default network interface defined in libvirt must be present. Usually it comes with one by default named "default". If your default interface is not started (#3) try:

# use sudo if your user is not in the libvirt group
virsh --connect qemu:///system net-start --network default
virsh --connect qemu:///system net-autostart default

🚀 Usage

VmChamp run mytestvm
# or VmChamp run mytestvm --os debian11 --mem 256MB --disk 4GB

For shell completion put this in your ~.zshrc:

source <(VmChamp --completion zsh)

Description:

Usage:
  vmchamp [command] [options]

Options:
  --completion <completion>  generate shell completion. (zsh or bash)
  --version                  Show version information
  -?, -h, --help             Show help and usage information

Commands:
  run, start <name>                      start a new VM [default: testvm]
  clean                                  delete all vms and images
  remove, rm <debiantestvm>              removes a vm [default: testvm]
  reboot, reset, restart <debiantestvm>  force restarts a vm [default: testvm]
  ssh <debiantestvm>                     connect to vm via ssh [default: testvm]
  list, ls, ps                           list all existing vms
  images, os                             get a list of all available os images

🏗️ Build

Simply use the included bash script as follows:

./build.sh <version> <output dir>

For example:

./build.sh 1.2.3 ~/build/

Output dir defaults to ./build/.