From patchwork Wed May 30 21:05:47 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Sandeen X-Patchwork-Id: 10439911 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id CE8CF60327 for ; Wed, 30 May 2018 21:06:00 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id B58802959A for ; Wed, 30 May 2018 21:06:00 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id A9819295A0; Wed, 30 May 2018 21:06:00 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00, MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 364EF2959F for ; Wed, 30 May 2018 21:05:57 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932268AbeE3VFy (ORCPT ); Wed, 30 May 2018 17:05:54 -0400 Received: from sandeen.net ([63.231.237.45]:44828 "EHLO sandeen.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932078AbeE3VFs (ORCPT ); Wed, 30 May 2018 17:05:48 -0400 Received: from [10.0.0.4] (erlite [10.0.0.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by sandeen.net (Postfix) with ESMTPSA id 50939327A; Wed, 30 May 2018 16:05:44 -0500 (CDT) Subject: [PATCH 3.7/4] mkfs.xfs.8: parameterize sysconfdir To: "Luis R. Rodriguez" , linux-xfs@vger.kernel.org Cc: darrick.wong@oracle.com, jack@suse.com, jeffm@suse.com, okurz@suse.com, lpechacek@suse.com, jtulak@redhat.com References: <20180529220603.29420-1-mcgrof@kernel.org> <20180529220603.29420-4-mcgrof@kernel.org> From: Eric Sandeen Message-ID: Date: Wed, 30 May 2018 16:05:47 -0500 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:52.0) Gecko/20100101 Thunderbird/52.8.0 MIME-Version: 1.0 In-Reply-To: <20180529220603.29420-4-mcgrof@kernel.org> Content-Language: en-US Sender: linux-xfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-xfs@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This is a big looking patch, but it's just moving mkfs.xfs.8 to mkfs.xfs.8.in, substituting /etc for @sysconfdir@, and setting up a little bit of makefile magic to do the substitution and make the resulting manpage clean-able. Signed-off-by: Eric Sandeen Reviewed-by: Darrick J. Wong --- -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/man/man8/Makefile b/man/man8/Makefile index 36620da..08e5e0d 100644 --- a/man/man8/Makefile +++ b/man/man8/Makefile @@ -7,14 +7,20 @@ include $(TOPDIR)/include/builddefs MAN_SECTION = 8 -MAN_PAGES = $(shell echo *.$(MAN_SECTION)) +MAN_PAGES = $(shell echo *.$(MAN_SECTION)) mkfs.xfs.8 MAN_DEST = $(PKG_MAN_DIR)/man$(MAN_SECTION) LSRCFILES = $(MAN_PAGES) default : $(MAN_PAGES) +LDIRT = mkfs.xfs.8 + include $(BUILDRULES) +mkfs.xfs.8: mkfs.xfs.8.in + @echo " [SED] $@" + $(Q)$(SED) -e "s|@sysconfdir@|$(PKG_ETC_DIR)|g" < $< > $@ + install : default $(INSTALL) -m 755 -d $(MAN_DEST) $(INSTALL_MAN) diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8 deleted file mode 100644 index ca8c775..0000000 --- a/man/man8/mkfs.xfs.8 +++ /dev/null @@ -1,1016 +0,0 @@ -.TH mkfs.xfs 8 -.SH NAME -mkfs.xfs \- construct an XFS filesystem -.SH SYNOPSIS -.B mkfs.xfs -[ -.B \-c -.I configuration -] [ -[ -.B \-b -.I block_size_options -] [ -.B \-m -.I global_metadata_options -] [ -.B \-d -.I data_section_options -] [ -.B \-f -] [ -.B \-i -.I inode_options -] [ -.B \-l -.I log_section_options -] [ -.B \-n -.I naming_options -] [ -.B \-p -.I protofile -] [ -.B \-q -] [ -.B \-r -.I realtime_section_options -] [ -.B \-s -.I sector_size_options -] [ -.B \-L -.I label -] [ -.B \-N -] [ -.B \-K -] -.I device -.br -.B mkfs.xfs \-V -.SH DESCRIPTION -.B mkfs.xfs -constructs an XFS filesystem by writing on a special -file using the values found in the arguments of the command line. -It is invoked automatically by -.BR mkfs (8) -when it is given the -.B \-t xfs -option. -.PP -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: -.IP -.B mkfs.xfs /dev/sda1 -.PP -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 10MiB log located on the first partition -on the second SCSI disk, use: -.RS -.HP -.B mkfs.xfs\ \-l\ logdev=/dev/sdb1,size=10m /dev/sda1 -.RE -.PP -Each of the -.I option -elements in the argument list above can be given as multiple comma-separated -suboptions if multiple suboptions apply to the same option. -Equivalently, each main option can be given multiple times with -different suboptions. -For example, -.B \-l internal,size=10m -and -.B \-l internal \-l size=10m -are equivalent. -.PP -In the descriptions below, sizes are given in sectors, bytes, blocks, -kilobytes, megabytes, gigabytes, etc. -Sizes are treated as hexadecimal if prefixed by 0x or 0X, -octal if prefixed by 0, or decimal otherwise. -The following lists possible multiplication suffixes: -.RS -.PD 0 -.HP -.BR s "\ \-\ multiply by sector size (default = 512, see " \-s -option below). -.HP -.BR b "\ \-\ multiply by filesystem block size (default = 4K, see " \-b -option below). -.HP -.BR k "\ \-\ multiply by one kilobyte (1,024 bytes)." -.HP -.BR m "\ \-\ multiply by one megabyte (1,048,576 bytes)." -.HP -.BR g "\ \-\ multiply by one gigabyte (1,073,741,824 bytes)." -.HP -.BR t "\ \-\ multiply by one terabyte (1,099,511,627,776 bytes)." -.HP -.BR p "\ \-\ multiply by one petabyte (1,024 terabytes)." -.HP -.BR e "\ \-\ multiply by one exabyte (1,048,576 terabytes)." -.PD -.RE -.PP -When specifying parameters in units of sectors or filesystem blocks, the -.B \-s -option or the -.B \-b -option first needs to be added to the command line. -Failure to specify the size of the units will result in illegal value errors -when parameters are quantified in those units. -.PP -Many feature options allow an optional argument of 0 or 1, to explicitly -disable or enable the functionality. -.SH DEFAULT VALUES -.BR mkfs.xfs (8) -contains built-in default values for every option as described in the sections -below. -These built-in defaults may evolve over time as new capabilities are added. -If the file -.B /etc/xfs/mkfs/default -exists, it will be parsed to override built-in defaults, and the defaults -described in sections below may no longer apply. -.PP -The -.B \-c -option may also be used to specify an alternate configuration file -as described in the OPTIONS section. -.SH OPTIONS -.TP -.BI \-c " configuration" -This option may be used to specify a configuration file other than -.B /etc/xfs/mkfs/default -to override selected built-in parameter defaults. -If -.B configuration -is a simple filename with no path components, it will be searched in the -.B /etc/xfs/mkfs/ -directory. -If -.B configuration -is an absolute pathname, that path will be used to find the configuration file. -Otherwise, if -.B configuration -begins with -.BR \'./\' " or " \'../\' -it will be treated as a pathname relative to the current working directory. -See also the CONFIGURATION FILE FORMAT section below. -.TP -.BI \-b " block_size_options" -This option specifies the fundamental block size of the filesystem. -The valid -.I block_size_option -is: -.RS 1.2i -.TP -.BI size= value -The filesystem block size is specified with a -.I value -in bytes. The default value is 4096 bytes (4 KiB), the minimum is 512, and the -maximum is 65536 (64 KiB). -.IP -To specify any options on the command line in units of filesystem blocks, this -option must be specified first so that the filesystem block size is -applied consistently to all options. -.IP -Although -.B mkfs.xfs -will accept any of these values and create a valid filesystem, -XFS on Linux can only mount filesystems with pagesize or smaller blocks. -.RE -.TP -.BI \-m " global_metadata_options" -These options specify metadata format options that either apply to the entire -filesystem or aren't easily characterised by a specific functionality group. The -valid -.I global_metadata_options -are: -.RS 1.2i -.TP -.BI crc= value -This is used to create a filesystem which maintains and checks CRC information -in all metadata objects on disk. The value is either 0 to disable the feature, -or 1 to enable the use of CRCs. -.IP -CRCs enable enhanced error detection due to hardware issues, whilst the format -changes also improves crash recovery algorithms and the ability of various tools -to validate and repair metadata corruptions when they are found. The CRC -algorithm used is CRC32c, so the overhead is dependent on CPU architecture as -some CPUs have hardware acceleration of this algorithm. Typically the overhead -of calculating and checking the CRCs is not noticeable in normal operation. -.IP -By default, -.B mkfs.xfs -will enable metadata CRCs. -.TP -.BI finobt= value -This option enables the use of a separate free inode btree index in each -allocation group. The value is either 0 to disable the feature, or 1 to create -a free inode btree in each allocation group. -.IP -The free inode btree mirrors the existing allocated inode btree index which -indexes both used and free inodes. The free inode btree does not index used -inodes, allowing faster, more consistent inode allocation performance as -filesystems age. -.IP -By default, -.B mkfs.xfs -will create free inode btrees for filesystems created with the (default) -.B \-m crc=1 -option set. When the option -.B \-m crc=0 -is used, the free inode btree feature is not supported and is disabled. -.TP -.BI uuid= value -Use the given value as the filesystem UUID for the newly created filesystem. -The default is to generate a random UUID. -.TP -.BI rmapbt= value -This option enables the creation of a reverse-mapping btree index in each -allocation group. The value is either 0 to disable the feature, or 1 to -create the btree. -.IP -The reverse mapping btree maps filesystem blocks to the owner of the -filesystem block. Most of the mappings will be to an inode number and an -offset, though there will also be mappings to filesystem metadata. This -secondary metadata can be used to validate the primary metadata or to -pinpoint exactly which data has been lost when a disk error occurs. -.IP -By default, -.B mkfs.xfs -will not create reverse mapping btrees. This feature is only available -for filesystems created with the (default) -.B \-m crc=1 -option set. When the option -.B \-m crc=0 -is used, the reverse mapping btree feature is not supported and is disabled. -.TP -.BI reflink= value -This option enables the use of a separate reference count btree index in each -allocation group. The value is either 0 to disable the feature, or 1 to create -a reference count btree in each allocation group. -.IP -The reference count btree enables the sharing of physical extents between -the data forks of different files, which is commonly known as "reflink". -Unlike traditional Unix filesystems which assume that every inode and -logical block pair map to a unique physical block, a reflink-capable -XFS filesystem removes the uniqueness requirement, allowing up to four -billion arbitrary inode/logical block pairs to map to a physical block. -If a program tries to write to a multiply-referenced block in a file, the write -will be redirected to a new block, and that file's logical-to-physical -mapping will be changed to the new block ("copy on write"). This feature -enables the creation of per-file snapshots and deduplication. It is only -available for the data forks of regular files. -.IP -By default, -.B mkfs.xfs -will not create reference count btrees and therefore will not enable the -reflink feature. This feature is only available for filesystems created with -the (default) -.B \-m crc=1 -option set. When the option -.B \-m crc=0 -is used, the reference count btree feature is not supported and reflink is -disabled. -.RE -.TP -.BI \-d " data_section_options" -These options specify the location, size, and other parameters of the -data section of the filesystem. The valid -.I data_section_options -are: -.RS 1.2i -.TP -.BI agcount= value -This 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 MiB; the maximum size is just under 1 TiB. -The data section of the filesystem is divided into -.I value -allocation groups (default value is scaled automatically based -on the underlying device size). -.TP -.BI agsize= value -This is an alternative to using the -.B agcount -suboption. The -.I value -is the desired size of the allocation group expressed in bytes -(usually using the -.BR m " or " g -suffixes). -This value must be a multiple of the filesystem block size, and -must be at least 16MiB, and no more than 1TiB, and may -be automatically adjusted to properly align with the stripe geometry. -The -.B agcount -and -.B agsize -suboptions are mutually exclusive. -.TP -.BI cowextsize= value -Set the copy-on-write extent size hint on all inodes created by -.BR mkfs.xfs "." -The value must be provided in units of filesystem blocks. -If the value is zero, the default value (currently 32 blocks) will be used. -Directories will pass on this hint to newly created children. -.TP -.BI name= value -This can be used to specify the name of the special file containing -the filesystem. In this case, the log section must be specified as -.B internal -(with a size, see the -.B \-l -option below) and there can be no real-time section. -.TP -.BI file[= value ] -This is used to specify that the file given by the -.B name -suboption is a regular file. The -.I value -is either 0 or 1, with 1 signifying that the file is regular. This -suboption is used only to make a filesystem image. If the -.I value -is omitted then 1 is assumed. -.TP -.BI size= value -This is used to specify the size of the data section. This suboption -is required if -.B \-d file[=1] -is given. Otherwise, it is only needed if the filesystem should occupy -less space than the size of the special file. -.TP -.BI sunit= value -This is used to specify the stripe unit for a RAID device or a -logical volume. The -.I value -has to be specified in 512-byte block units. Use the -.B 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 512KiB. Also inode allocations and the internal log will be -stripe unit aligned. -.TP -.BI su= value -This is an alternative to using -.B sunit. -The -.B su -suboption is used to specify the stripe unit for a RAID device or a -striped logical volume. The -.I value -has to be specified in bytes, (usually using the -.BR m " or " g -suffixes). This -.I value -must be a multiple of the filesystem block size. -.TP -.BI swidth= value -This is used to specify the stripe width for a RAID device or a -striped logical volume. The -.I value -has to be specified in 512-byte block units. Use the -.B sw -suboption to specify the stripe width size in bytes. -This suboption is required if -.B \-d sunit -has been specified and it has to be a multiple of the -.B \-d sunit -suboption. -.TP -.BI sw= value -suboption is an alternative to using -.B swidth. -The -.B sw -suboption is used to specify the stripe width for a RAID device or -striped logical volume. The -.I 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. -.IP -When a filesystem is created on a logical volume device, -.B mkfs.xfs -will automatically query the logical volume for appropriate -.B sunit -and -.B swidth -values. -.TP -.BI noalign -This option disables automatic geometry detection and creates the filesystem -without stripe geometry alignment even if the underlying storage device provides -this information. -.TP -.BI rtinherit= value -If set, all inodes created by -.B mkfs.xfs -will be created with the realtime flag set. -Directories will pass on this flag to newly created children. -.TP -.BI projinherit= value -All inodes created by -.B mkfs.xfs -will be assigned this project quota id. -Directories will pass on the project id to newly created children. -.TP -.BI extszinherit= value -All inodes created by -.B mkfs.xfs -will have this extent size hint applied. -The value must be provided in units of filesystem blocks. -Directories will pass on this hint to newly created children. -.RE -.TP -.B \-f -Force overwrite when an existing filesystem is detected on the device. -By default, -.B mkfs.xfs -will not write to the device if it suspects that there is a filesystem -or partition table on the device already. -.TP -.BI \-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. -.IP -The valid -.I inode_options -are: -.RS 1.2i -.TP -.BI size= value " | perblock=" value -The inode size is specified either as a -.I value -in bytes with -.BR size= -or as the number fitting in a filesystem block with -.BR perblock= . -The minimum (and default) -.I value -is 256 bytes without crc, 512 bytes with crc enabled. -The maximum -.I value -is 2048 (2 KiB) subject to the restriction that -the inode size cannot exceed one half of the filesystem block size. -.IP -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 (on 32 bit hardware platforms) and most applications -cannot currently handle inode numbers greater than 32 significant bits, -so if no inode size is given on the command line, -.B 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 sufficiently large, -.B mkfs.xfs -will warn if this will create inode numbers > 32 significant -bits. -.TP -.BI maxpct= value -This specifies the maximum percentage of space in the filesystem that -can be allocated to inodes. The default -.I value -is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1% -for filesystems over 50TB. -.IP -In the default inode allocation mode, inode blocks are chosen such -that inode numbers will not exceed 32 bits, which restricts the inode -blocks to the lower portion of the filesystem. The data block -allocator will avoid these low blocks to accommodate the specified -maxpct, so a high value may result in a filesystem with nothing but -inodes in a significant portion of the lower blocks of the filesystem. -(This restriction is not present when the filesystem is mounted with -the -.I "inode64" -option on 64-bit platforms). -.IP -Setting the value to 0 means that essentially all of the filesystem -can become inode blocks, subject to inode32 restrictions. -.IP -This value can be modified with -.IR xfs_growfs(8) . -.TP -.BI align[= value ] -This is used to specify that inode allocation is or is not aligned. The -.I value -is either 0 or 1, with 1 signifying that inodes are allocated aligned. -If the -.I 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 established 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 without XFS patches). -.TP -.BI attr= value -This is used to specify the version of extended attribute inline -allocation policy to be used. By default, this is 2, which uses an -efficient algorithm for managing the available inline inode space -between attribute and extent data. -.IP -The previous version 1, which has fixed regions for attribute and -extent data, is kept for backwards compatibility with kernels older -than version 2.6.16. -.TP -.BI projid32bit[= value ] -This is used to enable 32bit quota project identifiers. The -.I value -is either 0 or 1, with 1 signifying that 32bit projid are to be enabled. -If the value is omitted, 1 is assumed. (This default changed -in release version 3.2.0.) -.TP -.BI sparse[= value ] -Enable sparse inode chunk allocation. The -.I value -is either 0 or 1, with 1 signifying that sparse allocation is enabled. -If the value is omitted, 1 is assumed. Sparse inode allocation is -disabled by default. This feature is only available for filesystems -formatted with -.B \-m crc=1. -.IP -When enabled, sparse inode allocation allows the filesystem to allocate -smaller than the standard 64-inode chunk when free space is severely -limited. This feature is useful for filesystems that might fragment free -space over time such that no free extents are large enough to -accommodate a chunk of 64 inodes. Without this feature enabled, inode -allocations can fail with out of space errors under severe fragmented -free space conditions. -.RE -.TP -.BI \-l " log_section_options" -These options specify the location, size, and other parameters of the -log section of the filesystem. The valid -.I log_section_options -are: -.RS 1.2i -.TP -.BI agnum= value -If the log is internal, allocate it in this AG. -.TP -.BI internal[= value ] -This is used to specify that the log section is a piece of the data -section instead of being another device or logical volume. The -.I value -is either 0 or 1, with 1 signifying that the log is internal. If the -.I value -is omitted, 1 is assumed. -.TP -.BI logdev= device -This is used to specify that the log section should reside on the -.I device -separate from the data section. The -.B internal=1 -and -.B logdev -options are mutually exclusive. -.TP -.BI size= value -This is used to specify the size of the log section. -.IP -If the log is contained within the data section and -.B size -isn't specified, -.B 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. -.IP -Otherwise, the -.B size -suboption is only needed if the log section of the filesystem -should occupy less space than the size of the special file. The -.I value -is specified in bytes or blocks, with a -.B b -suffix meaning multiplication by the filesystem block size, as -described above. The overriding minimum value for size is 512 blocks. -With some combinations of filesystem block size, inode size, -and directory block size, the minimum log size is larger than 512 blocks. -.TP -.BI version= value -This specifies the version of the log. The current default is 2, -which allows for larger log buffer sizes, as well as supporting -stripe-aligned log writes (see the sunit and su options, below). -.IP -The previous version 1, which is limited to 32k log buffers and does -not support stripe-aligned writes, is kept for backwards compatibility -with very old 2.4 kernels. -.TP -.BI sunit= value -This specifies the alignment to be used for log writes. The -.I value -has to be specified in 512-byte block units. Use the -.B su -suboption to specify the log stripe unit size in bytes. -Log writes will be aligned on this boundary, -and rounded up to this boundary. -This gives major improvements in performance on some configurations -such as software RAID5 when the -.B sunit -is specified as the filesystem block size. -The equivalent byte value must be a multiple of the filesystem block -size. Version 2 logs are automatically selected if the log -.B sunit -suboption is specified. -.IP -The -.B su -suboption is an alternative to using -.B sunit. -.TP -.BI su= value -This is used to specify the log stripe. The -.I value -has to be specified in bytes, (usually using the -.BR s " or " b -suffixes). This value must be a multiple of the filesystem block size. -Version 2 logs are automatically selected if the log -.B su -suboption is specified. -.TP -.BI lazy-count= value -This changes the method of logging various persistent counters -in the superblock. Under metadata intensive workloads, these -counters are updated and logged frequently enough that the superblock -updates become a serialization point in the filesystem. The -.I value -can be either 0 or 1. -.IP -With -.BR lazy-count=1 , -the superblock is not modified or logged on every change of the -persistent counters. Instead, enough information is kept in -other parts of the filesystem to be able to maintain the persistent -counter values without needed to keep them in the superblock. -This gives significant improvements in performance on some configurations. -The default -.I value -is 1 (on) so you must specify -.B lazy-count=0 -if you want to disable this feature for older kernels which don't support -it. -.RE -.TP -.BI \-n " naming_options" -These options specify the version and size parameters for the naming -(directory) area of the filesystem. The valid -.I naming_options -are: -.RS 1.2i -.TP -.BI size= value -The directory block size is specified with a -.I value -in bytes. The block size must be a power of 2 and cannot be less than the -filesystem block size. -The default size -.I value -for version 2 directories is 4096 bytes (4 KiB), -unless the filesystem block size is larger than 4096, -in which case the default -.I value -is the filesystem block size. -For version 1 directories the block size is the same as the -filesystem block size. -.TP -.BI version= value -The naming (directory) version -.I value -can be either 2 or 'ci', defaulting to 2 if unspecified. -With version 2 directories, the directory block size can be -any power of 2 size from the filesystem block size up to 65536. -.IP -The -.B version=ci -option enables ASCII only case-insensitive filename lookup and version -2 directories. Filenames are case-preserving, that is, the names -are stored in directories using the case they were created with. -.IP -Note: Version 1 directories are not supported. -.TP -.BI ftype= value -This feature allows the inode type to be stored in the directory -structure so that the -.BR readdir (3) -and -.BR getdents (2) -do not need to look up the inode to determine the inode type. - -The -.I value -is either 0 or 1, with 1 signifying that filetype information -will be stored in the directory structure. The default value is 1. - -When CRCs are enabled (the default), the ftype functionality is always -enabled, and cannot be turned off. -.IP -.RE -.TP -.BI \-p " protofile" -If the optional -.BI \-p " protofile" -argument is given, -.B mkfs.xfs -uses -.I protofile -as a prototype file and takes its directions from that file. -The blocks and inodes specifiers in the -.I protofile -are provided for backwards compatibility, but are otherwise unused. -The syntax of the protofile is defined by a number of tokens separated -by spaces or newlines. Note that the line numbers are not part of the -syntax but are meant to help you in the following discussion of the file -contents. -.nf -.sp .8v -.in +5 -\f71 /stand/\f1\f2diskboot\f1\f7 -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 $\f1 -.in -5 -.fi -.IP -Line 1 is a dummy string. -(It was formerly the bootfilename.) -It is present for backward -compatibility; boot blocks are not used on SGI systems. -.IP -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. -.IP -Line 2 contains two numeric values (formerly the numbers of blocks and inodes). -These are also merely for backward compatibility: two numeric values must -appear at this point for the proto file to be correctly parsed, -but their values are immaterial since they are ignored. -.IP -The lines 3 through 11 specify the files and directories you want to -include in this filesystem. Line 3 defines the -root directory. Other directories and -files that you want in the filesystem -are indicated by lines 4 through 6 and -lines 8 through 10. Line 11 contains -symbolic link syntax. -.IP -Notice the dollar sign -.RB ( $ ) -syntax on line 7. This syntax directs the -.B mkfs.xfs -command to terminate the branch of the filesystem it -is currently on and then continue -from the directory specified by -the next line, in this case line 8. -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 -.B $ -on lines 13 and 14 end the process, since no additional -specifications follow. -.IP -File specifications provide the following: -.IP - * file mode -.br - * user ID -.br - * group ID -.br - * the file's beginning contents -.P -.IP -A 6-character string defines the mode for -a file. The first character of this string -defines the file type. The character range -for this first character is -.B \-bcdpl. -A file may be a regular file, a block special file, -a character special file, directory files, named -pipes (first-in, first out files), and symbolic -links. -The second character of the mode string is -used to specify setuserID mode, in which case -it is -.BR u . -If setuserID mode is not specified, the second character is -.BR \- . -The third character of the mode string is -used to specify the setgroupID mode, in which -case it is -.BR g . -If setgroupID mode is not specified, the third character is -.BR \- . -The remaining characters of the mode string are -a three digit octal number. This octal number -defines the owner, group, and other read, write, -and execute permissions for the file, respectively. -For more information on file permissions, see the -.BR chmod (1) -command. -.IP -Following the mode character string are two -decimal number tokens that specify the user and group IDs -of the file's owner. -.IP -In a regular file, the next token specifies the -pathname from which the contents and size of the -file are copied. -In a block or character special file, the next token -are two decimal numbers that specify the major and minor -device numbers. -When a file is a symbolic link, the next token -specifies the contents of the link. - -When the file is a directory, the -.B mkfs.xfs -command creates the entries -.B dot -(.) and -.B dot-dot -(..) and then reads the list of names and file specifications -in a recursive manner for all of the entries -in the directory. A scan of the protofile is -always terminated with the dollar ( -.B $ -) token. -.TP -.B \-q -Quiet option. Normally -.B mkfs.xfs -prints the parameters of the filesystem -to be constructed; -the -.B \-q -flag suppresses this. -.TP -.BI \-r " realtime_section_options" -These options specify the location, size, and other parameters of the -real-time section of the filesystem. The valid -.I realtime_section_options -are: -.RS 1.2i -.TP -.BI rtdev= device -This is used to specify the -.I device -which should contain the real-time section of the filesystem. -The suboption value is the name of a block device. -.TP -.BI extsize= value -This is used to specify the size of the blocks in the real-time -section of the filesystem. This -.I value -must be a multiple of the filesystem block size. The minimum allowed -size is the filesystem block size or 4 KiB (whichever is larger); the -default size is the stripe width for striped volumes or 64 KiB for -non-striped volumes; the maximum allowed size is 1 GiB. The real-time -extent size should be carefully chosen to match the parameters of the -physical media used. -.TP -.BI size= value -This is used to specify the size of the real-time section. -This suboption is only needed if the real-time section of the -filesystem should occupy less space than the size of the partition -or logical volume containing the section. -.TP -.BI noalign -This option disables stripe size detection, enforcing a realtime device with no -stripe geometry. -.RE -.TP -.BI \-s " sector_size_options" -This option specifies the fundamental sector size of the filesystem. -The valid -.I sector_size_option -is: -.RS 1.2i -.TP -.BI size= value -The sector size is specified with a -.I value -in bytes. The default -.I sector_size -is 512 bytes. The minimum value for sector size is -512; the maximum is 32768 (32 KiB). The -.I sector_size -must be a power of 2 size and cannot be made larger than the -filesystem block size. -.IP -To specify any options on the command line in units of sectors, this -option must be specified first so that the sector size is -applied consistently to all options. -.RE -.TP -.BI \-L " label" -Set the filesystem -.IR label . -XFS filesystem labels can be at most 12 characters long; if -.I label -is longer than 12 characters, -.B mkfs.xfs -will not proceed with creating the filesystem. Refer to the -.BR mount "(8) and " xfs_admin (8) -manual entries for additional information. -.TP -.B \-N -Causes the file system parameters to be printed out without really -creating the file system. -.TP -.B \-K -Do not attempt to discard blocks at mkfs time. -.TP -.B \-V -Prints the version number and exits. -.SH CONFIGURATION FILE FORMAT -The optional default configuration file in -.B /etc/xfs/mkfs/default -as well as any alternate configuration file specified via the -.B \-c -option must follow a simple ini-style format as shown below. -Available options consist of a subset of the parameters available -via the -.BR mkfs.xfs (8) -command line. -Currently all default parameters can only be either enabled or disabled, -with a value of 1 to enable or 0 to disable. -See below for a list of all supported configuration parameters and their -current built-in default settings. -.PP -.BI [data] -.br -.BI noalign=0 -.PP -.BI [inode] -.br -.BI align=1 -.br -.BI projid32bit=1 -.br -.BI sparse=0 -.PP -.BI [log] -.br -.BI lazy-count=1 -.PP -.BI [metadata] -.br -.BI crc=1 -.br -.BI finobt=1 -.br -.BI rmapbt=0 -.br -.BI reflink=0 -.PP -.BI [naming] -.br -.BI ftype=1 -.PP -.BI [rtdev] -.br -.BI noalign=0 -.PP -.SH SEE ALSO -.BR xfs (5), -.BR mkfs (8), -.BR mount (8), -.BR xfs_info (8), -.BR xfs_admin (8). -.SH BUGS -With a prototype file, it is not possible to specify hard links. diff --git a/man/man8/mkfs.xfs.8.in b/man/man8/mkfs.xfs.8.in new file mode 100644 index 0000000..c91a92d --- /dev/null +++ b/man/man8/mkfs.xfs.8.in @@ -0,0 +1,1016 @@ +.TH mkfs.xfs 8 +.SH NAME +mkfs.xfs \- construct an XFS filesystem +.SH SYNOPSIS +.B mkfs.xfs +[ +.B \-c +.I configuration +] [ +[ +.B \-b +.I block_size_options +] [ +.B \-m +.I global_metadata_options +] [ +.B \-d +.I data_section_options +] [ +.B \-f +] [ +.B \-i +.I inode_options +] [ +.B \-l +.I log_section_options +] [ +.B \-n +.I naming_options +] [ +.B \-p +.I protofile +] [ +.B \-q +] [ +.B \-r +.I realtime_section_options +] [ +.B \-s +.I sector_size_options +] [ +.B \-L +.I label +] [ +.B \-N +] [ +.B \-K +] +.I device +.br +.B mkfs.xfs \-V +.SH DESCRIPTION +.B mkfs.xfs +constructs an XFS filesystem by writing on a special +file using the values found in the arguments of the command line. +It is invoked automatically by +.BR mkfs (8) +when it is given the +.B \-t xfs +option. +.PP +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: +.IP +.B mkfs.xfs /dev/sda1 +.PP +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 10MiB log located on the first partition +on the second SCSI disk, use: +.RS +.HP +.B mkfs.xfs\ \-l\ logdev=/dev/sdb1,size=10m /dev/sda1 +.RE +.PP +Each of the +.I option +elements in the argument list above can be given as multiple comma-separated +suboptions if multiple suboptions apply to the same option. +Equivalently, each main option can be given multiple times with +different suboptions. +For example, +.B \-l internal,size=10m +and +.B \-l internal \-l size=10m +are equivalent. +.PP +In the descriptions below, sizes are given in sectors, bytes, blocks, +kilobytes, megabytes, gigabytes, etc. +Sizes are treated as hexadecimal if prefixed by 0x or 0X, +octal if prefixed by 0, or decimal otherwise. +The following lists possible multiplication suffixes: +.RS +.PD 0 +.HP +.BR s "\ \-\ multiply by sector size (default = 512, see " \-s +option below). +.HP +.BR b "\ \-\ multiply by filesystem block size (default = 4K, see " \-b +option below). +.HP +.BR k "\ \-\ multiply by one kilobyte (1,024 bytes)." +.HP +.BR m "\ \-\ multiply by one megabyte (1,048,576 bytes)." +.HP +.BR g "\ \-\ multiply by one gigabyte (1,073,741,824 bytes)." +.HP +.BR t "\ \-\ multiply by one terabyte (1,099,511,627,776 bytes)." +.HP +.BR p "\ \-\ multiply by one petabyte (1,024 terabytes)." +.HP +.BR e "\ \-\ multiply by one exabyte (1,048,576 terabytes)." +.PD +.RE +.PP +When specifying parameters in units of sectors or filesystem blocks, the +.B \-s +option or the +.B \-b +option first needs to be added to the command line. +Failure to specify the size of the units will result in illegal value errors +when parameters are quantified in those units. +.PP +Many feature options allow an optional argument of 0 or 1, to explicitly +disable or enable the functionality. +.SH DEFAULT VALUES +.BR mkfs.xfs (8) +contains built-in default values for every option as described in the sections +below. +These built-in defaults may evolve over time as new capabilities are added. +If the file +.B @sysconfdir@/xfs/mkfs/default +exists, it will be parsed to override built-in defaults, and the defaults +described in sections below may no longer apply. +.PP +The +.B \-c +option may also be used to specify an alternate configuration file +as described in the OPTIONS section. +.SH OPTIONS +.TP +.BI \-c " configuration" +This option may be used to specify a configuration file other than +.B @sysconfdir@/xfs/mkfs/default +to override selected built-in parameter defaults. +If +.B configuration +is a simple filename with no path components, it will be searched in the +.B @sysconfdir@/xfs/mkfs/ +directory. +If +.B configuration +is an absolute pathname, that path will be used to find the configuration file. +Otherwise, if +.B configuration +begins with +.BR \'./\' " or " \'../\' +it will be treated as a pathname relative to the current working directory. +See also the CONFIGURATION FILE FORMAT section below. +.TP +.BI \-b " block_size_options" +This option specifies the fundamental block size of the filesystem. +The valid +.I block_size_option +is: +.RS 1.2i +.TP +.BI size= value +The filesystem block size is specified with a +.I value +in bytes. The default value is 4096 bytes (4 KiB), the minimum is 512, and the +maximum is 65536 (64 KiB). +.IP +To specify any options on the command line in units of filesystem blocks, this +option must be specified first so that the filesystem block size is +applied consistently to all options. +.IP +Although +.B mkfs.xfs +will accept any of these values and create a valid filesystem, +XFS on Linux can only mount filesystems with pagesize or smaller blocks. +.RE +.TP +.BI \-m " global_metadata_options" +These options specify metadata format options that either apply to the entire +filesystem or aren't easily characterised by a specific functionality group. The +valid +.I global_metadata_options +are: +.RS 1.2i +.TP +.BI crc= value +This is used to create a filesystem which maintains and checks CRC information +in all metadata objects on disk. The value is either 0 to disable the feature, +or 1 to enable the use of CRCs. +.IP +CRCs enable enhanced error detection due to hardware issues, whilst the format +changes also improves crash recovery algorithms and the ability of various tools +to validate and repair metadata corruptions when they are found. The CRC +algorithm used is CRC32c, so the overhead is dependent on CPU architecture as +some CPUs have hardware acceleration of this algorithm. Typically the overhead +of calculating and checking the CRCs is not noticeable in normal operation. +.IP +By default, +.B mkfs.xfs +will enable metadata CRCs. +.TP +.BI finobt= value +This option enables the use of a separate free inode btree index in each +allocation group. The value is either 0 to disable the feature, or 1 to create +a free inode btree in each allocation group. +.IP +The free inode btree mirrors the existing allocated inode btree index which +indexes both used and free inodes. The free inode btree does not index used +inodes, allowing faster, more consistent inode allocation performance as +filesystems age. +.IP +By default, +.B mkfs.xfs +will create free inode btrees for filesystems created with the (default) +.B \-m crc=1 +option set. When the option +.B \-m crc=0 +is used, the free inode btree feature is not supported and is disabled. +.TP +.BI uuid= value +Use the given value as the filesystem UUID for the newly created filesystem. +The default is to generate a random UUID. +.TP +.BI rmapbt= value +This option enables the creation of a reverse-mapping btree index in each +allocation group. The value is either 0 to disable the feature, or 1 to +create the btree. +.IP +The reverse mapping btree maps filesystem blocks to the owner of the +filesystem block. Most of the mappings will be to an inode number and an +offset, though there will also be mappings to filesystem metadata. This +secondary metadata can be used to validate the primary metadata or to +pinpoint exactly which data has been lost when a disk error occurs. +.IP +By default, +.B mkfs.xfs +will not create reverse mapping btrees. This feature is only available +for filesystems created with the (default) +.B \-m crc=1 +option set. When the option +.B \-m crc=0 +is used, the reverse mapping btree feature is not supported and is disabled. +.TP +.BI reflink= value +This option enables the use of a separate reference count btree index in each +allocation group. The value is either 0 to disable the feature, or 1 to create +a reference count btree in each allocation group. +.IP +The reference count btree enables the sharing of physical extents between +the data forks of different files, which is commonly known as "reflink". +Unlike traditional Unix filesystems which assume that every inode and +logical block pair map to a unique physical block, a reflink-capable +XFS filesystem removes the uniqueness requirement, allowing up to four +billion arbitrary inode/logical block pairs to map to a physical block. +If a program tries to write to a multiply-referenced block in a file, the write +will be redirected to a new block, and that file's logical-to-physical +mapping will be changed to the new block ("copy on write"). This feature +enables the creation of per-file snapshots and deduplication. It is only +available for the data forks of regular files. +.IP +By default, +.B mkfs.xfs +will not create reference count btrees and therefore will not enable the +reflink feature. This feature is only available for filesystems created with +the (default) +.B \-m crc=1 +option set. When the option +.B \-m crc=0 +is used, the reference count btree feature is not supported and reflink is +disabled. +.RE +.TP +.BI \-d " data_section_options" +These options specify the location, size, and other parameters of the +data section of the filesystem. The valid +.I data_section_options +are: +.RS 1.2i +.TP +.BI agcount= value +This 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 MiB; the maximum size is just under 1 TiB. +The data section of the filesystem is divided into +.I value +allocation groups (default value is scaled automatically based +on the underlying device size). +.TP +.BI agsize= value +This is an alternative to using the +.B agcount +suboption. The +.I value +is the desired size of the allocation group expressed in bytes +(usually using the +.BR m " or " g +suffixes). +This value must be a multiple of the filesystem block size, and +must be at least 16MiB, and no more than 1TiB, and may +be automatically adjusted to properly align with the stripe geometry. +The +.B agcount +and +.B agsize +suboptions are mutually exclusive. +.TP +.BI cowextsize= value +Set the copy-on-write extent size hint on all inodes created by +.BR mkfs.xfs "." +The value must be provided in units of filesystem blocks. +If the value is zero, the default value (currently 32 blocks) will be used. +Directories will pass on this hint to newly created children. +.TP +.BI name= value +This can be used to specify the name of the special file containing +the filesystem. In this case, the log section must be specified as +.B internal +(with a size, see the +.B \-l +option below) and there can be no real-time section. +.TP +.BI file[= value ] +This is used to specify that the file given by the +.B name +suboption is a regular file. The +.I value +is either 0 or 1, with 1 signifying that the file is regular. This +suboption is used only to make a filesystem image. If the +.I value +is omitted then 1 is assumed. +.TP +.BI size= value +This is used to specify the size of the data section. This suboption +is required if +.B \-d file[=1] +is given. Otherwise, it is only needed if the filesystem should occupy +less space than the size of the special file. +.TP +.BI sunit= value +This is used to specify the stripe unit for a RAID device or a +logical volume. The +.I value +has to be specified in 512-byte block units. Use the +.B 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 512KiB. Also inode allocations and the internal log will be +stripe unit aligned. +.TP +.BI su= value +This is an alternative to using +.B sunit. +The +.B su +suboption is used to specify the stripe unit for a RAID device or a +striped logical volume. The +.I value +has to be specified in bytes, (usually using the +.BR m " or " g +suffixes). This +.I value +must be a multiple of the filesystem block size. +.TP +.BI swidth= value +This is used to specify the stripe width for a RAID device or a +striped logical volume. The +.I value +has to be specified in 512-byte block units. Use the +.B sw +suboption to specify the stripe width size in bytes. +This suboption is required if +.B \-d sunit +has been specified and it has to be a multiple of the +.B \-d sunit +suboption. +.TP +.BI sw= value +suboption is an alternative to using +.B swidth. +The +.B sw +suboption is used to specify the stripe width for a RAID device or +striped logical volume. The +.I 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. +.IP +When a filesystem is created on a logical volume device, +.B mkfs.xfs +will automatically query the logical volume for appropriate +.B sunit +and +.B swidth +values. +.TP +.BI noalign +This option disables automatic geometry detection and creates the filesystem +without stripe geometry alignment even if the underlying storage device provides +this information. +.TP +.BI rtinherit= value +If set, all inodes created by +.B mkfs.xfs +will be created with the realtime flag set. +Directories will pass on this flag to newly created children. +.TP +.BI projinherit= value +All inodes created by +.B mkfs.xfs +will be assigned this project quota id. +Directories will pass on the project id to newly created children. +.TP +.BI extszinherit= value +All inodes created by +.B mkfs.xfs +will have this extent size hint applied. +The value must be provided in units of filesystem blocks. +Directories will pass on this hint to newly created children. +.RE +.TP +.B \-f +Force overwrite when an existing filesystem is detected on the device. +By default, +.B mkfs.xfs +will not write to the device if it suspects that there is a filesystem +or partition table on the device already. +.TP +.BI \-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. +.IP +The valid +.I inode_options +are: +.RS 1.2i +.TP +.BI size= value " | perblock=" value +The inode size is specified either as a +.I value +in bytes with +.BR size= +or as the number fitting in a filesystem block with +.BR perblock= . +The minimum (and default) +.I value +is 256 bytes without crc, 512 bytes with crc enabled. +The maximum +.I value +is 2048 (2 KiB) subject to the restriction that +the inode size cannot exceed one half of the filesystem block size. +.IP +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 (on 32 bit hardware platforms) and most applications +cannot currently handle inode numbers greater than 32 significant bits, +so if no inode size is given on the command line, +.B 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 sufficiently large, +.B mkfs.xfs +will warn if this will create inode numbers > 32 significant +bits. +.TP +.BI maxpct= value +This specifies the maximum percentage of space in the filesystem that +can be allocated to inodes. The default +.I value +is 25% for filesystems under 1TB, 5% for filesystems under 50TB and 1% +for filesystems over 50TB. +.IP +In the default inode allocation mode, inode blocks are chosen such +that inode numbers will not exceed 32 bits, which restricts the inode +blocks to the lower portion of the filesystem. The data block +allocator will avoid these low blocks to accommodate the specified +maxpct, so a high value may result in a filesystem with nothing but +inodes in a significant portion of the lower blocks of the filesystem. +(This restriction is not present when the filesystem is mounted with +the +.I "inode64" +option on 64-bit platforms). +.IP +Setting the value to 0 means that essentially all of the filesystem +can become inode blocks, subject to inode32 restrictions. +.IP +This value can be modified with +.IR xfs_growfs(8) . +.TP +.BI align[= value ] +This is used to specify that inode allocation is or is not aligned. The +.I value +is either 0 or 1, with 1 signifying that inodes are allocated aligned. +If the +.I 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 established 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 without XFS patches). +.TP +.BI attr= value +This is used to specify the version of extended attribute inline +allocation policy to be used. By default, this is 2, which uses an +efficient algorithm for managing the available inline inode space +between attribute and extent data. +.IP +The previous version 1, which has fixed regions for attribute and +extent data, is kept for backwards compatibility with kernels older +than version 2.6.16. +.TP +.BI projid32bit[= value ] +This is used to enable 32bit quota project identifiers. The +.I value +is either 0 or 1, with 1 signifying that 32bit projid are to be enabled. +If the value is omitted, 1 is assumed. (This default changed +in release version 3.2.0.) +.TP +.BI sparse[= value ] +Enable sparse inode chunk allocation. The +.I value +is either 0 or 1, with 1 signifying that sparse allocation is enabled. +If the value is omitted, 1 is assumed. Sparse inode allocation is +disabled by default. This feature is only available for filesystems +formatted with +.B \-m crc=1. +.IP +When enabled, sparse inode allocation allows the filesystem to allocate +smaller than the standard 64-inode chunk when free space is severely +limited. This feature is useful for filesystems that might fragment free +space over time such that no free extents are large enough to +accommodate a chunk of 64 inodes. Without this feature enabled, inode +allocations can fail with out of space errors under severe fragmented +free space conditions. +.RE +.TP +.BI \-l " log_section_options" +These options specify the location, size, and other parameters of the +log section of the filesystem. The valid +.I log_section_options +are: +.RS 1.2i +.TP +.BI agnum= value +If the log is internal, allocate it in this AG. +.TP +.BI internal[= value ] +This is used to specify that the log section is a piece of the data +section instead of being another device or logical volume. The +.I value +is either 0 or 1, with 1 signifying that the log is internal. If the +.I value +is omitted, 1 is assumed. +.TP +.BI logdev= device +This is used to specify that the log section should reside on the +.I device +separate from the data section. The +.B internal=1 +and +.B logdev +options are mutually exclusive. +.TP +.BI size= value +This is used to specify the size of the log section. +.IP +If the log is contained within the data section and +.B size +isn't specified, +.B 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. +.IP +Otherwise, the +.B size +suboption is only needed if the log section of the filesystem +should occupy less space than the size of the special file. The +.I value +is specified in bytes or blocks, with a +.B b +suffix meaning multiplication by the filesystem block size, as +described above. The overriding minimum value for size is 512 blocks. +With some combinations of filesystem block size, inode size, +and directory block size, the minimum log size is larger than 512 blocks. +.TP +.BI version= value +This specifies the version of the log. The current default is 2, +which allows for larger log buffer sizes, as well as supporting +stripe-aligned log writes (see the sunit and su options, below). +.IP +The previous version 1, which is limited to 32k log buffers and does +not support stripe-aligned writes, is kept for backwards compatibility +with very old 2.4 kernels. +.TP +.BI sunit= value +This specifies the alignment to be used for log writes. The +.I value +has to be specified in 512-byte block units. Use the +.B su +suboption to specify the log stripe unit size in bytes. +Log writes will be aligned on this boundary, +and rounded up to this boundary. +This gives major improvements in performance on some configurations +such as software RAID5 when the +.B sunit +is specified as the filesystem block size. +The equivalent byte value must be a multiple of the filesystem block +size. Version 2 logs are automatically selected if the log +.B sunit +suboption is specified. +.IP +The +.B su +suboption is an alternative to using +.B sunit. +.TP +.BI su= value +This is used to specify the log stripe. The +.I value +has to be specified in bytes, (usually using the +.BR s " or " b +suffixes). This value must be a multiple of the filesystem block size. +Version 2 logs are automatically selected if the log +.B su +suboption is specified. +.TP +.BI lazy-count= value +This changes the method of logging various persistent counters +in the superblock. Under metadata intensive workloads, these +counters are updated and logged frequently enough that the superblock +updates become a serialization point in the filesystem. The +.I value +can be either 0 or 1. +.IP +With +.BR lazy-count=1 , +the superblock is not modified or logged on every change of the +persistent counters. Instead, enough information is kept in +other parts of the filesystem to be able to maintain the persistent +counter values without needed to keep them in the superblock. +This gives significant improvements in performance on some configurations. +The default +.I value +is 1 (on) so you must specify +.B lazy-count=0 +if you want to disable this feature for older kernels which don't support +it. +.RE +.TP +.BI \-n " naming_options" +These options specify the version and size parameters for the naming +(directory) area of the filesystem. The valid +.I naming_options +are: +.RS 1.2i +.TP +.BI size= value +The directory block size is specified with a +.I value +in bytes. The block size must be a power of 2 and cannot be less than the +filesystem block size. +The default size +.I value +for version 2 directories is 4096 bytes (4 KiB), +unless the filesystem block size is larger than 4096, +in which case the default +.I value +is the filesystem block size. +For version 1 directories the block size is the same as the +filesystem block size. +.TP +.BI version= value +The naming (directory) version +.I value +can be either 2 or 'ci', defaulting to 2 if unspecified. +With version 2 directories, the directory block size can be +any power of 2 size from the filesystem block size up to 65536. +.IP +The +.B version=ci +option enables ASCII only case-insensitive filename lookup and version +2 directories. Filenames are case-preserving, that is, the names +are stored in directories using the case they were created with. +.IP +Note: Version 1 directories are not supported. +.TP +.BI ftype= value +This feature allows the inode type to be stored in the directory +structure so that the +.BR readdir (3) +and +.BR getdents (2) +do not need to look up the inode to determine the inode type. + +The +.I value +is either 0 or 1, with 1 signifying that filetype information +will be stored in the directory structure. The default value is 1. + +When CRCs are enabled (the default), the ftype functionality is always +enabled, and cannot be turned off. +.IP +.RE +.TP +.BI \-p " protofile" +If the optional +.BI \-p " protofile" +argument is given, +.B mkfs.xfs +uses +.I protofile +as a prototype file and takes its directions from that file. +The blocks and inodes specifiers in the +.I protofile +are provided for backwards compatibility, but are otherwise unused. +The syntax of the protofile is defined by a number of tokens separated +by spaces or newlines. Note that the line numbers are not part of the +syntax but are meant to help you in the following discussion of the file +contents. +.nf +.sp .8v +.in +5 +\f71 /stand/\f1\f2diskboot\f1\f7 +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 $\f1 +.in -5 +.fi +.IP +Line 1 is a dummy string. +(It was formerly the bootfilename.) +It is present for backward +compatibility; boot blocks are not used on SGI systems. +.IP +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. +.IP +Line 2 contains two numeric values (formerly the numbers of blocks and inodes). +These are also merely for backward compatibility: two numeric values must +appear at this point for the proto file to be correctly parsed, +but their values are immaterial since they are ignored. +.IP +The lines 3 through 11 specify the files and directories you want to +include in this filesystem. Line 3 defines the +root directory. Other directories and +files that you want in the filesystem +are indicated by lines 4 through 6 and +lines 8 through 10. Line 11 contains +symbolic link syntax. +.IP +Notice the dollar sign +.RB ( $ ) +syntax on line 7. This syntax directs the +.B mkfs.xfs +command to terminate the branch of the filesystem it +is currently on and then continue +from the directory specified by +the next line, in this case line 8. +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 +.B $ +on lines 13 and 14 end the process, since no additional +specifications follow. +.IP +File specifications provide the following: +.IP + * file mode +.br + * user ID +.br + * group ID +.br + * the file's beginning contents +.P +.IP +A 6-character string defines the mode for +a file. The first character of this string +defines the file type. The character range +for this first character is +.B \-bcdpl. +A file may be a regular file, a block special file, +a character special file, directory files, named +pipes (first-in, first out files), and symbolic +links. +The second character of the mode string is +used to specify setuserID mode, in which case +it is +.BR u . +If setuserID mode is not specified, the second character is +.BR \- . +The third character of the mode string is +used to specify the setgroupID mode, in which +case it is +.BR g . +If setgroupID mode is not specified, the third character is +.BR \- . +The remaining characters of the mode string are +a three digit octal number. This octal number +defines the owner, group, and other read, write, +and execute permissions for the file, respectively. +For more information on file permissions, see the +.BR chmod (1) +command. +.IP +Following the mode character string are two +decimal number tokens that specify the user and group IDs +of the file's owner. +.IP +In a regular file, the next token specifies the +pathname from which the contents and size of the +file are copied. +In a block or character special file, the next token +are two decimal numbers that specify the major and minor +device numbers. +When a file is a symbolic link, the next token +specifies the contents of the link. + +When the file is a directory, the +.B mkfs.xfs +command creates the entries +.B dot +(.) and +.B dot-dot +(..) and then reads the list of names and file specifications +in a recursive manner for all of the entries +in the directory. A scan of the protofile is +always terminated with the dollar ( +.B $ +) token. +.TP +.B \-q +Quiet option. Normally +.B mkfs.xfs +prints the parameters of the filesystem +to be constructed; +the +.B \-q +flag suppresses this. +.TP +.BI \-r " realtime_section_options" +These options specify the location, size, and other parameters of the +real-time section of the filesystem. The valid +.I realtime_section_options +are: +.RS 1.2i +.TP +.BI rtdev= device +This is used to specify the +.I device +which should contain the real-time section of the filesystem. +The suboption value is the name of a block device. +.TP +.BI extsize= value +This is used to specify the size of the blocks in the real-time +section of the filesystem. This +.I value +must be a multiple of the filesystem block size. The minimum allowed +size is the filesystem block size or 4 KiB (whichever is larger); the +default size is the stripe width for striped volumes or 64 KiB for +non-striped volumes; the maximum allowed size is 1 GiB. The real-time +extent size should be carefully chosen to match the parameters of the +physical media used. +.TP +.BI size= value +This is used to specify the size of the real-time section. +This suboption is only needed if the real-time section of the +filesystem should occupy less space than the size of the partition +or logical volume containing the section. +.TP +.BI noalign +This option disables stripe size detection, enforcing a realtime device with no +stripe geometry. +.RE +.TP +.BI \-s " sector_size_options" +This option specifies the fundamental sector size of the filesystem. +The valid +.I sector_size_option +is: +.RS 1.2i +.TP +.BI size= value +The sector size is specified with a +.I value +in bytes. The default +.I sector_size +is 512 bytes. The minimum value for sector size is +512; the maximum is 32768 (32 KiB). The +.I sector_size +must be a power of 2 size and cannot be made larger than the +filesystem block size. +.IP +To specify any options on the command line in units of sectors, this +option must be specified first so that the sector size is +applied consistently to all options. +.RE +.TP +.BI \-L " label" +Set the filesystem +.IR label . +XFS filesystem labels can be at most 12 characters long; if +.I label +is longer than 12 characters, +.B mkfs.xfs +will not proceed with creating the filesystem. Refer to the +.BR mount "(8) and " xfs_admin (8) +manual entries for additional information. +.TP +.B \-N +Causes the file system parameters to be printed out without really +creating the file system. +.TP +.B \-K +Do not attempt to discard blocks at mkfs time. +.TP +.B \-V +Prints the version number and exits. +.SH CONFIGURATION FILE FORMAT +The optional default configuration file in +.B @sysconfdir@/xfs/mkfs/default +as well as any alternate configuration file specified via the +.B \-c +option must follow a simple ini-style format as shown below. +Available options consist of a subset of the parameters available +via the +.BR mkfs.xfs (8) +command line. +Currently all default parameters can only be either enabled or disabled, +with a value of 1 to enable or 0 to disable. +See below for a list of all supported configuration parameters and their +current built-in default settings. +.PP +.BI [data] +.br +.BI noalign=0 +.PP +.BI [inode] +.br +.BI align=1 +.br +.BI projid32bit=1 +.br +.BI sparse=0 +.PP +.BI [log] +.br +.BI lazy-count=1 +.PP +.BI [metadata] +.br +.BI crc=1 +.br +.BI finobt=1 +.br +.BI rmapbt=0 +.br +.BI reflink=0 +.PP +.BI [naming] +.br +.BI ftype=1 +.PP +.BI [rtdev] +.br +.BI noalign=0 +.PP +.SH SEE ALSO +.BR xfs (5), +.BR mkfs (8), +.BR mount (8), +.BR xfs_info (8), +.BR xfs_admin (8). +.SH BUGS +With a prototype file, it is not possible to specify hard links.