move documents

documents/quickemu_conf.1

@@ -0,0 +1,327 @@
+.\" Automatically generated by Pandoc 2.19.2
+.\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
+.TH "QUICKEMU_CONF" "1" "February 4, 2023" "quickemu_conf" "Quickemu Configuration Manual"
+.hy
+.SH NAME
+.PP
+quickemu_conf - Options and parameters in the quickemu <vm>.conf
+.SH DESCRIPTION
+.PP
+\f[B]quickemu\f[R] will create and run highly optimised desktop virtual
+machines for Linux, macOS and Windows.
+It uses sensible defaults, but many configuration options can be
+overridden in the required configuration file, which will as a minimum
+specify the path to the installation ISO and QEMU disk for the installed
+VM
+.SH OPTIONS
+.PP
+These are the options and defaults for the <vm>.conf file
+.IP
+.nf
+\f[C]
+# Lowercase variables are used in the VM config file only
+boot=\[dq]efi\[dq]
+cpu_cores=\[dq]\[dq]
+disk_img=\[dq]\[dq]
+disk_size=\[dq]\[dq]
+display=\[dq]\[dq]
+extra_args=\[dq]\[dq]
+fixed_iso=\[dq]\[dq]
+floppy=\[dq]\[dq]
+guest_os=\[dq]linux\[dq]
+img=\[dq]\[dq]
+iso=\[dq]\[dq]
+macaddr=\[dq]\[dq]
+macos_release=\[dq]\[dq]
+network=\[dq]\[dq]
+port_forwards=()
+preallocation=\[dq]off\[dq]
+ram=\[dq]\[dq]
+secureboot=\[dq]off\[dq]
+tpm=\[dq]off\[dq]
+usb_devices=()
+viewer=\[dq]spicy\[dq]
+ssh_port=\[dq]\[dq]
+spice_port=\[dq]\[dq]
+public_dir=\[dq]\[dq]
+monitor=\[dq]socket\[dq]
+monitor_telnet_port=\[dq]4440\[dq]
+monitor_telnet_host=\[dq]localhost\[dq]
+monitor_cmd=\[dq]\[dq]
+serial=\[dq]socket\[dq]
+serial_telnet_port=\[dq]6660\[dq]
+serial_telnet_host=\[dq]localhost\[dq]
+# options: ehci(USB2.0), xhci(USB3.0)
+usb_controller=\[dq]ehci\[dq]
+# options: ps2, usb, virtio
+keyboard=\[dq]usb\[dq]
+keyboard_layout=\[dq]en-us\[dq]
+# options: ps2, usb, tablet, virtio
+mouse=\[dq]tablet\[dq]
+\f[R]
+.fi
+.SH EXAMPLES
+.IP
+.nf
+\f[C]
+guest_os=\[dq]linux\[dq]
+disk_img=\[dq]debian-bullseye/disk.qcow2\[dq]
+iso=\[dq]debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso\[dq]
+\f[R]
+.fi
+.PP
+The default macOS configuration looks like this:
+.IP
+.nf
+\f[C]
+guest_os=\[dq]macos\[dq]
+img=\[dq]macos-catalina/RecoveryImage.img\[dq]
+disk_img=\[dq]macos-catalina/disk.qcow2\[dq]
+macos_release=\[dq]catalina\[dq]
+\f[R]
+.fi
+.IP \[bu] 2
+\f[V]guest_os=\[dq]macos\[dq]\f[R] instructs Quickemu to optimise for
+macOS.
+.IP \[bu] 2
+\f[V]macos_release=\[dq]catalina\[dq]\f[R] instructs Quickemu to
+optimise for a particular macOS release.
+.RS 2
+.IP \[bu] 2
+For example VirtIO Network and Memory Ballooning are available in Big
+Sur and newer, but not previous releases.
+.IP \[bu] 2
+And VirtIO Block Media (disks) are supported/stable in Catalina and
+newer.
+.RE
+.PP
+The default Windows 11 configuration looks like this:
+.IP
+.nf
+\f[C]
+guest_os=\[dq]windows\[dq]
+disk_img=\[dq]windows-11/disk.qcow2\[dq]
+iso=\[dq]windows-11/Win11_EnglishInternational_x64.iso\[dq]
+fixed_iso=\[dq]windows-11/virtio-win.iso\[dq]
+tpm=\[dq]on\[dq]
+secureboot=\[dq]on\[dq]
+\f[R]
+.fi
+.IP \[bu] 2
+\f[V]guest_os=\[dq]windows\[dq]\f[R] instructs \f[V]quickemu\f[R] to
+optimise for Windows.
+.IP \[bu] 2
+\f[V]fixed_iso=\f[R] specifies the ISO image that provides VirtIO
+drivers.
+.IP \[bu] 2
+\f[V]tpm=\[dq]on\[dq]\f[R] instructs \f[V]quickemu\f[R] to create a
+software emulated TPM device using \f[V]swtpm\f[R].
+.SH BIOS and EFI
+.PP
+Since Quickemu 2.1.0 \f[V]efi\f[R] is the default boot option.
+If you want to override this behaviour then add the following line to
+you VM configuration to enable legacy BIOS.
+.IP \[bu] 2
+\f[V]boot=\[dq]legacy\[dq]\f[R] - Enable Legacy BIOS boot
+.SH Tuning CPU cores, RAM & disks
+.PP
+By default, Quickemu will calculate the number of CPUs cores and RAM to
+allocate to a VM based on the specifications of your host computer.
+You can override this default behaviour and tune the VM configuration to
+your liking.
+.PP
+Add additional lines to your virtual machine configuration:
+.IP \[bu] 2
+\f[V]cpu_cores=\[dq]4\[dq]\f[R] - Specify the number of CPU cores
+allocated to the VM
+.IP \[bu] 2
+\f[V]ram=\[dq]4G\[dq]\f[R] - Specify the amount of RAM to allocate to
+the VM
+.IP \[bu] 2
+\f[V]disk_size=\[dq]16G\[dq]\f[R] - Specify the size of the virtual disk
+allocated to the VM
+.SS Disk preallocation
+.PP
+Preallocation mode (allowed values: \f[V]off\f[R] (default),
+\f[V]metadata\f[R], \f[V]falloc\f[R], \f[V]full\f[R]).
+An image with preallocated metadata is initially larger but can improve
+performance when the image needs to grow.
+.PP
+Specify what disk preallocation should be used, if any, when creating
+the system disk image by adding a line like this to your VM
+configuration.
+.IP \[bu] 2
+\f[V]preallocation=\[dq]metadata\[dq]\f[R]
+.SS CD-ROM disks
+.PP
+If you want to expose an ISO image from the host to guest add the
+following line to the VM configuration:
+.IP \[bu] 2
+\f[V]fixed_iso=\[dq]/path/to/image.iso\[dq]\f[R]
+.SS Floppy disks
+.PP
+If you\[cq]re like Alan Pope (https://popey.com) you\[cq]ll probably
+want to mount a floppy disk image in the guest.
+To do so add the following line to the VM configuration:
+.IP \[bu] 2
+\f[V]floppy=\[dq]/path/to/floppy.img\[dq]\f[R]
+.SH File Sharing
+.PP
+All File Sharing options will only expose \f[V]\[ti]/Public\f[R] (or
+localised variations) for the current user to the guest VMs.
+.SS Samba \[u1F427] \[u1F34F] \[u1FA9F]
+.PP
+If \f[V]smbd\f[R] is available on the host, Quickemu will automatically
+enable the built-in QEMU support for exposing a Samba share from the
+host to the guest.
+.PP
+You can install the minimal Samba components on Ubuntu using:
+.IP
+.nf
+\f[C]
+sudo apt install --no-install-recommends samba
+\f[R]
+.fi
+.PP
+If everything is set up correctly, the \f[V]smbd\f[R] address will be
+printed when the virtual machine is started.
+For example:
+.IP
+.nf
+\f[C]
+ - smbd:     On guest: smb://10.0.2.4/qemu
+\f[R]
+.fi
+.PP
+If using a Windows guest, right-click on \[lq]This PC\[rq], click
+\[lq]Add a network location\[rq], and paste this address, removing
+\f[V]smb:\f[R] and replacing forward slashes with backslashes (in this
+example \f[V]\[rs]\[rs]10.0.2.4\[rs]qemu\f[R]).
+.SS SPICE WebDAV \[u1F427] \[u1FA9F]
+.IP \[bu] 2
+TBD
+.SS VirtIO-9P \[u1F427] \[u1F34F]
+.IP \[bu] 2
+TBD
+.SH Network port forwarding
+.PP
+Add an additional line to your virtual machine configuration.
+For example:
+.IP \[bu] 2
+\f[V]port_forwards=(\[dq]8123:8123\[dq] \[dq]8888:80\[dq])\f[R]
+.PP
+In the example above:
+.IP \[bu] 2
+Port 8123 on the host is forwarded to port 8123 on the guest.
+.IP \[bu] 2
+Port 8888 on the host is forwarded to port 80 on the guest.
+.SH Disable networking
+.PP
+To completely disable all network interfaces in a guest VM add this
+additional line to your virtual machine configuration:
+.IP \[bu] 2
+\f[V]network=\[dq]none\[dq]\f[R]
+.SH Restricted networking
+.PP
+You can isolate the guest from the host (and broader network) using the
+restrict option, which will restrict networking to just the guest and
+any virtual devices.
+.PP
+This can be used to prevent software running inside the guest from
+phoning home while still providing a network inside the guest.
+Add this additional line to your virtual machine configuration:
+.IP \[bu] 2
+\f[V]network=\[dq]restrict\[dq]\f[R]
+.SH Bridged networking
+.PP
+Connect your virtual machine to a preconfigured network bridge.
+Add an additional line to your virtual machine configuration:
+.IP \[bu] 2
+\f[V]network=\[dq]br0\[dq]\f[R]
+.PP
+If you want to have a persistent MAC address for your bridged network
+interface in the guest VM you can add \f[V]macaddr\f[R] to the virtual
+machine configuration.
+QEMU requires that the MAC address is in the range:
+\f[B]52:54:00:AB:00:00 - 52:54:00:AB:FF:FF\f[R]
+.PP
+So you can generate your own MAC addresses with:
+.IP \[bu] 2
+\f[V]macaddr=\[dq]52:54:00:AB:51:AE\[dq]\f[R]
+.SH USB redirection
+.PP
+Quickemu supports USB redirection via SPICE pass-through and host
+pass-through.
+.SS SPICE redirection (recommended)
+.PP
+Using SPICE for USB pass-through is easiest as it doesn\[cq]t require
+any elevated permission, start Quickemu with \f[V]--display spice\f[R]
+and then select \f[V]Input\f[R] ->
+\f[V]Select USB Device for redirection\f[R] from the menu to choose
+which device(s) you want to attach to the guest.
+.SS Host redirection \f[B]NOT Recommended\f[R]
+.PP
+\f[B]USB host redirection is not recommended\f[R], it is provided purely
+for backwards compatibility to older versions of Quickemu.
+Using SPICE is preferred, see above.
+.PP
+Add an additional line to your virtual machine configuration.
+For example:
+.IP \[bu] 2
+\f[V]usb_devices=(\[dq]046d:082d\[dq] \[dq]046d:085e\[dq])\f[R]
+.PP
+In the example above:
+.IP \[bu] 2
+The USB device with vendor_id 046d and product_id 082d will be exposed
+to the guest.
+.IP \[bu] 2
+The USB device with vendor_id 046d and product_id 085e will be exposed
+to the guest.
+.PP
+If the USB devices are not writable, \f[V]quickemu\f[R] will display the
+appropriate commands to modify the USB device(s) access permissions,
+like this:
+.IP
+.nf
+\f[C]
+ - USB:      Host pass-through requested:
+              - Sennheiser Communications EPOS GTW 270 on bus 001 device 005 needs permission changes:
+                sudo chown -v root:user /dev/bus/usb/001/005
+                ERROR! USB permission changes are required \[u1F446]
+\f[R]
+.fi
+.SH TPM
+.PP
+Since Quickemu 2.2.0 a software emulated TPM device can be added to
+guest virtual machines.
+Just add \f[V]tpm=\[dq]on\[dq]\f[R] to your VM configuration.
+\f[V]quickget\f[R] will automatically add this line to Windows 11
+virtual machines.
+.SH AUTHORS
+.PP
+Written by Martin Wimpress.
+.SH BUGS
+.PP
+Submit bug reports online at:
+<https://github.com/quickemu-project/quickemu/issues>
+.SH SEE ALSO
+.PP
+Full sources at: <https://github.com/quickemu-project/quickemu>
+.PP
+quickget(1), quickemu(1), quickgui(1)
+.SH AUTHORS
+Martin Wimpress.