qvm-prefs.rst 7.8 KB

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