Qubes XML specification
=======================

This is the documentation of qubes.xml autogenerated from RelaxNG source.

Quick example, worth thousands lines of specification:

.. literalinclude:: example.xml
   :language: xml

.. _qubesxml-element-device:

Element: **device**
-------------------

One device. It's identified by a pair of backend domain and some identifier
(device class dependant).

Attributes
^^^^^^^^^^

.. csv-table::
   :header: "attribute", "req.", "type", "value", "description"
   :widths: 1, 1, 1, 1, 1

   "backend-domain", "yes", "string", "``[a-z0-9_]+``", "Backend domain name."
   "id", "yes", "string", "``[0-9a-f]{2}_[0-9a-f]{2}.[0-9a-f]{1}``", ""

Child elements
^^^^^^^^^^^^^^

.. csv-table::
   :header: "element", "number"
   :widths: 1, 1

   ":ref:`option <qubesxml-element-option>`", "\*"

.. _qubesxml-element-devices:

Element: **devices**
--------------------

Container for devices of particular class.

Attributes
^^^^^^^^^^

.. csv-table::
   :header: "attribute", "req.", "type", "value", "description"
   :widths: 1, 1, 1, 1, 1

   "class", "yes", "", "``pci``", "Class of devices in this container. Currently the only supported is ``pci``."

Child elements
^^^^^^^^^^^^^^

.. csv-table::
   :header: "element", "number"
   :widths: 1, 1

   ":ref:`device <qubesxml-element-device>`", "\+"

.. _qubesxml-element-domain:

Element: **domain**
-------------------

One Qubes domain.

Attributes
^^^^^^^^^^

.. csv-table::
   :header: "attribute", "req.", "type", "value", "description"
   :widths: 1, 1, 1, 1, 1

   "class", "yes", "string", "", "Type of the domain. This specifies Python's class that is used for instantiation of this VM."
   "id", "yes", "string", "``domain-[0-9]+``", "XML id attribute used for cross-referencing in properties' ``ref`` attribute."

Child elements
^^^^^^^^^^^^^^

.. csv-table::
   :header: "element", "number"
   :widths: 1, 1

   ":ref:`properties <qubesxml-element-properties>`", "1"
   ":ref:`features <qubesxml-element-features>`", "?"
   ":ref:`tags <qubesxml-element-tags>`", "?"
   ":ref:`devices <qubesxml-element-devices>`", "\*"

.. _qubesxml-element-domains:

Element: **domains**
--------------------

Container for domains.

Child elements
^^^^^^^^^^^^^^

.. csv-table::
   :header: "element", "number"
   :widths: 1, 1

   ":ref:`domain <qubesxml-element-domain>`", "\*"

.. _qubesxml-element-feature:

Element: **feature**
--------------------

One feature of this domain.

Attributes
^^^^^^^^^^

.. csv-table::
   :header: "attribute", "req.", "type", "value", "description"
   :widths: 1, 1, 1, 1, 1

   "name", "yes", "string", "``[a-z0-9_-]+``", "Name of the feature."

.. _qubesxml-element-features:

Element: **features**
---------------------

Container for features.

Child elements
^^^^^^^^^^^^^^

.. csv-table::
   :header: "element", "number"
   :widths: 1, 1

   ":ref:`feature <qubesxml-element-feature>`", "\+"

.. _qubesxml-element-label:

Element: **label**
------------------

Label which can be used by domain. One choice of colour for padlock icon.

Attributes
^^^^^^^^^^

.. csv-table::
   :header: "attribute", "req.", "type", "value", "description"
   :widths: 1, 1, 1, 1, 1

   "id", "yes", "string", "``label-[0-9]+``", "XML id attribute used for cross-referencing in properties' ``ref`` attribute."
   "color", "no", "string", "``#[0-9a-f]{6}``", "Label's colour, HTML-like."

.. _qubesxml-element-labels:

Element: **labels**
-------------------

Container for labels.

Child elements
^^^^^^^^^^^^^^

.. csv-table::
   :header: "element", "number"
   :widths: 1, 1

   ":ref:`label <qubesxml-element-label>`", "\+"

.. _qubesxml-element-option:

Element: **option**
-------------------

Options

Attributes
^^^^^^^^^^

.. csv-table::
   :header: "attribute", "req.", "type", "value", "description"
   :widths: 1, 1, 1, 1, 1

   "name", "yes", "string", "``[a-z0-9_-]+``", "Option name."

.. _qubesxml-element-properties:

Element: **properties**
-----------------------

Container for properties.

Child elements
^^^^^^^^^^^^^^

.. csv-table::
   :header: "element", "number"
   :widths: 1, 1

   ":ref:`property <qubesxml-element-property>`", "\*"

.. _qubesxml-element-property:

Element: **property**
---------------------

One property and its value specified either directly (as text contained in this
tag) or as reference to another XML element in the tree (by ``ref=`` attribute).
How it is saved, it depends on particular property.

Attributes
^^^^^^^^^^

.. csv-table::
   :header: "attribute", "req.", "type", "value", "description"
   :widths: 1, 1, 1, 1, 1

   "name", "yes", "string", "``[a-z0-9_]+``", "Property name."
   "ref", "no", "string", "", "Alternative property value, by reference to another XML element."

.. _qubesxml-element-qubes:

Element: **qubes**
------------------

This is root element of whole qubes tree.

Attributes
^^^^^^^^^^

.. csv-table::
   :header: "attribute", "req.", "type", "value", "description"
   :widths: 1, 1, 1, 1, 1

   "version", "yes", "", "``3.0``", "Specifies minimal Qubes OS version."

Child elements
^^^^^^^^^^^^^^

.. csv-table::
   :header: "element", "number"
   :widths: 1, 1

   ":ref:`properties <qubesxml-element-properties>`", "1"
   ":ref:`labels <qubesxml-element-labels>`", "1"
   ":ref:`domains <qubesxml-element-domains>`", "1"

.. _qubesxml-element-tag:

Element: **tag**
----------------

Tag value.

Tags are not used anywhere by qubes core, they are for users reference. In the
future they will be available for use in policies.

Attributes
^^^^^^^^^^

.. csv-table::
   :header: "attribute", "req.", "type", "value", "description"
   :widths: 1, 1, 1, 1, 1

   "name", "yes", "string", "``[a-z0-9_-]+``", "Name of the tag."

.. _qubesxml-element-tags:

Element: **tags**
-----------------

Container for user-defined tags.

Child elements
^^^^^^^^^^^^^^

.. csv-table::
   :header: "element", "number"
   :widths: 1, 1

   ":ref:`tag <qubesxml-element-tag>`", "\+"