wubbl0rz / vmchamp

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

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/.

vmchamp's Issues

no bash completion

VmChmap make no bash-completion, but for zsh

Edit:
I think it has to look like this for that, but it's broken.

_VmChamp_bash_complete() {
	COMPREPLY=()
	local cur completions base
	cur="${COMP_WORDS[COMP_CWORD]}"
	completions="$( VmChamp '[complete]' "${cur}")"
	local IFS=$'\n'
	COMPREPLY=($(compgen -W "${completions}" -- "${cur}"))
}

complete -F _VmChamp_bash_complete VmChamp

unknown watchdog model 'itco' in ubuntu 22.04

Got an error on ubuntu:
libvirt: Domain Config error : unsupported configuration: unknown watchdog model 'itco'
Down below is the outut of my shell and some info about my system.

❯ VmChamp --version
0.0.5

❯ VmChamp run test
👉 Creating VM: test
💻 Using OS: Debian11
📔 Memory size: 256 MiB
💽 Disk size: 4 GiB
Download: https://cloud.debian.org/images/cloud/bullseye/latest/debian-11-genericcloud-amd64.qcow2

  100% 00:00:00

libvirt: Domain Config error : unsupported configuration: unknown watchdog model 'itco'

OS Info

❯ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 22.10
Release:        22.10
Codename:       kinetic

❯ hostnamectl
 Static hostname: ubuntu-shit
       Icon name: computer
      Machine ID: 6ecf321569cc43729eee804ca317b987
         Boot ID: a5743ee4e2b74658bf976d8301cec69f
Operating System: Ubuntu 22.10
          Kernel: Linux 5.19.0-41-generic
    Architecture: x86-64
 Hardware Vendor: Lenovo
  Hardware Model: ThinkPad X1 Carbon Gen 10
Firmware Version: N3AET71W (1.36 )

Network "virbr0" doesn't exist by default

virbr0 interface didn't exist for me causing virsh errors. It's fairly simple to active this interface:

sudo virsh net-define /etc/libvirt/qemu/networks/default.xml
sudo virsh net-start default

Info: dnsmasq must be installed for this to successfully activate.

Libvirt docs say the xml is located at /usr/share/libvirt/networks/default.xml but mine was at /etc/libvirt/qemu/networks/default.xml (arch).

Maybe add it to the readme or ask the user if he wants to automatically active the bridge.

Crash on clean or create

When I run the clean command, it crashes because it can't connect to qemu (while qemu runs).

λ ~/ sudo vmchamp clean
Going to delete all VMs (1) and IMAGES
Continue? (y/N) (N): y
libvirt: XML-RPC error : Failed to connect socket to '/var/run/libvirt/virtqemud-sock': No such file or directory
Unhandled exception: System.ArgumentException: Cannot connect to: qemu:///session
   at VmChamp.LibvirtConnection.Create(String) + 0x62
   at CleanCommand.<>c__DisplayClass1_0.<.ctor>b__0() + 0x185
   at System.CommandLine.Invocation.AnonymousCommandHandler.Invoke(InvocationContext) + 0x1e
   at System.CommandLine.Invocation.AnonymousCommandHandler.<InvokeAsync>d__6.MoveNext() + 0x47
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Invocation.InvocationPipeline.<>c__DisplayClass4_0.<<BuildInvocationChain>b__0>d.MoveNext() + 0xe9
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass17_0.<<UseParseErrorReporting>b__0>d.MoveNext() + 0xfd
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass12_0.<<UseHelp>b__0>d.MoveNext() + 0xbd
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass22_0.<<UseVersionOption>b__0>d.MoveNext() + 0x1b9
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass19_0.<<UseTypoCorrections>b__0>d.MoveNext() + 0x13b
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c.<<UseSuggestDirective>b__18_0>d.MoveNext() + 0x15c
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass16_0.<<UseParseDirective>b__0>d.MoveNext() + 0x10d
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c.<<RegisterWithDotnetSuggest>b__5_0>d.MoveNext() + 0x194
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass8_0.<<UseExceptionHandler>b__0>d.MoveNext() + 0xa7

And on run:

λ ~/ sudo vmchamp run                            
Default network bridge: virbr0 missing configuration. Some distributions do not setup a bridge automatically.
👉 The following default network can be created: 
Name: virbr0
IP: 192.168.22.1
Mask: 255.255.255.0

