source: postlfs/filesystems/btrfs-progs.xml@ 5a80bacd

12.2 gimp3 lazarus trunk xry111/for-12.3 xry111/spidermonkey128
Last change on this file since 5a80bacd was 227ecfb, checked in by Bruce Dubbs <bdubbs@…>, 3 months ago

Update to btrfs-progs-v6.9.
  • Property mode set to 100644
File size: 13.0 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 btrfs-progs-download-http "&kernel-dl;/linux/kernel/people/kdave/btrfs-progs/btrfs-progs-v&btrfs-progs-version;.tar.xz">
8 <!ENTITY btrfs-progs-download-ftp " ">
9 <!ENTITY btrfs-progs-md5sum "0eacc7c73c4f086fa10e4bb2fd3f6739">
10 <!ENTITY btrfs-progs-size "2.5 MB">
11 <!ENTITY btrfs-progs-buildsize "65 MB (transient files created during tests need up to 10 GB)">
12 <!ENTITY btrfs-progs-time "0.3 SBU (with parallelism=4; add 3.6 SBU for tests, up to 14 SBU on slow disks)">
13]>
14
15<sect1 id="btrfs-progs" xreflabel="btrfs-progs-&btrfs-progs-version;">
16 <?dbhtml filename="btrfs-progs.html"?>
17
18
19 <title>btrfs-progs-&btrfs-progs-version;</title>
20
21 <indexterm zone="btrfs-progs">
22 <primary sortas="a-btrfs-progs">btrfs-progs</primary>
23 </indexterm>
24
25 <sect2 role="package">
26 <title>Introduction to btrfs-progs</title>
27
28 <para>
29 The <application>btrfs-progs</application> package contains
30 administration and debugging tools for the B-tree file system (btrfs).
31 </para>
32
33 &lfs121_checked;
34
35 <bridgehead renderas="sect3">Package Information</bridgehead>
36 <itemizedlist spacing="compact">
37 <listitem>
38 <para>
39 Download (HTTP): <ulink url="&btrfs-progs-download-http;"/>
40 </para>
41 </listitem>
42 <listitem>
43 <para>
44 Download (FTP): <ulink url="&btrfs-progs-download-ftp;"/>
45 </para>
46 </listitem>
47 <listitem>
48 <para>
49 Download MD5 sum: &btrfs-progs-md5sum;
50 </para>
51 </listitem>
52 <listitem>
53 <para>
54 Download size: &btrfs-progs-size;
55 </para>
56 </listitem>
57 <listitem>
58 <para>
59 Estimated disk space required: &btrfs-progs-buildsize;
60 </para>
61 </listitem>
62 <listitem>
63 <para>
64 Estimated build time: &btrfs-progs-time;
65 </para>
66 </listitem>
67 </itemizedlist>
68<!--
69<bridgehead renderas="sect3">Additional Downloads</bridgehead>
70 <itemizedlist spacing="compact">
71 <listitem>
72 <para>
73 Required patch if building with linux kernel headers version
74 before 5.12:
75 <ulink url="&patch-root;/btrfs-progs-&btrfs-progs-version;-headers_fix-1.patch"/>
76 </para>
77 </listitem>
78 </itemizedlist>
79-->
80 <bridgehead renderas="sect3">Btrfs-progs Dependencies</bridgehead>
81
82 <bridgehead renderas="sect4">Required</bridgehead>
83 <para role="required">
84 <xref linkend="lzo"/>
85 </para>
86 <!-- In v6.2.1 (and maybe previous), sphinx is required for the doc
87 <bridgehead renderas="sect4">Recommended</bridgehead>
88 <para role="recommended">
89 <xref linkend="asciidoc"/> (or <xref role="nodep" linkend="asciidoctor"/>)
90 and <xref linkend="xmlto"/> (both required to generate man pages)
91 </para>
92 -->
93 <bridgehead renderas="sect4">Optional</bridgehead>
94 <para role="optional">
95 <xref linkend="lvm2"/> (<command>dmsetup</command> is used in tests),
96 <xref linkend="sphinx"/> and <xref linkend="sphinx_rtd_theme"/>
97 (required to build documentation), and
98 <ulink
99 url='https://mirrors.edge.kernel.org/pub/linux/kernel/people/jeffm/reiserfsprogs/'>
100 reiserfsprogs</ulink> (for tests).
101
102 </para>
103
104
105 </sect2>
106
107 <sect2 role="kernel" id="btrfs-progs-kernel">
108 <title>Kernel Configuration</title>
109
110 <para>
111 Enable the following option in the kernel configuration
112 and recompile the kernel:
113 </para>
114
115 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
116 href="btrfs-progs-kernel.xml"/>
117
118 <para>
119 In addition to the above and to the options required for
120 <xref linkend="lvm2"/>, the following
121 options must be set for running tests. The options marked
122 as empty should <emphasis>not</emphasis> be selected because they
123 are for developers and make some tests fail.
124 </para>
125
126 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
127 href="btrfs-progs-test-kernel.xml"/>
128
129 <indexterm zone="btrfs-progs btrfs-progs-kernel">
130 <primary sortas="d-btrfs-progs">BTRFS Programs</primary>
131 </indexterm>
132
133 </sect2>
134
135 <sect2 role="installation">
136 <title>Installation of btrfs-progs</title>
137
138 <para>
139 Install <application>btrfs-progs</application> by running the following
140 commands:
141 </para>
142
143<screen><userinput>./configure --prefix=/usr \
144 --disable-static \
145 --disable-documentation &amp;&amp;
146make</userinput></screen>
147
148 <note>
149 <para>
150 Some tests require grep built with perl regular expressions. To
151 obtain this, rebuild grep with the LFS Chapter 8 instructions after
152 installing <xref linkend="pcre2"/>.
153 </para>
154 </note>
155<!-- Keeping this for now, but it seems that calling "make test" is
156 simpler and does the same thing -->
157 <para>
158 Before running tests, build a support program:
159 </para>
160
161<screen remap="test"><userinput>make fssum</userinput></screen>
162
163 <para>
164 First, fix one test and disable another that is known to fail:
165 </para>
166
167<screen role="root" remap="test"><userinput>sed -i 's/ mount/&amp; -o nodiscard/' tests/misc-tests/004-shrink-fs/test.sh &amp;&amp;
168mv tests/misc-tests/041-subvolume-delete-during-send/test.sh \
169 tests/misc-tests/041-subvolume-delete-during-send/test.sh.skip</userinput></screen>
170
171 <para>
172 To test the results, issue (as the &root; user):
173 </para>
174
175<screen role="root" remap="test"><userinput>pushd tests
176 ./fsck-tests.sh
177 ./mkfs-tests.sh
178 ./cli-tests.sh
179 ./convert-tests.sh
180 ./misc-tests.sh
181 ./fuzz-tests.sh
182popd</userinput></screen>
183
184<!-- Template for failed test removal:
185 the other ones to run:
186 </para>
187
188<screen remap="test"><userinput>mv tests/fsck-tests/012-leaf-corruption/test.sh{,.broken}</userinput></screen>
189Substitute your test failure with the one above.
190 <para>
191 To test the results, run (as the
192 <systemitem class="username">root</systemitem> user):
193 </para>
194
195<screen role="root" remap="test"><userinput>make -j1 -k test</userinput></screen>
196-->
197 <note>
198 <para>
199 If the above mentioned kernel options are not enabled, some tests
200 fail, and prevent all the remaining tests from running because the test
201 disk image is not cleanly unmounted. Also make sure that the btrfs
202 kernel module is loaded.
203 </para>
204 </note>
205
206<!-- 6.8.1 - all tests went pretty fine, including the previously commented
207 convert-tests and the other two mentioned tests.
208 <para>
209 The convert-tests scripts are known to fail.
210 Tests 004-shrink-fs and 062-fi-show-raw-dm-all-devices in the misc-tests
211 are known to fail.
212 </para>
213-->
214 <para>
215 Install the package as the &root; user:
216 </para>
217
218<screen role="root"><userinput>make install</userinput></screen>
219
220 <para>
221 If you have passed <parameter>--disable-documentation</parameter> to
222 <command>configure</command> and you need the manual pages, install them
223 by running, as the &root; user:
224 </para>
225
226<screen role="root"><userinput>for i in 5 8; do
227 install Documentation/*.$i /usr/share/man/man$i
228done</userinput></screen>
229
230 </sect2>
231
232 <sect2 role="commands">
233 <title>Command Explanations</title>
234
235 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
236 href="../../xincludes/static-libraries.xml"/>
237
238 <para>
239 <parameter>--disable-documentation</parameter>: This switch
240 disables rebuilding the manual pages, because it requires
241 <xref linkend="sphinx"/>.
242 </para>
243<!--
244 <para>
245 <command>sed 's/,orphan_file//" ...</command>: In this version of
246 <application>btrfs-progs</application>, the
247 <command>btrfs-convert</command> program produces a btrfs filesystem
248 containing errors if converting from an ext4 filesystem created
249 with the <quote>orphan_file</quote> feature. This command creates
250 a custom configuration file that prevents creating a filesystem
251 with this feature.
252 </para>
253-->
254 <!--
255 <para>
256 <command>ln -s ... /usr/lib/libbtrfs.so</command>: Creates a
257 symbolic link in the directory where it is expected.
258 </para>
259
260 <para>
261 <command>rm /lib/libbtrfs.{a,so}</command>: Removes unneeded
262 library entries.
263 </para>
264-->
265 </sect2>
266<!--
267 <sect2 role="using" id="using-btrfs-convert">
268 <title>Using the btrfs-convert Program</title>
269
270 <para>
271 This version of <application>btrfs-progs</application> does not convert
272 correctly ext4 filesystems to btrfs if the ext4
273 <option>orphan_file</option> feature is turned on. If you happen to
274 convert such a filesystem, you need to first run:
275 </para>
276
277<screen role="nodump"><userinput>tune2fs -O ^orphan_file <replaceable>/dev/sdxx</replaceable></userinput></screen>
278
279 <para>
280 where <filename>/dev/sdxx</filename> is the partition of the filesystem
281 you want to convert.
282 </para>
283 </sect2>
284-->
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 btrfs,
297 btrfs-convert,
298 btrfs-find-root,
299 btrfs-image,
300 btrfs-map-logical,
301 btrfs-select-super,
302 btrfsck (link to btrfs),
303 btrfstune,
304 fsck.btrfs, and
305 mkfs.btrfs
306 </seg>
307
308 <seg>
309 libbtrfs.so and
310 libbtrfsutil.so
311 </seg>
312
313 <seg>/usr/include/btrfs</seg>
314 </seglistitem>
315 </segmentedlist>
316
317 <variablelist>
318 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
319 <?dbfo list-presentation="list"?>
320 <?dbhtml list-presentation="table"?>
321
322 <varlistentry id="btrfs-prog">
323 <term><command>btrfs</command></term>
324 <listitem>
325 <para>
326 is the main interface into btrfs filesystem operations
327 </para>
328 <indexterm zone="btrfs-progs btrfs-prog">
329 <primary sortas="b-btrfs">btrfs</primary>
330 </indexterm>
331 </listitem>
332 </varlistentry>
333
334 <varlistentry id="btrfs-convert">
335 <term><command>btrfs-convert</command></term>
336 <listitem>
337 <para>
338 converts from an ext2/3/4 or reiserfs filesystem to btrfs <!--(see
339 <xref linkend="using-btrfs-convert"/> above)-->
340 </para>
341 <indexterm zone="btrfs-progs btrfs-convert">
342 <primary sortas="b-btrfs-convert">btrfs-convert</primary>
343 </indexterm>
344 </listitem>
345 </varlistentry>
346
347 <varlistentry id="btrfs-find-root">
348 <term><command>btrfs-find-root</command></term>
349 <listitem>
350 <para>
351 is a filter to find btrfs root
352 </para>
353 <indexterm zone="btrfs-progs btrfs-find-root">
354 <primary sortas="b-btrfs-find-root">btrfs-find-root</primary>
355 </indexterm>
356 </listitem>
357 </varlistentry>
358
359 <varlistentry id="btrfs-map-logical">
360 <term><command>btrfs-map-logical</command></term>
361 <listitem>
362 <para>
363 maps btrfs logical extent to physical extent
364 </para>
365 <indexterm zone="btrfs-progs btrfs-map-logical">
366 <primary sortas="b-btrfs-map-logical">btrfs-map-logical</primary>
367 </indexterm>
368 </listitem>
369 </varlistentry>
370
371 <varlistentry id="btrfs-select-super">
372 <term><command>btrfs-select-super</command></term>
373 <listitem>
374 <para>
375 overwrites the primary superblock with a backup copy
376 </para>
377 <indexterm zone="btrfs-progs btrfs-select-super">
378 <primary sortas="b-btrfs-select-super">btrfs-select-super</primary>
379 </indexterm>
380 </listitem>
381 </varlistentry>
382
383 <varlistentry id="btrfstune">
384 <term><command>btrfstune</command></term>
385 <listitem>
386 <para>
387 tunes various filesystem parameters
388 </para>
389 <indexterm zone="btrfs-progs btrfstune">
390 <primary sortas="b-btrfstune">btrfstune</primary>
391 </indexterm>
392 </listitem>
393 </varlistentry>
394
395 <varlistentry id="fsck.btrfs">
396 <term><command>fsck.btrfs</command></term>
397 <listitem>
398 <para>
399 does nothing, but is present for consistency with fstab
400 </para>
401 <indexterm zone="btrfs-progs fsck.btrfs">
402 <primary sortas="b-fsck.btrfs">fsck.btrfs</primary>
403 </indexterm>
404 </listitem>
405 </varlistentry>
406
407 <varlistentry id="mkfs.btrfs">
408 <term><command>mkfs.btrfs</command></term>
409 <listitem>
410 <para>
411 creates a btrfs file system
412 </para>
413 <indexterm zone="btrfs-progs mkfs.btrfs">
414 <primary sortas="b-mkfs.btrfs">mkfs.btrfs</primary>
415 </indexterm>
416 </listitem>
417 </varlistentry>
418
419 </variablelist>
420
421 </sect2>
422
423</sect1>
Note: See TracBrowser for help on using the repository browser.