path: root/README

QEMU-TUI
========
A terminal UI for managing QEMU virtual machines.
Zero external dependencies -- uses only Python's built-in curses module.


REQUIREMENTS
------------
  Python 3.7 or later
  qemu-system-* binaries on your PATH
  qemu-img  (for disk management and snapshots)
  /dev/kvm  (optional, auto-detected for hardware acceleration)
  OVMF firmware  (optional, auto-detected for UEFI boot)


INSTALLATION
------------
No pip install needed. Just make the script executable:

  chmod +x qemu-tui.py
  ./qemu-tui.py

Or copy it somewhere on your PATH:

  cp qemu-tui.py ~/.local/bin/qemu-tui
  chmod +x ~/.local/bin/qemu-tui
  qemu-tui


LAYOUT
------
The screen is divided into two panes separated by a vertical line.

Left sidebar
  Lists all VMs with a live status icon and state label.
  Key hints are shown at the bottom of the sidebar.

  Status icons:
    >  running
    .  stopped
    ~  paused
    !  error

Right panel
  Shows details for the currently selected VM.
  A header line shows the VM name, status, PID, and uptime.
  Below it are six tabs selectable with the Tab key:

    Info       VM configuration and runtime info
    Command    The exact qemu-system-* command line
    Log        Live stdout/stderr from the QEMU process
    Disk       Disk image details and management hint
    Snapshots  List of internal qcow2 snapshots
    Monitor    QEMU monitor socket status and quick reference

Status bar
  The bottom row shows the result of the last action in green
  (success) or red (error).


KEYBINDINGS
-----------
Navigation

  Up / Down      Move between VMs in the sidebar
  Tab            Cycle through tabs
  PgUp / PgDn   Scroll log or console output
  q              Quit

VM lifecycle

  n              New VM
  e              Edit VM config (VM must be stopped)
  Del            Delete VM (VM must be stopped)
  s              Start VM
  k              Stop VM via SIGTERM (requests graceful OS shutdown)
  F              Force kill VM via SIGKILL (immediate termination)
  g              Graceful ACPI power-off via monitor socket
  z              Pause / resume toggle via monitor socket

Features

  d              Open disk management menu
  p              Open snapshot manager
  f              Open port forwarding editor
  ~              Open interactive QEMU monitor console
  c              Clone VM
  i              Import existing disk image as new VM
  x              Eject CD-ROM / ISO


TABS
----
Info
  Displays all VM settings, current PID, uptime, UEFI firmware path
  (or a warning if OVMF is not found), and port forwarding rules.

Command
  Shows the full qemu-system-* command that will be used to start the
  VM, wrapped across multiple lines for readability. Useful for
  debugging or copying the command to run manually.

Log
  Streams live stdout and stderr output from the QEMU process.
  Scroll with PgUp and PgDn. Output is buffered up to 500 lines.

Disk
  Shows the disk image path, format, virtual size, actual used space
  with a percentage, snapshot count, and backing file if any.
  If the disk is locked by a running VM, a friendly note is shown
  instead of a raw error.

  Press 'd' to open the disk management menu:
    Create   -- create a new qcow2 image (prompts for path and size)
    Resize   -- expand the disk to a new size (VM must be stopped)
    Convert  -- convert to qcow2, raw, vmdk, or vdi (VM must be stopped)
    Delete   -- permanently delete the disk file (VM must be stopped)

Snapshots
  Lists all internal qcow2 snapshots with ID, name, date, and VM
  clock time. If the disk is locked, a note is shown instead.

  Press 'p' to open the snapshot manager:
    c        Create a snapshot (allowed while VM is running)
    r        Restore a snapshot (VM must be stopped)
    x / Del  Delete a snapshot (VM must be stopped)
    R        Refresh the list
    Esc      Close

  Snapshot names cannot contain spaces.

Monitor
  When the VM is running, shows the path of the QEMU monitor Unix
  socket and a quick-reference of useful monitor commands.

  Press '~' to open the interactive monitor console:
    Left pane    Quick-command list. Tab to focus, Up/Down to navigate,
                 Enter to run the selected command.
    Right pane   Scrollable output area. Cleared on each new command.
                 Scroll with PgUp / PgDn.
    Bottom bar   Free-form command input. Tab to focus, Enter to send.
    Esc          Close the console.

  Useful monitor commands:
    info status        Current VM state
    info network       Network interfaces
    info block         Block devices and disk images
    info cpus          CPU information
    info mem           Memory map
    info pci           PCI device list
    info snapshots     Snapshot list (live)
    system_powerdown   Send ACPI power button signal
    system_reset       Hard reset (like pressing the reset button)
    stop               Pause execution
    cont               Resume execution


