source: postlfs/filesystems/lvm2.xml@ 213d18c

11.3 12.0 12.1 kea ken/TL2024 ken/inkscape-core-mods ken/tuningfonts lazarus lxqt plabs/newcss plabs/python-mods python3.11 qt5new rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18 xry111/xf86-video-removal
Last change on this file since 213d18c was 213d18c, checked in by Pierre Labastie <pierre.labastie@…>, 18 months ago

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