Introduction and quick-start

Nvirt is a tool for repeatably provisioning libvirt virtual machines. Define customisations for your OS, and easily set up features like port forwarding and shared volumes. It's similar to Vagrant, but for libvirt user session VMs, and you can base your VMs on cloud-builder templates or any bootable image.

GitLab: nvirt-cli/nvirt

Behind the scenes, nvirt is a wrapper around the tools provided by the libguestfs project (virt-builder and virt-customize) and the virt-manager project (virt-install), with a few extra conveniences around the edges.

Commands

Commands for controlling the VM's lifecycle:

• nvirt init - Create a new virtfile from a template.
• nvirt up - Start the machine defined in the virtfile.
• nvirt halt - Shut down the machine.
• nvirt destroy - Delete the VM and its backing disk(s).
• nvirt rebuild - Delete the VM and recreate it (shortcut for 'destroy' then 'up').

Commands for interacting with the VM:

• nvirt ssh - Open an SSH session in the machine.
• nvirt sshinfo - Get information about the SSH connection.
• nvirt rsync - Copy files to or from the machine.

Quick-start: Using a virt-builder image template

This example builds a new VM based on the virt-builder fedora-42 image, installs an nginx web server, and sets up port-forwarding for it and a bi-directional shared folder mounted at /nvirt in the guest.

• Copy the following text into a file called virtfile in a new directory
• Run nvirt up from inside that directory.
• Once it's booted, you can browse to http://localhost:8080/ to interact with the nginx web server running inside.

Example virtfile: Based on virt-builder Fedora 42, with an nginx web server

virtfile.yml

default:
  source: virt-builder
  image: fedora-42  # see `virt-builder --list` for available templates

  # all lines in this section map directly to options for the virt-install command. 
  # see its manual for a full list.
  machine:
  - osinfo: linux2024
  - vcpu: 2
  - memory: 3072

  # when the source is virt-builder (as above), all lines in this section map
  # directly to options for the virt-builder command - see its manual for a full list.
  customize:
  - size: 40G
  - install: openssh-server,nginx

  ports:
  - 127.0.0.1:8080:80  # forward port 8080 on the host to port 80 in the guest

  volumes:
  - .:/nvirt:rw

Quick-start: Using a distribution image with virt-customize

Many distributions provide pre-built bootable images that can be used directly. If you have a URL for an image that you want to use for your VM, you can specify the url source.

• Copy the following text into a file called virtfile in a new directory
• Run nvirt up from inside that directory.
• Once it's booted, you can browse to http://localhost:8081/ to interact with the nginx web server running inside.

Example virtfile: Based on Ubuntu 24.04 upstream image, with an nginx web server

virtfile.yml

default:
  source: url
  image: https://cloud-images.ubuntu.com/releases/resolute/release/ubuntu-26.04-server-cloudimg-amd64.img
  resize: 20G

  # all lines in this section map directly to options for the virt-install command.
  # see its manual for a full list.
  machine:
  - osinfo: linux2024
  - vcpu: 2
  - memory: 3072

  # for the 'url' source, all lines in the 'customize' section map directly to
  # options for the virt-customize command. see its manual for a full list.
  customize:
  - run-command: growpart /dev/sda 1 && resize2fs /dev/sda1  # resize root partition (1) to fill disk
  - run-command: ssh-keygen -A                               # generate ssh host keys
  - install: nginx                                           # for demonstration

  ports:
  - 127.0.0.1:8081:80  # forward port 8081 on the host to port 80 in the guest

Note

When specifying a disk size with the 'url' source and the 'resize' option, only the virtual disk itself is resized. You may need to specify extra commands to expand the partitions and filesystems it contains.

The growpart tool is used in this example to expand the root partition (partition 1 in this case).