mkfs.xfs - construct an XFS filesystem


SYNOPSIS

       mkfs.xfs [ -b subopt=value ] [ -d subopt[=value] ]
            [ -i subopt=value ] [ -l subopt[=value] ]
            [ -n subopt[=value] ] [ -p protofile ] [ -q ]
            [ -r subopt[=value] ] [ -C ] [ -L label ] device


DESCRIPTION

       mkfs.xfs constructs an XFS filesystem by writing on a spe­
       cial file using the values found in the arguments  of  the
       command line.  It is invoked automatically by mkfs(8) when
       mkfs is given the -t xfs option.

       In its simplest (and most commonly used form), the size of
       the  filesystem is determined from the disk driver.  As an
       example, to make a filesystem with an internal log on  the
       first partition on the first SCSI disk, use:

            mkfs.xfs /dev/sda1

       The metadata log can be placed on another device to reduce
       the number of disk seeks.  To create a filesystem  on  the
       first  partition on the first SCSI disk with a 10000 block
       log located on the first  partition  on  the  second  SCSI
       disk, use:

            mkfs.xfs -l logdev=/dev/sdb1,size=10000b /dev/sda1

       Each  of  the  subopt=value  elements in the argument list
       above  can  be  given  as  multiple  comma-separated  sub­
       opt=value  suboptions  if multiple suboptions apply to the
       same option.  Equivalently, each main option can be  given
       multiple times with different suboptions.  For example, -l
       internal,size=10000b and -l internal  -l  size=10000b  are
       equivalent.

       In  the  descriptions  below,  sizes are given in sectors,
       bytes, blocks, kilobytes, megabytes, or gigabytes.   Sizes
       are  treated as hexadecimal if prefixed by 0x or 0X, octal
       if prefixed by 0, or decimal otherwise.  If suffixed  with
       s  then  the  size  is  converted by multiplying it by 512
       (sector size).  If suffixed with b then the size  is  con­
       verted  by  multiplying it by the filesystem's block size.
       If suffixed with k then the size is converted by multiply­
       ing  it by 1024.  If suffixed with m then the size is con­
       verted by multiplying it by 1048576  (1024  *  1024).   If
       suffixed  with g then the size is converted by multiplying
       it by 1073741824 (1024 * 1024 * 1024).

       -b     Block size options.

              This option specifies the fundamental block size of

              log=value and size=value; only one can be supplied.
              The  block  size  is specified either as a base two
              logarithm value with log=, or in bytes with  size=.
              The  default  value is 4096 bytes (4 KB) on systems
              with a 4KB pagesize.  The minimum value  for  block
              size  is 512; the maximum is 65536 (64 KB).  XFS on
              Linux currently only supports pagesize  or  smaller
              blocks.

       -d     Data section options.

              These options specify the location, size, and other
              parameters of the data section of  the  filesystem.
              The    valid    suboptions    are:   agcount=value,
              agsize=value, file[=value], name=value, size=value,
              sunit=value,  swidth=value, su=value, sw=value, and
              unwritten[=value].

              The agcount suboption is used to specify the number
              of  allocation  groups.   The  data  section of the
              filesystem is divided  into  allocation  groups  to
              improve  the  performance  of XFS.  More allocation
              groups imply that more parallelism can be  achieved
              when  allocating  blocks  and  inodes.  The minimum
              allocation group size is 16 MB; the maximum size is
              just  under 4 GB.  The data section of the filesys­
              tem  is  divided  into  agcount  allocation  groups
              (default  value 8, unless the filesystem is smaller
              than 128 MB or larger than 8 GB).  Setting  agcount
              to  a  very  large  number should be avoided, since
              this causes an unreasonable amount of CPU  time  to
              be used when the filesystem is close to full.

              The  agsize  suboption  is  an alternative to using
              agcount.  The argument provided to  agsize  is  the
              desired  size  of the allocation group expressed in
              bytes (usually using the m or  g  suffixes).   This
              value  must  be  a multiple of the filesystem block
              size, and must be at least 16MB, and no  more  than
              4GB,  and may be automatically adjusted to properly
              align with the stripe geometry.  The agcount subop­
              tion  and  the agsize suboption are mutually exclu­
              sive.

              The name suboption can be used to specify the  name
              of  the special file containing the filesystem.  In
              this case, the log section  must  be  specified  as
              internal (with a size, see the -l option below) and
              there can be no real-time section.

              The file suboption is used to specify that the file
              given by the name suboption is a regular file.  The
              suboption value is either 0 or 1, with 1 signifying

              only to make a filesystem image.  If the  value  is
              omitted then 1 is assumed.

              The  size  suboption is used to specify the size of
              the data section.  This suboption is required if -d
              file[=1] is given.  Otherwise, it is only needed if
              the filesystem should occupy less  space  than  the
              size of the special file.

              The  sunit  suboption is used to specify the stripe
              unit for a RAID device or a  logical  volume.   The
              suboption  value  has  to  be specified in 512-byte
              block units.  Use the su suboption to  specify  the
              stripe  unit size in bytes.  This suboption ensures
              that data allocations will be stripe  unit  aligned
              when  the current end of file is being extended and
              the file size is larger  than  512KB.   Also  inode
              allocations  and  the  internal  log will be stripe
              unit aligned.

              The su suboption is an alternative to using  sunit.
              The su suboption is used to specify the stripe unit
              for a RAID device or a striped logical volume.  The
              suboption value has to be specified in bytes, (usu­
              ally using the m or g suffixes).  This  value  must
              be a multiple of the filesystem block size.

              The  swidth suboption is used to specify the stripe
              width for a RAID device or a striped  logical  vol­
              ume.   The  suboption  value has to be specified in
              512-byte block units.   Use  the  sw  suboption  to
              specify  the stripe width size in bytes.  This sub­
              option is required if -d sunit has  been  specified
              and  it has to be a multiple of the -d sunit subop­
              tion.  The  stripe  width  will  be  the  preferred
              iosize returned in the stat(2) system call.

              The sw suboption is an alternative to using swidth.
              The sw suboption is  used  to  specify  the  stripe
              width  for a RAID device or striped logical volume.
              The suboption value is expressed as a multiplier of
              the  stripe unit, usually the same as the number of
              stripe members in the logical volume configuration,
              or data disks in a RAID device.

              When  a  filesystem  is created on a logical volume
              device, mkfs.xfs will automatically query the logi­
              cal volume for appropriate sunit and swidth values.

              The unwritten suboption is used to specify  whether
              unwritten extents are flagged as such, or not.  The
              suboption value is either 0 or 1, with 1 signifying
              that  unwritten  extent  flagging should occur.  If

              is  enabled.   If  unwritten  extents  are flagged,
              filesystem write  performance  will  be  negatively
              affected for preallocated file extents, since extra
              filesystem transactions  are  required  to  convert
              extent  flags  for  the  range of the file written.
              This suboption should be disabled if the filesystem
              needs to be used on operating system versions which
              do not support the flagging capability.

       -i     Inode options.

              This  option  specifies  the  inode  size  of   the
              filesystem,  and other inode allocation parameters.
              The XFS inode contains  a  fixed-size  part  and  a
              variable-size  part.  The variable-size part, whose
              size is  affected  by  this  option,  can  contain:
              directory  data,  for  small directories; attribute
              data, for small attribute sets; symbolic link data,
              for  small  symbolic links; the extent list for the
              file, for files with a small number of extents; and
              the  root  of  a  tree  describing  the location of
              extents for the file, for files with a large number
              of extents.

              The valid suboptions for specifying inode size are:
              log=value, perblock=value, and size=value; only one
              can  be  supplied.   The  inode  size  is specified
              either as a base two logarithm value with log=,  in
              bytes  with  size=,  or  as the number fitting in a
              filesystem block with perblock=.  The mininum  (and
              default)  value is 256 bytes.  The maximum value is
              2048 (2 KB) subject to  the  restriction  that  the
              inode size cannot exceed one half of the filesystem
              block size.

              XFS uses 64-bit inode numbers internally;  however,
              the  number  of significant bits in an inode number
              is affected by filesystem geometry.   In  practice,
              filesystem  size and inode size are the predominant
              factors.  The Linux kernel  and  most  applications
              cannot  currently handle inode numbers greater than
              32 significant bits, so if no inode size  is  given
              on  the  command  line,  mkfs.xfs  will  attempt to
              choose a size such that inode numbers will be <  32
              bits.   If  an  inode  size  is  specified, or if a
              filesystem is sufficently large, mkfs.xfs will warn
              if  this will create inode numbers > 32 significant
              bits.

              The option maxpct=value specifies the maximum  per­
              centage  of  space  in  the  filesystem that can be
              allocated to inodes.  The  default  value  is  25%.
              Setting  the  value to 0 means that essentially all


              The option align[=value] is used  to  specify  that
              inode  allocation  is or is not aligned.  The value
              is either 0 or 1, with 1 signifying that inodes are
              allocated  aligned.   If the value is omitted, 1 is
              assumed.  The default is that inodes  are  aligned.
              Aligned  inode  access  is  normally more efficient
              than unaligned access;  alignment  must  be  estab­
              lished at the time the filesystem is created, since
              inodes are allocated at that time.  This option can
              be  used  to  turn  off  inode  alignment  when the
              filesystem needs to be mountable by  a  version  of
              IRIX that does not have the inode alignment feature
              (any release of IRIX before 6.2, and IRIX 6.2 with­
              out XFS patches).

       -l     Log section options.

              These options specify the location, size, and other
              parameters of the log section  of  the  filesystem.
              The   valid   suboptions   are:   internal[=value],
              size=value,   version=[1|2],    sunit=value,    and
              su=value.

              The  internal suboption is used to specify that the
              log section is a piece of the data section  instead
              of  being  another  device  or logical volume.  The
              suboption value is either 0 or 1, with 1 signifying
              that the log is internal.  If the value is omitted,
              1 is assumed.

              The size suboption is used to specify the  size  of
              the log section.

              If the log is contained within the data section and
              size isn't specified, mkfs.xfs will try to select a
              suitable  log  size  depending  on  the size of the
              filesystem.  The  actual  logsize  depends  on  the
              filesystem block size and the directory block size.

              Otherwise, the size suboption is only needed if the
              log  section  of  the filesystem should occupy less
              space than the size of the special file.  The  size
              is  specified  in  bytes or blocks, with a b suffix
              meaning  multiplication  by  the  filesystem  block
              size,  as  described above.  The overriding minimum
              value for size is 512 blocks.  With  some  combina­
              tions  of  filesystem  block  size, inode size, and
              directory block  size,  the  minimum  log  size  is
              larger than 512 blocks.

              Using  the version suboption to specify a version 2
              log enables the sunit  suboption,  and  allows  the

              logs are automatically selected  if  a  log  stripe
              unit  is  specified.   See sunit and su suboptions,
              below.

              The sunit suboption specifies the alignment  to  be
              used for log writes.  The suboption value has to be
              specified in 512-byte block units.  Use the su sub­
              option  to  specify  the  log  stripe  unit size in
              bytes.  Log writes will be aligned on  this  bound­
              ary,  and  rounded up to this boundary.  This gives
              major improvements in performance on some  configu­
              rations  such  as  software raid5 when the sunit is
              specified as the filesystem block size.  The equiv­
              alent byte value must be a multiple of the filesys­
              tem block size.  Version 2 logs  are  automatically
              selected if the log su suboption is specified.

              The  su suboption is an alternative to using sunit.
              The su suboption is used to specify the log stripe.
              The  suboption  value has to be specified in bytes,
              (usually using the s or b  suffixes).   This  value
              must  be  a  multiple of the filesystem block size.
              Version 2 logs are automatically  selected  if  the
              log su suboption is specified.

       -n     Naming options.

              These  options specify the version and size parame­
              ters  for  the  naming  (directory)  area  of   the
              filesystem.   The  valid suboptions are: log=value,
              size=value, and version=value.  The naming  (direc­
              tory) version is 1 or 2, defaulting to 2 if unspec­
              ified.  With version 2 directories,  the  directory
              block  size  can  be  any  power of 2 size from the
              filesystem block size up to 65536.  The block  size
              is  specified  either as a base two logarithm value
              with log=, or in bytes  with  size=.   The  default
              size  value for version 2 directories is 4096 bytes
              (4 KB), unless the filesystem block size is  larger
              than  4096,  in which case the default value is the
              filesystem block size.  For version  1  directories
              the  block size is the same as the filesystem block
              size.

       -p protofile
              If the optional -p  protofile  argument  is  given,
              mkfs.xfs  uses  protofile  as  a prototype file and
              takes its directions from that  file.   The  blocks
              and inodes specifiers in the protofile are provided
              for  backwards  compatibility,  but  are  otherwise
              unused.   The  prototype file contains tokens sepa­
              rated by spaces or newlines.   A  sample  prototype
              specification follows (line numbers have been added


                   1       /stand/diskboot
                   2       4872 110
                   3       d--777 3 1
                   4       usr     d--777 3 1
                   5       sh      ---755 3 1 /bin/sh
                   6       ken     d--755 6 1
                   7               $
                   8       b0      b--644 3 1 0 0
                   9       c0      c--644 3 1 0 0
                   10      fifo    p--644 3 1
                   11      slink   l--644 3 1 /a/symbolic/link
                   12      :  This is a comment line
                   13      $
                   14      $

              Line 1 is a dummy string.   (It  was  formerly  the
              bootfilename.)  It is present for backward compati­
              bility; boot blocks are not used on SGI systems.

              Note that some string of characters must be present
              as  the first line of the proto file to cause it to
              be parsed correctly; the value of  this  string  is
              immaterial since it is ignored.

              Line  2  contains  two numeric values (formerly the
              numbers of blocks  and  inodes).   These  are  also
              merely for backward compatibility: two numeric val­
              ues must appear at this point for the proto file to
              be  correctly  parsed, but their values are immate­
              rial since they are ignored.

              Lines 3-11 tell mkfs.xfs about files  and  directo­
              ries  to  be  included  in this filesystem.  Line 3
              specifies the root directory.  Lines 4-6  and  8-10
              specifies  other  directories  and files.  Note the
              special symbolic link syntax on line 11.

              The $ on line 7 tells mkfs.xfs to end the branch of
              the filesystem it is on, and continue from the next
              higher directory.  It must be the last character on
              a line.  The colon on line 12 introduces a comment;
              all characters up until the following  newline  are
              ignored.   Note  that  this means you cannot have a
              file in a prototype  file  whose  name  contains  a
              colon.   The  $ on lines 13 and 14 end the process,
              since no additional specifications follow.

              File specifications give the mode, the user ID, the
              group  ID,  and  the  initial contents of the file.
              Valid syntax for the contents field depends on  the
              first character of the mode.

              string.  The first character specifies the type  of
              the file.  The character range is -bcdpl to specify
              regular, block special, character  special,  direc­
              tory  files,  named  pipes  (fifos),  and  symbolic
              links, respectively.  The second character  of  the
              mode  is either u or - to specify setuserID mode or
              not.  The third is g or - for the setgroupID  mode.
              The  rest of the mode is a three digit octal number
              giving the owner, group,  and  other  read,  write,
              execute permissions (see chmod(1)).

              Two decimal number tokens come after the mode; they
              specify the user and group IDs of the owner of  the
              file.

              If  the  file  is a regular file, the next token of
              the specification can be a pathname from which  the
              contents  and  size  are  copied.  If the file is a
              block or character special file, two  decimal  num­
              bers  follow  that  give the major and minor device
              numbers.  If the file is a symbolic link, the  next
              token  of the specification is used as the contents
              of the link.  If the file is a directory,  mkfs.xfs
              makes  the entries .  and ..  and then reads a list
              of names and (recursively) file specifications  for
              the  entries in the directory.  As noted above, the
              scan is terminated with the token $.

       -q     Quiet option.

              Normally mkfs.xfs  prints  the  parameters  of  the
              filesystem  to  be  constructed;  the  -q flag sup­
              presses this.

       -r     Real-time section options.

              These options specify the location, size, and other
              parameters of the real-time section of the filesys­
              tem.  The valid suboptions are:  extsize=value  and
              size=value.

              The  extsize  suboption is used to specify the size
              of the blocks  in  the  real-time  section  of  the
              filesystem.   This  size  must be a multiple of the
              filesystem block size.  The minimum  allowed  value
              is  the filesystem block size or 4 KB (whichever is
              larger); the default value is the stripe width  for
              striped  volumes  or 64 KB for non-striped volumes;
              the maximum allowed value is 1 GB.   The  real-time
              extent size should be carefully chosen to match the
              parameters of the physical media used.

              The size suboption is used to specify the  size  of

              needed if the real-time section of  the  filesystem
              should  occupy less space than the size of the par­
              tition or logical volume containing the section.

       -C     Disable overlapping partition/volume checks.

              By default mkfs.xfs checks to see if  the  destina­
              tion  partition  or  logical  volume  overlaps  any
              mounted or reserved partitions in the  system.   If
              an  overlap  or  mount  conflict is found, the user
              will be notified  and  prevented  from  potentially
              corrupting  the  existing data.  For systems with a
              large number of disks, this additional checking may
              add  noticable  overhead to the command's execution
              time.  For situations where command performance  is
              necessary,  this  switch may be used to disable the
              safeguards.  Due to the  potential  for  user-error
              causing corrupted filesystems or other on-disk data
              corruption, we  strongly  discourage  use  of  this
              switch in normal operation.

       -L label
              Set  the  filesystem  label.  XFS filesystem labels
              can be at most 12  characters  long;  if  label  is
              longer  than  12 characters, mkfs.xfs will not pro­
              ceed with creating the filesystem.   Refer  to  the
              mount(8)  and xfs_admin(8) manual entries for addi­
              tional information.


SEE ALSO

       mkfs(8), mount(8), xfs_info(8), xfs_admin(8).


BUGS

       With a prototype file, it is not possible to specify  hard
       links.


Man(1) output converted with man2html