core-admin-client/doc/manpages/qvm-template.rst

.. 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`.