source: postlfs/filesystems/lvm2.xml

trunk
Last change on this file was 1241ea19, checked in by Bruce Dubbs <bdubbs@…>, 2 months ago

Tag xfce and dependencies

  • Property mode set to 100644
File size: 16.1 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY lvm2-download-http "https://sourceware.org/ftp/lvm2/LVM2.&lvm2-version;.tgz">
8 <!ENTITY lvm2-download-ftp " ">
9 <!ENTITY lvm2-md5sum "0535b5e638b6f0b48f7b259e0ec0ba65">
10 <!ENTITY lvm2-size "2.7 MB">
11 <!ENTITY lvm2-buildsize "39 MB (add 20 MB for tests; transient files can grow up to around 300 MB in the /tmp directory during tests)">
12 <!-- My build size was 124 MB with tests, but I'll leave this here. -renodr
13 The files in /tmp are transient. I monitor /tmp with a loop during
14 tests. -pierre, August 2020
15
16 Build size with tests was 58M. The largest size of /tmp I saw was 289MB.
17 ### 412 tests: 245 passed, 155 skipped, 0 timed out, 1 warned, 11 failed
18 Aug 2023 LVM2.2.03.22 - bdubbs
19
20 ### 424 tests: 261 passed, 153 skipped, 0 timed out, 1 warned, 9 failed
21 Nov 2023 LVM2.2.03.23 - bdubbs
22 -->
23 <!ENTITY lvm2-time "0.1 SBU (using parallelism=4; add 9 to 48 SBU for tests, depending on disk speed and whether ram block device is enabled in the kernel)">
24]>
25
26<sect1 id="lvm2" xreflabel="LVM2-&lvm2-version;">
27 <?dbhtml filename="lvm2.html"?>
28
29
30 <title>LVM2-&lvm2-version;</title>
31
32 <indexterm zone="lvm2">
33 <primary sortas="a-LVM2">LVM2</primary>
34 </indexterm>
35
36 <sect2 role="package">
37 <title>Introduction to LVM2</title>
38
39 <para>
40 The <application>LVM2</application> package is a set of tools that manage
41 logical partitions. It allows spanning of file systems across multiple
42 physical disks and disk partitions and provides for dynamic growing or
43 shrinking of logical partitions, mirroring and low storage footprint
44 snapshots.
45 </para>
46
47 &lfs121_checked;
48
49 <bridgehead renderas="sect3">Package Information</bridgehead>
50 <itemizedlist spacing="compact">
51 <listitem>
52 <para>
53 Download (HTTP): <ulink url="&lvm2-download-http;"/>
54 </para>
55 </listitem>
56 <listitem>
57 <para>
58 Download (FTP): <ulink url="&lvm2-download-ftp;"/>
59 </para>
60 </listitem>
61 <listitem>
62 <para>
63 Download MD5 sum: &lvm2-md5sum;
64 </para>
65 </listitem>
66 <listitem>
67 <para>
68 Download size: &lvm2-size;
69 </para>
70 </listitem>
71 <listitem>
72 <para>
73 Estimated disk space required: &lvm2-buildsize;
74 </para>
75 </listitem>
76 <listitem>
77 <para>
78 Estimated build time: &lvm2-time;
79 </para>
80 </listitem>
81 </itemizedlist>
82
83 <bridgehead renderas="sect3">LVM2 Dependencies</bridgehead>
84
85 <bridgehead renderas="sect4">Required</bridgehead>
86 <para role="required">
87 <xref linkend='libaio'/>
88 </para>
89
90 <bridgehead renderas="sect4">Optional</bridgehead>
91 <para role="optional">
92 <xref linkend='mdadm'/>,
93 <xref linkend='valgrind'/>,
94 <xref linkend='which'/>,
95 <xref linkend='xfsprogs'/> (all four may be used, but are not required,
96 for tests),
97 <ulink
98 url='https://mirrors.edge.kernel.org/pub/linux/kernel/people/jeffm/reiserfsprogs/'>
99 reiserfsprogs</ulink>,
100 <ulink url='https://github.com/jthornber/thin-provisioning-tools'>
101 thin-provisioning-tools</ulink>, and
102 <ulink url="https://github.com/dm-vdo/vdo">vdo</ulink>
103 </para>
104
105 </sect2>
106
107 <sect2 role="kernel" id="lvm2-kernel">
108 <title>Kernel Configuration</title>
109
110 <para>
111 Enable the following options in the kernel configuration
112 and recompile the kernel:
113 </para>
114
115 <note><para>
116 There are several other Device Mapper options in the kernel beyond those
117 listed below. In order to get reasonable results if running the
118 regression tests, all must be enabled either internally or as a module.
119 The tests will all time out if Magic SysRq key is not enabled.
120 </para></note>
121
122 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
123 href="lvm2-kernel.xml"/>
124
125 <indexterm zone="lvm2 lvm2-kernel">
126 <primary sortas="d-lvm2">lvm2</primary>
127 </indexterm>
128
129 </sect2>
130
131 <sect2 role="installation">
132 <title>Installation of LVM2</title>
133
134 <para>
135 Install <application>LVM2</application> by running the following
136 commands:
137 </para>
138
139<screen><userinput>PATH+=:/usr/sbin \
140./configure --prefix=/usr \
141 --enable-cmdlib \
142 --enable-pkgconfig \
143 --enable-udev_sync &amp;&amp;
144make</userinput></screen>
145
146 <para>
147 The tests use <application>udev</application> for logical volume
148 synchronization, so the LVM udev rules and some utilities need to
149 be installed before running the tests. If you are installing
150 <application>LVM2</application> for the first time, and do not
151 want to install the full package before running the tests, the minimal
152 set of utilities can be installed by running the following instructions
153 as the <systemitem class="username">root</systemitem> user:
154 </para>
155
156<screen role="root"
157 remap="test"><userinput>make -C tools install_tools_dynamic &amp;&amp;
158make -C udev install &amp;&amp;
159make -C libdm install</userinput></screen>
160
161 <para>
162 To test the results, issue, as the
163 <systemitem class="username">root</systemitem> user:
164 </para>
165
166<screen role="root"
167 remap="test"><userinput>LC_ALL=en_US.UTF-8 make check_local</userinput></screen>
168
169 <para>
170 Some tests may hang. In this case they can be skipped by adding
171 <command>S=&lt;testname&gt;</command> to the <command>make</command>
172 command.
173 Other targets are available and can be listed with
174 <command>make -C test help</command>. The test timings are very dependent
175 on the speed of the disk(s), and on the number of enabled kernel options.
176 </para>
177
178 <!-- Results for LVM2.2.02.176:
179 ### 292 tests: 177 passed, 46 skipped, 0 timed out, 60 warned, 9 failed
180
181 Results for LVM2.2.03.01:
182 ### 302 tests: 182 passed, 43 skipped, 0 timed out, 62 warned, 15 failed
183
184 Results for LVM2.2.03.05:
185 ### 326 tests: 255 passed, 58 skipped, 0 timed out, 2 warned, 11 failed
186
187 Results for LVM2.2.03.09:
188 ### 338 tests: 212 passed, 41 skipped, 0 timed out, 70 warned, 15 failed
189
190 Results for LVM2.2.03.11:
191 ### 357 tests: 231 passed, 32 skipped, 0 timed out, 77 warned, 17 failed
192
193 Results for LVM2.2.03.14:
194 ### 389 tests: 304 passed, 73 skipped, 0 timed out, 2 warned, 10 failed
195
196 Results for LVM2.2.03.16:
197 ### 395 tests: 241 passed, 145 skipped, 0 timed out, 1 warned, 8 failed
198
199 Results for LVM2.2.03.17:
200 ### 403 tests: 333 passed, 61 skipped, 0 timed out, 3 warned, 6 failed
201
202 Results for LVM2.2.03.20 [pierre]:
203 ### 407 tests: 324 passed, 75 skipped, 0 timed out, 3 warned, 5 failed
204 -->
205
206 <para>
207 The tests do not implement the <quote>expected fail</quote> possibility,
208 and a small number of test failures is expected by upstream.
209 <!-- 1 -->More failures may happen because some kernel options are missing.
210 For example, the lack of the <emphasis>dm-delay</emphasis> device
211 mapper target explains some failures.
212 <!-- 2 -->Some tests may fail if there is insufficient free space available
213 in the partition with the /tmp directory. At least one test fails if 16 TB
214 is not available.
215 <!-- 3 -->Some tests are flagged <quote>warned</quote> if
216 <ulink url='https://github.com/jthornber/thin-provisioning-tools'>
217 thin-provisioning-tools</ulink> are not installed. A workaround is to
218 add the following flags to <command>configure</command>:
219 </para>
220
221<screen role="nodump"><userinput> --with-thin-check= \
222 --with-thin-dump= \
223 --with-thin-repair= \
224 --with-thin-restore= \
225 --with-cache-check= \
226 --with-cache-dump= \
227 --with-cache-repair= \
228 --with-cache-restore= \</userinput></screen>
229
230 <para>
231 Some tests may hang. They can be removed if necessary, for example:
232 <command>rm test/shell/lvconvert-raid-reshape.sh</command>. The tests
233 generate a lot of kernel messages, which may clutter your terminal. You
234 can disable them by issuing <command>dmesg -D</command> before running
235 the tests (do not forget to issue <command>dmesg -E</command> when tests
236 are done).
237
238 <note><simpara>The checks create device nodes in the /tmp directory. The
239 tests will fail if /tmp is mounted with the nodev option.
240 </simpara></note>
241 </para>
242
243 <para>
244 Now, as the <systemitem class="username">root</systemitem> user:
245 </para>
246
247<screen role="root" revision="sysv"><userinput>make install
248rm -fv /usr/lib/udev/rules.d/69-dm-lvm.rules</userinput></screen>
249
250<screen role="root" revision="systemd"><userinput>make install
251make install_systemd_units</userinput></screen>
252
253 </sect2>
254
255 <sect2 role="commands">
256 <title>Command Explanations</title>
257
258 <para>
259 <command>PATH+=:/usr/sbin</command>: The path
260 must contain
261 <filename class='directory'>/usr/sbin</filename> for proper system tool
262 detection by the <command>configure</command> script. This instruction
263 ensures that PATH is properly set even if you build as an unprivileged user.
264 </para>
265
266 <para>
267 <parameter>--enable-cmdlib</parameter>: This switch enables
268 building of the shared command library. It is required
269 when building the event daemon.
270 </para>
271
272 <para>
273 <parameter>--enable-pkgconfig</parameter>: This switch enables
274 installation of <command>pkg-config</command> support files.
275 </para>
276
277 <para>
278 <parameter>--enable-udev_sync</parameter>: This switch enables
279 synchronisation with <application>Udev</application> processing.
280 </para>
281
282 <para>
283 <option>--enable-dmeventd</option>: This switch enables
284 building of the <application>Device Mapper</application>
285 event daemon.
286 </para>
287
288 <para revision="sysv">
289 <command>rm .../69-dm-lvm.rules</command>: Under certain circumstances,
290 this udev rule calls <command>systemd-run</command>, which is not
291 available on sysv. It performs actions that are done by another boot
292 script anyway, so it is not needed.
293 </para>
294
295 <para revision="systemd">
296 <command>make install_systemd_units</command>: This is needed to install
297 a unit that activates logical volumes at boot. It is not installed
298 by default.
299 </para>
300
301 </sect2>
302
303 <sect2 role="configuration" revision="systemd">
304 <title>Configuring LVM2</title>
305
306 <sect3 id="lvm2-config">
307 <title>Config File</title>
308 <para>
309 <filename>/etc/lvm/lvm.conf</filename>
310 </para>
311
312 <indexterm zone="lvm2 lvm2-config">
313 <primary
314 sortas="e-etc-lvm-lvm.conf">/etc/lvm/lvm.conf</primary>
315 </indexterm>
316 </sect3>
317
318 <sect3><title>Configuration Information</title>
319 <para>
320 The default configuration still references the obsolete <filename
321 class="directory">/var/lock</filename> directory. This creates
322 a deadlock at boot time. Change this (as the <systemitem
323 class="username">root</systemitem> user):
324 </para>
325
326<screen role="root"><userinput>sed -e '/locking_dir =/{s/#//;s/var/run/}' \
327 -i /etc/lvm/lvm.conf</userinput></screen>
328
329 </sect3>
330 </sect2>
331
332 <sect2 role="content">
333 <title>Contents</title>
334
335 <segmentedlist>
336 <segtitle>Installed Programs</segtitle>
337 <segtitle>Installed Libraries</segtitle>
338 <segtitle>Installed Directories</segtitle>
339
340 <seglistitem>
341 <seg>
342 blkdeactivate, dmeventd (optional), dmsetup, fsadm, lvm, lvmdump,
343 and lvm_import_vdo.
344 There are also numerous symbolic links to lvm that implement specific
345 functionalities
346 </seg>
347 <seg>
348 libdevmapper.so and liblvm2cmd.so; optional:
349 libdevmapper-event.so, libdevmapper-event-lvm2.so,
350 libdevmapper-event-lvm2mirror.so, libdevmapper-event-lvm2raid.so,
351 libdevmapper-event-lvm2snapshot.so, libdevmapper-event-lvm2thin.so,
352 and libdevmapper-event-lvm2vdo.so
353 </seg>
354 <seg>
355 /etc/lvm and
356 /usr/lib/device-mapper (optional)
357 </seg>
358 </seglistitem>
359 </segmentedlist>
360
361 <variablelist>
362 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
363 <?dbfo list-presentation="list"?>
364
365 <?dbhtml list-presentation="table"?>
366
367 <varlistentry id="blkdeactivate">
368 <term><command>blkdeactivate</command></term>
369 <listitem>
370 <para>
371 is a utility to deactivate block devices
372 </para>
373 <indexterm zone="lvm2 blkdeactivate">
374 <primary sortas="b-blkdeactivate">blkdeactivate</primary>
375 </indexterm>
376 </listitem>
377 </varlistentry>
378
379 <varlistentry id="dmeventd">
380 <term><command>dmeventd</command></term>
381 <listitem>
382 <para>
383 (optional) is the Device Mapper event daemon
384 </para>
385 <indexterm zone="lvm2 dmeventd">
386 <primary sortas="b-dmeventd">dmeventd</primary>
387 </indexterm>
388 </listitem>
389 </varlistentry>
390
391 <varlistentry id="dmsetup">
392 <term><command>dmsetup</command></term>
393 <listitem>
394 <para>
395 is a low level logical volume management tool
396 </para>
397 <indexterm zone="lvm2 dmsetup">
398 <primary sortas="b-dmsetup">dmsetup</primary>
399 </indexterm>
400 </listitem>
401 </varlistentry>
402
403 <varlistentry id="fsadm">
404 <term><command>fsadm</command></term>
405 <listitem>
406 <para>
407 is a utility used to resize or check filesystem on a device
408 </para>
409 <indexterm zone="lvm2 fsadm">
410 <primary sortas="b-fsadm">fsadm</primary>
411 </indexterm>
412 </listitem>
413 </varlistentry>
414
415 <varlistentry id="lvm">
416 <term><command>lvm</command></term>
417 <listitem>
418 <para>
419 provides the command-line tools for <application>LVM2</application>.
420 Commands are implemented via symbolic links to this program to
421 manage physical devices (pv*), volume groups (vg*) and logical
422 volumes (lv*)
423 </para>
424 <indexterm zone="lvm2 lvm">
425 <primary sortas="b-lvm">lvm</primary>
426 </indexterm>
427 </listitem>
428 </varlistentry>
429
430 <!--
431 <varlistentry id="lvmconf">
432 <term><command>lvmconf</command></term>
433 <listitem>
434 <para>
435 is a script that modifies the locking configuration in
436 the <application>LVM2</application> configuration file.
437 </para>
438 <indexterm zone="lvm2 lvmconf">
439 <primary sortas="b-lvmconf">lvmconf</primary>
440 </indexterm>
441 </listitem>
442 </varlistentry>
443 -->
444
445 <varlistentry id="lvmdump">
446 <term><command>lvmdump</command></term>
447 <listitem>
448 <para>
449 is a tool used to dump various information concerning
450 <application>LVM2</application>
451 </para>
452 <indexterm zone="lvm2 lvmdump">
453 <primary sortas="b-lvmdump">lvmdump</primary>
454 </indexterm>
455 </listitem>
456 </varlistentry>
457
458 <varlistentry id="vgimportclone">
459 <term><command>vgimportclone</command></term>
460 <listitem>
461 <para>
462 is used to import a duplicated VG (e.g. hardware snapshot)
463 </para>
464 <indexterm zone="lvm2 vgimportclone">
465 <primary sortas="b-vgimportclone">vgimportclone</primary>
466 </indexterm>
467 </listitem>
468 </varlistentry>
469
470 <varlistentry id="libdevmapper">
471 <term><filename class="libraryfile">libdevmapper.so</filename></term>
472 <listitem>
473 <para>
474 contains the <application>Device Mapper</application> API
475 functions
476 </para>
477 <indexterm zone="lvm2 libdevmapper">
478 <primary sortas="c-libdevmapper">libdevmapper.so</primary>
479 </indexterm>
480 </listitem>
481 </varlistentry>
482
483 </variablelist>
484
485 </sect2>
486
487</sect1>
Note: See TracBrowser for help on using the repository browser.