BashVM — Documentation

Table of Contents

Overview

BashVM is an interactive, text-menu wrapper around the virsh (libvirt) command-line tools. Instead of typing long virsh, virt-clone, ufw, and iptables invocations, you pick a numbered item from a menu and answer a the prompts.

• Main menu — top level, 11 functional areas plus q to exit.
• Sub-menus — one per functional area (VMs, storage, networks, snapshots, …).
• Prompts — short questions that collect names, sizes, IPs, MAC addresses, etc.

Running the Script

On a fresh host, run the 12.1 Installer first:

Once the installer finishes, run the main script:

On launch you are shown the main menu:

Type the number (or letter) of the area you want and press Enter. The helper scripts (e.g. the 1.1 Create a new / existing VM option) are expected to live in the same working directory as the main script or somewhere on your PATH.

Main Menu Reference

1. Virtual Machines

Example — start a VM and confirm

Example — clone a VM

1.1 Create a new / existing VM (menu 1 → 8)

Interactive VM creation from an installation ISO, or import of an existing disk. Builds a complete libvirt XML definition with Q35 machine type, host-passthrough CPU, virtio disk, and a VNC listener on 0.0.0.0, then defines the domain.

Prompts

What it does

• Downloads the selected ISO into the pool with resumable wget -c (saved as .part then renamed on completion).
• Generates a random UUID via /proc/sys/kernel/random/uuid.
• Writes XML to /etc/libvirt/qemu/<name>.xml and runs virsh define.
• VNC is pre-configured with autoport='yes' on 0.0.0.0 and no password.

1.2 Create a new VM (Automated) (menu 1 → 10)

Fully automated VM deployment using a cloud image and cloud-init. In one pass it downloads the base image, writes a cloud-init user-data file, runs virt-install, waits for the VM's MAC, reserves a DHCP IP, and installs port-forwarding rules into the qemu hook.

Prompts

What it does

1. Writes bashvm-cloudinit.yaml with the chosen user, password, SSH password auth, qemu-guest-agent package, and a runcmd: shutdown -P 0 so the VM powers off after first boot (ready for the hook).
2. Moves the cloud-init file to /var/lib/libvirt/images.
3. Downloads the cloud image to /var/lib/libvirt/images if not already present.
4. Ensures the default network is active and autostarted.
5. Runs virt-install --disk=size=…,backing_store=… --cloud-init user-data=… --network bridge=virbr0 --noautoconsole.
6. Waits for a virtio MAC to appear, then generates a unique IPv4 in 192.168.122.x (excluding .0, .1, .255) and a port range starting at 49152, stored in bashvm.db.
7. Adds a DHCP reservation to the default network.
8. Appends iptables DNAT rules between #vm_name# and ###vm_name### markers in /etc/libvirt/hooks/qemu (SSH plus the port range, TCP and UDP).
9. Restarts libvirtd if it was the only running VM (so the hook loads cleanly).
10. Prints the assigned IPv4, SSH port, port range, username, and password.

1.3 Change resources of a VM (menu 1 → 12)

A second-level menu for adjusting an existing VM's vCPU count, memory, disk size, and network attachments. Most operations require the VM to be shut off.

1.4 Delete a VM (menu 1 → 13)

Deletes a VM and everything attached to it: DHCP reservation, CD-ROM attachment, all storage volumes, snapshot metadata, SQLite port-forwarding record, and the iptables block in the qemu hook.

Prompts

• VM name — must be shut off; the script aborts if state is running.
• Confirmation — you must type DELETE (all caps). Anything else cancels.

What it does

1. Refuses to run if the VM is running.
2. Removes the DHCP reservation by matching the VM's MAC and IP in virsh net-dumpxml.
3. Detaches any CD-ROM device (looks for cdrom followed by source file in the XML).
4. Runs virsh undefine <vm> --remove-all-storage --snapshots-metadata — this deletes the qcow2 disks.
5. Removes the block between #<vm># and ###<vm>### in /etc/libvirt/hooks/qemu.
6. Deletes the VM's row from the network's table in bashvm.db if present.

2. Storage Pools

Example — create a 20 GB volume in the default pool

Example — download an ISO

3. Networks

Example — create a NAT network

Example — reserve an IP for a VM

3.1 Delete a network (menu 3 → 8)

