mirror of
https://github.com/oSoWoSo/DistroHopper.git
synced 2024-08-14 22:46:53 +00:00
New release docs with cogged README (#508)
This commit is contained in:
Phil Clifford
GitHub
parent
39da52a3bf
commit
d0c2bb228a
8 changed files with 698 additions and 520 deletions
|
|
@ -1,30 +1,26 @@
|
|||
---
|
||||
author: Martin Wimpress
|
||||
date: 'February 20, 2022'
|
||||
date: July 30, 2022
|
||||
footer: quickemu
|
||||
header: Quickemu User Manual
|
||||
section: 1
|
||||
title: QUICKEMU
|
||||
---
|
||||
|
||||
NAME
|
||||
====
|
||||
# NAME
|
||||
|
||||
quickemu - A quick VM builder and manager
|
||||
|
||||
SYNOPSIS
|
||||
========
|
||||
# SYNOPSIS
|
||||
|
||||
**quickemu** \[*OPTION*\]...
|
||||
|
||||
DESCRIPTION
|
||||
===========
|
||||
# DESCRIPTION
|
||||
|
||||
**quickemu** will create and run highly optimised desktop virtual
|
||||
machines for Linux, macOS and Windows
|
||||
|
||||
OPTIONS
|
||||
=======
|
||||
# OPTIONS
|
||||
|
||||
**--vm**
|
||||
: vm configuration file
|
||||
|
|
@ -70,23 +66,21 @@ You can also pass optional parameters
|
|||
**--version**
|
||||
: Print version
|
||||
|
||||
EXAMPLES
|
||||
========
|
||||
# EXAMPLES
|
||||
|
||||
**quickemu --vm ubuntu-mate-21.10-.conf**
|
||||
: Launches the VM specified in the file *ubuntu-mate-21.10-.conf*
|
||||
**quickemu --vm ubuntu-mate-22.04-.conf**
|
||||
: Launches the VM specified in the file *ubuntu-mate-22.04-.conf*
|
||||
|
||||
Introduction
|
||||
------------
|
||||
## Introduction
|
||||
|
||||
Quickly create and run highly optimised desktop virtual machines for
|
||||
Linux, macOS and Windows; with just two commands. You decide what
|
||||
operating system you want to run and Quickemu will figure out the best
|
||||
way to do it for you. For example:
|
||||
|
||||
``` {.bash}
|
||||
quickget ubuntu-mate 21.10
|
||||
quickemu --vm ubuntu-mate-21.10-.conf
|
||||
``` bash
|
||||
quickget ubuntu-mate 22.04
|
||||
quickemu --vm ubuntu-mate-22.04-.conf
|
||||
```
|
||||
|
||||
The original objective of the project was to enable quick testing of
|
||||
|
|
@ -96,8 +90,7 @@ and no elevated permissions are required to run the virtual machines.
|
|||
**Quickemu now also includes comprehensive support for macOS and
|
||||
Windows**.
|
||||
|
||||
Features
|
||||
--------
|
||||
## Features
|
||||
|
||||
- **macOS** Monterey, Big Sur, Catalina, Mojave & High Sierra
|
||||
- **Windows** 8.1, 10 and 11 including TPM 2.0
|
||||
|
|
@ -135,8 +128,7 @@ Quickemu.
|
|||
[](https://www.youtube.com/watch?v=AOTYWEgw0hI)
|
||||
|
||||
Requirements
|
||||
------------
|
||||
## Requirements
|
||||
|
||||
- [QEMU](https://www.qemu.org/) (*6.0.0 or newer*) **with GTK, SDL,
|
||||
SPICE & VirtFS support**
|
||||
|
|
@ -161,11 +153,37 @@ Requirements
|
|||
- [zsync](http://zsync.moria.org.uk/)
|
||||
- [unzip](http://www.info-zip.org/UnZip.html)
|
||||
|
||||
Usage
|
||||
=====
|
||||
### Installing Requirements
|
||||
|
||||
Graphical User Interfaces
|
||||
-------------------------
|
||||
For Ubuntu, Arch and nixos systems the
|
||||
[ppa](https://launchpad.net/~flexiondotorg/+archive/ubuntu/quickemu),
|
||||
[AUR](https://aur.archlinux.org/packages/quickemu) or
|
||||
[nix](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/quickemu)
|
||||
packaging will take care of the dependencies. For other host
|
||||
distributions or operating systems it will be necessary to install the
|
||||
above requirements or their equivalents.
|
||||
|
||||
These examples may save a little typing
|
||||
|
||||
Debian:
|
||||
|
||||
sudo apt install qemu bash coreutils ovmf grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-client-gtk swtpm wget xdg-user-dirs zsync unzip
|
||||
|
||||
Fedora:
|
||||
|
||||
sudo dnf install qemu bash coreutils edk2-tools grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-gtk-tools swtpm wget xdg-user-dirs xrandr unzip
|
||||
|
||||
MacOS:
|
||||
|
||||
This is a work in progress (see [issue
|
||||
248](https://github.com/quickemu-project/quickemu/issues/248) for other
|
||||
steps and changes that may enable running on MacOS)
|
||||
|
||||
brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync
|
||||
|
||||
# Usage
|
||||
|
||||
## Graphical User Interfaces
|
||||
|
||||
While `quickemu` and `quickget` are designed for the terminal, a
|
||||
graphical user interface is also available:
|
||||
|
|
@ -180,21 +198,20 @@ Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and
|
|||
|
||||
### Quickgui for Ubuntu
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
sudo add-apt-repository ppa:yannick-mauray/quickgui
|
||||
sudo apt update
|
||||
sudo apt install quickgui
|
||||
```
|
||||
|
||||
Ubuntu Guest
|
||||
------------
|
||||
## Ubuntu Guest
|
||||
|
||||
`quickget` will automatically download an Ubuntu release and create the
|
||||
virtual machine configuration.
|
||||
|
||||
``` {.bash}
|
||||
quickget ubuntu 20.04
|
||||
quickemu --vm ubuntu-20.04.conf
|
||||
``` bash
|
||||
quickget ubuntu 22.04
|
||||
quickemu --vm ubuntu-22.04.conf
|
||||
```
|
||||
|
||||
- Complete the installation as normal.
|
||||
|
|
@ -211,7 +228,7 @@ quickemu --vm ubuntu-20.04.conf
|
|||
`quickget` can also download/refresh devel images via `zsync` for Ubuntu
|
||||
developers and testers.
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
quickget ubuntu devel
|
||||
quickemu --vm ubuntu-devel.conf
|
||||
```
|
||||
|
|
@ -234,8 +251,7 @@ with your preferred flavour.
|
|||
- `ubuntu` (Ubuntu)
|
||||
- `xubuntu` (Xubuntu)
|
||||
|
||||
Other Operating Systems
|
||||
-----------------------
|
||||
## Other Operating Systems
|
||||
|
||||
`quickget` also supports:
|
||||
|
||||
|
|
@ -244,11 +260,15 @@ Other Operating Systems
|
|||
- `android` (Android x86)
|
||||
- `archlinux` (Arch Linux)
|
||||
- `arcolinux` (Arco Linux)
|
||||
- `batocera` (Batocera)
|
||||
- `cachyos` (CachyOS)
|
||||
- `centos-stream` (CentOS Stream)
|
||||
- `debian` (Debian)
|
||||
- `deepin` (Deepin)
|
||||
- `devuan` (Devuan)
|
||||
- `dragonflybsd` (DragonFlyBSD)
|
||||
- `elementary` (elementary OS)
|
||||
- `endeavouros` (EndeavourOS)
|
||||
- `fedora` (Fedora)
|
||||
- `freebsd` (FreeBSD)
|
||||
- `freedos` (FreeDOS)
|
||||
|
|
@ -260,6 +280,7 @@ Other Operating Systems
|
|||
- `kdeneon` (KDE Neon)
|
||||
- `kolibrios` (KolibriOS)
|
||||
- `linuxmint` (Linux Mint)
|
||||
- `lmde` (Linux Mint Debian Edition)
|
||||
- `manjaro` (Manjaro)
|
||||
- `mxlinux` (MX Linux)
|
||||
- `netboot` (netboot.xyz)
|
||||
|
|
@ -283,7 +304,7 @@ configuration.
|
|||
- Download a .iso image of a Linux distribution
|
||||
- Create a VM configuration file; for example `debian-bullseye.conf`
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
guest_os="linux"
|
||||
disk_img="debian-bullseye/disk.qcow2"
|
||||
iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso"
|
||||
|
|
@ -291,7 +312,7 @@ iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso"
|
|||
|
||||
- Use `quickemu` to start the virtual machine:
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
quickemu --vm debian-bullseye.conf
|
||||
```
|
||||
|
||||
|
|
@ -302,13 +323,12 @@ quickemu --vm debian-bullseye.conf
|
|||
- Install the SPICE WebDAV agent (`spice-webdavd`) to enable file
|
||||
sharing.
|
||||
|
||||
macOS Guest
|
||||
-----------
|
||||
## macOS Guest
|
||||
|
||||
`quickget` automatically downloads a macOS recovery image and creates a
|
||||
virtual machine configuration.
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
quickget macos catalina
|
||||
quickemu --vm macos-catalina.conf
|
||||
```
|
||||
|
|
@ -338,7 +358,7 @@ supported.
|
|||
|
||||
The default macOS configuration looks like this:
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
guest_os="macos"
|
||||
img="macos-catalina/RecoveryImage.img"
|
||||
disk_img="macos-catalina/disk.qcow2"
|
||||
|
|
@ -389,8 +409,7 @@ There are some considerations when running macOS via Quickemu.
|
|||
webdavd](https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24).
|
||||
- Copy/paste via SPICE agent is **not available on macOS**.
|
||||
|
||||
Windows 8.1, 10 & 11 Guests
|
||||
---------------------------
|
||||
## Windows 8.1, 10 & 11 Guests
|
||||
|
||||
`quickget` can automatically download Windows 8.1, [Windows
|
||||
10](https://www.microsoft.com/en-gb/software-download/windows10ISO) and
|
||||
|
|
@ -400,7 +419,7 @@ with the [VirtIO drivers for
|
|||
Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/)
|
||||
and creates a virtual machine configuration.
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
quickget windows 11
|
||||
quickemu --vm windows-11.conf
|
||||
```
|
||||
|
|
@ -414,18 +433,19 @@ By default `quickget` will download the *"English International"*
|
|||
release, but you can optionally specify one of the supported languages:
|
||||
For example:
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
quickget windows 11 "Chinese (Traditional)"
|
||||
```
|
||||
|
||||
The default Windows 11 configuration looks like this:
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
guest_os="windows"
|
||||
disk_img="windows-11/disk.qcow2"
|
||||
iso="windows-11/Win11_EnglishInternational_x64.iso"
|
||||
fixed_iso="windows-11/virtio-win.iso"
|
||||
tpm="on"
|
||||
secureboot="on"
|
||||
```
|
||||
|
||||
- `guest_os="windows"` instructs `quickemu` to optimise for Windows.
|
||||
|
|
@ -433,47 +453,58 @@ tpm="on"
|
|||
- `tpm="on"` instructs `quickemu` to create a software emulated TPM
|
||||
device using `swtpm`.
|
||||
|
||||
All the options
|
||||
===============
|
||||
# All the options
|
||||
|
||||
Here are the usage instructions:
|
||||
|
||||
``` {.bash}
|
||||
|
||||
Usage
|
||||
quickemu --vm ubuntu.conf
|
||||
|
||||
You can also pass optional parameters
|
||||
--braille : Enable braille support. Requires SDL.
|
||||
--delete-disk : Delete the disk image and EFI variables
|
||||
--delete-vm : Delete the entire VM and it's configuration
|
||||
--display : Select display backend. 'sdl' (default), 'gtk', 'none', or 'spice'
|
||||
--fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit)
|
||||
--ignore-msrs-always : Configure KVM to always ignore unhandled machine-specific registers
|
||||
--screen <screen> : Use specified screen to determine the window size.
|
||||
--shortcut : Create a desktop shortcut
|
||||
--snapshot apply <tag> : Apply/restore a snapshot.
|
||||
--snapshot create <tag> : Create a snapshot.
|
||||
--snapshot delete <tag> : Delete a snapshot.
|
||||
--snapshot info : Show disk/snapshot info.
|
||||
--status-quo : Do not commit any changes to disk/snapshot.
|
||||
--version : Print version
|
||||
Usage
|
||||
quickemu --vm ubuntu.conf
|
||||
|
||||
```
|
||||
You can also pass optional parameters
|
||||
--braille : Enable braille support. Requires SDL.
|
||||
--delete-disk : Delete the disk image and EFI variables
|
||||
--delete-vm : Delete the entire VM and it's configuration
|
||||
--display : Select display backend. 'sdl' (default), 'gtk', 'none', or 'spice'
|
||||
--fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit)
|
||||
--ignore-msrs-always : Configure KVM to always ignore unhandled machine-specific registers
|
||||
--screen <screen> : Use specified screen to determine the window size.
|
||||
--shortcut : Create a desktop shortcut
|
||||
--snapshot apply <tag> : Apply/restore a snapshot.
|
||||
--snapshot create <tag> : Create a snapshot.
|
||||
--snapshot delete <tag> : Delete a snapshot.
|
||||
--snapshot info : Show disk/snapshot info.
|
||||
--status-quo : Do not commit any changes to disk/snapshot.
|
||||
--viewer <viewer> : Choose an alternative viewer. @Options: 'spicy' (default), 'remote-viewer', 'none'
|
||||
--ssh-port <port> : Set ssh-port manually
|
||||
--spice-port <port> : Set spice-port manually
|
||||
--public-dir <path> : expose share directory. @Options: '' (default: xdg-user-dir PUBLICSHARE), '<directory>', 'none'
|
||||
--monitor <type> : Set monitor connection type. @Options: 'socket' (default), 'telnet', 'none'
|
||||
--monitor-telnet-host <ip/host> : Set telnet host for monitor. (default: 'localhost')
|
||||
--monitor-telnet-port <port> : Set telnet port for monitor. (default: '4440')
|
||||
--monitor-cmd <cmd> : Send command to monitor if available. (Example: system_powerdown)
|
||||
--serial <type> : Set serial connection type. @Options: 'socket' (default), 'telnet', 'none'
|
||||
--serial-telnet-host <ip/host> : Set telnet host for serial. (default: 'localhost')
|
||||
--serial-telnet-port <port> : Set telnet port for serial. (default: '6660')
|
||||
--keyboard <type> : Set keyboard. @Options: 'usb' (default), 'ps2', 'virtio'
|
||||
--keyboard_layout <layout> : Set keyboard layout.
|
||||
--mouse <type> : Set mouse. @Options: 'tablet' (default), 'ps2', 'usb', 'virtio'
|
||||
--usb-controller <type> : Set usb-controller. @Options: 'ehci' (default), 'xhci', 'none'
|
||||
--extra_args <arguments> : Pass additional arguments to qemu
|
||||
--version : Print version
|
||||
|
||||
Desktop shortcuts
|
||||
-----------------
|
||||
## Desktop shortcuts
|
||||
|
||||
Desktop shortcuts can be created for a VM, the shortcuts are saved in
|
||||
`~/.local/share/applications`. Here is an example of how to create a
|
||||
shortcut.
|
||||
|
||||
``` {.bash}
|
||||
quickemu --vm ubuntu-20.04-desktop.conf --shortcut
|
||||
``` bash
|
||||
quickemu --vm ubuntu-22.04-desktop.conf --shortcut
|
||||
```
|
||||
|
||||
Screen and window size (Linux guests only)
|
||||
------------------------------------------
|
||||
## Screen and window size (Linux guests only)
|
||||
|
||||
`qemu` will always default to the primary monitor to display the VM's
|
||||
window.
|
||||
|
|
@ -494,13 +525,13 @@ must match the resolution of the screen.
|
|||
|
||||
To know which screen to use, type:
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
xrandr --listmonitors | grep -v Monitors
|
||||
```
|
||||
|
||||
The command will output something like this:
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
0: +*HDMI-0 2560/597x1440/336+1920+0 HDMI-0
|
||||
1: +DVI-D-0 1920/527x1080/296+0+0 DVI-D-0
|
||||
```
|
||||
|
|
@ -509,7 +540,7 @@ The first number is what needs to be passed to the `--screen` option.
|
|||
|
||||
For example:
|
||||
|
||||
``` {.bash}
|
||||
``` bash
|
||||
quickemu --vm vm.conf --screen 0
|
||||
```
|
||||
|
||||
|
|
@ -518,8 +549,7 @@ which Quickemu sizes to 2048x1152. Without the `--screen` option,
|
|||
Quickemu would have used the 1920x1080 monitor which results in a window
|
||||
size of 1664x936.
|
||||
|
||||
References
|
||||
==========
|
||||
# References
|
||||
|
||||
Useful reference that assisted the development of Quickemu.
|
||||
|
||||
|
|
@ -556,20 +586,17 @@ Useful reference that assisted the development of Quickemu.
|
|||
- <https://superuser.com/questions/628169/how-to-share-a-directory-with-the-host-without-networking-in-qemu>
|
||||
- <https://virtio-fs.gitlab.io/>
|
||||
|
||||
AUTHORS
|
||||
=======
|
||||
# AUTHORS
|
||||
|
||||
Written by Martin Wimpress.
|
||||
|
||||
BUGS
|
||||
====
|
||||
# BUGS
|
||||
|
||||
Submit bug reports online at:
|
||||
<https://github.com/quickemu-project/quickemu/issues>
|
||||
|
||||
SEE ALSO
|
||||
========
|
||||
# SEE ALSO
|
||||
|
||||
Full sources at: <https://github.com/quickemu-project/quickemu>
|
||||
|
||||
quickemu\_conf(1), quickget(1), quickgui(1)
|
||||
quickemu_conf(1), quickget(1), quickgui(1)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue