doc: update list of properties in qvm-prefs/qubes-prefs man pages
Fixes QubesOS/qubes-issues#3011
This commit is contained in:
parent
a260685bd1
commit
f7b31a005e
@ -46,17 +46,45 @@ Common properties
|
|||||||
This list is non-exhaustive. For authoritative listing, see
|
This list is non-exhaustive. For authoritative listing, see
|
||||||
:option:`--help-properties` and documentation of the source code.
|
: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,
|
Qube used as a time source for dom0
|
||||||
some of them not.
|
|
||||||
|
|
||||||
- clock VM
|
default_template
|
||||||
- update VM
|
|
||||||
- default template
|
Default template for newly created qubes
|
||||||
- default firewallVM
|
|
||||||
- default kernel
|
default_fw_netvm
|
||||||
- default 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
|
Authors
|
||||||
-------
|
-------
|
||||||
|
@ -40,44 +40,93 @@ Options
|
|||||||
Ignored; for compatibility with older scripts.
|
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
|
Common properties
|
||||||
=================
|
=================
|
||||||
|
|
||||||
This list is non-exhaustive. For authoritative listing, see
|
This list is non-exhaustive. For authoritative listing, see
|
||||||
:option:`--help-properties` and documentation of the source code.
|
: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,
|
Start the VM during system startup. The default netvm is autostarted
|
||||||
some of them not.
|
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
|
include_in_backups
|
||||||
Accepted values: ``True``, ``False``
|
Property type: bool
|
||||||
|
|
||||||
Control whenever this VM will be included in backups by default (for now
|
Control whenever this VM will be included in backups by default (for now
|
||||||
works only in qubes-manager). You can always manually select or
|
works only in qubes-manager). You can always manually select or
|
||||||
deselect any VM for backup.
|
deselect any VM for backup.
|
||||||
|
|
||||||
pcidevs
|
ip
|
||||||
PCI devices assigned to the VM. Should be edited using qvm-pci tool.
|
Accepted values: valid IPv4 address
|
||||||
|
|
||||||
pci_strictreset
|
IP address of this VM, used for inter-vm communication.
|
||||||
Accepted values: ``True``, ``False``
|
|
||||||
|
|
||||||
Control whether prevent assigning to VM a device which does not support any
|
kernel
|
||||||
reset method. Generally such devices should not be assigned to any VM,
|
Accepted values: kernel version, empty
|
||||||
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.
|
|
||||||
|
|
||||||
pci_e820_host
|
Kernel version to use. Setting to empty value will use bootloader installed
|
||||||
Accepted values: ``True``, ``False``
|
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
|
kernelopts
|
||||||
required for some devices to properly resolve conflicts in address space.
|
Accepted values: string
|
||||||
This option is enabled by default for VMs with PCI devices and have no
|
|
||||||
effect for VMs without devices.
|
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
|
label
|
||||||
Accepted values: ``red``, ``orange``, ``yellow``, ``green``, ``gray``,
|
Accepted values: ``red``, ``orange``, ``yellow``, ``green``, ``gray``,
|
||||||
@ -86,18 +135,13 @@ label
|
|||||||
Color of VM label (icon, appmenus, windows border). If VM is running,
|
Color of VM label (icon, appmenus, windows border). If VM is running,
|
||||||
change will be applied at first VM restart.
|
change will be applied at first VM restart.
|
||||||
|
|
||||||
netvm
|
mac
|
||||||
Accepted values: netvm name, ``default``, ``none``
|
Accepted values: MAC address, ``auto``
|
||||||
|
|
||||||
To which NetVM connect. Setting to ``default`` will follow system-global
|
Can be used to force specific of virtual ethernet card in the VM. Setting
|
||||||
default NetVM (managed by qubes-prefs). Setting to ``none`` will disable
|
to ``auto`` will use automatic-generated MAC - based on VM id. Especially
|
||||||
networking in this VM.
|
useful when licensing requires a static MAC address.
|
||||||
|
For template-based HVM ``auto`` mode means to clone template MAC.
|
||||||
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.
|
|
||||||
|
|
||||||
maxmem
|
maxmem
|
||||||
Accepted values: memory size in MB
|
Accepted values: memory size in MB
|
||||||
@ -114,18 +158,41 @@ memory
|
|||||||
- before qmemman starts managing memory for this VM. For VM with qmemman
|
- before qmemman starts managing memory for this VM. For VM with qmemman
|
||||||
disabled, this is static memory size.
|
disabled, this is static memory size.
|
||||||
|
|
||||||
kernel
|
name
|
||||||
Accepted values: kernel version, ``default``, ``none``
|
Accepted values: alphanumerical name
|
||||||
|
|
||||||
Kernel version to use (only for PV VMs). Available kernel versions will be
|
Name of the VM. Cannot be changed.
|
||||||
listed when no value given (there are in /var/lib/qubes/vm-kernels).
|
|
||||||
Setting to ``default`` will follow system-global default kernel (managed
|
netvm
|
||||||
via qubes-prefs). Setting to ``none`` will use "kernels" subdir in
|
Property type: VM
|
||||||
VM directory - this allows having VM-specific kernel; also this the only
|
|
||||||
case when /lib/modules is writable from within 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
|
template
|
||||||
Accepted values: TemplateVM name
|
Property type: VM
|
||||||
|
|
||||||
TemplateVM on which VM base. It can be changed only when VM isn't running.
|
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
|
Number of CPU (cores) available to VM. Some VM types (eg DispVM) will not
|
||||||
work properly with more than one CPU.
|
work properly with more than one CPU.
|
||||||
|
|
||||||
kernelopts
|
virt_mode
|
||||||
Accepted values: string, ``default``
|
Accepted values: ``hvm``, ``pv``
|
||||||
|
|
||||||
VM kernel parameters (available only for PV VMs). This can be used to
|
Virtualisation mode in VM should be started. ``hvm`` allow to install
|
||||||
workaround some hardware specific problems (eg for NetVM). Setting to
|
operating system without Xen-specific integration.
|
||||||
``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).
|
|
||||||
|
|
||||||
Authors
|
Authors
|
||||||
-------
|
-------
|
||||||
|
Loading…
Reference in New Issue
Block a user