source: postlfs/filesystems/lvm2.xml@ 04d189b

12.0 12.1 ken/TL2024 ken/tuningfonts lazarus plabs/newcss python3.11 rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18
Last change on this file since 04d189b was d67d543, checked in by Xi Ruoyao <xry111@…>, 11 months ago

filesystems: Convert the remaining kernel configurations to use new rendering

I don't know these FS very well so I did not change things, except:

  • "SCSI_LOW_LEVEL" should be "SCSI_LOWLEVEL" (without the "_" between "LOW" and "LEVEL").
  • RAID append mode is deprecated, so I removed it.

And I've fixed some issues in kernel-config.py as well.

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