qvm-template.rst 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497
  1. .. program:: qvm-template
  2. :program:`qvm-template` -- Manage template VMs
  3. ==============================================
  4. Synopsis
  5. --------
  6. :command:`qvm-template` [-h] [--repo-files *REPO_FILES*] [--keyring *KEYRING*] [--updatevm *UPDATEVM*] [--enablerepo *REPOID*] [--disablerepo *REPOID*] [--repoid *REPOID*] [--releasever *RELEASEVER*] [--refresh] [--cachedir *CACHEDIR*] [--yes] [--quiet] *SUBCOMMAND*
  7. See Section `Subcommands`_ for available subcommands.
  8. Options
  9. -------
  10. .. option:: --help, -h
  11. Show help message and exit.
  12. .. option:: --repo-files REPO_FILES
  13. Specify files containing DNF repository configuration. Can be
  14. used more than once. (default:
  15. ['/usr/share/qubes/repo-templates/qubes-templates.repo'])
  16. .. option:: --keyring KEYRING
  17. Specify directory containing RPM public keys. (default:
  18. /usr/share/qubes/repo-templates/keys)
  19. .. option:: --updatevm UPDATEVM
  20. Specify VM to download updates from. (Set to empty string to specify the
  21. current VM.) (default: same as UpdateVM - see ``qubes-prefs``)
  22. .. option:: --enablerepo REPOID
  23. Enable additional repositories by an id or a glob. Can be used more than
  24. once.
  25. .. option:: --disablerepo REPOID
  26. Disable certain repositories by an id or a glob. Can be used more than once.
  27. .. option:: --repoid REPOID
  28. Enable just specific repositories by an id or a glob. Can be used more than
  29. once.
  30. .. option:: --releasever RELEASEVER
  31. Override Qubes release version.
  32. .. option:: --refresh
  33. Set repository metadata as expired before running the command.
  34. .. option:: --cachedir CACHEDIR
  35. Specify cache directory. (default: ~/.cache/qvm-template)
  36. .. option:: --yes
  37. Assume "yes" to questions.
  38. .. option:: --quiet
  39. Decrease verbosity.
  40. Subcommands
  41. ===========
  42. install
  43. -------
  44. Install template packages.
  45. Synopsis
  46. ^^^^^^^^
  47. :command:`qvm-template install` [-h] [--pool *POOL*] [--nogpgcheck] [--allow-pv] [--downloaddir *DOWNLOADDIR*] [--retries *RETRIES*] [*TEMPLATESPEC* [*TEMPLATESPEC* ...]]
  48. See Section `Template Spec`_ for an explanation of *TEMPLATESPEC*.
  49. Options
  50. ^^^^^^^
  51. .. option:: -h, --help
  52. Show help message and exit.
  53. .. option:: --pool POOL
  54. Specify pool to store created VMs in.
  55. .. option:: --nogpgcheck
  56. Disable signature checks.
  57. .. option:: --allow-pv
  58. Allow templates that set virt_mode to pv.
  59. .. option:: --downloaddir DOWNLOADDIR
  60. Specify download directory. (default: .)
  61. .. option:: --retries RETRIES
  62. Specify maximum number of retries for downloads. (default: 5)
  63. {reinstall,downgrade,upgrade}
  64. -----------------------------
  65. Reinstall/downgrade/upgrade template packages.
  66. Synopsis
  67. ^^^^^^^^
  68. :command:`qvm-template {reinstall,downgrade,upgrade}` [-h] [--nogpgcheck] [--allow-pv] [--downloaddir *DOWNLOADDIR*] [--retries *RETRIES*] [*TEMPLATESPEC* [*TEMPLATESPEC* ...]]
  69. See Section `Template Spec`_ for an explanation of *TEMPLATESPEC*.
  70. Options
  71. ^^^^^^^
  72. .. option:: -h, --help
  73. Show help message and exit.
  74. .. option:: --nogpgcheck
  75. Disable signature checks.
  76. .. option:: --allow-pv
  77. Allow templates that set virt_mode to pv.
  78. .. option:: --downloaddir DOWNLOADDIR
  79. Specify download directory. (default: .)
  80. .. option:: --retries RETRIES
  81. Specify maximum number of retries for downloads. (default: 5)
  82. download
  83. --------
  84. Download template packages.
  85. Synopsis
  86. ^^^^^^^^
  87. :command:`qvm-template download` [-h] [--downloaddir *DOWNLOADDIR*] [--retries *RETRIES*] [*TEMPLATESPEC* [*TEMPLATESPEC* ...]]
  88. See Section `Template Spec`_ for an explanation of *TEMPLATESPEC*.
  89. Options
  90. ^^^^^^^
  91. .. option:: -h, --help
  92. Show help message and exit.
  93. .. option:: --downloaddir DOWNLOADDIR
  94. Specify download directory. (default: .)
  95. .. option:: --retries RETRIES
  96. Specify maximum number of retries for downloads. (default: 5)
  97. list
  98. ----
  99. List templates.
  100. Synopsis
  101. ^^^^^^^^
  102. :command:`qvm-template list` [-h] [--all] [--installed] [--available] [--extras] [--upgrades] [--machine-readable | --machine-readable-json] [*TEMPLATESPEC* [*TEMPLATESPEC* ...]]
  103. See Section `Template Spec`_ for an explanation of *TEMPLATESPEC*.
  104. Options
  105. ^^^^^^^
  106. .. option:: -h, --help
  107. Show help message and exit.
  108. .. option:: --all
  109. Show all templates (default).
  110. .. option:: --installed
  111. Show installed templates.
  112. .. option:: --available
  113. Show available templates.
  114. .. option:: --extras
  115. Show extras (e.g., ones that exist locally but not in repos)
  116. templates.
  117. .. option:: --upgrades
  118. Show available upgrades.
  119. .. option:: --machine-readable
  120. Enable machine-readable output.
  121. Format
  122. Each line describes a template in the following format:
  123. ::
  124. {status}|{name}|{evr}|{reponame}
  125. Where ``{status}`` can be one of ``installed``, ``available``,
  126. ``extra``, or ``upgradable``.
  127. The field ``{evr}`` contains version information in the form of
  128. ``{epoch}:{version}-{release}``.
  129. .. option:: --machine-readable-json
  130. Enable machine-readable output (JSON).
  131. Format
  132. The resulting JSON document is in the following format:
  133. ::
  134. {
  135. STATUS: [
  136. {
  137. "name": str,
  138. "evr": str,
  139. "reponame": str
  140. },
  141. ...
  142. ],
  143. ...
  144. }
  145. Where ``STATUS`` can be one of ``"installed"``, ``"available"``,
  146. ``"extra"``, or ``"upgradable"``.
  147. The fields ``buildtime`` and ``installtime`` are in ``%Y-%m-%d
  148. %H:%M:%S`` format in UTC.
  149. The field ``{evr}`` contains version information in the form of
  150. ``{epoch}:{version}-{release}``.
  151. info
  152. ----
  153. Display details about templates.
  154. Synopsis
  155. ^^^^^^^^
  156. :command:`qvm-template list` [-h] [--all] [--installed] [--available] [--extras] [--upgrades] [--machine-readable | --machine-readable-json] [*TEMPLATESPEC* [*TEMPLATESPEC* ...]]
  157. See Section `Template Spec`_ for an explanation of *TEMPLATESPEC*.
  158. Options
  159. ^^^^^^^
  160. .. option:: -h, --help
  161. Show help message and exit.
  162. .. option:: --all
  163. Show all templates (default).
  164. .. option:: --installed
  165. Show installed templates.
  166. .. option:: --available
  167. Show available templates.
  168. .. option:: --extras
  169. Show extras (e.g., ones that exist locally but not in repos)
  170. templates.
  171. .. option:: --upgrades
  172. Show available upgrades.
  173. .. option:: --machine-readable
  174. Enable machine-readable output.
  175. Format
  176. Each line describes a template in the following format:
  177. ::
  178. {status}|{name}|{epoch}|{version}|{release}|{reponame}|{size}|{buildtime}|{installtime}|{license}|{url}|{summary}|{description}
  179. Where ``{status}`` can be one of ``installed``, ``available``,
  180. ``extra``, or ``upgradable``.
  181. The fields ``buildtime`` and ``installtime`` are in ``%Y-%m-%d
  182. %H:%M:%S`` format in UTC.
  183. Newlines in the ``{description}`` field are replaced with pipe
  184. characters (``|``) for easier processing.
  185. .. option:: --machine-readable-json
  186. Enable machine-readable output (JSON).
  187. Format
  188. The resulting JSON document is in the following format:
  189. ::
  190. {
  191. STATUS: [
  192. {
  193. "name": str,
  194. "epoch": str,
  195. "version": str,
  196. "release": str,
  197. "reponame": str,
  198. "size": int,
  199. "buildtime": str,
  200. "installtime": str,
  201. "license": str,
  202. "url": str,
  203. "summary": str,
  204. "description": str
  205. },
  206. ...
  207. ],
  208. ...
  209. }
  210. Where ``STATUS`` can be one of ``"installed"``, ``"available"``,
  211. ``"extra"``, or ``"upgradable"``.
  212. The fields ``buildtime`` and ``installtime`` are in ``%Y-%m-%d
  213. %H:%M:%S`` format in UTC.
  214. search
  215. ------
  216. Search template details for the given string.
  217. Synopsis
  218. ^^^^^^^^
  219. :command:`qvm-template search` [-h] [--all] [*PATTERN* [*PATTERN* ...]]
  220. Options
  221. ^^^^^^^
  222. .. option:: -h, --help
  223. Show help message and exit.
  224. .. option:: --all
  225. Search also in the template description and URL. In addition, the criterion
  226. are evaluated with OR instead of AND.
  227. remove
  228. ------
  229. Remove installed templates.
  230. Synopsis
  231. ^^^^^^^^
  232. :command:`qvm-template remove` [-h] [--disassoc] [*TEMPLATE* [*TEMPLATE* ...]]
  233. Options
  234. ^^^^^^^
  235. .. option:: -h, --help
  236. Show help message and exit.
  237. .. option:: --disassoc
  238. Also disassociate VMs from the templates to be removed. This
  239. creates a *dummy* template for the VMs to link with.
  240. purge
  241. -----
  242. Remove installed templates and associated VMs.
  243. Synopsis
  244. ^^^^^^^^
  245. :command:`qvm-template purge` [-h] [*TEMPLATE* [*TEMPLATE* ...]]
  246. Options
  247. ^^^^^^^
  248. .. option:: -h, --help
  249. Show help message and exit.
  250. clean
  251. -----
  252. Remove locally cached packages.
  253. Synopsis
  254. ^^^^^^^^
  255. :command:`qvm-template clean` [-h]
  256. Options
  257. ^^^^^^^
  258. .. option:: -h, --help
  259. Show help message and exit.
  260. repolist
  261. --------
  262. Show configured repositories.
  263. Synopsis
  264. ^^^^^^^^
  265. :command:`qvm-template repolist` [-h] [--all | --enabled | --disabled] [*REPOS* [*REPOS* ...]]
  266. Options
  267. ^^^^^^^
  268. .. option:: -h, --help
  269. Show help message and exit.
  270. .. option:: --all
  271. Show all repos.
  272. .. option:: --enabled
  273. Show only enabled repos (default).
  274. .. option:: --disabled
  275. Show only disabled repos.
  276. Template Spec
  277. -------------
  278. Subcommands such as ``install`` and ``download`` accept one or more
  279. *TEMPLATESPEC* strings. The format is, in essence, almost identical to
  280. ``<package-name-spec>`` described in the DNF documentation.
  281. In short, the spec is matched against the following list of NEVRA forms, in
  282. decreasing orders of priority:
  283. * ``name-[epoch:]version-release``
  284. * ``name``
  285. * ``name-[epoch:]version``
  286. Note that unlike DNF, ``arch`` is currently ignored as the template packages
  287. should all be of ``noarch``.
  288. One can also use globs in spec strings. See Section `Globs`_ for details.
  289. Refer to Section *NEVRA Matching* in the DNF documentation for details.
  290. Globs
  291. -----
  292. `Template Spec`_ strings, repo ids, and search patterns support glob pattern
  293. matching. In particular, the following special characters can be used:
  294. * ``*``: Matches any number of characters.
  295. * ``?``: Matches exactly one character.
  296. * ``[]``: Matches any enclosed character.
  297. * ``[!]``: Matches any character except those enclosed.
  298. In particular, note that ``{}``, while supported by DNF, is not supported by
  299. `qvm-template`.