qvm-template – Manage template VMs

Synopsis

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

--help, -h

Show help message and exit.

--repo-files REPO_FILES

Specify files containing DNF repository configuration. Can be used more than once. (default: [‘/etc/qubes/repo-templates/qubes-templates.repo’])

--keyring KEYRING

Specify directory containing RPM public keys. (default: /etc/qubes/repo-templates/keys)

--updatevm UPDATEVM

Specify VM to download updates from. (Set to empty string to specify the current VM.) (default: same as UpdateVM - see qubes-prefs)

--enablerepo REPOID

Enable additional repositories by an id or a glob. Can be used more than once.

--disablerepo REPOID

Disable certain repositories by an id or a glob. Can be used more than once.

--repoid REPOID

Enable just specific repositories by an id or a glob. Can be used more than once.

--releasever RELEASEVER

Override Qubes release version.

--refresh

Set repository metadata as expired before running the command.

--cachedir CACHEDIR

Specify cache directory. (default: ~/.cache/qvm-template)

--yes

Assume “yes” to questions.

--quiet

Decrease verbosity.

Subcommands

install

Install template packages.

Synopsis

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

-h, --help

Show help message and exit.

--pool POOL

Specify pool to store created VMs in.

--nogpgcheck

Disable signature checks.

--allow-pv

Allow templates that set virt_mode to pv.

--downloaddir DOWNLOADDIR

Specify download directory. (default: .)

--retries RETRIES

Specify maximum number of retries for downloads. (default: 5)

{reinstall,downgrade,upgrade}

Reinstall/downgrade/upgrade template packages.

Synopsis

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

-h, --help

Show help message and exit.

--nogpgcheck

Disable signature checks.

--allow-pv

Allow templates that set virt_mode to pv.

--downloaddir DOWNLOADDIR

Specify download directory. (default: .)

--retries RETRIES

Specify maximum number of retries for downloads. (default: 5)

download

Download template packages.

Synopsis

qvm-template download [-h] [–downloaddir DOWNLOADDIR] [–retries RETRIES] [TEMPLATESPEC [TEMPLATESPEC …]]

See Section Template Spec for an explanation of TEMPLATESPEC.

Options

-h, --help

Show help message and exit.

--downloaddir DOWNLOADDIR

Specify download directory. (default: .)

--retries RETRIES

Specify maximum number of retries for downloads. (default: 5)

list

List templates.

Synopsis

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

-h, --help

Show help message and exit.

--all

Show all templates (default).

--installed

Show installed templates.

--available

Show available templates.

--extras

Show extras (e.g., ones that exist locally but not in repos) templates.

--upgrades

Show available upgrades.

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

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

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

-h, --help

Show help message and exit.

--all

Show all templates (default).

--installed

Show installed templates.

--available

Show available templates.

--extras

Show extras (e.g., ones that exist locally but not in repos) templates.

--upgrades

Show available upgrades.

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

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

remove

Remove installed templates.

Synopsis

qvm-template remove [-h] [–disassoc] [TEMPLATE [TEMPLATE …]]

Options

-h, --help

Show help message and exit.

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

qvm-template purge [-h] [TEMPLATE [TEMPLATE …]]

Options

-h, --help

Show help message and exit.

clean

Remove locally cached packages.

Synopsis

qvm-template clean [-h]

Options

-h, --help

Show help message and exit.

repolist

Show configured repositories.

Synopsis

qvm-template repolist [-h] [–all | –enabled | –disabled] [REPOS [REPOS …]]

Options

-h, --help

Show help message and exit.

--all

Show all repos.

--enabled

Show only enabled repos (default).

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

Authors