Virt-Lightning is a lightweight virtual machine management tool created to help developers and system administrators to quickly and consistently deploy VMs for testing or development purposes. It is focused on simplicity, speed and ease of use. Virt-lightning provides a user-friendly CLI for creating, managing, and destroying VMs.

In our previous guide, we looked at how we can install virt-lightning on most if not all of the major Linux distributions:

• How To Install virt-lightning on RHEL/Rocky/AlmaLinux/Debian/Ubuntu

virt-lightning usage examples

Before we can proceed any further with the examples, set correct permissions to operate vl

sudo mkdir -p /var/lib/virt-lightning/pool/upstream
sudo chown -R libvirt-qemu:kvm /var/lib/virt-lightning/pool
sudo chown -R $USER /var/lib/virt-lightning/pool/upstream
sudo chmod 775 /var/lib/virt-lightning
sudo chmod 775 /var/lib/virt-lightning/pool /var/lib/virt-lightning/pool/upstream

Check the list of available VM images from virt-lightning official website.

Step 1: Fetch VM image(s)

Before starting the first virtual machine, the VM image should be fetched. This is accomplished using the vl fetch command.

The most recent Linux distribution images are available from the images link. We can fetch some of the images for later use:

• Debian:

# Debian 13
vl fetch debian-13

# Debian 12
vl fetch debian-12

# Debian 11
vl fetch debian-11

• Rocky Linux:

# Rocky Linux 9
vl fetch rockylinux-9

# Rocky Linux 8
vl fetch rockylinux-8

• Ubuntu:

# Ubuntu 24.04
vl fetch ubuntu-24.04

# Ubuntu 22.04
vl fetch ubuntu-22.04

# Ubuntu 20.04
vl fetch ubuntu-20.04

• Amazon Linux:

# Amazon Linux 2023
vl fetch amazon2-20230320.0

# Amazon Linux 2021
vl fetch amazon2-20210126.0

• AlmaLinux:

# AlmaLinux 9
vl fetch almalinux-9

# AlmaLinux 8
vl fetch almalinux-8

• FreeBSD:

# FreeBSD 14
vl fetch freebsd-14.2-zfs
vl fetch freebsd-14.2-ufs

# FreeBSD 13
vl fetch freebsd-13.4-ufs
vl fetch freebsd-13.4-zfs

• Gentoo:

vl fetch gentoo-systemd-latest

• openSUSE:

vl fetch opensuse-leap-15.2

• Fedora 41:

vl fetch fedora-41

• CentOS Stream

# CentOS Stream 9
vl fetch centos-stream-9

Step 2: List available distro images

After fetching VM images of various Linux distributions, you can list them:

vl distro_list

Sample command output:

- distro: almalinux-8
- distro: almalinux-9
- distro: amazon2-20230320.0
- distro: debian-12
- distro: fedora-41
- distro: freebsd-14.2-zfs
- distro: rockylinux-9
- distro: ubuntu-22.04
- distro: ubuntu-24.04

Step 3: Create a VM without virt-lightning.yaml file

Use the vl startcommand to create a new virtual machine. Usage:

vl start [-h] [--ssh] [--name NAME] [--memory MEMORY] [--vcpus VCPUS] [--context CONTEXT] [--show-console ENABLE_CONSOLE] [--disk SIZE] distro

Available start options:

• --ssh Automatically open a SSH connection.
• --name NAME – Name of the VM
• --memory MEMORY – Memory in MB
• --vcpus VCPUS – Number of VCPUS
• --context CONTEXT – Alternative context (default: default)
• --show-console ENABLE_CONSOLE – Suppress console output during VM creation
• --disk SIZE – Size of disk in GB. Multiple disks might be defined

Generate default SSH keys if you don’t have them already.

ssh-keygen -t rsa -b 4096

Generated public key will be injected into instance created through vl when --ssh option is used.

For example, to create Debian 12 virtual machine using default vl settings, the command to run is:

vl start --name debian12 \
--memory 2048 \
--vcpus 2 \
--disk 20 \
--ssh \
debian-12

Wait for the “System is online” message.

...
[  OK  ] Finished cloud-init.servic…it job (metadata service crawler).
[  OK  ] Reached target cloud-confi…t - Cloud-config availability.
[  OK  ] Reached target network-online.target - Network is Online.
[  OK  ] Reached target sysinit.target - System Initialization.
[  OK  ] Started apt-daily.timer - Daily apt download activities.
[  OK  ] Started apt-daily-upgrade.… apt upgrade and clean activities.
[  OK  ] Started dpkg-db-backup.tim Daily dpkg database backup timer.
[  OK  ] Started e2scrub_all.timer��etadata Check for All Filesystems.
[  OK  ] Started fstrim.timer - Discard unused blocks once a week.
[  OK  ] Started man-db.timer - Daily man-db regeneration.
[  OK  ] Started systemd-tmpfiles-c… Cleanup of Temporary Directories.
[  OK  ] Reached target timers.target - Timer Units.
[  OK  ] Listening on cloud-init-ho… - cloud-init hotplug hook socket.
[  OK  ] Listening on dbus.socke-Bus System Message Bus Socket.
[  OK  ] Listening on uuidd.socket��m - UUID daemon activation socket.
[  OK  ] Reached target sockets.target - Socket Units.
[  OK  ] Reached target basic.target - Basic System.
         Starting cloud-config.serv…tings specified in cloud-config...
         Starting dbus.service - D-Bus System Message Bus...
         Starting e2scrub_reap.serv…e ext4 Metadata Check Snapshots...
         Starting ssh.service - OpenBSD Secure Shell server...
         Starting systemd-logind.se…ice - User Login Management...
         Starting systemd-user-sess…vice - Permit User Sessions...
