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

11.3 12.0 12.1 kea ken/TL2024 ken/inkscape-core-mods ken/tuningfonts lazarus lxqt plabs/newcss plabs/python-mods python3.11 qt5new rahul/power-profiles-daemon renodr/vulkan-addition trunk xry111/llvm18 xry111/xf86-video-removal
Last change on this file since ad9eab68 was ad9eab68, checked in by Bruce Dubbs <bdubbs@…>, 16 months ago

Update to btrfs-progs-v6.1.1.
  • Property mode set to 100644
File size: 10.9 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 "840c21c9103bc74dd14d41305bfc081e">
10 <!ENTITY btrfs-progs-size "2.2 MB">
11 <!ENTITY btrfs-progs-buildsize "53 MB (add 8.2 GB for tests)">
12 <!ENTITY btrfs-progs-time "0.2 SBU (add 5.0 SBU for tests, but will be longer 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 &lfs112_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
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 <ulink url="https://www.sphinx-doc.org/">Sphinx</ulink> (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 --disable-documentation &amp;&amp;
143make</userinput></screen>
144
145 <note>
146 <para>
147 Some tests require grep built with perl regular expressions. To
148 obtain this, rebuild grep with the LFS Chapter 8 instructions after
149 installing <xref linkend="pcre2"/>.
150 </para>
151 </note>
152<!-- Keeping this for now, but it seems that calling "make test" is
153 simpler and does the same thing -->
154 <para>
155 Before running tests, build a support program:
156 </para>
157
158<screen remap="test"><userinput>make fssum</userinput></screen>
159
160 <para>
161 To test the results, issue (as the &root; user):
162 </para>
163
164<screen role="root" remap="test"><userinput>pushd tests
165 ./fsck-tests.sh
166 ./mkfs-tests.sh
167 ./cli-tests.sh
168 ./convert-tests.sh
169 ./misc-tests.sh
170 ./fuzz-tests.sh
171popd</userinput></screen>
172
173<!-- Template for failed test removal:
174 <para>
175 To test the results, first disable one test that fails and prevents
176 the other ones to run:
177 </para>
178
179<screen remap="test"><userinput>mv tests/fsck-tests/012-leaf-corruption/test.sh{,.broken}</userinput></screen>
180Substitute your test failure with the one above.
181 <para>
182 To test the results, run (as the
183 <systemitem class="username">root</systemitem> user):
184 </para>
185
186<screen role="root" remap="test"><userinput>make -j1 -k test</userinput></screen>
187-->
188 <note>
189 <para>
190 If the above mentioned kernel options are not enabled, some tests
191 fail, and prevent all the remaining tests to run because the test
192 disk image is not cleanly unmounted.
193 </para>
194 </note>
195
196 <para>
197 The mkfs test 025-zoned-parallel is known to fail.
198 </para>
199
200 <para>
201 Install the package as the &root; user:
202 </para>
203
204<screen role="root"><userinput>make install</userinput></screen>
205
206 </sect2>
207
208 <sect2 role="commands">
209 <title>Command Explanations</title>
210
211 <para>
212 <option>--disable-documentation</option>: This option
213 is needed if the recommended dependencies are not installed.
214 </para>
215<!-- not anymore in the commands
216 <para>
217 <command>mv tests/{cli,convert,misc,fuzz}-tests/ ...</command>: Disables
218 tests that fail and prevent tests from completing.
219 </para>
220
221 <para>
222 <command>ln -s ... /usr/lib/libbtrfs.so</command>: Creates a
223 symbolic link in the directory where it is expected.
224 </para>
225
226 <para>
227 <command>rm /lib/libbtrfs.{a,so}</command>: Removes unneeded
228 library entries.
229 </para>
230-->
231 </sect2>
232
233 <sect2 role="content">
234 <title>Contents</title>
235
236 <segmentedlist>
237 <segtitle>Installed Programs</segtitle>
238 <segtitle>Installed Libraries</segtitle>
239 <segtitle>Installed Directories</segtitle>
240
241 <seglistitem>
242 <seg>
243 btrfs,
244 btrfs-convert,
245 btrfs-find-root,
246 btrfs-image,
247 btrfs-map-logical,
248 btrfs-select-super,
249 btrfsck (link to btrfs),
250 btrfstune,
251 fsck.btrfs, and
252 mkfs.btrfs
253 </seg>
254
255 <seg>
256 libbtrfs.so and
257 libbtrfsutil.so
258 </seg>
259
260 <seg>/usr/include/btrfs</seg>
261 </seglistitem>
262 </segmentedlist>
263
264 <variablelist>
265 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
266 <?dbfo list-presentation="list"?>
267 <?dbhtml list-presentation="table"?>
268
269 <varlistentry id="btrfs-prog">
270 <term><command>btrfs</command></term>
271 <listitem>
272 <para>
273 is the main interface into btrfs filesystem operations
274 </para>
275 <indexterm zone="btrfs-progs btrfs-prog">
276 <primary sortas="b-btrfs">btrfs</primary>
277 </indexterm>
278 </listitem>
279 </varlistentry>
280
281 <varlistentry id="btrfs-convert">
282 <term><command>btrfs-convert</command></term>
283 <listitem>
284 <para>
285 converts from an ext2/3/4 or reiserfs filesystem to btrfs
286 </para>
287 <indexterm zone="btrfs-progs btrfs-convert">
288 <primary sortas="b-btrfs-convert">btrfs-convert</primary>
289 </indexterm>
290 </listitem>
291 </varlistentry>
292
293 <varlistentry id="btrfs-find-root">
294 <term><command>btrfs-find-root</command></term>
295 <listitem>
296 <para>
297 is a filter to find btrfs root
298 </para>
299 <indexterm zone="btrfs-progs btrfs-find-root">
300 <primary sortas="b-btrfs-find-root">btrfs-find-root</primary>
301 </indexterm>
302 </listitem>
303 </varlistentry>
304
305 <varlistentry id="btrfs-map-logical">
306 <term><command>btrfs-map-logical</command></term>
307 <listitem>
308 <para>
309 maps btrfs logical extent to physical extent
310 </para>
311 <indexterm zone="btrfs-progs btrfs-map-logical">
312 <primary sortas="b-btrfs-map-logical">btrfs-map-logical</primary>
313 </indexterm>
314 </listitem>
315 </varlistentry>
316
317 <varlistentry id="btrfs-select-super">
318 <term><command>btrfs-select-super</command></term>
319 <listitem>
320 <para>
321 overwrites the primary superblock with a backup copy
322 </para>
323 <indexterm zone="btrfs-progs btrfs-select-super">
324 <primary sortas="b-btrfs-select-super">btrfs-select-super</primary>
325 </indexterm>
326 </listitem>
327 </varlistentry>
328
329 <varlistentry id="btrfstune">
330 <term><command>btrfstune</command></term>
331 <listitem>
332 <para>
333 tunes various filesystem parameters
334 </para>
335 <indexterm zone="btrfs-progs btrfstune">
336 <primary sortas="b-btrfstune">btrfstune</primary>
337 </indexterm>
338 </listitem>
339 </varlistentry>
340
341 <varlistentry id="fsck.btrfs">
342 <term><command>fsck.btrfs</command></term>
343 <listitem>
344 <para>
345 does nothing, but is present for consistency with fstab
346 </para>
347 <indexterm zone="btrfs-progs fsck.btrfs">
348 <primary sortas="b-fsck.btrfs">fsck.btrfs</primary>
349 </indexterm>
350 </listitem>
351 </varlistentry>
352
353 <varlistentry id="mkfs.btrfs">
354 <term><command>mkfs.btrfs</command></term>
355 <listitem>
356 <para>
357 creates a btrfs file system
358 </para>
359 <indexterm zone="btrfs-progs mkfs.btrfs">
360 <primary sortas="b-mkfs.btrfs">mkfs.btrfs</primary>
361 </indexterm>
362 </listitem>
363 </varlistentry>
364
365 </variablelist>
366
367 </sect2>
368
369</sect1>
Note: See TracBrowser for help on using the repository browser.