1mkfs.xfs(8) System Manager's Manual mkfs.xfs(8)
2
6 mkfs.xfs - construct an XFS filesystem
7
9 mkfs.xfs [ -b block_size ] [ -d data_section_options ] [ -f ] [ -i
10 inode_options ] [ -l log_section_options ] [ -n naming_options ] [ -p
11 protofile ] [ -q ] [ -r realtime_section_options ] [ -s sector_size ] [
12 -L label ] [ -N ] device
13
15 mkfs.xfs constructs an XFS filesystem by writing on a special file
16 using the values found in the arguments of the command line. It is
17 invoked automatically by mkfs(8) when it is given the -t xfs option.
18 In its simplest (and most commonly used form), the size of the filesys‐
20 tem is determined from the disk driver. As an example, to make a
21 filesystem with an internal log on the first partition on the first
22 SCSI disk, use:
23 mkfs.xfs /dev/sda1
25 The metadata log can be placed on another device to reduce the number
27 of disk seeks. To create a filesystem on the first partition on the
28 first SCSI disk with a 10000 block log located on the first partition
29 on the second SCSI disk, use:
30 mkfs.xfs -l logdev=/dev/sdb1,size=10000b /dev/sda1
32 Each of the option elements in the argument list above can be given as
34 multiple comma-separated suboptions if multiple suboptions apply to the
35 same option. Equivalently, each main option can be given multiple
36 times with different suboptions. For example, -l internal,size=10000b
37 and -l internal -l size=10000b are equivalent.
38 In the descriptions below, sizes are given in sectors, bytes, blocks,
40 kilobytes, megabytes, gigabytes, etc. Sizes are treated as hexadecimal
41 if prefixed by 0x or 0X, octal if prefixed by 0, or decimal otherwise.
42 The following lists possible multiplication suffixes:
43 s - multiply by sector size (default = 512, see -s option
44 below).
45 b - multiply by filesystem block size (default = 4K, see -b
46 option below).
47 k - multiply by one kilobyte (1,024 bytes).
48 m - multiply by one megabyte (1,048,576 bytes).
49 g - multiply by one gigabyte (1,073,741,824 bytes).
50 t - multiply by one terabyte (1,099,511,627,776 bytes).
51 p - multiply by one petabyte (1,024 terabytes).
52 e - multiply by one exabyte (1,048,576 terabytes).
53
55 -b block_size_options
56 This option specifies the fundamental block size of the filesys‐
57 tem. The valid block_size_options are: log=value or size=value
58 and only one can be supplied. The block size is specified
59 either as a base two logarithm value with log=, or in bytes with
60 size=. The default value is 4096 bytes (4 KiB), the minimum is
61 512, and the maximum is 65536 (64 KiB). XFS on Linux currently
62 only supports pagesize or smaller blocks.
63 -d data_section_options
65 These options specify the location, size, and other parameters
66 of the data section of the filesystem. The valid data_sec‐
67 tion_options are:
68 agcount=value
70 This is used to specify the number of allocation
71 groups. The data section of the filesystem is
72 divided into allocation groups to improve the per‐
73 formance of XFS. More allocation groups imply that
74 more parallelism can be achieved when allocating
75 blocks and inodes. The minimum allocation group size
76 is 16 MiB; the maximum size is just under 1 TiB.
77 The data section of the filesystem is divided into
78 value allocation groups (default value is scaled
79 automatically based on the underlying device size).
80 agsize=value
82 This is an alternative to using the agcount subop‐
83 tion. The value is the desired size of the alloca‐
84 tion group expressed in bytes (usually using the m
85 or g suffixes). This value must be a multiple of
86 the filesystem block size, and must be at least
87 16MiB, and no more than 1TiB, and may be automati‐
88 cally adjusted to properly align with the stripe
89 geometry. The agcount and agsize suboptions are
90 mutually exclusive.
91 name=value
93 This can be used to specify the name of the special
94 file containing the filesystem. In this case, the
95 log section must be specified as internal (with a
96 size, see the -l option below) and there can be no
97 real-time section.
98 file[=value]
100 This is used to specify that the file given by the
101 name suboption is a regular file. The value is
102 either 0 or 1, with 1 signifying that the file is
103 regular. This suboption is used only to make a
104 filesystem image. If the value is omitted then 1 is
105 assumed.
106 size=value
108 This is used to specify the size of the data sec‐
109 tion. This suboption is required if -d file[=1] is
110 given. Otherwise, it is only needed if the filesys‐
111 tem should occupy less space than the size of the
112 special file.
113 sunit=value
115 This is used to specify the stripe unit for a RAID
116 device or a logical volume. The value has to be
117 specified in 512-byte block units. Use the su subop‐
118 tion to specify the stripe unit size in bytes. This
119 suboption ensures that data allocations will be
120 stripe unit aligned when the current end of file is
121 being extended and the file size is larger than
122 512KiB. Also inode allocations and the internal log
123 will be stripe unit aligned.
124 su=value
126 This is an alternative to using sunit. The su sub‐
127 option is used to specify the stripe unit for a RAID
128 device or a striped logical volume. The value has to
129 be specified in bytes, (usually using the m or g
130 suffixes). This value must be a multiple of the
131 filesystem block size.
132 swidth=value
134 This is used to specify the stripe width for a RAID
135 device or a striped logical volume. The value has to
136 be specified in 512-byte block units. Use the sw
137 suboption to specify the stripe width size in bytes.
138 This suboption is required if -d sunit has been
139 specified and it has to be a multiple of the -d
140 sunit suboption.
141 sw=value
143 suboption is an alternative to using swidth. The sw
144 suboption is used to specify the stripe width for a
145 RAID device or striped logical volume. The value is
146 expressed as a multiplier of the stripe unit, usu‐
147 ally the same as the number of stripe members in the
148 logical volume configuration, or data disks in a
149 RAID device.
150 When a filesystem is created on a logical volume
152 device, mkfs.xfs will automatically query the logi‐
153 cal volume for appropriate sunit and swidth values.
154 unwritten[=value]
156 This is used to specify whether unwritten extents
157 are flagged as such, or not. The value is either 0
158 or 1, with 1 signifying that unwritten extent flag‐
159 ging should occur. If the suboption is omitted,
160 unwritten extent flagging is enabled. If unwritten
161 extents are flagged, filesystem write performance
162 will be negatively affected for preallocated file
163 extents, since extra filesystem transactions are
164 required to convert extent flags for the range of
165 the file written. This suboption should be disabled
166 if the filesystem needs to be used on operating sys‐
167 tem versions which do not support the flagging capa‐
168 bility.
169 -f Force overwrite when an existing filesystem is detected on the
171 device. By default, mkfs.xfs will not write to the device if it
172 suspects that there is a filesystem or partition table on the
173 device already.
174 -i inode_options
176 This option specifies the inode size of the filesystem, and
177 other inode allocation parameters. The XFS inode contains a
178 fixed-size part and a variable-size part. The variable-size
179 part, whose size is affected by this option, can contain: direc‐
180 tory data, for small directories; attribute data, for small
181 attribute sets; symbolic link data, for small symbolic links;
182 the extent list for the file, for files with a small number of
183 extents; and the root of a tree describing the location of
184 extents for the file, for files with a large number of extents.
185 The valid inode_options are:
187 size=value | log=value | perblock=value
189 The inode size is specified either as a value in
190 bytes with size=, a base two logarithm value with
191 log=, or as the number fitting in a filesystem block
192 with perblock=. The mininum (and default) value is
193 256 bytes. The maximum value is 2048 (2 KiB) sub‐
194 ject to the restriction that the inode size cannot
195 exceed one half of the filesystem block size.
196 XFS uses 64-bit inode numbers internally; however,
198 the number of significant bits in an inode number is
199 affected by filesystem geometry. In practice,
200 filesystem size and inode size are the predominant
201 factors. The Linux kernel (on 32 bit hardware plat‐
202 forms) and most applications cannot currently handle
203 inode numbers greater than 32 significant bits, so
204 if no inode size is given on the command line,
205 mkfs.xfs will attempt to choose a size such that
206 inode numbers will be < 32 bits. If an inode size
207 is specified, or if a filesystem is sufficently
208 large, mkfs.xfs will warn if this will create inode
209 numbers > 32 significant bits.
210 maxpct=value
212 This specifies the maximum percentage of space in
213 the filesystem that can be allocated to inodes. The
214 default value is 25%. Setting the value to 0 means
215 that essentially all of the filesystem can become
216 inode blocks.
217 align[=value]
219 This is used to specify that inode allocation is or
220 is not aligned. The value is either 0 or 1, with 1
221 signifying that inodes are allocated aligned. If
222 the value is omitted, 1 is assumed. The default is
223 that inodes are aligned. Aligned inode access is
224 normally more efficient than unaligned access;
225 alignment must be established at the time the
226 filesystem is created, since inodes are allocated at
227 that time. This option can be used to turn off
228 inode alignment when the filesystem needs to be
229 mountable by a version of IRIX that does not have
230 the inode alignment feature (any release of IRIX
231 before 6.2, and IRIX 6.2 without XFS patches).
232 attr[=value]
234 This is used to specify the version of extended
235 attribute inline allocation policy to be used. By
236 default, this is zero. Once extended attributes are
237 used for the first time, the version will be set to
238 either one or two. The current version (two) uses a
239 more efficient algorithm for managing the available
240 inline inode space than version one does, however,
241 for backward compatibility reasons (and in the
242 absence of the attr=2 mkfs option, or the attr2
243 mount option), version one will be selected by
244 default when attributes are first used on a filesys‐
245 tem.
246 -l log_section_options
248 These options specify the location, size, and other parameters
249 of the log section of the filesystem. The valid log_sec‐
250 tion_options are:
251 internal[=value]
253 This is used to specify that the log section is a
254 piece of the data section instead of being another
255 device or logical volume. The value is either 0 or
256 1, with 1 signifying that the log is internal. If
257 the value is omitted, 1 is assumed.
258 logdev=device
260 This is used to specify that the log section should
261 reside on the device separate from the data section.
262 The internal=1 and logdev options are mutually
263 exclusive.
264 size=value
266 This is used to specify the size of the log section.
267 If the log is contained within the data section and
269 size isn't specified, mkfs.xfs will try to select a
270 suitable log size depending on the size of the
271 filesystem. The actual logsize depends on the
272 filesystem block size and the directory block size.
273 Otherwise, the size suboption is only needed if the
275 log section of the filesystem should occupy less
276 space than the size of the special file. The value
277 is specified in bytes or blocks, with a b suffix
278 meaning multiplication by the filesystem block size,
279 as described above. The overriding minimum value for
280 size is 512 blocks. With some combinations of
281 filesystem block size, inode size, and directory
282 block size, the minimum log size is larger than 512
283 blocks.
284 version=value
286 This specifies the version of the log. The value is
287 either 1 or 2. Specifying version=2 enables the
288 sunit suboption, and allows the logbsize to be
289 increased beyond 32K. Version 2 logs are automati‐
290 cally selected if a log stripe unit is specified.
291 See sunit and su suboptions, below.
292 sunit=value
294 This specifies the alignment to be used for log
295 writes. The value has to be specified in 512-byte
296 block units. Use the su suboption to specify the log
297 stripe unit size in bytes. Log writes will be
298 aligned on this boundary, and rounded up to this
299 boundary. This gives major improvements in perfor‐
300 mance on some configurations such as software RAID5
301 when the sunit is specified as the filesystem block
302 size. The equivalent byte value must be a multiple
303 of the filesystem block size. Version 2 logs are
304 automatically selected if the log sunit suboption is
305 specified.
306 The su suboption is an alternative to using sunit.
308 su=value
310 This is used to specify the log stripe. The value
311 has to be specified in bytes, (usually using the s
312 or b suffixes). This value must be a multiple of the
313 filesystem block size. Version 2 logs are automati‐
314 cally selected if the log su suboption is specified.
315 lazy-count=value
317 This changes the method of logging various persis‐
318 tent counters in the superblock. Under metadata
319 intensive workloads, these counters are updated and
320 logged frequently enough that the superblock updates
321 become a serialisation point in the filesystem. The
322 value can be either 0 or 1.
323 With lazy-count=1, the superblock is not modified or
325 logged on every change of the persistent counters.
326 Instead, enough information is kept in other parts
327 of the filesystem to be able to maintain the persis‐
328 tent counter values without needed to keep them in
329 the superblock. This gives significant improvements
330 in performance on some configurations. The default
331 value is 0 (off) so you must specify lazy-count=1 if
332 you want to make use of this feature.
333 -n naming_options
335 These options specify the version and size parameters for the
336 naming (directory) area of the filesystem. The valid nam‐
337 ing_options are:
338 size=value | log=value
340 The block size is specified either as a value in
341 bytes with size=, or as a base two logarithm value
342 with log=. The default size value for version 2
343 directories is 4096 bytes (4 KiB), unless the
344 filesystem block size is larger than 4096, in which
345 case the default value is the filesystem block size.
346 For version 1 directories the block size is the same
347 as the filesystem block size.
348 version=value
350 The naming (directory) version value can be either 1
351 or 2, defaulting to 2 if unspecified. With version
352 2 directories, the directory block size can be any
353 power of 2 size from the filesystem block size up to
354 65536.
355 -p protofile
357 If the optional -p protofile argument is given, mkfs.xfs uses
358 protofile as a prototype file and takes its directions from that
359 file. The blocks and inodes specifiers in the protofile are
360 provided for backwards compatibility, but are otherwise unused.
361 The syntax of the protofile is defined by a number of tokens
362 separated by spaces or newlines. Note that the line numbers are
363 not part of the syntax but are meant to help you in the follow‐
364 ing discussion of the file contents.
365 1 /stand/diskboot
367 2 4872 110
368 3 d--777 3 1
369 4 usr d--777 3 1
370 5 sh ---755 3 1 /bin/sh
371 6 ken d--755 6 1
372 7 $
373 8 b0 b--644 3 1 0 0
374 9 c0 c--644 3 1 0 0
375 10 fifo p--644 3 1
376 11 slink l--644 3 1 /a/symbolic/link
377 12 : This is a comment line
378 13 $
379 14 $
380 Line 1 is a dummy string. (It was formerly the bootfilename.)
382 It is present for backward compatibility; boot blocks are not
383 used on SGI systems.
384 Note that some string of characters must be present as the first
386 line of the proto file to cause it to be parsed correctly; the
387 value of this string is immaterial since it is ignored.
388 Line 2 contains two numeric values (formerly the numbers of
390 blocks and inodes). These are also merely for backward compati‐
391 bility: two numeric values must appear at this point for the
392 proto file to be correctly parsed, but their values are immate‐
393 rial since they are ignored.
394 The lines 3 through 11 specify the files and directories you
396 want to include in this filesystem. Line 3 defines the root
397 directory. Other directories and files that you want in the
398 filesystem are indicated by lines 4 through 6 and lines 8
399 through 10. Line 11 contains symbolic link syntax.
400 Notice the dollar sign ($) syntax on line 7. This syntax directs
402 the mkfs.xfs command to terminate the branch of the filesystem
403 it is currently on and then continue from the directory speci‐
404 fied by the next line,in this case line 8 It must be the last
405 character on a line. The colon on line 12 introduces a comment;
406 all characters up until the following newline are ignored. Note
407 that this means you cannot have a file in a prototype file whose
408 name contains a colon. The $ on lines 13 and 14 end the
409 process, since no additional specifications follow.
410 File specifications provide the following:
412 * file mode
414 * user ID
415 * group ID
416 * the file's beginning contents
417 A 6-character string defines the mode for a file. The first
419 character of this string defines the file type. The character
420 range for this first character is -bcdpl. A file may be a regu‐
421 lar file, a block special file, a character special file, direc‐
422 tory files, named pipes (first-in, first out files), and sym‐
423 bolic links. The second character of the mode string is used to
424 specify setuserID mode, in which case it is u. If setuserID
425 mode is not specified, the second character is -. The third
426 character of the mode string is used to specify the setgroupID
427 mode, in which case it is g. If setgroupID mode is not speci‐
428 fied, the second character is -. The remaining characters of
429 the mode string are a three digit octal number. This octal num‐
430 ber defines the owner, group, and other read, write, and execute
431 permissions for the file, respectively. Form more information
432 on file permissions, see the chmod(1) command.
433 Following the mode character string are two decimal number
435 tokens that specify the user and group IDs of the file's owner.
436 In a regular file, the next token specifies the pathname from
438 which the contents and size of the file are copied. In a block
439 or character special file, the next token are two decimal num‐
440 bers that specify the major and minor device numbers. When a
441 file is a symbolic link, the next token specifies the contents
442 of the link.
443 When the file is a directory, the mkfs.xfs command creates the
445 entries dot (.) and dot-dot (..) and then reads the list of
446 names and file specifications in a recursive manner for all of
447 the entries in the directory. A scan of the protofile is always
448 terminated with the dollar ( $ ) token.
449 -q Quiet option. Normally mkfs.xfs prints the parameters of the
451 filesystem to be constructed; the -q flag suppresses this.
452 -r realtime_section_options
454 These options specify the location, size, and other parameters
455 of the real-time section of the filesystem. The valid real‐
456 time_section_options are:
457 rtdev=device
459 This is used to specify the device which should con‐
460 tain the real-time section of the filesystem. The
461 suboption value is the name of a block device.
462 extsize=value
464 This is used to specify the size of the blocks in
465 the real-time section of the filesystem. This value
466 must be a multiple of the filesystem block size. The
467 minimum allowed size is the filesystem block size or
468 4 KiB (whichever is larger); the default size is the
469 stripe width for striped volumes or 64 KiB for non-
470 striped volumes; the maximum allowed size is 1 GiB.
471 The real-time extent size should be carefully chosen
472 to match the parameters of the physical media used.
473 size=value
475 This is used to specify the size of the real-time
476 section. This suboption is only needed if the real-
477 time section of the filesystem should occupy less
478 space than the size of the partition or logical vol‐
479 ume containing the section.
480 -s sector_size
482 This option specifies the fundamental sector size of the
483 filesystem. The sector_size is specified either as a value in
484 bytes with size=value or as a base two logarithm value with
485 log=value. The default sector_size is 512 bytes. The minimum
486 value for sector size is 512; the maximum is 32768 (32 KiB). The
487 sector_size must be a power of 2 size and cannot be made larger
488 than the filesystem block size.
489 -L label
491 Set the filesystem label. XFS filesystem labels can be at most
492 12 characters long; if label is longer than 12 characters,
493 mkfs.xfs will not proceed with creating the filesystem. Refer
494 to the mount(8) and xfs_admin(8) manual entries for additional
495 information.
496 -N Causes the file system parameters to be printed out without
498 really creating the file system.
499
501 xfs(5), mkfs(8), mount(8), xfs_info(8), xfs_admin(8).
502
504 With a prototype file, it is not possible to specify hard links.
505 mkfs.xfs(8)