qvm-prefs.rst 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239
  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] [--verbose] [--quiet] [--force-root] [--help-properties] *VMNAME* [*PROPERTY* [*VALUE* \| --default ]]
  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:: --hide-default
  14. Do not show properties that are set to the default value.
  15. .. option:: --verbose, -v
  16. Increase verbosity.
  17. .. option:: --quiet, -q
  18. Decrease verbosity.
  19. .. option:: --default, -D
  20. Reset property to its default value.
  21. .. option:: --get, -g
  22. Ignored; for compatibility with older scripts.
  23. .. option:: --set, -s
  24. Ignored; for compatibility with older scripts.
  25. Property values
  26. ===============
  27. Some properties may have strict type, here is description of available values.
  28. bool
  29. ----
  30. Accepted values for true: ``True``, ``true``, ``on``, ``1``
  31. Accepted values for false: ``False``, ``false``, ``off``, ``0``
  32. For example to enable debug mode, use: ``qvm-prefs vmname debug on``
  33. VM
  34. --
  35. Reference to a VM can be either a VM name, or empty string for no VM (remember
  36. to quote it, empty string is not the same as lack of argument!).
  37. For example to change netvm to sys-whonix, use: ``qvm-prefs vmname netvm
  38. sys-whonix``. Or to make VM offline, use: ``qvm-prefs vmname netvm ""``.
  39. Common properties
  40. =================
  41. This list is non-exhaustive. For authoritative listing, see
  42. :option:`--help-properties` and documentation of the source code.
  43. autostart
  44. Property type: bool
  45. Start the VM during system startup. The default netvm is autostarted
  46. regardless of this setting.
  47. debug
  48. Property type: bool
  49. Enables debug mode for VM. This can be used to turn on/off verbose logging
  50. in many Qubes components at once (gui virtualization, VM kernel, some other
  51. services). Also, for HVM, this will show VGA output, regardless of GUI agent
  52. being installed or not.
  53. default_dispvm
  54. Property type: VM
  55. Which Disposable VMs should be userd when requested by this VM, by default.
  56. VM may request different DispVM, if qrexec policy allows that.
  57. default_user
  58. Accepted values: username
  59. Default user used by :manpage:`qvm-run(1)`. Note that it make sense only on
  60. non-standard template, as the standard one always have "user" account.
  61. TemplateBasedVM use its template's value as a default.
  62. dispvm_allowed
  63. Property type: bool
  64. Allow to use this VM as a base AppVM for Disposable VM. I.e. start this
  65. AppVM as Disposable VM.
  66. include_in_backups
  67. Property type: bool
  68. Control whenever this VM will be included in backups by default (for now
  69. works only in qubes-manager). You can always manually select or
  70. deselect any VM for backup.
  71. ip
  72. Accepted values: valid IPv4 address
  73. IP address of this VM, used for inter-vm communication.
  74. kernel
  75. Accepted values: kernel version, empty
  76. Kernel version to use. Setting to empty value will use bootloader installed
  77. in root volume (of VM's template) - available only for HVM.
  78. TemplateBasedVM use its template's value as a default.
  79. kernelopts
  80. Accepted values: string
  81. VM kernel parameters (available only for PV VMs). This can be used to
  82. workaround some hardware specific problems (eg for NetVM). For VM without
  83. PCI devices default means inherit this value from the VM template (if any).
  84. Some helpful options (for debugging purposes): ``earlyprintk=xen``,
  85. ``init=/bin/bash``
  86. TemplateBasedVM use its template's value as a default.
  87. label
  88. Accepted values: ``red``, ``orange``, ``yellow``, ``green``, ``gray``,
  89. ``blue``, ``purple``, ``black``
  90. Color of VM label (icon, appmenus, windows border). If VM is running,
  91. change will be applied at first VM restart.
  92. mac
  93. Accepted values: MAC address, ``auto``
  94. Can be used to force specific of virtual ethernet card in the VM. Setting
  95. to ``auto`` will use automatic-generated MAC - based on VM id. Especially
  96. useful when licensing requires a static MAC address.
  97. For template-based HVM ``auto`` mode means to clone template MAC.
  98. maxmem
  99. Accepted values: memory size in MB
  100. Maximum memory size available for this VM. Dynamic memory management (aka
  101. qmemman) will not be able to balloon over this limit. For VMs with
  102. qmemman disabled, this will be overridden by *memory* property (at VM
  103. startup).
  104. TemplateBasedVM use its template's value as a default.
  105. memory
  106. Accepted values: memory size in MB
  107. Initial memory size for VM. This should be large enough to allow VM startup
  108. - before qmemman starts managing memory for this VM. For VM with qmemman
  109. disabled, this is static memory size.
  110. TemplateBasedVM use its template's value as a default.
  111. name
  112. Accepted values: alphanumerical name
  113. Name of the VM. Cannot be changed.
  114. netvm
  115. Property type: VM
  116. To which NetVM connect. Default value (`--default` option) will follow
  117. system-global default NetVM (managed by qubes-prefs). Setting to empty name
  118. will disable networking in this VM.
  119. provides_network
  120. Property type: bool
  121. Should this VM provide network to other VMs. Setting this property to
  122. ``True`` will allow to set this VM as ``netvm`` to other VMs.
  123. qrexec_timeout
  124. Accepted values: timeout in seconds
  125. How log to wait for VM boot and qrexec agent connection. After this timeout,
  126. if qrexec agent is still not connected, VM is forcefully shut down.
  127. Ignored if qrexec not installed at all (`qrexec` feature not set, see
  128. :manpage:`qvm-features(1)`).
  129. TemplateBasedVM use its template's value as a default.
  130. stubdom_mem
  131. Accepted values: memory in MB
  132. Amount of memory to allocate to stubdomain. By default let Xen choose
  133. sensible value. This property is mostly for debugging early stubdomain
  134. implementations and may be removed in the future, without notice.
  135. template
  136. Property type: VM
  137. TemplateVM on which VM base. It can be changed only when VM isn't running.
  138. vcpus
  139. Accepted values: no of CPUs
  140. Number of CPU (cores) available to VM. Some VM types (eg DispVM) will not
  141. work properly with more than one CPU.
  142. TemplateBasedVM use its template's value as a default.
  143. virt_mode
  144. Accepted values: ``hvm``, ``pv``
  145. Virtualisation mode in VM should be started. ``hvm`` allow to install
  146. operating system without Xen-specific integration.
  147. TemplateBasedVM use its template's value as a default.
  148. Authors
  149. -------
  150. | Joanna Rutkowska <joanna at invisiblethingslab dot com>
  151. | Rafal Wojtczuk <rafal at invisiblethingslab dot com>
  152. | Marek Marczykowski <marmarek at invisiblethingslab dot com>
  153. | Wojtek Porczyk <woju at invisiblethingslab dot com>
  154. .. vim: ts=3 sw=3 et tw=80