Do you want to create it now and allow VMs to use it? (y/N) (N): y
👉 Creating VM: testvm
💻 Using OS: Debian11
📔 Memory size: 256 MiB
💽 Disk size: 4 GiB
VM: testvm already exists. Do you want to delete and recreate it now?
Continue? (y/N) (N): y
libvirt: XML-RPC error : Failed to connect socket to '/var/run/libvirt/virtqemud-sock': No such file or directory
Unhandled exception: System.ArgumentException: Cannot connect to: qemu:///session
   at VmChamp.LibvirtConnection.Create(String) + 0x62
   at VmChamp.RunCommand.RemoveVm(String, String) + 0x1f
   at VmChamp.RunCommand.<>c__DisplayClass3_0.<<-ctor>b__11>d.MoveNext() + 0x3c1
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Invocation.AnonymousCommandHandler.<InvokeAsync>d__6.MoveNext() + 0x1c2
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Invocation.InvocationPipeline.<>c__DisplayClass4_0.<<BuildInvocationChain>b__0>d.MoveNext() + 0xe9
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass17_0.<<UseParseErrorReporting>b__0>d.MoveNext() + 0xfd
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass12_0.<<UseHelp>b__0>d.MoveNext() + 0xbd
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass22_0.<<UseVersionOption>b__0>d.MoveNext() + 0x1b9
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass19_0.<<UseTypoCorrections>b__0>d.MoveNext() + 0x13b
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c.<<UseSuggestDirective>b__18_0>d.MoveNext() + 0x15c
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass16_0.<<UseParseDirective>b__0>d.MoveNext() + 0x10d
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c.<<RegisterWithDotnetSuggest>b__5_0>d.MoveNext() + 0x194
--- End of stack trace from previous location ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw() + 0x1c
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task) + 0xbe
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task) + 0x44
   at System.CommandLine.Builder.CommandLineBuilderExtensions.<>c__DisplayClass8_0.<<UseExceptionHandler>b__0>d.MoveNext() + 0xa7

[Bug] Image downloads

When I download the Debian 9 or Fedora 36 image I get a 404 error. Also, downloading the Arch image over the official worldwide mirror is very slow (the time estimation said more than an hour).

Add a web interface?

Maybe you can add a simple web interface / dashboard where you can create the virtual machines? 👀

Build Error: Missing GLIBCXX versions in CentOS 7 Docker image

When attempting to run the Dockerfile on a CentOS 7-based Docker image, I encounter an error indicating missing GLIBCXX versions. I have attached the error message as an image.

To work around this issue, I suggest using another "old" Linux distribution that provides the required GLIBCXX versions as the base for your Docker image.

Permission denied (publickey)

i got an error when try to connect to the vm

VmChamp run test1
Default network has no IP address or is down.
Do you want to start it now? (y/N) (N): y
👉 Creating VM: test1
💻 Using OS: Debian11
📔 Memory size: 256 MiB
💽 Disk size: 4 GiB
VM: test1 already exists. Do you want to delete and recreate it now?
Continue? (y/N) (N): y
💀 Removing VM: test1
Using existing image: debian-11-genericcloud-amd64.qcow2
                        
⣽ Waiting for network...
                        
🚀 Your VM is ready.
IP: 192.168.22.204
Connect with 'VmChamp ssh [email protected]'
Warning: Permanently added '192.168.22.204' (ED25519) to the list of known hosts.
[email protected]: Permission denied (publickey).

system setup:
Vmware Workstation 17
debian 12
VmChamp 0.0.7

use custom ssh key instead of copying all public keys

Problem:
SSH will fail if there is no public key with default name.

debug1: Trying private key: /home/max/.ssh/id_rsa
debug1: Trying private key: /home/max/.ssh/id_ecdsa
debug1: Trying private key: /home/max/.ssh/id_ecdsa_sk
debug1: Trying private key: /home/max/.ssh/id_ed25519
debug1: Trying private key: /home/max/.ssh/id_ed25519_sk
debug1: Trying private key: /home/max/.ssh/id_xmss
debug1: Trying private key: /home/max/.ssh/id_dsa

Explaination:
All public ssh keys are copied to the vm on start and VmChamp will try to connect to the vm.
If the user doesn't have one of the default keyfile names, the connection will fail because ssh doesn't know which key to use.
For example my .ssh dir looks like this:

~/r/VmChamp ❯❯❯ tree ~/.ssh
/home/max/.ssh
├── arbeit
│   ├── config
│   ├── id_1
│   ├── id_1.pub
├── config
├── home
│   ├── config
│   ├── id_1
│   ├── id_1.pub
└── known_hosts

There is none of the default names and connection fails.

Solution:
It would be best to create a seperate ssh key somewhere at ~/.config/VmChamp/id_rsa and pass that to the ssh connection to use.