.. program:: qvm-template
:program:`qvm-template` -- Manage template VMs
==============================================
Synopsis
--------
: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*
See Section `Subcommands`_ for available subcommands.
Options
-------
.. option:: --help, -h
Show help message and exit.
.. option:: --repo-files REPO_FILES
Specify files containing DNF repository configuration. Can be
used more than once. (default:
['/usr/share/qubes/repo-templates/qubes-templates.repo'])
.. option:: --keyring KEYRING
Specify directory containing RPM public keys. (default:
/usr/share/qubes/repo-templates/keys)
.. option:: --updatevm UPDATEVM
Specify VM to download updates from. (Set to empty string to specify the
current VM.) (default: same as UpdateVM - see ``qubes-prefs``)
.. option:: --enablerepo REPOID
Enable additional repositories by an id or a glob. Can be used more than
once.
.. option:: --disablerepo REPOID
Disable certain repositories by an id or a glob. Can be used more than once.
.. option:: --repoid REPOID
Enable just specific repositories by an id or a glob. Can be used more than
once.
.. option:: --releasever RELEASEVER
Override Qubes release version.
.. option:: --refresh
Set repository metadata as expired before running the command.
.. option:: --cachedir CACHEDIR
Specify cache directory. (default: ~/.cache/qvm-template)
.. option:: --yes
Assume "yes" to questions.
.. option:: --quiet
Decrease verbosity.
Subcommands
===========
install
-------
Install template packages.
Synopsis
^^^^^^^^
:command:`qvm-template install` [-h] [--pool *POOL*] [--nogpgcheck] [--allow-pv] [--downloaddir *DOWNLOADDIR*] [--retries *RETRIES*] [*TEMPLATESPEC* [*TEMPLATESPEC* ...]]
See Section `Template Spec`_ for an explanation of *TEMPLATESPEC*.
Options
^^^^^^^
.. option:: -h, --help
Show help message and exit.
.. option:: --pool POOL
Specify pool to store created VMs in.
.. option:: --nogpgcheck
Disable signature checks.
.. option:: --allow-pv
Allow templates that set virt_mode to pv.
.. option:: --downloaddir DOWNLOADDIR
Specify download directory. (default: .)
.. option:: --retries RETRIES
Specify maximum number of retries for downloads. (default: 5)
{reinstall,downgrade,upgrade}
-----------------------------
Reinstall/downgrade/upgrade template packages.
Synopsis
^^^^^^^^
:command:`qvm-template {reinstall,downgrade,upgrade}` [-h] [--nogpgcheck] [--allow-pv] [--downloaddir *DOWNLOADDIR*] [--retries *RETRIES*] [*TEMPLATESPEC* [*TEMPLATESPEC* ...]]
See Section `Template Spec`_ for an explanation of *TEMPLATESPEC*.
Options
^^^^^^^
.. option:: -h, --help
Show help message and exit.
.. option:: --nogpgcheck
Disable signature checks.
.. option:: --allow-pv
Allow templates that set virt_mode to pv.
.. option:: --downloaddir DOWNLOADDIR
Specify download directory. (default: .)
.. option:: --retries RETRIES
Specify maximum number of retries for downloads. (default: 5)
download
--------
Download template packages.
Synopsis
^^^^^^^^
:command:`qvm-template download` [-h] [--downloaddir *DOWNLOADDIR*] [--retries *RETRIES*] [*TEMPLATESPEC* [*TEMPLATESPEC* ...]]
See Section `Template Spec`_ for an explanation of *TEMPLATESPEC*.
Options
^^^^^^^
.. option:: -h, --help
Show help message and exit.
.. option:: --downloaddir DOWNLOADDIR
Specify download directory. (default: .)
.. option:: --retries RETRIES
Specify maximum number of retries for downloads. (default: 5)
list
----
List templates.
Synopsis
^^^^^^^^
:command:`qvm-template list` [-h] [--all] [--installed] [--available] [--extras] [--upgrades] [--machine-readable | --machine-readable-json] [*TEMPLATESPEC* [*TEMPLATESPEC* ...]]
See Section `Template Spec`_ for an explanation of *TEMPLATESPEC*.
Options
^^^^^^^
.. option:: -h, --help
Show help message and exit.
.. option:: --all
Show all templates (default).
.. option:: --installed
Show installed templates.
.. option:: --available
Show available templates.
.. option:: --extras
Show extras (e.g., ones that exist locally but not in repos)
templates.
.. option:: --upgrades
Show available upgrades.
.. option:: --machine-readable
Enable machine-readable output.
Format
Each line describes a template in the following format:
::
{status}|{name}|{evr}|{reponame}
Where ``{status}`` can be one of ``installed``, ``available``,
``extra``, or ``upgradable``.
The field ``{evr}`` contains version information in the form of
``{epoch}:{version}-{release}``.
.. option:: --machine-readable-json
Enable machine-readable output (JSON).
Format
The resulting JSON document is in the following format:
::
{
STATUS: [
{
"name": str,
"evr": str,
"reponame": str
},
...
],
...
}
Where ``STATUS`` can be one of ``"installed"``, ``"available"``,
``"extra"``, or ``"upgradable"``.
The fields ``buildtime`` and ``installtime`` are in ``%Y-%m-%d
%H:%M:%S`` format in UTC.
The field ``{evr}`` contains version information in the form of
``{epoch}:{version}-{release}``.
info
----
Display details about templates.
Synopsis
^^^^^^^^
:command:`qvm-template list` [-h] [--all] [--installed] [--available] [--extras] [--upgrades] [--machine-readable | --machine-readable-json] [*TEMPLATESPEC* [*TEMPLATESPEC* ...]]
See Section `Template Spec`_ for an explanation of *TEMPLATESPEC*.
Options
^^^^^^^
.. option:: -h, --help
Show help message and exit.
.. option:: --all
Show all templates (default).
.. option:: --installed
Show installed templates.
.. option:: --available
Show available templates.
.. option:: --extras
Show extras (e.g., ones that exist locally but not in repos)
templates.
.. option:: --upgrades
Show available upgrades.
.. option:: --machine-readable
Enable machine-readable output.
Format
Each line describes a template in the following format:
::
{status}|{name}|{epoch}|{version}|{release}|{reponame}|{size}|{buildtime}|{installtime}|{license}|{url}|{summary}|{description}
Where ``{status}`` can be one of ``installed``, ``available``,
``extra``, or ``upgradable``.
The fields ``buildtime`` and ``installtime`` are in ``%Y-%m-%d
%H:%M:%S`` format in UTC.
Newlines in the ``{description}`` field are replaced with pipe
characters (``|``) for easier processing.
.. option:: --machine-readable-json
Enable machine-readable output (JSON).
Format
The resulting JSON document is in the following format:
::
{
STATUS: [
{
"name": str,
"epoch": str,
"version": str,
"release": str,
"reponame": str,
"size": int,
"buildtime": str,
"installtime": str,
"license": str,
"url": str,
"summary": str,
"description": str
},
...
],
...
}
Where ``STATUS`` can be one of ``"installed"``, ``"available"``,
``"extra"``, or ``"upgradable"``.
The fields ``buildtime`` and ``installtime`` are in ``%Y-%m-%d
%H:%M:%S`` format in UTC.
search
------
Search template details for the given string.
Synopsis
^^^^^^^^
:command:`qvm-template search` [-h] [--all] [*PATTERN* [*PATTERN* ...]]
Options
^^^^^^^
.. option:: -h, --help
Show help message and exit.
.. option:: --all
Search also in the template description and URL. In addition, the criterion
are evaluated with OR instead of AND.
remove
------
Remove installed templates.
Synopsis
^^^^^^^^
:command:`qvm-template remove` [-h] [--disassoc] [*TEMPLATE* [*TEMPLATE* ...]]
Options
^^^^^^^
.. option:: -h, --help
Show help message and exit.
.. option:: --disassoc
Also disassociate VMs from the templates to be removed. This
creates a *dummy* template for the VMs to link with.
purge
-----
Remove installed templates and associated VMs.
Synopsis
^^^^^^^^
:command:`qvm-template purge` [-h] [*TEMPLATE* [*TEMPLATE* ...]]
Options
^^^^^^^
.. option:: -h, --help
Show help message and exit.
clean
-----
Remove locally cached packages.
Synopsis
^^^^^^^^
:command:`qvm-template clean` [-h]
Options
^^^^^^^
.. option:: -h, --help
Show help message and exit.
repolist
--------
Show configured repositories.
Synopsis
^^^^^^^^
:command:`qvm-template repolist` [-h] [--all | --enabled | --disabled] [*REPOS* [*REPOS* ...]]
Options
^^^^^^^
.. option:: -h, --help
Show help message and exit.
.. option:: --all
Show all repos.
.. option:: --enabled
Show only enabled repos (default).
.. option:: --disabled
Show only disabled repos.
Template Spec
-------------
Subcommands such as ``install`` and ``download`` accept one or more
*TEMPLATESPEC* strings. The format is, in essence, almost identical to
``<package-name-spec>`` described in the DNF documentation.
In short, the spec is matched against the following list of NEVRA forms, in
decreasing orders of priority:
* ``name-[epoch:]version-release``
* ``name``
* ``name-[epoch:]version``
Note that unlike DNF, ``arch`` is currently ignored as the template packages
should all be of ``noarch``.
One can also use globs in spec strings. See Section `Globs`_ for details.
Refer to Section *NEVRA Matching* in the DNF documentation for details.
Globs
-----
`Template Spec`_ strings, repo ids, and search patterns support glob pattern
matching. In particular, the following special characters can be used:
* ``*``: Matches any number of characters.
* ``?``: Matches exactly one character.
* ``[]``: Matches any enclosed character.
* ``[!]``: Matches any character except those enclosed.
In particular, note that ``{}``, while supported by DNF, is not supported by
`qvm-template`.