Deletes a libvirt network and, optionally, its associated table in bashvm.db.

Prompts

• Network name to delete.
• Delete the SQLite table and data? (y/n) — accepts y, ye, or yes (case-insensitive).

What it does

1. If confirmed, drops the table <network>_table from bashvm.db (only if it exists).
2. Runs virsh net-destroy <network> then virsh net-undefine <network>.

3.2 Add DHCPv6 to a NAT network (menu 3 → 11)

Adds DHCPv6 service to an existing NAT network. The script refuses to run on non-NAT networks.

Prompts

What it does

1. Aborts if virsh net-dumpxml does not contain <forward mode='nat'>.
2. Aborts if the network XML already contains ipv6 — you must remove the existing DHCPv6 config first.
3. Adds net.ipv6.conf.<iface>.accept_ra = 2 to /etc/sysctl.conf if not present, runs sysctl -p, and creates a systemd unit bashvm-ipv6-accept-ra.service to re-apply on boot.
4. Strips the closing </ip> and </network> tags from the network XML with sed and appends a new IPv6 <ip> block with a <dhcp> range.
5. Stops, redefines, starts, and autostarts the network.
6. Writes /etc/ndppd.conf with a proxy rule for the configured prefix and enables/restarts ndppd.

3.3 Create a routed IPv6 network (menu 3 → 7)

Creates a routed (non-NAT, no DHCP) IPv6 network. Useful for static IPv6 addressing on guests where you control the upstream routing.

Prompts

What it does

1. Aborts if a network with that name already exists.
2. Adds net.ipv6.conf.<iface>.accept_ra = 2 to /etc/sysctl.conf if not already present, applies it, and creates the same bashvm-ipv6-accept-ra.service persistence unit.
3. Generates a network XML with <forward mode='route'/> and a random bridge name in the form virbrNNN (three random digits).
4. Defines, starts, and autostarts the network.
5. Writes /etc/ndppd.conf with a proxy rule for the chosen prefix and enables/restarts ndppd.

4. Snapshots

Example

5. Edit Properties

6. Firewall Settings

Example — open a port range for a web stack

7. Port Forwarding

Port forwarding for VMs behind a NAT network is implemented with the libvirt qemu hook at /etc/libvirt/hooks/qemu. When a VM starts, the hook adds iptables DNAT rules; when it stops, they are removed. Forwarding records are also stored in the SQLite database bashvm.db.

Typical port-forwarding workflow

1. 1 — list DHCP leases to confirm the guest's IP address.
2. 2 — add the forwarding rule (host port → guest IP:guest port).
3. Restart the VM so the qemu hook runs.
4. s — verify the DNAT rule appears in the NAT table.
5. 3 — remove the rule when it is no longer needed.

7.1 Add port forwarding to a VM (menu 7 → 2)

Adds a new port-forwarding rule set for a VM behind a NAT network. The first port in the range is reserved for SSH (forwarded to guest port 22); the remaining ports are forwarded 1:1 to the same guest port numbers.

Prompts

What it does

1. Resolves the VM's network and bridge name from virsh dumpxml / virsh net-dumpxml (defaults to default / virbr0).
2. Validates that the IP, start port, and end port are well-formed and ordered.
3. Creates bashvm.db and the network's table if missing.
4. Rejects the request if the VM name or IP already exists in the table, or if any of the three ports is not strictly greater than the highest port already recorded.
5. Inserts (vm_name, ipv4, ssh_port, start_port, end_port) into the table.
6. Appends a block to /etc/libvirt/hooks/qemu between #<vm># and ###<vm>### markers, containing iptables delete rules for the stopped/reconnect branch and insert rules for the start/reconnect branch. Both TCP and UDP are covered for SSH and every port in the range.
7. Makes the hook executable and restarts libvirtd if it was the only running VM.
8. Prints the SSH port and the forwarded port range.

7.2 Remove port forwarding from a VM (menu 7 → 3)

Removes a VM's port-forwarding rule set from both bashvm.db and /etc/libvirt/hooks/qemu.

Prompts

• VM name — must be non-empty.

What it does

1. Resolves the network and bridge (defaults default / virbr0).
2. Aborts if bashvm.db does not exist.
3. Aborts if the VM has no row in the network's table.
4. Aborts if the hook file contains no reference to the VM.
5. Deletes the row from the table.
6. Removes the block between #<vm># and ###<vm>### from the hook.

