qvm-prefs.rst 8.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240
  1. .. program:: qvm-prefs
  2. :program:`qvm-prefs` -- List/set various per-VM properties
  3. ==========================================================
  4. Synopsis
  5. --------
  6. :command:`qvm-prefs` qvm-prefs [-h] [--xml *XMLFILE*] [--verbose] [--quiet] [--force-root] [--help-properties] *VMNAME* [*PROPERTY* [*VALUE*\|--delete]]
  7. Options
  8. -------
  9. .. option:: --help, -h
  10. Show help message and exit.
  11. .. option:: --help-properties
  12. List available properties with short descriptions and exit.
  13. .. option:: --xml=XMLFILE
  14. Qubes OS store file.
  15. .. option:: --verbose, -v
  16. Increase verbosity.
  17. .. option:: --quiet, -q
  18. Decrease verbosity.
  19. .. option:: --force-root
  20. Force to run as root.
  21. .. option:: --unset, --default, --delete, -D
  22. Unset the property. If is has default value, it will be used instead.
  23. Common properties
  24. =================
  25. This list is non-exhaustive. For authoritative listing, see
  26. :option:`--help-properties` and documentation of the source code.
  27. .. warning::
  28. This list is from the core2. It is wrong in many cases, some of them obvious,
  29. some of them not.
  30. include_in_backups
  31. Accepted values: ``True``, ``False``
  32. Control whenever this VM will be included in backups by default (for now
  33. works only in qubes-manager). You can always manually select or deselect
  34. any VM for backup.
  35. pcidevs
  36. PCI devices assigned to the VM. Should be edited using
  37. :manpage:`qvm-pci(1)` tool.
  38. pci_strictreset
  39. Accepted values: ``True``, ``False``
  40. Control whether prevent assigning to VM a device which does not support any
  41. reset method. Generally such devices should not be assigned to any VM,
  42. because there will be no way to reset device state after VM shutdown, so
  43. the device could attack next VM to which it will be assigned. But in some
  44. cases it could make sense - for example when the VM to which it is assigned
  45. is trusted one, or is running all the time.
  46. label
  47. Accepted values: ``red``, ``orange``, ``yellow``, ``green``, ``gray``,
  48. ``blue``, ``purple``, ``black``
  49. Color of VM label (icon, appmenus, windows border). If VM is running,
  50. change will be applied at first VM restart.
  51. netvm
  52. Accepted values: netvm name, ``default``, ``none``
  53. To which NetVM connect. Setting to ``default`` will follow system-global
  54. default NetVM (managed by qubes-prefs). Setting to ``none`` will disable
  55. networking in this VM.
  56. .. note::
  57. When setting to ``none``, firewall will be set to block all traffic -
  58. it will be used by DispVM started from this VM. Setting back to some
  59. NetVM will *NOT* restore previous firewall settings.
  60. dispvm_netvm
  61. Accepted values: netvm name, ``default``, ``none``
  62. Which NetVM should be used for Disposable VMs started by this one. ``default`` is to use the same NetVM as the VM itself.
  63. maxmem
  64. Accepted values: memory size in MB
  65. Maximum memory size available for this VM. Dynamic memory management (aka
  66. qmemman) will not be able to balloon over this limit. For VMs with qmemman
  67. disabled, this will be overridden by *memory* property (at VM startup).
  68. memory
  69. Accepted values: memory size in MB
  70. Initial memory size for VM. This should be large enough to allow VM startup
  71. - before qmemman starts managing memory for this VM. For VM with qmemman
  72. disabled, this is static memory size.
  73. kernel
  74. Accepted values: kernel version, ``default``, ``none``
  75. Kernel version to use (only for PV VMs). Available kernel versions will be
  76. listed when no value given (there are in
  77. :file:`/var/lib/qubes/vm-kernels`). Setting to ``default`` will follow
  78. system-global default kernel (managed via qubes-prefs). Setting to ``none``
  79. will use "kernels" subdir in VM directory - this allows having VM-specific
  80. kernel; also this the only case when :file:`/lib/modules` is writable from
  81. within VM.
  82. template
  83. Accepted values: TemplateVM name
  84. TemplateVM on which VM base. It can be changed only when VM isn't running.
  85. vcpus
  86. Accepted values: no of CPUs
  87. Number of CPU (cores) available to VM. Some VM types (eg DispVM) will not
  88. work properly with more than one CPU.
  89. kernelopts
  90. Accepted values: string, ``default``
  91. VM kernel parameters (available only for PV VMs). This can be used to
  92. workaround some hardware specific problems (eg for NetVM). Setting to
  93. ``default`` will use some reasonable defaults (currently different for VMs
  94. with PCI devices and without). Some helpful options (for debugging
  95. purposes): ``earlyprintk=xen``, ``init=/bin/bash``
  96. name
  97. Accepted values: alphanumerical name
  98. Name of the VM. Can be only changed when VM isn't running.
  99. drive
  100. Accepted values: [hd:\|cdrom:][backend-vm:]\ *path*
  101. Additional drive for the VM (available only for HVMs). This can be used to
  102. attach installation image. ``path`` can be file or physical device (eg.
  103. :file:`/dev/sr0`). The same syntax can be used in :option:`qvm-start
  104. --drive` - to attach drive only temporarily.
  105. mac
  106. Accepted values: MAC address, ``auto``
  107. Can be used to force specific of virtual ethernet card in the VM. Setting
  108. to ``auto`` will use automatic-generated MAC - based on VM id. Especially
  109. useful when some licencing depending on static MAC address.
  110. For template-based HVM ``auto`` mode means to clone template MAC.
  111. default_user
  112. Accepted values: username
  113. Default user used by :manpage:`qvm-run(1)`. Note that it make sense only on
  114. non-standard template, as the standard one always have "user" account.
  115. debug
  116. Accepted values: ``on``, ``off``
  117. Enables debug mode for VM. This can be used to turn on/off verbose logging
  118. in many qubes components at once (gui virtualization, VM kernel, some other
  119. services).
  120. For template-based HVM, enabling debug mode also disables automatic reset
  121. :file:`root.img` (actually :file:`volatile.img`) before each VM startup, so
  122. changes made to root filesystem stays intact. To force reset
  123. :file:`root.img` when debug mode enabled, either change something in the
  124. template (simple start+stop will do, even touch its root.img is enough), or
  125. remove VM's :file:`volatile.img` (check the path with
  126. :manpage:`qvm-prefs(1)`).
  127. qrexec_installed
  128. Accepted values: ``True``, ``False``
  129. This HVM have qrexec agent installed. When VM have qrexec agent installed,
  130. one can use qvm-run to start VM process, VM will benefit from Qubes RPC
  131. services (like file copy, or inter-vm clipboard). This option will be
  132. automatically turned on during Qubes Windows Tools installation, but if you
  133. install qrexec agent in some other OS, you need to turn this option on
  134. manually.
  135. guiagent_installed
  136. Accepted values: ``True``, ``False``
  137. This HVM have gui agent installed. This option disables full screen GUI
  138. virtualization and enables per-window seamless GUI mode. This option will
  139. be automatically turned on during Qubes Windows Tools installation, but if
  140. you install qubes gui agent in some other OS, you need to turn this option
  141. on manually. You can turn this option off to troubleshoot some early HVM OS
  142. boot problems (enter safe mode etc), but the option will be automatically
  143. enabled at first VM normal startup (and will take effect from the next
  144. startup).
  145. .. note::
  146. when Windows GUI agent is installed in the VM, SVGA device (used to
  147. full screen video) is disabled, so even if you disable this option, you
  148. will not get functional full desktop access (on normal VM startup). Use
  149. some other means for that (VNC, RDP or so).
  150. autostart
  151. Accepted values: ``True``, ``False``
  152. Start the VM during system startup. The default netvm is autostarted
  153. regardless of this setting.
  154. timezone
  155. Accepted values: ``localtime``, time offset in seconds
  156. Set emulated HVM clock timezone. Use ``localtime`` (the default) to use the
  157. same time as dom0 have. Note that HVM will get only clock value, not the
  158. timezone itself, so if you use ``localtime`` setting, OS inside of HVM
  159. should also be configured to treat hardware clock as local time (and have
  160. proper timezone set).
  161. Authors
  162. -------
  163. | Joanna Rutkowska <joanna at invisiblethingslab dot com>
  164. | Rafal Wojtczuk <rafal at invisiblethingslab dot com>
  165. | Marek Marczykowski <marmarek at invisiblethingslab dot com>
  166. | Wojtek Porczyk <woju at invisiblethingslab dot com>
  167. .. vim: ts=3 sw=3 et tw=80