source: postlfs/filesystems/lvm2.xml@ 756f4609

12.0 12.1 kea ken/TL2024 ken/tuningfonts lazarus lxqt plabs/newcss python3.11 qt5new rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18 xry111/xf86-video-removal
Last change on this file since 756f4609 was 756f4609, checked in by Bruce Dubbs <bdubbs@…>, 14 months ago

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