Initial project proposal (contains motivation and goals, while this document primarily focuses on the implementation):
Discussion threads:
- https://groups.google.com/forum/#!topic/qubes-devel/6Zb_WLy3GY4
- https://groups.google.com/forum/#!topic/qubes-devel/PyJogqT1TUg
- https://groups.google.com/forum/#!topic/qubes-devel/2XaMP4Us3kg
- https://groups.google.com/forum/#!topic/qubes-devel/wF_84b1BR0A
Command format should roughly follow that of
DNF. See qvm-template --help
for details.
qvm-template install
- install template from repo/existing RPM
qvm-template download
- download, but not install, template RPM from repo
qvm-template list
- list available/installed templates
qvm-template info
- list information about available/installed templates
qvm-template search
- search for templates in repo
qvm-template upgrade
qvm-template downgrade
qvm-template reinstall
- {upgrade,downgrade,reinstall} templates, overriding local changes
qvm-template remove
- remove template (equivalent to
qvm-remove
)
- remove template (equivalent to
qvm-template clean
- clean downloaded RPMs
qvm-template repolist
- list repos, e.g.,
qubes-templates-community
- list repos, e.g.,
- use kernel in template (i.e., set to PVGrub)
- ability to output information in machine-readable format (JSON?), as mentioned in QubesOS/qubes-issues#2534
- ability to install templates in alternative pools, again mentioned in #2534
- when removing templates, possibly remove associated AppVMs or have their
templates set to
dummy
1) - set template of AppVMs (merge with current
qubes-template-manager
?) (low priority) - GUI
The package format is based on RPM to take advantage of existing tools and mechanisms such as repository management and signature verification.
For the package metadata, one needs to ensure that the character |
does not
appear. This is because we use the character as a separator internally. Failure
to do so may result in qvm-template
to fail with cryptic error messages.
Note that as we already consider the repository metadata to be untrusted, this
should not result in an issue security-wise.
The file structure should be quite similar to the current template RPMs. Namely, there should be the following files in the package:
var/lib/qubes/vm-templates/${template_name}/root.img.part.*
- Split tarball of template
root.img
.Note that the file is no longer split, since newer releases of Fedora handles large files fine. However, the tarball is still kept due to RPM not preserving sparsity.The file is still split due to tools such asrpm2cpio
not supporting large files.2
- Split tarball of template
var/lib/qubes/vm-templates/${template_name}/template.conf
- Stores custom package metadata (as RPM does not support custom attributes).
KEY=VALUE
format- Fields (corresponding to qvm-prefs/qvm-features tags)
virt_mode
Setting this topv
requires user confirmation.kernel
Only allowed to be set to "none", i.e., empty string.no-monitor-layout
pci-e820-host
linux-stubdom
gui
gui-emulated
qrexec
These six flags are only allowed to be set to "1" or "0", denoting "true" and "false" respectively.net.fake-ip
net.fake-gateway
net.fake-netmask
var/lib/qubes/vm-templates/${template_name}/whitelisted-appmenus.list
var/lib/qubes/vm-templates/${template_name}/vm-whitelisted-appmenus.list
var/lib/qubes/vm-templates/${template_name}/netvm-whitelisted-appmenus.list
- Same as current format. Namely, default appmenu entries of the template itself, VMs based on the template, and NetVMs based on the template are stored respectively.
- Note that the contents of these files are stored in
qvm-features
upon installation. See section below for details.
The template manager needs to store metadata of installed templates such as
version information and template origin. This data can be stored via
qvm-features
to keep things consistent when, e.g., qvm-remove
is used.
Besides, backups are also more easily handled. In addition, the fields also
serve as an indication to whether a template is installed by qvm-template
.
Most of the fields should be fairly self-explanatory.
-
template-name
-
template-epoch
-
template-version
-
template-release
-
template-reponame
-
template-buildtime
-
template-install-date
- Dates are in ISO 8601 format, and can be parsed in Python with
datetime.datetime.fromisoformat()
.
- Dates are in ISO 8601 format, and can be parsed in Python with
-
template-licence
-
template-url
-
template-summary
-
template-description
- Note that the newlines in this field are converted to
|
to work better with existing tools likeqvm-features
.
- Note that the newlines in this field are converted to
-
menu-items
-
default-menu-items
-
netvm-menu-items
- The entries store the contents of
var/lib/qubes/vm-templates/${template_name}/whitelisted-appmenus.list
var/lib/qubes/vm-templates/${template_name}/vm-whitelisted-appmenus.list
var/lib/qubes/vm-templates/${template_name}/netvm-whitelisted-appmenus.list
respectively. - Note that the newlines are converted to spaces, again for it to work better
with existing tools like
qvm-features
. This should not cause ambiguity as the FreeDesktop specifications forbid spaces from file names of desktop files.
- The entries store the contents of
Should work straightforwardly.
A template is treated as non-RPM-installed once renamed. However, the origin is still stored in the VM features for future extension and a hint for the user.
For UpdateVMs to access the template repository configuration, a package qubes-repo-templates is created that contains not only the repository configuration but also relevant PGP keys.
To achieve features such as qtm purge
, the template manager needs to have
corresponding AdminAPI access to change the templates of other AppVMs. However,
one might wish for the management VM not to be able to see/control all VMs.
More fine-grained rules can be created by automatically adjusting VM tags based on the template VM used -- similar to how GUI VMs are handled3 -- so that a management VM is able to control the VMs based on the templates that it control.
https://github.com/QubesOS/qubes-core-admin/blob/master/qubes/ext/gui.py#L55-L77
As discussed, qrexec calls for listing and downloading templates are needed. The following calls are thus proposed.
qubes.TemplateSearch
: Wrapsdnf repoquery
qubes.TemplateDownload
: Wrapsdnf download
Both of the calls accept the following input format from standard input:
arg1
arg2
...
argN
package-file-spec
---
repo config
In other words, the input consists of two parts separated by the line ---
.
The first part contains some arguments and a parameter that indicates the
pattern to be queried or downloaded.4 The following arguments are allowed:
--enablerepo=<repoid>
--disablerepo=<repoid>
--repoid=<repoid>
--releasever=<release>
--refresh
where the usage is identical to that of DNF.
The second part contains the repository configurations in /etc/yum.repos.d/
format.
qubes.TemplateSearch
outputs the packages in
%{name}|%{epoch}|%{version}|%{release}|%{reponame}|%{downloadsize}|%{buildtime}|%{license}|%{url}|%{summary}|%{description}|
format to standard output, separated by newlines. Note that there is a |
at
the end of the line. This is because %{description}
may contain newlines, and
doing so allows us to split the entries by |\n
.5
On the other hand, qubes.TemplateDownload
directly outputs the downloaded
content to standard output.
Note that some changes may not have been fully reviewed. (Unfortunately, GFM does not seem to provide tri-state checkboxes.)
- GitHub Project
- Installation of downloaded RPM
- Ability to set kernel & other qvm-feature flags mentioned above
- Appmenu whitelists
-
qvm-template install
-
qvm-template reinstall
-
qvm-template downgrade
-
qvm-template upgrade
- Repo interaction
- https://github.com/WillyPillow/qubes-repo-templates
- Qrexec calls
-
qvm-template download
-
qvm-template list
-
qvm-template info
-
qvm-template search
-
qvm-template repolist
- Manage local templates
-
qvm-template remove
-
qvm-template purge
-
qvm-template clean
-
- QubesOS/qubes-issues#5946
- Document the new admin API call
- Machine-readable output
- Simple format
- JSON format
- Documentation
- GUI