Qubes/core-admin-client
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

doc: update list of properties in qvm-prefs/qubes-prefs man pages

Browse Source 
Fixes QubesOS/qubes-issues#3011
This commit is contained in:
Marek Marczykowski-Górecki 2017-08-12 22:37:59 +02:00
parent a260685bd1
commit f7b31a005e
No known key found for this signature in database
GPG Key ID: 063938BA42CFA724
2 changed files with 148 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
doc/manpages/qubes-prefs.rst
View File

@ -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
------- -------

246
doc/manpages/qvm-prefs.rst
View File

@ -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
------- -------