initial commit
This commit is contained in:
@@ -0,0 +1,21 @@
|
|||||||
|
The MIT License (MIT)
|
||||||
|
|
||||||
|
Copyright (c) 2026 Emmett1
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is furnished
|
||||||
|
to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in
|
||||||
|
all copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
||||||
|
THE SOFTWARE.
|
||||||
@@ -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
|
||||||
+591
@@ -0,0 +1,591 @@
|
|||||||
|
.TH QEMU\-TUI 1 "March 2026" "qemu-tui" "User Commands"
|
||||||
|
.SH NAME
|
||||||
|
qemu\-tui \- terminal UI for managing QEMU virtual machines
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.B qemu\-tui
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.B qemu\-tui
|
||||||
|
is an interactive terminal user interface for creating, configuring,
|
||||||
|
and controlling QEMU virtual machines.
|
||||||
|
It requires no external Python packages \(em only the standard library
|
||||||
|
.B curses
|
||||||
|
module.
|
||||||
|
.PP
|
||||||
|
The interface is divided into a left sidebar listing all VMs with live
|
||||||
|
status and a right panel showing details for the selected VM across six
|
||||||
|
tabs: Info, Command, Log, Disk, Snapshots, and Monitor.
|
||||||
|
A status bar at the bottom reports the result of each action.
|
||||||
|
.SH REQUIREMENTS
|
||||||
|
.TP
|
||||||
|
.B Python 3.7+
|
||||||
|
.TP
|
||||||
|
.BR qemu\-system\-* (1)
|
||||||
|
on PATH
|
||||||
|
.TP
|
||||||
|
.BR qemu\-img (1)
|
||||||
|
for disk management and snapshots
|
||||||
|
.TP
|
||||||
|
.I /dev/kvm
|
||||||
|
for hardware acceleration (optional, auto-detected)
|
||||||
|
.TP
|
||||||
|
.B OVMF firmware
|
||||||
|
for UEFI boot (optional, auto-detected)
|
||||||
|
.SH LAYOUT
|
||||||
|
The screen has three areas.
|
||||||
|
.SS Left sidebar
|
||||||
|
Lists all configured VMs.
|
||||||
|
Each entry shows the VM name and current status icon:
|
||||||
|
.TP
|
||||||
|
.B >
|
||||||
|
running
|
||||||
|
.TP
|
||||||
|
.B \&.
|
||||||
|
stopped
|
||||||
|
.TP
|
||||||
|
.B ~
|
||||||
|
paused
|
||||||
|
.TP
|
||||||
|
.B !
|
||||||
|
error
|
||||||
|
.PP
|
||||||
|
Key hints are printed at the bottom of the sidebar.
|
||||||
|
.SS Right panel
|
||||||
|
Shows the selected VM across six tabs, selectable with
|
||||||
|
.BR Tab :
|
||||||
|
.TP
|
||||||
|
.B Info
|
||||||
|
All VM configuration fields, current PID, uptime, UEFI firmware path,
|
||||||
|
and port forwarding rules.
|
||||||
|
.TP
|
||||||
|
.B Command
|
||||||
|
The exact
|
||||||
|
.B qemu\-system\-*
|
||||||
|
command line that will be used to start the VM.
|
||||||
|
.TP
|
||||||
|
.B Log
|
||||||
|
Live stdout and stderr from the QEMU process, buffered to 500 lines.
|
||||||
|
.TP
|
||||||
|
.B Disk
|
||||||
|
Disk image format, virtual size, actual used space, snapshot count,
|
||||||
|
and backing file.
|
||||||
|
.TP
|
||||||
|
.B Snapshots
|
||||||
|
List of internal qcow2 snapshots with ID, name, date, and VM clock time.
|
||||||
|
.TP
|
||||||
|
.B Monitor
|
||||||
|
QEMU monitor socket status and quick-command reference.
|
||||||
|
.SS Status bar
|
||||||
|
The bottom row shows the result of the last action in green (success)
|
||||||
|
or red (error).
|
||||||
|
.SH KEYS
|
||||||
|
.SS Navigation
|
||||||
|
.TP
|
||||||
|
.B Up / Down
|
||||||
|
Move between VMs in the sidebar.
|
||||||
|
.TP
|
||||||
|
.B Tab
|
||||||
|
Cycle through the six tabs.
|
||||||
|
.TP
|
||||||
|
.B PgUp / PgDn
|
||||||
|
Scroll the Log or monitor console output.
|
||||||
|
.TP
|
||||||
|
.B q
|
||||||
|
Quit.
|
||||||
|
.SS VM Lifecycle
|
||||||
|
.TP
|
||||||
|
.B n
|
||||||
|
Create a new VM.
|
||||||
|
.TP
|
||||||
|
.B e
|
||||||
|
Edit the selected VM's configuration.
|
||||||
|
The VM must be stopped.
|
||||||
|
.TP
|
||||||
|
.B Del
|
||||||
|
Delete the selected VM.
|
||||||
|
The VM must be stopped.
|
||||||
|
The disk image is not deleted automatically.
|
||||||
|
.TP
|
||||||
|
.B s
|
||||||
|
Start the selected VM.
|
||||||
|
.TP
|
||||||
|
.B k
|
||||||
|
Stop the VM by sending SIGTERM.
|
||||||
|
Requests a graceful shutdown from the guest OS.
|
||||||
|
.TP
|
||||||
|
.B F
|
||||||
|
Force kill the VM with SIGKILL.
|
||||||
|
Takes effect immediately.
|
||||||
|
.TP
|
||||||
|
.B g
|
||||||
|
Send an ACPI power button signal via the QEMU monitor socket.
|
||||||
|
The guest OS receives a polite shutdown request.
|
||||||
|
The VM must be running.
|
||||||
|
.TP
|
||||||
|
.B z
|
||||||
|
Toggle pause and resume via the QEMU monitor socket.
|
||||||
|
.SS Feature Keys
|
||||||
|
.TP
|
||||||
|
.B d
|
||||||
|
Open the disk management menu.
|
||||||
|
.TP
|
||||||
|
.B p
|
||||||
|
Open the snapshot manager.
|
||||||
|
.TP
|
||||||
|
.B f
|
||||||
|
Open the port forwarding editor.
|
||||||
|
Only available when network is set to
|
||||||
|
.BR user .
|
||||||
|
.TP
|
||||||
|
.B ~
|
||||||
|
Open the interactive QEMU monitor console.
|
||||||
|
.TP
|
||||||
|
.B c
|
||||||
|
Clone the selected VM.
|
||||||
|
The VM must be stopped.
|
||||||
|
.TP
|
||||||
|
.B i
|
||||||
|
Import an existing disk image as a new VM.
|
||||||
|
.TP
|
||||||
|
.B x
|
||||||
|
Eject the attached CD-ROM or ISO image.
|
||||||
|
.SH VM CONFIGURATION
|
||||||
|
Fields available in the new/edit form.
|
||||||
|
Navigate rows with
|
||||||
|
.B Tab
|
||||||
|
or arrow keys.
|
||||||
|
Use
|
||||||
|
.B Left / Right
|
||||||
|
to cycle option fields.
|
||||||
|
Press
|
||||||
|
.B Enter
|
||||||
|
or
|
||||||
|
.B B
|
||||||
|
on path fields to open the file browser.
|
||||||
|
Press
|
||||||
|
.B S
|
||||||
|
to save,
|
||||||
|
.B Esc
|
||||||
|
to cancel.
|
||||||
|
.TP
|
||||||
|
.B Name
|
||||||
|
Identifier for the VM.
|
||||||
|
Also used as the default disk filename
|
||||||
|
.RI ( ~/.cache/qemu\-tui/<n>.qcow2 ).
|
||||||
|
.TP
|
||||||
|
.B Memory (MiB)
|
||||||
|
RAM allocated to the VM in mebibytes.
|
||||||
|
.TP
|
||||||
|
.B CPUs
|
||||||
|
Number of virtual CPU cores.
|
||||||
|
.TP
|
||||||
|
.B Disk image
|
||||||
|
Path to the disk image file.
|
||||||
|
If the file does not exist when the form is saved, an option to create
|
||||||
|
a new qcow2 image is offered.
|
||||||
|
.TP
|
||||||
|
.B CD-ROM / ISO
|
||||||
|
Path to an ISO to attach as a CD-ROM.
|
||||||
|
Press
|
||||||
|
.B x
|
||||||
|
from the main screen to eject.
|
||||||
|
.TP
|
||||||
|
.B Architecture
|
||||||
|
One of:
|
||||||
|
.BR x86_64 ,
|
||||||
|
.BR aarch64 ,
|
||||||
|
.BR arm ,
|
||||||
|
.BR riscv64 ,
|
||||||
|
.BR mips .
|
||||||
|
The matching
|
||||||
|
.B qemu\-system\-<arch>
|
||||||
|
binary is invoked.
|
||||||
|
.TP
|
||||||
|
.B Network
|
||||||
|
.B user
|
||||||
|
\(em NAT via SLIRP with optional port forwarding rules.
|
||||||
|
.br
|
||||||
|
.B none
|
||||||
|
\(em no network interface.
|
||||||
|
.TP
|
||||||
|
.B Display
|
||||||
|
.B none
|
||||||
|
\(em headless, no graphical output.
|
||||||
|
.br
|
||||||
|
.B sdl
|
||||||
|
\(em opens an SDL window on the local display.
|
||||||
|
.br
|
||||||
|
.B vnc
|
||||||
|
\(em listens on VNC port 5900.
|
||||||
|
.TP
|
||||||
|
.B UEFI / OVMF
|
||||||
|
Enables UEFI firmware.
|
||||||
|
The manager auto-detects installed OVMF firmware files.
|
||||||
|
The detected path is shown inline when this field is selected.
|
||||||
|
.TP
|
||||||
|
.B Extra args
|
||||||
|
Additional arguments appended verbatim to the
|
||||||
|
.B qemu\-system\-*
|
||||||
|
invocation, parsed with
|
||||||
|
.BR shlex .
|
||||||
|
.SH DISK MANAGEMENT
|
||||||
|
Opened by pressing
|
||||||
|
.B d
|
||||||
|
when a VM is selected.
|
||||||
|
Navigate actions with
|
||||||
|
.B Up
|
||||||
|
/
|
||||||
|
.B Down
|
||||||
|
and execute with
|
||||||
|
.BR Enter .
|
||||||
|
Press
|
||||||
|
.B R
|
||||||
|
to refresh disk information.
|
||||||
|
Press
|
||||||
|
.B Esc
|
||||||
|
to close.
|
||||||
|
.TP
|
||||||
|
.B Show disk info
|
||||||
|
Runs
|
||||||
|
.B qemu\-img info
|
||||||
|
on the current disk file and refreshes the displayed statistics.
|
||||||
|
Available while the VM is running.
|
||||||
|
.TP
|
||||||
|
.B Create new disk
|
||||||
|
Prompts for a file path and size in gibibytes, then runs:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
qemu\-img create \-f qcow2 <path> <size>G
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
If the VM has no disk configured the new file is set as its disk
|
||||||
|
automatically.
|
||||||
|
Available while the VM is running.
|
||||||
|
.TP
|
||||||
|
.B Resize disk
|
||||||
|
Prompts for a new size in gibibytes and runs:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
qemu\-img resize <path> <size>G
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Disks can only be grown, not shrunk.
|
||||||
|
The filesystem inside the guest must be expanded separately.
|
||||||
|
.B The VM must be stopped.
|
||||||
|
.TP
|
||||||
|
.B Convert to another format
|
||||||
|
Prompts for a destination path and target format, then runs:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
qemu\-img convert \-p \-O <fmt> <src> <dst>
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Supported formats:
|
||||||
|
.BR qcow2 ,
|
||||||
|
.BR raw ,
|
||||||
|
.BR vmdk ,
|
||||||
|
.BR vdi .
|
||||||
|
.B The VM must be stopped.
|
||||||
|
.TP
|
||||||
|
.B Delete disk file
|
||||||
|
Prompts for confirmation then permanently removes the disk image file.
|
||||||
|
This action cannot be undone.
|
||||||
|
.B The VM must be stopped.
|
||||||
|
.SH SNAPSHOTS
|
||||||
|
Opened by pressing
|
||||||
|
.B p
|
||||||
|
when a VM is selected.
|
||||||
|
The manager displays a table with columns ID, Tag/Name, Date, and
|
||||||
|
VM Clock.
|
||||||
|
Navigate with
|
||||||
|
.B Up
|
||||||
|
/
|
||||||
|
.BR Down .
|
||||||
|
.TP
|
||||||
|
.B c
|
||||||
|
Create a new snapshot.
|
||||||
|
Prompts for a name (no spaces allowed).
|
||||||
|
The VM may be running.
|
||||||
|
.TP
|
||||||
|
.B r
|
||||||
|
Restore the selected snapshot.
|
||||||
|
Reverts the disk to the captured state; changes since the snapshot are
|
||||||
|
discarded.
|
||||||
|
.B The VM must be stopped.
|
||||||
|
.TP
|
||||||
|
.B x / Del
|
||||||
|
Delete the selected snapshot.
|
||||||
|
.B The VM must be stopped.
|
||||||
|
.TP
|
||||||
|
.B R
|
||||||
|
Refresh the snapshot list.
|
||||||
|
.TP
|
||||||
|
.B Esc
|
||||||
|
Close the manager.
|
||||||
|
.PP
|
||||||
|
Snapshots use these
|
||||||
|
.BR qemu\-img (1)
|
||||||
|
subcommands internally:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
qemu\-img snapshot \-l <disk> (list)
|
||||||
|
qemu\-img snapshot \-c <tag> <disk> (create)
|
||||||
|
qemu\-img snapshot \-a <tag> <disk> (restore)
|
||||||
|
qemu\-img snapshot \-d <tag> <disk> (delete)
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Snapshots require qcow2 format.
|
||||||
|
Restoring a snapshot does not restore guest RAM state.
|
||||||
|
.SH PORT FORWARDING
|
||||||
|
Opened by pressing
|
||||||
|
.B f
|
||||||
|
when a VM is selected.
|
||||||
|
Only available when network is set to
|
||||||
|
.BR user .
|
||||||
|
.PP
|
||||||
|
The editor shows a table with columns Proto, Host addr, Host port,
|
||||||
|
Guest port, and Desc.
|
||||||
|
Navigate with
|
||||||
|
.B Up
|
||||||
|
/
|
||||||
|
.BR Down .
|
||||||
|
.TP
|
||||||
|
.B a
|
||||||
|
Add a new rule.
|
||||||
|
A preset picker is shown first:
|
||||||
|
.TS
|
||||||
|
l l l l.
|
||||||
|
Preset Protocol Host port Guest port
|
||||||
|
_
|
||||||
|
SSH tcp 2222 22
|
||||||
|
HTTP tcp 8080 80
|
||||||
|
HTTPS tcp 8443 443
|
||||||
|
RDP tcp 3389 3389
|
||||||
|
VNC tcp 5900 5900
|
||||||
|
Custom (prompt) (prompt) (prompt)
|
||||||
|
.TE
|
||||||
|
.PP
|
||||||
|
After choosing a preset you are prompted to confirm or override the
|
||||||
|
protocol, host port, guest port, host bind address (blank = all
|
||||||
|
interfaces), and an optional description.
|
||||||
|
.TP
|
||||||
|
.B d / Del
|
||||||
|
Delete the selected rule (with confirmation).
|
||||||
|
.TP
|
||||||
|
.B Esc
|
||||||
|
Save all rules and close the editor.
|
||||||
|
.PP
|
||||||
|
Rules are stored in the VM configuration and injected as
|
||||||
|
.B hostfwd=
|
||||||
|
entries in the
|
||||||
|
.B \-netdev user
|
||||||
|
argument on the next VM start:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
\-netdev user,id=net0,hostfwd=tcp::2222\-:22
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
To SSH into a headless VM after adding an SSH rule:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
ssh \-p 2222 user@localhost
|
||||||
|
.fi
|
||||||
|
.SH MONITOR CONSOLE
|
||||||
|
Press
|
||||||
|
.B ~
|
||||||
|
to open the interactive QEMU monitor console for the selected VM.
|
||||||
|
The console is divided into three areas:
|
||||||
|
.TP
|
||||||
|
.B Left pane
|
||||||
|
A quick-command list.
|
||||||
|
Press
|
||||||
|
.B Tab
|
||||||
|
to focus,
|
||||||
|
.B Up
|
||||||
|
/
|
||||||
|
.B Down
|
||||||
|
to navigate, and
|
||||||
|
.B Enter
|
||||||
|
to run the selected command.
|
||||||
|
.TP
|
||||||
|
.B Right pane
|
||||||
|
Scrollable output area, cleared on each new command.
|
||||||
|
Scroll with
|
||||||
|
.B PgUp
|
||||||
|
/
|
||||||
|
.BR PgDn .
|
||||||
|
.TP
|
||||||
|
.B Input line
|
||||||
|
Free-form command entry.
|
||||||
|
Press
|
||||||
|
.B Tab
|
||||||
|
to focus, type a command, and press
|
||||||
|
.B Enter
|
||||||
|
to send.
|
||||||
|
.PP
|
||||||
|
Press
|
||||||
|
.B Esc
|
||||||
|
to close.
|
||||||
|
.PP
|
||||||
|
Useful monitor commands:
|
||||||
|
.TS
|
||||||
|
l l.
|
||||||
|
Command Description
|
||||||
|
_
|
||||||
|
info status Current VM execution state
|
||||||
|
info network Network interface details
|
||||||
|
info block Block devices and disk images
|
||||||
|
info cpus Virtual 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 the VM
|
||||||
|
stop Pause VM execution
|
||||||
|
cont Resume paused VM
|
||||||
|
.TE
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.B g
|
||||||
|
and
|
||||||
|
.B z
|
||||||
|
keys on the main screen are shortcuts for
|
||||||
|
.B system_powerdown
|
||||||
|
and
|
||||||
|
.BR stop / cont
|
||||||
|
respectively, without opening the console.
|
||||||
|
.SH CLONE VM
|
||||||
|
Press
|
||||||
|
.B c
|
||||||
|
(VM must be stopped).
|
||||||
|
Enter a new name, then select a disk copy mode:
|
||||||
|
.TP
|
||||||
|
.B 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 at its original path.
|
||||||
|
.TP
|
||||||
|
.B Full copy
|
||||||
|
Runs
|
||||||
|
.B qemu\-img convert
|
||||||
|
to produce a completely independent copy.
|
||||||
|
Takes time proportional to the virtual disk size.
|
||||||
|
Safe to move or delete the original afterwards.
|
||||||
|
.TP
|
||||||
|
.B No copy
|
||||||
|
Clones only the configuration.
|
||||||
|
Both VMs share the same disk file.
|
||||||
|
Running both simultaneously will corrupt the disk.
|
||||||
|
.PP
|
||||||
|
Port forwarding rules are not copied to avoid host port conflicts.
|
||||||
|
After cloning the new VM is automatically selected.
|
||||||
|
.SH IMPORT VM
|
||||||
|
Press
|
||||||
|
.B i
|
||||||
|
to import an existing disk image as a new VM.
|
||||||
|
A file browser opens filtered to:
|
||||||
|
.BR .qcow2 ,
|
||||||
|
.BR .img ,
|
||||||
|
.BR .raw ,
|
||||||
|
.BR .vmdk ,
|
||||||
|
.BR .vdi ,
|
||||||
|
.BR .iso .
|
||||||
|
.PP
|
||||||
|
After selecting a file:
|
||||||
|
.IP 1. 4
|
||||||
|
.B qemu\-img info
|
||||||
|
is run to detect the format and virtual size.
|
||||||
|
.IP 2. 4
|
||||||
|
A brief summary is shown.
|
||||||
|
.IP 3. 4
|
||||||
|
You are prompted for a VM name (defaults to the filename stem).
|
||||||
|
.IP 4. 4
|
||||||
|
A VM configuration is created pointing at the disk.
|
||||||
|
If the format is not qcow2 the correct
|
||||||
|
.B \-drive format=
|
||||||
|
flag is set via extra args.
|
||||||
|
.PP
|
||||||
|
After importing the new VM is automatically selected.
|
||||||
|
.SH UEFI / OVMF
|
||||||
|
Enable the
|
||||||
|
.B UEFI / OVMF
|
||||||
|
toggle in the VM form.
|
||||||
|
The manager searches these paths in order for x86_64:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
/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
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
For aarch64:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
/usr/share/AAVMF/AAVMF_CODE.fd
|
||||||
|
/usr/share/qemu-efi-aarch64/QEMU_EFI.fd
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Install OVMF on common distributions:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
Arch Linux: sudo pacman -S edk2-ovmf
|
||||||
|
Void Linux: sudo xbps-install edk2-ovmf
|
||||||
|
Debian/Ubuntu: sudo apt install ovmf
|
||||||
|
Fedora: sudo dnf install edk2-ovmf
|
||||||
|
.fi
|
||||||
|
.SH KVM ACCELERATION
|
||||||
|
If
|
||||||
|
.I /dev/kvm
|
||||||
|
exists the flags
|
||||||
|
.B \-enable\-kvm \-cpu host
|
||||||
|
are added automatically for near-native CPU performance.
|
||||||
|
.PP
|
||||||
|
To enable KVM:
|
||||||
|
.PP
|
||||||
|
.nf
|
||||||
|
sudo usermod \-aG kvm $USER
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
Log out and back in for the group change to take effect.
|
||||||
|
.SH SESSION PERSISTENCE
|
||||||
|
VMs started by
|
||||||
|
.B qemu\-tui
|
||||||
|
are ordinary background processes.
|
||||||
|
Closing the manager does not stop them.
|
||||||
|
.PP
|
||||||
|
On startup the manager reads
|
||||||
|
.I ~/.cache/qemu\-tui/runtime.json
|
||||||
|
and sends signal 0 to each saved PID to check whether the process is
|
||||||
|
still alive.
|
||||||
|
If it is, the VM is shown as
|
||||||
|
.B running
|
||||||
|
with its original start time and monitor socket path restored.
|
||||||
|
All actions (stop, force kill, ACPI shutdown, pause, resume, and the
|
||||||
|
monitor console) work on re-attached VMs.
|
||||||
|
.SH FILES
|
||||||
|
.TP
|
||||||
|
.I ~/.config/qemu\-tui/vms.json
|
||||||
|
VM configurations.
|
||||||
|
Do not edit while the manager is running.
|
||||||
|
.TP
|
||||||
|
.I ~/.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 processes.
|
||||||
|
.TP
|
||||||
|
.I ~/.cache/qemu\-tui/<n>.qcow2
|
||||||
|
Default location for newly created disk images.
|
||||||
|
.TP
|
||||||
|
.I ~/.cache/qemu\-tui/monitors/<n>.sock
|
||||||
|
QEMU monitor Unix domain socket for each running VM.
|
||||||
|
.SH SEE ALSO
|
||||||
|
.BR qemu\-system\-x86_64 (1),
|
||||||
|
.BR qemu\-img (1),
|
||||||
|
.BR qemu\-system\-aarch64 (1)
|
||||||
|
.SH AUTHOR
|
||||||
|
Written by Emmett.
|
||||||
Executable
+2842
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user