path: root/en-US/Tools.xml

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Virtualization_Getting_Started_Guide.ent">
%BOOK_ENTITIES;
]>

<chapter>
   <title>Virtualization Tools</title>
    
   <para>
      Read this chapter for an introduction to the many tools available to assist
      with virtualization.
   </para>
   
   <section>
      <title><command>virsh</command></title>
      <para>
	<firstterm>virsh</firstterm> is a command line interface (CLI) tool for managing guests and the hypervisor. The <command>virsh</command> command-line tool is built on the <application>libvirt</application> management API and operates as an alternative to the <command>qemu-kvm</command> command and the graphical <application>virt-manager</application> application. The <command>virsh</command> command can be used in read-only mode by unprivileged users or, with root access, full administration functionality. The <command>virsh</command> command is ideal for scripting virtualization administration. In addition the <command>virsh</command> tool is a main management interface for <command>virsh</command> guest domains and can be used to create, pause, and shut down domains, as well as list current domains. This tool is installed as part of the <package>libvirt-client</package> package.
      </para>
	  <note>
	      <para>
		Refer to the <citetitle>Red Hat Enterprise Linux&nbsp;6 Virtualization Administration Guide</citetitle> for more information about managing virtual machines with <command>virsh</command>.
	      </para>
	  </note>
   </section>
   
   <section>
      <title><command>virt-manager</command></title>
      <para>
         A light-weight graphical tool for managing virtual machines. It provides the ability 
         to control the life cycle of existing machines, provision new machines,
         manage virtual networks, access the graphical console of virtual 
         machines, and view performance statistics. This tool ships in its own
         package called <package>virt-manager</package>.
      </para>
	    <note>
	      <para>
		Refer to the <citetitle>Red Hat Enterprise Linux&nbsp;6 Virtualization Administration Guide</citetitle> for more information about managing virtual machines with <command>virt-manager</command>.
	      </para>
	    </note>
   </section>
   
   <section>
      <title><command>virt-install</command></title>
      <para>
         A command line tool to provision new virtual machines. It supports both
	 text-based and graphical installations, using serial console, SDL, SPICE, or VNC client/server pair graphics. Installation media can be local,
         or exist remotely on an NFS, HTTP, or FTP server. The tool can also be
         configured to run unattended and kickstart the guest when installation is
         complete, allowing for easy automation of installation. This tool is
         installed as part of the <package>python-virtinst</package> package.
       </para>
	      <note>      
		<para>
		  Refer to the <citetitle>Red Hat Enterprise Linux&nbsp;6 Virtualization Host Configuration and Guest Installation Guide</citetitle> for more information about <command>virt-install</command>.
	      </para>
	    </note>
   </section>
   
   <section>
      <title><command>guestfish</command></title>
      <para>
         A command line tool for examining and modifying the file systems of
         the host. This tool uses <package>libguestfs</package> and
         exposes all functionality provided by the <literal>guestfs</literal> API.
         This tool ships in its own package entitled <package>guestfish</package>.
      </para>
      <para>
         Refer to the <citetitle>Red Hat Enterprise Linux&nbsp;6 Virtualization Administration Guide</citetitle> for more information about <command>guestfish</command>.
      </para>
      <warning>
         <para>
            Using <command>guestfish</command> on running virtual machines can
            cause disk-image corruption. Use the <command>guestfish</command> command with the <option>--ro</option> (read-only)
            option if the disk image is being used by a running virtual machine.
         </para>
      </warning>
   </section>
   
   
   <section>
      <title>Other useful tools</title>
      <para>The following tools are used to access a virtual machine's disk via the host. The guest's disk is usually accessed directly via the <filename>disk-image</filename> file located on the host. However it is sometimes possible to gain access via the <application>libvirt</application> domain. The commands that follow are part of the <application>libvirt</application> domain and are used to gain access to the guest's disk image.</para>

   <variablelist>
      <varlistentry>
       <term><command>guestmount</command></term>
       <listitem>
          <para>
            A command line tool used to mount virtual machine file systems and disk
	   images on the host machine. This tool is installed as part of the <package>libguestfs-mount</package> package.
          </para>
          <warning>
             <para>
		Using <command>guestmount</command> in <option>--r/w</option> read/write mode to access a disk that is currently being used by a guest can cause the disk to become corrupted. Do not use <command>guestmount</command> in <option>--r/w</option> read/write mode on live virtual machines. Use the <command>guestmount</command> command with the <option>--ro</option> (read-only)
            option if the disk image is being used.
             </para>
          </warning>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-cat</command></term>
       <listitem>
          <para>
             A command line tool that can be used to quickly view the contents of 
             one or more files in a specified virtual machine's disk or disk image. This
             tool is installed as part of the <package>libguestfs-tools</package>
             package
          </para>
          <warning>
             <para>
                Using <command>virt-cat</command> on running virtual machines can
                cause disk corruption in the virtual machine. Do not use
                <command>virt-cat</command> command on a running virtual machine.
             </para>
          </warning>
       </listitem>
      </varlistentry>
      <!-- All released versions problematic; being rewritten upstream.
      <varlistentry>
       <term><command>virt-clone</command></term>
       <listitem>
          <para>
             Clone a VM.
          </para>
       </listitem>
      </varlistentry>-->
      <!-- This tool is obsolete and problematic.  Use virt-v2v instead.
      <varlistentry>
       <term><command>virt-convert</command></term>
       <listitem>
          <para>
             Convert a VM disk image.
          </para>
       </listitem>
      </varlistentry>-->
      <varlistentry>
       <term><command>virt-df</command></term>
       <listitem>
          <para>
             A command line tool used to show the actual physical disk usage of 
             virtual machines. Similar to the command line tool <command>df</command>.
             Note that this tool does not work across remote connections. It is
             installed as part of the <package>libguestfs-tools</package> package.
          </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-edit</command></term>
       <listitem>
          <para>
            A command line tool used to edit files that exist on a specified virtual
            machine. This tool is installed as part of the 
            <package>libguestfs-tools</package> package.
          </para>
	<warning>
             <para>
                Using <command>virt-edit</command> on live virtual machines can
                cause disk corruption in the virtual machine. 
                Although the <command>virt-edit</command> command will try to prevent users from editing
                files on live virtual machines, it is not guaranteed to catch all instances.
                Therefore, do not use <command>virt-edit</command> on a live virtual machine.
             </para>
          </warning>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-filesystems</command></term>
       <listitem>
         <para>
            A command line tool used to discover file systems, partitions, logical
            volumes and their sizes in a disk image or virtual machine. One common
            use is in shell scripts, to iterate over all file systems in a disk 
            image. This tool is installed as part of the 
            <package>libguestfs-tools</package> package.
	  </para>
	  <para>
	    This tool replaces <command>virt-list-filesystems</command> and
	    <command>virt-list-partitions</command>.
	  </para>
      </listitem>
      </varlistentry>
      <varlistentry>
      <term><command>virt-inspector</command></term>
      <listitem>
          <para>
             A command line tool that can examine a virtual machine or disk image to
             determine the version of its operating system and other information.
             It can also produce XML output, which can be piped into other programs.
             Note that <command>virt-inspector</command> can only inspect one domain
             at a time. This tool is installed as part of the 
             <package>libguestfs-tools</package> package.
         </para>
      </listitem>
      </varlistentry>
      <varlistentry>
	<term><command>virt-inspector2</command></term>
      <listitem>
          <para>
	    An alternative tool to <command>virt-inspector</command>, written in C. This tool is installed as part of the <package>libguestfs-tools</package> package.
	  </para>
      </listitem>
      </varlistentry>
      <varlistentry>
      <term><command>virt-ls</command></term>
      <listitem>
         <para>
            A command line tool that lists files and directories inside a virtual
            machine. This tool is installed as part of the 
            <package>libguestfs-tools</package> package.
          </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-make-fs</command></term>
       <listitem>
          <para>
             A command line tool for creating a file system based on a tar archive
             or files in a directory. It is similar to tools like 
             <command>mkisofs</command> and <command>mksquashfs</command>, but it
             can create common file system types such as ext2, ext3 and NTFS, and 
             the size of the file system created can be equal to or greater than the
             size of the files it is based on. This tool is provided as part of the 
             <package>libguestfs-tools</package> package.
          </para>
       </listitem>
      </varlistentry>
      <!-- wont make 6.2 
      <varlistentry>
       <term><command>virt-p2v</command></term>
       <listitem>
         <para>
            A graphical tool to convert physical machines into virtual machines.
            This tool is installed as part of the <package>virt-v2v</package> package
            in Red Hat Enterprise Linux 6.2 and later.
         </para>
       </listitem>
     </varlistentry>-->
      <varlistentry>
       <term><command>virt-rescue</command></term>
       <listitem>
          <para>
             A command line tool that provides a rescue shell and some simple
             recovery tools for unbootable virtual machines and disk images. It can
             be run on any virtual machine known to <application>libvirt</application>, or directly on disk
             images. This tool is installed as part of the 
             <package>libguestfs-tools</package> package.
          </para>
          <warning>
             <para>
                Using <command>virt-rescue</command> on running virtual machines can
                cause disk corruption in the virtual machine. 
                <command>virt-rescue</command> attempts to prevent its own use on
                running virtual machines, but cannot catch all cases.
             </para>
             <para>
                Using the command with the <option>--ro</option> (read-only) option
                will not cause disk corruption, but may give strange or inconsistent
                results. It is better to avoid using <command>virt-rescue</command>
                on a running virtual machine.
             </para>
          </warning>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-resize</command></term>
       <listitem>
          <para>
             A command line tool to resize virtual machine disks, and resize or 
             delete any partitions on a virtual machine disk. It works by copying the guest image and leaving the original disk image untouched. This tool is installed as part of the 
             <package>libguestfs-tools</package> package.
          </para>
	<important>
             <para>
                Using <command>virt-resize</command> on running virtual machines can
                give inconsistent results. It is best to shut down virtual machines
                before attempting to resize them.
             </para>
          </important>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-tar</command></term>
       <listitem>
      <!--This is obsolete upstream, but we haven't shipped the replacement tools
      in RHEL yet.  Probably we will obsolete it in and ship replacements in
      RHEL 6.3.-->
          <para>
            A command line archive tool for downloading and uploading parts of a
            virtual machine's file system. This tool is commonly used for making backups, 
            uploading data, reviewing guest activity, and fixing or customizing 
            guests. This tool is installed as part of the 
            <package>libguestfs-tools</package> package.
          </para>
          <warning>
             <para>
                Using <command>virt-tar</command> with the <option>-u</option> 
                (upload) option on running virtual machines can cause disk corruption
                in the virtual machine. <command>virt-tar</command> attempts to 
                prevent its own use on running virtual machines, but cannot catch 
                all cases.
             </para>
             <para>
                Using <command>virt-tar</command> with the <option>-x</option> 
                (extract) option on running virtual machines will not cause disk 
                corruption, but may give strange or inconsistent results. It is best 
                to shut down virtual machines before attempting to extract files from
                them.
             </para>
          </warning>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-top</command></term>
       <listitem>
          <para>
             A command line utility similar to <command>top</command>, which shows
             stats related to virtualized domains. This tool ships in its own package:
             <package>virt-top</package>.
          </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-v2v</command></term>
       <listitem>
          <para>
            A graphical tool to convert virtual machines from Xen and VMware hypervisors
            to run on KVM. This tool ships in its own package: 
            <package>virt-v2v</package>.
          </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-viewer</command></term>
       <listitem>
          <para>
            A minimal tool for displaying the graphical console of a virtual machine via
            the VNC and SPICE protocols. This tool ships in its own package: 
            <package>virt-viewer</package>.
          </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-what</command></term>
       <listitem>
          <para>
            A shell script that detects whether a program is running in a virtual machine.
            This tool ships in its own package: <package>virt-what</package>.
          </para>
       </listitem>
      </varlistentry>
      <varlistentry>
	<term><command>virt-who</command></term>
	<listitem>
	  <para>
	    The <package>virt-who</package> package is a Red Hat Enterprise Linux host agent that queries <application>libvirt</application> for guest UUIDs. It then passes that data to the local entitlement server for the purposes of issuing certificates. This tool ships in its own package: <package>virt-who</package>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-win-reg</command></term>
       <listitem>
          <para>
            A command line tool to export and merge Windows Registry entries from a
            Windows guest, and perform simple Registry operations. This tool is installed 
            as part of the <package>libguestfs-tools</package> package.
          </para>
          <warning>
             <para>
                Using <command>virt-win-reg</command> on running virtual machines will
                cause irreversible disk corruption in the virtual machine.
                <command>virt-win-reg</command> attempts to prevent its own use on 
                running virtual machines, but cannot catch all cases.
             </para>
          </warning>
          <warning>
             <para>
                Modifying the Windows Registry is an inherently risky operation, as the
                format is deliberately obscure and undocumented. Changes to the registry 
                can leave the system unbootable, so ensure you have a reliable backup
                before you use the <option>--merge</option> option.
             </para>
          </warning>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><command>virt-xml-validate</command></term>
       <listitem>
          <para>
            A command line tool to validate <application>libvirt</application> XML files for compliance with the
            published schema. This tool is installed as part of the
            <package>libvirt-client</package> package.
          </para>
       </listitem>
      </varlistentry>
   </variablelist>
</section>
    
</chapter>