source: postlfs/filesystems/lvm2.xml@ f39cf0d0

10.1 11.0 11.1 lazarus qt5new trunk upgradedb xry111/intltool xry111/test-20220226
Last change on this file since f39cf0d0 was f39cf0d0, checked in by Ken Moffat <ken@…>, 18 months ago

Kernel config changes suggested by rhubarbpieguy

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@23948 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 14.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 "ffce8d4e86c74d8d44098a530410e843">
10 <!ENTITY lvm2-size "2.4 MB">
11 <!ENTITY lvm2-buildsize "34 MB (add 22 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 transcient. I monitor /tmp with a loop during
14 tests. -pierre, August 2020 -->
15 <!ENTITY lvm2-time "0.2 SBU (using parallelism=4; add 16 to 45 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 <othername>$LastChangedBy$</othername>
23 <date>$Date$</date>
24 </sect1info>
25
26 <title>LVM2-&lvm2-version;</title>
27
28 <indexterm zone="lvm2">
29 <primary sortas="a-LVM2">LVM2</primary>
30 </indexterm>
31
32 <sect2 role="package">
33 <title>Introduction to LVM2</title>
34
35 <para>
36 The <application>LVM2</application> package is a set of tools that manage
37 logical partitions. It allows spanning of file systems across multiple
38 physical disks and disk partitions and provides for dynamic growing or
39 shrinking of logical partitions, mirroring and low storage footprint
40 snapshots.
41 </para>
42
43 &lfs10_checked;
44
45 <bridgehead renderas="sect3">Package Information</bridgehead>
46 <itemizedlist spacing="compact">
47 <listitem>
48 <para>
49 Download (HTTP): <ulink url="&lvm2-download-http;"/>
50 </para>
51 </listitem>
52 <listitem>
53 <para>
54 Download (FTP): <ulink url="&lvm2-download-ftp;"/>
55 </para>
56 </listitem>
57 <listitem>
58 <para>
59 Download MD5 sum: &lvm2-md5sum;
60 </para>
61 </listitem>
62 <listitem>
63 <para>
64 Download size: &lvm2-size;
65 </para>
66 </listitem>
67 <listitem>
68 <para>
69 Estimated disk space required: &lvm2-buildsize;
70 </para>
71 </listitem>
72 <listitem>
73 <para>
74 Estimated build time: &lvm2-time;
75 </para>
76 </listitem>
77 </itemizedlist>
78
79 <bridgehead renderas="sect3">LVM2 Dependencies</bridgehead>
80
81 <bridgehead renderas="sect4">Required</bridgehead>
82 <para role="required">
83 <xref linkend='libaio'/>
84 </para>
85
86 <bridgehead renderas="sect4">Optional</bridgehead>
87 <para role="optional">
88 <xref linkend='mdadm'/>,
89 <xref linkend='reiserfs'/>,
90 <xref linkend='valgrind'/>,
91 <xref linkend='which'/>,
92 <xref linkend='xfsprogs'/> (all five may be used, but are not required,
93 for tests), and
94 <ulink url='https://github.com/jthornber/thin-provisioning-tools'>
95 thin-provisioning-tools</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; Mirror target [CONFIG_DM_MIRROR]
126Kernel hacking ---&gt;
127 Generic Kernel Debugging Instruments ---&gt;
128 [*] Magic SysRq key [CONFIG_MAGIC_SYSRQ]</literal></screen>
129
130 <indexterm zone="lvm2 lvm2-kernel">
131 <primary sortas="d-lvm2">lvm2</primary>
132 </indexterm>
133
134 </sect2>
135
136 <sect2 role="installation">
137 <title>Installation of LVM2</title>
138
139 <para>
140 Install <application>LVM2</application> by running the following
141 commands:
142 </para>
143
144<screen><userinput>SAVEPATH=$PATH &amp;&amp;
145PATH=$PATH:/sbin:/usr/sbin &amp;&amp;
146./configure --prefix=/usr \
147 --exec-prefix= \
148 --enable-cmdlib \
149 --enable-pkgconfig \
150 --enable-udev_sync &amp;&amp;
151make &amp;&amp;
152PATH=$SAVEPATH &amp;&amp;
153unset SAVEPATH</userinput></screen>
154
155 <para>
156 The tests use <application>udev</application> for logical volume
157 synchronization, so the LVM udev rules and some utilities need to
158 be installed before running the tests. If you are installing
159 <application>LVM2</application> for the first time, and do not
160 want to install the full package before running the tests, the minimal
161 set of utilities can be installed by running the following instructions
162 as the <systemitem class="username">root</systemitem> user:
163 </para>
164
165<screen role="root"
166 remap="test"><userinput>make -C tools install_tools_dynamic &amp;&amp;
167make -C udev install &amp;&amp;
168make -C libdm install</userinput></screen>
169
170 <para>
171 To test the results, issue, as the
172 <systemitem class="username">root</systemitem> user:
173 </para>
174
175<screen role="root"
176 remap="test"><userinput>make S=shell/thin-flags.sh check_local</userinput></screen>
177
178 <para>
179 The <command>S=...</command> option allows to skip tests. The
180 <command>shell/thin-flags.sh</command> test has been reported to freeze
181 the computer.
182 Other targets are available and can be listed with
183 <command>make -C test help</command>. The test timings are very dependent
184 on the speed of the disk(s), and on the number of enabled kernel options.
185 </para>
186
187 <!-- Results for LVM2.2.02.176:
188 ### 292 tests: 177 passed, 46 skipped, 0 timed out, 60 warned, 9 failed
189
190 Results for LVM2.2.03.01:
191 ### 302 tests: 182 passed, 43 skipped, 0 timed out, 62 warned, 15 failed
192
193 Results for LVM2.2.03.05:
194 ### 326 tests: 255 passed, 58 skipped, 0 timed out, 2 warned, 11 failed
195
196 Results for LVM2.2.03.09:
197 ### 338 tests: 212 passed, 41 skipped, 0 timed out, 70 warned, 15 failed
198 -->
199
200 <para>
201 The tests do not implement the <quote>expected fail</quote> possibility,
202 and a small number of test failures is expected by upstream. More
203 failures may happen because some kernel options are missing. For example,
204 the lack of the <emphasis>dm-delay</emphasis> device mapper target may
205 explain some failures. Some tests are flagged
206 <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
231 option.</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</userinput></screen>
239
240<screen role="root" revision="systemd"><userinput>make install
241make install_systemd_units</userinput></screen>
242
243 </sect2>
244
245 <sect2 role="commands">
246 <title>Command Explanations</title>
247
248 <para>
249 <command>PATH=$PATH:/sbin:/usr/sbin</command>: The path
250 must contain <filename class="directory">/sbin</filename> and
251 <filename class='directory'>/usr/sbin</filename> for proper system tool
252 detection by the <command>configure</command> script. This instruction
253 ensures that PATH is properly set even if you build as an unprivileged user.
254 </para>
255
256 <para>
257 <parameter>--enable-cmdlib</parameter>: This switch enables
258 building of the shared command library. It is required
259 when building the event daemon.
260 </para>
261
262 <para>
263 <parameter>--enable-pkgconfig</parameter>: This switch enables
264 installation of <command>pkg-config</command> support files.
265 </para>
266
267 <para>
268 <parameter>--enable-udev_sync</parameter>: This switch enables
269 synchronisation with <application>Udev</application> processing.
270 </para>
271
272 <para>
273 <option>--enable-dmeventd</option>: This switch enables
274 building of the <application>Device Mapper</application>
275 event daemon.
276 </para>
277
278 <para revision="systemd">
279 <command>make install_systemd_units</command>: This is needed to install
280 a unit that activates logical volumes at boot. It is not installed
281 by default.
282 </para>
283
284 </sect2>
285
286 <sect2 role="content">
287 <title>Contents</title>
288
289 <segmentedlist>
290 <segtitle>Installed Programs</segtitle>
291 <segtitle>Installed Libraries</segtitle>
292 <segtitle>Installed Directories</segtitle>
293
294 <seglistitem>
295 <seg>
296 blkdeactivate, dmeventd (optional), dmsetup, fsadm, lvm, and lvmdump.
297 There are also numerous symbolic links to lvm that implement specific
298 functionalities
299 </seg>
300 <seg>
301 libdevmapper.so and liblvm2cmd.so; optional:
302 libdevmapper-event.so, libdevmapper-event-lvm2.so,
303 libdevmapper-event-lvm2mirror.so, libdevmapper-event-lvm2raid.so,
304 libdevmapper-event-lvm2snapshot.so, and libdevmapper-event-lvm2thin.so
305 </seg>
306 <seg>
307 /etc/lvm and
308 /lib/device-mapper (optional)
309 </seg>
310 </seglistitem>
311 </segmentedlist>
312
313 <variablelist>
314 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
315 <?dbfo list-presentation="list"?>
316
317 <?dbhtml list-presentation="table"?>
318
319 <varlistentry id="blkdeactivate">
320 <term><command>blkdeactivate</command></term>
321 <listitem>
322 <para>
323 is a utility to deactivate block devices.
324 </para>
325 <indexterm zone="lvm2 blkdeactivate">
326 <primary sortas="b-blkdeactivate">blkdeactivate</primary>
327 </indexterm>
328 </listitem>
329 </varlistentry>
330
331 <varlistentry id="dmeventd">
332 <term><command>dmeventd</command></term>
333 <listitem>
334 <para>
335 (optional) is the Device Mapper event daemon.
336 </para>
337 <indexterm zone="lvm2 dmeventd">
338 <primary sortas="b-dmeventd">dmeventd</primary>
339 </indexterm>
340 </listitem>
341 </varlistentry>
342
343 <varlistentry id="dmsetup">
344 <term><command>dmsetup</command></term>
345 <listitem>
346 <para>
347 is a low level logical volume management tool.
348 </para>
349 <indexterm zone="lvm2 dmsetup">
350 <primary sortas="b-dmsetup">dmsetup</primary>
351 </indexterm>
352 </listitem>
353 </varlistentry>
354
355 <varlistentry id="fsadm">
356 <term><command>fsadm</command></term>
357 <listitem>
358 <para>
359 is a utility used to resize or check filesystem on a device.
360 </para>
361 <indexterm zone="lvm2 fsadm">
362 <primary sortas="b-fsadm">fsadm</primary>
363 </indexterm>
364 </listitem>
365 </varlistentry>
366
367 <varlistentry id="lvm">
368 <term><command>lvm</command></term>
369 <listitem>
370 <para>
371 provides the command-line tools for <application>LVM2</application>.
372 Commands are implemented via sympolic links to this program to
373 manage physical devices (pv*), volume groups (vg*) and logical
374 volumes (lv*).
375 </para>
376 <indexterm zone="lvm2 lvm">
377 <primary sortas="b-lvm">lvm</primary>
378 </indexterm>
379 </listitem>
380 </varlistentry>
381
382 <!--
383 <varlistentry id="lvmconf">
384 <term><command>lvmconf</command></term>
385 <listitem>
386 <para>
387 is a script that modifies the locking configuration in
388 the <application>LVM2</application> configuration file.
389 </para>
390 <indexterm zone="lvm2 lvmconf">
391 <primary sortas="b-lvmconf">lvmconf</primary>
392 </indexterm>
393 </listitem>
394 </varlistentry>
395 -->
396
397 <varlistentry id="lvmdump">
398 <term><command>lvmdump</command></term>
399 <listitem>
400 <para>
401 is a tool used to dump various information concerning
402 <application>LVM2</application>.
403 </para>
404 <indexterm zone="lvm2 lvmdump">
405 <primary sortas="b-lvmdump">lvmdump</primary>
406 </indexterm>
407 </listitem>
408 </varlistentry>
409
410 <varlistentry id="vgimportclone">
411 <term><command>vgimportclone</command></term>
412 <listitem>
413 <para>
414 is used to import a duplicated VG (e.g. hardware snapshot).
415 </para>
416 <indexterm zone="lvm2 vgimportclone">
417 <primary sortas="b-vgimportclone">vgimportclone</primary>
418 </indexterm>
419 </listitem>
420 </varlistentry>
421
422 <varlistentry id="libdevmapper">
423 <term><filename class='libraryfile'>libdevmapper.so</filename></term>
424 <listitem>
425 <para>
426 contains the <application>Device Mapper</application> API
427 functions.
428 </para>
429 <indexterm zone="lvm2 libdevmapper">
430 <primary sortas="c-libdevmapper">libdevmapper.so</primary>
431 </indexterm>
432 </listitem>
433 </varlistentry>
434
435 </variablelist>
436
437 </sect2>
438
439</sect1>
Note: See TracBrowser for help on using the repository browser.