ManagementVM support

.gitlab-ci.yml

@@ -12,30 +12,44 @@ lint:
   extends: .lint
   stage: tests
 
-.mgmt-host-template:
+.qubes-ansible-tests:
   stage: tests
   tags:
     - vm-kvm
-  after_script:
-    - ci/codecov-wrapper -F unittests
-  before_script:
+
+  before_script: &install_qubes_ansible
     # install dependencies
     - sudo qubes-dom0-update -y
     - sudo qubes-dom0-update -y ansible python3-pytest python3-coverage perl-Digest-SHA
     # install from artifacts
     - find $CI_PROJECT_DIR/artifacts/repository/host-fc* -name '*.noarch.rpm' -exec sudo dnf install -y {} \+
     - $CI_PROJECT_DIR/ci/install_ansible_vm.sh
-  script:
-    # run ansible's tests
-    - cd /usr/share/ansible && sudo coverage run --data-file=$CI_PROJECT_DIR/.coverage --include=plugins/modules/qubesos.py,plugins/connection/qubes.py -m pytest -vvv tests/qubes/
 
-r4.3:mgmt-host:
-  extends: .mgmt-host-template
+  after_script:
+    - ci/codecov-wrapper -F unittests
+
+  variables:
+    VM_IMAGE: qubes_4.3_64bit_stable.qcow2
+
   needs:
     - r4.3:build:host-fc41
     - r4.3:build:vm-fc42
-  variables:
-    VM_IMAGE: qubes_4.3_64bit_stable.qcow2
+
+r4.3:mgmt-host:
+  extends: .qubes-ansible-tests
+  script:
+    # run ansible's tests
+    - cd /usr/share/ansible && sudo coverage run --data-file=$CI_PROJECT_DIR/.coverage --include=plugins/modules/qubesos.py,plugins/connection/qubes.py -m pytest -vvv tests/qubes/
+
+r4.3:mgmtvm:
+  extends: .qubes-ansible-tests
+
+  before_script:
+    - *install_qubes_ansible
+    - $CI_PROJECT_DIR/ci/install_mgmtvm.sh
+  script:
+    # run ansible's tests
+    - qvm-run -p -u root mgmtvm 'cd /usr/share/ansible ; coverage run --data-file=/root/.coverage --include=plugins/modules/qubesos.py,plugins/connection/qubes.py -m pytest -vvv tests/qubes/'
 
 pages:
   stage: build
