diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 355 |
1 files changed, 355 insertions, 0 deletions
@@ -0,0 +1,355 @@ +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 |