1 files changed, 160 insertions, 0 deletions
diff --git a/website/src/learning/start-list-with-command-line/index.html b/website/src/learning/start-list-with-command-line/index.html
new file mode 100644
index 0000000..3fe5deb
--- /dev/null
+++ b/website/src/learning/start-list-with-command-line/index.html
@@ -0,0 +1,160 @@
+[% 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/">This libvirt documentation describes
+remote connections</a> in detail.
+</p>
+
+[% END %]
+
+
+
+[% END -%]