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