7.3 Show port forwarding rules (menu 7 → s)

Dumps every table in bashvm.db with column headers. Used by the port-forwarding menu to give a human-readable view of all reserved ports.

What it does

1. Lists all tables from sqlite_master.
2. For each table, prints the table name and then SELECT * with -column -header formatting.

8. VNC / Console Access

Example — check ports

Connecting

9. System Monitor

Selecting 9 immediately launches btop — a full-screen terminal resource monitor showing CPU, memory, disks, network, and processes for the host.

10. VM Monitor

Example — per-vCPU usage

10.1 All usage metrics of a VM (menu 10 → 5)

Combined per-VM metrics dashboard. Equivalent to running options 1–4 of the VM Monitor menu in sequence for a single VM.

Prompts

• VM name — validated with virsh dominfo; invalid names exit silently.

What it reports

1. Per-vCPU utilisation — loops from vCPU 0 to count-1, sleeping 1 s between domstats reads and normalising by 10⁹ ns.
2. Memory usage — balloon.rss / (balloon.rss + balloon.available) × 100.
3. Disk usage — fs.0.used / fs.0.total × 100 from virsh guestinfo.
4. Network throughput — ifstat -i <vNIC> 1 1.

11. SQLite Editor

The SQLite Editor provides menu-driven access to the per-network tables in bashvm.db (typically holding VM name, IPv4 address, SSH port, and a port range used for port-forwarding bookkeeping). The main script's option 11 simply launches this editor.

Startup prompts

• Network name — validated against virsh net-list --all. Repeats until a real network is entered. Defaults to default.

The chosen network's table is created if it does not already exist.

Editor menu

12. Installation & Uninstallation

Two standalone scripts handle first-time setup and complete removal of the packages used by BashVM. They are not invoked from the main menu; run them directly from the shell before the first bashvm.sh launch (installer) or when decommissioning the host (uninstaller).

12.1 Installer (run first)

A fully automated setup script for Debian/Ubuntu hosts. Installs every package BashVM needs, initializes the default storage pool and network, and configures VNC over TLS. It does not prompt for input.

Running

Packages installed

• qemu-kvm, libvirt-daemon-system, libvirt-clients, qemu-utils
• bridge-utils, net-tools, dnsmasq (only if not already present)
• virt-manager, cloud-init
• ufw, btop, bc, ifstat, ndppd, sqlite3

What it does

1. Installs every package with apt install -y and exits on the first failure.
2. Starts and enables libvirtd if it is not already active.
3. Defines, starts, and autostarts the default storage pool at /var/lib/libvirt/images if missing or inactive.
4. Defines, starts, and autostarts the default network if missing or inactive.
5. Generates a TLS CA and server certificate in /etc/pki/libvirt-vnc:
   • ca-cert.pem, ca-key.pem (CA)
   • server-cert.pem, server-key.pem (server, with all detected IPv4/IPv6 addresses in the SAN)
   • 10-year validity, private keys chmod 600
6. Backs up /etc/libvirt/qemu.conf to a timestamped .bak file, then sets:
   • vnc_tls = 1
   • vnc_tls_x509_cert_dir = "/etc/pki/libvirt-vnc"
7. Restarts libvirtd if no VMs are currently running. If VMs are running, it prints the restart command and a warning instead.
8. Prints the final hint: "If no errors above then you can run bashvm with bash bashvm.sh".

12.2 Uninstaller (destructive)

Removes every package that the installer would have installed. It does not touch user data (VM disks, bashvm.db, network XML, or the qemu hook) — those are left for you to remove manually.

Running

Prompts

• The script prints a warning that it will remove BashVM's packages.
• You must type remove (case-insensitive) to proceed, or cancel to exit. Any other input re-prompts.

What it does

1. Removes each package with apt remove -y and exits on the first failure: qemu-kvm, libvirt-daemon-system, libvirt-clients, bridge-utils, qemu-utils, virt-manager, cloud-init, net-tools, ufw, btop, bc, ifstat, ndppd, sqlite3.
2. Runs apt autoremove -y to clean up now-orphaned dependencies.
3. Prints a completion message.

Common Workflows

First-time host setup