VM CONFIGURATION
----------------
Fields available when creating or editing a VM:

  Name
    Identifier for the VM. Also used as the default disk filename:
    ~/.cache/qemu-tui/<name>.qcow2

  Memory (MiB)
    RAM allocated to the VM. e.g. 1024, 2048, 4096.

  CPUs
    Number of virtual CPU cores.

  Disk image
    Path to the qcow2 (or other format) disk image.
    Press Enter or B on this field to open the file browser.
    Default path is set automatically from the VM name.
    If the file does not exist when you save, you are offered
    the option to create it.

  CD-ROM / ISO
    Path to an ISO or image file to attach as a CD-ROM drive.
    Press Enter or B to browse. Press 'x' from the main screen
    to eject.

  Architecture
    One of: x86_64, aarch64, arm, riscv64, mips.
    The matching qemu-system-<arch> binary is used.

  Network
    user  -- NAT networking via SLIRP. Supports port forwarding.
    none  -- No network interface.

  Display
    none  -- Headless. No graphical output. Use SSH to access.
    sdl   -- Opens an SDL window on the local display.
    vnc   -- Listens on VNC port 5900.

  UEFI / OVMF
    Enables UEFI firmware. The manager searches common paths for
    an OVMF firmware file automatically. The detected path is shown
    inline when the field is selected. If no firmware is found,
    an error is shown in the Info tab.

  Extra args
    Additional raw arguments appended verbatim to the qemu-system-*
    command line. Parsed with shlex so quoting is respected.


PORT FORWARDING
---------------
Only available when network is set to 'user'.

Press 'f' to open the editor. Press 'a' to add a rule.
A preset picker appears first:

  SSH      tcp  host 2222 -> guest 22
  HTTP     tcp  host 8080 -> guest 80
  HTTPS    tcp  host 8443 -> guest 443
  RDP      tcp  host 3389 -> guest 3389
  VNC      tcp  host 5900 -> guest 5900
  Custom        enter all fields manually

After choosing a preset you can override all values:
  Protocol         tcp or udp
  Host port        port on the physical machine
  Guest port       port inside the VM
  Host bind addr   leave blank to listen on all interfaces
  Description      optional label shown in the rule list

Rules are saved with the VM config and injected as hostfwd= entries
in the -netdev user argument. Changes take effect on the next start.

  d / Del  Delete the selected rule
  Esc      Save and close


CLONE VM
--------
Press 'c' (VM must be stopped). Enter a new name, then choose a
disk copy mode:

  Linked clone
    Creates a new qcow2 image with the original disk as a backing
    file. Very small and instant. Writes from the clone go to the
    new file; the original is not modified. Requires the original
    disk to remain accessible.

  Full copy
    Runs qemu-img convert to produce a completely independent copy.
    Takes time proportional to the virtual disk size and uses the
    same amount of storage. Safe to use without the original.

  No copy
    Clones only the config. Both VMs point at the same disk file.
    Running both simultaneously will corrupt the disk.

Port forwarding rules are not copied to avoid host port conflicts.
After cloning the new VM is selected automatically.


IMPORT VM
---------
Press 'i' to import an existing disk image as a new VM.

A file browser opens, filtered to common disk image extensions:
  .qcow2  .img  .raw  .vmdk  .vdi  .iso

After selecting a file:
  1. qemu-img info is run to detect the format and virtual size.
  2. A brief summary is shown.
  3. You are prompted for a VM name (defaults to the filename stem).
  4. A VM config is created pointing at the selected file.
     If the format is not qcow2 the correct -drive format= flag
     is set via extra args.

After importing the new VM is selected automatically.


UEFI / OVMF
-----------
Enable the 'UEFI / OVMF' toggle in the VM form.

The manager searches these paths in order (x86_64):
  /usr/share/ovmf/OVMF.fd
  /usr/share/ovmf/x64/OVMF.fd
  /usr/share/OVMF/OVMF_CODE.fd
  /usr/share/edk2/ovmf/OVMF_CODE.fd
  /usr/share/edk2-ovmf/OVMF_CODE.fd
  /usr/lib/ovmf/OVMF.fd
  /usr/share/qemu/ovmf-x86_64.bin

For aarch64:
  /usr/share/AAVMF/AAVMF_CODE.fd
  /usr/share/qemu-efi-aarch64/QEMU_EFI.fd

Install on common distributions:

  Arch Linux / Void Linux
    sudo pacman -S edk2-ovmf
    sudo xbps-install edk2-ovmf

  Debian / Ubuntu
    sudo apt install ovmf

  Fedora
    sudo dnf install edk2-ovmf


KVM ACCELERATION
----------------
Detected automatically. If /dev/kvm exists, the flags
  -enable-kvm -cpu host
are added to the command, giving near-native CPU performance.

To enable KVM on Linux:
  sudo usermod -aG kvm $USER
  (log out and back in for the group change to take effect)

If KVM is not available QEMU falls back to software emulation,
which is significantly slower.


FILE LOCATIONS
--------------
  ~/.config/qemu-tui/vms.json
    VM configurations. Edited by the manager; do not modify
    while the manager is running.

  ~/.cache/qemu-tui/runtime.json
    Runtime state: PID, start time, status, and monitor socket
    path for each running or paused VM. Written on every start
    and stop. Read on startup to re-attach to surviving VMs.

  ~/.cache/qemu-tui/<name>.qcow2
    Default location for newly created disk images.

  ~/.cache/qemu-tui/monitors/<name>.sock
    QEMU monitor Unix domain socket for each running VM.


SESSION PERSISTENCE
-------------------
VMs started by qemu-tui are ordinary background processes. Closing
the manager does not stop them.

When qemu-tui starts it reads runtime.json and for each entry sends
signal 0 (kill -0) to the saved PID to check whether the process is
still alive. If it is, the VM is shown as 'running' with its original
start time and monitor socket path restored.

All actions work on re-attached VMs:
  k   Stop (SIGTERM)
  F   Force kill (SIGKILL)
  g   ACPI power-off via monitor
  z   Pause / resume via monitor
  ~   Open monitor console