source: postlfs/filesystems/btrfs-progs.xml@ 60e8d690

12.0 12.1 kea ken/TL2024 ken/tuningfonts lazarus lxqt plabs/newcss python3.11 rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18 xry111/xf86-video-removal
Last change on this file since 60e8d690 was 416be1c, checked in by Bruce Dubbs <bdubbs@…>, 12 months ago

Update to btrfs-progs-v6.3.1.
  • Property mode set to 100644
File size: 12.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 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 "745ce7e4c547f0579ac5dfd793f126af">
10 <!ENTITY btrfs-progs-size "3.0 MB">
11 <!ENTITY btrfs-progs-buildsize "62 MB (transient files created during tests need up to 10 GB)">
12 <!ENTITY btrfs-progs-time "0.2 SBU (add 3.8 SBU for tests, up to 80 SBU on slow disks if reiserfsprogs is installed)">
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 &lfs113_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="reiserfs"/> (for tests), and
97 <xref linkend="sphinx"/> (required to build documentation)
98
99 </para>
100
101 <para condition="html" role="usernotes">User Notes:
102 <ulink url="&blfs-wiki;/btrfs-progs"/></para>
103
104 </sect2>
105
106 <sect2 role="kernel" id="btrfs-progs-kernel">
107 <title>Kernel Configuration</title>
108
109 <para>
110 Enable the following option in the kernel configuration
111 and recompile the kernel:
112 </para>
113
114<screen><literal>File systems ---&gt;
115 &lt;*/M&gt; Btrfs filesystem support [CONFIG_BTRFS_FS]</literal></screen>
116
117 <para>
118 In addition to the above and to the options required for
119 <xref linkend="lvm2"/> and <xref linkend="reiserfs"/>, the following
120 options must be enabled for running tests:
121 </para>
122
123<screen><literal>File systems ---&gt;
124 [*] Btrfs POSIX Access Control Lists [CONFIG_BTRFS_FS_POSIX_ACL]
125 [*] ReiserFS extended attributes [CONFIG_REISERFS_FS_XATTR]
126 [*] ReiserFS POSIX Access Control Lists [CONFIG_REISERFS_FS_POSIX_ACL]</literal></screen>
127
128 <indexterm zone="btrfs-progs btrfs-progs-kernel">
129 <primary sortas="d-btrfs-progs">BTRFS Programs</primary>
130 </indexterm>
131
132 </sect2>
133
134 <sect2 role="installation">
135 <title>Installation of btrfs-progs</title>
136
137 <para>
138 Install <application>btrfs-progs</application> by running the following
139 commands:
140 </para>
141
142<screen><userinput>./configure --prefix=/usr \
143 --disable-static \
144 --disable-documentation &amp;&amp;
145make</userinput></screen>
146
147 <note>
148 <para>
149 Some tests require grep built with perl regular expressions. To
150 obtain this, rebuild grep with the LFS Chapter 8 instructions after
151 installing <xref linkend="pcre2"/>.
152 </para>
153 </note>
154<!-- Keeping this for now, but it seems that calling "make test" is
155 simpler and does the same thing -->
156 <para>
157 Before running tests, build a support program:
158 </para>
159
160<screen remap="test"><userinput>make fssum</userinput></screen>
161
162 <para>
163 To test the results, issue (as the &root; user):
164 </para>
165
166<screen role="root" remap="test"><userinput>pushd tests
167 ./fsck-tests.sh
168 ./mkfs-tests.sh
169 ./cli-tests.sh
170 sed 's/,orphan_file//' /etc/mke2fs.conf >./custom_mke2fs.conf &amp;&amp;
171 export MKE2FS_CONFIG=$PWD/custom_mke2fs.conf &amp;&amp;
172 ./convert-tests.sh
173 unset MKE2FS_CONFIG &amp;&amp; rm custom_mke2fs.conf
174 ./misc-tests.sh
175 ./fuzz-tests.sh
176popd</userinput></screen>
177
178<!-- Template for failed test removal:
179 <para>
180 To test the results, first disable one test that fails and prevents
181 the other ones to run:
182 </para>
183
184<screen remap="test"><userinput>mv tests/fsck-tests/012-leaf-corruption/test.sh{,.broken}</userinput></screen>
185Substitute your test failure with the one above.
186 <para>
187 To test the results, run (as the
188 <systemitem class="username">root</systemitem> user):
189 </para>
190
191<screen role="root" remap="test"><userinput>make -j1 -k test</userinput></screen>
192-->
193 <note>
194 <para>
195 If the above mentioned kernel options are not enabled, some tests
196 fail, and prevent all the remaining tests from running because the test
197 disk image is not cleanly unmounted.
198 </para>
199 </note>
200<!-- Now passes in version 6.3.1.
201 <para>
202 The mkfs test 025-zoned-parallel is known to fail.
203 </para>
204-->
205 <para>
206 Install the package as the &root; user:
207 </para>
208
209<screen role="root"><userinput>make install</userinput></screen>
210
211 <para>
212 If you have passed <parameter>--disable-documentation</parameter> to
213 <command>configure</command> and you need the manual pages, install them
214 by running, as the &root; user:
215 </para>
216
217<screen role="root"><userinput>for i in 5 8; do
218 install Documentation/*.$i /usr/share/man/man$i
219done</userinput></screen>
220
221 </sect2>
222
223 <sect2 role="commands">
224 <title>Command Explanations</title>
225
226 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
227 href="../../xincludes/static-libraries.xml"/>
228
229 <para>
230 <parameter>--disable-documentation</parameter>: This switch
231 disables rebuilding the manual pages, because it requires
232 <xref linkend="sphinx"/>.
233 </para>
234 <para>
235 <command>sed 's/,orphan_file//" ...</command>: In this version of
236 <application>btrfs-progs</application>, the
237 <command>btrfs-convert</command> program produces a btrfs filesystem
238 containing errors if converting from an ext4 filesystem created
239 with the <quote>orphan_file</quote> feature. This command creates
240 a custom configuration file that prevents creating a filesystem
241 with this feature.
242 </para>
243 <!--
244 <para>
245 <command>ln -s ... /usr/lib/libbtrfs.so</command>: Creates a
246 symbolic link in the directory where it is expected.
247 </para>
248
249 <para>
250 <command>rm /lib/libbtrfs.{a,so}</command>: Removes unneeded
251 library entries.
252 </para>
253-->
254 </sect2>
255
256 <sect2 role="using" id="using-btrfs-convert">
257 <title>Using the btrfs-convert Program</title>
258
259 <para>
260 This version of <application>btrfs-progs</application> does not convert
261 correctly ext4 filesystems to btrfs if the ext4
262 <option>orphan_file</option> feature is turned on. If you happen to
263 convert such a filesystem, you need to first run:
264 </para>
265
266<screen role="nodump"><userinput>tune2fs -O ^orphan_file <replaceable>/dev/sdxx</replaceable></userinput></screen>
267
268 <para>
269 where <filename>/dev/sdxx</filename> is the partition of the filesystem
270 you want to convert.
271 </para>
272 </sect2>
273
274 <sect2 role="content">
275 <title>Contents</title>
276
277 <segmentedlist>
278 <segtitle>Installed Programs</segtitle>
279 <segtitle>Installed Libraries</segtitle>
280 <segtitle>Installed Directories</segtitle>
281
282 <seglistitem>
283 <seg>
284 btrfs,
285 btrfs-convert,
286 btrfs-find-root,
287 btrfs-image,
288 btrfs-map-logical,
289 btrfs-select-super,
290 btrfsck (link to btrfs),
291 btrfstune,
292 fsck.btrfs, and
293 mkfs.btrfs
294 </seg>
295
296 <seg>
297 libbtrfs.so and
298 libbtrfsutil.so
299 </seg>
300
301 <seg>/usr/include/btrfs</seg>
302 </seglistitem>
303 </segmentedlist>
304
305 <variablelist>
306 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
307 <?dbfo list-presentation="list"?>
308 <?dbhtml list-presentation="table"?>
309
310 <varlistentry id="btrfs-prog">
311 <term><command>btrfs</command></term>
312 <listitem>
313 <para>
314 is the main interface into btrfs filesystem operations
315 </para>
316 <indexterm zone="btrfs-progs btrfs-prog">
317 <primary sortas="b-btrfs">btrfs</primary>
318 </indexterm>
319 </listitem>
320 </varlistentry>
321
322 <varlistentry id="btrfs-convert">
323 <term><command>btrfs-convert</command></term>
324 <listitem>
325 <para>
326 converts from an ext2/3/4 or reiserfs filesystem to btrfs (see
327 <xref linkend="using-btrfs-convert"/> above)
328 </para>
329 <indexterm zone="btrfs-progs btrfs-convert">
330 <primary sortas="b-btrfs-convert">btrfs-convert</primary>
331 </indexterm>
332 </listitem>
333 </varlistentry>
334
335 <varlistentry id="btrfs-find-root">
336 <term><command>btrfs-find-root</command></term>
337 <listitem>
338 <para>
339 is a filter to find btrfs root
340 </para>
341 <indexterm zone="btrfs-progs btrfs-find-root">
342 <primary sortas="b-btrfs-find-root">btrfs-find-root</primary>
343 </indexterm>
344 </listitem>
345 </varlistentry>
346
347 <varlistentry id="btrfs-map-logical">
348 <term><command>btrfs-map-logical</command></term>
349 <listitem>
350 <para>
351 maps btrfs logical extent to physical extent
352 </para>
353 <indexterm zone="btrfs-progs btrfs-map-logical">
354 <primary sortas="b-btrfs-map-logical">btrfs-map-logical</primary>
355 </indexterm>
356 </listitem>
357 </varlistentry>
358
359 <varlistentry id="btrfs-select-super">
360 <term><command>btrfs-select-super</command></term>
361 <listitem>
362 <para>
363 overwrites the primary superblock with a backup copy
364 </para>
365 <indexterm zone="btrfs-progs btrfs-select-super">
366 <primary sortas="b-btrfs-select-super">btrfs-select-super</primary>
367 </indexterm>
368 </listitem>
369 </varlistentry>
370
371 <varlistentry id="btrfstune">
372 <term><command>btrfstune</command></term>
373 <listitem>
374 <para>
375 tunes various filesystem parameters
376 </para>
377 <indexterm zone="btrfs-progs btrfstune">
378 <primary sortas="b-btrfstune">btrfstune</primary>
379 </indexterm>
380 </listitem>
381 </varlistentry>
382
383 <varlistentry id="fsck.btrfs">
384 <term><command>fsck.btrfs</command></term>
385 <listitem>
386 <para>
387 does nothing, but is present for consistency with fstab
388 </para>
389 <indexterm zone="btrfs-progs fsck.btrfs">
390 <primary sortas="b-fsck.btrfs">fsck.btrfs</primary>
391 </indexterm>
392 </listitem>
393 </varlistentry>
394
395 <varlistentry id="mkfs.btrfs">
396 <term><command>mkfs.btrfs</command></term>
397 <listitem>
398 <para>
399 creates a btrfs file system
400 </para>
401 <indexterm zone="btrfs-progs mkfs.btrfs">
402 <primary sortas="b-mkfs.btrfs">mkfs.btrfs</primary>
403 </indexterm>
404 </listitem>
405 </varlistentry>
406
407 </variablelist>
408
409 </sect2>
410
411</sect1>
Note: See TracBrowser for help on using the repository browser.