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

--keep-cache

Keep downloaded packages in the cache dir (by default are removed after install).

--yes

Assume “yes” to questions.

--verbose, -v

Increase verbosity.

--quiet, -q

Decrease verbosity.

Commands

install

qvm-template install [-h] [–pool POOL] [–nogpgcheck] [–allow-pv] [–downloaddir DOWNLOADDIR] [–retries RETRIES] [TEMPLATESPEC [TEMPLATESPEC …]]

Install template packages. See Section Template Spec for an explanation of TEMPLATESPEC.

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

qvm-template {reinstall,downgrade,upgrade} [-h] [–nogpgcheck] [–allow-pv] [–downloaddir DOWNLOADDIR] [–retries RETRIES] [TEMPLATESPEC [TEMPLATESPEC …]]

Reinstall/downgrade/upgrade template packages.

See Section Template Spec for an explanation of TEMPLATESPEC.

-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

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

Download template packages.

See Section Template Spec for an explanation of TEMPLATESPEC.

-h, --help

Show help message and exit.

--nogpgcheck

Disable signature checks.

--downloaddir DOWNLOADDIR

Specify download directory. (default: .)

--retries RETRIES

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

list

qvm-template list [-h] [–all] [–installed] [–available] [–extras] [–upgrades] [–machine-readable | –machine-readable-json] [TEMPLATESPEC [TEMPLATESPEC …]]

List templates.

See Section Template Spec for an explanation of TEMPLATESPEC.

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

--all-versions

Show all available versions, not only the latest.

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

qvm-template list [-h] [–all] [–installed] [–available] [–extras] [–upgrades] [–machine-readable | –machine-readable-json] [TEMPLATESPEC [TEMPLATESPEC …]]

Display details about templates.

See Section Template Spec for an explanation of TEMPLATESPEC.

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

--all-versions

Show all available versions, not only the latest.

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

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

Remove installed templates.

-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

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

Remove installed templates and associated VMs.

-h, --help

Show help message and exit.

clean

qvm-template clean [-h]

Remove locally cached packages.

-h, --help

Show help message and exit.

repolist

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

Show configured repositories.

-h, --help

Show help message and exit.

--all

Show all repos.

--enabled

Show only enabled repos (default).

--disabled

Show only disabled repos.

migrate-from-rpmdb

qvm-template migrate-from-rpmdb [-h]

Migrate templates metadata from R4.0 format. This makes template originally installed via rpm (qubes-dom0-update) available for qvm-template. All templates gets installed_by_rpm property set to false. If the operation fails for any reason, it is safe to retry.

-h, --help

Show help message and exit.

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

For complete author list see: https://github.com/QubesOS/qubes-core-admin-client.git