@@ -53,3 +67,4 @@ pages:
     - antsibull-docs sphinx-init qubesos.* --use-current --dest-dir build/
     - ANSIBLE_COLLECTIONS_PATH=$(pwd) ./build/build.sh
     - mv build/build/html/* public/
+

.qubesbuilder

@@ -1,7 +1,7 @@
 host:
   rpm:
     build:
-    - rpm_spec/qubes-ansible.spec
+    - rpm_spec/qubes-ansible-host.spec
 vm:
   rpm:
     build:

Makefile

@@ -1,7 +1,7 @@
 VERSION := $(shell cat version)
 QUBE_COLLECTION_DIR := $(DESTDIR)/usr/share/ansible/collections/ansible_collections/qubesos
 
-install-common:
+_install-common:
 	mkdir -p $(QUBE_COLLECTION_DIR)/core/plugins/connection
 	mkdir -p $(QUBE_COLLECTION_DIR)/core/plugins/modules
 	mkdir -p $(QUBE_COLLECTION_DIR)/core/plugins/module_utils
@@ -17,7 +17,14 @@ install-common:
 	install -m 644 plugins/modules/qubesos.py $(DESTDIR)/usr/share/ansible/plugins/modules/qubesos.py
 
 
-install-dom0:
+_install-dom0:
+	mkdir -p $(DESTDIR)/etc/qubes-rpc/
+	mkdir -p $(DESTDIR)/usr/lib/qubes/qubes-rpc/
+	install -m 755 qubes-rpc/qubes-ansible-manage-policies $(DESTDIR)/usr/lib/qubes/qubes-rpc/qubes-ansible-manage-policies
+	ln -s ../../usr/lib/qubes/qubes-rpc/qubes-ansible-manage-policies $(DESTDIR)/etc/qubes-rpc/ansible.CreateManagementPolicies
+	ln -s ../../usr/lib/qubes/qubes-rpc/qubes-ansible-manage-policies $(DESTDIR)/etc/qubes-rpc/ansible.RemoveManagementPolicies
+
+_install-security:
 	mkdir -p $(DESTDIR)/usr/lib/qubes/
 	mkdir -p $(QUBE_COLLECTION_DIR)/security/plugins/callback
 	mkdir -p $(QUBE_COLLECTION_DIR)/security/plugins/strategy
@@ -32,13 +39,16 @@ install-dom0:
 	ln -s ../../collections/ansible_collections/qubesos/security/plugins/strategy/qubes_proxy.py \
 		$(DESTDIR)/usr/share/ansible/plugins/strategy/qubes_proxy.py
 
-install-tests:
+_install-vm:
+	mkdir -p $(DESTDIR)/etc/qubes-rpc/
+	install -m 755 qubes-rpc/qubes.AnsibleVM $(DESTDIR)/etc/qubes-rpc/qubes.AnsibleVM
+
+_install-tests:
 	mkdir -p $(DESTDIR)/usr/share/ansible/tests/qubes
 	install -m 644 tests/qubes/*.py $(DESTDIR)/usr/share/ansible/tests/qubes/
 	install -m 644 tests/*.cfg $(DESTDIR)/usr/share/ansible/tests/
 
-install-vm:
-	mkdir -p $(DESTDIR)/etc/qubes-rpc/
-	install -m 755 qubes-rpc/qubes.AnsibleVM $(DESTDIR)/etc/qubes-rpc/qubes.AnsibleVM
-
-install-all: install-common install-dom0 install-tests install-vm
+install-vm: _install-common _install-vm
+install-vm-sec: install-vm _install-security
+install-vm-all: install-vm-sec _install-tests
+install-dom0: _install-common _install-security _install-dom0 _install-tests

README.md

@@ -53,14 +53,14 @@ will raise an error and interrupt Ansible execution.
 
 ## Installation
 
-### AdminVM (dom0)
+### Dom0
 
-Install the following package: ``qubes-ansible-dom0``
+Install the following package: ``qubes-ansible``.
 
 ### Management DVM
 
 The package ``qubes-ansible-vm`` (``qubes-ansible`` for Debian and Archlinux) must be installed 
-on templates used by your qubes management DVM (``default-mgmt-dvm`` by default).
+in the templates used by your management DVM (``default-mgmt-dvm`` by default).
 
 ## Usage
 
@@ -127,31 +127,96 @@ limitations:
   * Play recap will reflect the number of plays ran for each host instead of the number of tasks
   * Only plain text output is supported
 
-## Management VM
+## Management VM (advanced)
 
-Usage of this module with a Management VM is not yet supported. However, the 
-following policies may be added if doing so:
+You can use a dedicated qube to run your Ansible playbooks. Install the
+package `qubes-ansible-admin`: it will deploy the `qubesos.core` collection and
+all the `qubesos.security` plugins.
 
-Append the following lines to `/etc/qubes/policy.d/include/admin-local-rwx`:
+Then, you will need to write policies that fit your needs. 
+
+First, you can add the following lines to `/etc/qubes/policy.d/include/admin-local-rwx`:
 ```
 mgmtvm @tag:created-by-mgmtvm allow target=dom0
 mgmtvm mgmtvm                 allow target=dom0
 ```
 
-Append the following lines to `/etc/qubes/policy.d/include/admin-global-ro`:
+And append the following lines to `/etc/qubes/policy.d/include/admin-global-ro`:
 ```
 mgmtvm @adminvm               allow target=dom0
 mgmtvm @tag:created-by-mgmtvm allow target=dom0
 mgmtvm mgmtvm                 allow target=dom0
 ```
 
-Create a policy file at `/etc/qubes/policy.d/30-ansible.policy` with the 
-following content:
+This lets your ManagementVM manage the qubes it creates.
+
+You may also want to allow your ManagementVM to read properties of sys vms and 
+several templates. For example, when setting a netvm to a qube, the module checks 
+if the target qube exits and provides network, which requires the mgmtvm to be 
+able to read the target qube properties:
+
+`/etc/qubes/policy.d/include/admin-global-ro`:
+```
+mgmtvm sys-net                allow target=dom0
+mgmtvm sys-firewall           allow target=dom0
+mgmtvm sys-usb                allow target=dom0
+mgmtvm debian-13-xfce         allow target=dom0
+mgmtvm fedora-42-xfce         allow target=dom0
+```
+
+`/etc/qubes/policy.d/include/admin-local-ro`:
+```
+mgmtvm sys-net                allow target=dom0
+mgmtvm sys-firewall           allow target=dom0
+mgmtvm sys-usb                allow target=dom0
+mgmtvm debian-13-xfce         allow target=dom0
+mgmtvm fedora-42-xfce         allow target=dom0
 ```
-admin.vm.Create.AppVM        * mgmtvm dom0                   allow
-admin.vm.Create.StandaloneVM * mgmtvm dom0                   allow
-admin.vm.Create.TemplateVM   * mgmtvm dom0                   allow
-admin.vm.Remove              * mgmtvm @tag:created-by-mgmtvm allow target=dom0
+
+Then, create a policy file at `/etc/qubes/policy.d/30-mgmtvm.policy` and adjust 
+its content to fit your security requirements:
+```
+# =================
+# Qubes management
+# =================
+
+# The ManagementVM must be able to create new qubes and manage them
+admin.vm.Create.AppVM            * mgmtvm dom0                   allow
+admin.vm.Create.StandaloneVM     * mgmtvm dom0                   allow
+admin.vm.Create.TemplateVM       * mgmtvm dom0                   allow
+
+
+# You may want to allow to clone some template to create StandaloneVMs or new TemplateVMs
+admin.vm.volume.CloneFrom        * mgmtvm debian-13-xfce         allow target=dom0
+admin.vm.volume.CloneFrom        * mgmtvm fedora-42-xfce         allow target=dom0
+
+# And to remove created ones
+admin.vm.Remove                  * mgmtvm @tag:created-by-mgmtvm allow target=dom0
+
+# Get available devices (qubesos.core.host_devices_facs)
+admin.vm.device.pci.Available    * mgmtvm dom0 allow
+admin.vm.device.block.Available  * mgmtvm dom0 allow
+
+# You may want to assign devices to your qubes
+admin.vm.device.pci.Assign       * mgmtvm @tag:created-by-mgmtvm allow target=dom0
+
+# =============
+# Proxy Plugin
+# =============
+
+# The proxy creates a dispvm from the management dvm of the managed qubes
+# Copy these lines for each value of the management_dispvm preference used by your qubes.
+admin.vm.Create.DispVM           +default-mgmt-dvm mgmtvm dom0 allow
+admin.vm.property.Get            +label            mgmtvm default-mgmt-dvm allow target=dom0
+
+# Allow mgmtvm to call RPC managing dynamic policy creation allowing to run the
+# connection plugin
+ansible.CreateManagementPolicies * mgmtvm @tag:created-by-mgmtvm allow target=dom0
+ansible.RemoveManagementPolicies * mgmtvm @tag:created-by-mgmtvm allow target=dom0
+
+# The proxy needs to copy and execute playbooks on DispVMs
+qubes.AnsibleVM                  * mgmtvm @tag:created-by-mgmtvm allow
+qubes.Filecopy                   * mgmtvm @tag:created-by-mgmtvm allow
 ```
 
 ## Legacy module `qubesos`