LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity
LDP/LDP/howto/docbook/LVM-HOWTO.xml

5543 lines
200 KiB
XML
Raw Blame History

<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book>
<bookinfo>
<title>LVM HOWTO</title>
<author>
<firstname>AJ</firstname>
<surname>Lewis</surname>
<affiliation>
<address>
<email>alewis(at)rackable.com</email>
</address>
</affiliation>
</author>
<revhistory id="revhistory">
<revision>
<revnumber>0.19</revnumber>
<date>2006-11-27</date>
<authorinitials>ajl</authorinitials>
<revremark>
Clarified full snapshot conditions in <link linkend="snapshotintro"><xref linkend="snapshotintro"/></link> and <link linkend="snapbackcreate"><xref linkend="snapbackcreate"/></link> and added a note about resizing the origin of a snapshot;
Fixed Rackable copyright;
Fixed e-mail address
</revremark>
</revision>
<revision>
<revnumber>0.18</revnumber>
<date>2006-11-27</date>
<authorinitials>ajl</authorinitials>
<revremark>
Clarify whole disk usage in <link linkend="initdisks"><xref linkend="initdisks"/></link>;
Updated copyright;
Updated e-mail address
</revremark>
</revision>
<revision>
<revnumber>0.17</revnumber>
<date>2005-10-03</date>
<authorinitials>ajl</authorinitials>
<revremark>
Added FAQ entry for max size of LVs in LVM2;
Did some cleanup of "Recover physical volume metadata" section;
Updated e-mail address
</revremark>
</revision>
<revision>
<revnumber>0.16</revnumber>
<date>2005-07-15</date>
<authorinitials>ajl</authorinitials>
<revremark>
Added lvm2 boot-time scripts info;
Added "Recover physical volume metadata" section - thanks to
Maximilian Attems for the patch
</revremark>
</revision>
<revision>
<revnumber>0.15</revnumber>
<date>2005-06-09</date>
<authorinitials>ajl</authorinitials>
<revremark>
Removed references to xfs_freeze - it is no longer needed;
Updated snapshots subsection in Anatomy of LVM section;
Added a couple entries to the LVM2 FAQ;
Fixed a couple typos
</revremark>
</revision>
<revision>
<revnumber>0.14</revnumber>
<date>2004-10-06</date>
<authorinitials>ajl</authorinitials>
<revremark>
Added reference to lvm2_createinitrd in source tree;
Adjusted lvcreate example slightly; Added 'vgchange -ay' in
'Moving a volume group to another system' recipe
</revremark>
</revision>
<revision>
<revnumber>0.13</revnumber>
<date>2004-08-16</date>
<authorinitials>ajl</authorinitials>
<revremark>
Clarify symlink farm description;
Fix dm control device major number;
Remove /boot from vg in small lvm setup example;
Add notes about /boot and / on LVM;
Remove outdated link;
</revremark>
</revision>
<revision>
<revnumber>0.12</revnumber>
<date>2004-06-07</date>
<authorinitials>ajl</authorinitials>
<revremark>
Updated LVM2 FAQ entries
</revremark>
</revision>
<revision>
<revnumber>0.11</revnumber>
<date>2004-05-03</date>
<authorinitials>ajl</authorinitials>
<revremark>
Updated LVM2 FAQ entries
</revremark>
</revision>
<revision>
<revnumber>0.10</revnumber>
<date>2004-04-22</date>
<authorinitials>ajl</authorinitials>
<revremark>
removed -print0 from find command after receiving
reports that it doesn't work
</revremark>
</revision>
<revision>
<revnumber>0.9</revnumber>
<date>2004-04-16</date>
<authorinitials>ajl</authorinitials>
<revremark>
Added -print0 to find command before piping
it to cpio;
Changed vgimport command line for LVM 2;
Added ext3 to the ext2 resize section;
Updated FAQ;
Updated Links section
</revremark>
</revision>
<revision>
<revnumber>0.8</revnumber>
<date>2004-02-25</date>
<authorinitials>ajl</authorinitials>
<revremark>
Updated CVS locations and FTP links;
Added section on extending a JFS filesystem;
Fixed typos - Ran aspell against document
</revremark>
</revision>
<revision>
<revnumber>0.7</revnumber>
<date>2004-02-16</date>
<authorinitials>ajl</authorinitials>
<revremark>
Updated to include LVM 2 and device mapper information;
Updated email addresses;
Updated copyright;
Added FAQ section;
Added document license;
Updated to docbook 4.2
</revremark>
</revision>
<revision>
<revnumber>0.6</revnumber>
<date>2003-12-09</date>
<authorinitials>ajl</authorinitials>
<revremark>
Updated for LVM 1.0.8;
fixed broken link;
Clarified redhat init script section;
</revremark>
</revision>
<revision>
<revnumber>0.5</revnumber>
<date>2003-02-10</date>
<authorinitials>ajl</authorinitials>
<revremark>
Updated Redhat initscript information for 7.0 and above;
Added information on removing a partition table from a
disk if pvcreate fails;
Default PE size is 32MB now;
Updated method for snapshotting under XFS.
</revremark>
</revision>
<revision>
<revnumber>0.4</revnumber>
<date>2002-12-16</date>
<authorinitials>ajl</authorinitials>
<revremark>
Updated for LVM 1.0.6
</revremark>
</revision>
<revision>
<revnumber>0.3</revnumber>
<date>2002-09-16</date>
<authorinitials>ajl</authorinitials>
<revremark>
removed example pvmove from Command Operations section - we now
just point to the more detailed recipe on pvmove that contains
various warnings and such
</revremark>
</revision>
<revision>
<revnumber>0.2</revnumber>
<date>2002-09-11</date>
<authorinitials>ajl</authorinitials>
<revremark>
Updated for LVM 1.0.5 and converted to DocBook XML 4.1.2.
</revremark>
</revision>
<revision>
<revnumber>0.1</revnumber>
<date>2002-04-28</date>
<authorinitials>gf</authorinitials>
<revremark>
Initial conversion from Sistina's LaTeX source and import to
tLDP in LinuxDoc format.
</revremark>
</revision>
</revhistory>
<copyright>
<year>2002-2003</year>
<holder>Sistina Software, Inc</holder>
</copyright>
<copyright>
<year>2004-2005</year>
<holder>Red Hat, Inc</holder>
</copyright>
<copyright>
<year>2005-2006</year>
<holder>Terrascale Technologies, Inc</holder>
</copyright>
<copyright>
<year>2006</year>
<holder>Rackable Systems, Inc</holder>
</copyright>
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify
this document under the terms of the GNU Free
Documentation License, Version 1.2 published by the Free
Software Foundation; with no Invariant Sections, no
Front-Cover Texts and no Back-Cover Texts. A copy of the
license is included in the section entitled "GNU Free
Documentation License".
</para>
<para>
This document is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY, either expressed or
implied. While every effort has been taken to ensure the
accuracy of the information documented herein, the
author(s)/editor(s)/maintainer(s)/contributor(s) assumes
NO RESPONSIBILITY for any errors, or for any damages,
direct or consequential, as a result of the use of the
information documented herein.
</para>
</legalnotice>
<abstract>
<para>
This document describes how to build, install, and configure
LVM for Linux. A basic description of LVM is also included.
This version of the HowTo is for LVM 2 with device-mapper, as
well as LVM 1.0.8.
</para>
</abstract>
</bookinfo>
<preface id="intro"><title> Introduction </title>
<para>
This is an attempt to collect everything needed to know to get LVM up
and running. The entire process of getting, compiling, installing, and
setting up LVM will be covered. Pointers to LVM configurations that
have been tested with will also be included. This version of the
HowTo is for LVM 2 with device-mapper and LVM 1.0.8.
</para>
<para>
All previous versions of LVM are considered obsolete and are only kept
for historical reasons. This document makes no attempt to explain or
describe the workings or use of those versions.
</para>
<sect1 id="latest_version"><title>Latest Version</title>
<para>
We will keep the latest version of this HowTo in the CVS with the
other LDP Howtos. You can get it by checking out
``LDP/howto/docbook/LVM-HOWTO.xml'' from the tLDP CVS server.
You should always be able to get a human readable version of
this HowTo from the
<ulink url="http://www.tldp.org/HOWTO/LVM-HOWTO.html">
http://www.tldp.org/HOWTO/LVM-HOWTO.html
</ulink>
</para>
</sect1>
<sect1 id="disclaimer"><title>Disclaimer</title>
<para>
This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY, either expressed or implied. While every
effort has been taken to ensure the accuracy of the information
documented herein, the
author(s)/editor(s)/maintainer(s)/contributor(s) assumes NO
RESPONSIBILITY for any errors, or for any damages, direct or
consequential, as a result of the use of the information documented
herein.
</para>
</sect1>
<sect1 id="contributors"><title>Contributors</title>
<para>
List of everyone who has put words into this file.
</para>
<itemizedlist>
<listitem> <para>
<ulink url="mailto:alewis@redhat.com_NOSPAM">AJ Lewis</ulink>
</para> </listitem>
<listitem> <para>
<ulink url="mailto:thornber@redhat.com_NOSPAM">Joe Thornber</ulink>
</para> </listitem>
<listitem> <para>
<ulink url="mailto:pcaulfie@redhat.com_NOSPAM">Patrick Caulfield</ulink>
</para> </listitem>
<listitem> <para>
<ulink url="mailto:agk@redhat.com_NOSPAM">Alasdair Kergon</ulink>
</para> </listitem>
<listitem> <para>
<ulink url="mailto:jradmacher@gmx.de_NOSPAM"> Jochen Radmacher
</ulink> - JFS extend information
</para> </listitem>
</itemizedlist>
<para>
Please notify the HowTo maintainer if you believe you should be
listed above.
</para>
</sect1>
</preface>
<chapter id="whatislvm"><title>What is LVM?</title>
<para>
LVM is a Logical Volume Manager for the Linux operating system.
There are now two version of LVM for Linux:
<itemizedlist>
<listitem>
<para>
LVM 2 - The latest and greatest version of LVM for Linux.
</para>
<para>
LVM 2 is almost completely backward compatible with
volumes created with LVM 1. The exception to this is
snapshots (You must remove snapshot volumes before
upgrading to LVM 2)
</para>
<para>
LVM 2 uses the device mapper kernel driver. Device mapper
support is in the 2.6 kernel tree and there are patches
available for current 2.4 kernels.
</para>
</listitem>
<listitem>
<para>
LVM 1 - The version that is in the 2.4 series kernel,
</para>
<para>
LVM 1 is a mature product that has been considered stable
for a couple of years. The kernel driver for LVM 1 is
included in the 2.4 series kernels, but this does not mean
that your 2.4.x kernel is up to date with the latest
version of LVM. Look at the <ulink
url="ftp://ftp.sistina.com/pub/LVM/1.0/README">README</ulink>
for the latest information about which kernels have the
current code in them.
</para>
</listitem>
</itemizedlist>
</para>
</chapter>
<chapter id="whatisvolman"><title>What is Logical Volume Management?</title>
<para>
Logical volume management provides a higher-level view of the disk
storage on a computer system than the traditional view of disks and
partitions. This gives the system administrator much more flexibility
in allocating storage to applications and users.
</para>
<para>
Storage volumes created under the control of the logical volume
manager can be resized and moved around almost at will, although this
may need some upgrading of file system tools.
</para>
<para>
The logical volume manager also allows management of storage volumes in
user-defined groups, allowing the system administrator to deal with
sensibly named volume groups such as "development" and "sales" rather
than physical disk names such as "sda" and "sdb".
</para>
<sect1 id="whywouldiwantit"><title>Why would I want it?</title>
<para>
Logical volume management is traditionally associated with large
installations containing many disks but it is equally suited to
small systems with a single disk or maybe two.
</para>
</sect1>
<sect1 id="benefitsoflvmsmall"><title>Benefits of Logical Volume Management on a Small System</title>
<para>
One of the difficult decisions facing a new user installing Linux
for the first time is how to partition the disk drive. The need to
estimate just how much space is likely to be needed for system
files and user files makes the installation more complex than is
necessary and some users simply opt to put all their data into one
large partition in an attempt to avoid the issue.
</para>
<para>
Once the user has guessed how much space is needed for /home /usr /
(or has let the installation program do it) then is quite common
for one of these partitions to fill up even if there is plenty of
disk space in one of the other partitions.
</para>
<para>
With logical volume management, the whole disk would be allocated
to a single volume group and logical volumes created to hold the /
/usr and /home file systems. If, for example the /home logical
volume later filled up but there was still space available on /usr
then it would be possible to shrink /usr by a few megabytes and
reallocate that space to /home.
</para>
<para>
Another alternative would be to allocate minimal amounts of space
for each logical volume and leave some of the disk unallocated.
Then, when the partitions start to fill up, they can be expanded as
necessary.
</para>
<para>
As an example:
Joe buys a PC with an 8.4 Gigabyte disk on it and installs Linux
using the following partitioning system:
<screen>
/boot /dev/hda1 10 Megabytes
swap /dev/hda2 256 Megabytes
/ /dev/hda3 2 Gigabytes
/home /dev/hda4 6 Gigabytes
</screen>
This, he thinks, will maximize the amount of space available for all his MP3
files.
</para>
<para>
Sometime later Joe decides that he want to install the latest
office suite and desktop UI available but realizes that the root
partition isn't large enough. But, having archived all his MP3s
onto a new writable DVD drive there is plenty of space on /home.
</para>
<para>
His options are not good:
</para>
<orderedlist>
<listitem>
<para>
Reformat the disk, change the partitioning scheme and
reinstall.
</para>
</listitem>
<listitem>
<para>
Buy a new disk and figure out some new partitioning scheme
that will require the minimum of data movement.
</para>
</listitem>
<listitem>
<para>
Set up a symlink farm on / pointing to /home and install the new
software on /home
</para>
</listitem>
</orderedlist>
<para>
With LVM this becomes much easier:
</para>
<para>
Jane buys a similar PC but uses LVM to divide up the disk in a similar
manner:
</para>
<screen>
/boot /dev/hda1 10 Megabytes
swap /dev/vg00/swap 256 Megabytes
/ /dev/vg00/root 2 Gigabytes
/home /dev/vg00/home 6 Gigabytes
</screen>
<note>
<para>
boot is not included on the LV because bootloaders don't
understand LVM volumes yet. It's possible boot on LVM will
work, but you run the risk of having an unbootable system.
</para>
</note>
<warning> <title> root on LV should be used by advanced users only
</title>
<para>
root on LVM requires an initrd image that activates the root
LV. If a kernel is upgraded without building the necessary
initrd image, that kernel will be unbootable. Newer
distributions support lvm in their mkinitrd scripts as well
as their packaged initrd images, so this becomes less of an
issue over time.
</para>
</warning>
<para>
When she hits a similar problem she can reduce the size of /home by
a gigabyte and add that space to the root partition.
</para>
<para>
Suppose that Joe and Jane then manage to fill up the /home
partition as well and decide to add a new 20 Gigabyte disk to their
systems.
</para>
<para>
Joe formats the whole disk as one partition (/dev/hdb1) and moves
his existing /home data onto it and uses the new disk as /home. But
he has 6 gigabytes unused or has to use symlinks to make that disk
appear as an extension of /home, say /home/joe/old-mp3s.
</para>
<para>
Jane simply adds the new disk to her existing volume group and
extends her /home logical volume to include the new disk. Or, in
fact, she could move the data from /home on the old disk to the new
disk and then extend the existing root volume to cover all of the
old disk.
</para>
</sect1>
<sect1 id="benefitsoflvmlarge"><title>Benefits of Logical Volume Management on a Large System</title>
<para>
The benefits of logical volume management are more obvious on large
systems with many disk drives.
</para>
<para>
Managing a large disk farm is a time-consuming job, made
particularly complex if the system contains many disks of different
sizes. Balancing the (often conflicting) storage requirements of
various users can be a nightmare.
</para>
<para>
User groups can be allocated to volume groups and logical volumes
and these can be grown as required. It is possible for the system
administrator to "hold back" disk storage until it is required. It
can then be added to the volume(user) group that has the most
pressing need.
</para>
<para>
When new drives are added to the system, it is no longer necessary
to move users files around to make the best use of the new storage;
simply add the new disk into an existing volume group or groups and
extend the logical volumes as necessary.
</para>
<para>
It is also easy to take old drives out of service by moving the
data from them onto newer drives - this can be done online, without
disrupting user service.
</para>
</sect1>
</chapter>
<chapter id="anatomy"><title>Anatomy of LVM</title>
<para>
This diagram gives a overview of the main elements in an LVM system:
<screen>
+-- Volume Group --------------------------------+
| |
| +----------------------------------------+ |
| PV | PE | PE | PE | PE | PE | PE | PE | PE | |
| +----------------------------------------+ |
| . . . . |
| . . . . |
| +----------------------------------------+ |
| LV | LE | LE | LE | LE | LE | LE | LE | LE | |
| +----------------------------------------+ |
| . . . . |
| . . . . |
| +----------------------------------------+ |
| PV | PE | PE | PE | PE | PE | PE | PE | PE | |
| +----------------------------------------+ |
| |
+------------------------------------------------+
</screen>
</para>
<para>
Another way to look at is this (courtesy of
<ulink url="mailto:erik@bagfors.nu_NOSPAM">Erik B&#229;gfors</ulink>
on the linux-lvm mailing list):
<screen>
hda1 hdc1 (PV:s on partitions or whole disks)
\ /
\ /
diskvg (VG)
/ | \
/ | \
usrlv rootlv varlv (LV:s)
| | |
ext2 reiserfs xfs (filesystems)
</screen>
</para>
<sect1 id="VG"><title>volume group (VG)</title>
<para>
The Volume Group is the highest level abstraction used within the
LVM. It gathers together a collection of Logical Volumes and
Physical Volumes into one administrative unit.
</para>
</sect1>
<sect1 id="PV"><title>physical volume (PV)</title>
<para>
A physical volume is typically a hard disk, though it may well just
be a device that 'looks' like a hard disk (eg. a software raid
device).
</para>
</sect1>
<sect1 id="LV"><title>logical volume (LV)</title>
<para>
The equivalent of a disk partition in a non-LVM system. The LV is
visible as a standard block device; as such the LV can contain a
file system (eg. <filename class="directory">/home</filename>).
</para>
</sect1>
<sect1 id="PE"><title>physical extent (PE)</title>
<para>
Each physical volume is divided chunks of data, known as physical
extents, these extents have the same size as the logical extents
for the volume group.
</para>
</sect1>
<sect1 id="LE"><title>logical extent (LE)</title>
<para>
Each logical volume is split into chunks of data, known as logical
extents. The extent size is the same for all logical volumes in
the volume group.
</para>
</sect1>
<sect1 id="tyingittogether"><title>Tying it all together</title>
<para>
A concrete example will help:
</para>
<para>
Lets suppose we have a volume group called VG1, this volume group
has a physical extent size of 4MB. Into this volume group we
introduce 2 hard disk partitions, /dev/hda1 and /dev/hdb1. These
partitions will become physical volumes PV1 and PV2 (more
meaningful names can be given at the administrators discretion).
The PV's are divided up into 4MB chunks, since this is the extent
size for the volume group. The disks are different sizes and we
get 99 extents in PV1 and 248 extents in PV2. We now can create
ourselves a logical volume, this can be any size between 1 and 347
(248 + 99) extents. When the logical volume is created a mapping
is defined between logical extents and physical extents, eg.
logical extent 1 could map onto physical extent 51 of PV1, data
written to the first 4 MB of the logical volume in fact be written
to the 51st extent of PV1.
</para>
</sect1>
<sect1 id="mapmode"><title>mapping modes (linear/striped)</title>
<para>
The administrator can choose between a couple of general strategies
for mapping logical extents onto physical extents:
</para>
<orderedlist>
<listitem> <para>
<emphasis role="strong">Linear mapping</emphasis> will assign a
range of PE's to an area of an LV in order eg., LE 1 - 99 map to
PV1 and LE 100 - 347 map onto PV2.
</para> </listitem>
<listitem><para>
<emphasis role="strong">Striped mapping</emphasis> will interleave
the chunks of the logical extents across a number of physical
volumes eg.,
<screen>
1st chunk of LE[1] -&gt; PV1[1],
2nd chunk of LE[1] -&gt; PV2[1],
3rd chunk of LE[1] -&gt; PV3[1],
4th chunk of LE[1] -&gt; PV1[2],
</screen>
and so on. In certain situations this strategy can
improve the performance of the logical volume.
<warning> <title> LVM 1 Caveat </title>
<para>
LVs created using striping cannot be extended past
the PVs they were originally created on in LVM 1.
</para>
</warning>
In LVM 2, striped LVs can be extended by concatenating
another set of devices onto the end of the first set. So
you can get into a situation where your LV is a 2 stripe
set concatenated with a linear set concatenated with a 4
stripe set. Are you confused yet?
</para> </listitem>
</orderedlist>
</sect1>
<sect1 id="snapshotintro"><title>Snapshots</title>
<para>
A wonderful facility provided by LVM is 'snapshots'. This
allows the administrator to create a new block device which
presents an exact copy of a logical volume, frozen at some
point in time. Typically this would be used when some batch
processing, a backup for instance, needs to be performed on
the logical volume, but you don't want to halt a live system
that is changing the data. When the snapshot device has been
finished with the system administrator can just remove the
device. This facility does require that the snapshot be made
at a time when the data on the logical volume is in a
consistent state - the VFS-lock patch for LVM1 makes sure that
some filesystems do this automatically when a snapshot is
created, and many of the filesystems in the 2.6 kernel do this
automatically when a snapshot is created without patching.
</para>
<warning><title>Full snapshot are automatically disabled</title>
<para>
If the snapshot logical volume becomes full it will be dropped
(become unusable) so it is vitally important to allocate enough space.
The amount of space necessary is dependent on the usage of the
snapshot, so there is no set recipe to follow for this. If the
snapshot size equals the origin size, it will never overflow.
</para>
</warning>
<para>
LVM1 has read-only snapshots. Read-only snapshots work by
creating an <emphasis>exception table</emphasis>, which is
used to keep track of which blocks have been changed. If a
block is to be changed on the origin, it is first copied to
the snapshot, marked as copied in the exception table, and
then the new data is written to the original volume.
</para>
<para>
In LVM2, snapshots are read/write by default. Read/write
snapshots work like read-only snapshots, with the additional
feature that if data is written to the snapshot, that block is
marked in the exception table as used, and never gets copied
from the original volume. This opens up many new
possibilities that were not possible with LVM1's read-only
snapshots. One example is to snapshot a volume, mount the
snapshot, and try an experimental program that change files on
that volume. If you don't like what it did, you can unmount
the snapshot, remove it, and mount the original filesystem in
its place. It is also useful for creating volumes for use
with <ulink
url="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/">Xen</ulink>.
You can create a disk image, then snapshot it and modify the
snapshot for a particular domU instance. You can then create
another snapshot of the original volume, and modify that one
for a different domU instance. Since the only storage used by
a snapshot is blocks that were changed on the origin or the
snapshot, the majority of the volume is shared by the domU's.
</para>
<note>
<para>
With the current LVM2/device-mapper code, the origin can be
grown, but not shrunk. With LVM1, you cannot resize the origin.
</para>
</note>
<warning> <title> LVM 1 -> LVM 2 Upgrade Info </title>
<para>
Make sure to remove snapshot LVs before upgrading from
LVM 1 to LVM 2. (See <xref linkend="lvm2faq"/>)
</para>
</warning>
</sect1>
</chapter>
<chapter id="FAQ"><title>Frequently Asked Questions</title>
<sect1 id="lvm2faq"><title>LVM 2 FAQ</title>
<qandaset>
<qandaentry>
<question>
<para>
I have LVM 1 installed and running on my system. How do
I start using LVM 2?
</para>
</question>
<answer>
<para>
Here's the Quick Start instructions :)
<orderedlist>
<listitem>
<para>
Start by removing any snapshot LVs on the system.
These are not handled by LVM 2 and will prevent the
origin from being activated when LVM 2 comes up.
</para>
</listitem>
<listitem>
<para>
Make sure you have some way of booting the system
other than from your standard boot partition. Have
the LVM 1 tools, standard system tools (mount) and
an LVM 1 compatible kernel on it in case you need to
get back and fix some things.
</para>
</listitem>
<listitem>
<para>
Grab the LVM 2 tools source and the device mapper
source and compile them. You need to install the
device mapper library using <quote>make
install</quote> before compiling the LVM 2 tools.
Also copy the dm/scripts/devmap_mknod.sh script into
/sbin. I recommend only installing the 'lvm' binary
for now so you have access to the LVM 1 tools if you
need them. If you have access to packages for LVM 2
and device-mapper, you can install those instead,
but beware of them overwriting your LVM 1 tool set.
</para>
</listitem>
<listitem>
<para>
Get a device mapper compatible kernel, either built
in or as a kernel module.
</para>
</listitem>
<listitem>
<para>
Figure out where LVM 1 was activated in your startup
scripts. Make sure the device-mapper module is
loaded by that point (if you are using device mapper
as a module) and add '/sbin/devmap_mknod.sh; lvm
vgscan; lvm vgchange -ay' afterward.
</para>
</listitem>
<listitem>
<para>
Install the kernel with device mapper support in it.
Reboot. If all goes well, you should be running with
lvm2.
</para>
</listitem>
</orderedlist>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Do I need a special lvm2 kernel module?
</para>
</question>
<answer>
<para>
No. You need device-mapper. The lvm2 tools use
device-mapper to interface with the kernel and do all
their device mapping (hence the name device-mapper). As
long as you have device-mapper, you should be able to
use LVM2.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
I get errors about
<filename>/dev/mapper/control</filename> when I try to
use the LVM 2 tools. What's going on?
</para>
</question>
<answer>
<para>
The primary cause of this is not having run the
<quote>dmsetup mknodes</quote> after rebooting into a dm
capable kernel. This script generates the control node
for device mapper.
</para>
<para>
If you don't have the <quote>dmsetup mknodes</quote>,
don't despair! (Though you should probably upgrade to
the latest version of device-mapper.) It's pretty easy
to create the <filename>/dev/mapper/control</filename>
file on your own:
<orderedlist>
<listitem>
<para>
Make sure you have the device-mapper module loaded
(if you didn't build it into your kernel).
</para>
</listitem>
<listitem>
<para>
Run
<screen># cat /proc/misc | grep device-mapper | awk '{print $1}'</screen>
and note the number
printed. (If you don't get any output, refer to
step 1.)
</para>
</listitem>
<listitem>
<para>
Run <screen># mkdir /dev/mapper</screen> - if you
get an error saying
<filename>/dev/mapper</filename> already exists,
make sure it's a directory and move on.
</para>
</listitem>
<listitem>
<para>
Run
<screen># mknod /dev/mapper/control c 10 $number</screen>
where $number is the number printed in step 2.
</para>
</listitem>
</orderedlist>
You should be all set now!
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Which commands and types of logical volumes are
currently supported in LVM 2?
</para>
</question>
<answer>
<para>
If you are using the stable 2.4 device mapper patch from
the lvm2 tarball, all the major functionality you'd
expect using lvm1 is supported with the lvm2 tools.
(You still need to remove snapshots before upgrading
from lvm1 to lvm2)
</para>
<para>
If you are using the version of device mapper in the 2.6
kernel.org kernel series the following commands and LV
types are not supported:
<itemizedlist>
<listitem>
<para> pvmove </para>
</listitem>
<listitem>
<para> snapshots </para>
</listitem>
</itemizedlist>
The beginnings of support for these features are in the
<ulink url="http://people.sistina.com/~thornber/dm/">
unstable device mapper patches</ulink> maintained by Joe
Thornber.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Does LVM 2 use a different format from LVM 1 for it's
ondisk representation of Volume Groups and Logical
Volumes?
</para>
</question>
<answer>
<para>
Yes. LVM 2 uses lvm 2 format metadata. This format is much
more flexible than the LVM 1 format metadata, removing
or reducing most of the limitations LVM 1 had.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Does LVM 2 support VGs and LVs created with LVM 1?
</para>
</question>
<answer>
<para>
Yes. LVM 2 will activate and operate on VG and LVs created
with LVM 1. The exception to this is snapshots created with
LVM 1 - these should be removed before upgrading. Snapshots
that remain after upgrading will have to be removed before
their origins can be activated by LVM 2.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Can I upgrade my LVM 1 based VGs and LVs to LVM 2 native
format?
</para>
</question>
<answer>
<para>
Yes. Use vgconvert to convert your VG and all LVs contained
within it to the new lvm 2 format metadata. Be warned that it's
not always possible to revert back to lvm 1 format metadata.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
I've upgraded to LVM 2, but the tools keep failing with out
of memory errors. What gives?
</para>
</question>
<answer>
<para>
One possible cause of this is that some versions of LVM
1 (The user that reported this bug originally was using
Mandrake 9.2, but it is not necessarily limited to that
distribution) did not put a UUID into the PV and VG
structures as they were supposed to. The most current
versions of the LVM 2 tools automatically fill UUIDs in
for the structures if they see they are missing, so you
should grab a more current version and your problem
should be solved. If not, post to the <link
linkend="Maillists">linux-lvm mailing list</link>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
I have my root partition on an LV in LVM 1. How do I
upgrade to LVM 2? And what happened to lvmcreate_initrd?
</para>
</question>
<answer>
<para>
Upgrading to LVM 2 is a bit trickier with root on LVM,
but it's not impossible. You need to queue up a kernel
with device-mapper support and install the lvm2 tools
(you might want to make a backup of the lvm 1 tools, or
find a rescue disk with the lvm tools built in, in case
you need them before you're done). Then find a mkinitrd
script that has support for your distro and lvm 2.
</para>
<para>
Currently, this is the list of mkinitrd scripts that I
know support lvm2, sorted by distro:
<variablelist><title>mkinitrd scripts with lvm 2 support</title>
<varlistentry><term>fedora</term>
<listitem>
<para>
The latest fedora core 2 <ulink
url="http://distro.ibiblio.org/pub/linux/distributions/fedora/linux/core/development/i386/Fedora/RPMS/mkinitrd-3.5.21-1.i386.rpm">mkinitrd</ulink>
handles lvm2, but it relies on a statically
built lvm binary from the latest lvm 2 tarball.
</para>
<para>
Redhat 9 users may be able to use this as well
</para>
</listitem>
</varlistentry>
<varlistentry><term>Debian</term>
<listitem>
<para>
There is an unofficial version <ulink
url="http://www.poochiereds.net/svn/lvm2/">here</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry><term>Generic</term>
<listitem>
<para>
There is a version in the lvm2 source tree under
<filename>scripts/lvm2_createinitrd/</filename>.
See the documentation in that directory for more
details.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How resilient is LVM to a sudden renumbering of
physical hard disks?
</para>
</question>
<answer>
<para>
It's fine - LVM identifies PVs by UUID, not by device
name.
</para>
<para>
Each disk (PV) is labeled with a UUID, which uniquely
identifies it to the system. 'vgscan' identifies this
after a new disk is added that changes your drive
numbering. Most distros run vgscan in the lvm startup
scripts to cope with this on reboot after a hardware
addition. If you're doing a hot-add, you'll have to run
this by hand I think. On the other hand, if your vg is
activated and being used, the renumbering should not
affect it at all. It's only the activation that needs
the identifier, and the worst case scenario is that the
activation will fail without a vgscan with a complaint
about a missing PV.
</para>
<note>
<para>
The failure or removal of a drive that LVM is
currently using will cause problems with current use
and future activations of the VG that was using it.
</para>
</note>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
I'm trying to fill my vg, and vgdisplay/vgs says that I
have 1.87 GB free, but when I do an lvcreate vg -L1.87G
it says "insufficient free extends". What's going on?
</para>
</question>
<answer>
<para>
The 1.87 GB figure is rounded to 2 decimal places, so
it's probably 1.866 GB or something. This is a
human-readable output to give you a general idea of how
big the VG is. If you want to specify an exact size,
you must use extents instead of some multiple of bytes.
</para>
<para>
In the case of vgdisplay, use the Free PE count instead
of the human readable capacity.
<screen>
Free PE / Size 478 / 1.87 GB
^^^
</screen>
So, this would indicate that you should do run
<screen>
# lvcreate vg -l478 </screen> Note that instead of an upper-case 'L',
we used a lower-case 'l' to tell lvm to use extents
instead of bytes.
</para>
<para>
In the case of vgs, you need to instruct it to tell you how many extents are available:
<screen>
# vgs -o +vg_free_count,vg_extent_count
</screen>
This tell vgs to add the free extents and the total
number of extents to the end of the vgs listing. Use
the free extent number the same way you would in the
above vgdisplay case.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How are snapshots in LVM2 different from LVM1?
</para>
</question>
<answer>
<para>
In LVM2 snapshots are read/write by default, whereas in
LVM1, snapshots were only read-only. See <xref
linkend="snapshotintro"/> for more details
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
What is the maximum size of a single LV?
</para>
</question>
<answer>
<para>
The answer to this question depends upon the CPU
architecture of your computer and the kernel you are a
running:
<itemizedlist>
<listitem>
<para>
For 2.4 based kernels, the maximum LV size is 2TB.
For some older kernels, however, the limit was 1TB
due to signedness problems in the block layer.
Red Hat Enterprise Linux 3 Update 5 has fixes to
allow the full 2TB LVs. Consult your distribution
for more information in this regard.
</para>
</listitem>
<listitem>
<para>
For 32-bit CPUs on 2.6 kernels, the maximum LV size is 16TB.
</para>
</listitem>
<listitem>
<para>
For 64-bit CPUs on 2.6 kernels, the maximum LV
size is 8EB. (Yes, that is a very large number.)
</para>
</listitem>
</itemizedlist>
</para>
</answer>
</qandaentry>
</qandaset>
</sect1>
<sect1 id="lvm1faq"><title>LVM 1 FAQ</title>
<qandaset>
<qandaentry>
<question>
<para>
When will there be info here?
</para>
</question>
<answer>
<para>
When people start submitting FAQ entries ;)
</para>
</answer>
</qandaentry>
</qandaset>
</sect1>
</chapter>
<!-- FIXME: I need to add LVM 2 information here -->
<chapter id="getlvm"><title>Acquiring LVM</title> <!--label id="getlvm"-->
<para>
The first thing you need to do is get a copy of LVM.
<itemizedlist>
<listitem>
<para> Download via FTP a tarball of LVM. </para>
</listitem>
<listitem>
<para>
Download the source that is under active development via
CVS
</para>
</listitem>
</itemizedlist>
</para>
<sect1 id="downloadsource"><title>Download the source</title>
<para>
<itemizedlist>
<listitem>
<para>
<ulink url="ftp://sources.redhat.com/pub/dm/">
Device Mapper </ulink>
</para>
</listitem>
<listitem>
<para>
<ulink
url="ftp://sources.redhat.com/pub/lvm2/">
LVM 2
</ulink>
</para>
<para>
Make sure you also grab the device mapper
source
</para>
</listitem>
<listitem>
<para>
<ulink
url="ftp://sources.redhat.com/pub/lvm/current/"> LVM
1
</ulink>
</para>
</listitem>
</itemizedlist>
</para>
<note>
<para>
The LVM 1 kernel patch must be generated using the LVM 1 source.
More information regarding this can be found in
<!--fixme-->
<xref linkend="buildlvmmod"/>
</para>
</note>
</sect1>
<sect1 id="PublicCVS"><title>Download the development source via CVS</title> <!--label id="PublicCVS"-->
<para>
<emphasis role="strong">Note:</emphasis> the state of code in the
CVS repository fluctuates wildly. It will contain bugs. Maybe ones
that will crash LVM or the kernel. It may not even compile.
Consider it alpha-quality code. You could lose data. You have
been warned.
</para>
</sect1>
<sect1 id="beforebeginning"><title>Before You Begin</title>
<para>
To follow the development progress of LVM, subscribe to the
LVM mailing lists, linux-lvm and the appropriate commit list
(see <xref linkend="Maillists"/>).
</para>
<para>
To build LVM from the CVS sources, you
<emphasis role="strong">must</emphasis> have several GNU tools:
</para>
<itemizedlist>
<listitem> <para> the CVS client version 1.9 or better</para></listitem>
<listitem> <para>GCC 2.95.2</para></listitem>
<listitem> <para>GNU make 3.79</para></listitem>
<listitem> <para>autoconf, version 2.13 or better</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="initsetup"><title>Initial Setup</title>
<para>
To make life easier in the future with regards to updating the CVS
tree create the file <filename>$HOME/.cvsrc</filename> and
insert the following lines. This configures useful defaults for
the three most commonly used CVS commands. Do this now before
proceeding any further.
</para>
<screen>
diff -u -b -B
checkout -P
update -d -P
</screen>
<para>
Also, if you are on a slow net link (like a dialup), you will want
to add a line containing <filename>cvs -z5</filename> in this file.
This turns on a useful compression level for all CVS commands.
</para>
</sect1>
<sect1 id="checkoutsource"><title>Checking Out Source Code</title>
<itemizedlist>
<listitem>
<para>
<emphasis role="strong">Device Mapper library and
tools</emphasis>
</para>
<para> The device mapper library is required to build LVM 2.
</para>
<para>
The first time you download from cvs, you must login
<screen>
<command> # cvs -d :pserver:cvs@sources.redhat.com:/cvs/dm login cvs
</command>
</screen>
</para>
<para>
The password is `cvs'. The command outputs nothing if
successful and an error message if it fails. Only an
initial login is required. All subsequent CVS commands
read the password stored in the file
<filename>$HOME/.cvspass</filename> for authentication.
</para>
<para>
Use the following to check out a copy of the code
</para>
<screen>
<command> # cvs -d :pserver:cvs@sources.redhat.com:/cvs/dm checkout device-mapper
</command>
</screen>
<para>
This will create a new directory
<filename>device-mapper</filename> in your current
directory containing the latest, up-to-the-minute
device mapper code.
</para>
</listitem>
<listitem>
<para> <emphasis role="strong">LVM 2</emphasis>
</para>
<para>
The first time you download from cvs, you must login
<screen>
<command> # cvs -d :pserver:cvs@sources.redhat.com:/cvs/lvm2 login cvs
</command>
</screen>
</para>
<para>
The password is `cvs'. The command outputs nothing if
successful and an error message if it fails. Only an
initial login is required. All subsequent CVS commands
read the password stored in the file
<filename>$HOME/.cvspass</filename> for authentication.
</para>
<para>
Use the following to check out a copy of the code
</para>
<screen>
<command> # cvs -d :pserver:cvs@sources.redhat.com:/cvs/lvm2 checkout LVM2
</command>
</screen>
<para>
This will create a new directory
<filename>LVM2</filename> in your current
directory containing the latest, up-to-the-minute
LVM 2 code.
</para>
</listitem>
<listitem>
<para> <emphasis role="strong">LVM 1</emphasis>
</para>
<para>
The first time you download from cvs, you must login
<screen>
<command> # cvs -d :pserver:cvs@sources.redhat.com:/cvs/lvm login cvs
</command>
</screen>
</para>
<para>
The password is `cvs'. The command outputs nothing if
successful and an error message if it fails. Only an
initial login is required. All subsequent CVS commands
read the password stored in the file
<filename>$HOME/.cvspass</filename> for authentication.
</para>
<para>
Use the following to check out a copy of the code
</para>
<screen>
<command> # cvs -d :pserver:cvs@sources.redhat.com:/cvs/lvm checkout LVM
</command>
</screen>
<para>
This will create a new directory
<filename>LVM</filename> in your current
directory containing the latest, up-to-the-minute
LVM 1 code.
</para>
</listitem>
</itemizedlist>
<para>
CVS commands work from <emphasis>anywhere</emphasis> inside the
source tree, and recurse downward. So if you happen to issue an
update from inside the `tools' subdirectory it will work fine, but
only update the tools directory and it's subdirectories. In the
following command examples it is assumed that you are at the top of
the source tree.
</para>
</sect1>
<sect1 id="codeupdate"><title>Code Updates</title>
<para>
Code changes are made fairly frequently in the CVS repository.
Announcements of this are automatically sent to the lvm-commit
list.
</para>
<para>
You can update your copy of the sources to match the master
repository with the update command. It is not necessary to check
out a new copy. Using update is significantly faster and simpler,
as it will download only patches instead of entire files and update
only those files that have changed since your last update. It will
automatically merge any changes in the CVS repository with any
local changes you have made as well. Just cd to the directory you'd
like to update and then type the following.
</para>
<screen>
<command> # cvs update </command>
</screen>
<para>
If you did not specify a tag when you checked out the source, this
will update your sources to the latest version on the main branch.
If you specified a branch tag, it will update to the latest version
on that branch. If you specified a version tag, it will not do
anything.
</para>
</sect1>
<sect1 id="startproj"><title>Starting a Project</title>
<para>
Discuss your ideas on the developers list before you start.
Someone may be working on the same thing you have in mind or they
may have some good ideas about how to go about it.
</para>
</sect1>
<sect1 id="hackingcode"><title>Hacking the Code</title>
<para>
So, have you found a bug you want to fix? Want to implement a
feature from the TODO list? Got a new feature to implement?
Hacking the code couldn't be easier. Just edit your copy of the
sources. No need to copy files to <filename>.orig</filename> or
anything. CVS has copies of the originals.
</para>
<para>
When you have your code in a working state and have tested as best
you can with the hardware you have, generate a patch against the
<emphasis>current</emphasis> sources in the CVS repository.
</para>
<screen>
<command> # cvs update
# cvs diff &gt; patchfile</command>
</screen>
<para>
Mail the patch to the linux-lvm or dm-devel list (<xref linkend="Maillists"/>)
with a description of what changes or additions you implemented.
</para>
</sect1>
<sect1 id="conflicts"><title>Conflicts</title>
<para>
If someone else has been working on the same files as you have, you
may find that there are conflicting modifications. You'll discover
this when you try to update your sources.
</para>
<screen>
<command> # cvs update </command>
<computeroutput>
RCS file: LVM/tools/pvcreate.c,v
retrieving revision 1.5
retrieving revision 1.6
Merging differences between 1.5 and 1.6 into pvcreate.c
rcsmerge: warning: conflicts during merge
cvs server: conflicts found in tools/pvcreate.c
C tools/pvcreate.c
</computeroutput>
</screen>
<para>
Don't panic! Your working file, as it existed before the update, is
saved under the filename <filename>.#pvcreate.c.1.5</filename>.
You can always recover it should things go horribly wrong. The
file named `pvcreate.c' now contains
<emphasis role="strong">both</emphasis> the old (i.e. your) version
and new version of lines that conflicted. You simply edit the file
and resolve each conflict by deleting the unwanted version of the
lines involved.
</para>
<screen>
&lt;&lt;&lt;&lt;&lt;&lt;&lt; pvcreate.c
j++;
=======
j--;
&gt;&gt;&gt;&gt;&gt;&gt;&gt; 1.6
</screen>
<para>
Don't forget to delete the lines with all the ``&lt;'', ``='', and
``&gt;'' symbols.
</para>
</sect1>
</chapter>
<chapter id="buildkernelmods"><title>Building the kernel modules</title> <!--label id="buildlvmmod"-->
<sect1 id="builddmmod"><title>Building the device-mapper module</title>
<para>
Device mapper is in 2.6.9 and later, so you just need to make
sure it is enabled either as a module or builtin to the
kernel. Look for /sys/class/misc/device-mapper or look in
/proc/devices for a device-mapper entry to see if it is
enabled. If neither are there, try modprobe dm_mod, then
check again. For versions previous to 2.6.9, either you or
your distro must patch the kernel to support it. Check the
<ulink url="http://sources.redhat.com/dm/">device
mapper</ulink> web page for more information.
</para>
</sect1>
<sect1 id="buildlvmmod"><title>Build the LVM 1 kernel module</title>
<para>
To use LVM 1 you will have to build the LVM 1 kernel module
(recommended), or if you prefer rebuild the kernel with the
LVM 1 code statically linked into it.
</para>
<para>
Your Linux system is probably based on one of the popular
distributions (eg., Red Hat, SuSE, Debian) in which case it
is possible that you already have the LVM 1 module. Check
the version of the tools you have on your system. You can do
this by running any of the LVM command line tools with the
'-h' flag. Use <command>pvscan -h</command> if you don't
know any of the commands. If the version number listed at
the top of the help listing is LVM 1.0.8, <emphasis
role="strong">use your current setup</emphasis> and avoid the
rest of this section.
</para>
<sect2 id="buildlvmpatch"><title>Building a patch for your kernel</title> <!--label id="buildlvmpatch"-->
<para>
In order to patch the linux kernel to support LVM 1.0.8, you must
do the following:
<orderedlist>
<listitem><para> Unpack LVM 1.0.8 </para>
<screen>
<command> # tar zxf lvm_1.0.8.tar.gz </command>
</screen>
</listitem>
<listitem> <para> Enter the root directory of that version. </para>
<screen>
<command> # cd LVM/1.0.8 </command>
</screen>
</listitem>
<listitem><para> Run configure</para>
<screen>
<command> # ./configure </command>
</screen>
<para>
You will need to pass the option
<option>--with-kernel_dir</option> to configure if your
linux kernel source is not in
<filename class="directory">/usr/src/linux</filename>.
(Run <command>./configure --help</command> to see all the
options available)
</para>
</listitem>
<listitem><para> Enter the PATCHES directory</para>
<screen>
<command> # cd PATCHES </command>
</screen>
</listitem>
<listitem><para> Run 'make'</para>
<screen>
<command># make </command>
</screen>
<para>
You should now have a patch called
<filename>lvm-1.0.8-$KERNELVERSION.patch</filename> in the
patches directory. This is the LVM kernel patch referenced
in later sections of the howto.
</para>
</listitem>
<listitem><para> Patch the kernel</para>
<screen>
<command> # cd /usr/src/linux ; patch -pX &lt; /directory/lvm-1.0.8-$KERNELVERSION.patch </command>
</screen>
</listitem>
</orderedlist>
</para>
</sect2>
<sect2 id="buildlvm1-2.2"><title>Building the LVM module for Linux 2.2.17+</title>
<para>
The 2.2 series kernel needs to be patched before you can start
building, look elsewhere for instructions on how to patch your
kernel.
</para>
<para>
Patches:
</para>
<orderedlist>
<listitem>
<para>
<emphasis role="strong">rawio patch</emphasis>
</para>
<para>
Stephen Tweedie's raw_io patch which can be found at
<ulink url="http://www.kernel.org/pub/linux/kernel/people/sct/raw-io">http://www.kernel.org/pub/linux/kernel/people/sct/raw-io</ulink>
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">lvm patch</emphasis>
</para>
<para>
The relevant LVM 1 patch which should be built out
of the PATCHES sub-directory of the LVM
distribution. More information can be found in
<xref linkend="buildlvmpatch"/>, Building a patch
for your kernel.
</para>
</listitem>
</orderedlist>
<para>
Once the patches have been correctly applied, you need to make sure
that the module is actually built, LVM 1 lives under the block
devices section of the kernel config, you should probably request
that the LVM /proc information is compiled as well.
</para>
<para>
Build the kernel modules as usual.
</para>
</sect2>
<sect2 id="buildlvm1-2.4"><title>Building the LVM modules for Linux 2.4</title>
<para>
The 2.4 kernel comes with LVM 1 already included although
you should check at the Sistina web site for updates,
(eg. v2.4.9 kernels and earlier must have the <link
linkend="buildlvmpatch">latest LVM 1 patch</link> applied ).
When configuring your kernel look for LVM 1 under <emphasis
role="strong">Multi-device support (RAID and
LVM)</emphasis>. LVM 1 can be compiled into the kernel or as
a module. Build your kernel and modules and install then
in the usual way. If you chose to build LVM as a module it
will be called <filename>lvm-mod.o</filename>
</para>
<para>
If you want to use snapshots with ReiserFS, make sure you apply the
<filename>linux-2.4.x-VFS-lock</filename> patch (there are copies
of this in the
<filename class="directory">LVM/1.0.8/PATCHES</filename> directory.)
</para>
</sect2>
<sect2 id="checkproc"><title>Checking the proc file system</title>
<para>
If your kernel was compiled with the /proc file system (most are)
then you can verify that LVM is present by looking for a /proc/lvm
directory. If this doesn't exist then you may have to load the
module with the command
</para>
<screen>
<command> # modprobe lvm-mod </command>
</screen>
<para>
If <filename> /proc/lvm </filename> still does not exist then check
your kernel configuration carefully.
</para>
<para>
When LVM is active you will see entries in
<filename>/proc/lvm</filename> for all your physical volumes,
volume groups and logical volumes. In addition
there is a <quote>file</quote> called
<filename>/proc/lvm/global</filename> which gives a summary
of the LVM status and also shows just which version of the LVM
kernel you are using.
</para>
</sect2>
</sect1>
</chapter>
<chapter id="boot_scripts"><title>LVM 1 Boot time scripts</title>
<para>
Boot-time scripts are not provided as part of the LVM distribution,
however these are quite simple to do for yourself.
</para>
<para>
The startup of LVM requires just the following two commands:
</para>
<screen>
<command> # vgscan
# vgchange -ay </command>
</screen>
<para>
And the shutdown only one:
</para>
<screen>
<command> # vgchange -an</command>
</screen>
<para>
Follow the instructions below depending on the distribution of
Linux you are running.
</para>
<sect1 id="initscriptcaldera"><title>Caldera</title>
<para>
It is necessary to edit the file
<filename>/etc/rc.d/rc.boot</filename>. Look for the line that
says <quote>Mounting local filesystems</quote> and insert the
vgscan and vgchange commands just before it.
</para>
<para>
You may also want to edit the file
<filename>/etc/rc.d/init.d/halt</filename> to deactivate the volume
groups at shutdown. Insert the
<screen>
<command> vgchange -an </command>
</screen>
command near the end of this file just after the filesystems are
unmounted or mounted read-only, before the comment that says
<quote>Now halt or reboot</quote>.
</para>
</sect1>
<sect1 id="initscriptdebian"><title>Debian</title>
<para>
If you download the Debian lvm tool package, an initscript should
be installed for you.
</para>
<para>
If you are installing LVM from source, you will still need to build
your own initscript:
</para>
<para>
Create a startup script in <filename>/etc/init.d/lvm</filename>
containing the following:
<screen>
#!/bin/sh
case "$1" in
start)
/sbin/vgscan
/sbin/vgchange -ay
;;
stop)
/sbin/vgchange -an
;;
restart|force-reload)
;;
esac
exit 0
</screen>
</para>
<para>
Then execute the commands
<screen>
<command>
# chmod 0755 /etc/init.d/lvm
# update-rc.d lvm start 26 S . stop 82 1 .
</command>
</screen>
Note the dots in the last command.
</para>
</sect1>
<sect1 id="initscriptmandrake"><title>Mandrake</title>
<para>
No initscript modifications should be necessary for current
versions of Mandrake.
</para>
</sect1>
<sect1 id="initscriptredhat"><title>Redhat</title>
<para>
For Redhat 7.0 and up, you should not need to modify any
initscripts to enable LVM at boot time if LVM is built
into the kernel. If LVM is built as a module, it may be
necessary to modify <filename> /etc/rc.d/rc.sysinit
</filename> to load the LVM module by adding
<quote>modprobe lvm-mod</quote> before the section that
reads:
<screen># LVM initialization, take 2 (it could be on top of RAID)
if [ -e /proc/lvm -a -x /sbin/vgchange -a -f /etc/lvmtab ]; then
action $"Setting up Logical Volume Management:" /sbin/vgscan &amp;&amp;
/sbin/vgchange -a y
fi</screen>
<note>
<para>
This init script fragment is from Red Hat 7.3 - other versions
of Redhat may look slightly different.
</para>
</note>
</para>
<para>
For versions of Redhat older than 7.0, it is necessary to edit the
file <filename>/etc/rc.d/rc.sysinit</filename>. Look for the line
that says <quote>Mount all other filesystems</quote> and insert the
vgscan and vgchange commands just before it. You should be sure
that your root file system is mounted read/write before you run the
LVM commands.
</para>
<para>
You may also want to edit the file
<filename>/etc/rc.d/init.d/halt</filename> to deactivate the volume
groups at shutdown. Insert the
<screen>
vgchange -an
</screen>
command near the end of this file just after the filesystems are
mounted read-only, before the comment that says <quote>Now halt or
reboot</quote>.
</para>
</sect1>
<sect1 id="initscriptslackware"><title>Slackware</title>
<para>
Slackware 8.1 requires no updating of boot time scripts in order to
make LVM work.
</para>
<para>
For versions previous to Slackware 8.1, you should apply the
following patch to <filename>/etc/rc.d/rc.S</filename>
<screen>
cd /etc/rc.d
cp -a rc.S rc.S.old
patch -p0 &lt; rc.S.diff
</screen>
(the cp part to make a backup in case).
</para>
<screen>
----- snip snip file: rc.S.diff---------------
--- rc.S.or Tue Jul 17 18:11:20 2001
+++ rc.S Tue Jul 17 17:57:36 2001
@@ -4,6 +4,7 @@
#
# Mostly written by: Patrick J. Volkerding, &lt;volkerdi@slackware.com&gt;
#
+# Added LVM support &lt;tgs@iafrica.com&gt;
PATH=/sbin:/usr/sbin:/bin:/usr/bin
@@ -28,19 +29,21 @@
READWRITE=yes
fi
+
# Check the integrity of all filesystems
if [ ! READWRITE = yes ]; then
- /sbin/fsck -A -a
+ /sbin/fsck -a /
+ # Check only the root fs first, but no others
# If there was a failure, drop into single-user mode.
if [ ? -gt 1 ] ; then
echo
echo
- echo "*******************************************************"
- echo "*** An error occurred during the file system check. ***"
- echo "*** You will now be given a chance to log into the ***"
- echo "*** system in single-user mode to fix the problem. ***"
- echo "*** Running 'e2fsck -v -y &lt;partition&gt;' might help. ***"
- echo "*******************************************************"
+ echo "************************************************************"
+ echo "*** An error occurred during the root file system check. ***"
+ echo "*** You will now be given a chance to log into the ***"
+ echo "*** system in single-user mode to fix the problem. ***"
+ echo "*** Running 'e2fsck -v -y &lt;partition&gt;' might help. ***"
+ echo "************************************************************"
echo
echo "Once you exit the single-user shell, the system will reboot."
echo
@@ -82,6 +85,44 @@
echo -n "get into your machine and start looking for the problem. "
read junk;
fi
+ # okay / fs is clean, and mounted as rw
+ # This was an addition, limits vgscan to /proc thus
+ # speeding up the scan immensely.
+ /sbin/mount /proc
+
+ # Initialize Logical Volume Manager
+ /sbin/vgscan
+ /sbin/vgchange -ay
+
+ /sbin/fsck -A -a -R
+ #Check all the other filesystem, including the LVM's, excluding /
+
+ # If there was a failure, drop into single-user mode.
+ if [ ? -gt 1 ] ; then
+ echo
+ echo
+ echo "*******************************************************"
+ echo "*** An error occurred during the file system check. ***"
+ echo "*** You will now be given a chance to log into the ***"
+ echo "*** system in single-user mode to fix the problem. ***"
+ echo "*** Running 'e2fsck -v -y &lt;partition&gt;' might help. ***"
+ echo "*** The root filesystem is ok and mounted readwrite ***"
+ echo "*******************************************************"
+ echo
+ echo "Once you exit the single-user shell, the system will reboot."
+ echo
+
+ PS1="(Repair filesystem) #"; export PS1
+ sulogin
+
+ echo "Unmounting file systems."
+ umount -a -r
+ mount -n -o remount,ro /
+ echo "Rebooting system."
+ sleep 2
+ reboot
+ fi
+
else
echo "Testing filesystem status: read-write filesystem"
if cat /etc/fstab | grep ' / ' | grep umsdos 1> /dev/null 2> /dev/null ;
then
@@ -111,14 +152,16 @@
echo -n "Press ENTER to continue. "
read junk;
fi
+
fi
+
# remove /etc/mtab* so that mount will create it with a root entry
/bin/rm -f /etc/mtab* /etc/nologin /etc/shutdownpid
# mount file systems in fstab (and create an entry for /)
# but not NFS or SMB because TCP/IP is not yet configured
-/sbin/mount -a -v -t nonfs,nosmbfs
+/sbin/mount -a -v -t nonfs,nosmbfs,proc
# Clean up temporary files on the /var volume:
/bin/rm -f /var/run/utmp /var/run/*.pid /var/log/setup/tmp/*
--snip snip snip end of file---------------
</screen>
</sect1>
<sect1 id="initscriptsuse"><title>SuSE</title>
<para>
No changes should be necessary from 6.4 onward as LVM is included
</para>
</sect1>
</chapter>
<chapter id="lvm2_boot"> <title> LVM 2 Boot Time Scripts </title>
<para>
For initrds, you should have:
<screen>
dmsetup mknodes
vgscan --ignorelockingfailure
vgchange -ay --ignorelockingfailure
</screen>
in the linuxrc to get the root LV activated before the root
volume is accessed.
Most distros seem to have this setup in their mkinitrd scripts
now, and they also tend to have them in rc.sysinit or
equivilant, so all volumes get activated on bootup.
</para>
</chapter>
<chapter id="buildlvm"><title>Building LVM from the Source</title>
<sect1 id="makelvm1user"><title>Make LVM library and tools</title>
<para>
Change into the LVM directory and do a
<command>./configure</command> followed
by <command>make</command>. This will make all of the libraries and
programs.
</para>
<para>
If the need arises you can change some options with the configure
script. Do a <command>./configure --help</command> to determine
which options are supported. Most of the time this will not be
necessary.
</para>
<para>
There should be no errors from the build process. If there are,
see <link linkend="ReportBug">Reporting Errors and Bugs</link>
on how to report this.
</para>
<para>
You are welcome to fix them and send us the patches too.
Patches are generally sent to the <link
linkend="Maillists">linux-lvm</link> list.
</para>
</sect1>
<sect1 id="installlvm1user"><title>Install LVM library and tools</title>
<para>
After the LVM source compiles properly, simply run
<command>make install</command> to install the LVM library and
tools onto your system.
</para>
</sect1>
<sect1 id="removelvm1user"><title>Removing LVM library and tools</title>
<para>
To remove the library and tools you just installed, run
<command>make remove</command>. You must have the original source
tree you used to install LVM to use this feature.
</para>
</sect1>
</chapter>
<chapter id="trans1"><title>Transitioning from previous versions of LVM to LVM 1.0.8</title>
<para>
Transitioning from previous versions of LVM to LVM 1.0.8 should be
fairly painless. We have come up with a method to read in PV version
1 metadata (LVM 0.9.1 Beta7 and earlier) as well as PV version 2
metadata (LVM 0.9.1 Beta8 and LVM 1.0).
</para>
<para>
<emphasis>Warning:</emphasis> New PVs initialized with LVM 1.0.8 are
created with the PV version 1 on-disk structure. This means that LVM
0.9.1 Beta8 and LVM 1.0 cannot read or use PVs created with 1.0.8.
</para>
<sect1 id="upgradelvm1"><title>Upgrading to LVM 1.0.8 with a non-LVM root partition</title>
<para>
There are just a few simple steps to transition this setup, but it
is still recommended that you backup your data before you try it.
You have been warned.
<orderedlist>
<listitem>
<para>
<emphasis role="strong">Build LVM kernel and modules</emphasis>
</para>
<para>
Follow the steps outlined in <xref linkend="getlvm"/> -
<xref linkend="buildlvmmod"/> for instructions on how to get
and build the necessary kernel components of LVM.
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">Build the LVM user tools</emphasis>
</para>
<para>
Follow the steps in
<xref linkend="buildlvm"/> to build and install the user tools
for LVM.
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">Setup your init scripts</emphasis>
</para>
<para>
Make sure you have the proper init scripts setup as per
<xref linkend="boot_scripts"/>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">Boot into the new kernel</emphasis>
</para>
<para>
Make sure your boot-loader is setup to load the new
LVM-enhanced kernel and, if you are using LVM modules, put an
<command>insmod lvm-mod</command> into your startup script OR
extend <filename>/etc/modules.conf</filename> (formerly
<filename>/etc/conf.modules</filename>) by adding
<screen>
alias block-major-58 lvm-mod
alias char-major-109 lvm-mod
</screen>
to enable modprobe to load the LVM module (don't forget to
enable kmod).
</para>
<para>
Reboot and enjoy.
</para>
</listitem>
</orderedlist>
</para>
</sect1>
<sect1 id="upgradetolvmroot"><title>Upgrading to LVM 1.0.8 with an LVM root partition and initrd</title>
<para>
This is relatively straightforward if you follow the steps
carefully. It is recommended you have a good backup and a suitable
rescue disk handy just in case.
</para>
<para>
The <quote>normal</quote> way of running an LVM root file system is
to have a single non-LVM partition called
<filename class="directory">/boot</filename>
which contains the kernel and initial RAM disk needed to start the
system. The system I upgraded was as follows:
<screen>
<command> # df</command>
<computeroutput>
Filesystem 1k-blocks Used Available Use% Mounted on
/dev/rootvg/root 253871 93384 147380 39% /
/dev/hda1 17534 12944 3685 78% /boot
/dev/rootvg/home 4128448 4568 3914168 0% /home
/dev/rootvg/usr 1032088 332716 646944 34% /usr
/dev/rootvg/var 253871 31760 209004 13% /var
</computeroutput>
</screen>
<filename class="directory">/boot</filename>
contains the old kernel and an initial RAM disk as well as the LILO
boot files and the following entry in
<filename>/etc/lilo.conf</filename>
<screen>
<command> # ls /boot</command>
<computeroutput>
System.map lost+found vmlinux-2.2.16lvm
map module-info boot.0300
boot.b os2_d.b chain.b
initrd.gz
</computeroutput>
<command> # tail /etc/lilo.conf</command>
<computeroutput>
image=/boot/vmlinux-2.2.16lvm
label=lvm08
read-only
root=/dev/rootvg/root
initrd=/boot/initrd.gz
append="ramdisk_size=8192"
</computeroutput>
</screen>
<orderedlist>
<listitem>
<para>
<emphasis role="strong">
Build LVM kernel and modules
</emphasis>
</para>
<para>
Follow the steps outlined in
<xref linkend="getlvm"/> - <xref linkend="buildlvmmod"/>
for instructions on how to get and build the necessary
kernel components of LVM.
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
Build the LVM user tools
</emphasis>
</para>
<para>
Follow the steps in
<xref linkend="buildlvmmod"/> to build and install the user
tools for LVM.
</para>
<para>
Install the new tools. Once you have done this you cannot
do any LVM manipulation as they are not compatible with
the kernel you are currently running.
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
Rename the existing initrd.gz
</emphasis>
</para>
<para>
This is so it doesn't get overwritten by the new one
<screen>
<command># mv /boot/initrd.gz /boot/initrd08.gz</command>
</screen>
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
Edit <filename>/etc/lilo.conf</filename>
</emphasis>
</para>
<para>
Make the existing boot entry point to the renamed file.
You will need to reboot using this if something goes wrong
in the next reboot. The changed entry will look something
like this:
<screen>
image=/boot/vmlinux-2.2.16lvm
label=lvm08
read-only
root=/dev/rootvg/root
initrd=/boot/initrd08.gz
append="ramdisk_size=8192"
</screen>
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
Run lvmcreate_initrd to create a new initial RAM disk
</emphasis>
<screen>
<command># lvmcreate_initrd 2.4.9</command>
</screen>
Don't forget the put the new kernel version in there so
that it picks up the correct modules.
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
Add a new entry into /etc/lilo.conf
</emphasis>
</para>
<para>
This new entry is to boot the new kernel with its new
initrd.
<screen>
image=/boot/vmlinux-2.4.9lvm
label=lvm10
read-only
root=/dev/rootvg/root
initrd=/boot/initrd.gz
append="ramdisk_size=8192"
</screen>
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
Re-run lilo
</emphasis>
</para>
<para>
This will install the new boot block
<screen>
<command># /sbin/lilo</command>
</screen>
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
Reboot
</emphasis>
</para>
<para>
When you get the LILO prompt select the new entry name (in
this example lvm10) and your system should boot into Linux
using the new LVM version.
</para>
<para>
If the new kernel does not boot, then simply boot the old
one and try to fix the problem. It may be that the new
kernel does not have all the correct device drivers built
into it, or that they are not available in the initrd.
Remember that all device drivers (apart from LVM) needed
to access the root device should be compiled into the
kernel and not as modules.
</para>
<para>
If you need to do any LVM manipulation when booted back
into the old version, then simply recompile the old tools
and install them with
<screen>
<command># make install</command>
</screen>
If you do this, don't forget to install the new tools when
you reboot into the new LVM version.
</para>
</listitem>
</orderedlist>
When you are happy with the new system remember to change the
``default='' entry in your lilo.conf file so that it is the default
kernel.
</para>
</sect1>
</chapter>
<chapter id="commontask"><title>Common Tasks</title>
<para>
The following sections outline some common administrative tasks for an
LVM system. <emphasis>This is no substitute for reading the man
pages.</emphasis>
</para>
<sect1 id="initdisks"><title>Initializing disks or disk partitions</title>
<para>
Before you can use a disk or disk partition as a physical volume
you will have to initialize it:
</para>
<para>
For entire disks:
<itemizedlist>
<listitem>
<para>
Run pvcreate on the disk:
<screen>
<command># pvcreate /dev/hdb</command>
</screen>
This creates a volume group descriptor at the start of
disk.
<warning><title>Not Recommended</title>
<para>
Using the whole disk as a PV (as opposed to a partition spanning the whole disk) is not recommended because of the management issues it can create. Any other OS that looks at the disk will not recognize the LVM metadata and display the disk as being free, so it is likely it will be overwritten. LVM itself will work fine with whole disk PVs.
</para>
</warning>
</para>
</listitem>
<listitem>
<para>
If you get an error that LVM can't initialize a
disk with a partition table on it, first make sure
that the disk you are operating on is the correct
one. If you are very sure that it is, run the
following:
<warning> <title>DANGEROUS</title>
<para>
The following commands will destroy the
partition table on the disk being operated on.
Be very sure it is the correct disk.
</para>
</warning>
<screen>
# dd if=/dev/zero of=/dev/diskname bs=1k count=1
# blockdev --rereadpt /dev/diskname
</screen>
</para>
</listitem>
</itemizedlist>
For partitions:
<itemizedlist>
<listitem>
<para>
When using LVM 1 on PCs with DOS partitions, set
the partition type to 0x8e using fdisk or some
other similar program. This step is unnecessary
on PPC systems or when using LVM 2.
</para>
</listitem>
<listitem>
<para>
Run pvcreate on the partition:
<screen>
<command># pvcreate /dev/hdb1</command>
</screen>
This creates a volume group descriptor at the start of
the /dev/hdb1 partition.
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id="createvgs"><title>Creating a volume group</title>
<para>
Use the 'vgcreate' program:
<screen>
<command># vgcreate my_volume_group /dev/hda1 /dev/hdb1 </command>
</screen>
<emphasis>NOTE:</emphasis> If you are using LVM 1 with
devfs it is essential to use the full devfs name of the
device rather than the symlinked name in <filename
class="directory">/dev</filename>. So the above would be:
<screen>
<command># vgcreate my_volume_group /dev/ide/host0/bus0/target0/lun0/part1 \
/dev/ide/host0/bus0/target1/lun0/part1</command>
</screen>
LVM 2 does not have this restriction.
</para>
<para>
You can also specify the extent size with this command if the
default of 32MB is not suitable for you with the '-s' switch. In
addition you can put some limits on the number of physical or
logical volumes the volume can have.
</para>
</sect1>
<sect1 id="activatevgs"><title>Activating a volume group</title>
<para>
After rebooting the system or running
<command>vgchange -an</command>, you will not be able to access
your VGs and LVs. To reactivate the volume group, run:
<screen>
<command># vgchange -a y my_volume_group</command>
</screen>
</para>
</sect1>
<sect1 id="removevgs"><title>Removing a volume group</title>
<para>
Make sure that no logical volumes are present in the volume group,
see later section for how to do this.
</para>
<para>
Deactivate the volume group:
<screen>
<command># vgchange -a n my_volume_group</command>
</screen>
</para>
<para>
Now you actually remove the volume group:
<screen>
<command># vgremove my_volume_group</command>
</screen>
</para>
</sect1>
<sect1 id="addpvstovg"><title>Adding physical volumes to a volume group</title>
<para>
Use 'vgextend' to add an initialized physical volume to an existing
volume group.
<screen>
<command># vgextend my_volume_group /dev/hdc1</command>
^^^^^^^^^ new physical volume
</screen>
</para>
</sect1>
<sect1 id="removepvsfromvg"><title>Removing physical volumes from a volume group</title>
<para>
Make sure that the physical volume isn't used by any logical
volumes by using then 'pvdisplay' command:
<screen>
<command># pvdisplay /dev/hda1</command>
<computeroutput>
--- Physical volume ---
PV Name /dev/hda1
VG Name myvg
PV Size 1.95 GB / NOT usable 4 MB [LVM: 122 KB]
PV# 1
PV Status available
Allocatable yes (but full)
Cur LV 1
PE Size (KByte) 4096
Total PE 499
Free PE 0
Allocated PE 499
PV UUID Sd44tK-9IRw-SrMC-MOkn-76iP-iftz-OVSen7
</computeroutput>
</screen>
</para>
<para>
If the physical volume is still used you will have to migrate the
data to another physical volume using pvmove.
</para>
<para>
Then use 'vgreduce' to remove the physical volume:
<screen>
<command># vgreduce my_volume_group /dev/hda1</command>
</screen>
</para>
</sect1>
<sect1 id="createlv"><title>Creating a logical volume</title>
<para>
To create a 1500MB linear LV named 'testlv' and its block
device special '/dev/testvg/testlv':
<screen>
<command># lvcreate -L1500 -ntestlv testvg</command>
</screen>
</para>
<para>
To create a 100 LE large logical volume with 2 stripes and
stripe size 4 KB.
<screen>
<command># lvcreate -i2 -I4 -l100 -nanothertestlv testvg</command>
</screen>
</para>
<para>
If you want to create an LV that uses the entire VG, use vgdisplay
to find the <quote>Total PE</quote> size, then use that when
running lvcreate.
<screen>
<command># vgdisplay testvg | grep "Total PE"</command>
<computeroutput>Total PE 10230</computeroutput>
<command># lvcreate -l 10230 testvg -n mylv</command>
</screen>
This will create an LV called
<emphasis role="strong">mylv</emphasis> filling the
<emphasis role="strong">testvg</emphasis> VG.
</para>
<para>
If you want the logical volume to be allocated from a specific
physical volume in the volume group, specify the PV or PVs at
the end of the lvcreate command line.
<screen>
<command># lvcreate -L 1500 -ntestlv testvg /dev/sdg</command>
</screen>
</para>
</sect1>
<sect1 id="removelv"><title>Removing a logical volume</title>
<para>
A logical volume must be closed before it can be removed:
<screen>
<command># umount /dev/myvg/homevol
# lvremove /dev/myvg/homevol</command>
<prompt>lvremove -- do you really want to remove "/dev/myvg/homevol"? [y/n]: </prompt><replaceable>y</replaceable>
<computeroutput>lvremove -- doing automatic backup of volume group "myvg"
lvremove -- logical volume "/dev/myvg/homevol" successfully removed</computeroutput>
</screen>
</para>
</sect1>
<sect1 id="extendlv"><title>Extending a logical volume</title>
<para>
To extend a logical volume you simply tell the lvextend command how
much you want to increase the size. You can specify how much to
grow the volume, or how large you want it to grow to:
<screen>
<command># lvextend -L12G /dev/myvg/homevol</command>
<computeroutput>lvextend -- extending logical volume "/dev/myvg/homevol" to 12 GB
lvextend -- doing automatic backup of volume group "myvg"
lvextend -- logical volume "/dev/myvg/homevol" successfully extended</computeroutput>
</screen>
will extend <filename>/dev/myvg/homevol</filename> to 12 Gigabytes.
</para>
<para>
<screen>
<command># lvextend -L+1G /dev/myvg/homevol</command>
<computeroutput>lvextend -- extending logical volume "/dev/myvg/homevol" to 13 GB
lvextend -- doing automatic backup of volume group "myvg"
lvextend -- logical volume "/dev/myvg/homevol" successfully extended</computeroutput>
</screen>
will add another gigabyte to <filename>/dev/myvg/homevol</filename>.
</para>
<para>
After you have extended the logical volume it is necessary to
increase the file system size to match. how you do this depends on
the file system you are using.
</para>
<para>
By default, most file system resizing tools will increase the size
of the file system to be the size of the underlying logical volume
so you don't need to worry about specifying the same size for each
of the two commands.
</para>
<orderedlist>
<listitem>
<para>
<emphasis role="strong">
ext2/ext3
</emphasis>
</para>
<para>
Unless you have patched your kernel with the ext2online
patch it is necessary to unmount the file system before
resizing it. (It seems that the online resizing patch is
rather dangerous, so use at your own risk)
<screen>
<command># umount /dev/myvg/homevol/dev/myvg/homevol
# resize2fs /dev/myvg/homevol
# mount /dev/myvg/homevol /home</command>
</screen>
</para>
<para>
If you don't have e2fsprogs 1.19 or later, you can download
the ext2resize command from
<ulink url="http://ext2resize.sourceforge.net">ext2resize.sourceforge.net</ulink>
and use that:
<screen>
<command># umount /dev/myvg/homevol/dev/myvg/homevol
# ext2resize /dev/myvg/homevol
# mount /dev/myvg/homevol /home</command>
</screen>
</para>
<para>
For ext2 there is an easier way. LVM 1 ships with a utility
called e2fsadm which does the lvextend and resize2fs for you
(it can also do file system shrinking, see the next section).
<warning><title>LVM 2 Caveat</title>
<para>
There is currently no e2fsadm equivalent for
LVM 2 and the e2fsadm that ships with LVM 1
does not work with LVM 2.
</para>
</warning>
so the single command
<screen>
<command># e2fsadm -L+1G /dev/myvg/homevol</command>
</screen>
is equivalent to the two commands:
<screen>
<command># lvextend -L+1G /dev/myvg/homevol
# resize2fs /dev/myvg/homevol</command>
</screen>
<note><title>Note</title>
<para>
You will still need to unmount the file system before
running e2fsadm.
</para>
</note>
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
reiserfs
</emphasis>
</para>
<para>
Reiserfs file systems can be resized when mounted or
unmounted as you prefer:
<itemizedlist>
<listitem>
<para>
Online:
<screen>
<command># resize_reiserfs -f /dev/myvg/homevol</command>
</screen>
</para>
</listitem>
<listitem>
<para>
Offline:
<screen>
<command># umount /dev/myvg/homevol
# resize_reiserfs /dev/myvg/homevol
# mount -treiserfs /dev/myvg/homevol /home</command>
</screen>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
xfs
</emphasis>
</para>
<para>
XFS file systems must be mounted to be resized and the
mount-point is specified rather than the device name.
<screen>
<command># xfs_growfs /home</command>
</screen>
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
jfs
</emphasis>
</para>
<para>
Just like XFS the JFS file system must be mounted to be
resized and the mount-point is specified rather than the
device name. You need at least Version 1.0.21 of the
jfs-utils to do this.
<screen>
<command># mount -o remount,resize /home</command>
</screen>
</para>
<warning><title>Known Kernel Bug</title>
<para>
Some kernel versions have problems with this syntax
(2.6.0 is known to have this problem). In this case you
have to explicitly specify the new size of the
filesystem in blocks. This is extremely error prone as
you <emphasis>must</emphasis> know the blocksize of your
filesystem and calculate the new size based on those
units.
</para>
<para>
Example: If you were to resize a JFS file system to 4
gigabytes that has 4k blocks, you would write:
<screen>
<command># mount -o remount,resize=1048576 /home</command>
</screen>
</para>
</warning>
</listitem>
</orderedlist>
</sect1>
<sect1 id="reducelv"><title>Reducing a logical volume</title>
<para>
Logical volumes can be reduced in size as well as increased.
However, it is <emphasis>very</emphasis> important to remember to
reduce the size of the file system or whatever is residing in the
volume before shrinking the volume itself, otherwise you risk
losing data.
</para>
<orderedlist>
<listitem>
<para>
<emphasis role="strong">
ext2
</emphasis>
</para>
<para>
If you are using LVM 1 with ext2 as the file system
then you can use the e2fsadm command mentioned
earlier to take care of both the file system and
volume resizing as follows:
<screen>
<command># umount /home
# e2fsadm -L-1G /dev/myvg/homevol
# mount /home</command>
</screen>
<warning><title>LVM 2 Caveat</title>
<para>
There is currently no e2fsadm equivalent for
LVM 2 and the e2fsadm that ships with LVM 1
does not work with LVM 2.
</para>
</warning>
</para>
<para>
If you prefer to do this manually you must know the new size
of the volume in blocks and use the following commands:
<screen>
<command># umount /home
# resize2fs /dev/myvg/homevol 524288
# lvreduce -L-1G /dev/myvg/homevol
# mount /home</command>
</screen>
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
reiserfs
</emphasis>
</para>
<para>
Reiserfs seems to prefer to be unmounted when shrinking
<screen>
<command># umount /home
# resize_reiserfs -s-1G /dev/myvg/homevol
# lvreduce -L-1G /dev/myvg/homevol
# mount -treiserfs /dev/myvg/homevol /home</command>
</screen>
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
xfs
</emphasis>
</para>
<para>
There is no way to shrink XFS file systems.
</para>
</listitem>
<listitem>
<para>
<emphasis role="strong">
jfs
</emphasis>
</para>
<para>
There is no way to shrink JFS file systems.
</para>
</listitem>
</orderedlist>
</sect1>
<sect1 id="migrateoffpv"><title>Migrating data off of a physical volume</title>
<para>
To take a disk out of service it must first have all of its active
physical extents moved to one or more of the remaining disks in the
volume group. There must be enough free physical extents in the
remaining PVs to hold the extents to be copied from the old disk.
For further detail see <xref linkend="RemoveADisk"/>.
</para>
</sect1>
</chapter>
<chapter id="diskpart"><title>Disk partitioning</title>
<sect1 id="multpartitions"><title>Multiple partitions on the same disk</title>
<para>
LVM allows you to create PVs (physical volumes) out of almost any
block device so, for example, the following are all valid commands
and will work quite happily in an LVM environment:
<screen>
<command># pvcreate /dev/sda1
# pvcreate /dev/sdf
# pvcreate /dev/hda8
# pvcreate /dev/hda6
# pvcreate /dev/md1</command>
</screen>
</para>
<para>
In a <quote>normal</quote> production system it is recommended that
only one PV exists on a single real disk, for the following
reasons:
<itemizedlist>
<listitem>
<para>
Administrative convenience
</para>
<para>
It's easier to keep track of the hardware in a system if
each real disk only appears once. This becomes
particularly true if a disk fails.
</para>
</listitem>
<listitem>
<para>
To avoid striping performance problems
</para>
<para>
LVM can't tell that two PVs are on the same physical disk,
so if you create a striped LV then the stripes could be on
different partitions on the same disk resulting in a
<emphasis role="strong">decrease</emphasis> in performance
rather than an increase.
</para>
</listitem>
</itemizedlist>
However it may be desirable to do this for some reasons:
<itemizedlist>
<listitem>
<para>
Migration of existing system to LVM
</para>
<para>
On a system with few disks it may be necessary to move
data around partitions to do the conversion (see
<xref linkend="UpgradeRootToLVM"/>)
</para>
</listitem>
<listitem>
<para>
Splitting one big disk between Volume Groups
</para>
<para>
If you have a very large disk and want to have more than
one volume group for administrative purposes then it is
necessary to partition the drive into more than one area.
</para>
</listitem>
</itemizedlist>
</para>
<para>
If you do have a disk with more than one partition and both of
those partitions are in the same volume group, take care to specify
which partitions are to be included in a logical volume when
creating striped volumes.
</para>
<para>
The recommended method of partitioning a disk is to create a single
partition that covers the whole disk. This avoids any nasty
accidents with whole disk drive device nodes and prevents the
kernel warning about unknown partition types at boot-up.
</para>
</sect1>
<sect1 id="sundisklabels"><title>Sun disk labels</title>
<para>
You need to be especially careful on SPARC systems where the disks
have Sun disk labels on them.
</para>
<para>
The normal layout for a Sun disk label is for the first partition
to start at block zero of the disk, thus the first partition also
covers the area containing the disk label itself. This works fine
for ext2 filesystems (and is essential for booting using SILO) but
such partitions should not be used for LVM. This is because LVM
starts writing at the very start of the device and will overwrite
the disk label.
</para>
<para>
If you want to use a disk with a Sun disk label with LVM, make sure
that the partition you are going to use starts at cylinder 1 or
higher.
</para>
</sect1>
</chapter>
<chapter id="recipes"><title>Recipes</title>
<para>
This section details several different <quote>recipes</quote> for
setting up lvm. The hope is that the reader will adapt these recipes
to their own system and needs.
</para>
<sect1 id="recipethreescsi"><title>Setting up LVM on three SCSI disks</title>
<para>
For this recipe, the setup has three SCSI disks that will be put
into a logical volume using LVM. The disks are at /dev/sda,
/dev/sdb, and /dev/sdc.
</para>
<sect2><title>Preparing the disks</title>
<para>
Before you can use a disk in a volume group you will have to
prepare it:
</para>
<warning><title>Warning!</title>
<para>
<emphasis role="strong">
The following will destroy any data on /dev/sda, /dev/sdb,
and /dev/sdc
</emphasis>
</para>
</warning>
<para>
Run pvcreate on the disks
<screen>
<command># pvcreate /dev/sda
# pvcreate /dev/sdb
# pvcreate /dev/sdc</command>
</screen>
This creates a volume group descriptor area (VGDA) at the start
of the disks.
</para>
</sect2>
<sect2><title>Setup a Volume Group</title>
<orderedlist>
<listitem>
<para>
Create a volume group
<screen>
<command># vgcreate my_volume_group /dev/sda /dev/sdb /dev/sdc/</command>
</screen>
</para>
</listitem>
<listitem>
<para>
Run vgdisplay to verify volume group
<screen>
<command># vgdisplay</command>
<computeroutput># vgdisplay
--- Volume Group ---
VG Name my_volume_group
VG Access read/write
VG Status available/resizable
VG # 1
MAX LV 256
Cur LV 0
Open LV 0
MAX LV Size 255.99 GB
Max PV 256
Cur PV 3
Act PV 3
VG Size 1.45 GB
PE Size 4 MB
Total PE 372
Alloc PE / Size 0 / 0
Free PE / Size 372/ 1.45 GB
VG UUID nP2PY5-5TOS-hLx0-FDu0-2a6N-f37x-0BME0Y</computeroutput>
</screen>
The most important things to verify are that the first
three items are correct and that the VG Size item is the
proper size for the amount of space in all four of your
disks.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2><title>Creating the Logical Volume</title>
<para>
If the volume group looks correct, it is time to create a
logical volume on top of the volume group.
</para>
<para>
You can make the logical volume any size you like. (It is
similar to a partition on a non LVM setup.) For this example we
will create just a single logical volume of size 1GB on the
volume group. We will not use striping because it is not
currently possible to add a disk to a stripe set after the
logical volume is created.
<screen>
<command># lvcreate -L1G -nmy_logical_volume my_volume_group</command>
<computeroutput>lvcreate -- doing automatic backup of "my_volume_group"
lvcreate -- logical volume "/dev/my_volume_group/my_logical_volume" successfully created</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Create the File System</title>
<para>
Create an ext2 file system on the logical volume
<screen>
<command># mke2fs /dev/my_volume_group/my_logical_volume</command>
<computeroutput>mke2fs 1.19, 13-Jul-2000 for EXT2 FS 0.5b, 95/08/09
Filesystem label=
OS type: Linux
Block size=4096 (log=2)
Fragment size=4096 (log=2)
131072 inodes, 262144 blocks
13107 blocks (5.00%) reserved for the super user
First data block=0
9 block groups
32768 blocks per group, 32768 fragments per group
16384 inodes per group
Superblock backups stored on blocks:
32768, 98304, 163840, 229376
Writing inode tables: done
Writing superblocks and filesystem accounting information: done</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Test the File System</title>
<para>
Mount the logical volume and check to make sure everything looks
correct
<screen>
<command># mount /dev/my_volume_group/my_logical_volume /mnt
# df</command>
<computeroutput>Filesystem 1k-blocks Used Available Use% Mounted on
/dev/hda1 1311552 628824 616104 51% /
/dev/my_volume_group/my_logical_volume
1040132 20 987276 0% /mnt</computeroutput>
</screen>
</para>
<para>
If everything worked properly, you should now have a logical
volume with and ext2 file system mounted at
<filename class="directory">/mnt</filename>.
</para>
</sect2>
</sect1>
<sect1 id="recipethreescsistripe"><title>Setting up LVM on three SCSI disks with striping</title>
<para>
For this recipe, the setup has three SCSI disks that will be put
into a logical volume using LVM. The disks are at /dev/sda,
/dev/sdb, and /dev/sdc.
</para>
<note><title>Note</title>
<para>
<emphasis role="strong">
It is not currently possible to add a disk to a
striped logical volume in LVM 1. Use LVM 2 with the
lvm 2 format metadata if you wish to be able to do
so able to do so.
</emphasis>
</para>
</note>
<sect2><title>Preparing the disk partitions</title>
<para>
Before you can use a disk in a volume group you will have to
prepare it:
</para>
<warning><title>Warning!</title>
<para>
<emphasis role="strong">
The following will destroy any data on /dev/sda, /dev/sdb,
and /dev/sdc
</emphasis>
</para>
</warning>
<para>
Run pvcreate on the disks:
<screen>
<command># pvcreate /dev/sda
# pvcreate /dev/sdb
# pvcreate /dev/sdc</command>
</screen>
This creates a volume group descriptor area (VGDA) at the start
of the disks.
</para>
</sect2>
<sect2><title>Setup a Volume Group</title>
<orderedlist>
<listitem>
<para>
Create a volume group
<screen>
<command># vgcreate my_volume_group /dev/sda /dev/sdb /dev/sdc</command>
</screen>
</para>
</listitem>
<listitem>
<para>
Run vgdisplay to verify volume group
<screen>
<command># vgdisplay</command>
<computeroutput>--- Volume Group ---
VG Name my_volume_group
VG Access read/write
VG Status available/resizable
VG # 1
MAX LV 256
Cur LV 0
Open LV 0
MAX LV Size 255.99 GB
Max PV 256
Cur PV 3
Act PV 3
VG Size 1.45 GB
PE Size 4 MB
Total PE 372
Alloc PE / Size 0 / 0
Free PE / Size 372/ 1.45 GB
VG UUID nP2PY5-5TOS-hLx0-FDu0-2a6N-f37x-0BME0Y</computeroutput>
</screen>
The most important things to verify are that the first
three items are correct and that the VG Size item is the
proper size for the amount of space in all four of your
disks.
</para>
</listitem>
</orderedlist>
</sect2>
<sect2><title>Creating the Logical Volume</title>
<para>
If the volume group looks correct, it is time to create a
logical volume on top of the volume group.
</para>
<para>
You can make the logical volume any size you like (up to the
size of the VG you are creating it on; it is similar to a
partition on a non LVM setup). For this example we will create
just a single logical volume of size 1GB on the volume group.
The logical volume will be a striped set using for the 4k stripe
size. This should increase the performance of the logical
volume.
<screen>
<command># lvcreate -i3 -I4 -L1G -nmy_logical_volume my_volume_group</command>
<computeroutput>lvcreate -- rounding 1048576 KB to stripe boundary size 1056768 KB / 258 PE
lvcreate -- doing automatic backup of "my_volume_group"
lvcreate -- logical volume "/dev/my_volume_group/my_logical_volume" successfully created</computeroutput>
</screen>
</para>
<note><title>Note</title>
<para>
If you create the logical volume with a '-i2' you will only
use two of the disks in your volume group. This is useful if
you want to create two logical volumes out of the same
physical volume, but we will not touch that in this recipe.
</para>
</note>
</sect2>
<sect2><title>Create the File System</title>
<para>
Create an ext2 file system on the logical volume
<screen>
<command># mke2fs /dev/my_volume_group/my_logical_volume</command>
<computeroutput>mke2fs 1.19, 13-Jul-2000 for EXT2 FS 0.5b, 95/08/09
Filesystem label=
OS type: Linux
Block size=4096 (log=2)
Fragment size=4096 (log=2)
132192 inodes, 264192 blocks
13209 blocks (5.00%) reserved for the super user
First data block=0
9 block groups
32768 blocks per group, 32768 fragments per group
14688 inodes per group
Superblock backups stored on blocks:
32768, 98304, 163840, 229376
Writing inode tables: done
Writing superblocks and filesystem accounting information: done</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Test the File System</title>
<para>
Mount the file system on the logical volume
<screen>
<command># mount /dev/my_volume_group/my_logical_volume /mnt</command>
</screen>
and check to make sure everything looks correct
<screen>
<command># df</command>
<computeroutput>Filesystem 1k-blocks Used Available Use% Mounted on
/dev/hda1 1311552 628824 616104 51% /
/dev/my_volume_group/my_logical_volume
1040132 20 987276 0% /mnt</computeroutput>
</screen>
If everything worked properly, you should now have a logical
volume mounted at <filename class="directory">/mnt</filename>.
</para>
</sect2>
</sect1>
<sect1 id="recipeadddisk"><title>Add a new disk to a multi-disk SCSI system</title>
<sect2><title>Current situation</title>
<para>
A data centre machine has 6 disks attached as follows:
<screen>
<command># pvscan</command>
<computeroutput>pvscan -- ACTIVE PV "/dev/sda" of VG "dev" [1.95 GB / 0 free]
pvscan -- ACTIVE PV "/dev/sdb" of VG "sales" [1.95 GB / 0 free]
pvscan -- ACTIVE PV "/dev/sdc" of VG "ops" [1.95 GB / 44 MB free]
pvscan -- ACTIVE PV "/dev/sdd" of VG "dev" [1.95 GB / 0 free]
pvscan -- ACTIVE PV "/dev/sde1" of VG "ops" [996 MB / 52 MB free]
pvscan -- ACTIVE PV "/dev/sde2" of VG "sales" [996 MB / 944 MB free]
pvscan -- ACTIVE PV "/dev/sdf1" of VG "ops" [996 MB / 0 free]
pvscan -- ACTIVE PV "/dev/sdf2" of VG "dev" [996 MB / 72 MB free]
pvscan -- total: 8 [11.72 GB] / in use: 8 [11.72 GB] / in no VG: 0 [0]</computeroutput>
<command># df</command>
<computeroutput>Filesystem 1k-blocks Used Available Use% Mounted on
/dev/dev/cvs 1342492 516468 757828 41% /mnt/dev/cvs
/dev/dev/users 2064208 2060036 4172 100% /mnt/dev/users
/dev/dev/build 1548144 1023041 525103 66% /mnt/dev/build
/dev/ops/databases 2890692 2302417 588275 79% /mnt/ops/databases
/dev/sales/users 2064208 871214 1192994 42% /mnt/sales/users
/dev/ops/batch 1032088 897122 134966 86% /mnt/ops/batch</computeroutput>
</screen>
As you can see the "dev" and "ops" groups are getting full so
a new disk is purchased and added to the system. It becomes
<filename class="directory">/dev/sdg</filename>.
</para>
</sect2>
<sect2><title>Prepare the disk partitions</title>
<para>
The new disk is to be shared equally between ops and dev so
it is partitioned into two physical volumes /dev/sdg1 and
/dev/sdg2 :
<screen>
<command># fdisk /dev/sdg</command>
<computeroutput>
Device contains neither a valid DOS partition table, nor Sun or SGI
disklabel Building a new DOS disklabel. Changes will remain in memory
only, until you decide to write them. After that, of course, the
previous content won't be recoverable.</computeroutput>
<prompt>Command (m for help): </prompt>n
<computeroutput>Command action
e extended
p primary partition (1-4)</computeroutput>
p
<prompt>Partition number (1-4): </prompt>1
<prompt>First cylinder (1-1000, default 1):</prompt>
<computeroutput>Using default value 1</computeroutput>
<prompt>Last cylinder or +size or +sizeM or +sizeK (1-1000, default 1000): </prompt>500
<prompt>Command (m for help): </prompt>n
<computeroutput>Command action
e extended
p primary partition (1-4)</computeroutput>
p
<prompt>Partition number (1-4): </prompt>2
<prompt>First cylinder (501-1000, default 501):</prompt>
<computeroutput>Using default value 501</computeroutput>
<prompt>Last cylinder or +size or +sizeM or +sizeK (501-1000, default 1000):</prompt>
<computeroutput>Using default value 1000</computeroutput>
<prompt>Command (m for help): </prompt>t
<prompt>Partition number (1-4): </prompt>1
<prompt>Hex code (type L to list codes): </prompt>8e
<computeroutput>Changed system type of partition 1 to 8e (Unknown)</computeroutput>
<prompt>Command (m for help): </prompt>t
<prompt>Partition number (1-4): </prompt>2
<prompt>Hex code (type L to list codes): </prompt>8e
<computeroutput>Changed system type of partition 2 to 8e (Unknown)</computeroutput>
<prompt>Command (m for help): </prompt>w
<computeroutput>The partition table has been altered!
Calling ioctl() to re-read partition table.
WARNING: If you have created or modified any DOS 6.x partitions,
please see the fdisk manual page for additional information.
</computeroutput>
</screen>
</para>
<para>
Next physical volumes are created on this partition:
<screen>
<command># pvcreate /dev/sdg1</command>
<computeroutput>pvcreate -- physical volume "/dev/sdg1" successfully created</computeroutput>
<command># pvcreate /dev/sdg2</command>
<computeroutput>pvcreate -- physical volume "/dev/sdg2" successfully created</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Add the new disks to the volume groups</title>
<para>
The volumes are then added to the dev and ops volume groups:
<screen>
<command># vgextend ops /dev/sdg1</command>
<computeroutput>vgextend -- INFO: maximum logical volume size is 255.99 Gigabyte
vgextend -- doing automatic backup of volume group "ops"
vgextend -- volume group "ops" successfully extended</computeroutput>
<command># vgextend dev /dev/sdg2</command>
<computeroutput>vgextend -- INFO: maximum logical volume size is 255.99 Gigabyte
vgextend -- doing automatic backup of volume group "dev"
vgextend -- volume group "dev" successfully extended</computeroutput>
<command># pvscan</command>
<computeroutput>pvscan -- reading all physical volumes (this may take a while...)
pvscan -- ACTIVE PV "/dev/sda" of VG "dev" [1.95 GB / 0 free]
pvscan -- ACTIVE PV "/dev/sdb" of VG "sales" [1.95 GB / 0 free]
pvscan -- ACTIVE PV "/dev/sdc" of VG "ops" [1.95 GB / 44 MB free]
pvscan -- ACTIVE PV "/dev/sdd" of VG "dev" [1.95 GB / 0 free]
pvscan -- ACTIVE PV "/dev/sde1" of VG "ops" [996 MB / 52 MB free]
pvscan -- ACTIVE PV "/dev/sde2" of VG "sales" [996 MB / 944 MB free]
pvscan -- ACTIVE PV "/dev/sdf1" of VG "ops" [996 MB / 0 free]
pvscan -- ACTIVE PV "/dev/sdf2" of VG "dev" [996 MB / 72 MB free]
pvscan -- ACTIVE PV "/dev/sdg1" of VG "ops" [996 MB / 996 MB free]
pvscan -- ACTIVE PV "/dev/sdg2" of VG "dev" [996 MB / 996 MB free]
pvscan -- total: 10 [13.67 GB] / in use: 10 [13.67 GB] / in no VG: 0 [0]</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Extend the file systems</title>
<para>
The next thing to do is to extend the file systems so that the
users can make use of the extra space.
</para>
<para>
There are tools to allow online-resizing of ext2 file systems
but here we take the safe route and unmount the two file systems
before resizing them:
<screen>
<command># umount /mnt/ops/batch
# umount /mnt/dev/users</command>
</screen>
</para>
<para>
We then use the e2fsadm command to resize the logical volume and
the ext2 file system on one operation. We are using ext2resize
instead of resize2fs (which is the default command for e2fsadm)
so we define the environment variable E2FSADM_RESIZE_CMD to tell
e2fsadm to use that command.
<screen>
<command># export E2FSADM_RESIZE_CMD=ext2resize
# e2fsadm /dev/ops/batch -L+500M</command>
<computeroutput>e2fsck 1.18, 11-Nov-1999 for EXT2 FS 0.5b, 95/08/09
Pass 1: Checking inodes, blocks, and sizes
Pass 2: Checking directory structure
Pass 3: Checking directory connectivity
Pass 4: Checking reference counts
Pass 5: Checking group summary information
/dev/ops/batch: 11/131072 files (0.0&lt;!-- non-contiguous), 4127/262144 blocks
lvextend -- extending logical volume "/dev/ops/batch" to 1.49 GB
lvextend -- doing automatic backup of volume group "ops"
lvextend -- logical volume "/dev/ops/batch" successfully extended
ext2resize v1.1.15 - 2000/08/08 for EXT2FS 0.5b
e2fsadm -- ext2fs in logical volume "/dev/ops/batch" successfully extended to 1.49 GB</computeroutput>
<command># e2fsadm /dev/dev/users -L+900M</command>
<computeroutput>e2fsck 1.18, 11-Nov-1999 for EXT2 FS 0.5b, 95/08/09
Pass 1: Checking inodes, blocks, and sizes
Pass 2: Checking directory structure
Pass 3: Checking directory connectivity
Pass 4: Checking reference counts
Pass 5: Checking group summary information
/dev/dev/users: 12/262144 files (0.0% non-contiguous), 275245/524288 blocks
lvextend -- extending logical volume "/dev/dev/users" to 2.88 GB
lvextend -- doing automatic backup of volume group "dev"
lvextend -- logical volume "/dev/dev/users" successfully extended
ext2resize v1.1.15 - 2000/08/08 for EXT2FS 0.5b
e2fsadm -- ext2fs in logical volume "/dev/dev/users" successfully extended to 2.88 GB</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Remount the extended volumes</title>
<para>
We can now remount the file systems and see that the is plenty
of space.
<screen>
<command># mount /dev/ops/batch
# mount /dev/dev/users
# df</command>
<computeroutput>Filesystem 1k-blocks Used Available Use% Mounted on
/dev/dev/cvs 1342492 516468 757828 41% /mnt/dev/cvs
/dev/dev/users 2969360 2060036 909324 69% /mnt/dev/users
/dev/dev/build 1548144 1023041 525103 66% /mnt/dev/build
/dev/ops/databases 2890692 2302417 588275 79% /mnt/ops/databases
/dev/sales/users 2064208 871214 1192994 42% /mnt/sales/users
/dev/ops/batch 1535856 897122 638734 58% /mnt/ops/batch</computeroutput>
</screen>
</para>
</sect2>
</sect1>
<sect1 id="Snapshots_Backup"><title>Taking a Backup Using Snapshots</title>
<para>
Following on from the previous example we now want to use the extra
space in the "ops" volume group to make a database backup every
evening. To ensure that the data that goes onto the tape is
consistent we use an LVM snapshot logical volume.
</para>
<para>
A snapshot volume is a special type of volume that presents
all the data that was in the volume at the time the snapshot
was created. For a more detailed description, see
<xref linkend="snapshotintro"/>, Snapshots.
This means we
can back up that volume without having to worry about data
being changed while the backup is going on, and we don't have
to take the database volume offline while the backup is taking
place.
</para>
<note>
<para>
In LVM1, this type of volume was read-only, but
LVM2 creates read/write snapshots by default.
</para>
</note>
<sect2 id="snapbackcreate"><title>Create the snapshot volume</title>
<para>
There is a little over 500 Megabytes of free space in the "ops"
volume group, so we will use all of it to allocate space for the
snapshot logical volume. A snapshot volume can be as large or a
small as you like but it must be large enough to hold all the
changes that are likely to happen to the original volume during
the lifetime of the snapshot. So here, allowing 500 megabytes of
changes to the database volume which should be plenty.
<screen>
<command># lvcreate -L592M -s -n dbbackup /dev/ops/databases </command>
<computeroutput>lvcreate -- WARNING: the snapshot must be disabled if it gets full
lvcreate -- INFO: using default snapshot chunk size of 64 KB for "/dev/ops/dbbackup"
lvcreate -- doing automatic backup of "ops"
lvcreate -- logical volume "/dev/ops/dbbackup" successfully created</computeroutput>
</screen>
</para>
<warning><title>Full snapshot are automatically disabled</title>
<para>
If the snapshot logical volume becomes full it will be dropped
(become unusable) so it is vitally important to allocate enough space.
The amount of space necessary is dependent on the usage of the
snapshot, so there is no set recipe to follow for this. If the
snapshot size equals the origin size, it will never overflow.
</para>
</warning>
</sect2>
<sect2><title>Mount the snapshot volume</title>
<para>
We can now create a mount-point and mount the volume
<screen>
<command># mkdir /mnt/ops/dbbackup
# mount /dev/ops/dbbackup /mnt/ops/dbbackup</command>
<computeroutput>mount: block device /dev/ops/dbbackup is write-protected, mounting read-only</computeroutput>
</screen>
</para>
<para>
If you are using XFS as the filesystem you will need to add the
<option>nouuid</option> option
to the mount command:
<screen>
<command># mount /dev/ops/dbbackup /mnt/ops/dbbackup -onouuid,ro</command>
</screen>
</para>
</sect2>
<sect2><title>Do the backup</title>
<para>
I assume you will have a more sophisticated backup strategy than
this!
<screen>
<command># tar -cf /dev/rmt0 /mnt/ops/dbbackup</command>
<computeroutput>tar: Removing leading `/' from member names</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Remove the snapshot</title>
<para>
When the backup has finished you can now unmount the volume and
remove it from the system. You should remove snapshot volume
when you have finished with them because they take a copy of all
data written to the original volume and this can hurt
performance.
<screen>
<command># umount /mnt/ops/dbbackup
# lvremove /dev/ops/dbbackup </command>
<prompt>lvremove -- do you really want to remove "/dev/ops/dbbackup"? [y/n]: </prompt>y
<computeroutput>lvremove -- doing automatic backup of volume group "ops"
lvremove -- logical volume "/dev/ops/dbbackup" successfully removed</computeroutput>
</screen>
</para>
</sect2>
</sect1>
<sect1 id="RemoveADisk"><title>Removing an Old Disk</title>
<para>
Say you have an old IDE drive on /dev/hdb. You want to remove that
old disk but a lot of files are on it.
</para>
<caution><title>Backup Your System</title>
<para>
You should always backup your system before attempting a pvmove
operation.
</para>
</caution>
<sect2><title>Distributing Old Extents to Existing Disks in Volume Group</title>
<para>
If you have enough free extents on the other disks in the volume
group, you have it easy. Simply run
<screen>
<command># pvmove /dev/hdb</command>
<computeroutput>pvmove -- moving physical extents in active volume group "dev"
pvmove -- WARNING: moving of active logical volumes may cause data loss!</computeroutput>
<prompt>pvmove -- do you want to continue? [y/n]</prompt> y
<computeroutput>pvmove -- 249 extents of physical volume "/dev/hdb" successfully moved</computeroutput>
</screen>
This will move the allocated physical extents from /dev/hdb onto
the rest of the disks in the volume group.
</para>
<note><title><command>pvmove</command> is Slow</title>
<para>
Be aware that pvmove is quite slow as it has to copy the
contents of a disk block by block to one or more disks. If you
want more steady status reports from pvmove, use the
<option>-v</option> flag.
</para>
</note>
<sect3><title>Remove the unused disk</title>
<para>
We can now remove the old IDE disk from the volume group.
<screen>
<command># vgreduce dev /dev/hdb</command>
<computeroutput>vgreduce -- doing automatic backup of volume group "dev"
vgreduce -- volume group "dev" successfully reduced by physical volume:
vgreduce -- /dev/hdb</computeroutput>
</screen>
The drive can now be either physically removed when the
machine is next powered down or reallocated to other users.
</para>
</sect3>
</sect2>
<sect2><title>Distributing Old Extents to a New Replacement Disk</title>
<para>
If you do not have enough free physical extents to distribute
the old physical extents to, you will have to add a disk to the
volume group and move the extents to it.
</para>
<sect3><title>Prepare the disk</title>
<para>
First, you need to pvcreate the new disk to make it available
to LVM. In this recipe we show that you don't need to
partition a disk to be able to use it.
<screen>
<command># pvcreate /dev/sdf</command>
<computeroutput>pvcreate -- physical volume "/dev/sdf" successfully created</computeroutput>
</screen>
</para>
</sect3>
<sect3><title>Add it to the volume group</title>
<para>
As developers use a lot of disk space this is a good volume
group to add it into.
<screen>
<command># vgextend dev /dev/sdf</command>
<computeroutput>vgextend -- INFO: maximum logical volume size is 255.99 Gigabyte
vgextend -- doing automatic backup of volume group "dev"
vgextend -- volume group "dev" successfully extended</computeroutput>
</screen>
</para>
</sect3>
<sect3><title>Move the data</title>
<para>
Next we move the data from the old disk onto the new one.
Note that it is not necessary to unmount the file system
before doing this. Although it is *highly* recommended that
you do a full backup before attempting this operation in case
of a power outage or some other problem that may interrupt
it. The pvmove command can take a considerable amount of time
to complete and it also exacts a performance hit on the two
volumes so, although it isn't necessary, it is advisable to
do this when the volumes are not too busy.
<screen>
<command># pvmove /dev/hdb /dev/sdf</command>
<computeroutput>pvmove -- moving physical extents in active volume group "dev"
pvmove -- WARNING: moving of active logical volumes may cause data loss!</computeroutput>
<prompt>pvmove -- do you want to continue? [y/n]</prompt> y
<computeroutput>pvmove -- 249 extents of physical volume "/dev/hdb" successfully moved</computeroutput>
</screen>
</para>
</sect3>
<sect3><title>Remove the unused disk</title>
<para>
We can now remove the old IDE disk from the volume group.
<screen>
<command># vgreduce dev /dev/hdb</command>
<computeroutput>vgreduce -- doing automatic backup of volume group "dev"
vgreduce -- volume group "dev" successfully reduced by physical volume:
vgreduce -- /dev/hdb</computeroutput>
</screen>
The drive can now be either physically removed when the
machine is next powered down or reallocated to some other
users.
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="recipemovevgtonewsys"><title>Moving a volume group to another system</title>
<para>
It is quite easy to move a whole volume group to another system if,
for example, a user department acquires a new server. To do this we
use the vgexport and vgimport commands.
</para>
<note>
<para>
vgexport/vgimport is not necessary to move drives
from one system to another. It is an administrative policy
tool to prevent access to volumes in the time it takes to
move them.
</para>
</note>
<sect2><title>Unmount the file system</title>
<para>
First, make sure that no users are accessing files on the active
volume, then unmount it
<screen>
<command># unmount /mnt/design/users</command>
</screen>
</para>
</sect2>
<sect2><title>Mark the volume group inactive</title>
<para>
Marking the volume group inactive removes it from the kernel and
prevents any further activity on it.
<screen>
<command># vgchange -an design</command>
<computeroutput>vgchange -- volume group "design" successfully deactivated</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Export the volume group</title>
<para>
It is now necessary to export the volume group. This prevents it
from being accessed on the ``old'' host system and prepares it
to be removed.
<screen>
<command># vgexport design</command>
<computeroutput>vgexport -- volume group "design" successfully exported</computeroutput>
</screen>
When the machine is next shut down, the disk can be unplugged
and then connected to it's new machine
</para>
</sect2>
<sect2><title>Import the volume group</title>
<para>
When plugged into the new system it becomes /dev/sdb so an
initial pvscan shows:
<screen>
<command># pvscan</command>
<computeroutput>pvscan -- reading all physical volumes (this may take a while...)
pvscan -- inactive PV "/dev/sdb1" is in EXPORTED VG "design" [996 MB / 996 MB free]
pvscan -- inactive PV "/dev/sdb2" is in EXPORTED VG "design" [996 MB / 244 MB free]
pvscan -- total: 2 [1.95 GB] / in use: 2 [1.95 GB] / in no VG: 0 [0]</computeroutput>
</screen>
We can now import the volume group (which also activates it) and
mount the file system.
</para>
<para>
If you are importing on an LVM 2 system, run:
<screen>
<command># vgimport design</command>
<computeroutput> Volume group "vg" successfully imported</computeroutput>
</screen>
</para>
<para>
If you are importing on an LVM 1 system, add the PVs that need to be imported:
<screen>
<command># vgimport design /dev/sdb1 /dev/sdb2</command>
<computeroutput>vgimport -- doing automatic backup of volume group "design"
vgimport -- volume group "design" successfully imported and activated</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Activate the volume group</title>
<para>
You must activate the volume group before you can access it.
<screen>
<command># vgchange -ay design</command>
</screen>
</para>
</sect2>
<sect2><title>Mount the file system</title>
<para>
<screen>
<command># mkdir -p /mnt/design/users
# mount /dev/design/users /mnt/design/users</command>
</screen>
The file system is now available for use.
</para>
</sect2>
</sect1>
<sect1 id="recipesplitvg"><title>Splitting a volume group</title>
<para>
There is a new group of users "design" to add to the system. One
way of dealing with this is to create a new volume group to hold
their data. There are no new disks but there is plenty of free
space on the existing disks that can be reallocated.
</para>
<sect2><title>Determine free space</title>
<para>
<screen>
<command># pvscan </command>
<computeroutput>pvscan -- reading all physical volumes (this may take a while...)
pvscan -- ACTIVE PV "/dev/sda" of VG "dev" [1.95 GB / 0 free]
pvscan -- ACTIVE PV "/dev/sdb" of VG "sales" [1.95 GB / 1.27 GB free]
pvscan -- ACTIVE PV "/dev/sdc" of VG "ops" [1.95 GB / 564 MB free]
pvscan -- ACTIVE PV "/dev/sdd" of VG "dev" [1.95 GB / 0 free]
pvscan -- ACTIVE PV "/dev/sde" of VG "ops" [1.95 GB / 1.9 GB free]
pvscan -- ACTIVE PV "/dev/sdf" of VG "dev" [1.95 GB / 1.33 GB free]
pvscan -- ACTIVE PV "/dev/sdg1" of VG "ops" [996 MB / 432 MB free]
pvscan -- ACTIVE PV "/dev/sdg2" of VG "dev" [996 MB / 632 MB free]
pvscan -- total: 8 [13.67 GB] / in use: 8 [13.67 GB] / in no VG: 0 [0]</computeroutput>
</screen>
We decide to reallocate /dev/sdg1 and /dev/sdg2 to design so
first we have to move the physical extents into the free areas
of the other volumes (in this case /dev/sdf for volume group dev
and /dev/sde for volume group ops).
</para>
</sect2>
<sect2><title>Move data off the disks to be used</title>
<para>
Some space is still used on the chosen volumes so it is
necessary to move that used space off onto some others.
</para>
<para>
Move all the used physical extents from /dev/sdg1 to /dev/sde
and from /dev/sdg2 to /dev/sdf
<screen>
<command># pvmove /dev/sdg1 /dev/sde</command>
<computeroutput>pvmove -- moving physical extents in active volume group "ops"
pvmove -- WARNING: moving of active logical volumes may cause data loss!</computeroutput>
<prompt>pvmove -- do you want to continue? [y/n]</prompt> y
<computeroutput>pvmove -- doing automatic backup of volume group "ops"
pvmove -- 141 extents of physical volume "/dev/sdg1" successfully moved</computeroutput>
<command># pvmove /dev/sdg2 /dev/sdf</command>
<computeroutput>pvmove -- moving physical extents in active volume group "dev"
pvmove -- WARNING: moving of active logical volumes may cause data loss!</computeroutput>
<prompt>pvmove -- do you want to continue? [y/n]</prompt> y
<computeroutput>pvmove -- doing automatic backup of volume group "dev"
pvmove -- 91 extents of physical volume "/dev/sdg2" successfully moved</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Create the new volume group</title>
<para>
Now, split /dev/sdg2 from dev and add it into a new group called
"design". it is possible to do this using vgreduce and vgcreate
but the vgsplit command combines the two.
<screen>
<command># vgsplit dev design /dev/sdg2</command>
<computeroutput>vgsplit -- doing automatic backup of volume group "dev"
vgsplit -- doing automatic backup of volume group "design"
vgsplit -- volume group "dev" successfully split into "dev" and "design"</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Remove remaining volume</title>
<para>
Next, remove /dev/sdg1 from ops and add it into design.
<screen>
<command># vgreduce ops /dev/sdg1</command>
<computeroutput>vgreduce -- doing automatic backup of volume group "ops"
vgreduce -- volume group "ops" successfully reduced by physical volume:
vgreduce -- /dev/sdg1</computeroutput>
<command># vgextend design /dev/sdg1</command>
<computeroutput>vgextend -- INFO: maximum logical volume size is 255.99 Gigabyte
vgextend -- doing automatic backup of volume group "design"
vgextend -- volume group "design" successfully extended</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Create new logical volume</title>
<para>
Now create a logical volume. Rather than allocate all of the
available space, leave some spare in case it is needed
elsewhere.
<screen>
<command># lvcreate -L750M -n users design</command>
<computeroutput>lvcreate -- rounding up size to physical extent boundary "752 MB"
lvcreate -- doing automatic backup of "design"
lvcreate -- logical volume "/dev/design/users" successfully created</computeroutput>
</screen>
</para>
</sect2>
<sect2><title>Make a file system on the volume</title>
<screen>
<command># mke2fs /dev/design/users</command>
<computeroutput>mke2fs 1.18, 11-Nov-1999 for EXT2 FS 0.5b, 95/08/09
Filesystem label=
OS type: Linux
Block size=4096 (log=2)
Fragment size=4096 (log=2)
96384 inodes, 192512 blocks
9625 blocks (5.00&lt;!-- ) reserved for the super user
First data block=0
6 block groups
32768 blocks per group, 32768 fragments per group
16064 inodes per group
Superblock backups stored on blocks:
32768, 98304, 163840
Writing inode tables: done
Writing superblocks and filesystem accounting information: done</computeroutput>
</screen>
</sect2>
<sect2><title>Mount the new volume</title>
<screen>
<command># mkdir -p /mnt/design/users mount /dev/design/users /mnt/design/users/</command>
</screen>
<para>
It's also a good idea to add an entry for this file system in
your /etc/fstab file as follows:
<screen>
/dev/design/user
/mnt/design/users ext2 defaults 1 2
</screen>
</para>
</sect2>
</sect1>
<sect1 id="UpgradeRootToLVM"><title>Converting a root filesystem to
LVM 1</title>
<caution><title>Backup Your System</title>
<para>
It is strongly recommended that you take a full backup of your
system before attempting to convert to root on LVM 1.
</para>
</caution>
<warning><title>Upgrade Complications</title>
<para>
Having your root filesystem on LVM 1 can significantly complicate
upgrade procedures (depending on your distribution) so it should
not be attempted lightly. Particularly, you must consider how
you will insure that the LVM 1 kernel module (if you do not have
LVM 1 compiled into the kernel) as well as the vgscan/vgchange
tools are available before, during, and after the upgrade.
</para>
</warning>
<warning><title>Recovery Complications</title>
<para>
Having your root filesystem on LVM 1 can significantly complicate
recovery of damaged filesystems. If you lose your initrd, it
will be very difficult to boot your system. You will need to
have a recover disk that contains the kernel, LVM 1 module, and
LVM 1 tools, as well as any tools necessary to recover a
damaged filesystem.
Be sure to make regular backups and have an up-to-date
alternative boot method that allows for recovery of LVM 1.
<!-- FIXME: Add a section on how to do this -->
</para>
</warning>
<para>
In this example the whole system was installed in a single root
partition with the exception of /boot. The system had a 2 gig disk
partitioned as:
<screen>
/dev/hda1 /boot
/dev/hda2 swap
/dev/hda3 /
</screen>
</para>
<para>
The / partition covered all of the disk not used by /boot and swap.
An important prerequisite of this procedure is that the root
partition is less that half full (so that a copy of it can be
created in a logical volume). If this is not the case then a
second disk drive should be used. The procedure in that case is
similar but there is no need to shrink the existing root partition
and /dev/hda4 should be replaced with (eg) /dev/hdb1 in the
examples.
</para>
<para>
To do this it is easiest to use GNU parted. This software allows
you to grow and shrink partitions that contain filesystems. It is
possible to use resize2fs and fdisk to do this but GNU parted makes
it much less prone to error. It may be included in your
distribution, if not you can download it from
<ulink url="ftp://ftp.gnu.org/pub/gnu/parted">ftp://ftp.gnu.org/pub/gnu/parted</ulink>.
</para>
<para>
Once you have parted on your system AND YOU HAVE BACKED THE SYSTEM
UP:
</para>
<sect2><title>Boot single user</title>
<para>
Boot into single user mode (type <command>linux S</command> at
the LILO prompt) This is important. Booting single-user ensures
that the root filesystem is mounted read-only and no programs
are accessing the disk.
</para>
</sect2>
<sect2><title>Run Parted</title>
<para>
Run parted to shrink the root partition Do this so there is room
on the disk for a complete copy of it in a logical volume. In
this example a 1.8 gig partition is shrunk to 1 gigabyte
This displays the sizes and names of the partitions on the disk
<screen>
<command># parted /dev/hda</command>
<prompt>(parted)</prompt> p
.
.
.
</screen>
</para>
<para>
Now resize the partition:
<screen>
<prompt>(parted)</prompt> resize 3 145 999
</screen>
The first number here the partition number (hda3), the second is
the same starting position that hda3 currently has. Do not
change this. The last number should make the partition around
half the size it currently is.
</para>
<para>
Create a new partition
<screen>
<prompt>(parted)</prompt> mkpart primary ext2 1000 1999
</screen>
This makes a new partition to hold the initial LVM 1 data. It
should start just beyond the newly shrunk hda3 and finish at the
end of the disk.
</para>
<para>
Quit parted
<screen>
<prompt>(parted)</prompt> q
</screen>
</para>
</sect2>
<sect2><title>Reboot</title>
<para>
Reboot the system
</para>
</sect2>
<sect2><title>Verify kernel config options</title>
<para>
Make sure that the kernel you are currently running works with
LVM 1 and has CONFIG_BLK_DEV_RAM and CONFIG_BLK_DEV_INITRD set in
the config file.
</para>
</sect2>
<sect2><title>Adjust partition type</title>
<para>
Change the partition type on the newly created partition from
Linux to LVM (8e). Parted doesn't understand LVM 1 partitions so
this has to be done using fdisk.
<screen>
<command># fdisk /dev/hda</command>
<prompt>Command (m for help): </prompt>t
<prompt>Partition number (1-4): </prompt>4
<prompt>Hex code (type L to list codes): </prompt>8e
<computeroutput>Changed system type of partition 4 to 8e (Unknown)</computeroutput>
<prompt>Command (m for help): </prompt>w
</screen>
</para>
</sect2>
<sect2><title>Set up LVM 1 for the new scheme</title>
<itemizedlist>
<listitem>
<para>
Initialize LVM 1 (vgscan)
<screen>
<command># vgscan</command>
</screen>
</para>
</listitem>
<listitem>
<para>
Make the new partition into a PV
<screen>
<command># pvcreate /dev/hda4</command>
</screen>
</para>
</listitem>
<listitem>
<para>
create a new volume group
<screen>
<command># vgcreate vg /dev/hda4</command>
</screen>
</para>
</listitem>
<listitem>
<para>
Create a logical volume to hold the new root.
<screen>
<command># lvcreate -L250M -n root vg</command>
</screen>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2><title>Create the Filesystem</title>
<para>
Make a filesystem in the logical volume and copy the root files
onto it.
<screen>
<command># mke2fs /dev/vg/root
# mount /dev/vg/root /mnt/
# find / -xdev | cpio -pvmd /mnt</command>
</screen>
</para>
</sect2>
<sect2><title>Update /etc/fstab</title>
<para>
Edit /mnt/etc/fstab on the new root so that / is mounted on
/dev/vg/root. For example:
<screen>
/dev/hda3 / ext2 defaults 1 1
</screen>
becomes:
<screen>
/dev/vg/root / ext2 defaults 1 1
</screen>
</para>
</sect2>
<sect2><title>Create an LVM 1 initial RAM disk</title>
<screen>
<command># lvmcreate_initrd</command>
</screen>
<para>
Make sure you note the name that lvmcreate_initrd calls the
initrd image. It should be in /boot.
</para>
</sect2>
<sect2><title>Update /etc/lilo.conf</title>
<para>
Add an entry in /etc/lilo.conf for LVM 1.
This should look similar to the following:
<screen>
image = /boot/KERNEL_IMAGE_NAME
label = lvm
root = /dev/vg/root
initrd = /boot/INITRD_IMAGE_NAME
ramdisk = 8192
</screen>
Where KERNEL_IMAGE_NAME is the name of your LVM 1 enabled kernel,
and INITRD_IMAGE_NAME is the name of the initrd image created by
lvmcreate_initrd. The ramdisk line may need to be increased if
you have a large LVM 1 configuration, but 8192 should suffice for
most users. The default ramdisk size is 4096. If in doubt check
the output from the lvmcreate_initrd command, the line that
says:
<screen>
lvmcreate_initrd -- making loopback file (6189 kB)
</screen>
and make the ramdisk the size given in brackets.
</para>
<para>
You should copy this new lilo.conf onto /etc in the new root fs
as well.
<screen>
<command># cp /etc/lilo.conf /mnt/etc/</command>
</screen>
</para>
</sect2>
<sect2><title>Run LILO to write the new boot sector</title>
<screen>
<command># lilo</command>
</screen>
</sect2>
<sect2><title>Reboot to lvm</title>
<para>
Reboot - at the LILO prompt type "lvm"
The system should reboot into Linux using the newly created
Logical Volume.
</para>
<para>
If that worked then you should make lvm the default LILO boot
destination by adding the line
<screen>
default=lvm
</screen>
in the first section of /etc/lilo.conf
</para>
<para>
If it did not work then reboot normally and try to diagnose the
problem. It could be a typing error in lilo.conf or LVM 1 not
being available in the initial RAM disk or its kernel. Examine
the message produced at boot time carefully.
</para>
</sect2>
<sect2><title>Add remainder of disk</title>
<para>
Add the rest of the disk into LVM 1. When you are happy with this
setup you can then add the old root partition to LVM 1 and spread
out over the disk.
</para>
<para>
First set the partition type to 8e(LVM)
<screen>
<command># fdisk /dev/hda</command>
<prompt>Command (m for help): </prompt>t
<prompt>Partition number (1-4): </prompt>3
<prompt>Hex code (type L to list codes): </prompt>8e
<computeroutput>Changed system type of partition 3 to 8e (Unknown)</computeroutput>
<prompt>Command (m for help): </prompt>w
</screen>
</para>
<para>
Convert it into a PV and add it to the volume group:
<screen>
<command># pvcreate /dev/hda3
# vgextend vg /dev/hda3</command>
</screen>
</para>
</sect2>
</sect1>
<sect1 id="recovermetadata"><title>Recover physical volume metadata</title>
<para>
If you get the warning "incorrect metadata area header checksum"
or something about not being able to find PV with UUID foo,
you probably toasted the volume group descriptor area and lvm
startup can't occur.
</para>
<warning><title>Only run on non-functional VG</title>
<para>
Don't do this on a properly working lvm.
You need to specify the correct physical volume to
<command>pvcreate</command> or you may lose your data.
</para>
</warning>
<para>
Extract the exact uuid for the PV that was overwritten from the file
<filename>/etc/lvm/archive/VolumeGroupName_XXXXX.vg</filename>.
(Where XXXXX represents the number of the last known good archived lvm
metadata).
</para>
<para>
Use <command>pvcreate</command> to restore the metadata:
<command>pvcreate --uuid "&lt;some_long_string&gt;" --restorefile /etc/lvm/archive/VolumeGroupName_XXXXX.vg &lt;PhysicalVolume&gt;</command>
</para>
<para>
If you are lucky you'll find that the on-disk lvm metadata takes
at least so much space as what it was overwritten with. The above
command has been know to recover a PV overwritten with mkswap. If
whatever overwrote the VGDA writes past that area, LVs may be affected.
In this case, fsck might be able to fix the filesystem on the LV, or
you may need more drastic measures to pull data off of it. Contact
your local friendly filesystem expert for help in that case.
</para>
<note>
<para><command>pvcreate</command> only overwrites the lvm metadata
areas on disk and doesn't touch the data areas (the logical
volumes).
</para>
</note>
</sect1>
</chapter>
<appendix id="dangerousops"><title>Dangerous Operations</title>
<warning><title>Warning</title>
<para>
Don't do this unless you're really sure of what you're doing.
You'll probably lose all your data.
</para>
</warning>
<sect1 id="uuidfixer"><title>Restoring the VG UUIDs using uuid_fixer</title>
<para>
If you've upgraded LVM from previous versions to early 0.9 and
0.9.1 versions of LVM and <command>vgscan</command> says
<computeroutput>vgscan -- no volume groups found</computeroutput>,
this is one way to fix it.
</para>
<itemizedlist>
<listitem>
<para>
Download the UUID fixer program from the contributor
directory at Sistina.
</para>
<para>
It is located at
<ulink url="ftp://ftp.sistina.com/pub/LVM/contrib/uuid_fixer-0.3-IOP10.tar.gz">ftp://ftp.sistina.com/pub/LVM/contrib/uuid_fixer-0.3-IOP10.tar.gz"</ulink>
</para>
</listitem>
<listitem>
<para>
Extract <filename>uuid_fixer-0.3-IOP10.tar.gz</filename>
<screen>
<command># tar zxf uuid_fixer-0.3-IOP10.tar.gz</command>
</screen>
</para>
</listitem>
<listitem>
<para>
cd to uuid_fixer
<screen>
<command># cd uuid_fixer</command>
</screen>
</para>
<para>
You have one of two options at this point:
</para>
<orderedlist>
<listitem>
<para>
Use the prebuild binary (it is build for i386
architecture).
</para>
<para>
Make sure you list all the PVs in the VG you are
restoring, and follow the prompts
<screen>
<command># ./uuid_fixer </command><replaceable>&lt;LIST OF ALL PVS IN VG TO BE RESTORED&gt;</replaceable>
</screen>
</para>
</listitem>
<listitem>
<para>
Build the uuid_builder program from source
</para>
<para>
Edit the Makefile with your favorite editor, and make
sure LVMDIR points to your LVM source.
</para>
<para>
Then run make.
<screen>
<command># make</command>
</screen>
</para>
<para>
Now run uuid_fixer. Make sure you list all the PVs in
the VG you are restoring, and follow the prompts.
<screen>
<command># ./uuid_fixer </command><replaceable>&lt;LIST OF ALL PVS IN VG TO BE RESTORED&gt;</replaceable>
</screen>
</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>
Deactivate any active Volume Groups
(<emphasis>optional</emphasis>)
<screen>
<command># vgchange -an</command>
</screen>
</para>
</listitem>
<listitem>
<para>
Run vgscan
<screen>
<command># vgscan</command>
</screen>
</para>
</listitem>
<listitem>
<para>
Reactivate Volume Groups
<screen>
<command># vgchange -ay</command>
</screen>
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="sharinglvm1"><title>Sharing LVM volumes</title>
<warning><title>LVM is not cluster aware</title>
<para>
Be very careful doing this, LVM is not currently cluster-aware
and it is very easy to lose all your data.
</para>
</warning>
<para>
If you have a fibre-channel or shared-SCSI environment where more
than one machine has physical access to a set of disks then you can
use LVM to divide these disks up into logical volumes. If you want
to share data you should really be looking at
<ulink url="http://www.sistina.com/gfs">GFS</ulink> or other
cluster filesystems.
</para>
<para>
The key thing to remember when sharing volumes is that all the LVM
administration must be done on one node only and that all other
nodes must have LVM shut down before changing anything on the admin
node. Then, when the changes have been made, it is necessary to
run vgscan on the other nodes before reloading the volume groups.
Also, unless you are running a cluster-aware filesystem (such as
GFS) or application on the volume, only one node can mount each
filesystem. It is up to you, as system administrator to enforce
this, LVM will not stop you corrupting your data.
</para>
<para>
The startup sequence of each node is the same as for a single-node
setup with
<screen>
vgscan
vgchange -ay
</screen>
in the startup scripts.
</para>
<para>
If you need to do <emphasis role="strong">any</emphasis> changes to
the LVM metadata (regardless of whether it affects volumes mounted
on other nodes) you must go through the following sequence. In the
steps below ``admin node'' is any arbitrarily chosen node in the
cluster.
<screen>
Admin node Other nodes
---------- -----------
Close all Logical volumes (umount)
vgchange -an
&lt;make changes, eg lvextend&gt;
vgscan
vgchange -ay
</screen>
</para>
<note><title>VGs should be active on the admin node</title>
<para>
You do not need to, nor should you, unload the VGs on
the admin node, so this can be the node with the highest uptime
requirement.
</para>
</note>
<para>
I'll say it again: <emphasis role="strong">Be very careful doing
this</emphasis>
</para>
</sect1>
</appendix>
<appendix id="ReportBug"><title>Reporting Errors and Bugs</title>
<para>
Just telling us that LVM did not work does not provide us with enough
information to help you. We need to know about your setup and the
various components of your configuration. The first thing you should
do is check the
<ulink url="http://lists.sistina.com/pipermail/linux-lvm/">linux-lvm mailing list archives</ulink>
to see if someone else has already reported the same bug. If you do
not find a bug report for a problem similar to yours you should
collect as much of the following information as possible. The list is
grouped into three categories of errors.
</para>
<itemizedlist>
<listitem>
<para>
For compilation errors:
</para>
<orderedlist>
<listitem>
<para>
Detail the specific version of LVM you have. If you
extracted LVM from a tarball give the name of the tar file
and list any patches you applied. If you acquired LVM
from the Public CVS server, give the date and time you
checked it out.
</para>
</listitem>
<listitem>
<para>
Provide the exact error message. Copy the lines
of output before the actual error message as well
as the lines after. These lines occasionally
give hints as to why the error occurred.
</para>
</listitem>
<listitem>
<para>
List the steps, in order, that produced the error. Is the
error reproducible? If you start from a clean state does
the same sequence of steps reproduce the error?
</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>
For LVM errors:
</para>
<orderedlist>
<listitem>
<para>
Include all of the information requested in the
compilation section.
</para>
</listitem>
<listitem>
<para>
Attach a short description of your hardware: types of
machines and disks, disks interface (SCSI, FC, NBD). Any
other tidbits about your hardware you feel is important.
</para>
</listitem>
<listitem>
<para>
The command lines used with LVM to produce the error.
</para>
</listitem>
<listitem>
<para>
A log file produced when running the offending commands.
Make sure you have the following in your
<filename>/etc/lvm/lvm.conf</filename> file:
<screen>
log {
file="/tmp/lvm2.log"
level=7
activation=1
}
</screen>
</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>
When LVM trips a panic trap:
</para>
<orderedlist>
<listitem>
<para>
Include all of the information requested in two sections
above.
</para>
</listitem>
<listitem>
<para>
Provide the debug dump for the machine. This is best
accomplished if you are watching the console output of the
computer over a serial link, since you can't very well
copy and paste from a panic'd machine, and it is very easy
to mistype something if you try to copy the output by
hand.
</para>
</listitem>
</orderedlist>
</listitem>
</itemizedlist>
<para>
This can be a lot of information. If you end up with more
than a couple of files, tar and gzip them into a single
archive. Submit a link to where this file can be found to
the appropriate mailing list (see <xref
linkend="Maillists"/>) along with a short description of the
error. If you do not have a public web or ftp site that you
can post the information to, you can try to submit the file
to the list.
</para>
</appendix>
<appendix id="contactsandlinks"><title>Contact and Links</title>
<sect1 id="Maillists"><title>Mail lists</title>
<para>
Before you post to any of our lists please read the all of
this document and check the archives to see if your
question has already been answered. Please post in text
only to our lists, fancy formated messages are near
impossible to read if someone else is not running a mail
client that understands it. Standard mailing list
etiquette applies. Incomplete questions or configuration
data make it very hard for us to answer your questions.
</para>
<variablelist><title>LVM Discussion Mailing Lists</title>
<varlistentry><term>linux-lvm</term>
<listitem>
<para>
This list is aimed at user-related questions and comments.
You may be able to get the answers you need from other
people who have the same issues. Open discussion is
encouraged. Bug reports should be sent to this list.
</para>
<para>
Subscribe using the <ulink
url="http://www.redhat.com/mailman/listinfo/linux-lvm">web
interface</ulink>.
</para>
<para>
Look at the <ulink
url="http://www.redhat.com/archives/linux-lvm/">
archives</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry><term>dm-devel</term>
<listitem>
<para>
This list is not specifically for lvm, but since
device mapper is used by LVM 2, it is mentioned
here.
</para>
<para>
Subscribe using the <ulink
url="http://www.redhat.com/mailman/listinfo/dm-devel">web
interface</ulink>.
</para>
<para>
Look at the <ulink
url="http://www.redhat.com/archives/dm-devel/">
archives</ulink>
</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist><title>LVM-Related Commit Lists</title>
<varlistentry><term>lvm2-commit</term>
<listitem>
<para>
This list gets messages automatically whenever
someone commits to the lvm2 cvs tree. Its main
purpose is to keep up with the cvs tree.
</para>
<para>
Look at the <ulink
url="http://sources.redhat.com/ml/lvm2-cvs/">
archives</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry><term>lvm-commit</term>
<listitem>
<para>
This list gets messages automatically whenever
someone commits to the lvm cvs tree. Its main
purpose is to keep up with the cvs tree.
</para>
<para>
Look at the <ulink
url="http://sources.redhat.com/ml/lvm-cvs/">
archives</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry><term>dm-commit</term>
<listitem>
<para>
This list gets messages automatically whenever
someone commits to the dm cvs tree. Its main
purpose is to keep up with the cvs tree.
</para>
<para>
Look at the <ulink
url="http://sources.redhat.com/ml/dm-cvs/">
archives</ulink>
</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist><title>Discontinued Lists</title>
<varlistentry><term>lvm-devel</term>
<listitem>
<para>
This list has been discontinued; please use
linux-lvm for lvm development discussion.
</para>
</listitem>
</varlistentry>
<varlistentry><term>lvm-bugs</term>
<listitem>
<para>
This list has been discontinued; Bug reports should be
sent to the linux-lvm list.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="Links"><title>Links</title>
<para>
LVM Links:
</para>
<itemizedlist>
<listitem>
<para>
The <ulink url="http://sources.redhat.com/lvm2/">Logical
Volume Manager</ulink> home page.
</para>
</listitem>
<listitem>
<para>
The <ulink url="http://sources.redhat.com/lvm/">LVM
1</ulink> home page.
</para>
</listitem>
<listitem>
<para>
The <ulink url="http://sources.redhat.com/dm/">Device
Mapper</ulink> home page.
</para>
</listitem>
<listitem>
<para>
The <ulink url="ftp://sources.redhat.com/pub/lvm2/">LVM
2 ftp</ulink> site.
</para>
</listitem>
<listitem>
<para>
The <ulink url="ftp://sources.redhat.com/pub/lvm/">LVM
1 ftp</ulink> site.
</para>
</listitem>
<listitem>
<para>
The <ulink url="ftp://sources.redhat.com/pub/dm/">Device
Mapper ftp</ulink> site.
</para>
</listitem>
</itemizedlist>
</sect1>
</appendix>
<appendix id="gfdl">
<title>GNU Free Documentation License</title>
<subtitle>Version 1.2, November 2002</subtitle>
<blockquote id="fsf-copyright">
<para>Copyright (C) 2000,2001,2002 Free Software Foundation,
Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not
allowed.</para>
</blockquote>
<section id="gfdl-0"><title>PREAMBLE</title>
<para>The purpose of this License is to make a manual, textbook,
or other functional and useful document "free" in the sense of
freedom: to assure everyone the effective freedom to copy and
redistribute it, with or without modifying it, either
commercially or noncommercially. Secondarily, this License
preserves for the author and publisher a way to get credit for
their work, while not being considered responsible for
modifications made by others.</para>
<para>This License is a kind of "copyleft", which means that
derivative works of the document must themselves be free in
the same sense. It complements the GNU General Public
License, which is a copyleft license designed for free
software.</para>
<para>We have designed this License in order to use it for
manuals for free software, because free software needs free
documentation: a free program should come with manuals
providing the same freedoms that the software does. But this
License is not limited to software manuals; it can be used for
any textual work, regardless of subject matter or whether it
is published as a printed book. We recommend this License
principally for works whose purpose is instruction or
reference.</para>
</section>
<section id="gfdl-1"><title>APPLICABILITY AND DEFINITIONS</title>
<para id="gfdl-doc">This License applies to any manual or other
work, in any medium, that contains a notice placed by the
copyright holder saying it can be distributed under the terms
of this License. Such a notice grants a world-wide,
royalty-free license, unlimited in duration, to use that work
under the conditions stated herein. The "Document", below,
refers to any such manual or work. Any member of the public
is a licensee, and is addressed as "you". You accept the
license if you copy, modify or distribute the work in a way
requiring permission under copyright law.</para>
<para id="gfdl-mod-ver">A "Modified Version" of the Document
means any work containing the Document or a portion of it,
either copied verbatim, or with modifications and/or
translated into another language.</para>
<para id="gfdl-secnd-sect">A "Secondary Section" is a named
appendix or a front-matter section of the Document that deals
exclusively with the relationship of the publishers or authors
of the Document to the Document's overall subject (or to
related matters) and contains nothing that could fall directly
within that overall subject. (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter
of historical connection with the subject or with related
matters, or of legal, commercial, philosophical, ethical or
political position regarding them.</para>
<para id="gfdl-inv-sect">The "Invariant Sections" are certain
Secondary Sections whose titles are designated, as being those
of Invariant Sections, in the notice that says that the
Document is released under this License. If a section does
not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may
contain zero Invariant Sections. If the Document does not
identify any Invariant Sections then there are none.</para>
<para id="gfdl-cov-text">The "Cover Texts" are certain short
passages of text that are listed, as Front-Cover Texts or
Back-Cover Texts, in the notice that says that the Document is
released under this License. A Front-Cover Text may be at
most 5 words, and a Back-Cover Text may be at most 25
words.</para>
<para id="gfdl-transparent">A "Transparent" copy of the Document
means a machine-readable copy, represented in a format whose
specification is available to the general public, that is
suitable for revising the document straightforwardly with
generic text editors or (for images composed of pixels)
generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text
formatters or for automatic translation to a variety of
formats suitable for input to text formatters. A copy made in
an otherwise Transparent file format whose markup, or absence
of markup, has been arranged to thwart or discourage
subsequent modification by readers is not Transparent. An
image format is not Transparent if used for any substantial
amount of text. A copy that is not "Transparent" is called
"Opaque".</para>
<para>Examples of suitable formats for Transparent copies
include plain ASCII without markup, Texinfo input format,
LaTeX input format, SGML or XML using a publicly available
DTD, and standard-conforming simple HTML, PostScript or PDF
designed for human modification. Examples of transparent
image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only
by proprietary word processors, SGML or XML for which the DTD
and/or processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some
word processors for output purposes only.</para>
<para id="gfdl-title-page">The "Title Page" means, for a printed
book, the title page itself, plus such following pages as are
needed to hold, legibly, the material this License requires to
appear in the title page. For works in formats which do not
have any title page as such, "Title Page" means the text near
the most prominent appearance of the work's title, preceding
the beginning of the body of the text.</para>
<para id="gfdl-entitled">A section "Entitled XYZ" means a named
subunit of the Document whose title either is precisely XYZ or
contains XYZ in parentheses following text that translates XYZ
in another language. (Here XYZ stands for a specific section
name mentioned below, such as "Acknowledgements",
"Dedications", "Endorsements", or "History".) To "Preserve
the Title" of such a section when you modify the Document
means that it remains a section "Entitled XYZ" according to
this definition.</para>
<para>The Document may include Warranty Disclaimers next to the
notice which states that this License applies to the Document.
These Warranty Disclaimers are considered to be included by
reference in this License, but only as regards disclaiming
warranties: any other implication that these Warranty
Disclaimers may have is void and has no effect on the meaning
of this License.</para>
</section>
<section id="gfdl-2"><title>VERBATIM COPYING</title>
<para>You may copy and distribute the Document in any medium,
either commercially or noncommercially, provided that this
License, the copyright notices, and the license notice saying
this License applies to the Document are reproduced in all
copies, and that you add no other conditions whatsoever to
those of this License. You may not use technical measures to
obstruct or control the reading or further copying of the
copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a
large enough number of copies you must also follow the
conditions in section 3.
</para>
<para>You may also lend copies, under the same conditions stated
above, and you may publicly display copies.</para>
</section>
<section id="gfdl-3"><title>COPYING IN QUANTITY</title>
<para>If you publish printed copies (or copies in media that
commonly have printed covers) of the Document, numbering more
than 100, and the Document's license notice requires Cover
Texts, you must enclose the copies in covers that carry,
clearly and legibly, all these Cover Texts: Front-Cover Texts
on the front cover, and Back-Cover Texts on the back cover.
Both covers must also clearly and legibly identify you as the
publisher of these copies. The front cover must present the
full title with all words of the title equally prominent and
visible. You may add other material on the covers in
addition. Copying with changes limited to the covers, as long
as they preserve the title of the Document and satisfy these
conditions, can be treated as verbatim copying in other
respects.</para>
<para>If the required texts for either cover are too voluminous
to fit legibly, you should put the first ones listed (as many
as fit reasonably) on the actual cover, and continue the rest
onto adjacent pages.</para>
<para>If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy,
or state in or with each Opaque copy a computer-network
location from which the general network-using public has
access to download using public-standard network protocols a
complete Transparent copy of the Document, free of added
material. If you use the latter option, you must take
reasonably prudent steps, when you begin distribution of
Opaque copies in quantity, to ensure that this Transparent
copy will remain thus accessible at the stated location until
at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that
edition to the public.</para>
<para>It is requested, but not required, that you contact the
authors of the Document well before redistributing any large
number of copies, to give them a chance to provide you with an
updated version of the Document.</para>
</section>
<section id="gfdl-4"><title>MODIFICATIONS</title>
<para>You may copy and distribute a Modified Version of the
Document under the conditions of sections 2 and 3 above,
provided that you release the Modified Version under precisely
this License, with the Modified Version filling the role of
the Document, thus licensing distribution and modification of
the Modified Version to whoever possesses a copy of it. In
addition, you must do these things in the Modified
Version:</para>
<orderedlist id="gfdl-modif-cond" numeration="upperalpha">
<listitem><simpara>Use in the Title Page (and on the covers,
if any) a title distinct from that of the Document, and
from those of previous versions (which should, if there
were any, be listed in the History section of the
Document). You may use the same title as a previous
version if the original publisher of that version gives
permission. </simpara></listitem>
<listitem><simpara>List on the Title Page, as authors, one or
more persons or entities responsible for authorship of the
modifications in the Modified Version, together with at
least five of the principal authors of the Document (all
of its principal authors, if it has fewer than five),
unless they release you from this requirement.
</simpara></listitem>
<listitem><simpara>State on the Title page the name of the
publisher of the Modified Version, as the
publisher.</simpara></listitem>
<listitem><simpara>Preserve all the copyright notices of the
Document. </simpara></listitem>
<listitem><simpara> Add an appropriate copyright notice for
your modifications adjacent to the other copyright
notices. </simpara></listitem>
<listitem><simpara>Include, immediately after the copyright notices, a
license notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in the
<link linkend="gfdl-addendum">Addendum</link> below.
</simpara></listitem>
<listitem><simpara>Preserve in that license notice the full lists of
Invariant Sections and required Cover Texts given in the Document's
license notice.</simpara></listitem>
<listitem><simpara>Include an unaltered copy of this License.
</simpara></listitem>
<listitem><simpara>Preserve the section Entitled "History",
Preserve its Title, and add to it an item stating at least
the title, year, new authors, and publisher of the
Modified Version as given on the Title Page. If there is
no section Entitled "History" in the Document, create one
stating the title, year, authors, and publisher of the
Document as given on its Title Page, then add an item
describing the Modified Version as stated in the previous
sentence. </simpara></listitem>
<listitem><simpara>Preserve the network location, if any,
given in the Document for public access to a Transparent
copy of the Document, and likewise the network locations
given in the Document for previous versions it was based
on. These may be placed in the "History" section. You
may omit a network location for a work that was published
at least four years before the Document itself, or if the
original publisher of the version it refers to gives
permission. </simpara></listitem>
<listitem><simpara>For any section Entitled "Acknowledgements"
or "Dedications", Preserve the Title of the section, and
preserve in the section all the substance and tone of each
of the contributor acknowledgements and/or dedications
given therein. </simpara></listitem>
<listitem><simpara>Preserve all the Invariant Sections of the
Document, unaltered in their text and in their titles.
Section numbers or the equivalent are not considered part
of the section titles. </simpara></listitem>
<listitem><simpara>Delete any section Entitled "Endorsements".
Such a section may not be included in the Modified
Version. </simpara></listitem>
<listitem><simpara>Do not retitle any existing section to be
Entitled "Endorsements" or to conflict in title with any
Invariant Section. </simpara></listitem>
<listitem><simpara>Preserve any Warranty Disclaimers.
</simpara></listitem>
</orderedlist>
<para>If the Modified Version includes new front-matter sections
or appendices that qualify as Secondary Sections and contain
no material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do
this, add their titles to the list of Invariant Sections in
the Modified Version's license notice. These titles must be
distinct from any other section titles.</para>
<para>You may add a section Entitled "Endorsements", provided it
contains nothing but endorsements of your Modified Version by
various parties--for example, statements of peer review or
that the text has been approved by an organization as the
authoritative definition of a standard.</para>
<para>You may add a passage of up to five words as a Front-Cover
Text, and a passage of up to 25 words as a Back-Cover Text, to
the end of the list of Cover Texts in the Modified Version.
Only one passage of Front-Cover Text and one of Back-Cover
Text may be added by (or through arrangements made by) any one
entity. If the Document already includes a cover text for the
same cover, previously added by you or by arrangement made by
the same entity you are acting on behalf of, you may not add
another; but you may replace the old one, on explicit
permission from the previous publisher that added the old
one.</para>
<para>The author(s) and publisher(s) of the Document do not by
this License give permission to use their names for publicity
for or to assert or imply endorsement of any Modified
Version.</para>
</section>
<section id="gfdl-5"><title>COMBINING DOCUMENTS</title>
<para>You may combine the Document with other documents released
under this License, under the terms defined in <link
linkend="gfdl-4">section 4</link> above for modified versions,
provided that you include in the combination all of the
Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.</para>
<para>The combined work need only contain one copy of this
License, and multiple identical Invariant Sections may be
replaced with a single copy. If there are multiple Invariant
Sections with the same name but different contents, make the
title of each such section unique by adding at the end of it,
in parentheses, the name of the original author or publisher
of that section if known, or else a unique number. Make the
same adjustment to the section titles in the list of Invariant
Sections in the license notice of the combined work.</para>
<para>In the combination, you must combine any sections Entitled
"History" in the various original documents, forming one
section Entitled "History"; likewise combine any sections
Entitled "Acknowledgements", and any sections Entitled
"Dedications". You must delete all sections Entitled
"Endorsements".</para>
</section>
<section id="gfdl-6"><title>COLLECTIONS OF DOCUMENTS</title>
<para>You may make a collection consisting of the Document and
other documents released under this License, and replace the
individual copies of this License in the various documents
with a single copy that is included in the collection,
provided that you follow the rules of this License for
verbatim copying of each of the documents in all other
respects.</para>
<para>You may extract a single document from such a collection,
and distribute it individually under this License, provided
you insert a copy of this License into the extracted document,
and follow this License in all other respects regarding
verbatim copying of that document.</para>
</section>
<section id="gfdl-7"><title>AGGREGATION WITH INDEPENDENT WORKS</title>
<para>A compilation of the Document or its derivatives with
other separate and independent documents or works, in or on a
volume of a storage or distribution medium, is called an
"aggregate" if the copyright resulting from the compilation is
not used to limit the legal rights of the compilation's users
beyond what the individual works permit. When the Document is
included in an aggregate, this License does not apply to the
other works in the aggregate which are not themselves
derivative works of the Document.</para>
<para>If the Cover Text requirement of section 3 is applicable
to these copies of the Document, then if the Document is less
than one half of the entire aggregate, the Document's Cover
Texts may be placed on covers that bracket the Document within
the aggregate, or the electronic equivalent of covers if the
Document is in electronic form. Otherwise they must appear on
printed covers that bracket the whole aggregate.</para>
</section>
<section id="gfdl-8"><title>TRANSLATION</title>
<para>Translation is considered a kind of modification, so you
may distribute translations of the Document under the terms of
section 4. Replacing Invariant Sections with translations
requires special permission from their copyright holders, but
you may include translations of some or all Invariant Sections
in addition to the original versions of these Invariant
Sections. You may include a translation of this License, and
all the license notices in the Document, and any Warranty
Disclaimers, provided that you also include the original
English version of this License and the original versions of
those notices and disclaimers. In case of a disagreement
between the translation and the original version of this
License or a notice or disclaimer, the original version will
prevail.</para>
<para>If a section in the Document is Entitled
"Acknowledgements", "Dedications", or "History", the
requirement (section 4) to Preserve its Title (section 1) will
typically require changing the actual title.</para>
</section>
<section id="gfdl-9"><title>TERMINATION</title>
<para>You may not copy, modify, sublicense, or distribute the
Document except as expressly provided for under this License.
Any other attempt to copy, modify, sublicense or distribute
the Document is void, and will automatically terminate your
rights under this License. However, parties who have received
copies, or rights, from you under this License will not have
their licenses terminated so long as such parties remain in
full compliance.</para>
</section>
<section id="gfdl-10"><title>FUTURE REVISIONS OF THIS LICENSE</title>
<para>The Free Software Foundation may publish new, revised
versions of the GNU Free Documentation License from time to
time. Such new versions will be similar in spirit to the
present version, but may differ in detail to address new
problems or concerns. See
http://www.gnu.org/copyleft/.</para>
<para>Each version of the License is given a distinguishing
version number. If the Document specifies that a particular
numbered version of this License "or any later version"
applies to it, you have the option of following the terms and
conditions either of that specified version or of any later
version that has been published (not as a draft) by the Free
Software Foundation. If the Document does not specify a
version number of this License, you may choose any version
ever published (not as a draft) by the Free Software
Foundation.</para>
</section>
<section id="gfdl-addendum"><title>ADDENDUM: How to use this License for
your documents</title>
<para>To use this License in a document you have written,
include a copy of the License in the document and put the
following copyright and license notices just after the title
page:</para>
<blockquote id="copyright-sample"><para> Copyright (c) YEAR YOUR
NAME. Permission is granted to copy, distribute and/or
modify this document under the terms of the GNU Free
Documentation License, Version 1.2 or any later version
published by the Free Software Foundation; with no Invariant
Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled "GNU
Free Documentation License". </para></blockquote>
<para>If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:</para>
<blockquote id="inv-cover-sample"><para> with the Invariant
Sections being LIST THEIR TITLES, with the Front-Cover Texts
being LIST, and with the Back-Cover Texts being LIST.
</para></blockquote>
<para>If you have Invariant Sections without Cover Texts, or
some other combination of the three, merge those two
alternatives to suit the situation.</para>
<para>If your document contains nontrivial examples of program
code, we recommend releasing these examples in parallel under
your choice of free software license, such as the GNU General
Public License, to permit their use in free software.</para>
</section>
</appendix>
</book>
View Git Blame Copy Permalink