virt-tools website using Template Toolkit (incomplete).

28 files changed, 1256 insertions, 0 deletions

diff --git a/website/src/learning/advanced-virt-df/df-centos-graph.png b/website/src/learning/advanced-virt-df/df-centos-graph.png
new file mode 100644
index 0000000..9d32a53
--- /dev/null
+++ b/website/src/learning/advanced-virt-df/df-centos-graph.png
diff --git a/website/src/learning/advanced-virt-df/df-openoffice-sorted.png b/website/src/learning/advanced-virt-df/df-openoffice-sorted.png
new file mode 100644
index 0000000..50d2d6e
--- /dev/null
+++ b/website/src/learning/advanced-virt-df/df-openoffice-sorted.png
diff --git a/website/src/learning/advanced-virt-df/df-openoffice.png b/website/src/learning/advanced-virt-df/df-openoffice.png
new file mode 100644
index 0000000..4d5c587
--- /dev/null
+++ b/website/src/learning/advanced-virt-df/df-openoffice.png
diff --git a/website/src/learning/advanced-virt-df/index.html b/website/src/learning/advanced-virt-df/index.html
new file mode 100644
index 0000000..c8840f0
--- /dev/null
+++ b/website/src/learning/advanced-virt-df/index.html
@@ -0,0 +1,193 @@
+[% topdir = "../.." -%]
+[% PROCESS globals -%]
+[% WRAPPER page
+   title = "Advanced use of virt-df"
+   h1 = "Advanced use of virt-df"
+   section = "learning"
+%]
+
+<p>
+This tutorial discusses advanced use of
+<a href="http://www.libguestfs.org/virt-df.1.html">virt-df</a>.
+Some of the topics covered are:
+</p>
+
+<ul>
+<li> Using CSV output to import data into spreadsheets, databases
+  and monitoring tools. </li>
+<li> Graphing and using trends to predict future disk usage of guests. </li>
+<li> Generating alerts when virtual machines are near to running
+  out of disk space. </li>
+<li> Using virt-df safely with untrusted and malicious guests. </li>
+</ul>
+
+[% WRAPPER h2 h2="CSV output" anchor="csv" %]
+
+<p>
+If you are going to do anything apart from looking at the output of
+virt-df, you should use the <code>--csv</code> flag so that virt-df
+produces machine-readable
+<a href="http://en.wikipedia.org/wiki/Comma-separated_Values">comma-separated
+values (CSV)</a> output.  The output looks like this:
+</p>
+
+<pre>
+# <b>virt-df --csv</b>
+Virtual Machine,Filesystem,1K-blocks,Used,Available,Use%
+"CentOS5x64","/dev/sda1",101086,19290,76577,19.1%
+"CentOS5x64","/dev/VolGroup00/LogVol00",8030648,3116144,4499992,38.8%
+<i>[etc]</i>
+</pre>
+
+[% END %]
+
+[% WRAPPER h2 h2="Using cron" anchor="cron" %]
+
+<p>
+You can write a cron job to collect virt-df output periodically
+(I collect it once a day).
+</p>
+
+<pre>
+# <b>cat &gt; /etc/cron.daily/local-virt-df</b>
+#!/bin/bash -
+date=$(date +%F)
+virt-df --csv &gt; /var/local/virt-df.$date
+# <b>chmod 0755 /etc/cron.daily/local-virt-df</b>
+</pre>
+
+<p>
+The cron job will create one file every day in <code>/var/local</code>.
+</p>
+
+[% END %]
+
+[% WRAPPER h2
+   h2="Importing the data into spreadsheets and databases" anchor="import" %]
+
+<p>
+CSV files can be loaded directly into spreadsheets and databases:
+</p>
+
+<p>
+<img src="df-openoffice.png" width="721" height="642"
+  longdesc="Screenshot showing virt-df output in OpenOffice Calc"/>
+</p>
+
+<pre>
+<b>CREATE TABLE df_data (
+  "Virtual Machine" TEXT NOT NULL,
+  "Filesystem" TEXT NOT NULL,
+  "1K-blocks" BIGINT NOT NULL,
+  "Used" BIGINT NOT NULL,
+  "Available" BIGINT NOT NULL,
+  "Use%" TEXT
+);</b>
+<b>COPY df_data FROM 'df.csv' WITH DELIMITER ',' CSV HEADER;</b>
+</pre>
+
+[% END %]
+
+[% WRAPPER h2 h2="Sorting and querying the data" anchor="query" %]
+
+<p>
+Once your data has been imported, you can start to process it,
+for example finding out which virtual machines are running
+out of space:
+</p>
+
+<p>
+<img src="df-openoffice-sorted.png" width="653" height="143"
+  longdesc="Screenshot showing virt-df output in OpenOffice Calc"/>
+</p>
+
+<p>
+The following PostgreSQL query on the previously imported data
+shows all filesystems with over 60% usage:
+</p>
+
+<pre>
+<b>SELECT "Virtual Machine", "Filesystem"
+  FROM df_data
+ WHERE (100. * "Used" / "1K-blocks") &gt; 60;</b>
+
+ Virtual Machine |              Filesystem              
+-----------------+--------------------------------------
+ Debian5x64      | /dev/debian5x64.home.annexia.org/usr
+ OpenSUSE11x64   | /dev/sda2
+ VBox            | /dev/vg_f13x64/lv_root
+(3 rows)
+</pre>
+
+[% END %]
+
+[% WRAPPER h2 h2="Graphs and trends" anchor="graphs" %]
+
+<p>
+You can use daily historical data to graph disk usage.
+In theory at least you could use trends in this data
+to predict future requirements, although in my experience
+usage tends to be <q>lumpy</q> &mdash; installing OpenOffice
+in a VM results in a big increase in usage which is not
+indicative of any trend.
+</p>
+
+<p>
+In any case, here is a graph of usage data for one VM filesystem
+over approximately one month, generated using OpenOffice Calc
+(Insert&nbsp;&rarr;&nbsp;Chart) with a linear trend line
+(select chart and do Insert&nbsp;&rarr;&nbsp;Trend&nbsp;Lines):
+</p>
+
+<p>
+<img src="df-centos-graph.png" width="583" height="340"
+  longdesc="Output of virt-df for one VM graphed over one month" />
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Alerts" anchor="alerts" %]
+
+
+
+
+
+
+
+
+
+[% END %]
+
+[% WRAPPER h2 h2="Safety" anchor="safety" %]
+
+<p>
+virt-df is generally safe to use with untrusted or malicious guests,
+but there are some things to be aware of.
+</p>
+
+<p>
+An untrusted guest can present any disk data that it wants
+to the host.  By simple manipulations of the filesystem it can show
+the disk as full when it is empty, or empty when it is full.  This
+is not important in itself, it only becomes an issue if a guest
+could manipulate the statistics of another unrelated VM.
+</p>
+
+<p>
+Older versions of virt-df ran a separate libguestfs appliance for each
+guest.  This is safe because one guest cannot possibly interfere with
+the statistics from another, but also slow.  Since virt-df 1.5.0,
+several unrelated guests may share a single libguestfs appliance,
+which is much faster but there is a (slim) possibility that one guest
+might corrupt the appliance leading to misreported statistics for
+another guest.
+</p>
+
+<p>
+You can get the old, safest possible behaviour by adding
+the <code>--one-per-guest</code> flag to the virt-df command line.
+</p>
+
+[% END %]
+
+[% END -%]
diff --git a/website/src/learning/check-hardware-virt/index.html b/website/src/learning/check-hardware-virt/index.html
new file mode 100644
index 0000000..11160cd
--- /dev/null
+++ b/website/src/learning/check-hardware-virt/index.html
@@ -0,0 +1,56 @@
+[% topdir = "../.." -%]
+[% PROCESS globals -%]
+[% WRAPPER page
+   title = "How to check if your hardware supports virtualization"
+   h1 = "How to check if your hardware supports virtualization"
+   section = "learning"
+%]
+
+[% WRAPPER h2 h2="Hardware virtualization technologies" anchor="hvm" %]
+
+<p>
+The first machines to support virtualization were IBM mainframes
+in the 1970s.
+XXXXXXXXXXX BACKGROUND XXXXXXXXXXXX
+</p>
+
+<p>
+Until a few years ago the central processors in server PCs were not
+<a href="http://XXX">virtualizable</a> except by using slow
+emulation or tricks.  However both AMD and Intel have recently
+produced processors which include extra modes and instructions
+that allow full, hardware-accelerated virtualization.
+</p>
+
+<p>
+AMD and Intel's virtualization techniques are different and
+incompatible, but all hypervisors hide the differences from you.
+</p>
+
+<p>
+There are also several generations of virtualization technologies
+available.  Initial implementations from both AMD and Intel were quite
+slow, and great improvements have been made over time.  This article
+does not talk about all these variations since the differences are
+mostly hidden from the end user.  The upshot is that more modern
+processors are not only faster, but the virtualization will be more
+efficient too.
+</p>
+
+[% END %]
+
+XXX XXX XXX
+[%#
+- look up model number on Intel's site
+- dmesg
+- disabled in BIOS
+- kvm_* module loaded
+- Ubuntu virt tool?
+%]
+
+
+
+
+
+
+[% END -%]
diff --git a/website/src/learning/index.html b/website/src/learning/index.html
new file mode 100644
index 0000000..af267cb
--- /dev/null
+++ b/website/src/learning/index.html
@@ -0,0 +1,73 @@
+[% topdir = ".." -%]
+[% PROCESS globals -%]
+[% WRAPPER page
+   title = "virt tools: Tutorials and videos"
+   h1 = "virt tools: Tutorials and videos"
+   section = "learning"
+   local_stylesheet = 1
+%]
+
+[% WRAPPER h2 h2="For absolute beginners, start here" anchor="beginners" %]
+
+[% BLOCK element %]
+<li>
+  <a href="[% x.name %]/">[% x.link %]</a>
+  [% x.rest %]
+  <span class="notes">
+  [% IF x.difficulty > 1 %]Difficulty: [% x.difficulty %] out of 5.[% END %]
+  [% IF x.cmdline %]Requires use of the command line.[% END %]
+  [% IF x.author %]Author: [% x.author %].[% END %]
+  [% IF x.date %]Last updated: [% x.date %].[% END %]
+  </span>
+</li>
+[% END %]
+
+<ul>
+[% FOREACH x IN learning_documents -%]
+  [% IF x.difficulty == 0 %][% INCLUDE element %][% END %]
+[%- END %]
+</ul>
+
+[% END %]
+
+[% WRAPPER h2 h2="Tutorials rated <q>easy</q>" anchor="easy" %]
+
+<ul>
+[% FOREACH x IN learning_documents -%]
+  [% IF x.difficulty == 1 %][% INCLUDE element %][% END %]
+[%- END %]
+</ul>
+
+[% END %]
+
+[% WRAPPER h2 h2="Tutorials rated a little harder" anchor="others" %]
+
+<ul>
+[% FOREACH x IN learning_documents -%]
+  [% IF x.difficulty > 1 %][% INCLUDE element %][% END %]
+[%- END %]
+</ul>
+
+[% END %]
+
+[% WRAPPER h2 h2="More help" anchor="more-help" %]
+
+<p>
+Not found what you're looking for?
+<a href="[% topdir %]/contact/">Contact us via our mailing list
+or chat&nbsp;(IRC).</a>
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Contribute" anchor="contribute" %]
+
+<p>
+Do you want to write a tutorial?  Do you blog about virt tools?
+Your writings could appear here.
+<a href="[% topdir %]/contact/">Send us a note on the mailing list.</a>
+</p>
+
+[% END %]
+
+[% END -%]
diff --git a/website/src/learning/start-conventions/index.html b/website/src/learning/start-conventions/index.html
new file mode 100644
index 0000000..bb0781c
--- /dev/null
+++ b/website/src/learning/start-conventions/index.html
@@ -0,0 +1,236 @@
+[% topdir = "../.." -%]
+[% PROCESS globals -%]
+[% WRAPPER page
+   title = "Names and terms used in the virt tools documentation"
+   h1 = "Names and terms used in the virt tools documentation"
+   section = "learning"
+   local_stylesheet = 1
+%]
+
+[% WRAPPER h2 h2="Hosts, guests, virtual machines, hypervisors" anchor="names" %]
+
+<p>
+The virt tools and
+<a href="[% topdir %]/about/#projects">project documentation</a>
+uses the terms
+<strong>guest</strong>,
+<strong>virtual machine</strong>,
+<strong>VM</strong> and
+<strong>domain</strong> interchangably to refer to a virtual machine.
+The term <q>domain</q> comes from Xen.
+</p>
+
+<p>
+When we say <strong>host</strong> we mean the ordinary physical machine
+and the operating system which contains the guests.
+</p>
+
+<p>
+The term <strong>hypervisor</strong> has several different meanings:
+</p>
+
+<ul>
+<li> It can refer to the virtualization technology being employed.
+For example you can discuss the pros and cons of VMWare vs
+KVM as a <strong>hypervisor technology</strong>. </li>
+<li> For some virtualization systems (notably Xen) it can
+mean a separate component (the <strong>Xen hypervisor</strong>)
+which provides virtualization.  In Xen, unlike other systems,
+the host runs on top of the hypervisor and behaves more like a
+specialized guest. </li>
+<li> For KVM, you can refer to <q>Linux as the hypervisor</q>,
+meaning that the ordinary Linux host kernel has extra hypervisor
+capabilities provided by the KVM module. </li>
+</ul>
+
+<p>
+Xen (only) uses the special terms <strong>Dom0</strong> (a.k.a.
+<strong>Domain-0</strong>) and <strong>DomU</strong> as synonyms
+for host and guest respectively.
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Full virtualization and paravirtualization" anchor="fvpv" %]
+
+<p class="vtmarginnote">
+Examples of full virtualization technologies:
+Bochs, QEMU, KVM, VMWare, Xen-FV, MAME.
+</p>
+
+<p>
+<strong>Full virtualization</strong> (or <strong>fullvirt</strong>,
+<strong>FV</strong>) is what you use to run an unmodified operating
+system as a virtual machine.  The operating system <q>thinks</q> it is
+running on a PC, and (from the point of view of the guest) it sees
+usual hardware like a keyboard, disk drive, monitor and so on.  These
+of course are not real, but are emulated by the hypervisor technology
+underneath.
+</p>
+
+<p>
+Full virtualization is usually a bit slower, because of all the
+emulation, but it has the big advantage that you can run unmodified
+operating systems like Windows.
+</p>
+
+<p>
+<strong>Paravirtualization</strong>
+(or <strong>paravirt</strong>, <strong>PV</strong>) is where you
+modify the guest operating system so that it knows it is running in a
+virtual machine and it cooperates with the host.  This is done to gain
+extra performance by avoiding unnecessary emulation.
+</p>
+
+<p>
+There are essentially two methods currently in use for
+paravirtualization.  The <strong>Xen paravirt</strong> approach makes
+deep changes to the Linux kernel so that cooperation is achieved at
+many levels.  The advantage of Xen paravirt is
+that <a href="#hardware">hardware support</a> is not required, but the
+disadvantage is it is only possible for some Linux guests.
+</p>
+
+<p class="vtmarginnote">
+Examples of FV with PV drivers technologies:
+KVM Virtio, VMWare Tools, VirtualBox Additions, Xen-PV drivers.
+</p>
+
+<p>
+The more common approach these days is <strong>device driver
+paravirtualization</strong> where only the device drivers of the
+operating system are replaced.  This is sometimes called
+<strong>fullvirt with PV drivers</strong>.  This gains almost all the
+performance benefits of paravirtualization, it works with Windows
+guests, and it can be implemented incrementally by starting with a
+fullvirt guest and adding PV drivers as required.  The downside is
+that you need hardware support.  The most commonly paravirtualized
+devices are: the hard disk (often called the <q>block device</q>), the
+network device, the console, and the clock.
+</p>
+
+<p>
+<strong>Virtio</strong> is an emerging standard for
+paravirtualized drivers, and is particularly used for
+QEMU and KVM guests.  Virtio PV drivers are available
+for many different operating systems.
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Hardware support for virtualization" anchor="hardware" %]
+
+<p>
+Nowadays most computer processors contain extra support to accelerate
+virtualization (see <a href="../check-hardware-virt/">this tutorial to
+check if yours has support and to find out more about the different
+types</a>).
+</p>
+
+<p>
+Support in hardware is often called <strong>hardware
+virtualization</strong> (or <strong>hardware virt</strong>),
+abbreviated to <strong>HVM</strong>.
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Lifecycle" anchor="lifecycle" %]
+
+<p>
+Virtual machines can be started and stopped, and you may see this
+being referred to as the <strong>lifecycle</strong>
+or <strong>lifecycle management</strong>.  This is entirely equivalent
+to switching a real machine on and off.
+</p>
+
+<p>
+As well as just being started and stopped (and unlike real machines),
+virtual machines can be <strong>paused</strong>,
+<strong>snapshotted</strong> and <strong>cloned</strong>.
+</p>
+
+<p>
+Taking a snapshot usually means to save the state of the
+virtual machine at a moment in time, either so it can be
+backed up consistently, or so that you can try some experimental
+operation and roll back to the snapshot if that fails.
+</p>
+
+<p>
+Cloning is somewhat similar to snapshotting, but the two
+clones are allowed to run independently of each other
+(and cannot be combined again), so that whereas before you
+had one virtual machine, now you have two.
+</p>
+
+<p>
+Another aspect of lifecycle management is <strong>saving</strong>
+and <strong>restoring</strong> virtual machines.
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Disks and storage" anchor="storage" %]
+
+<p>
+The hard drive of a virtual machine is usually emulated ie.  it's not
+a physical, separate hard drive, but a file or logical volume on the
+host.  This host file (or however it is stored) is called
+the <strong>disk image</strong>.
+</p>
+
+<p>
+Disk images are allocated in <strong>volumes</strong>
+out of <strong>storage pools</strong>.
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Migration" anchor="migration" %]
+
+<p>
+<strong>Migration</strong> means moving a virtual machine from
+one host to another.  Usually this means <strong>live migration</strong>
+where the running VM is moved without interruption.
+</p>
+
+<p>
+Don't confuse migration and conversion (see next section).
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="P2V, V2V and V2P" anchor="p2v" %]
+
+<p>
+The terms <strong>P2V</strong>,
+<strong>V2V</strong>, and <strong>V2P</strong> refer to different
+sorts of <strong>conversions</strong>:
+</p>
+
+<table>
+<tr>
+<th> P2V </th>
+<td> Physical to virtual: Converting a physical machine to a
+virtual machine.  This is often done so you can continue to
+use the applications on the physical machine, but with newer
+hardware underneath. </td>
+</tr>
+<tr>
+<th> V2V </th>
+<td> Virtual to virtual: Converting a virtual machine
+from one hypervisor technology to another, for example
+converting a VMWare virtual machine to run on KVM to
+save money. </td>
+</tr>
+<tr>
+<th> V2P </th>
+<td> Virtual to physical: This is the reverse of P2V, taking
+a virtual machine and restoring it onto a physical machine. </td>
+</tr>
+</table>
+
+[% END %]
+
+[% END -%]
diff --git a/website/src/learning/start-conventions/style.css b/website/src/learning/start-conventions/style.css
new file mode 100644
index 0000000..2cd4ee6
--- /dev/null
+++ b/website/src/learning/start-conventions/style.css
@@ -0,0 +1,8 @@
+table {
+    width: 40em;
+}
+
+table th {
+    vertical-align: top;
+    text-align: right;
+}
diff --git a/website/src/learning/start-install-with-virt-manager/authenticate.png b/website/src/learning/start-install-with-virt-manager/authenticate.png
new file mode 100644
index 0000000..c84a389
--- /dev/null
+++ b/website/src/learning/start-install-with-virt-manager/authenticate.png
diff --git a/website/src/learning/start-install-with-virt-manager/index.html b/website/src/learning/start-install-with-virt-manager/index.html
new file mode 100644
index 0000000..29d610c
--- /dev/null
+++ b/website/src/learning/start-install-with-virt-manager/index.html
@@ -0,0 +1,154 @@
+[% topdir = "../.." -%]
+[% PROCESS globals -%]
+[% WRAPPER page
+   title = "Installing a virtual machine with virt-manager"
+   h1 = "Installing a virtual machine with virt-manager"
+   section = "learning"
+%]
+
+<p>
+Installing a virtual machine in virt-manager is a three step
+process.  First <a href="#download">download the operating
+system ISO</a> that you want to install.
+Secondly <a href="#virt-manager">start virt-manager</a>
+and <a href="#new-vm">create a new virtual machine for your
+guest</a>.  Lastly <a href="#installer">run the guest installer
+from the ISO</a>.
+</p>
+
+<p>
+You may also be interested in <a href="../install-with-command-line/">our
+tutorial which explains how to do all of this from the command line</a>.
+</p>
+
+[% WRAPPER h2 h2="Download the ISO" anchor="download" %]
+
+<p>
+Download an ISO of the operating system you want to install.
+Here are some common starting points:
+</p>
+
+<ul>
+<li> XXX FEDORA XXX </li>
+<li> XXX DEBIAN XXX </li>
+<li> XXX UBUNTU XXX </li>
+<li> XXX WINDOWS MSDN XXX </li>
+</ul>
+
+<p>
+Remember the operating system you install as a guest does
+not need to be the same as your host!
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Start virt-manager" anchor="virt-manager" %]
+
+<p>
+Start virt-manager
+(Applications &rarr; System Tools &rarr; Virtual Machine Manager)
+</p>
+
+<p>
+You may be asked to select the hypervisor and/or type your
+root password:
+</p>
+
+<p>
+<img src="authenticate.png" width="477" height="454"
+  longdesc="Image showing authentication." />
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Start new VM wizard" anchor="new-vm" %]
+
+<p>
+Click the button in the top left corner to begin installing
+your virtual machine:
+</p>
+
+<p>
+<img src="new-button.png" width="44" height="40"
+  longdesc="New VM button." />
+</p>
+
+<p>
+<img src="new-vm-1.png" width="457" height="381"
+  longdesc="New VM step 1" />
+</p>
+
+<p>
+Since you have downloaded an ISO, you need to select
+<q>Local install media</q>.  Also choose a name for the
+new guest.
+</p>
+
+<p>
+At the next step you need to tell virt-manager where
+you downloaded the ISO to.  When you click <q>Browse</q>
+you will see the default libvirt storage volume (which
+will probably be empty the first time):
+</p>
+
+<p>
+<img src="new-vm-2-browse.png" width="750" height="500"
+  longdesc="New VM step 2 browse window" />
+</p>
+
+<p>
+Click <q>Browse Local</q> to browse to the ISO on your
+local disk.
+</p>
+
+<p>
+<img src="new-vm-2.png" width="457" height="381"
+  longdesc="New VM step 2" />
+</p>
+
+<p>
+The third step allows you to choose the amount of RAM
+and number of virtual CPUs allocated to the guest.  For
+KVM guests, RAM can be overcommitted carefully (you can allocate
+more RAM to all your guests than you really have available).
+For Xen guests this is not possible.  A modern Linux guest
+requires at least 512 MB of RAM, and more is better.
+</p>
+
+<p>
+<img src="new-vm-3.png" width="457" height="381"
+  longdesc="New VM step 3" />
+</p>
+
+<p>
+If all goes well you should be able to skip through
+the next steps and start your install:
+</p>
+
+<p>
+<img src="new-vm-4.png" width="457" height="381"
+  longdesc="New VM step 4" />
+</p>
+
+<p>
+<img src="new-vm-5.png" width="457" height="381"
+  longdesc="New VM step 5" />
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Run the installer" anchor="installer" %]
+
+<p>
+From now on you should install the guest from the ISO
+as if you were installing it on real hardware:
+</p>
+
+<p>
+<img src="installer.png" width="784" height="563"
+  longdesc="Virtual machine installer running" />
+</p>
+
+[% END %]
+
+[% END -%]
diff --git a/website/src/learning/start-install-with-virt-manager/installer.png b/website/src/learning/start-install-with-virt-manager/installer.png
new file mode 100644
index 0000000..14cd3a4
--- /dev/null
+++ b/website/src/learning/start-install-with-virt-manager/installer.png
diff --git a/website/src/learning/start-install-with-virt-manager/new-button.png b/website/src/learning/start-install-with-virt-manager/new-button.png
new file mode 100644
index 0000000..993c906
--- /dev/null
+++ b/website/src/learning/start-install-with-virt-manager/new-button.png
diff --git a/website/src/learning/start-install-with-virt-manager/new-vm-1.png b/website/src/learning/start-install-with-virt-manager/new-vm-1.png
new file mode 100644
index 0000000..b9e2449
--- /dev/null
+++ b/website/src/learning/start-install-with-virt-manager/new-vm-1.png
diff --git a/website/src/learning/start-install-with-virt-manager/new-vm-2-browse.png b/website/src/learning/start-install-with-virt-manager/new-vm-2-browse.png
new file mode 100644
index 0000000..ac57c9b
--- /dev/null
+++ b/website/src/learning/start-install-with-virt-manager/new-vm-2-browse.png
diff --git a/website/src/learning/start-install-with-virt-manager/new-vm-2.png b/website/src/learning/start-install-with-virt-manager/new-vm-2.png
new file mode 100644
index 0000000..a27c17d
--- /dev/null
+++ b/website/src/learning/start-install-with-virt-manager/new-vm-2.png
diff --git a/website/src/learning/start-install-with-virt-manager/new-vm-3.png b/website/src/learning/start-install-with-virt-manager/new-vm-3.png
new file mode 100644
index 0000000..382bc3e
--- /dev/null
+++ b/website/src/learning/start-install-with-virt-manager/new-vm-3.png
diff --git a/website/src/learning/start-install-with-virt-manager/new-vm-4.png b/website/src/learning/start-install-with-virt-manager/new-vm-4.png
new file mode 100644
index 0000000..b95cf52
--- /dev/null
+++ b/website/src/learning/start-install-with-virt-manager/new-vm-4.png
diff --git a/website/src/learning/start-install-with-virt-manager/new-vm-5.png b/website/src/learning/start-install-with-virt-manager/new-vm-5.png
new file mode 100644
index 0000000..5635412
--- /dev/null
+++ b/website/src/learning/start-install-with-virt-manager/new-vm-5.png
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 -%]
diff --git a/website/src/learning/start-stop-vm-with-command-line/index.html b/website/src/learning/start-stop-vm-with-command-line/index.html
new file mode 100644
index 0000000..888efcd
--- /dev/null
+++ b/website/src/learning/start-stop-vm-with-command-line/index.html
@@ -0,0 +1,154 @@
+[% topdir = "../.." -%]
+[% PROCESS globals -%]
+[% WRAPPER page
+   title = "Starting and stopping VMs from the command line"
+   h1 = "Starting and stopping VMs from the command line"
+   section = "learning"
+%]
+
+<p>
+<q>Lifecycle management</q> (which is a fancy way of
+saying <q>starting and stopping virtual machines</q>) can be done
+either <a href="../start-vm-with-virt-manager/">from virt-manager</a>
+or directly from the command line or shell scripts
+using <code>virsh</code>.
+</p>
+
+<p>
+These commands generally require that you are root.  On
+Fedora and Debian, do:
+</p>
+
+<pre>
+su
+</pre>
+
+<p>
+and type the root password.
+</p>
+
+<p>
+On Ubuntu you can prefix each command with <code>sudo</code>,
+or get a root shell first by doing:
+</p>
+
+<pre>
+sudo bash
+</pre>
+
+<p>
+<a href="../start-list-with-command-line/">List out the
+virtual machines that you have available</a>.  You can
+then substitute the name of one of your virtual machines
+for generic <q>Guest</q> below.
+</p>
+
+[% WRAPPER h2 h2="Starting a virtual machine with virsh" anchor="start" %]
+
+<p>
+To start a virtual machine running, do:
+</p>
+
+<pre>
+virsh start Guest
+</pre>
+
+<p>
+where <q>Guest</q> is the name of the virtual machine.  Check
+that it is running by
+<a href="../start-list-with-command-line/">using <code>virsh list</code></a>
+or connecting to the console with:
+</p>
+
+<pre>
+virt-viewer Guest
+</pre>
+
+[% END %]
+
+[% WRAPPER h2 h2="Stopping the virtual machine with virsh" anchor="stop" %]
+
+<p>
+Stopping the virtual machine is a little more complex and requires
+some understanding of how real PC hardware works.
+</p>
+
+<h3>Pull the plug</h3>
+
+<p>
+On a real PC you can just pull out the power cord (and battery
+if it's a laptop).  This abruptly shuts the machine down, but
+it's not usually a good thing to do since the operating system
+gets no time to gracefully shut down applications and synchronize
+the disk.
+</p>
+
+<p>
+You can do this from <code>virsh</code> too using the
+<code>virsh destroy</code> command, but be careful as the guest is
+switched off with no warning and no chance to sync the disks:
+</p>
+
+<pre>
+virsh destroy Guest
+</pre>
+
+<h3>ACPI</h3>
+
+<p>
+The more common option is to reboot or shutdown the guest:
+</p>
+
+<pre>
+virsh reboot Guest
+</pre>
+
+<pre>
+virsh shutdown Guest
+</pre>
+
+<p>
+You cannot reboot or shut down a machine (real or virtual) without
+cooperation from the operating system.  On a real PC the power switch
+just sends a signal to the operating system, and the operating system
+has to be listening out for the signal and has to react by doing the
+right thing.  This signal mechanism is known as
+<a href="http://en.wikipedia.org/wiki/ACPI">ACPI</a>.
+The same mechanism is used to <q>wire</q> the virtual power
+switch to the virtual machine.
+</p>
+
+<p>
+Using the <code>virsh reboot</code> or <code>virsh shutdown</code>
+commands is like pressing the virtual power button, and it may
+open a dialog inside the VM like this one (taken
+from an Ubuntu guest):
+</p>
+
+<p>
+<img src="ubuntu-power-dlg.png" width="532" height="450"
+  longdesc="Ubuntu power dialog" />
+</p>
+
+<p>
+The precise action taken depends on:
+</p>
+
+<ul>
+<li> the guest </li>
+<li> how the guest has been configured to react to ACPI events </li>
+<li> if the guest is listening to ACPI at all
+  (it may require that an ACPI daemon is started) </li>
+<li> whether the guest is listening or has crashed, is busy &amp;c. </li>
+</ul>
+
+<p>
+If a guest won't shut down or reboot, it is usually caused
+by a problem with ACPI and/or guest configuration.  Eventually
+you may need to <code>virsh destroy</code> guests that don't
+respond to ordinary events.
+</p>
+
+[% END %]
+
+[% END -%]
diff --git a/website/src/learning/start-stop-vm-with-command-line/ubuntu-power-dlg.png b/website/src/learning/start-stop-vm-with-command-line/ubuntu-power-dlg.png
new file mode 100644
index 0000000..1fcd58e
--- /dev/null
+++ b/website/src/learning/start-stop-vm-with-command-line/ubuntu-power-dlg.png
diff --git a/website/src/learning/start-virt-tools/index.html b/website/src/learning/start-virt-tools/index.html
new file mode 100644
index 0000000..b6b2e91
--- /dev/null
+++ b/website/src/learning/start-virt-tools/index.html
@@ -0,0 +1,94 @@
+[% topdir = "../.." -%]
+[% PROCESS globals -%]
+[% WRAPPER page
+   title = "Installing virt tools"
+   h1 = "Download and install virt tools"
+   section = "learning"
+%]
+
+<p>
+Select your operating system or Linux distro from the list below:
+</p>
+
+<ul>
+<li> <a href="#fedora">Fedora, Red Hat Enterprise Linux and clones</a> </li>
+<li> <a href="#debian">Debian</a> </li>
+<li> <a href="#ubuntu">Ubuntu</a> </li>
+</ul>
+
+[% WRAPPER h2 h2="Fedora, Red Hat Enterprise Linux" anchor="fedora" %]
+
+<h3>Graphical method</h3>
+
+<p>
+Go to System &rarr; Administration &rarr; Add/Remove Software.
+</p>
+
+<p>
+From the list on the left, select Virtualization.
+</p>
+
+<p>
+Select the required virt tools and click Apply.
+</p>
+
+<h3>From the command line</h3>
+
+<p>
+Open a terminal window (Applications &rarr; System Tools &rarr; Terminal)
+and type the following:
+</p>
+
+<pre>
+su
+</pre>
+
+<p>
+(now type your root password)
+</p>
+
+<pre>
+yum install qemu libvirt-client virt-manager \
+  virt-viewer guestfish libguestfs-tools virt-top
+</pre>
+
+[% END %]
+
+[% WRAPPER h2 h2="Debian" anchor="debian" %]
+
+<p>
+Open a terminal window (Applications &rarr; Accessories &rarr; Terminal)
+and type:
+</p>
+
+<pre>
+su
+apt-get install kvm libvirt-bin virt-manager virt-viewer virt-top
+</pre>
+
+<p>
+For information on installing guestfish and libguestfs-tools in
+Debian, see <a href="http://libguestfs.org/FAQ.html#binaries">this page</a>.
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Ubuntu" anchor="ubuntu" %]
+
+<p>
+Open a terminal window (Applications &rarr; Accessories &rarr; Terminal)
+and type:
+</p>
+
+<pre>
+sudo apt-get install ubuntu-virt virt-top virt-what
+</pre>
+
+<p>
+For information on installing guestfish and libguestfs-tools in
+Ubuntu, see <a href="http://libguestfs.org/FAQ.html#binaries">this page</a>.
+</p>
+
+[% END %]
+
+[% END -%]
diff --git a/website/src/learning/start-vm-with-virt-manager/debian.png b/website/src/learning/start-vm-with-virt-manager/debian.png
new file mode 100644
index 0000000..e4ff0a3
--- /dev/null
+++ b/website/src/learning/start-vm-with-virt-manager/debian.png
diff --git a/website/src/learning/start-vm-with-virt-manager/force-off.png b/website/src/learning/start-vm-with-virt-manager/force-off.png
new file mode 100644
index 0000000..a9def3d
--- /dev/null
+++ b/website/src/learning/start-vm-with-virt-manager/force-off.png
diff --git a/website/src/learning/start-vm-with-virt-manager/index.html b/website/src/learning/start-vm-with-virt-manager/index.html
new file mode 100644
index 0000000..2fcfc51
--- /dev/null
+++ b/website/src/learning/start-vm-with-virt-manager/index.html
@@ -0,0 +1,115 @@
+[% topdir = "../.." -%]
+[% PROCESS globals -%]
+[% WRAPPER page
+   title = "Starting and stopping virtual machines with virt-manager"
+   h1 = "Starting and stopping virtual machines with virt-manager"
+   section = "learning"
+%]
+
+<p>
+In principle, <q>lifecycle management</q> (which is a fancy way of
+saying <q>starting and stopping virtual machines</q>) is quite easy.
+</p>
+
+[% WRAPPER h2 h2="Starting the virtual machine" anchor="start" %]
+
+<p>
+To start a virtual machine running, select it from the list and either
+press the <q>play</q> button or right click and select <q>Run</q>:
+</p>
+
+<p>
+<img src="run.png" width="312" height="315"
+  longdesc="Screenshot showing the right button popup menu in virt-manager" />
+</p>
+
+<p>
+When the virtual machine is running, two things will change.  You
+will get a small graph showing the CPU usage in the main virt-manager
+window.  And if you double click on the virtual machine, virt-manager
+will open another window showing you the console:
+</p>
+
+<p>
+<img src="debian.png" width="946" height="677"
+  longdesc="Screenshot showing virtual machine running" />
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Stopping the virtual machine" anchor="stop" %]
+
+<p>
+Stopping the virtual machine is a little more complex and requires
+some understanding of how real PC hardware works.
+</p>
+
+<h3>Force off</h3>
+
+<p>
+On a real PC you can just pull out the power cord (and battery
+if it's a laptop).  This abruptly shuts the machine down, but
+it's not usually a good thing to do since the operating system
+gets no time to gracefully shut down applications and synchronize
+the disk.
+</p>
+
+<p>
+Nevertheless virt-manager lets you do this: From the <q>switch</q>
+menu select <q>Force Off</q>:
+</p>
+
+<p>
+<img src="force-off.png" width="310" height="193"
+  longdesc="Screenshot showing force-off option in virt-manager" />
+</p>
+
+<h3>ACPI</h3>
+
+<p>
+The other two options on this menu are <q>Reboot</q> and
+<q>Shut Down</q>.  However you cannot reboot or shut down
+a machine (real or virtual) without cooperation from the
+operating system.  On a real PC the power switch just sends
+a signal to the operating system, and the operating system
+has to be listening out for the signal and has to react
+by doing the right thing.  This signal mechanism
+is known as
+<a href="http://en.wikipedia.org/wiki/ACPI">ACPI</a>.
+The same mechanism is used to <q>wire</q> the virtual power
+switch to the virtual machine.
+</p>
+
+<p>
+This is why pressing the virtual power button may
+open a dialog inside the VM like this one (taken
+from an Ubuntu guest):
+</p>
+
+<p>
+<img src="ubuntu-power-dlg.png" width="532" height="450"
+  longdesc="Ubuntu power dialog" />
+</p>
+
+<p>
+The precise action taken depends on:
+</p>
+
+<ul>
+<li> the guest </li>
+<li> how the guest has been configured to react to ACPI events </li>
+<li> if the guest is listening to ACPI at all
+  (it may require that an ACPI daemon is started) </li>
+<li> whether the guest is listening or has crashed, is busy &amp;c. </li>
+</ul>
+
+<p>
+If a guest won't shut down or reboot, it is usually caused
+by a problem with ACPI and/or guest configuration.  Eventually
+you may need to use the <q>Force Off</q> option on recalcitrant
+guests.
+</p>
+
+[% END %]
+
+[% END -%]
diff --git a/website/src/learning/start-vm-with-virt-manager/run.png b/website/src/learning/start-vm-with-virt-manager/run.png
new file mode 100644
index 0000000..429b47d
--- /dev/null
+++ b/website/src/learning/start-vm-with-virt-manager/run.png
diff --git a/website/src/learning/start-vm-with-virt-manager/ubuntu-power-dlg.png b/website/src/learning/start-vm-with-virt-manager/ubuntu-power-dlg.png
new file mode 100644
index 0000000..1fcd58e
--- /dev/null
+++ b/website/src/learning/start-vm-with-virt-manager/ubuntu-power-dlg.png
diff --git a/website/src/learning/style.css b/website/src/learning/style.css
new file mode 100644
index 0000000..b7c6867
--- /dev/null
+++ b/website/src/learning/style.css
@@ -0,0 +1,13 @@
+/* Local stylesheet. */
+
+ul {
+  list-style: none;
+  margin: 0px;
+  padding: 0px;
+}
+
+span.notes {
+  display: block;
+  font-size: 70%;
+  color: #888;
+}
\ No newline at end of file