From: "Darrick J. Wong" <darrick.wong@oracle.com>
To: Dave Chinner <david@fromorbit.com>
Cc: linux-xfs@vger.kernel.org
Subject: Re: [PATCH 5/5] mkfs: document config files in mkfs.xfs(8)
Date: Wed, 14 Oct 2020 22:36:42 -0700 [thread overview]
Message-ID: <20201015053642.GP9832@magnolia> (raw)
In-Reply-To: <20201015032925.1574739-6-david@fromorbit.com>
On Thu, Oct 15, 2020 at 02:29:25PM +1100, Dave Chinner wrote:
> From: Dave Chinner <dchinner@redhat.com>
>
> So people know it exists.
Yay documentation!
> Signed-off-by: Dave Chinner <dchinner@redhat.com>
> ---
> man/man8/mkfs.xfs.8 | 113 +++++++++++++++++++++++++++++++++++++++++---
> 1 file changed, 106 insertions(+), 7 deletions(-)
>
> diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8
> index 0a7858748457..f70d91d994fa 100644
> --- a/man/man8/mkfs.xfs.8
> +++ b/man/man8/mkfs.xfs.8
> @@ -122,8 +122,46 @@ If the size of the block or sector is not specified, the default sizes
> Many feature options allow an optional argument of 0 or 1, to explicitly
> disable or enable the functionality.
> .SH OPTIONS
> +Options may be specified either on the command line or in a configuration file.
> +Not all command line options can be specified in configuration files; only the
> +command line options followed by a
> +.B [section]
> +label can be used in a configuration file.
> +.PP
> +Options that can be used in configuration files are grouped into related
> +sections containing multiple options.
> +Both the command line and configuration file formats use the same section and
"The command line options and configuration files use the same option
sections and grouping."?
> +option grouping.
> +Configuration file section names are described command line options in the list
/me stumbles over "are described command line options in the list".
"Configuration file section names are listed in the command line option
sections below."?
> +below.
> +Option names and values are the same for both command line
> +and configuration file specification.
> +.PP
> +Options specified are the combined set of command line parameters and
> +configuration file parameters.
> +Duplicated options will result in a respecification error, regardless of the
> +location they were specified at.
> +.TP
> +.BI \-c " configuration_file_option"
> +This option specifies the files that mkfs configuration will be obtained from.
> +The valid
> +.I configuration_file_option
> +is:
> +.RS 1.2i
> .TP
> +.BI options= name
> +The configuration options will be sourced from the file specified by the
> +.I name
> +option string.
> +This option can be use either an absolute or relative path to the configuration
> +file to be read.
> +.RE
> +.PP
> +.PD 0
> .BI \-b " block_size_options"
> +.TP
> +.BI [block]
We might want to call this out explicitly as the name of the section in
the config file.
--D
> +.PD
> This option specifies the fundamental block size of the filesystem.
> The valid
> .I block_size_option
> @@ -141,8 +179,12 @@ Although
> 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
> +.PP
> +.PD 0
> .BI \-m " global_metadata_options"
> +.TP
> +.BI [metadata]
> +.PD
> 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
> @@ -243,8 +285,12 @@ reflink-enabled XFS filesystems. To use filesystem DAX with XFS, specify the
> .B \-m reflink=0
> option to mkfs.xfs to disable the reflink feature.
> .RE
> -.TP
> +.PP
> +.PD 0
> .BI \-d " data_section_options"
> +.TP
> +.BI [data]
> +.PD
> These options specify the location, size, and other parameters of the
> data section of the filesystem. The valid
> .I data_section_options
> @@ -416,8 +462,12 @@ 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
> +.PP
> +.PD 0
> .BI \-i " inode_options"
> +.TP
> +.BI [inode]
> +.PD
> 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.
> @@ -537,8 +587,12 @@ 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
> +.PP
> +.PD 0
> .BI \-l " log_section_options"
> +.TP
> +.BI [log]
> +.PD
> These options specify the location, size, and other parameters of the
> log section of the filesystem. The valid
> .I log_section_options
> @@ -651,8 +705,12 @@ is 1 (on) so you must specify
> if you want to disable this feature for older kernels which don't support
> it.
> .RE
> -.TP
> +.PP
> +.PD 0
> .BI \-n " naming_options"
> +.TP
> +.BI [naming]
> +.PD
> These options specify the version and size parameters for the naming
> (directory) area of the filesystem. The valid
> .I naming_options
> @@ -858,8 +916,12 @@ to be constructed;
> the
> .B \-q
> flag suppresses this.
> -.TP
> +.PP
> +.PD 0
> .BI \-r " realtime_section_options"
> +.TP
> +.BI [realtime]
> +.PD
> These options specify the location, size, and other parameters of the
> real-time section of the filesystem. The valid
> .I realtime_section_options
> @@ -893,8 +955,12 @@ or logical volume containing the section.
> This option disables stripe size detection, enforcing a realtime device with no
> stripe geometry.
> .RE
> -.TP
> +.PP
> +.PD 0
> .BI \-s " sector_size_options"
> +.TP
> +.BI [sector]
> +.PD
> This option specifies the fundamental sector size of the filesystem.
> The valid
> .I sector_size_option
> @@ -933,6 +999,39 @@ Do not attempt to discard blocks at mkfs time.
> .TP
> .B \-V
> Prints the version number and exits.
> +.SH Configuration File Format
> +The configuration file uses a basic INI format to specify sections and options
> +within a section.
> +Section and option names are case sensitive.
> +Section names must not contain whitespace.
> +Options are name-value pairs, ended by the first whitespace in the line.
> +Option names cannot contain whitespace.
> +Full line comments can be added by starting a line with a # symbol.
> +If values contain whitespace, then it must be quoted.
> +.PP
> +The following example configuration file sets the block size to 4096 bytes,
> +turns on reverse mapping btrees and sets the inode size to 2048 bytes.
> +.PP
> +.PD 0
> +# Example mkfs.xfs configuration file
> +.HP
> +.HP
> +[block]
> +.HP
> +size=4k
> +.HP
> +.HP
> +[metadata]
> +.HP
> +rmapbt=1
> +.HP
> +.HP
> +[inode]
> +.HP
> +size=2048
> +.HP
> +.PD
> +.PP
> .SH SEE ALSO
> .BR xfs (5),
> .BR mkfs (8),
> --
> 2.28.0
>
next prev parent reply other threads:[~2020-10-15 5:36 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-15 3:29 [PATCH 0/5] mkfs: Configuration file defined options Dave Chinner
2020-10-15 3:29 ` [PATCH 1/5] build: add support for libinih for mkfs Dave Chinner
2020-10-15 5:40 ` Darrick J. Wong
2020-10-15 3:29 ` [PATCH 2/5] mkfs: add initial ini format config file parsing support Dave Chinner
2020-10-15 5:46 ` Darrick J. Wong
2020-10-15 6:09 ` Dave Chinner
2020-10-15 3:29 ` [PATCH 3/5] mkfs: constify various strings Dave Chinner
2020-10-15 5:31 ` Darrick J. Wong
2020-10-15 3:29 ` [PATCH 4/5] mkfs: hook up suboption parsing to ini files Dave Chinner
2020-10-15 5:24 ` Darrick J. Wong
2020-10-15 3:29 ` [PATCH 5/5] mkfs: document config files in mkfs.xfs(8) Dave Chinner
2020-10-15 5:36 ` Darrick J. Wong [this message]
2020-10-15 5:13 ` [PATCH 0/5] mkfs: Configuration file defined options Darrick J. Wong
2020-10-15 5:32 ` Dave Chinner
2020-10-15 5:39 ` Darrick J. Wong
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201015053642.GP9832@magnolia \
--to=darrick.wong@oracle.com \
--cc=david@fromorbit.com \
--cc=linux-xfs@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).