New document: Installing from the command line.

2 files changed, 295 insertions, 0 deletions

diff --git a/website/src/learning/install-with-command-line/index.html b/website/src/learning/install-with-command-line/index.html
new file mode 100644
index 0000000..08ad739
--- /dev/null
+++ b/website/src/learning/install-with-command-line/index.html
@@ -0,0 +1,286 @@
+[% topdir = "../.." -%]
+[% PROCESS globals -%]
+[% WRAPPER page
+   title = "Installing a virtual machine using virt-install"
+   h1 = "Installing a virtual machine using virt-install"
+   section = "learning"
+   local_stylesheet = 1
+%]
+
+<p>
+Creating a virtual machine with virt-install involves the same steps
+as doing it <a href="../start-install-with-virt-manager/">graphically
+with virt-manager</a>.
+</p>
+
+<p>
+First you need to download an ISO of the
+operating system you want to install or you can do a
+<a href="#network">network install</a>.
+</p>
+
+[% WRAPPER h2 h2="Create space for the virtual disk" anchor="disk" %]
+
+<p>
+There are several decisions you have to make about how
+and where you want to create the virtual hard disk for
+the new guest:
+</p>
+
+<ol>
+<li> <b>How large?</b>
+  Decide how large you want the disk image to be.  This is the
+  maximum amount of disk space that the virtual machine will be
+  able to use, unless you take manual steps to increase it
+  (using <code>virt-resize</code>), so choose this wisely.
+  Even if you choose a format which <q>grows</q> (like sparse or
+  qcow2), this is a hard limit that you cannot easily grow beyond.
+  Below are some rough guides for minimum <i>operating system only</i>
+  space.  Remember if you want to store significant amounts of
+  data in the guest, you must add that requirement on top of
+  these figures.
+  <table>
+  <tr>
+  <th> Minimal </th>
+  <td> eg. Debian or FreeBSD, text only, configured with just the
+    essential components. </td>
+  <td> 2048&nbsp;MB </td>
+  </tr>
+  <tr>
+  <th> Linux </th>
+  <td> Typical Linux distribution, base install with graphical
+    components. </td>
+  <td> 8192&nbsp;MB </td>
+  </tr>
+  <tr>
+  <th> Windows </th>
+  <td> Recent version of Windows. </td>
+  <td> 16384&nbsp;MB </td>
+  </tr>
+  </table>
+  An example calculation: a Linux virtual machine for developers
+  &mdash; 8192 (base OS) + 1000 (compiler tools) + 20000 (space to check
+  out and compile software in home directory) = 29192&nbsp;MB.
+  </li>
+<li> <b>File, logical volume or SAN?</b>
+  Storing the disk as a plain host file is the easiest option.  As
+  long as you have enough free space, you can put the file anywhere,
+  and move it around later.  However file access isn't very
+  fast, so for the best performance you should choose an LVM2 logical
+  volume (LV) or (if you have it) a dedicated LUN on your SAN storage.
+  Using a host partition or host disk directly is not recommended
+  for security reasons.
+  </li>
+<li> <b>Fully allocated or sparse?</b>
+  If you choose <q>file</q> then you also have the option of using
+  a sparse file.  Sparse files are allocated on demand (as the guest
+  writes to them), which means you don't need to dedicate disk space
+  up-front.  On the other hand, sparse allocation is slow, and
+  if you allow the host to run out of disk space this can cause dangerous
+  data loss in the guest.
+  </li>
+<li> <b>Raw or qcow2?</b>
+  Again for file storage, you can choose a raw disk (just a massive
+  file which is a direct image of what is in the guest's disk), or
+  the more flexible <a href="http://en.wikipedia.org/wiki/Qcow2">qcow2
+  format</a>.  qcow2 images grow on-demand (a bit like sparse files),
+  and there are other features like snapshotting.  However out of all
+  the file options, qcow2 is the slowest.
+  </li>
+<li> <b>Snapshot?</b>
+  If you chose LV, qcow2 or SAN, then you might want to clone an
+  existing guest.  Snapshots are out of scope for this document.
+  For more information we suggest reading the <code>lvcreate(8)</code>
+  and/or <code>qemu-img(1)</code> man pages.
+  </li>
+<li> <b>libvirt storage pools?</b>
+  Libvirt now features storage management, and you can store your
+  VM disk images in a volume in a libvirt storage pool.  This is out
+  of scope for the current document, but we suggest
+  <a href="http://libvirt.org/storage.html">reading about libvirt storage
+  management here</a>.
+  </li>
+</ol>
+
+<p>
+With these decisions made, you can now go ahead and create the
+storage for the guest.  The examples below all assume that the
+disk will be 8192 MB in size (as the hard upper limit).  Adjust
+the number as required.
+</p>
+
+<p>
+To create a fully-allocated (non-sparse) raw file:
+</p>
+
+<pre>
+dd if=/dev/zero of=/var/lib/libvirt/images/guest.img bs=1M count=8192
+</pre>
+
+<p>
+or for newer versions of Linux, use the faster <code>fallocate(1)</code>
+program:
+</p>
+
+<pre>
+fallocate -l 8192M /var/lib/libvirt/images/guest.img
+</pre>
+
+<p>
+To create a sparse raw file:
+</p>
+
+<pre>
+rm -f /var/lib/libvirt/images/guest.img
+truncate --size=8192M /var/lib/libvirt/images/guest.img
+</pre>
+
+<p>
+To create a qcow2 file:
+</p>
+
+<pre>
+qemu-img create -f qcow2 /var/lib/libvirt/images/guest.qcow2 8192
+</pre>
+
+<p>
+To create an LVM2 logical volume in the volume group
+called <code>vg_host</code>:
+</p>
+
+<pre>
+lvcreate -n lv_guest -L 8192M /dev/vg_host
+</pre>
+
+<p>
+SAN LUN creation depends on your SAN, and you should consult that
+documentation.
+</p>
+
+<p>
+To create a libvirt volume in the <code>default</code>
+storage pool, do:
+</p>
+
+<pre>
+virsh vol-create-as default guest 8192M
+</pre>
+
+<p>
+The libvirt <code>default</code> storage pool is a directory
+<code>/var/lib/libvirt/images</code>, and you'll find the disk image
+under there.  <code>virsh vol-create-as</code> has several other
+options, and you might want to consult the <code>virsh(1)</code> man
+page.
+</p>
+
+[% END %]
+
+[% WRAPPER h2 h2="Create the virtual machine" anchor="create-vm" %]
+
+<p>
+Now you can create the virtual machine itself from the ISO
+which you downloaded and the disk image that you created.
+</p>
+
+<p>
+This is the basic virt-install command:
+</p>
+
+<pre>
+virt-install -r 1024 --accelerate -n Fedora14 \
+  -f /path/to/guest.img \
+  --cdrom Fedora-14-x86_64-Live.iso
+</pre>
+
+<p>
+The <code>-r</code> option specifies the amount of RAM (in megabytes).
+This depends on the operating system, but 768&nbsp;MB is a good
+starting point these days, and I use 1024&nbsp;MB for modern
+graphical Linux and Windows guests.
+</p>
+
+<p>
+<code>--accelerate</code> indicates you want to use hardware
+acceleration.  Recent versions of virt-install default to this.
+</p>
+
+<p>
+<code>-n</code> specifies the name of the virtual machine
+(as known to libvirt), and this is the name you will see
+in listings and use when <a href="../start-stop-vm-with-command-line/">starting
+and stopping the VM</a>.
+</p>
+
+<p>
+<code>-f</code> is the full path to the disk image you created before.
+For LVs, use the device path,
+eg. <code>-f&nbsp;/dev/vg_host/lv_guest</code>
+</p>
+
+<p>
+<code>--cdrom</code> is the path to the ISO file that you downloaded.
+The ISO is only needed during installation, and can be deleted
+after that.
+</p>
+
+<p>
+Other virt-install options that might be useful (read
+<code>virt-install(1)</code> for the full list) include:
+</p>
+
+<ul>
+<li> <code>--vcpus=N</code>
+  Specify an SMP guest with N virtual CPUs.
+  </li>
+<li> <code>--description</code>
+  Give a description string which appears in the libvirt XML.
+  </li>
+<li> <code>-l</code>
+  Use this to install from a network URL (instead of needing to
+  download an ISO).  See <a href="#network">network installs below</a>.
+  </li>
+<li> <code>--disk</code>
+  This option lets you specify other aspects of the disk such as
+  the format (qcow2 instead of raw).  See the man page for the
+  full details.
+  </li>
+<li> <code>--soundhw ac97</code>
+  Give the guest a (virtual) AC'97 soundcard.  Without this option
+  no soundcard is provided for the guest.
+  </li>
+</ul>
+
+[% END %]
+
+[% WRAPPER h2 h2="Advanced topic: Installing over the network" anchor="network" %]
+
+<p>
+Instead of downloading the ISO, you can install from public
+repositories over HTTP.  To do this, remove the <code>--cdrom</code>
+option and instead specify the
+<code>-l URL</code> option.  Some common locations that virt-install
+knows how to handle:
+</p>
+
+<ul>
+<li> <b>Fedora:</b>
+  <code>-l&nbsp;http://download.fedoraproject.org/pub/fedora/linux/releases/13/Fedora/i386/os/</code>
+  Change <q>13</q> to the Fedora release, and <q>i386</q>
+  to <code>x86_64</code> for a 64 bit guest.
+  </li>
+<li> <b>Debian:</b>
+  <code>-l&nbsp;http://ftp.us.debian.org/debian/dists/stable/main/installer-i386/</code>
+  Change <q>us</q> to your country code (for faster access to a local
+  mirror), and <q>i386</q> to <code>amd64</code> for a 64 bit guest.
+  </li>
+<li> <b>Ubuntu:</b>
+  <code>-l&nbsp;http://ftp.ubuntu.com/ubuntu/dists/maverick/main/installer-i386/</code>
+  Change <q>maverick</q> to the name of the version of Ubuntu to
+  install, and <q>i386</q> to <code>amd64</code> for a 64 bit guest.
+  </li>
+</ul>
+
+[% END %]
+
+[% END -%]
diff --git a/website/src/learning/install-with-command-line/style.css b/website/src/learning/install-with-command-line/style.css
new file mode 100644
index 0000000..704a74c
--- /dev/null
+++ b/website/src/learning/install-with-command-line/style.css
@@ -0,0 +1,9 @@
+table th {
+    vertical-align: top;
+    text-align: right;
+}
+
+table td {
+    vertical-align: top;
+    padding-left: 2em;
+}
\ No newline at end of file