From f7b31a005e68d48e7455e570a2fd60a233a3fdc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sat, 12 Aug 2017 22:37:59 +0200 Subject: [PATCH] doc: update list of properties in qvm-prefs/qubes-prefs man pages Fixes QubesOS/qubes-issues#3011 --- doc/manpages/qubes-prefs.rst | 46 +++++-- doc/manpages/qvm-prefs.rst | 246 ++++++++++++++++------------------- 2 files changed, 148 insertions(+), 144 deletions(-) diff --git a/doc/manpages/qubes-prefs.rst b/doc/manpages/qubes-prefs.rst index afaf753..803b1b1 100644 --- a/doc/manpages/qubes-prefs.rst +++ b/doc/manpages/qubes-prefs.rst @@ -46,17 +46,45 @@ Common properties This list is non-exhaustive. For authoritative listing, see :option:`--help-properties` and documentation of the source code. -.. warning:: +clockvm - This list is from the core2. It is wrong in many cases, some of them obvious, - some of them not. + Qube used as a time source for dom0 -- clock VM -- update VM -- default template -- default firewallVM -- default kernel -- default netVM +default_template + + Default template for newly created qubes + +default_fw_netvm + + Default netvm for qubes providing network (with `provides_network` property + set to `True`). + +default_netvm + + Default netvm for qubes not providing network + +default_kernel + + Default value for `kernel` property, see :manpage:`qvm-prefs(1)` for + details. + +default_pool + + Default storage pool for new qubes. + +default_pool_kernel, default_pool_private, default_pool_root, default_pool_volatile + + Default storage pool for particular volume for new qubes. Defaults to value + of `default_pool`. + +stats_interval + + Interval (in seconds) at which VM statistics are sent. This is for example + used by domains widget - this often memory usage will be refreshed. + +updatevm + + Qube used to download dom0 updates Authors ------- diff --git a/doc/manpages/qvm-prefs.rst b/doc/manpages/qvm-prefs.rst index 304f872..860c557 100644 --- a/doc/manpages/qvm-prefs.rst +++ b/doc/manpages/qvm-prefs.rst @@ -40,44 +40,93 @@ Options Ignored; for compatibility with older scripts. +Property values +=============== + +Some properties may have strict type, here is description of available values. + +bool +---- + +Accepted values for true: ``True``, ``true``, ``on``, ``1`` +Accepted values for false: ``False``, ``false``, ``off``, ``0`` + +For example to enable debug mode, use: ``qvm-prefs vmname debug on`` + +VM +-- + +Reference to a VM can be either a VM name, or empty string for no VM (remember +to quote it, empty string is not the same as lack of argument!). + +For example to change netvm to sys-whonix, use: ``qvm-prefs vmname netvm +sys-whonix``. Or to make VM offline, use: ``qvm-prefs vmname netvm ""``. + + Common properties ================= This list is non-exhaustive. For authoritative listing, see :option:`--help-properties` and documentation of the source code. -.. warning:: +autostart + Property type: bool - This list is from the core2. It is wrong in many cases, some of them obvious, - some of them not. + Start the VM during system startup. The default netvm is autostarted + regardless of this setting. + +debug + Property type: bool + + Enables debug mode for VM. This can be used to turn on/off verbose logging + in many Qubes components at once (gui virtualization, VM kernel, some other + services). Also, for HVM, this will show VGA output, regardless of GUI agent + being installed or not. + +default_dispvm + Property type: VM + + Which Disposable VMs should be userd when requested by this VM, by default. + VM may request different DispVM, if qrexec policy allows that. + +default_user + Accepted values: username + + Default user used by :manpage:`qvm-run(1)`. Note that it make sense only on + non-standard template, as the standard one always have "user" account. + +dispvm_allowed + Property type: bool + + Allow to use this VM as a base AppVM for Disposable VM. I.e. start this + AppVM as Disposable VM. include_in_backups - Accepted values: ``True``, ``False`` + Property type: bool Control whenever this VM will be included in backups by default (for now works only in qubes-manager). You can always manually select or deselect any VM for backup. -pcidevs - PCI devices assigned to the VM. Should be edited using qvm-pci tool. +ip + Accepted values: valid IPv4 address -pci_strictreset - Accepted values: ``True``, ``False`` + IP address of this VM, used for inter-vm communication. - Control whether prevent assigning to VM a device which does not support any - reset method. Generally such devices should not be assigned to any VM, - because there will be no way to reset device state after VM shutdown, so - the device could attack next VM to which it will be assigned. But in some - cases it could make sense - for example when the VM to which it is assigned - is trusted one, or is running all the time. +kernel + Accepted values: kernel version, empty -pci_e820_host - Accepted values: ``True``, ``False`` + Kernel version to use. Setting to empty value will use bootloader installed + in root volume (of VM's template) - available only for HVM - Give VM with PCI devices a memory map (e820) of the host. This is - required for some devices to properly resolve conflicts in address space. - This option is enabled by default for VMs with PCI devices and have no - effect for VMs without devices. +kernelopts + Accepted values: string + + VM kernel parameters (available only for PV VMs). This can be used to + workaround some hardware specific problems (eg for NetVM). For VM without + PCI devices default means inherit this value from the VM template (if any). + Some helpful options (for debugging purposes): ``earlyprintk=xen``, + ``init=/bin/bash`` label Accepted values: ``red``, ``orange``, ``yellow``, ``green``, ``gray``, @@ -86,18 +135,13 @@ label Color of VM label (icon, appmenus, windows border). If VM is running, change will be applied at first VM restart. -netvm - Accepted values: netvm name, ``default``, ``none`` +mac + Accepted values: MAC address, ``auto`` - To which NetVM connect. Setting to ``default`` will follow system-global - default NetVM (managed by qubes-prefs). Setting to ``none`` will disable - networking in this VM. - -dispvm_netvm - Accepted values: netvm name, ``default``, ``none`` - - Which NetVM should be used for Disposable VMs started by this one. - ``default`` is to use the same NetVM as the VM itself. + Can be used to force specific of virtual ethernet card in the VM. Setting + to ``auto`` will use automatic-generated MAC - based on VM id. Especially + useful when licensing requires a static MAC address. + For template-based HVM ``auto`` mode means to clone template MAC. maxmem Accepted values: memory size in MB @@ -114,18 +158,41 @@ memory - before qmemman starts managing memory for this VM. For VM with qmemman disabled, this is static memory size. -kernel - Accepted values: kernel version, ``default``, ``none`` +name + Accepted values: alphanumerical name - Kernel version to use (only for PV VMs). Available kernel versions will be - listed when no value given (there are in /var/lib/qubes/vm-kernels). - Setting to ``default`` will follow system-global default kernel (managed - via qubes-prefs). Setting to ``none`` will use "kernels" subdir in - VM directory - this allows having VM-specific kernel; also this the only - case when /lib/modules is writable from within VM. + Name of the VM. Cannot be changed. + +netvm + Property type: VM + + To which NetVM connect. Default value (`--default` option) will follow + system-global default NetVM (managed by qubes-prefs). Setting to empty name + will disable networking in this VM. + +provides_network + Property type: bool + + Should this VM provide network to other VMs. Setting this property to + ``True`` will allow to set this VM as ``netvm`` to other VMs. + +qrexec_timeout + Accepted values: timeout in seconds + + How log to wait for VM boot and qrexec agent connection. After this timeout, + if qrexec agent is still not connected, VM is forcefully shut down. + Ignored if qrexec not installed at all (`qrexec` feature not set, see + :manpage:`qvm-features(1)`). + +stubdom_mem + Accepted values: memory in MB + + Amount of memory to allocate to stubdomain. By default let Xen choose + sensible value. This property is mostly for debugging early stubdomain + implementations and may be removed in the future, without notice. template - Accepted values: TemplateVM name + Property type: VM TemplateVM on which VM base. It can be changed only when VM isn't running. @@ -135,102 +202,11 @@ vcpus Number of CPU (cores) available to VM. Some VM types (eg DispVM) will not work properly with more than one CPU. -kernelopts - Accepted values: string, ``default`` +virt_mode + Accepted values: ``hvm``, ``pv`` - VM kernel parameters (available only for PV VMs). This can be used to - workaround some hardware specific problems (eg for NetVM). Setting to - ``default`` will use some reasonable defaults (currently different for VMs - with PCI devices and without). For VM without PCI devices - ``default`` option means inherit this value from the VM template (if any). - Some helpful options (for debugging purposes): ``earlyprintk=xen``, - ``init=/bin/bash`` - -name - Accepted values: alphanumerical name - - Name of the VM. Can be only changed when VM isn't running. - -drive - Accepted values: [hd:\|cdrom:][backend-vm:]path - - Additional drive for the VM (available only for HVMs). This can be used to - attach installation image. ``path`` can be file or physical device (eg. - :file:`/dev/sr0`). The same syntax can be used in - :option:`qvm-start --drive` - to attach drive only temporarily. - -mac - Accepted values: MAC address, ``auto`` - - Can be used to force specific of virtual ethernet card in the VM. Setting - to ``auto`` will use automatic-generated MAC - based on VM id. Especially - useful when licensing requires a static MAC address. - For template-based HVM ``auto`` mode means to clone template MAC. - -default_user - Accepted values: username - - Default user used by :manpage:`qvm-run(1)`. Note that it make sense only on - non-standard template, as the standard one always have "user" account. - -debug - Accepted values: ``on``, ``off`` - - Enables debug mode for VM. This can be used to turn on/off verbose logging - in many Qubes components at once (gui virtualization, VM kernel, some other - services). - - For template-based HVM, enabling debug mode also disables automatic reset - :file:`root.img` (actually :file:`volatile.img`) before each VM startup, so - changes made to root filesystem stays intact. To force reset - :file:`root.img` when debug mode enabled, either change something in the - template (simple start+stop will do, even touch its :file:`root.img` is - enough), or remove VM's :file:`volatile.img` (check the path with - :manpage:`qvm-prefs(1)`). - -qrexec_installed - Accepted values: ``True``, ``False`` - - This HVM have qrexec agent installed. When VM have qrexec agent installed, - one can use qvm-run to start VM process, VM will benefit from Qubes RPC - services (like file copy, or inter-vm clipboard). This option will be - automatically turned on during Qubes Windows Tools installation, but if you - install qrexec agent in some other OS, you need to turn this option on - manually. - -guiagent_installed - Accepted values: ``True``, ``False`` - - This HVM have gui agent installed. This option disables full screen GUI - virtualization and enables per-window seemless GUI mode. This option will - be automatically turned on during Qubes Windows Tools installation, but if - you install Qubes gui agent in some other OS, you need to turn this option - on manually. You can turn this option off to troubleshoot some early HVM OS - boot problems (enter safe mode etc), but the option will be automatically - enabled at first VM normal startup (and will take effect from the next - startup). - - .. note:: - - when Windows GUI agent is installed in the VM, SVGA device (used to - full screen video) is disabled, so even if you disable this option, you - will not get functional full desktop access (on normal VM startup). Use - some other means for that (VNC, RDP or so). - -autostart - Accepted values: ``True``, ``False`` - - Start the VM during system startup. The default netvm is autostarted - regardless of this setting. - -timezone - Accepted values: ``localtime``, time offset in seconds - - Set emulated HVM clock timezone. Use ``localtime`` (the default) to use the - same time as dom0 have. Note that HVM will get only clock value, not the - timezone itself, so if you use ``localtime`` setting, OS inside of HVM - should also be configured to treat hardware clock as local time (and have - proper timezone set). + Virtualisation mode in VM should be started. ``hvm`` allow to install + operating system without Xen-specific integration. Authors -------