Debian Codegraph @

upstream/debian-trixie/man8/mkfs.xfs.8

raw
1 .TH mkfs.xfs 8
2 .SH NAME
3 mkfs.xfs \- construct an XFS filesystem
4 .SH SYNOPSIS
5 .B mkfs.xfs
6 [
7 .B \-b
8 .I block_size_options
9 ] [
10 .B \-c
11 .I config_file_options
12 ] [
13 .B \-m
14 .I global_metadata_options
15 ] [
16 .B \-d
17 .I data_section_options
18 ] [
19 .B \-f
20 ] [
21 .B \-i
22 .I inode_options
23 ] [
24 .B \-l
25 .I log_section_options
26 ] [
27 .B \-n
28 .I naming_options
29 ] [
30 .B \-p
31 .I protofile_options
32 ] [
33 .B \-q
34 ] [
35 .B \-r
36 .I realtime_section_options
37 ] [
38 .B \-s
39 .I sector_size_options
40 ] [
41 .B \-L
42 .I label
43 ] [
44 .B \-N
45 ] [
46 .B \-K
47 ]
48 .I device
49 .br
50 .B mkfs.xfs \-V
51 .SH DESCRIPTION
52 .B mkfs.xfs
53 constructs an XFS filesystem by writing on a special
54 file using the values found in the arguments of the command line.
55 It is invoked automatically by
56 .BR mkfs (8)
57 when it is given the
58 .B \-t xfs
59 option.
60 .PP
61 In its simplest (and most commonly used form), the size of the
62 filesystem is determined from the disk driver. As an example, to make
63 a filesystem with an internal log on the first partition on the first
64 SCSI disk, use:
65 .IP
66 .B mkfs.xfs /dev/sda1
67 .PP
68 The metadata log can be placed on another device to reduce the number
69 of disk seeks. To create a filesystem on the first partition on the
70 first SCSI disk with a 100MiB log located on the first partition
71 on the second SCSI disk, use:
72 .RS
73 .HP
74 .B mkfs.xfs\ \-l\ logdev=/dev/sdb1,size=100m /dev/sda1
75 .RE
76 .PP
77 Each of the
78 .I option
79 elements in the argument list above can be given as multiple comma-separated
80 suboptions if multiple suboptions apply to the same option.
81 Equivalently, each main option can be given multiple times with
82 different suboptions.
83 For example,
84 .B \-l internal,size=100m
85 and
86 .B \-l internal \-l size=100m
87 are equivalent.
88 .PP
89 In the descriptions below, sizes are given in sectors, bytes, blocks,
90 kilobytes, megabytes, gigabytes, etc.
91 Sizes are treated as hexadecimal if prefixed by 0x or 0X,
92 octal if prefixed by 0, or decimal otherwise.
93 The following lists possible multiplication suffixes:
94 .RS
95 .PD 0
96 .HP
97 .BR s "\ \-\ multiply by sector size (default = 512, see " \-s
98 option below).
99 .HP
100 .BR b "\ \-\ multiply by filesystem block size (default = 4K, see " \-b
101 option below).
102 .HP
103 .BR k "\ \-\ multiply by one kilobyte (1,024 bytes)."
104 .HP
105 .BR m "\ \-\ multiply by one megabyte (1,048,576 bytes)."
106 .HP
107 .BR g "\ \-\ multiply by one gigabyte (1,073,741,824 bytes)."
108 .HP
109 .BR t "\ \-\ multiply by one terabyte (1,099,511,627,776 bytes)."
110 .HP
111 .BR p "\ \-\ multiply by one petabyte (1,024 terabytes)."
112 .HP
113 .BR e "\ \-\ multiply by one exabyte (1,048,576 terabytes)."
114 .PD
115 .RE
116 .PP
117 When specifying parameters in units of sectors or filesystem blocks, the
118 .B \-s
119 option or the
120 .B \-b
121 option may be used to specify the size of the sector or block.
122 If the size of the block or sector is not specified, the default sizes
123 (block: 4KiB, sector: 512B) will be used.
124 .PP
125 Many feature options allow an optional argument of 0 or 1, to explicitly
126 disable or enable the functionality.
127
128 The correctness of the crc32c checksum implementation will be tested
129 before formatting the filesystem.
130 If the test fails, the format will abort.
131 .SH OPTIONS
132 Options may be specified either on the command line or in a configuration file.
133 Not all command line options can be specified in configuration files; only the
134 command line options followed by a
135 .B [section]
136 label can be used in a configuration file.
137 .PP
138 Options that can be used in configuration files are grouped into related
139 sections containing multiple options.
140 The command line options and configuration files use the same option
141 sections and grouping.
142 Configuration file section names are listed in the command line option
143 sections below.
144 Option names and values are the same for both command line
145 and configuration file specification.
146 .PP
147 Options specified are the combined set of command line parameters and
148 configuration file parameters.
149 Duplicated options will result in a respecification error, regardless of the
150 location they were specified at.
151 .TP
152 .BI \-c " configuration_file_option"
153 This option specifies the files that mkfs configuration will be obtained from.
154 The valid
155 .I configuration_file_option
156 is:
157 .RS 1.2i
158 .TP
159 .BI options= name
160 The configuration options will be sourced from the file specified by the
161 .I name
162 option string.
163 This option can be use either an absolute or relative path to the configuration
164 file to be read.
165 Sample configuration files can be found in /usr/share/xfsprogs/mkfs.
166 .RE
167 .PP
168 .PD 0
169 .BI \-b " block_size_options"
170 .TP
171 .BI "Section Name: " [block]
172 .PD
173 This option specifies the fundamental block size of the filesystem.
174 The valid
175 .I block_size_option
176 is:
177 .RS 1.2i
178 .TP
179 .BI size= value
180 The filesystem block size is specified with a
181 .I value
182 in bytes. The default value is 4096 bytes (4 KiB), the minimum is 512, and the
183 maximum is 65536 (64 KiB).
184 .IP
185 Although
186 .B mkfs.xfs
187 will accept any of these values and create a valid filesystem,
188 XFS on Linux can only mount filesystems with pagesize or smaller blocks.
189 .RE
190 .PP
191 .PD 0
192 .BI \-m " global_metadata_options"
193 .TP
194 .BI "Section Name: " [metadata]
195 .PD
196 These options specify metadata format options that either apply to the entire
197 filesystem or aren't easily characterised by a specific functionality group. The
198 valid
199 .I global_metadata_options
200 are:
201 .RS 1.2i
202 .TP
203 .BI bigtime= value
204 This option enables filesystems that can handle inode timestamps from December
205 1901 to July 2486, and quota timer expirations from January 1970 to July 2486.
206 The value is either 0 to disable the feature, or 1 to enable large timestamps.
207 .IP
208 If this feature is not enabled, the filesystem can only handle timestamps from
209 December 1901 to January 2038, and quota timers from January 1970 to February
210 2106.
211 .IP
212 By default,
213 .B mkfs.xfs
214 will enable this feature.
215 If the option
216 .B \-m crc=0
217 is used, the large timestamp feature is not supported and is disabled.
218 .TP
219 .BI crc= value
220 This is used to create a filesystem which maintains and checks CRC information
221 in all metadata objects on disk. The value is either 0 to disable the feature,
222 or 1 to enable the use of CRCs.
223 .IP
224 CRCs enable enhanced error detection due to hardware issues, whilst the format
225 changes also improves crash recovery algorithms and the ability of various tools
226 to validate and repair metadata corruptions when they are found. The CRC
227 algorithm used is CRC32c, so the overhead is dependent on CPU architecture as
228 some CPUs have hardware acceleration of this algorithm. Typically the overhead
229 of calculating and checking the CRCs is not noticeable in normal operation.
230 .IP
231 By default,
232 .B mkfs.xfs
233 will enable metadata CRCs.
234 .IP
235 Formatting a filesystem without CRCs selects the V4 format, which is deprecated
236 and will be removed from upstream in September 2030.
237 Distributors may choose to withdraw support for the V4 format earlier than
238 this date.
239 Several other options, noted below, are only tunable on V4 formats, and will
240 be removed along with the V4 format itself.
241 .TP
242 .BI finobt= value
243 This option enables the use of a separate free inode btree index in each
244 allocation group. The value is either 0 to disable the feature, or 1 to create
245 a free inode btree in each allocation group.
246 .IP
247 The free inode btree mirrors the existing allocated inode btree index which
248 indexes both used and free inodes. The free inode btree does not index used
249 inodes, allowing faster, more consistent inode allocation performance as
250 filesystems age.
251 .IP
252 By default,
253 .B mkfs.xfs
254 will create free inode btrees for filesystems created with the (default)
255 .B \-m crc=1
256 option set. When the option
257 .B \-m crc=0
258 is used, the free inode btree feature is not supported and is disabled.
259 .TP
260 .BI inobtcount= value
261 This option causes the filesystem to record the number of blocks used by
262 the inode btree and the free inode btree.
263 This can be used to reduce mount times when the free inode btree is enabled.
264 .IP
265 By default,
266 .B mkfs.xfs
267 will enable this option.
268 This feature is only available for filesystems created with the (default)
269 .B \-m finobt=1
270 option set.
271 When the option
272 .B \-m finobt=0
273 is used, the inode btree counter feature is not supported and is disabled.
274 .TP
275 .BI metadir= value
276 This option creates an internal directory tree to store filesystem metadata.
277 .IP
278 By default,
279 .B mkfs.xfs
280 will not enable this feature.
281 If the option
282 .B \-m crc=0
283 is used, the metadata directory feature is not supported and is disabled.
284
285 .TP
286 .BI uuid= value
287 Use the given value as the filesystem UUID for the newly created filesystem.
288 The default is to generate a random UUID.
289 .TP
290 .BI rmapbt= value
291 This option enables the creation of a reverse-mapping btree index in each
292 allocation group. The value is either 0 to disable the feature, or 1 to
293 create the btree.
294 .IP
295 The reverse mapping btree maps filesystem blocks to the owner of the
296 filesystem block. Most of the mappings will be to an inode number and an
297 offset, though there will also be mappings to filesystem metadata. This
298 secondary metadata can be used to validate the primary metadata or to
299 pinpoint exactly which data has been lost when a disk error occurs.
300 .IP
301 By default,
302 .B mkfs.xfs
303 will create reverse mapping btrees when possible.
304 This feature is only available for filesystems created with the (default)
305 .B \-m crc=1
306 option set. When the option
307 .B \-m crc=0
308 is used, the reverse mapping btree feature is not supported and is disabled.
309 .TP
310 .BI reflink= value
311 This option enables the use of a separate reference count btree index in each
312 allocation group. The value is either 0 to disable the feature, or 1 to create
313 a reference count btree in each allocation group.
314 .IP
315 The reference count btree enables the sharing of physical extents between
316 the data forks of different files, which is commonly known as "reflink".
317 Unlike traditional Unix filesystems which assume that every inode and
318 logical block pair map to a unique physical block, a reflink-capable
319 XFS filesystem removes the uniqueness requirement, allowing up to four
320 billion arbitrary inode/logical block pairs to map to a physical block.
321 If a program tries to write to a multiply-referenced block in a file, the write
322 will be redirected to a new block, and that file's logical-to-physical
323 mapping will be changed to the new block ("copy on write"). This feature
324 enables the creation of per-file snapshots and deduplication. It is only
325 available for the data forks of regular files.
326 .IP
327 By default,
328 .B mkfs.xfs
329 will create reference count btrees and therefore will enable the
330 reflink feature. This feature is only available for filesystems created with
331 the (default)
332 .B \-m crc=1
333 option set. When the option
334 .B \-m crc=0
335 is used, the reference count btree feature is not supported and reflink is
336 disabled.
337 .TP
338 .BI autofsck= value
339 Set the autofsck filesystem property to this value.
340 See the
341 .BI xfs_scrub (8)
342 manual page for more information on this property.
343 .TP
344 .B uquota
345 If the metadata directory feature is enabled, the
346 .B \-m uquota
347 option will set up user quota accounting and enforcement at format time;
348 specifying the quota options in fstab is no longer unnecessary.
349 If metadata directories are not enabled, quotas must still be enabled via
350 fstab.
351 .TP
352 .B gquota
353 If the metadata directory feature is enabled, the
354 .B \-m gquota
355 option will set up group quota accounting and enforcement at format time;
356 specifying the quota options in fstab is no longer unnecessary.
357 If metadata directories are not enabled, quotas must still be enabled via
358 fstab.
359 .TP
360 .B pquota
361 If the metadata directory feature is enabled, the
362 .B \-m pquota
363 option will set up project quota accounting and enforcement at format time;
364 specifying the quota options in fstab is no longer unnecessary.
365 If metadata directories are not enabled, quotas must still be enabled via
366 fstab.
367 .TP
368 .B uqnoenforce
369 If the metadata directory feature is enabled, the
370 .B \-m uqnoenforce
371 option will set up user quota accounting at format time; specifying the quota
372 options in fstab is no longer unnecessary.
373 If metadata directories are not enabled, quotas must still be enabled via
374 fstab.
375 .TP
376 .B gqnoenforce
377 If the metadata directory feature is enabled, the
378 .B \-m gqnoenforce
379 option will set up group quota accounting at format time; specifying the quota
380 options in fstab is no longer unnecessary.
381 If metadata directories are not enabled, quotas must still be enabled via
382 fstab.
383 .TP
384 .B pqnoenforce
385 If the metadata directory feature is enabled, the
386 .B \-m pqnoenforce
387 option will set up project quota accounting at format time; specifying the
388 quota options in fstab is no longer unnecessary.
389 If metadata directories are not enabled, quotas must still be enabled via
390 fstab.
391 .RE
392 .PP
393 .PD 0
394 .BI \-d " data_section_options"
395 .TP
396 .BI "Section Name: " [data]
397 .PD
398 These options specify the location, size, and other parameters of the
399 data section of the filesystem. The valid
400 .I data_section_options
401 are:
402 .RS 1.2i
403 .TP
404 .BI agcount= value
405 This is used to specify the number of allocation groups. The data section
406 of the filesystem is divided into allocation groups to improve the
407 performance of XFS. More allocation groups imply that more parallelism
408 can be achieved when allocating blocks and inodes. The minimum
409 allocation group size is 16 MiB; the maximum size is just under 1 TiB.
410 The data section of the filesystem is divided into
411 .I value
412 allocation groups (default value is scaled automatically based
413 on the underlying device size).
414 .TP
415 .BI agsize= value
416 This is an alternative to using the
417 .B agcount
418 suboption. The
419 .I value
420 is the desired size of the allocation group expressed in bytes
421 (usually using the
422 .BR m " or " g
423 suffixes).
424 This value must be a multiple of the filesystem block size, and
425 must be at least 16MiB, and no more than 1TiB, and may
426 be automatically adjusted to properly align with the stripe geometry.
427 The
428 .B agcount
429 and
430 .B agsize
431 suboptions are mutually exclusive.
432 .TP
433 .BI cowextsize= value
434 Set the copy-on-write extent size hint on all inodes created by
435 .BR mkfs.xfs "."
436 The value must be provided in units of filesystem blocks.
437 If the value is zero, the default value (currently 32 blocks) will be used.
438 Directories will pass on this hint to newly created regular files and
439 directories.
440 .TP
441 .BI name= value
442 This can be used to specify the name of the special file containing
443 the filesystem. In this case, the log section must be specified as
444 .B internal
445 (with a size, see the
446 .B \-l
447 option below) and there can be no real-time section.
448 .TP
449 .BI file[= value ]
450 This is used to specify that the file given by the
451 .B name
452 suboption is a regular file. The
453 .I value
454 is either 0 or 1, with 1 signifying that the file is regular. This
455 suboption is used only to make a filesystem image. If the
456 .I value
457 is omitted then 1 is assumed.
458 .TP
459 .BI size= value
460 This is used to specify the size of the data section. This suboption
461 is required if
462 .B \-d file[=1]
463 is given. Otherwise, it is only needed if the filesystem should occupy
464 less space than the size of the special file.
465
466 The data section must be at least 300MB in size.
467 .TP
468 .BI sunit= value
469 This is used to specify the stripe unit for a RAID device or a
470 logical volume. The
471 .I value
472 has to be specified in 512-byte block units. Use the
473 .B su
474 suboption to specify the stripe unit size in bytes. This suboption
475 ensures that data allocations will be stripe unit aligned when the
476 current end of file is being extended and the file size is larger
477 than 512KiB. Also inode allocations and the internal log will be
478 stripe unit aligned.
479 .TP
480 .BI su= value
481 This is an alternative to using
482 .B sunit.
483 The
484 .B su
485 suboption is used to specify the stripe unit for a RAID device or a
486 striped logical volume. The
487 .I value
488 has to be specified in bytes, (usually using the
489 .BR m " or " g
490 suffixes). This
491 .I value
492 must be a multiple of the filesystem block size.
493 .TP
494 .BI swidth= value
495 This is used to specify the stripe width for a RAID device or a
496 striped logical volume. The
497 .I value
498 has to be specified in 512-byte block units. Use the
499 .B sw
500 suboption to specify the stripe width size in bytes.
501 This suboption is required if
502 .B \-d sunit
503 has been specified and it has to be a multiple of the
504 .B \-d sunit
505 suboption.
506 .TP
507 .BI sw= value
508 suboption is an alternative to using
509 .B swidth.
510 The
511 .B sw
512 suboption is used to specify the stripe width for a RAID device or
513 striped logical volume. The
514 .I value
515 is expressed as a multiplier of the stripe unit,
516 usually the same as the number of stripe members in the logical
517 volume configuration, or data disks in a RAID device.
518 .IP
519 When a filesystem is created on a block device,
520 .B mkfs.xfs
521 will automatically query the block device for appropriate
522 .B sunit
523 and
524 .B swidth
525 values if the block device and the filesystem size would be larger than 1GB.
526 .TP
527 .BI noalign
528 This option disables automatic geometry detection and creates the filesystem
529 without stripe geometry alignment even if the underlying storage device provides
530 this information.
531 .TP
532 .BI rtinherit= value
533 If
534 .I value
535 is set to 1, all inodes created by
536 .B mkfs.xfs
537 will be created with the realtime flag set.
538 The default is 0.
539 Directories will pass on this flag to newly created regular files and
540 directories.
541 .TP
542 .BI projinherit= value
543 All inodes created by
544 .B mkfs.xfs
545 will be assigned the project quota id provided in
546 .I value.
547 Directories will pass on the project id to newly created regular files and
548 directories.
549 .TP
550 .BI extszinherit= value
551 All inodes created by
552 .B mkfs.xfs
553 will have this
554 .I value
555 extent size hint applied.
556 The value must be provided in units of filesystem blocks.
557 Directories will pass on this hint to newly created regular files and
558 directories.
559 .TP
560 .BI daxinherit= value
561 If
562 .I value
563 is set to 1, all inodes created by
564 .B mkfs.xfs
565 will be created with the DAX flag set.
566 The default is 0.
567 Directories will pass on this flag to newly created regular files and
568 directories.
569 By default,
570 .B mkfs.xfs
571 will not enable DAX mode.
572 .TP
573 .BI concurrency= value
574 Create enough allocation groups to handle the desired level of concurrency.
575 The goal of this calculation scheme is to set the number of allocation groups
576 to an integer multiple of the number of writer threads desired, to minimize
577 contention of AG locks.
578 This scheme will neither create fewer AGs than would be created by the default
579 configuration, nor will it create AGs smaller than 4GB.
580 This option is not compatible with the
581 .B agcount
582 or
583 .B agsize
584 options.
585 The magic value
586 .I nr_cpus
587 or
588 .I 1
589 or no value at all will set this parameter to the number of active processors
590 in the system.
591 If the kernel advertises that the data device is a non-mechanical storage
592 device,
593 .B mkfs.xfs
594 will use this new geometry calculation scheme.
595 The magic value of
596 .I 0
597 forces use of the older AG geometry calculations that is used for mechanical
598 storage.
599 .RE
600 .TP
601 .B \-f
602 Force overwrite when an existing filesystem is detected on the device.
603 By default,
604 .B mkfs.xfs
605 will not write to the device if it suspects that there is a filesystem
606 or partition table on the device already.
607 .PP
608 .PD 0
609 .BI \-i " inode_options"
610 .TP
611 .BI "Section Name: " [inode]
612 .PD
613 This option specifies the inode size of the filesystem, and other
614 inode allocation parameters.
615 The XFS inode contains a fixed-size part and a variable-size part.
616 The variable-size part, whose size is affected by this option, can contain:
617 directory data, for small directories;
618 attribute data, for small attribute sets;
619 symbolic link data, for small symbolic links;
620 the extent list for the file, for files with a small number of extents;
621 and the root of a tree describing the location of extents for the file,
622 for files with a large number of extents.
623 .IP
624 The valid
625 .I inode_options
626 are:
627 .RS 1.2i
628 .TP
629 .BI size= value " | perblock=" value
630 The inode size is specified either as a
631 .I value
632 in bytes with
633 .BR size=
634 or as the number fitting in a filesystem block with
635 .BR perblock= .
636 The minimum (and default)
637 .I value
638 is 256 bytes without crc, 512 bytes with crc enabled.
639 The maximum
640 .I value
641 is 2048 (2 KiB) subject to the restriction that
642 the inode size cannot exceed one half of the filesystem block size.
643 .IP
644 XFS uses 64-bit inode numbers internally; however, the number of
645 significant bits in an inode number
646 is affected by filesystem geometry. In
647 practice, filesystem size and inode size are the predominant factors.
648 The Linux kernel (on 32 bit hardware platforms) and most applications
649 cannot currently handle inode numbers greater than 32 significant bits,
650 so if no inode size is given on the command line,
651 .B mkfs.xfs
652 will attempt to choose a size
653 such that inode numbers will be < 32 bits. If an inode size
654 is specified, or if a filesystem is sufficiently large,
655 .B mkfs.xfs
656 will warn if this will create inode numbers > 32 significant
657 bits.
658 .TP
659 .BI maxpct= value
660 This specifies the maximum percentage of space in the filesystem that
661 can be allocated to inodes. The default
662 .I value
663 is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1%
664 for filesystems over 50TB.
665 .IP
666 Setting the value to 0 means that essentially all of the filesystem
667 can become inode blocks (subject to possible
668 .B inode32
669 mount option restrictions, see
670 .BR xfs (5)
671 for details.)
672 .IP
673 This value can be modified with
674 .BR xfs_growfs (8).
675 .TP
676 .BI align[= value ]
677 This is used to specify that inode allocation is or is not aligned. The
678 .I value
679 is either 0 or 1, with 1 signifying that inodes are allocated aligned.
680 If the
681 .I value
682 is omitted, 1 is assumed. The default is that inodes are aligned.
683 Aligned inode access is normally more efficient than unaligned access;
684 alignment must be established at the time the filesystem is created,
685 since inodes are allocated at that time.
686 This option can be used to turn off inode alignment when the
687 filesystem needs to be mountable by a version of IRIX
688 that does not have the inode alignment feature
689 (any release of IRIX before 6.2, and IRIX 6.2 without XFS patches).
690 .IP
691 This option is only tunable on the deprecated V4 format.
692 .TP
693 .BI attr= value
694 This is used to specify the version of extended attribute inline
695 allocation policy to be used. By default, this is 2, which uses an
696 efficient algorithm for managing the available inline inode space
697 between attribute and extent data.
698 .IP
699 The previous version 1, which has fixed regions for attribute and
700 extent data, is kept for backwards compatibility with kernels older
701 than version 2.6.16.
702 .IP
703 This option is only tunable on the deprecated V4 format.
704 .TP
705 .BI projid32bit[= value ]
706 This is used to enable 32bit quota project identifiers. The
707 .I value
708 is either 0 or 1, with 1 signifying that 32bit projid are to be enabled.
709 If the value is omitted, 1 is assumed. (This default changed
710 in release version 3.2.0.)
711 .IP
712 This option is only tunable on the deprecated V4 format.
713 .TP
714 .BI sparse[= value ]
715 Enable sparse inode chunk allocation. The
716 .I value
717 is either 0 or 1, with 1 signifying that sparse allocation is enabled.
718 If the value is omitted, 1 is assumed. Sparse inode allocation is
719 enabled by default. This feature is only available for filesystems
720 formatted with
721 .B \-m crc=1.
722 .IP
723 When enabled, sparse inode allocation allows the filesystem to allocate
724 smaller than the standard 64-inode chunk when free space is severely
725 limited. This feature is useful for filesystems that might fragment free
726 space over time such that no free extents are large enough to
727 accommodate a chunk of 64 inodes. Without this feature enabled, inode
728 allocations can fail with out of space errors under severe fragmented
729 free space conditions.
730 .TP
731 .BI nrext64[= value]
732 Extend maximum values of inode data and attr fork extent counters from 2^31 -
733 1 and 2^15 - 1 to 2^48 - 1 and 2^32 - 1 respectively.
734 If the value is omitted, 1 is assumed.
735 This feature will be enabled when possible.
736 This feature is only available for filesystems formatted with -m crc=1.
737 .TP
738 .BI exchange[= value]
739 When enabled, application programs can exchange file contents atomically
740 via the XFS_IOC_EXCHANGE_RANGE ioctl.
741 Online repair uses this functionality to rebuild extended attributes,
742 directories, symbolic links, and realtime metadata files.
743 This feature is disabled by default.
744 This feature is only available for filesystems formatted with -m crc=1.
745 .RE
746 .PP
747 .PD 0
748 .BI \-l " log_section_options"
749 .TP
750 .BI "Section Name: " [log]
751 .PD
752 These options specify the location, size, and other parameters of the
753 log section of the filesystem. The valid
754 .I log_section_options
755 are:
756 .RS 1.2i
757 .TP
758 .BI agnum= value
759 If the log is internal, allocate it in this AG.
760 .TP
761 .BI internal[= value ]
762 This is used to specify that the log section is a piece of the data
763 section instead of being another device or logical volume. The
764 .I value
765 is either 0 or 1, with 1 signifying that the log is internal. If the
766 .I value
767 is omitted, 1 is assumed.
768 .TP
769 .BI logdev= device
770 This is used to specify that the log section should reside on the
771 .I device
772 separate from the data section. The
773 .B internal=1
774 and
775 .B logdev
776 options are mutually exclusive.
777 .TP
778 .BI size= value
779 This is used to specify the size of the log section.
780 .IP
781 If the log is contained within the data section and
782 .B size
783 isn't specified,
784 .B mkfs.xfs
785 will try to select a suitable log size depending
786 on the size of the filesystem. The actual logsize depends on the
787 filesystem block size and the directory block size.
788 .IP
789 Otherwise, the
790 .B size
791 suboption is only needed if the log section of the filesystem
792 should occupy less space than the size of the special file. The
793 .I value
794 is specified in bytes or blocks, with a
795 .B b
796 suffix meaning multiplication by the filesystem block size, as
797 described above. The overriding minimum value for size is 512 blocks.
798 With some combinations of filesystem block size, inode size,
799 and directory block size, the minimum log size is larger than 512 blocks.
800
801 The log must be at least 64MB in size.
802 The log cannot be more than 2GB in size.
803 .TP
804 .BI version= value
805 This specifies the version of the log. The current default is 2,
806 which allows for larger log buffer sizes, as well as supporting
807 stripe-aligned log writes (see the sunit and su options, below).
808 .IP
809 The previous version 1, which is limited to 32k log buffers and does
810 not support stripe-aligned writes, is kept for backwards compatibility
811 with very old 2.4 kernels.
812 .IP
813 This option is only tunable on the deprecated V4 format.
814 .TP
815 .BI sunit= value
816 This specifies the alignment to be used for log writes. The
817 .I value
818 has to be specified in 512-byte block units. Use the
819 .B su
820 suboption to specify the log stripe unit size in bytes.
821 Log writes will be aligned on this boundary,
822 and rounded up to this boundary.
823 This gives major improvements in performance on some configurations
824 such as software RAID5 when the
825 .B sunit
826 is specified as the filesystem block size.
827 The equivalent byte value must be a multiple of the filesystem block
828 size. Version 2 logs are automatically selected if the log
829 .B sunit
830 suboption is specified.
831 .IP
832 The
833 .B su
834 suboption is an alternative to using
835 .B sunit.
836 .TP
837 .BI su= value
838 This is used to specify the log stripe. The
839 .I value
840 has to be specified in bytes, (usually using the
841 .BR s " or " b
842 suffixes). This value must be a multiple of the filesystem block size.
843 Version 2 logs are automatically selected if the log
844 .B su
845 suboption is specified.
846 .TP
847 .BI lazy-count= value
848 This changes the method of logging various persistent counters
849 in the superblock. Under metadata intensive workloads, these
850 counters are updated and logged frequently enough that the superblock
851 updates become a serialization point in the filesystem. The
852 .I value
853 can be either 0 or 1.
854 .IP
855 With
856 .BR lazy-count=1 ,
857 the superblock is not modified or logged on every change of the
858 persistent counters. Instead, enough information is kept in
859 other parts of the filesystem to be able to maintain the persistent
860 counter values without needed to keep them in the superblock.
861 This gives significant improvements in performance on some configurations.
862 The default
863 .I value
864 is 1 (on) so you must specify
865 .B lazy-count=0
866 if you want to disable this feature for older kernels which don't support
867 it.
868 .IP
869 This option is only tunable on the deprecated V4 format.
870 .TP
871 .BI concurrency= value
872 Allocate a log that is estimated to be large enough to handle the desired level
873 of concurrency without userspace program threads contending for log space.
874 This scheme will neither create a log smaller than the minimum required,
875 nor create a log larger than the maximum possible.
876 This option is only valid for internal logs and is not compatible with the
877 size option.
878 This option is not compatible with the
879 .B logdev
880 or
881 .B size
882 options.
883 The magic value
884 .I nr_cpus
885 or
886 .I 1
887 or no value at all will set this parameter to the number of active processors
888 in the system.
889 .RE
890 .PP
891 .PD 0
892 .BI \-n " naming_options"
893 .TP
894 .BI "Section Name: " [naming]
895 .PD
896 These options specify the version and size parameters for the naming
897 (directory) area of the filesystem. The valid
898 .I naming_options
899 are:
900 .RS 1.2i
901 .TP
902 .BI size= value
903 The directory block size is specified with a
904 .I value
905 in bytes. The block size must be a power of 2 and cannot be less than the
906 filesystem block size.
907 The default size
908 .I value
909 for version 2 directories is 4096 bytes (4 KiB),
910 unless the filesystem block size is larger than 4096,
911 in which case the default
912 .I value
913 is the filesystem block size.
914 For version 1 directories the block size is the same as the
915 filesystem block size.
916 .TP
917 .BI version= value
918 The naming (directory) version
919 .I value
920 can be either 2 or 'ci', defaulting to 2 if unspecified.
921 With version 2 directories, the directory block size can be
922 any power of 2 size from the filesystem block size up to 65536.
923 .IP
924 If the
925 .B version=ci
926 option is specified, the kernel will transform certain bytes in filenames
927 before performing lookup-related operations.
928 The byte sequence given to create a directory entry is persisted without
929 alterations.
930 The lookup transformations are defined as follows:
931
932 0x41-0x5a -> 0x61-0x7a
933
934 0xc0-0xd6 -> 0xe0-0xf6
935
936 0xd8-0xde -> 0xf8-0xfe
937
938 This transformation roughly corresponds to case insensitivity in ISO
939 8859-1.
940 The transformations are not compatible with other encodings (e.g. UTF8).
941 Do not enable this feature unless your entire environment has been coerced
942 to ISO 8859-1.
943 This feature is deprecated and will be removed in September 2030.
944 .IP
945 Note: Version 1 directories are not supported.
946 .TP
947 .BI ftype= value
948 This feature allows the inode type to be stored in the directory
949 structure so that the
950 .BR readdir (3)
951 and
952 .BR getdents (2)
953 do not need to look up the inode to determine the inode type.
954
955 The
956 .I value
957 is either 0 or 1, with 1 signifying that filetype information
958 will be stored in the directory structure. The default value is 1.
959
960 When CRCs are enabled (the default), the ftype functionality is always
961 enabled, and cannot be turned off.
962 .IP
963 In other words, this option is only tunable on the deprecated V4 format.
964 .TP
965 .BI parent= value
966 This feature creates back references from child files to parent directories
967 so that online repair can reconstruct broken directory files.
968 The value is either 0 to disable the feature, or 1 to create parent pointers.
969
970 By default,
971 .B mkfs.xfs
972 will not create parent pointers.
973 This feature is only available for filesystems created with the (default)
974 .B \-m crc=1
975 option set.
976 .RE
977 .PP
978 .PD 0
979 .TP
980 .BI \-p " protofile_options"
981 .TP
982 .BI "Section Name: " [proto]
983 .PD
984 These options specify the protofile parameters for populating the filesystem.
985 The valid
986 .I protofile_options
987 are:
988 .RS 1.2i
989 .TP
990 .BI [file=] protofile
991 The
992 .B file=
993 prefix is not required for this CLI argument for legacy reasons.
994 If specified as a config file directive, the prefix is required.
995
996 If the optional
997 .PD
998 .I protofile
999 argument is given,
1000 .B mkfs.xfs
1001 uses
1002 .I protofile
1003 as a prototype file and takes its directions from that file.
1004 The blocks and inodes specifiers in the
1005 .I protofile
1006 are provided for backwards compatibility, but are otherwise unused.
1007 The syntax of the protofile is defined by a number of tokens separated
1008 by spaces or newlines. Note that the line numbers are not part of the
1009 syntax but are meant to help you in the following discussion of the file
1010 contents.
1011 .nf
1012 .sp .8v
1013 .in +5
1014 \f71 /stand/\f1\f2diskboot\f1\f7
1015 2 4872 110
1016 3 d\-\-777 3 1
1017 4 usr d\-\-777 3 1
1018 5 sh \-\-\-755 3 1 /bin/sh
1019 6 ken d\-\-755 6 1
1020 7 $
1021 8 b0 b\-\-644 3 1 0 0
1022 9 c0 c\-\-644 3 1 0 0
1023 10 fifo p\-\-644 3 1
1024 11 slink l\-\-644 3 1 /a/symbolic/link
1025 12 : This is a comment line
1026 13 $
1027 14 $\f1
1028 .in -5
1029 .fi
1030 .IP
1031 Line 1 is a dummy string.
1032 (It was formerly the bootfilename.)
1033 It is present for backward
1034 compatibility; boot blocks are not used on SGI systems.
1035 .IP
1036 Note that some string of characters must be present as the first line of
1037 the proto file to cause it to be parsed correctly; the value
1038 of this string is immaterial since it is ignored.
1039 .IP
1040 Line 2 contains two numeric values (formerly the numbers of blocks and inodes).
1041 These are also merely for backward compatibility: two numeric values must
1042 appear at this point for the proto file to be correctly parsed,
1043 but their values are immaterial since they are ignored.
1044 .IP
1045 The lines 3 through 11 specify the files and directories you want to
1046 include in this filesystem. Line 3 defines the
1047 root directory. Other directories and
1048 files that you want in the filesystem
1049 are indicated by lines 4 through 6 and
1050 lines 8 through 10. Line 11 contains
1051 symbolic link syntax.
1052 .IP
1053 Notice the dollar sign
1054 .RB ( $ )
1055 syntax on line 7. This syntax directs the
1056 .B mkfs.xfs
1057 command to terminate the branch of the filesystem it
1058 is currently on and then continue
1059 from the directory specified by
1060 the next line, in this case line 8.
1061 It must be the last character
1062 on a line.
1063 The colon
1064 on line 12 introduces a comment; all characters up until the
1065 following newline are ignored.
1066 Note that this means you cannot
1067 have a file in a prototype file whose name contains a colon.
1068 The
1069 .B $
1070 on lines 13 and 14 end the process, since no additional
1071 specifications follow.
1072 .IP
1073 File specifications provide the following:
1074 .IP
1075 * file mode
1076 .br
1077 * user ID
1078 .br
1079 * group ID
1080 .br
1081 * the file's beginning contents
1082 .P
1083 .IP
1084 A 6-character string defines the mode for
1085 a file. The first character of this string
1086 defines the file type. The character range
1087 for this first character is
1088 .B \-bcdpl.
1089 A file may be a regular file, a block special file,
1090 a character special file, directory files, named
1091 pipes (first-in, first out files), and symbolic
1092 links.
1093 The second character of the mode string is
1094 used to specify setuserID mode, in which case
1095 it is
1096 .BR u .
1097 If setuserID mode is not specified, the second character is
1098 .BR \- .
1099 The third character of the mode string is
1100 used to specify the setgroupID mode, in which
1101 case it is
1102 .BR g .
1103 If setgroupID mode is not specified, the third character is
1104 .BR \- .
1105 The remaining characters of the mode string are
1106 a three digit octal number. This octal number
1107 defines the owner, group, and other read, write,
1108 and execute permissions for the file, respectively.
1109 For more information on file permissions, see the
1110 .BR chmod (1)
1111 command.
1112 .IP
1113 Following the mode character string are two
1114 decimal number tokens that specify the user and group IDs
1115 of the file's owner.
1116 .IP
1117 In a regular file, the next token specifies the
1118 pathname from which the contents and size of the
1119 file are copied.
1120 In a block or character special file, the next token
1121 are two decimal numbers that specify the major and minor
1122 device numbers.
1123 When a file is a symbolic link, the next token
1124 specifies the contents of the link.
1125
1126 When the file is a directory, the
1127 .B mkfs.xfs
1128 command creates the entries
1129 .B dot
1130 (.) and
1131 .B dot-dot
1132 (..) and then reads the list of names and file specifications
1133 in a recursive manner for all of the entries
1134 in the directory. A scan of the protofile is
1135 always terminated with the dollar (
1136 .B $
1137 ) token.
1138 .TP
1139 .BI slashes_are_spaces= value
1140 If set to 1, slashes ("/") in the first token of each line of the protofile
1141 are converted to spaces.
1142 This enables the creation of a filesystem containing filenames with spaces.
1143 By default, this is set to 0.
1144 .RE
1145 .TP
1146 .B \-q
1147 Quiet option. Normally
1148 .B mkfs.xfs
1149 prints the parameters of the filesystem
1150 to be constructed;
1151 the
1152 .B \-q
1153 flag suppresses this.
1154 .PP
1155 .PD 0
1156 .BI \-r " realtime_section_options"
1157 .TP
1158 .BI "Section Name: " [realtime]
1159 .PD
1160 These options specify the location, size, and other parameters of the
1161 real-time section of the filesystem. The valid
1162 .I realtime_section_options
1163 are:
1164 .RS 1.2i
1165 .TP
1166 .BI rtdev= device
1167 This is used to specify the
1168 .I device
1169 which should contain the real-time section of the filesystem.
1170 The suboption value is the name of a block device.
1171 .TP
1172 .BI extsize= value
1173 This is used to specify the size of the blocks in the real-time
1174 section of the filesystem. This
1175 .I value
1176 must be a multiple of the filesystem block size. The minimum allowed
1177 size is the filesystem block size or 4 KiB (whichever is larger); the
1178 default size is the stripe width for striped volumes or 64 KiB for
1179 non-striped volumes; the maximum allowed size is 1 GiB. The real-time
1180 extent size should be carefully chosen to match the parameters of the
1181 physical media used.
1182 .TP
1183 .BI size= value
1184 This is used to specify the size of the real-time section.
1185 This suboption is only needed if the real-time section of the
1186 filesystem should occupy less space than the size of the partition
1187 or logical volume containing the section.
1188 .TP
1189 .BI noalign
1190 This option disables stripe size detection, enforcing a realtime device with no
1191 stripe geometry.
1192 .TP
1193 .BI rgcount= value
1194 This is used to specify the number of allocation groups in the realtime
1195 section.
1196 The realtime section of the filesystem can be divided into allocation groups to
1197 improve the performance of XFS.
1198 More allocation groups imply that more parallelism can be achieved when
1199 allocating blocks.
1200 The minimum allocation group size is 2 realtime extents; the maximum size is
1201 2^31 blocks.
1202 The rt section of the filesystem is divided into
1203 .I value
1204 allocation groups (default value is scaled automatically based
1205 on the underlying device size).
1206 .TP
1207 .BI rgsize= value
1208 This is an alternative to using the
1209 .B rgcount
1210 suboption. The
1211 .I value
1212 is the desired size of the realtime allocation group expressed in bytes
1213 (usually using the
1214 .BR m " or " g
1215 suffixes).
1216 This value must be a multiple of the realtime extent size,
1217 must be at least two realtime extents, and no more than 2^31 blocks.
1218 The
1219 .B rgcount
1220 and
1221 .B rgsize
1222 suboptions are mutually exclusive.
1223 .TP
1224 .BI concurrency= value
1225 Create enough realtime allocation groups to handle the desired level of
1226 concurrency.
1227 The goal of this calculation scheme is to set the number of rtgroups to an
1228 integer multiple of the number of writer threads desired, to minimize
1229 contention of rtgroup locks.
1230 This scheme will neither create fewer rtgroups than would be created by the
1231 default configuration, nor will it create rtgroups smaller than 4GB.
1232 This option is not compatible with the
1233 .B rgcount
1234 or
1235 .B rgsize
1236 options.
1237 The magic value
1238 .I nr_cpus
1239 or
1240 .I 1
1241 or no value at all will set this parameter to the number of active processors
1242 in the system.
1243 If the kernel advertises that the realtime device is a non-mechanical storage
1244 device,
1245 .B mkfs.xfs
1246 will use this new geometry calculation scheme.
1247 The magic value of
1248 .I 0
1249 forces use of the older rtgroups geometry calculations that is used for
1250 mechanical storage.
1251 .RE
1252 .PP
1253 .PD 0
1254 .BI \-s " sector_size_options"
1255 .TP
1256 .BI "Section Name: " [sector]
1257 .PD
1258 This option specifies the fundamental sector size of the filesystem.
1259 The valid
1260 .I sector_size_option
1261 is:
1262 .RS 1.2i
1263 .TP
1264 .BI size= value
1265 The sector size is specified with a
1266 .I value
1267 in bytes. The default
1268 .I sector_size
1269 is 512 bytes. The minimum value for sector size is
1270 512; the maximum is 32768 (32 KiB). The
1271 .I sector_size
1272 must be a power of 2 size and cannot be made larger than the
1273 filesystem block size.
1274 .RE
1275 .TP
1276 .BI \-L " label"
1277 Set the filesystem
1278 .IR label .
1279 XFS filesystem labels can be at most 12 characters long; if
1280 .I label
1281 is longer than 12 characters,
1282 .B mkfs.xfs
1283 will not proceed with creating the filesystem. Refer to the
1284 .BR mount "(8) and " xfs_admin (8)
1285 manual entries for additional information.
1286 .TP
1287 .B \-N
1288 Causes the file system parameters to be printed out without really
1289 creating the file system.
1290 .TP
1291 .B \-K
1292 Do not attempt to discard blocks at mkfs time.
1293 .TP
1294 .B \-V
1295 Prints the version number and exits.
1296 .SH Configuration File Format
1297 The configuration file uses a basic INI format to specify sections and options
1298 within a section.
1299 Section and option names are case sensitive.
1300 Section names must not contain whitespace.
1301 Options are name-value pairs, ended by the first whitespace in the line.
1302 Option names cannot contain whitespace.
1303 Full line comments can be added by starting a line with a # symbol.
1304 If values contain whitespace, then it must be quoted.
1305 .PP
1306 The following example configuration file sets the block size to 4096 bytes,
1307 turns on reverse mapping btrees and sets the inode size to 2048 bytes.
1308 .PP
1309 .PD 0
1310 # Example mkfs.xfs configuration file
1311 .HP
1312 .HP
1313 [block]
1314 .HP
1315 size=4k
1316 .HP
1317 .HP
1318 [metadata]
1319 .HP
1320 rmapbt=1
1321 .HP
1322 .HP
1323 [inode]
1324 .HP
1325 size=2048
1326 .HP
1327 .PD
1328 .PP
1329 .SH SEE ALSO
1330 .BR xfs (5),
1331 .BR mkfs (8),
1332 .BR mount (8),
1333 .BR xfs_info (8),
1334 .BR xfs_admin (8).
1335 .SH BUGS
1336 With a prototype file, it is not possible to specify hard links.