1. 12.1 — run the installer to install packages and configure VNC TLS.
2. Confirm systemctl status libvirtd is active.
3. 1 → 1 — list VMs (should be empty).
4. 2 → s — confirm the default pool is active.
5. 3 → s — confirm the default network is active.

Create a new VM from scratch (ISO install)

1. 2 → 9 — download the installation ISO into the default pool (or let 1.1 Create a new / existing VM do it).
2. 2 → 6 — create a qcow2 volume for the VM's disk.
3. 1 → 8 — create the VM definition interactively.
4. 1 → 11 — console in to run the installer, or use VNC (menu 8).
5. 1 → 6 — enable autostart so it comes back after a host reboot.

Deploy a cloud-image VM in one step

1. 1 → 10 — 1.2 Create a new VM (Automated) handles download, cloud-init, DHCP reservation, and port forwarding.
2. Note the printed IPv4, SSH port, username, and password.
3. 1 → 11 — console in to verify the guest is healthy.
4. 7 → s — confirm the forwarding rules landed in the hook.

Duplicate an existing VM

1. 1 → 4 — gracefully shut down the source VM (important: virt-clone needs a consistent disk).
2. 1 → 14 — clone to a new name (or 1 → 15 for several copies).
3. 1 → 2 — start the clone.
4. 8 → 1 — add a VNC password if you need graphical access.

Expose a guest web server to the LAN

1. 3 → 4 — make sure the VM sits on a NAT network with a known subnet.
2. 3 → 9 — reserve a fixed IP for the VM's MAC address.
3. 7 → 1 — confirm the guest picked up the reserved lease.
4. 7 → 2 — forward host port 8080 to <guest-ip>:80.
5. 6 → 4 — allow port 8080 through ufw.
6. 7 → s — verify the DNAT rule is present.

Roll back a risky change

1. 4 → 1 — snapshot the VM before the change.
2. Apply the change.
3. 4 → 3 — revert to the snapshot if something breaks.
4. 4 → 2 — clean up the snapshot when you are happy.

Add DHCPv6 to an existing NAT network

1. Back up the network XML: cp /etc/libvirt/qemu/networks/default.xml ~/default.xml.bak.
2. 3 → 11 — run 3.2 Add DHCPv6 to a NAT network and supply the interface, gateway, prefix, and range.
3. Verify with virsh net-dumpxml default | grep ipv6.
4. Restart guest VMs so they pick up a DHCPv6 address.

Delete a VM completely

1. 1 → 4 — graceful shutdown (or 1 → 5 to force).
2. 1 → 13 — 1.4 Delete a VM; type DELETE to confirm.
3. Check the network no longer has a reservation: 3 → 1.
4. Check the hook no longer has a block: 7 → 4 and search for the VM name.

Decommission a host

1. Back up bashvm.db, network XML, and the qemu hook.
2. 12.2 — run the uninstaller; type remove to confirm.
3. Manually remove user data left behind (VM disks, /etc/pki/libvirt-vnc, etc.).

Troubleshooting & Notes

General notes

• No confirmation prompts on most destructive actions. Options such as 1 → 5 (force shutdown), 2 → 5 (delete pool), 3 → 8 (delete network), 4 → 2 (delete snapshot), and 6 → 8 (ufw reset) act immediately. Only 1 → 13 (1.4 Delete a VM) requires typing DELETE, and 12.2 Uninstaller requires typing remove.
• Default values. Empty input at a [default] prompt means default.
• Restart expectations. DHCP reservation changes, network edits, VNC/device XML changes, and port-forwarding rules usually require a VM stop and start rather than a reboot or hot-plug.
• Database file. bashvm.db is created relative to the current working directory. Run all scripts from the same directory, or the port-forwarding scripts will see an empty database.
• Logging. The scripts do not log to a file; errors come from the underlying virsh/ufw/iptables/sqlite3 output as it happens. Scroll back in your terminal to review it.
• Editor. Menu 5 and 7 → 4 invoke an editor via $EDITOR or explicit nano/vim. Set EDITOR if you prefer something else.
• Systemd units. bashvm-ipv6-accept-ra.service is created by the DHCPv6 and routed-IPv6 options to re-apply accept_ra = 2 on boot. Remove it with systemctl disable --now bashvm-ipv6-accept-ra.service if you no longer use IPv6.
• Root required. All scripts that touch libvirt, iptables, ufw, or systemd unit files must be run as root.