<page xmlns="http://projectmallard.org/1.0/"
      xmlns:its="http://www.w3.org/2005/11/its"
      type="topic" style="task"
      id="edit-domain">
  <info>
    <revision pkgversion="40.rc" date="2021-03-10" status="review"/>
    <link type="guide" xref="index#preferences"/>

    <credit type="author copyright">
      <name>Felipe Borges</name>
      <email>felipeborges@gnome.org</email>
      <years>2021</years>
    </credit>

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>

    <desc>Edit advanced configurations of your box.</desc>
  </info>

  <title>Edit the Libvirt domain XML configuration of a box</title>

  <comment>
    <cite date="2021-02-10" href="mailto:felipeborges@gnome.org">Felipe Borges</cite>
    <p>This assumes the reader has a basic understanding of libvirt domains and virtualization
    concepts such as virtual devices. See https://libvirt.org/format.html
    By the end of this page, the reader will be able to configure their virtual machine beyond
    what GNOME Boxes exposes in its user interface.</p>
  </comment>

  <p>Boxes enables you to manually edit the <sys>Libvirt</sys> domain configuration XML of your
  box. You can achieve specific setups which are not exposed in the Boxes interface and neither supported
  by the Boxes developers.</p>

  <note style="info">
    <p>See the Libvirt domain configuration format in documentation at https://libvirt.org/format.html</p>
  </note>

  <steps>
    <title>To edit the Libvirt XML configuration of a box:</title>
    <item><p>Right-click on the box in the collection view and select
    <gui>Preferences</gui>, or click the menu
    (<media type="image" src="figures/view-more-symbolic.svg" its:translate="no"><span its:translate="yes">settings</span></media>)
    button in the header bar and select <gui>Preferences</gui>.</p></item>
    <item><p>Click the <gui>Resources</gui> tab.</p></item>
    <item><p>Scroll to the <gui>Configuration</gui> section.</p></item>
    <item><p>Click the <gui style="button">Edit Configuration</gui> button to open the configuration
    in a text editor.</p></item>
    <item><p>Edit the XML configuration and <gui style="button">Save</gui>.</p></item>
    <item><p>If the virtual machine which has been edited is already running, the changes will take effect
    after restarting the running virtual machine.</p></item>
  </steps>

  <note style="info">
    <p>Before editing the box configuration, Boxes will suggest that you create a
    snapshot. Snapshots allow you to revert your changes in case of a mistake.</p>
  </note>
</page>
