libvirt.rst 3.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117
  1. Custom libvirt config
  2. =====================
  3. Starting from Qubes OS R4.0, libvirt domain config is generated using jinja
  4. templates. Those templates can be overridden by the user in a couple of ways.
  5. A basic knowledge of jinja template language and libvirt xml spec is needed.
  6. .. seealso::
  7. https://libvirt.org/formatdomain.html
  8. Format of the domain XML in libvirt.
  9. http://jinja.pocoo.org/docs/dev/templates/
  10. Template format documentation.
  11. File paths
  12. ----------
  13. In order of increasing precedence: the main template, from which the config is
  14. generated is :file:`/usr/share/templates/libvirt/xen.xml`).
  15. The distributor may put a file at
  16. :file:`/usr/share/qubes/template/xen-dist.xml`) to override this file.
  17. User may put a file at either
  18. :file:`/etc/qubes/templates/libvirt/xen-user.xml` or
  19. :file:`/etc/qubes/templates/libvirt/xen/by-name/<name>.xml`, where ``<name>`` is
  20. full name of the domain. Wildcards are not supported but symlinks are.
  21. Jinja has a concept of template names, which basically is the path below some
  22. load point, which in Qubes' case is :file:`/etc/qubes/templates` and
  23. :file:`/usr/share/qubes/templates`. Thus names of those templates are
  24. respectively ``'libvirt/xen.xml'``, ``'libvirt/xen-dist.xml'``,
  25. ``'libvirt/xen-user.xml'`` and ``'libvirt/xen/by-name/<name>.xml'``.
  26. This will be important later.
  27. .. note::
  28. Those who know jinja python API will know that the abovementioned locations
  29. aren't the only possibilities. Yes, it's a lie, but a justified one.
  30. What to put in the template
  31. ---------------------------
  32. In principle the user may put anything in the template and there is no attempt
  33. to constrain the user from doing stupid things. One obvious thing is to copy the
  34. original config file and make changes.
  35. .. code-block:: jinja
  36. <domain type="xen">
  37. <name>{{ vm.name }}</name>
  38. ...
  39. The better way is to inherit from the original template and override any number
  40. of blocks. This is the point when we need the name of the original template.
  41. .. code-block:: jinja
  42. {% extends 'libvirt/xen.xml' %}
  43. {% block devices %}
  44. {{ super() }}
  45. <serial type='pty'>
  46. <target port='0'/>
  47. </serial>
  48. {% endblock %}
  49. ``{% extends %}`` specifies which template we inherit from. Then you may put any
  50. block by putting new content inside ``{% block %}{% endblock %}``.
  51. ``{{ super() }}`` is substituted with original content of the block as specified
  52. in the parent template. Untouched blocks remain as they were.
  53. The example above adds serial device.
  54. Template API
  55. ------------
  56. .. warning::
  57. This API is provisional and subject to change at the minor releases until
  58. further notice. No backwards compatibility is promised.
  59. Globals
  60. ```````
  61. vm
  62. the domain object (instance of subclass of
  63. :py:class:`qubes.vm.qubesvm.QubesVM`)
  64. Filters
  65. ```````
  66. No custom filters at the moment.
  67. Blocks in the default template
  68. ``````````````````````````````
  69. basic
  70. Contains ``<name>``, ``<uuid>``, ``<memory>``, ``<currentMemory>`` and
  71. ``<vcpu>`` nodes.
  72. cpu
  73. ``<cpu>`` node.
  74. os
  75. Contents of ``<os>`` node.
  76. features
  77. Contents of ``<features>`` node.
  78. clock
  79. Contains the ``<clock>`` node.
  80. on
  81. Contains ``<on_*>`` nodes.
  82. devices
  83. Contents of ``<devices>`` node.
  84. .. vim: ts=3 sts=3 sw=3 et