Debian Codegraph @

upstream/debian-unstable/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 prototype_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 .TP
746 .BI max_atomic_write[= value]
747 When enabled, application programs can use the RWF_ATOMIC write flag to
748 persist changes of up to this size without tearing.
749 The default is chosen to allow a reasonable amount of scalability.
750 This value must also be passed via mount option.
751 This feature is only available for filesystems formatted with reflink.
752 .RE
753 .PP
754 .PD 0
755 .BI \-l " log_section_options"
756 .TP
757 .BI "Section Name: " [log]
758 .PD
759 These options specify the location, size, and other parameters of the
760 log section of the filesystem. The valid
761 .I log_section_options
762 are:
763 .RS 1.2i
764 .TP
765 .BI agnum= value
766 If the log is internal, allocate it in this AG.
767 .TP
768 .BI internal[= value ]
769 This is used to specify that the log section is a piece of the data
770 section instead of being another device or logical volume. The
771 .I value
772 is either 0 or 1, with 1 signifying that the log is internal. If the
773 .I value
774 is omitted, 1 is assumed.
775 .TP
776 .BI logdev= device
777 This is used to specify that the log section should reside on the
778 .I device
779 separate from the data section. The
780 .B internal=1
781 and
782 .B logdev
783 options are mutually exclusive.
784 .TP
785 .BI size= value
786 This is used to specify the size of the log section.
787 .IP
788 If the log is contained within the data section and
789 .B size
790 isn't specified,
791 .B mkfs.xfs
792 will try to select a suitable log size depending
793 on the size of the filesystem. The actual logsize depends on the
794 filesystem block size and the directory block size.
795 .IP
796 Otherwise, the
797 .B size
798 suboption is only needed if the log section of the filesystem
799 should occupy less space than the size of the special file. The
800 .I value
801 is specified in bytes or blocks, with a
802 .B b
803 suffix meaning multiplication by the filesystem block size, as
804 described above. The overriding minimum value for size is 512 blocks.
805 With some combinations of filesystem block size, inode size,
806 and directory block size, the minimum log size is larger than 512 blocks.
807
808 The log must be at least 64MB in size.
809 The log cannot be more than 2GB in size.
810 .TP
811 .BI version= value
812 This specifies the version of the log. The current default is 2,
813 which allows for larger log buffer sizes, as well as supporting
814 stripe-aligned log writes (see the sunit and su options, below).
815 .IP
816 The previous version 1, which is limited to 32k log buffers and does
817 not support stripe-aligned writes, is kept for backwards compatibility
818 with very old 2.4 kernels.
819 .IP
820 This option is only tunable on the deprecated V4 format.
821 .TP
822 .BI sunit= value
823 This specifies the alignment to be used for log writes. The
824 .I value
825 has to be specified in 512-byte block units. Use the
826 .B su
827 suboption to specify the log stripe unit size in bytes.
828 Log writes will be aligned on this boundary,
829 and rounded up to this boundary.
830 This gives major improvements in performance on some configurations
831 such as software RAID5 when the
832 .B sunit
833 is specified as the filesystem block size.
834 The equivalent byte value must be a multiple of the filesystem block
835 size. Version 2 logs are automatically selected if the log
836 .B sunit
837 suboption is specified.
838 .IP
839 The
840 .B su
841 suboption is an alternative to using
842 .B sunit.
843 .TP
844 .BI su= value
845 This is used to specify the log stripe. The
846 .I value
847 has to be specified in bytes, (usually using the
848 .BR s " or " b
849 suffixes). This value must be a multiple of the filesystem block size.
850 Version 2 logs are automatically selected if the log
851 .B su
852 suboption is specified.
853 .TP
854 .BI lazy-count= value
855 This changes the method of logging various persistent counters
856 in the superblock. Under metadata intensive workloads, these
857 counters are updated and logged frequently enough that the superblock
858 updates become a serialization point in the filesystem. The
859 .I value
860 can be either 0 or 1.
861 .IP
862 With
863 .BR lazy-count=1 ,
864 the superblock is not modified or logged on every change of the
865 persistent counters. Instead, enough information is kept in
866 other parts of the filesystem to be able to maintain the persistent
867 counter values without needed to keep them in the superblock.
868 This gives significant improvements in performance on some configurations.
869 The default
870 .I value
871 is 1 (on) so you must specify
872 .B lazy-count=0
873 if you want to disable this feature for older kernels which don't support
874 it.
875 .IP
876 This option is only tunable on the deprecated V4 format.
877 .TP
878 .BI concurrency= value
879 Allocate a log that is estimated to be large enough to handle the desired level
880 of concurrency without userspace program threads contending for log space.
881 This scheme will neither create a log smaller than the minimum required,
882 nor create a log larger than the maximum possible.
883 This option is only valid for internal logs and is not compatible with the
884 size option.
885 This option is not compatible with the
886 .B logdev
887 or
888 .B size
889 options.
890 The magic value
891 .I nr_cpus
892 or
893 .I 1
894 or no value at all will set this parameter to the number of active processors
895 in the system.
896 .RE
897 .PP
898 .PD 0
899 .BI \-n " naming_options"
900 .TP
901 .BI "Section Name: " [naming]
902 .PD
903 These options specify the version and size parameters for the naming
904 (directory) area of the filesystem. The valid
905 .I naming_options
906 are:
907 .RS 1.2i
908 .TP
909 .BI size= value
910 The directory block size is specified with a
911 .I value
912 in bytes. The block size must be a power of 2 and cannot be less than the
913 filesystem block size.
914 The default size
915 .I value
916 for version 2 directories is 4096 bytes (4 KiB),
917 unless the filesystem block size is larger than 4096,
918 in which case the default
919 .I value
920 is the filesystem block size.
921 For version 1 directories the block size is the same as the
922 filesystem block size.
923 .TP
924 .BI version= value
925 The naming (directory) version
926 .I value
927 can be either 2 or 'ci', defaulting to 2 if unspecified.
928 With version 2 directories, the directory block size can be
929 any power of 2 size from the filesystem block size up to 65536.
930 .IP
931 If the
932 .B version=ci
933 option is specified, the kernel will transform certain bytes in filenames
934 before performing lookup-related operations.
935 The byte sequence given to create a directory entry is persisted without
936 alterations.
937 The lookup transformations are defined as follows:
938
939 0x41-0x5a -> 0x61-0x7a
940
941 0xc0-0xd6 -> 0xe0-0xf6
942
943 0xd8-0xde -> 0xf8-0xfe
944
945 This transformation roughly corresponds to case insensitivity in ISO
946 8859-1.
947 The transformations are not compatible with other encodings (e.g. UTF8).
948 Do not enable this feature unless your entire environment has been coerced
949 to ISO 8859-1.
950 This feature is deprecated and will be removed in September 2030.
951 .IP
952 Note: Version 1 directories are not supported.
953 .TP
954 .BI ftype= value
955 This feature allows the inode type to be stored in the directory
956 structure so that the
957 .BR readdir (3)
958 and
959 .BR getdents (2)
960 do not need to look up the inode to determine the inode type.
961
962 The
963 .I value
964 is either 0 or 1, with 1 signifying that filetype information
965 will be stored in the directory structure. The default value is 1.
966
967 When CRCs are enabled (the default), the ftype functionality is always
968 enabled, and cannot be turned off.
969 .IP
970 In other words, this option is only tunable on the deprecated V4 format.
971 .TP
972 .BI parent= value
973 This feature creates back references from child files to parent directories
974 so that online repair can reconstruct broken directory files.
975 The value is either 0 to disable the feature, or 1 to create parent pointers.
976
977 By default,
978 .B mkfs.xfs
979 will not create parent pointers.
980 This feature is only available for filesystems created with the (default)
981 .B \-m crc=1
982 option set.
983 .RE
984 .PP
985 .PD 0
986 .TP
987 .BI \-p " prototype_options"
988 .TP
989 .BI "Section Name: " [proto]
990 .PD
991 These options specify the prototype parameters for populating the filesystem.
992 The valid
993 .I prototype_options
994 are:
995 .RS 1.2i
996 .TP
997 .BI [file=]
998 The
999 .B file=
1000 prefix is not required for this CLI argument for legacy reasons.
1001 If specified as a config file directive, the prefix is required.
1002 .TP
1003 .BI [file=] directory
1004 If the optional
1005 .PD
1006 .I prototype
1007 argument is given, and it's a directory,
1008 .B mkfs.xfs
1009 will populate the root file system with the contents of the given directory
1010 tree.
1011 Content, timestamps (atime, mtime), attributes and extended attributes
1012 are preserved for all file types.
1013 .TP
1014 .BI [file=] protofile
1015 If the optional
1016 .PD
1017 .I prototype
1018 argument is given, and points to a regular file,
1019 .B mkfs.xfs
1020 uses it as a prototype file and takes its directions from that file.
1021 The blocks and inodes specifiers in the
1022 .I protofile
1023 are provided for backwards compatibility, but are otherwise unused.
1024 The syntax of the protofile is defined by a number of tokens separated
1025 by spaces or newlines. Note that the line numbers are not part of the
1026 syntax but are meant to help you in the following discussion of the file
1027 contents.
1028 .nf
1029 .sp .8v
1030 .in +5
1031 \f71 /stand/\f1\f2diskboot\f1\f7
1032 2 4872 110
1033 3 d\-\-777 3 1
1034 4 usr d\-\-777 3 1
1035 5 sh \-\-\-755 3 1 /bin/sh
1036 6 ken d\-\-755 6 1
1037 7 $
1038 8 b0 b\-\-644 3 1 0 0
1039 9 c0 c\-\-644 3 1 0 0
1040 10 fifo p\-\-644 3 1
1041 11 slink l\-\-644 3 1 /a/symbolic/link
1042 12 : This is a comment line
1043 13 $
1044 14 $\f1
1045 .in -5
1046 .fi
1047 .IP
1048 Line 1 is a dummy string.
1049 (It was formerly the bootfilename.)
1050 It is present for backward
1051 compatibility; boot blocks are not used on SGI systems.
1052 .IP
1053 Note that some string of characters must be present as the first line of
1054 the proto file to cause it to be parsed correctly; the value
1055 of this string is immaterial since it is ignored.
1056 .IP
1057 Line 2 contains two numeric values (formerly the numbers of blocks and inodes).
1058 These are also merely for backward compatibility: two numeric values must
1059 appear at this point for the proto file to be correctly parsed,
1060 but their values are immaterial since they are ignored.
1061 .IP
1062 The lines 3 through 11 specify the files and directories you want to
1063 include in this filesystem. Line 3 defines the
1064 root directory. Other directories and
1065 files that you want in the filesystem
1066 are indicated by lines 4 through 6 and
1067 lines 8 through 10. Line 11 contains
1068 symbolic link syntax.
1069 .IP
1070 Notice the dollar sign
1071 .RB ( $ )
1072 syntax on line 7. This syntax directs the
1073 .B mkfs.xfs
1074 command to terminate the branch of the filesystem it
1075 is currently on and then continue
1076 from the directory specified by
1077 the next line, in this case line 8.
1078 It must be the last character
1079 on a line.
1080 The colon
1081 on line 12 introduces a comment; all characters up until the
1082 following newline are ignored.
1083 Note that this means you cannot
1084 have a file in a prototype file whose name contains a colon.
1085 The
1086 .B $
1087 on lines 13 and 14 end the process, since no additional
1088 specifications follow.
1089 .IP
1090 File specifications provide the following:
1091 .IP
1092 * file mode
1093 .br
1094 * user ID
1095 .br
1096 * group ID
1097 .br
1098 * the file's beginning contents
1099 .P
1100 .IP
1101 A 6-character string defines the mode for
1102 a file. The first character of this string
1103 defines the file type. The character range
1104 for this first character is
1105 .B \-bcdpl.
1106 A file may be a regular file, a block special file,
1107 a character special file, directory files, named
1108 pipes (first-in, first out files), and symbolic
1109 links.
1110 The second character of the mode string is
1111 used to specify setuserID mode, in which case
1112 it is
1113 .BR u .
1114 If setuserID mode is not specified, the second character is
1115 .BR \- .
1116 The third character of the mode string is
1117 used to specify the setgroupID mode, in which
1118 case it is
1119 .BR g .
1120 If setgroupID mode is not specified, the third character is
1121 .BR \- .
1122 The remaining characters of the mode string are
1123 a three digit octal number. This octal number
1124 defines the owner, group, and other read, write,
1125 and execute permissions for the file, respectively.
1126 For more information on file permissions, see the
1127 .BR chmod (1)
1128 command.
1129 .IP
1130 Following the mode character string are two
1131 decimal number tokens that specify the user and group IDs
1132 of the file's owner.
1133 .IP
1134 In a regular file, the next token specifies the
1135 pathname from which the contents and size of the
1136 file are copied.
1137 In a block or character special file, the next token
1138 are two decimal numbers that specify the major and minor
1139 device numbers.
1140 When a file is a symbolic link, the next token
1141 specifies the contents of the link.
1142
1143 When the file is a directory, the
1144 .B mkfs.xfs
1145 command creates the entries
1146 .B dot
1147 (.) and
1148 .B dot-dot
1149 (..) and then reads the list of names and file specifications
1150 in a recursive manner for all of the entries
1151 in the directory. A scan of the protofile is
1152 always terminated with the dollar (
1153 .B $
1154 ) token.
1155 .TP
1156 .BI atime= value
1157 If set to 1, mkfs will copy in access timestamps from the source files.
1158 Otherwise, access timestamps will be set to the current time.
1159 .TP
1160 .BI slashes_are_spaces= value
1161 If set to 1, slashes ("/") in the first token of each line of the prototype file
1162 are converted to spaces.
1163 This enables the creation of a filesystem containing filenames with spaces.
1164 By default, this is set to 0.
1165 .RE
1166 .TP
1167 .B \-q
1168 Quiet option. Normally
1169 .B mkfs.xfs
1170 prints the parameters of the filesystem
1171 to be constructed;
1172 the
1173 .B \-q
1174 flag suppresses this.
1175 .PP
1176 .PD 0
1177 .BI \-r " realtime_section_options"
1178 .TP
1179 .BI "Section Name: " [realtime]
1180 .PD
1181 These options specify the location, size, and other parameters of the
1182 real-time section of the filesystem. The valid
1183 .I realtime_section_options
1184 are:
1185 .RS 1.2i
1186 .TP
1187 .BI rtdev= device
1188 This is used to specify the
1189 .I device
1190 which should contain the real-time section of the filesystem.
1191 The suboption value is the name of a block device.
1192 .TP
1193 .BI extsize= value
1194 This is used to specify the size of the blocks in the real-time
1195 section of the filesystem. This
1196 .I value
1197 must be a multiple of the filesystem block size. The minimum allowed
1198 size is the filesystem block size or 4 KiB (whichever is larger); the
1199 default size is the stripe width for striped volumes or 64 KiB for
1200 non-striped volumes; the maximum allowed size is 1 GiB. The real-time
1201 extent size should be carefully chosen to match the parameters of the
1202 physical media used.
1203 .TP
1204 .BI size= value
1205 This is used to specify the size of the real-time section.
1206 This suboption is only needed if the real-time section of the
1207 filesystem should occupy less space than the size of the partition
1208 or logical volume containing the section.
1209 .TP
1210 .BI noalign
1211 This option disables stripe size detection, enforcing a realtime device with no
1212 stripe geometry.
1213 .TP
1214 .BI rgcount= value
1215 This is used to specify the number of allocation groups in the realtime
1216 section.
1217 The realtime section of the filesystem can be divided into allocation groups to
1218 improve the performance of XFS.
1219 More allocation groups imply that more parallelism can be achieved when
1220 allocating blocks.
1221 The minimum allocation group size is 2 realtime extents; the maximum size is
1222 2^31 blocks.
1223 The rt section of the filesystem is divided into
1224 .I value
1225 allocation groups (default value is scaled automatically based
1226 on the underlying device size).
1227 .TP
1228 .BI rgsize= value
1229 This is an alternative to using the
1230 .B rgcount
1231 suboption. The
1232 .I value
1233 is the desired size of the realtime allocation group expressed in bytes
1234 (usually using the
1235 .BR m " or " g
1236 suffixes).
1237 This value must be a multiple of the realtime extent size,
1238 must be at least two realtime extents, and no more than 2^31 blocks.
1239 The
1240 .B rgcount
1241 and
1242 .B rgsize
1243 suboptions are mutually exclusive.
1244 .TP
1245 .BI concurrency= value
1246 Create enough realtime allocation groups to handle the desired level of
1247 concurrency.
1248 The goal of this calculation scheme is to set the number of rtgroups to an
1249 integer multiple of the number of writer threads desired, to minimize
1250 contention of rtgroup locks.
1251 This scheme will neither create fewer rtgroups than would be created by the
1252 default configuration, nor will it create rtgroups smaller than 4GB.
1253 This option is not compatible with the
1254 .B rgcount
1255 or
1256 .B rgsize
1257 options.
1258 The magic value
1259 .I nr_cpus
1260 or
1261 .I 1
1262 or no value at all will set this parameter to the number of active processors
1263 in the system.
1264 If the kernel advertises that the realtime device is a non-mechanical storage
1265 device,
1266 .B mkfs.xfs
1267 will use this new geometry calculation scheme.
1268 The magic value of
1269 .I 0
1270 forces use of the older rtgroups geometry calculations that is used for
1271 mechanical storage.
1272 .TP
1273 .BI zoned= value
1274 Controls if the zoned allocator is used for the realtime device.
1275 The value is either 0 to disable the feature, or 1 to enable it.
1276 Defaults to 1 for zoned block device, else 0.
1277 .TP
1278 .BI start= value
1279 Controls the start of the internal realtime section. Defaults to 0
1280 for conventional block devices, or the start of the first sequential
1281 required zone for zoned block devices.
1282 This option is only valid if the zoned realtime allocator is used.
1283 .TP
1284 .BI reserved= value
1285 Controls the amount of space in the realtime section that is reserved for
1286 internal use by garbage collection and reorganization algorithms.
1287 Defaults to 0 if not set.
1288 This option is only valid if the zoned realtime allocator is used.
1289 .RE
1290 .PP
1291 .PD 0
1292 .BI \-s " sector_size_options"
1293 .TP
1294 .BI "Section Name: " [sector]
1295 .PD
1296 This option specifies the fundamental sector size of the filesystem.
1297 The valid
1298 .I sector_size_option
1299 is:
1300 .RS 1.2i
1301 .TP
1302 .BI size= value
1303 The sector size is specified with a
1304 .I value
1305 in bytes. The default
1306 .I sector_size
1307 is 512 bytes. The minimum value for sector size is
1308 512; the maximum is 32768 (32 KiB). The
1309 .I sector_size
1310 must be a power of 2 size and cannot be made larger than the
1311 filesystem block size.
1312 .RE
1313 .TP
1314 .BI \-L " label"
1315 Set the filesystem
1316 .IR label .
1317 XFS filesystem labels can be at most 12 characters long; if
1318 .I label
1319 is longer than 12 characters,
1320 .B mkfs.xfs
1321 will not proceed with creating the filesystem. Refer to the
1322 .BR mount "(8) and " xfs_admin (8)
1323 manual entries for additional information.
1324 .TP
1325 .B \-N
1326 Causes the file system parameters to be printed out without really
1327 creating the file system.
1328 .TP
1329 .B \-K
1330 Do not attempt to discard blocks at mkfs time.
1331 .TP
1332 .B \-V
1333 Prints the version number and exits.
1334 .SH Configuration File Format
1335 The configuration file uses a basic INI format to specify sections and options
1336 within a section.
1337 Section and option names are case sensitive.
1338 Section names must not contain whitespace.
1339 Options are name-value pairs, ended by the first whitespace in the line.
1340 Option names cannot contain whitespace.
1341 Full line comments can be added by starting a line with a # symbol.
1342 If values contain whitespace, then it must be quoted.
1343 .PP
1344 The following example configuration file sets the block size to 4096 bytes,
1345 turns on reverse mapping btrees and sets the inode size to 2048 bytes.
1346 .PP
1347 .PD 0
1348 # Example mkfs.xfs configuration file
1349 .HP
1350 .HP
1351 [block]
1352 .HP
1353 size=4k
1354 .HP
1355 .HP
1356 [metadata]
1357 .HP
1358 rmapbt=1
1359 .HP
1360 .HP
1361 [inode]
1362 .HP
1363 size=2048
1364 .HP
1365 .PD
1366 .PP
1367 .SH SEE ALSO
1368 .BR xfs (5),
1369 .BR mkfs (8),
1370 .BR mount (8),
1371 .BR xfs_info (8),
1372 .BR xfs_admin (8).
1373 .SH BUGS
1374 With a prototype file, it is not possible to specify hard links.