[% topdir = "../.." -%]
[% PROCESS globals -%]
[% WRAPPER page
   title = "List virtual machines using the command line"
   h1 = "List virtual machines using the command line"
   section = "learning"
%]

<p>
Open a Terminal window.
</p>

<p>
On Fedora and Debian you will need to become root.  Type
the following command and, when prompted, your root password:
</p>

<pre>
su
</pre>

<p>
Then you can list all the virtual machines:
</p>

<pre>
virsh list --all
</pre>

<p>
On Ubuntu, you should use <code>sudo</code> to run the command
as root instead:
</p>

<pre>
sudo virsh list --all
</pre>

[% WRAPPER h2 h2="virsh list output explained" anchor="virsh-list-output" %]

<p>
When you run the command you should see a listing like this:
</p>

<pre>
 Id Name                 State
----------------------------------
  3 FedoraRawhide        running
  - Debian               shut off
</pre>

<p>
The three columns are:
</p>

<ul>
<li> <code>Id</code>: A unique number given to running virtual machines.
</li>
<li> <code>Name</code>: The name of the VM, which you specified when
  it was created.
</li>
<li> <code>State</code>: The state which is <q>shut off</q> for
  VMs that are switched off, and various other states for
  running and paused VMs.
</li>
</ul>

<p>
Other virt tools commands can use either the <code>Id</code> or the
<code>Name</code> to refer to the virtual machine.  For example
these two commands are equivalent ways to show the console:
</p>

<pre>
virt-viewer 3
virt-viewer FedoraRawhide
</pre>

[% END %]

[% WRAPPER h2 h2="virsh list troubleshooting" anchor="virsh-list-troubleshooting" %]

<p>
If <code>virsh list</code> displays an error, then try
searching for the error or <a href="[% topdir %]/contact/">contacting us</a>.
For QEMU, KVM, and remote connections, ensure that the
<code>libvirtd</code> service is running.
</p>

<p>
Many errors are obvious from the error message, for example:
</p>

<pre>
error: no connection driver available for xen:///
error: failed to connect to the hypervisor
</pre>

<p>
would mean that the Xen hypervisor is not running on the
local machine.
</p>

<p>
If <code>virsh list --all</code> runs but displays nothing, it
could mean:
</p>

<ul>
<li> You haven't installed any guests. </li>
<li> You forgot the <code>--all</code> flag. </li>
<li> (For QEMU and KVM) Guests are running but were not started up
  by libvirt.  For example you might have started them by running
  the <code>qemu</code> command directly. </li>
</ul>

[% END %]

[% WRAPPER h2 h2="virsh flags" anchor="virsh-flags" %]

<p>
The <code>--all</code> flag lists all virtual machines, which
includes ones which are currently running and ones which are
switched off.  If you omit this flag then only running virtual
machines are shown.
</p>

<p>
Another useful flag is <code>-c</code> which can be used to
select the hypervisor.  This can be used if you are running
two hypervisors on one machine (eg. Xen and QEMU guests),
or if you are not root and want to connect to the system
hypervisor, or to connect to a remote server running libvirtd.
</p>

<p>
Use the <code>-r</code> flag to connect read-only to the hypervisor.
This is useful to perform operations while not requiring the
root password.
</p>

<p>
For example, if you are not root and want to list QEMU and KVM guests
without needing the root password you could do:
</p>

<pre>
virsh -r -c qemu:///system list --all
</pre>

<p>
<a href="http://libvirt.org/remote.html">This libvirt documentation
describes remote connections</a> in detail.
</p>

[% END %]



[% END -%]