[  OK  ] Started dbus.service - D-Bus System Message Bus.
[  OK  ] Finished systemd-user-sess…ervice - Permit User Sessions.
[  OK  ] Started [email protected] - Getty on tty1.
[  OK  ] Started serial-getty@ttyS0…rvice - Serial Getty on ttyS0.
[  OK  ] Reached target getty.target - Login Prompts.
[  OK  ] Started systemd-logind.service - User Login Management.
[  OK  ] Started unattended-upgrade…0m - Unattended Upgrades Shutdown.
💻 debian12 found at 192.168.123.5!

**** System is online ****
To connect use:
  vl console debian12 (virsh console)  vl ssh debian12

Step 4: Initiate ssh connection to VM

If you generated SSH keys and passed --ssh while creating a virtual machine, connect to the instance using

vl ssh <vnmane>

In example 3, we created a virtual machine called “debian12“, an ssh connection can be initiated by executing the command:

vl ssh debian12

You can also use IP address shown in the creation output as root or your host logged in user.

# SSH as root user
ssh [email protected]

# OR ssh as default standard user
ssh [email protected]

The SSH configuration for the instance can be dumped using the commands vl ssh_config.

$ vl ssh_config
Host debian12
     Hostname 192.168.123.5
     User devops
     IdentityFile None

After connecting confirm OS is correct.

$ cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
...

Step 5: Connect to VM using serial console

You can connect to virtual machine serial console using

vl console debian12

The default password for root user is root

Connected to domain 'debian12'
Escape character is ^] (Ctrl + ])

debian12 login: root
Password: root

Step 6: Create VM using virt-lightning.yaml file

Let’s consider an example to create AlmaLinux VM from a configuration file. Begin by creating a project directory.

mkdir -p ~/vl/almalinux
cd ~/vl/almalinux

Create a new virt-lightning.yaml in the directory

vim virt-lightning.yaml

A VM can be tuned at two different places with the following keys:

• distro: the name of the base distro image to use, it’s the only mandatory parameter.
• name: the VM name
• memory: the amount of memory to dedicate to the VM
• vcpus: the number of vcpu to dedicate to the VM
• root_password: the root password in clear text
• ssh_key_file: the path of the public key for connecting to the VM
• groups: this list of groups will be used if you generate an Ansible inventory.
• disks: a list of disks to create and attach to the VM. The first one is used as the root disk. Default to [{"size": 15}]
• size the size of the disk in GB. Default is 1.
• networks: a list of network to attach to the VM. The default is: one virtio interface attached to virt-lightning network.
• network: the name of the libvirt network. Default is the key network_name from the configuration (virt-lightning by default). The key cannot be used with bridge. A host variable is added to in the Ansible inventory, with the network name with suffix “ipv4″ as key and the IPv4 as value, e.g. “privateipv4″.
• ipv4: a static IPv4. Default is a dynamic IPv4 address.
• nic_model: the libvirt driver to use. Default is virtio
• mac: an optional static MAC address, e.g: ’52:54:00:71:b1:b6′
• bridge: optional, the name of a bridge to connect to. This key replace the network key.
• virtualport_type: The type of the virtualport, currently, this can be used with bridge. Add customize contents to the configuration file to what works for your lab setup.

- name: alma9
  distro: almalinux-9
  memory: 4096
  vcpus: 2
  root_disk_size: 30
  root_password: 'RootPassword'
  groups: ['all_alma']
  ssh_key_file: ~/.ssh/id_rsa.pub
  networks:
    - network: virt-lightning
  bootcmd:
    - dnf -y update
    - dnf -y install vim wget bash-completion git python3 python3-pip

Start the virtual machine using vl up command. if the distribution image is not available locally, it will be downloaded.

$ vl up
⚡ alma9
⌛ ok Waiting...
🛃 alma9 QEMU agent found
💻 alma9 found at 192.168.123.6!
👍 You are all set

Access VM terminal using vl console or ssh

ssh [email protected]

Generate ansible inventory

To dump an inventory file for ansible use:

vl ansible_inventory > inventory

You can check the contents and test by doing ping if you have ansible installed.

ansible all -m ping -i inventory

Output example:

alma9 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

Using OpenvSwitch bridge in VM

This example shows how to connect your VM to Open vSwitch bridge.

- name: alma9
  distro: almalinux-9
  memory: 4096
  vcpus: 2
  root_disk_size: 30
  root_password: 'RootPassword'
  groups: ['all_alma', 'webservers']
  ssh_key_file: ~/.ssh/id_rsa.pub
  networks:
    - bridge: ovs-bridge-name
      virtualport_type: openvswitch
      ipv4: 192.168.1.12
  bootcmd:
    - dnf -y update
    - dnf -y install vim wget bash-completion git python3 python3-pip

Stop / delete VM

To delete the virtual machine pass the stop command option:

vl stop <vm-name>