source: postlfs/filesystems/btrfs-progs.xml@ 034bcb11

12.2 gimp3 lazarus trunk xry111/for-12.3 xry111/spidermonkey128
Last change on this file since 034bcb11 was 341a3cf, checked in by Bruce Dubbs <bdubbs@…>, 3 months ago

Update to btrfs-progs-v6.9.2.
  • Property mode set to 100644
File size: 12.9 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 "819822379bf196178bb17484fcceeab7">
10 <!ENTITY btrfs-progs-size "2.5 MB">
11 <!ENTITY btrfs-progs-buildsize "64 MB (transient files created during tests need up to 10 GB)">
12 <!ENTITY btrfs-progs-time "0.3 SBU (with parallelism=4; add 3.7 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, disable one test that is known to fail:
165 </para>
166
167<screen role="root" remap="test"><userinput>mv tests/misc-tests/041-subvolume-delete-during-send/test.sh \
168 tests/misc-tests/041-subvolume-delete-during-send/test.sh.skip</userinput></screen>
169
170 <para>
171 To test the results, issue (as the &root; user):
172 </para>
173
174<screen role="root" remap="test"><userinput>pushd tests
175 ./fsck-tests.sh
176 ./mkfs-tests.sh
177 ./cli-tests.sh
178 ./convert-tests.sh
179 ./misc-tests.sh
180 ./fuzz-tests.sh
181popd</userinput></screen>
182
183<!-- Template for failed test removal:
184 the other ones to run:
185 </para>
186
187<screen remap="test"><userinput>mv tests/fsck-tests/012-leaf-corruption/test.sh{,.broken}</userinput></screen>
188Substitute your test failure with the one above.
189 <para>
190 To test the results, run (as the
191 <systemitem class="username">root</systemitem> user):
192 </para>
193
194<screen role="root" remap="test"><userinput>make -j1 -k test</userinput></screen>
195-->
196 <note>
197 <para>
198 If the above mentioned kernel options are not enabled, some tests
199 fail, and prevent all the remaining tests from running because the test
200 disk image is not cleanly unmounted. Also make sure that the btrfs
201 kernel module is loaded.
202 </para>
203 </note>
204
205<!-- 6.8.1 - all tests went pretty fine, including the previously commented
206 convert-tests and the other two mentioned tests.
207 <para>
208 The convert-tests scripts are known to fail.
209 Tests 004-shrink-fs and 062-fi-show-raw-dm-all-devices in the misc-tests
210 are known to fail.
211 </para>
212-->
213 <para>
214 Install the package as the &root; user:
215 </para>
216
217<screen role="root"><userinput>make install</userinput></screen>
218
219 <para>
220 If you have passed <parameter>--disable-documentation</parameter> to
221 <command>configure</command> and you need the manual pages, install them
222 by running, as the &root; user:
223 </para>
224
225<screen role="root"><userinput>for i in 5 8; do
226 install Documentation/*.$i /usr/share/man/man$i
227done</userinput></screen>
228
229 </sect2>
230
231 <sect2 role="commands">
232 <title>Command Explanations</title>
233
234 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
235 href="../../xincludes/static-libraries.xml"/>
236
237 <para>
238 <parameter>--disable-documentation</parameter>: This switch
239 disables rebuilding the manual pages, because it requires
240 <xref linkend="sphinx"/>.
241 </para>
242<!--
243 <para>
244 <command>sed 's/,orphan_file//" ...</command>: In this version of
245 <application>btrfs-progs</application>, the
246 <command>btrfs-convert</command> program produces a btrfs filesystem
247 containing errors if converting from an ext4 filesystem created
248 with the <quote>orphan_file</quote> feature. This command creates
249 a custom configuration file that prevents creating a filesystem
250 with this feature.
251 </para>
252-->
253 <!--
254 <para>
255 <command>ln -s ... /usr/lib/libbtrfs.so</command>: Creates a
256 symbolic link in the directory where it is expected.
257 </para>
258
259 <para>
260 <command>rm /lib/libbtrfs.{a,so}</command>: Removes unneeded
261 library entries.
262 </para>
263-->
264 </sect2>
265<!--
266 <sect2 role="using" id="using-btrfs-convert">
267 <title>Using the btrfs-convert Program</title>
268
269 <para>
270 This version of <application>btrfs-progs</application> does not convert
271 correctly ext4 filesystems to btrfs if the ext4
272 <option>orphan_file</option> feature is turned on. If you happen to
273 convert such a filesystem, you need to first run:
274 </para>
275
276<screen role="nodump"><userinput>tune2fs -O ^orphan_file <replaceable>/dev/sdxx</replaceable></userinput></screen>
277
278 <para>
279 where <filename>/dev/sdxx</filename> is the partition of the filesystem
280 you want to convert.
281 </para>
282 </sect2>
283-->
284
285 <sect2 role="content">
286 <title>Contents</title>
287
288 <segmentedlist>
289 <segtitle>Installed Programs</segtitle>
290 <segtitle>Installed Libraries</segtitle>
291 <segtitle>Installed Directories</segtitle>
292
293 <seglistitem>
294 <seg>
295 btrfs,
296 btrfs-convert,
297 btrfs-find-root,
298 btrfs-image,
299 btrfs-map-logical,
300 btrfs-select-super,
301 btrfsck (link to btrfs),
302 btrfstune,
303 fsck.btrfs, and
304 mkfs.btrfs
305 </seg>
306
307 <seg>
308 libbtrfs.so and
309 libbtrfsutil.so
310 </seg>
311
312 <seg>/usr/include/btrfs</seg>
313 </seglistitem>
314 </segmentedlist>
315
316 <variablelist>
317 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
318 <?dbfo list-presentation="list"?>
319 <?dbhtml list-presentation="table"?>
320
321 <varlistentry id="btrfs-prog">
322 <term><command>btrfs</command></term>
323 <listitem>
324 <para>
325 is the main interface into btrfs filesystem operations
326 </para>
327 <indexterm zone="btrfs-progs btrfs-prog">
328 <primary sortas="b-btrfs">btrfs</primary>
329 </indexterm>
330 </listitem>
331 </varlistentry>
332
333 <varlistentry id="btrfs-convert">
334 <term><command>btrfs-convert</command></term>
335 <listitem>
336 <para>
337 converts from an ext2/3/4 or reiserfs filesystem to btrfs <!--(see
338 <xref linkend="using-btrfs-convert"/> above)-->
339 </para>
340 <indexterm zone="btrfs-progs btrfs-convert">
341 <primary sortas="b-btrfs-convert">btrfs-convert</primary>
342 </indexterm>
343 </listitem>
344 </varlistentry>
345
346 <varlistentry id="btrfs-find-root">
347 <term><command>btrfs-find-root</command></term>
348 <listitem>
349 <para>
350 is a filter to find btrfs root
351 </para>
352 <indexterm zone="btrfs-progs btrfs-find-root">
353 <primary sortas="b-btrfs-find-root">btrfs-find-root</primary>
354 </indexterm>
355 </listitem>
356 </varlistentry>
357
358 <varlistentry id="btrfs-map-logical">
359 <term><command>btrfs-map-logical</command></term>
360 <listitem>
361 <para>
362 maps btrfs logical extent to physical extent
363 </para>
364 <indexterm zone="btrfs-progs btrfs-map-logical">
365 <primary sortas="b-btrfs-map-logical">btrfs-map-logical</primary>
366 </indexterm>
367 </listitem>
368 </varlistentry>
369
370 <varlistentry id="btrfs-select-super">
371 <term><command>btrfs-select-super</command></term>
372 <listitem>
373 <para>
374 overwrites the primary superblock with a backup copy
375 </para>
376 <indexterm zone="btrfs-progs btrfs-select-super">
377 <primary sortas="b-btrfs-select-super">btrfs-select-super</primary>
378 </indexterm>
379 </listitem>
380 </varlistentry>
381
382 <varlistentry id="btrfstune">
383 <term><command>btrfstune</command></term>
384 <listitem>
385 <para>
386 tunes various filesystem parameters
387 </para>
388 <indexterm zone="btrfs-progs btrfstune">
389 <primary sortas="b-btrfstune">btrfstune</primary>
390 </indexterm>
391 </listitem>
392 </varlistentry>
393
394 <varlistentry id="fsck.btrfs">
395 <term><command>fsck.btrfs</command></term>
396 <listitem>
397 <para>
398 does nothing, but is present for consistency with fstab
399 </para>
400 <indexterm zone="btrfs-progs fsck.btrfs">
401 <primary sortas="b-fsck.btrfs">fsck.btrfs</primary>
402 </indexterm>
403 </listitem>
404 </varlistentry>
405
406 <varlistentry id="mkfs.btrfs">
407 <term><command>mkfs.btrfs</command></term>
408 <listitem>
409 <para>
410 creates a btrfs file system
411 </para>
412 <indexterm zone="btrfs-progs mkfs.btrfs">
413 <primary sortas="b-mkfs.btrfs">mkfs.btrfs</primary>
414 </indexterm>
415 </listitem>
416 </varlistentry>
417
418 </variablelist>
419
420 </sect2>
421
422</sect1>
Note: See TracBrowser for help on using the repository browser.