path: root/help/virt-manager/C/virt-manager.xml

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY appversion "0.3.0">
  <!ENTITY manrevision "0.1">
  <!ENTITY date "March 2007">
  <!ENTITY app "virt-manager">
]>
<!--
      (Do not remove this comment block.)
  Template Maintained by the GNOME Documentation Project:
	  http://developer.gnome.org/projects/gdp
  Template version: 2.0 beta
  Template last modified Feb 12, 2002
-->


<!--
      (Do not remove this comment block.)
  Version: 0.0.1
  Last modified: March 2, 2007
  Maintainers:
               Hugh Brock      <hbrock@redhat.com>
               Dan Berrange    <berrange@redhat.com>
  Translators:
               (translators put your name and email here)
-->



<!-- =============Document Header ============================= -->
<article id="index" lang="en">
 <!-- please do not change the id; for translations, change lang to -->
 <!-- appropriate code -->

 <articleinfo>
  <title>Virtual Machine Manager Manual</title>
  <copyright>
   <year>2007</year>
   <holder>Red Hat Inc., and Hugh Brock</holder>
  </copyright>

  <!-- translators: uncomment this:

  <copyright>
  <year>2000</year>
  <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
 </copyright>

  -->
  <!-- An address can be added to the publisher information.  If a role is
  not specified, the publisher/author is the same for all versions of the
  document.  -->
  <publisher>
   <publishername> Red Hat Inc. </publishername>
  </publisher>
  
  <authorgroup>
   <author>
    <firstname>Hugh</firstname>
    <surname>Brock</surname>
    <affiliation>
     <orgname>Red Hat Inc.</orgname>
     <address> <email>hbrock@redhat.com</email> </address>
    </affiliation>
   </author>
   <author>
    <firstname>Daniel</firstname>
    <surname>Berrange</surname>
    <affiliation>
     <orgname>Red Hat Inc.</orgname>
     <address> <email>berrange@redhat.com</email> </address>
    </affiliation>
   </author>
   <!-- This is appropriate place for other contributors: translators,
   maintainers,  etc. Commented out by default.
   <othercredit role="translator">
   <firstname>Latin</firstname>
   <surname>Translator 1</surname>
   <affiliation>
   <orgname>Latin Translation Team</orgname>
   <address> <email>translator@gnome.org</email> </address>
  </affiliation>
   <contrib>Latin translation</contrib>
  </othercredit>
   -->
  </authorgroup>

  <!-- The revision numbering system for GNOME manuals is as follows: -->
  <!-- * the revision number consists of two components -->
  <!-- * the first component of the revision number reflects the release version of the GNOME desktop. -->
  <!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->
  <!-- For example, if the GNOME desktop release is V2.x, the first version of the manual that -->
  <!-- is written in that desktop timeframe is V2.0, the second version of the manual is V2.1, etc. -->
  <!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->
  <!-- to V3.0, and so on. -->
  
  <revhistory>
   <revision>
    <revnumber>&app; Man=ual V&manrevision;</revnumber>
    <date>&date;</date>
    <revdescription>
     <para role="author">Hugh Brock
      <email>hbrock@redhat.com</email>
     </para>
     <para role="publisher">Red Hat Inc.</para>
    </revdescription>
   </revision>
  </revhistory>
  <releaseinfo>This manual describes how to manage virtual machines
   with the Virtual Machine Manager program.
  </releaseinfo>
  <legalnotice>
   <title>Feedback</title>
   <para>To report a bug or make a suggestion regarding this package or
    this manual, follow the directions at the
    <ulink url="http://virt-manager.org"
     type="http">virt-manager website</ulink>.
   </para>
   <!-- Translators may also add here feedback address for translations -->
  </legalnotice>
 </articleinfo>
 
 <!-- ============= Document Body ============================= -->
 <!-- ============= Introduction ============================== -->
 <sect1 id="virt-manager-intro">
  <title>Introduction</title>

  <sect2 id="virt-manager-about-vm">
   <title>About <application>&app;</application></title>
   <indexterm>
    <primary>virt-manager</primary>
    <secondary>About</secondary>
   </indexterm>
   <para>
    <application>&app;</application> is a GUI tool for managing virtual
    machines (VMs). It helps you create, destroy, edit, monitor, save, restore,
    pause, and use the console on virtual machines running on multiple
    hypervisors (and, soon, multiple physical hosts). Because
    <application>&app;</application> relies entirely on
    <application>libvirt</application> (<ulink type="http"
     url="http://libvirt.org">http://libvirt.org</ulink>), the platform- and
    hypervisor-independent virtualization library, it is insulated from
    hypervisor API changes and virtualization system changes.
   </para>
   <para>
    <application>&app;</application> is released under the GNU General Public
    License. Contributions of source code patches are welcome and encouraged
    at <ulink type="http"
     url="http://virt-manager.org">virt-manager.org</ulink>, where you will 
    also find plans for future development.
   </para>
  </sect2>
  <sect2 id="virt-manager-about-doc">
   <title>About this Document</title>
   <para>
    This document is released under the Open Publication License v
    1.0. Corrections are welcome and encouraged at <ulink type="http"
    url="http://virt-manager.org">virt-manager.org</ulink>.
   </para>
  </sect2>
 </sect1>
 
 <sect1 id="virt-manager-getting-started">
  <title>Getting Started</title>
  
  <para>
   This section describes the different ways to start
   <application>&app;</application>, the command-line options that are
   available, and the various options in the Connection window.
  </para>
  <sect2 id="virt-manager-starting">
   <title>Starting virt-manager</title> 
   <para>You can start
    virt-manager from the Applications menu or from the command
    line</para>
   <variablelist>
    <varlistentry>
     From the <term><guimenu>Applications</guimenu> menu</term>:
     <listitem>
      <para>Choose <menuchoice><guisubmenu>System
	 Tools</guisubmenu><guimenuitem>Virtual Machine Manager</guimenuitem></menuchoice>. </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     From the <term>command line</term>:
     <listitem>
      <para>Execute the following command: <command>virt-manager</command></para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>
  
  <sect2 id="virt-manager-conn-window">
   <title>The Connection Window</title> 
   <para>The connection window
    lets you choose the type of hypervisor to connect to, and also
    whether to connect locally or to a remote machine.</para>
   <para>When you start <application>&app;</application>, the following window is displayed:</para>

   <figure id="virt-manager-FIG-connection-window">
    <title>Connection Window</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/vm-connection-window.png" format="PNG"/>
      </imageobject>
      <textobject> <phrase>Shows &app; connection window.</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>

   <para>The Connection Window contains the following
    elements: </para>
   <variablelist>
    <varlistentry> <term>Hypervisor pull-down</term>
     <listitem>
      <para>The Hypervisor pull-down lets you choose a supported hypervisor to
      connect to. The hypervisor must be started before you can connect to it.</para>
     </listitem>
    </varlistentry>
    <varlistentry> <term>&quot;Host Type&quot; radio buttons</term>
     <listitem>
      <para>The &quot;Host Type&quot; radio buttons let you choose whether to connect to
      a hypervisor on the local physical host, or (soon) a hypervisor on a
       remote physical host.</para>
     </listitem>
     <listitem>
      <para>The &quot;Host&quot; box lets you enter the hostname of a remote host to
       connect to.</para>
     </listitem>
    </varlistentry>
    <varlistentry> <term>Read-only connection</term>
     <listitem>
      <para>Checking &quot;Read-only connection&quot; will allow you to
       monitor a hypervisor's virtual machines, but not make any changes to
       them. If you are running as an unprivileged user, you may only be able
       to connect to certain hypervisors read-only.</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>
  <sect2 id="virt-manager-CLI-opts">
   <title>Command-line Options</title>
   <para>If you run &app; from the command line, you can specify a hypervisor
    URI to connect to, bypassing the Connection Window. You can also make
    specific &app; windows appear using the command line, if you have already
    established a connection to a hypervisor. The command line options are:</para>
   <itemizedlist>
    <listitem><para><command>-h, --help</command>: show command line help and exit</para>
    </listitem>
    <listitem>
     <para><command>--profile=FILE</command>: Generate runtime performance profile stats</para>
    </listitem>
    <listitem>
     <para><command>-c URI, --connect=URI</command>: Connect to hypervisor at
      URI</para>
    </listitem>
    <listitem>
     <para><command>--no-dbus</command>: Disable DBus service for controlling
      UI</para>
    </listitem>
    <listitem>
     <para><command>--show-domain-creator</command>: Create a new virtual
      machine</para>
    </listitem>
    <listitem>
     <para><command>--show-domain-editor=UUID</command>: Edit a domain
      configuration</para>
    </listitem>
    <listitem>
     <para><command>--show-domain-performance=UUID</command>: Show a domain
      performance</para>
    </listitem>
    <listitem>
     <para><command>--show-domain-console=UUID</command>: Show a domain
      console</para>
    </listitem>
    <listitem>
     <para><command>--show-host-summary</command>: Show a host summary</para>
    </listitem>
   </itemizedlist>
   <note>
    <title>Hypervisor URIs and the test hypervisor</title> <para>To connect to
    a local Xen hypervisor, the URI is simply &quot;xen&quot; (the
    default). To connect to a local QEMU session, the URI is
     &quot;qemu:///session&quot;. There is also a test hypervisor that is
     handy if you are trying to test a new &app; feature you have added. Its
     URI is &quot;test:///default&quot;.</para>
   </note>
  </sect2>
 </sect1>

 <sect1 id="virt-manager-mgr-window">
  <title>The Manager Window</title>
  <para>The manager window gives you a quick snapshot of the virtual machines
   that are available on your physical host. It displays both the virtual
   machines that are actually running
   on your physical host, and also the virtual machines for which it finds
   config information even though they are not running. For running virtual
   machines, the manager window displays the resources those running VMs are
   consuming. The manager window is customizable as described below.</para>
  
   <figure id="virt-manager-FIG-mgr-window">
    <title>Manager Window</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/vm-manager-window.png" format="PNG"/>
      </imageobject>
      <textobject> <phrase>Shows a typical Manager Window.</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>

  <sect2 id="virt-manager-vm-list">
   <title>The Virtual Machine List</title>
   <para>The manager window is dominated by a list of the virtual machines on your
   physical host. By default, the list has six columns of information:</para>
   <variablelist>
    <varlistentry><term>ID</term>
     <listitem>
      <para>The arbitrarily assigned ID number for the
       virtual machine. Guaranteed unique only while a virtual machine is
       running, and only to that particular host.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Name</term>
     <listitem>
      <para>The name of the virtual machine. Like the ID, guaranteed unique
       only among running virtual machines on a particular host.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Status</term>
     <listitem>
      <para>The virtual machine's status. One of <guilabel>Running</guilabel>,
       <guilabel>Paused</guilabel>, <guilabel>Shutdown</guilabel>,
       <guilabel>Shutoff</guilabel>, or <guilabel>Crashed</guilabel>.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>CPU Usage</term>
     <listitem>
      <para>The virtual machine's CPU usage, as a percentage of total CPU
       usage and as a running graph.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>VCPUs</term>
     <listitem>
      <para>The number of VCPUs currently assigned to the VM. This
       allocation can be changed on the fly for paravirtualized
       VMs.</para> 
     </listitem>
    </varlistentry>
    <varlistentry><term>Memory Usage</term>
     <listitem>
      <para>The amount of memory allocated to the virtual machine, and the percentage
       of total physical RAM on the host that the virtual machine is actually
       using (the percentage will be zero if the VM is not currently
       running). Note: The amount of memory for a virtual machine is the
       amount it is currently allocated, not the maximum it could be
       allocated. See the help for the <xref linkend="virt-manager-details-window"/>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>
  <sect2 id="virt-manager-file-menu">
   <title>File Menu Choices</title>
   <para>The File menu in the Manager window gives you the following
    options:</para>
   <variablelist>
    <varlistentry><term>New machine...</term>
     <listitem><para>Starts the virtual machine creation wizard. Clicking the
       <guibutton>New</guibutton> button at the bottom of the window has the
       same effect.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Restore saved machine...</term>
     <listitem><para>Restores a previously saved virtual machine. You must
       choose the memory image of a previously saved virtual machine in the
       dialog that will follow.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Open connection...</term>
     <listitem><para>Brings up the connection window again. You can connect to
       multiple hypervisors at the same time with
       <application>&app;</application>. At this writing opening a new
       connection brings up a new manager window; soon the manager window will
       display multiple connections to multiple machines.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Close</term>
     <listitem><para>Closes the Manager window. Any other
       <application>&app;</application> windows you have open will remain open.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Quit</term>
     <listitem><para>Closes the Manager window and any other open windows and
       stops the application. Note that any virtual machines running on the
       host will continue running regardless of whether 
       <application>&app;</application> is running or not.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>
  <sect2 id="virt-manager-edit-menu">
   <title>Edit Menu Choices</title>
   <para>The choices on the <guimenu>Edit</guimenu> menu are for working with
    a specific machine, or for changing <application>&app;</application>
    preferences.</para>
   <variablelist>
    <varlistentry><term>Machine details...</term>
     <listitem><para>Opens the Details window for the virtual machine you have
       highlighted in the list.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Delete machine</term>
     <listitem><para>Deletes the configuration of an inactive virtual machine you have
       highlighted in the list. Note that this does not touch the virtual
       machine's disk storage.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Preferences</term>
     <listitem><para>Brings up the <xref linkend="virt-manager-pref-window"/></para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>
  <sect2 id="virt-manager-view-menu">
   <title>View Menu Choices</title>
   <para>The View Menu choices toggle on and off the virtual machine list
    columns that are described above.</para>
  </sect2>
 </sect1>

 <sect1 id="virt-manager-details-window">
  <title>The Details Window</title> <para>On its Overview tab, the details
  window gives you a large view of the CPU and memory usage of a virtual
  machine. On a separate Hardware tab, it provides you with the details of the
  virtual hardware assigned to the machine. With sufficient privileges, you
  can add or remove CPUs, add or remove memory, and (soon) add and remove
  block devices and network devices. Finally, menu items allow you to pause
  and resume virtual machines, save a virtual machine to disk, and bring up
  the serial or graphical console for a virtual machine.</para>

  <sect2 id="virt-manager-details-window-menu">
   <title>Details Window Menus</title>
   <para>The menus in the Details window and the <link
     linkend="virt-manager-console-window">Console window</link> are very
    similar. The <guimenu>Virtual Machine</guimenu> menu gives you the
    following options:</para>
   <variablelist>
    <varlistentry><term>Run</term>
     <listitem><para><guisubmenu>Run</guisubmenu> starts the virtual machine,
       if it isn't already running. The <guibutton>Run</guibutton> button on
       the toolbar does the same thing.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Pause</term>
     <listitem><para><guisubmenu>Pause</guisubmenu> freezes the virtual
       machine, if it is running at the time. To unfreeze the machine, choose
       <guisubmenu>Pause</guisubmenu> again. The <guibutton>Pause</guibutton>
       button on the toolbar does the same thing.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Shutdown</term>
     <listitem><para><guisubmenu>Shutdown</guisubmenu> shuts the machine
       down, if it is running. For paravirtualized VMs, the hypervisor will
       attempt to gracefully shut down the VM; for fully virtualized VMs,
       <guisubmenu>Shutdown</guisubmenu> is equivalent to pulling the plug on
       the machine. The <guibutton>Shutdown</guibutton> button on the toolbar
       serves the same purpose.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Save</term>
     <listitem><para><guisubmenu>Save</guisubmenu> saves the machine's memory
       image to disk, shutting the machine down in the process. You can then
       <guisubmenu>Restore</guisubmenu> the machine from the <link
	linkend="virt-manager-mgr-window">Manager window</link> later. Note
       that if you really wish to preserve a VM in its saved state, you will
       also need a snapshot of the VM's disk image at the time you save
       it. If you start a VM that you have saved and then later attempt to
       restore the same VM using the same disk image, you will probably lose
       data or worse.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Destroy</term>
     <listitem><para><guisubmenu>Destroy</guisubmenu> is akin to pulling the
       plug on a machine, even for paravirtualized VMs. You may experience
       data loss, or worse. However, this command is useful if you have a wedged
       paravirtualized VM that you need to get rid of altogether.</para>
      </listitem>
    </varlistentry>
   </variablelist>
   <para>The <guimenu>View</guimenu> menu gives you the following
    options:</para>
   <variablelist>
    <varlistentry><term>Graphical Console</term>
     <listitem><para>The <guisubmenu>Graphical Console</guisubmenu> item pops up the
      graphical console for the VM, if one is available. The availability of a
      graphical console depends on whether the VM was created with graphics
      support available; if it was not, only the Serial Console will be
       available.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Serial Console</term>
     <listitem><para>The <guisubmenu>Serial Console</guisubmenu> item pops up
       the serial console window for the VM. It may not be available if the
       VM was created with graphics support available.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Toolbar</term>
     <listitem><para>The <guisubmenu>Toolbar</guisubmenu> item hides or shows
       the toolbar with Run/Pause/Shutdown buttons</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 id="virt-manager-details-window-vm-info">
   <title>Details Window Overview: Basic Details</title>

   <figure id="virt-manager-FIG-details-overview">
    <title>Details Window Overview</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/vm-details-overview.png" format="PNG"/>
      </imageobject>
      <textobject> <phrase>Shows a typical Details Window Overview tab.</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>

   <para>At the top of the Overview tab you will find the name, the UUID, and
    the status of the virtual machine you are examining. These are all
    read-only fields; the UUID should not change over the lifetime of the
    VM, and while the name of an inactive VM can change, there is no way to
    change it using <application>&app;</application> at this time.
   </para>
  </sect2>
  
  <sect2 id="virt-manager-details-performance">
   <title>Details Window Overview: Performance Information</title>
   <para>The details window also displays performance information, including
    the percentage of the physical host's CPU that the virtual machine is
    taking up, as well as the amount of physical RAM the virtual machine is using.</para>
  </sect2>
  
  <sect2 id="virt-manager-details-hardware">
   <title>Details Window Hardware</title>
   <para>The Details Window Hardware tab lets you view and, with appropriate
    permissions, change the virtual hardware allocated to a virtual
    machine. This includes the number of vcpus, the amount of memory, block
    devices, and network devices.</para>
   <note>
    <title>Virtual machine changes: Sometimes they persist, sometimes they
     don't</title>
    <para>The Hardware tab lets you make changes to active (running) VMs,
     and inactive VMs. Changes you make to inactive VMs are saved to the VM's
     config file and will persist over time. Changes you make to active VMs,
     by contrast, change the current settings for a VM, but will not be saved
     to the VM's config file. If you shut down a VM and restart it, it will
     restart with the last saved config.</para>
   </note>
  </sect2>

  <sect2 id="virt-manager-details-hardware-vcpus">
   <title>Details Window Hardware: VCPUs</title>

   <figure id="virt-manager-FIG-details-hardware-vcpu">
    <title>Details Window: VCPUs</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/vm-details-hardware-vcpu.png" format="PNG"/>
      </imageobject>
      <textobject> <phrase>Shows the VCPU pane in the Details Window.</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>

   <para>Choosing the <guilabel>Processor</guilabel> item in the list on the
    left of the Hardware tab brings up the <guilabel>Processor</guilabel>
    pane. This pane shows you the number of VCPUs the VM is currently using,
    as well as the number of physical cpus on the host, and the maximum number
    of VCPUs you can assign to this VM. If you have adequate privileges, you
    can set the number of VCPUs from one up to the maximum allowed.</para>
   
   <note>
    <title>VCPUs and paravirtualized VMs</title>
    <para>You can adjust the number of VCPUs for a running paravirtualized VM
     between 1 and the maximum set in the config file. It is not yet possible to
     adjust the number of VCPUs in a running, fully virtualized VM. The
     same limitation applies to memory adjustments (see below).</para>
   </note>

   <note>
    <title>Maximum VCPUs and inactive VMs</title>
    <para>If you are changing the VCPUs for a running VM, you are limited
     to a range from 1 to the maximum number of VCPUs in the VM's config when
     it was started. On the other hand, if you change the VCPUs for an
     inactive VM, you are limited only to a range from 1 to the maximum number
     of VCPUs your virtualization system will support (32, for
     example). Unless you have very specific reasons for doing so, it's
     probably not a good idea to set the maximum VCPUs larger than the number
     of physical processors on the machine, but
     <application>&app;</application> will let you, and the number you set
     will be saved to the inactive VM's config as both the maximum number of VCPUs, and
     the current number of VCPUs.</para>
   </note>
  </sect2>

  <sect2 id="virt-manager-details-hardware-memory">
   <title>Details Window Hardware: Memory</title> 

   <figure id="virt-manager-FIG-details-hardware-memory">
    <title>Details Window: Memory</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/vm-details-hardware-memory.png" format="PNG"/>
      </imageobject>
      <textobject> <phrase>Shows the Memory pane in the Details Window.</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>

   <para>Choosing the
   <guilabel>Memory</guilabel> item on the list on the left of the Hardware
   tab brings up the <guilabel>Memory</guilabel> pane. This pane shows you the
   amount of memory your VM is currently allocated, the maximum it can be
   allocated, and the amount of physical RAM on the machine. With adequate
   privileges, you can adjust the amount of memory your running VM is
   currently using, if your VM is <term>paravirtualized</term>. (It is not
   currently possible to adjust the memory allocation of a running, fully
   virtualized VM.) If your VM is not running, however, it is possible to
   adjust both the startup memory allocation and the maximum memory
    allocation.</para> 
  </sect2>
    
  <sect2 id="virt-manager-details-disk">
   <title>Details Window Hardware: Disk</title> 

   <figure id="virt-manager-FIG-details-hardware-disk">
    <title>Details Window: Disk</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/vm-details-hardware-disk.png" format="PNG"/>
      </imageobject>
      <textobject> <phrase>Shows the Disk pane in the Details Window.</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>

   <para>Choosing the <guilabel>Disk</guilabel> item on the list on the left
   of the Hardware tab displays the <guilabel>Disk</guilabel> pane. This
   displays all the virtual block devices your VM is aware of. In the future
   this pane will offer UI for adding and removing virtual block devices for a
   VM.
   </para>
  </sect2>

  <sect2 id="virt-manager-details-network">
   <title>Details Window Hardware: Network</title>

   <figure id="virt-manager-FIG-details-hardware-network">
    <title>Details Window: Network</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/vm-details-hardware-network.png" format="PNG"/>
      </imageobject>
      <textobject> <phrase>Shows the Network pane in the Details Window.</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>

   <para>Choosing the <guilabel>Network</guilabel> item on the list on the
    left of the Hardware tab displays the <guilabel>Network</guilabel>
    pane. This displays all the virtual network devices your VM is aware
    of. In the future this pane will offer UI for adding and removing virtual
    block devices for a VM.</para>
  </sect2>
 </sect1>
 
 <sect1 id="virt-manager-console-window">
  <title>The Console Window</title>
  <para>The Console window connects you to a VM's console, either in text mode
  or graphically depending on how the VM was installed.</para>

   <figure id="virt-manager-FIG-console-window">
    <title>Graphical Console Window</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/vm-graphic-console.png" format="PNG"/>
      </imageobject>
      <textobject> <phrase>Shows a graphical console window.</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>

  <sect2 id="virt-manager-console-menus">
   <title>Console Window Menus</title>
   <para>The menus for the Console window are identical to those for the <link
     linkend="virt-manager-details-window-menu">Details window</link>, with
    the following exceptions:</para>
   <itemizedlist>
    <listitem><para>The <guimenu>Virtual Machine</guimenu> menu adds an item
      <guimenuitem>Take Screenshot</guimenuitem> that lets you grab a
      screenshot of the VM's console.</para>
    </listitem>
    <listitem><para>The <guimenu>View</guimenu> menu adds an item
    <guimenuitem>Fullscreen</guimenuitem> that will enlarge the Console window
    to take up an entire screen, if you are using the graphical
    console.</para>
    </listitem>
   </itemizedlist>
  </sect2>
  <sect2 id="virt-manager-console-tips">
   <title>Console Window Tips</title>
   <para>Some useful things to know about using the Console window:</para>
   <itemizedlist>
    <listitem>
     <para>If you click your mouse anywhere in the graphical console window,
      the window will "grab" it and pop up a warning informing you it has done
      so. You can then use the mouse normally inside the console window. To
      "break out" of the window, press the key combination 
      <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap>
      </keycombo>.</para>
    </listitem>
    <listitem>
     <para>As of now, it is not possible to change the size of the console
      window. This capability depends on upstream work, although it should be
      available in a future release.</para>
    </listitem>
   </itemizedlist>
  </sect2>
 </sect1>

 <sect1 id="virt-manager-preferences-window">
  <title>The Preferences Window</title>
  <para>The Preferences window lets you customize certain of the application's
  behaviors. You can choose how frequently VM statistics are updated in the
   Manager and Details windows, choose the circumstances under which a console
  automatically appears, and finally choose how the console grabs your
   keyboard input.</para>
  
   <figure id="virt-manager-FIG-preferences-window">
    <title>Preferences Window</title>
    <screenshot>
     <mediaobject>
      <imageobject>
       <imagedata fileref="figures/vm-preferences.png" format="PNG"/>
      </imageobject>
      <textobject> <phrase>Shows a preferences window.</phrase>
      </textobject>
     </mediaobject>
    </screenshot>
   </figure>

  <sect2 id="virt-manager-pref-window-stats-refresh">
   <title>Preferences: Status Monitoring</title>
   <para>Here you can set how often your VM status graphs update. If you have
    a large number of VMs, you may want to consider increasing the interval in
    between status updates.</para>
  </sect2>

  <sect2 id="virt-manager-pref-window-consoles">
   <title>Preferences: Console Pop-up</title> <para>Here you can set the
   circumstances where you want <application>&app;</application> to pop up a
    Console window. The choices are:</para>
   <variablelist>
    <varlistentry><term>For all domains</term>
     <listitem><para>Pop up a Console window whenever a VM starts, including when
       <application>&app;</application> first starts up. This can be useful if
       you need to be sure you see what is happening right when starting a VM,
       but it's probably overkill for most situations.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>For new domains</term>
     <listitem><para>Pop up a Console window whenever a newly created domain
       starts. This is the default behavior; the application pops up a Console
       window for a newly created guest so that you can continue the guest
       install.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Never</term>
     <listitem><para>Never pop up a Console window automatically. With this
       choice you will have to manually start a Console window for any domain
       you want to connect to, by double-clicking on the domain in the <link
	linkend="virt-manager-mgr-window">Manager window</link>.</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 id="virt-manager-pref-window-grab-kbd">
   <title>Preferences: Grab Keyboard</title>
   <para>By default the Console window will grab input from your keyboard
    whenever you position your mouse pointer over it. You may also choose
    <guimenuitem>When fullscreen</guimenuitem> to grab keyboard input only
    when the Console window is full screen, or
    <guimenuitem>Never</guimenuitem>.
   </para>
  </sect2>
 </sect1>

 <sect1 id="virt-manager-create-wizard">
  <title>The Create Wizard</title>
  <para>The Create Wizard helps you gather the information necessary to create
  new virtual machines. All the information in each screen is retained and can
  be backed-up-to and modified until you click <guibutton>Finish</guibutton>
   on the last screen.</para>
  <sect2 id="virt-manager-system-name">
   <title>The System Name screen</title>
   <para>Choose a name for your virtual system. The name must be non-blank,
    alphanumeric (plus underscores), contain at least one letter, and be less
    than 50 characters.</para>
  </sect2>

  <sect2 id="virt-manager-virt-method">
   <title>The Virtualization Method screen</title>
   <para>Choose a virtualization method for your new system. The choices
    are:</para>
   <variablelist>
    <varlistentry><term>Paravirtualized</term> <listitem><para>A
       paravirtualized system typically performs better than a fully virtualized
       system because certain operations &mdash; disk and network access, for
       example &mdash; have direct access to the hardware. However a
       paravirtualized VM requires a specially modified kernel. If you
       choose paravirtualized, you must make sure this specially modified kernel
       is available for the operating system you wish to install.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>Fully Virtualized</term>
     <listitem>
      <para>A fully virtualized system simulates all the hardware for the VM,
       permitting no direct access. It allows for a greater range of operating
       systems, but generally will not perform as well as a paravirtualized
       system. Note that for some hypervisor types, full virtualization requires
       hardware support. In addition if your hardware allows it, you can
       enable hardware acceleration for your fully virtualized guest (this
       item will be grayed out unless your hardware is acceleration-capable).</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 id="virt-manager-installation-media">
   <title>The Installation Media screens</title>
   <para>The Installation Media screens let you specify where the physical or
    virtual install media for your VM are located, so that the installer can
    find them. There are two screens, one for each type of virtual
    machine.</para>
   <sect3 id="virt-manager-installation-media-paravirt">
    <title>Paravirtualized installation media</title>
    <figure id="virt-manager-FIG-paravirt-media">
     <title>Choose Install Media for Paravirtualized VMs</title>
     <screenshot>
      <mediaobject>
       <imageobject>
	<imagedata fileref="figures/vm-paravirt-media.png" format="PNG"/>
       </imageobject>
       <textobject> <phrase>Shows the paravirtualized VM media choice window.</phrase>
       </textobject>
      </mediaobject>
     </screenshot>
    </figure>
    <para>A paravirtualized VM requires an install tree that follows the
     pattern of the Fedora install tree (e.g. <ulink type="http"
      url="http://download.fedora.redhat.com/pub/fedora/linux/core/6/i386/os/">
      this tree</ulink>). The <guilabel>Install Media URL</guilabel> box lets
     you enter a URL for a tree like this. When you then go to install the
     guest, the installer will check to see if the URL you entered is
     readable, and if so download the paravirtualized install kernel and
     initrd that it will need to start the install. You can use the following
     URL types:</para>
    <variablelist>
     <varlistentry><term>http:</term>
      <listitem><para>e.g. <userinput>http://download.fedora.redhat.com/pub/fedora/linux/core/6/i386/os/</userinput></para>
      </listitem>
     </varlistentry>
     <varlistentry><term>ftp:</term>
      <listitem><para>e.g. <userinput>ftp://download.fedora.redhat.com/pub/fedora/linux/core/6/i386/os/</userinput></para>
      </listitem>
     </varlistentry>
     <varlistentry><term>nfs:</term>
      <listitem><para>e.g. <userinput>nfs:myfileserver:/images/linux/core/6/i386/os/</userinput></para>
      </listitem>
     </varlistentry>
     <varlistentry><term>local file:</term>
      <listitem><para>e.g. <userinput>/tmp/paravirttrees/fedora/os</userinput>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
    <para>You can specify a kickstart URL for your paravirtualized VM in
     exactly the same way as the install tree described
     above. <application>&app;</application> will remember the last 5 URLs you
     enter in these windows, so if you are installing multiple VMs you will
     not have to type the URLs more than once.
    </para>
   </sect3>
   <sect3 id="virt-manager-installation-media-full-virt">
    <title>Fully Virtualized Installation Media</title>
    <figure id="virt-manager-FIG-full-virt-media">
     <title>Choose Install Media for Fully Virtualized VMs</title>
     <screenshot>
      <mediaobject>
       <imageobject>
	<imagedata fileref="figures/vm-full-virt-media.png" format="PNG"/>
       </imageobject>
       <textobject> <phrase>Shows the fully virtualized VM media choice window.</phrase>
       </textobject>
      </mediaobject>
     </screenshot>
    </figure>
    <para>A fully virtualized VM requires the standard installation media that
     the same non-virtualized OS would require: either an actual CD or DVD, or
     a corresponding ISO image. On the Installation Media screen for a fully
     virtualized VM, you can therefore choose the path to your CD or DVD from
     the pull-down list, or you can enter or browse to the path of the ISO
     image you have saved in your local filesystem.</para>
    <para>For fully virtualized VMs, <application>&app;</application> also
     asks for the operating system type and variant you are installing. The
     installer uses this to set the <parameter>acpi</parameter> and
     <parameter>apic</parameter> flags according to the OS type (other
     parameters may be added to this list in the future).</para>
   </sect3>
  </sect2>

  <sect2 id="virt-manager-storage-space">
   <title>Assigning Storage Space</title>
    <figure id="virt-manager-FIG-assign-storage">
     <title>Assign Storage</title>
     <screenshot>
      <mediaobject>
       <imageobject>
	<imagedata fileref="figures/vm-assign-storage.png" format="PNG"/>
       </imageobject>
       <textobject> <phrase>Shows the Assigning Storage window.</phrase>
       </textobject>
      </mediaobject>
     </screenshot>
    </figure>

   <para>Designate the primary storage device for your VM. You may choose an
    existing physical or LVM partition in the <guilabel>Partition</guilabel>
    box; or, you may choose to use a file on the local filesystem. If you
    choose to use a file that does not already exist, you may specify the size
    of the file in megabytes. If you choose an existing file, that file's size
    will not change. If you use a file for your primary storage device, you
    may also choose whether to allocate the entire file
    at creation time, or whether to allow it to grow to its maximum over
    time.</para>
   <warning>
    <title>Sparse files can be dangerous</title>
    <para>You may be tempted not to allocate your entire file when your VM is
     created; filling a 5- to 10-GB file with 0s can take quite a while, and
     you will avoid this wait by not allocating the entire file and instead using a
     "sparse" file. However, be aware that this will slow down your VM's disk
     performance significantly, as the underlying OS must keep allocating more
     storage space as your VM runs. In addition, if the disk your sparse file
     is on runs out of space, your VM may crash and lose data. You may
     therefore only want to use a sparse file when testing, where guest
     creation speed could be at a premium.</para>
   </warning>
  </sect2>

  <sect2 id="virt-manager-memory-and-cpu">
   <title>Allocate Memory And CPU</title>
   <figure id="virt-manager-FIG-mem-cpu">
     <title>Set Memory and CPU</title>
     <screenshot>
      <mediaobject>
       <imageobject>
	<imagedata fileref="figures/vm-create-mem-cpu.png" format="PNG"/>
       </imageobject>
       <textobject> <phrase>Shows the VM Memory and CPU choice window.</phrase>
       </textobject>
      </mediaobject>
     </screenshot>
    </figure>
   <para>The <guilabel>Memory</guilabel> section of this screen lets you set
    two parameters, <guilabel>VM Max Memory</guilabel> and <guilabel>VM
     Startup Memory</guilabel>. These settings work as follows:</para>
   <variablelist>
    <varlistentry><term>VM Max Memory</term> <listitem><para><guilabel>VM Max
	Memory</guilabel> sets the maximum memory your VM can have unless you
       reboot it with a higher setting. For paravirtualized VMs, the maximum
       memory is a boot-time kernel setting; for fully virtualized VMs, the
       maximum memory appears to the VM to be the amount of physical memory
       available.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>VM Startup Memory</term>
     <listitem><para>For paravirtualized VMs, <guilabel>VM Startup
	Memory</guilabel> sets the amount of memory to start the VM with. The
       VM's available memory can then be changed from <application>&app;</application>
       while the VM is running. For fully virtualized guests, this setting has
       no effect.</para>
     </listitem>
    </varlistentry>
   </variablelist>
   <para>The virtual CPU section of this screen lets you set the number of
    vCPUs your VM starts up with. For paravirtualized guests, this number can
    be changed while the guest is running (although never to more than the VM
    started with). For fully virtualized guests, this number can only be
    changed while the guest is not running.</para>
  </sect2>

  <sect2 id="virt-manager-validation">
   <title>Validation</title>
   <para>The Validation screen lets you verify the setup for your new
    system. If you need to, you can back up and
    make changes. Clicking &quot;Finish&quot; will begin creating your virtual
    machine. If you have the <application>&app;</application> preferences set
    to automatically open consoles, a <link
     linkend="virt-manager-console-window">Console window</link> will pop up
    as soon as the installer has downloaded the necessary images and booted
    the VM's installer.
   </para>
  </sect2>
 </sect1>

</article>