initial commit
This commit is contained in:
+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.
|
||||
Reference in New Issue
Block a user