README (10917B)
1 QEMU-TUI 2 ======== 3 A terminal UI for managing QEMU virtual machines. 4 Zero external dependencies -- uses only Python's built-in curses module. 5 6 7 REQUIREMENTS 8 ------------ 9 Python 3.7 or later 10 qemu-system-* binaries on your PATH 11 qemu-img (for disk management and snapshots) 12 /dev/kvm (optional, auto-detected for hardware acceleration) 13 OVMF firmware (optional, auto-detected for UEFI boot) 14 15 16 INSTALLATION 17 ------------ 18 No pip install needed. Just make the script executable: 19 20 chmod +x qemu-tui.py 21 ./qemu-tui.py 22 23 Or copy it somewhere on your PATH: 24 25 cp qemu-tui.py ~/.local/bin/qemu-tui 26 chmod +x ~/.local/bin/qemu-tui 27 qemu-tui 28 29 30 LAYOUT 31 ------ 32 The screen is divided into two panes separated by a vertical line. 33 34 Left sidebar 35 Lists all VMs with a live status icon and state label. 36 Key hints are shown at the bottom of the sidebar. 37 38 Status icons: 39 > running 40 . stopped 41 ~ paused 42 ! error 43 44 Right panel 45 Shows details for the currently selected VM. 46 A header line shows the VM name, status, PID, and uptime. 47 Below it are six tabs selectable with the Tab key: 48 49 Info VM configuration and runtime info 50 Command The exact qemu-system-* command line 51 Log Live stdout/stderr from the QEMU process 52 Disk Disk image details and management hint 53 Snapshots List of internal qcow2 snapshots 54 Monitor QEMU monitor socket status and quick reference 55 56 Status bar 57 The bottom row shows the result of the last action in green 58 (success) or red (error). 59 60 61 KEYBINDINGS 62 ----------- 63 Navigation 64 65 Up / Down Move between VMs in the sidebar 66 Tab Cycle through tabs 67 PgUp / PgDn Scroll log or console output 68 q Quit 69 70 VM lifecycle 71 72 n New VM 73 e Edit VM config (VM must be stopped) 74 Del Delete VM (VM must be stopped) 75 s Start VM 76 k Stop VM via SIGTERM (requests graceful OS shutdown) 77 F Force kill VM via SIGKILL (immediate termination) 78 g Graceful ACPI power-off via monitor socket 79 z Pause / resume toggle via monitor socket 80 81 Features 82 83 d Open disk management menu 84 p Open snapshot manager 85 f Open port forwarding editor 86 ~ Open interactive QEMU monitor console 87 c Clone VM 88 i Import existing disk image as new VM 89 x Eject CD-ROM / ISO 90 91 92 TABS 93 ---- 94 Info 95 Displays all VM settings, current PID, uptime, UEFI firmware path 96 (or a warning if OVMF is not found), and port forwarding rules. 97 98 Command 99 Shows the full qemu-system-* command that will be used to start the 100 VM, wrapped across multiple lines for readability. Useful for 101 debugging or copying the command to run manually. 102 103 Log 104 Streams live stdout and stderr output from the QEMU process. 105 Scroll with PgUp and PgDn. Output is buffered up to 500 lines. 106 107 Disk 108 Shows the disk image path, format, virtual size, actual used space 109 with a percentage, snapshot count, and backing file if any. 110 If the disk is locked by a running VM, a friendly note is shown 111 instead of a raw error. 112 113 Press 'd' to open the disk management menu: 114 Create -- create a new qcow2 image (prompts for path and size) 115 Resize -- expand the disk to a new size (VM must be stopped) 116 Convert -- convert to qcow2, raw, vmdk, or vdi (VM must be stopped) 117 Delete -- permanently delete the disk file (VM must be stopped) 118 119 Snapshots 120 Lists all internal qcow2 snapshots with ID, name, date, and VM 121 clock time. If the disk is locked, a note is shown instead. 122 123 Press 'p' to open the snapshot manager: 124 c Create a snapshot (allowed while VM is running) 125 r Restore a snapshot (VM must be stopped) 126 x / Del Delete a snapshot (VM must be stopped) 127 R Refresh the list 128 Esc Close 129 130 Snapshot names cannot contain spaces. 131 132 Monitor 133 When the VM is running, shows the path of the QEMU monitor Unix 134 socket and a quick-reference of useful monitor commands. 135 136 Press '~' to open the interactive monitor console: 137 Left pane Quick-command list. Tab to focus, Up/Down to navigate, 138 Enter to run the selected command. 139 Right pane Scrollable output area. Cleared on each new command. 140 Scroll with PgUp / PgDn. 141 Bottom bar Free-form command input. Tab to focus, Enter to send. 142 Esc Close the console. 143 144 Useful monitor commands: 145 info status Current VM state 146 info network Network interfaces 147 info block Block devices and disk images 148 info cpus CPU information 149 info mem Memory map 150 info pci PCI device list 151 info snapshots Snapshot list (live) 152 system_powerdown Send ACPI power button signal 153 system_reset Hard reset (like pressing the reset button) 154 stop Pause execution 155 cont Resume execution 156 157 158 VM CONFIGURATION 159 ---------------- 160 Fields available when creating or editing a VM: 161 162 Name 163 Identifier for the VM. Also used as the default disk filename: 164 ~/.cache/qemu-tui/<name>.qcow2 165 166 Memory (MiB) 167 RAM allocated to the VM. e.g. 1024, 2048, 4096. 168 169 CPUs 170 Number of virtual CPU cores. 171 172 Disk image 173 Path to the qcow2 (or other format) disk image. 174 Press Enter or B on this field to open the file browser. 175 Default path is set automatically from the VM name. 176 If the file does not exist when you save, you are offered 177 the option to create it. 178 179 CD-ROM / ISO 180 Path to an ISO or image file to attach as a CD-ROM drive. 181 Press Enter or B to browse. Press 'x' from the main screen 182 to eject. 183 184 Architecture 185 One of: x86_64, aarch64, arm, riscv64, mips. 186 The matching qemu-system-<arch> binary is used. 187 188 Network 189 user -- NAT networking via SLIRP. Supports port forwarding. 190 none -- No network interface. 191 192 Display 193 none -- Headless. No graphical output. Use SSH to access. 194 sdl -- Opens an SDL window on the local display. 195 vnc -- Listens on VNC port 5900. 196 197 UEFI / OVMF 198 Enables UEFI firmware. The manager searches common paths for 199 an OVMF firmware file automatically. The detected path is shown 200 inline when the field is selected. If no firmware is found, 201 an error is shown in the Info tab. 202 203 Extra args 204 Additional raw arguments appended verbatim to the qemu-system-* 205 command line. Parsed with shlex so quoting is respected. 206 207 208 PORT FORWARDING 209 --------------- 210 Only available when network is set to 'user'. 211 212 Press 'f' to open the editor. Press 'a' to add a rule. 213 A preset picker appears first: 214 215 SSH tcp host 2222 -> guest 22 216 HTTP tcp host 8080 -> guest 80 217 HTTPS tcp host 8443 -> guest 443 218 RDP tcp host 3389 -> guest 3389 219 VNC tcp host 5900 -> guest 5900 220 Custom enter all fields manually 221 222 After choosing a preset you can override all values: 223 Protocol tcp or udp 224 Host port port on the physical machine 225 Guest port port inside the VM 226 Host bind addr leave blank to listen on all interfaces 227 Description optional label shown in the rule list 228 229 Rules are saved with the VM config and injected as hostfwd= entries 230 in the -netdev user argument. Changes take effect on the next start. 231 232 d / Del Delete the selected rule 233 Esc Save and close 234 235 236 CLONE VM 237 -------- 238 Press 'c' (VM must be stopped). Enter a new name, then choose a 239 disk copy mode: 240 241 Linked clone 242 Creates a new qcow2 image with the original disk as a backing 243 file. Very small and instant. Writes from the clone go to the 244 new file; the original is not modified. Requires the original 245 disk to remain accessible. 246 247 Full copy 248 Runs qemu-img convert to produce a completely independent copy. 249 Takes time proportional to the virtual disk size and uses the 250 same amount of storage. Safe to use without the original. 251 252 No copy 253 Clones only the config. Both VMs point at the same disk file. 254 Running both simultaneously will corrupt the disk. 255 256 Port forwarding rules are not copied to avoid host port conflicts. 257 After cloning the new VM is selected automatically. 258 259 260 IMPORT VM 261 --------- 262 Press 'i' to import an existing disk image as a new VM. 263 264 A file browser opens, filtered to common disk image extensions: 265 .qcow2 .img .raw .vmdk .vdi .iso 266 267 After selecting a file: 268 1. qemu-img info is run to detect the format and virtual size. 269 2. A brief summary is shown. 270 3. You are prompted for a VM name (defaults to the filename stem). 271 4. A VM config is created pointing at the selected file. 272 If the format is not qcow2 the correct -drive format= flag 273 is set via extra args. 274 275 After importing the new VM is selected automatically. 276 277 278 UEFI / OVMF 279 ----------- 280 Enable the 'UEFI / OVMF' toggle in the VM form. 281 282 The manager searches these paths in order (x86_64): 283 /usr/share/ovmf/OVMF.fd 284 /usr/share/ovmf/x64/OVMF.fd 285 /usr/share/OVMF/OVMF_CODE.fd 286 /usr/share/edk2/ovmf/OVMF_CODE.fd 287 /usr/share/edk2-ovmf/OVMF_CODE.fd 288 /usr/lib/ovmf/OVMF.fd 289 /usr/share/qemu/ovmf-x86_64.bin 290 291 For aarch64: 292 /usr/share/AAVMF/AAVMF_CODE.fd 293 /usr/share/qemu-efi-aarch64/QEMU_EFI.fd 294 295 Install on common distributions: 296 297 Arch Linux / Void Linux 298 sudo pacman -S edk2-ovmf 299 sudo xbps-install edk2-ovmf 300 301 Debian / Ubuntu 302 sudo apt install ovmf 303 304 Fedora 305 sudo dnf install edk2-ovmf 306 307 308 KVM ACCELERATION 309 ---------------- 310 Detected automatically. If /dev/kvm exists, the flags 311 -enable-kvm -cpu host 312 are added to the command, giving near-native CPU performance. 313 314 To enable KVM on Linux: 315 sudo usermod -aG kvm $USER 316 (log out and back in for the group change to take effect) 317 318 If KVM is not available QEMU falls back to software emulation, 319 which is significantly slower. 320 321 322 FILE LOCATIONS 323 -------------- 324 ~/.config/qemu-tui/vms.json 325 VM configurations. Edited by the manager; do not modify 326 while the manager is running. 327 328 ~/.cache/qemu-tui/runtime.json 329 Runtime state: PID, start time, status, and monitor socket 330 path for each running or paused VM. Written on every start 331 and stop. Read on startup to re-attach to surviving VMs. 332 333 ~/.cache/qemu-tui/<name>.qcow2 334 Default location for newly created disk images. 335 336 ~/.cache/qemu-tui/monitors/<name>.sock 337 QEMU monitor Unix domain socket for each running VM. 338 339 340 SESSION PERSISTENCE 341 ------------------- 342 VMs started by qemu-tui are ordinary background processes. Closing 343 the manager does not stop them. 344 345 When qemu-tui starts it reads runtime.json and for each entry sends 346 signal 0 (kill -0) to the saved PID to check whether the process is 347 still alive. If it is, the VM is shown as 'running' with its original 348 start time and monitor socket path restored. 349 350 All actions work on re-attached VMs: 351 k Stop (SIGTERM) 352 F Force kill (SIGKILL) 353 g ACPI power-off via monitor 354 z Pause / resume via monitor 355 ~ Open monitor console