initial commit

1 files changed, 591 insertions, 0 deletions

diff --git a/qemu-tui.1 b/qemu-tui.1
new file mode 100644
index 0000000..3310fdc
--- /dev/null
+++ b/qemu-tui.1
@@ -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.