.. 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: sys-firewall) .. 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 ISO 8601 format. For example, one can parse them in Python with ``datetime.fromisoformat()``. 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 ISO 8601 format. For example, one can parse them in Python with ``datetime.fromisoformat()``. 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 ISO 8601 format. For example, one can parse them in Python using `datetime.fromisoformat()`. 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 ```` 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`.