source: postlfs/filesystems/btrfs-progs.xml@ a39d68ec

12.2 gimp3 lazarus trunk xry111/for-12.3 xry111/spidermonkey128
Last change on this file since a39d68ec was f25866f, checked in by Thomas Trepl <thomas@…>, 3 months ago

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