diff options
| author | Richard W.M. Jones <rjones@redhat.com> | 2010-10-11 18:02:43 +0100 |
|---|---|---|
| committer | Richard W.M. Jones <rjones@redhat.com> | 2010-10-13 09:49:58 +0100 |
| commit | 728c0634432b39aacc7650bcdac92243b5817e6b (patch) | |
| tree | c2ebed1c9c5d8604d70a3d0d94b2ae31819ab627 | |
| parent | 968acff01a0c4d20d89881ab20850ff2db2cbad8 (diff) | |
| download | virt-tools-728c0634432b39aacc7650bcdac92243b5817e6b.tar.gz virt-tools-728c0634432b39aacc7650bcdac92243b5817e6b.tar.xz virt-tools-728c0634432b39aacc7650bcdac92243b5817e6b.zip | |
virt-tools website using Template Toolkit (incomplete).
48 files changed, 2122 insertions, 0 deletions
diff --git a/website/.gitignore b/website/.gitignore new file mode 100644 index 0000000..07ed706 --- /dev/null +++ b/website/.gitignore @@ -0,0 +1 @@ +build/*
\ No newline at end of file diff --git a/website/Makefile b/website/Makefile new file mode 100644 index 0000000..0c54bc8 --- /dev/null +++ b/website/Makefile @@ -0,0 +1,12 @@ +# Please read the README file. + +all: + ./rebuild.sh + +clean: + find -name '*~' -delete + rm -rf build/* + +go-live: + @echo "Sorry, we've not written this yet." + @exit 1 diff --git a/website/README b/website/README new file mode 100644 index 0000000..693b984 --- /dev/null +++ b/website/README @@ -0,0 +1,96 @@ +This directory contains the source for the virt tools website. Please +read this file carefully before making modifications. + +Overview +---------------------------------------------------------------------- + +The website has four different URLs. The first is the canonical one, +the other three redirect to the first. + + http://virt-tools.org # canonical + http://virttools.org # redirect + http://virt-tools.com # redirect + http://virttools.com # redirect + +Sub-directories +---------------------------------------------------------------------- + +- src: Source for the website. + + At the moment we use the perl Template Toolkit to provide simple + includes, and apart from that it's just flat HTML. We don't yet use a + CMS although we are considering using one in future. + +- templates: Templates used to build the site. + +- build: Preview / staging directory. + +To rebuild (preview) the site, run: + + make + +and point your browser in the build/ directory: + + firefox build/index.html + +To sync the contents of build/ to the live site, run: + + make go-live + +Content and stylesheets +---------------------------------------------------------------------- + +Each page of the site corresponds to a subdirectory (this is so that +'.html' extensions don't appear in URLs). To create a new page, copy +an existing subdirectory. + +Unfortunately this means when previewing that internal links will take +you to a directory listing, but they will work OK on the live site. + +One benefit however is you can put all related files in the same +directory (eg. images, page-local stylesheet). + +Global stylesheets are in the src/css/ subdirectory. + +Some rules: + +- Do not mix styling and HTML. Use simple, small HTML and style it + via stylesheets. Don't use table layouts, HTML editorcrap etc. + Look at existing pages for clues. In other words, use your head. + +- Use relative paths so that pages can be previewed without copying + them to the live site. + +- For page-specific styles, create 'style.css' in the same directory + containing the page (eg. foo/index.html => foo/style.css), and set + the local_stylesheet variable in the wrapper. + +- Links must *not* contain 'index.html'. Links *must* end with a '/' + character. In general use: <a href="[% topdir %]/foo/">.....</a> + +We declare pages XHTML 1.0 Strict to avoid quirks modes, but in fact +our pages are not strict XHTML. However it's still a good idea to +fully close tags and generally make the HTML as strict as possible. + +Templates +---------------------------------------------------------------------- + +Each page starts with a 'page wrapper'. Have a look at templates/page +to see the page template. + +The variables that you can use include: + +- topdir: the relative path to the top directory ("." for the home + page, ".." for pages which are one subdirectory deep, "../.." for + pages which are two subdirectories deep, etc.) + +- title: the page title + +- h1: the page <h1>, should probably be the same as the title, but not + too long + +- local_stylesheet: If set, this causes a local "style.css" to be + included for page-specific styles. + +- section: This controls which section menu item is highlighted. See + templates/page for the full list of sections. diff --git a/website/build/.keep b/website/build/.keep new file mode 100644 index 0000000..60fd346 --- /dev/null +++ b/website/build/.keep @@ -0,0 +1 @@ +keep directory diff --git a/website/rebuild.sh b/website/rebuild.sh new file mode 100755 index 0000000..b09df15 --- /dev/null +++ b/website/rebuild.sh @@ -0,0 +1,16 @@ +#!/bin/sh - + +ttree=/usr/bin/ttree +conf=templates/ttree.conf + +[ -x "$ttree" ] || { + echo "'ttree' is missing, you need to install the 'perl-Template-Toolkit' package" + exit 1 +} + +[ -f "$conf" ] || { + echo "configuration file missing, you are running this from the wrong directory" + exit 1 +} + +"$ttree" -f "$conf" diff --git a/website/src/about/index.html b/website/src/about/index.html new file mode 100644 index 0000000..ff1ba35 --- /dev/null +++ b/website/src/about/index.html @@ -0,0 +1,169 @@ +[% topdir = ".." -%] +[% PROCESS globals -%] +[% WRAPPER page + title = "About virt tools and the virt tools site" + h1 = "About virt tools and the virt tools site" + section = "about" + local_stylesheet = 1 +%] + +<p> +Virt Tools are open source virtualization management tools for Linux +system administrators. +</p> + +<p> +This site provides tutorials, videos, documentation, online help and +roadmaps to help you understand and get started with the tools. +</p> + +<p> +This site is an umbrella site covering many different virt projects. +Those sites also contain documentation and tutorials, and we link to +the best pages from here. +</p> + +[% WRAPPER h2 h2="Contributing to the virt tools site" anchor="contribute" %] + +<p> +This site is open source. You can clone the sources from +<a href="https://fedorahosted.org/virt-tools">this git repository</a> +(in the website subdirectory). We welcome contributions. +Please <a href="[% topdir %]/contact/">contact us through the mailing +list</a>. +</p> + +[% END %] + +[% WRAPPER h2 h2="The upstream virt projects" anchor="projects" %] + +[%- +# Alphabetical order of project name. + upstreams = [ + { url = "http://augeas.net/", + project = "augeas", + description = "Library and tools for Linux configuration +file editing from scripts. Tools include <code>augtool</code>. +The Augeas APIs are exposed through libguestfs, allowing you to +make structured edits to Linux virtual machines." }, + { url = "http://people.redhat.com/~rjones/guestfs-browser/", + project = "guest filesystem browser", + description = "A graphical filesystem browser for virtual machines. +Uses libguestfs and libvirt." }, + { url = "http://libguestfs.org/hivex.3.html", + project = "hivex", + description = "Library and tools for Windows Registry +(<q>hive file</q>) editing. +This functionality is exposed through libguestfs, allowing you +to make changes to the Registry in your Windows guests." }, + { url = "http://libguestfs.org/", + project = "libguestfs", + description = "Library and tools for editing disk images +and files within virtual machines. Tools include: +<code>guestfish</code>, +<code>virt-cat</code>, +<code>virt-df</code>, +<code>virt-inspector</code>, +<code>virt-resize</code>, +<code>virt-rescue</code>, +<code>virt-win-reg</code> and +<code>guestmount</code>." }, + { url = "http://libvirt.org/", + project = "libvirt", + description = "Libvirt is a comprehensive API +and set of tools for managing +virtual machines across many supported hypervisors including +KVM, Xen, VirtualBox, VMWare and more. Many of the virt tools +use libvirt for virtual machine management. Libvirt tools include +<code>virsh</code> (the virtual shell)." }, + { url = "https://fedorahosted.org/netcf/", + project = "netcf", + description = "Library and tools for network configuration. +Tools include <code>ncftool</code>." }, + { url = "http://people.redhat.com/dlutter/virt-image/", + project = "virt-image", + description = "Virt-image is a portable format for interchange of virtual +machines, and a command line tool for handling that format." }, + { url = "http://virt-manager.org/", + project = "virt-install", + description = "Virt-install is a command line tool for installing +new virtual machines. It is also used as part of virt-manager." }, + { url = "http://virt-manager.org/", + project = "virt-manager", + description = "Virt-manager is a graphical tool for creating +and managing virtual machines. It offers simple, rapid management +when you don't need the scalability and complexity of larger +more advanced programs." }, + { url = "http://people.redhat.com/~rjones/virt-p2v/", + project = "virt-p2v", + description = "Virt-p2v is a live CD that you can use to +convert a physical machine into a virtual machine." }, + { url = "http://people.redhat.com/~rjones/virt-top/", + project = "virt-top", + description = "Virt-top is a monitoring program, like <code>top</code> +for virtual machines. It can display CPU, disk and network statistics, +and also output to a file or database." }, + { url = "", + project = "virt-v2v", + description = "Virt-v2v allows you to convert virtual machines +from Xen and VMWare over to KVM." }, + { url = "http://virt-manager.org/", + project = "virt-viewer", + description = "Virt-viewer is a console viewer for virtual +machines. It is also used as part of virt-manager." }, + { url = "http://people.redhat.com/~rjones/virt-what/", + project = "virt-what", + description = "Virt-what is a set of shell scripts that you +can use to detect if your program is running inside a virtual machine." }, + ] + +# Others: +# +# "text" virt-manager ? +# matahari ? +# virt-clone +# virt-dmesg +# virt-uname +-%] + +<table> +[% FOREACH x IN upstreams -%] +<tr> +<th> +[% IF x.url -%] +<a href="[% x.url %]"> +[%- END -%] +[% x.project %] +[%- IF x.url -%] +</a> +[%- END %] +</th> +<td> [% x.description %] </td> +</tr> +[%- END %] +</table> + +[% END %] + +[% WRAPPER h2 h2="License" anchor="license" %] + +<p> +The main content of this site is copyright © [% year %] +<a href="http://redhat.com/">Red Hat Inc.</a> and licensed under +the GNU General Public License, version 2 or (at your option) any +later version. Tutorials, videos and other documentation are owned by +the respective authors. +</p> + +[% END %] + +[% WRAPPER h2 h2="Technology" anchor="technology" %] + +<p> +The content of the site is generated from templates using the +<a href="http://template-toolkit.org/">Template Toolkit</a>. +</p> + +[% END %] + +[% END -%] diff --git a/website/src/about/style.css b/website/src/about/style.css new file mode 100644 index 0000000..432c706 --- /dev/null +++ b/website/src/about/style.css @@ -0,0 +1,15 @@ +table { + width: 40em; +} + +table th { + width: 10em; + text-align: right; + vertical-align: top; + padding-right: 1em; +} + +table td { + vertical-align: top; + padding-bottom: 1em; +} diff --git a/website/src/contact/index.html b/website/src/contact/index.html new file mode 100644 index 0000000..9e3db93 --- /dev/null +++ b/website/src/contact/index.html @@ -0,0 +1,29 @@ +[% topdir = ".." -%] +[% PROCESS globals -%] +[% WRAPPER page + title = "Mailing list, chat IRC for virt tools" + h1 = "Contact and join the virt tools team" + section = "contact" +%] + +<p> +If you have any questions about the virt tools which are +not answered by this site, then the best way to get help +is on our mailing list or chat (IRC) channel. +</p> + +[% WRAPPER h2 h2="Mailing list" anchor="mailing-list" %] +<p> + +</p> +[% END %] + +[% WRAPPER h2 h2="Chat (IRC)" anchor="chat" %] +<p> +Join <code>#virt</code> channel on the OFTC IRC network. +Note that at some times of the day you won't get an immediate +answer, so stay in the channel. +</p> +[% END %] + +[% END -%] diff --git a/website/src/css/easytoread.css b/website/src/css/easytoread.css new file mode 100644 index 0000000..97a06ea --- /dev/null +++ b/website/src/css/easytoread.css @@ -0,0 +1,7 @@ +/* High contrast, large fonts. + * $Id: easytoread.css,v 1.1 2007/01/23 16:33:28 rjones Exp $ + */ + +body { + font-size: 200%; +}
\ No newline at end of file diff --git a/website/src/css/standard.css b/website/src/css/standard.css new file mode 100644 index 0000000..be60b31 --- /dev/null +++ b/website/src/css/standard.css @@ -0,0 +1,131 @@ +/* CSS for virt-tools.org */ + +body { + padding-top: 32px; /* space for menu */ + margin-left: 1em; + font-family: Helvetica; /* Fedora users get Liberation, hopefully */ +} + +body > p, body > ul, body > ol, body > dl { + margin-left: 1em; + width: 35em; +} + +li { + padding-bottom: 0.5em; +} + +/* Headings. */ + +h1 { + font-size: 125%; +} + +h2 { + font-size: 115%; +} + +h3, h4 { + font-size: 105%; +} + +h1, h2, h3, h4 { + color: #222; +} + +pre { + background-color: #fcfcfc; + /*border: 1px dotted #888;*/ + border-left: 6px solid #f0f0f0; + padding: 5px; + margin-left: 1em; + font-size: 120%; +} + +/* In subsections, links back to section at top and bottom. */ + +p#vtbacktosectiontop { + margin-top: -12px; + margin-left: 0px; + font-size: 70%; + color: #888; +} + +p#vtbacktosectiontop a { + text-decoration: none; +} + +/* Menu. */ + +ul#vtmenu { + position: absolute; + left: 1em; + top: 6px; + width: 98%; + padding: 0px; + margin: 0px; + list-style: none; +} + +ul#vtmenu li { + display: inline; + margin-left: -3px; + border: solid #fff 1px; +} + +ul#vtmenu li.vtmenuselected a, ul#vtmenu li.vtmenuselected span { + display: inline; + padding: 3px 2em 3px 2em; + background-color: #a3e8db; +} + +ul#vtmenu li.vtmenunotselected a, ul#vtmenu li.vtmenunotselected span { + display: inline; + padding: 3px 2em 3px 2em; + background-color: #93c5c2; +} + +ul#vtmenu li a:hover { + background-color: #a3e8db; +} + +ul#vtmenu a { + text-decoration: none; + color: #000; +} + +/* Footer (displayed on every page except the home page) */ + +p#vtfooter { + width: 98%; + font-size: 70%; + color: #888; +} + +/* Permalinks (see templates/h2) */ + +a.vtpermalink { + font-size: 70%; + color: #ddd; + text-decoration: none; +} + +a.vtpermalink:hover { + color: #222; +} + +/* Right-float boxes, used for margin notes, examples etc. */ + +p.vtmarginnote { + float: right; + + width: 16em; + margin-top: 0px; + margin-left: 2em; + margin-right: 2em; + padding-top: 0px; + + font-style: italic; + font-size: 85%; + color: #333; +}
\ No newline at end of file diff --git a/website/src/faq/index.html b/website/src/faq/index.html new file mode 100644 index 0000000..8e994b4 --- /dev/null +++ b/website/src/faq/index.html @@ -0,0 +1,84 @@ +[% topdir = ".." -%] +[% PROCESS globals -%] +[% WRAPPER page + title = "Frequently Asked Questions (FAQ) about virt tools" + h1 = "Frequently Asked Questions (FAQ) about virt tools" + section = "faq" + local_stylesheet = 1 +%] + +[%- +# We could put this array in globals. + +questions = [ + { name = "who", + q = "Who wrote these tools? Is this just a Red Hat / Fedora project?", + a = " + <p> + These tools are all open source and available on several Linux + distributions, including Fedora, Debian, Ubuntu and Gentoo, + and some of the programs have also been ported to + Mac OS X and Windows. + </p> + <p> + All of these projects solicit input from the widest possible + community, and libvirt in particular has active developers + from all the major Linux distros. + </p> + <p> + Red Hat sponsors some of the developers, Canonical are + active in libvirt development, and others projects and + people come from the rest of the community. + </p> + <p> + If a tool you need is not available on your distro of choice, + please help to port it. + </p>" }, + { name = "why-virt-tools", + q = "Why are they called <q>virt tools</q>?", + a = " + <p> + Simply because most of the command line tools are called + virt-<i>something</i> (such as <code>virt-df</code> and + <code>virt-manager</code>) and so the name <q>virt tools</q> + stuck. + </p>" }, + { name = "project-criteria", + q = "Can you feature my project? What are the criteria for being called a virt tool?", + a = " + <p> + The project must be open source with an active upstream community. + It must complement the existing virt tools (in particular it should + use libvirt for lifecycle management). + </p> + <p> + Generally we focus on small tools which are useful for + system administrators who are responsible for a few physical machines. + </p> + <p> + The tool should be easy to install + (eg. just <code>apt-get install</code> / <code>yum install</code>, + not needing an expensive consultant to visit you on site!) + </p> + <p> + Our focus is on Linux tools, although a Windows- or Mac-only program + wouldn't be out of the question if it met the other criteria above. + </p>" }, +] + +-%] + +<ul> +[% FOREACH x IN questions -%] +<li> <a href="#[% x.name %]">[% x.q %]</a> </li> +[%- END %] +</ul> + +[% FOREACH x IN questions -%] + [% WRAPPER h2 h2=x.q anchor=x.name %] + [% x.a %] + [% END %] +[%- END %] + + +[% END -%] diff --git a/website/src/faq/style.css b/website/src/faq/style.css new file mode 100644 index 0000000..f1cee39 --- /dev/null +++ b/website/src/faq/style.css @@ -0,0 +1,5 @@ +ul { + list-style: none; + margin: 0px; + padding: 0px; +}
\ No newline at end of file diff --git a/website/src/index.html b/website/src/index.html new file mode 100644 index 0000000..2f66c7b --- /dev/null +++ b/website/src/index.html @@ -0,0 +1,65 @@ +[% topdir = "." -%] +[% PROCESS globals -%] +[% WRAPPER page + title = "virt tools: open source virtualization management tools for Linux system administrators" + h1 = "virt tools: open source virtualization management tools" + section = "home" + local_stylesheet = 1 %] + +<p id="vtboxout"> +Virt Tools are open source virtualization management tools for Linux +system administrators. This site provides tutorials, videos, +documentation, online help and roadmaps to help you understand and get +started with the tools. Our most popular virt tools are virt-manager, +virsh, virt-install, virt-v2v, guestfish, virt-p2v, virt-df and +virt-viewer. <a href="[% topdir %]/about/">Find out more ...</a> +</p> + +<img src="virtualization.png" width="250" height="141" id="vtboximage" + alt="Virtualization" + longdesc="Image showing a virtual machine being run under virt-manager" /> + +<div id="vtleft"> +<h2>Latest articles</h2> + +[%# This just links to my blog at the moment, but eventually we + will use a planet to aggregate all relevant posts from all + contributors together -- RWMJ. %] + +<script language="JavaScript" src="http://feed2js.org/feed2js.php?src=http%3A%2F%2Frwmj.wordpress.com%2Ftag%2Fvirt-tools%2Ffeed%2F&chan=title&num=10&date=y&utf=y&css=style" type="text/javascript"></script> + +<noscript> +<a href="http://rwmj.wordpress.com/tag/virt-tools/">See all entries tagged 'virt-tools'</a> +</noscript> + +<p> +<a href="[% topdir %]/news/">More news ...</a> +</p> + +</div> + +<div id="vtmid"> +<h2>Video tutorials</h2> + + + + +</div> + +<div id="vtright"> +<h2>Get started</h2> + +<ul> +[% FOREACH x IN learning_documents -%] + [% IF x.difficulty == 0 -%] + <li> <a href="[% topdir %]/learning/[% x.name %]/">[% x.link %]</a> [% x.rest %] </li> + [%- END %] +[%- END %] +<li> <a href="[% topdir %]/learning/">More tutorials ...</a> </li> +<li> <a href="[% topdir %]/contact/">Get help via our mailing list + or chat (IRC) ...</a> </li> +</ul> + +</div> + +[% END -%] diff --git a/website/src/learning/advanced-virt-df/df-centos-graph.png b/website/src/learning/advanced-virt-df/df-centos-graph.png Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 > /etc/cron.daily/local-virt-df</b> +#!/bin/bash - +date=$(date +%F) +virt-df --csv > /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") > 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> — 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 → Chart) with a linear trend line +(select chart and do Insert → Trend 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 (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 Binary files differnew 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 → System Tools → 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 Binary files differnew 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 &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 Binary files differnew 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 → Administration → 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 → System Tools → 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 → Accessories → 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 → Accessories → 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 Binary files differnew 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 Binary files differnew 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 &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 Binary files differnew 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 Binary files differnew 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 diff --git a/website/src/style.css b/website/src/style.css new file mode 100644 index 0000000..67c31f7 --- /dev/null +++ b/website/src/style.css @@ -0,0 +1,45 @@ +/* Local stylesheet for home page. */ + +img#vtboximage { + position: absolute; + left: 40em; + top: 5em; +} + +div#vtleft { + width: 16em; + position: absolute; + left: 1em; + top: 14em; +} + +div#vtleft h2, div#vtmid h2, div#vtright h2 { + /*background-color: #93c5c2;*/ +} + +div#vtmid { + width: 16em; + position: absolute; + left: 18em; + top: 14em; +} + +div#vtright { + width: 16em; + position: absolute; + left: 35em; + top: 14em; +} + +ul { + list-style: none; + margin: 0px; + padding: 0px; +} + +/* Don't display footer on the front page, because the columns in + the center of the page don't make this easy. */ + +p#vtfooter { + display: none; +}
\ No newline at end of file diff --git a/website/src/virtualization.png b/website/src/virtualization.png Binary files differnew file mode 100644 index 0000000..e4e54d1 --- /dev/null +++ b/website/src/virtualization.png diff --git a/website/templates/globals b/website/templates/globals new file mode 100644 index 0000000..79d7d2f --- /dev/null +++ b/website/templates/globals @@ -0,0 +1,99 @@ +[% USE date -%] +[% +# This global template is included in every HTML file. It is +# included before the DOCTYPE and it *must not* generate any +# output. Be careful to chomp! However it is a very useful +# place to put global variables. Note that the only variable +# that is passed in here is topdir. + +year = date.format(date.now, '%Y') +printable_date = date.format + +# These are the sections / tabs of the site as they appear in +# the navigation at the top of all pages. + +sections = [ "home", "news", "learning", "faq", "about", "contact" ] + +section_titles.home = "Home" +section_titles.news = "News" +section_titles.learning = "Tutorials and videos" +section_titles.faq = "FAQ" +section_titles.about = "About this site" +section_titles.contact = "Contact us" + +section_paths.home = "/" +section_paths.news = "/news/" +section_paths.learning = "/learning/" +section_paths.faq = "/faq/" +section_paths.about = "/about/" +section_paths.contact = "/contact/" + +# The full list of local resources under src/learning/ +# +# Put new documents at the top. +# +# If the resource is really beginner level, then set difficulty = 0. +# Use this sparingly because these appear in 'Get started' on the +# front page of the site, and also at the top of the list. +# +# Other variables: +# difficulty: Difficulty level 0 (absolute beginner) 1 (easy) .. 5 (hardest). +# cmdline: (optional) Set to 1 if this involves using the command line. +# author: (optional) String containing author's name. +# date: (optional) Date last updated (use: date +%F) +# +# The text will be displayed to the user as: +# <a href="/learning/[name]/">[link]</a> [rest] + +learning_documents = [ + { difficulty = 0, cmdline = 1, + name = "start-virt-tools", + link = "Where to get virt tools.", + rest = "Learn how to download or obtain virt tools on Fedora, + Debian, Ubuntu, RHEL and more." }, + { difficulty = 0, + name = "start-conventions", + link = "Names and terms used in the rest of the documentation.", + rest = "If you confused by words like <q>paravirt</q>, <q>migration</q>, + <q>domain</q>, then start here." }, + { difficulty = 0, + name = "start-install-with-virt-manager", + link = "Install a virtual machine", + rest = "with virt-manager. A step by step guide to creating + your first virtual machine using simple graphical tools." }, + { difficulty = 0, + name = "start-vm-with-virt-manager", + link = "Start and stop virtual machines", + rest = "using graphical virt-manager." }, + { difficulty = 0, cmdline = 1, + name = "start-list-with-command-line", + link = "List virtual machines", + rest = "from the command line and shell scripts." }, + { difficulty = 1, cmdline = 1, + name = "start-stop-vm-with-command-line", + link = "Start and stop virtual machines", + rest = "from the command line and shell scripts." }, + { difficulty = 1, cmdline = 1, + name = "check-hardware-virt", + link = "Check if your hardware supports virtualization.", + rest = "Hardware virtualization is supported by many but not all + modern hardware. If enabled it offers great performance + benefits. This article explains the different types of + hardware virtualization and how to check if your hardware + supports it." }, + { difficulty = 3, cmdline = 1, + name = "install-with-command-line", + link = "Install a virtual machine", + rest = "using the command line. Create a VM from the command line + and shell scripts." }, + { difficulty = 5, cmdline = 1, + author = "Richard W.M. Jones", date = "2010-10-12", + name = "advanced-virt-df", + link = "Advanced use of virt-df.", + rest = "Check free disk space. Regularly check from a cron job, + draw graphs to predict future usage, and generate alerts + if VMs are running low on space." }, +] + +# NB: Make sure you don't add blank lines to the end of this file! +-%] diff --git a/website/templates/google_analytics b/website/templates/google_analytics new file mode 100644 index 0000000..2c881d1 --- /dev/null +++ b/website/templates/google_analytics @@ -0,0 +1,14 @@ +[%# Google analytics for tracking. + Ask RWMJ for access to the account. %] + +<script type="text/javascript"> + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-19035706-1']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); +</script> diff --git a/website/templates/h2 b/website/templates/h2 new file mode 100644 index 0000000..d5f7db1 --- /dev/null +++ b/website/templates/h2 @@ -0,0 +1,11 @@ +<h2> +[%- IF anchor -%] +<a name="[% anchor %]"> +[%- END -%] +[% h2 %] +[%- IF anchor -%] +</a> <a href="#[% anchor %]" title="Permanent link to this heading" class="vtpermalink">#</a> +[%- END -%] +</h2> + +[% content %] diff --git a/website/templates/page b/website/templates/page new file mode 100644 index 0000000..93dd573 --- /dev/null +++ b/website/templates/page @@ -0,0 +1,56 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<title>[% title %]</title> +<meta name="description" content="Virt Tools are open source virtualization management tools for Linux system administrators. This site provides tutorials, videos, documentation, online help and roadmaps to help you understand and get started with the tools." /> +<meta name="keywords" content="virsh, virt-install, virt-manager, virt-top, virt-df, virt-p2v, virt-v2v, virt-viewer, virt-df, ncftool, augeas, aug-tool, guestfish, guestfs-browser, hivex, libguestfs, virt-what" /> +<link rel="stylesheet" href="[% topdir %]/css/standard.css" type="text/css" title="Standard"/> +[% IF local_stylesheet %]<link rel="stylesheet" href="style.css" type="text/css" title="Standard"/>[% END %] +<link rel="alternate stylesheet" href="[% topdir %]/css/easytoread.css" type="text/css" title="High contrast, big fonts"/> +</head> +<body> +<h1><span>[% h1 %]</span></h1> + +[% IF topdir == "../.." -%] +<p id="vtbacktosectiontop"> +(from <a href="../">[% section_titles.$section %]</a>) +</p> +[%- END %] + +<ul id="vtmenu"> +[% FOREACH s IN sections -%] + [%- IF section == s -%] + [%- IF topdir == "." || topdir == ".." -%] + <li class="vtmenuselected"> + <span>[% section_titles.$s %]</span> + </li> + [%- ELSE -%] + <li class="vtmenuselected"> + <a href="[% topdir %][% section_paths.$s %]">[% section_titles.$s %]</a> + </li> + [%- END -%] + [%- ELSE -%] + <li class="vtmenunotselected"> + <a href="[% topdir %][% section_paths.$s %]">[% section_titles.$s %]</a> + </li> + [%- END -%] +[%- END %] +</ul> + +[% content %] + +[% IF topdir == "../.." -%] +<p id="vtbacktosectionbottom"> +Back to <a href="../">[% section_titles.$section %]</a>. +</p> +[%- END %] + +<p id="vtfooter"> +Copyright © [% year %] <a href="http://redhat.com/">Red Hat Inc.</a> — +License: GPLv2+ — +Last updated on [% printable_date %] +</p> + +[%- INCLUDE google_analytics -%] +</body> +</html> diff --git a/website/templates/ttree.conf b/website/templates/ttree.conf new file mode 100644 index 0000000..69eea7c --- /dev/null +++ b/website/templates/ttree.conf @@ -0,0 +1,10 @@ +ignore = ~$ +copy = \.(gif|png|jpg|pdf)$ +recurse +verbose + +lib = templates +src = src +dest = build + +depend *=globals,page,h2 |
