* [PATCH v4 0/4] xfsprogs: add mkfs.xfs configuration file parsing support
@ 2018-05-29 22:05 Luis R. Rodriguez
2018-05-29 22:06 ` [PATCH v4 1/4] mkfs: distinguish between struct sb_feat_args and struct cli_params Luis R. Rodriguez
` (3 more replies)
0 siblings, 4 replies; 21+ messages in thread
From: Luis R. Rodriguez @ 2018-05-29 22:05 UTC (permalink / raw)
To: sandeen, linux-xfs
Cc: darrick.wong, jack, jeffm, okurz, lpechacek, jtulak, Luis R. Rodriguez
This is v4 series addresses the feedback from Darrick mostly on man page
text changes and a few minor code updates listed below. I've also
amended the patches with Reviewed-by tags where appropriate, and rebased
it onto the latest origin/for-next branch. The details of the changes in
this v4 iteration and prior are listed below.
You can also get the code from my kernel.org xfsprogs-dev 20180529-own-parser-v4
branch [0].
Reviews, questions, or rants are greatly appreciated.
[0] https://git.kernel.org/pub/scm/linux/kernel/git/mcgrof/xfsprogs-dev.git/log/?h=20180529-own-parser-v4
Changes on v4:
- Tons of man page documentation enhancements from Darrick.
- Adjusted a few error code messages/ paths to make more sense as per
Darrick's feedback.
Changes on v3:
- Prefix errors on the configuration parsing with config file used and
exact line.
- Use uint64_t throughout all parsers as requested.
- Parse the CLI early for -c as I originally had implemented this on v1
but now platform_getoptreset() to reset the opts.
- Drop the enum for the source type for the configuration file type,
note that since we rely on the stack to set the variables we should
then always set the dft.src on main().
- Use getline() for fetching lines as requested
- Add a special iscomment() and isempty() to handle all space and
comment parsing. Now when PARSE_INVALID issued we really mean it.
- Embrace latest bikeshed preferences:
config.c, config.h, random function names
- Add man pages to be parsed via configure so that @sysconfigdir@ gets
properly parsed
- get_confopts() now iterates over the known sections tab and gives you
the right struct right away.
- Add respecification checks for a section.
- Add respecification checks for -c, -c is only allowed once.
- Add --sysconfigdir to debian/rules, note that if you *don't* set
--sysconfigdir your man pages will end up with ${prefix}. We could
add a secondary target parsing just in case, or we can do some hacks
with autoconf for this, but I don't think its worth it. Other packages
deal with this by having ./configure always run with --sysconfigdir
set (see systemd for instance).
- Reduced the number of declared enums, only enums for the config
subparams which are currently supported for parsing are declared.
- mkfs.xfs -c foo now will search for $PWD/foo and if that fails the
sysconfigdir/mkfs.xfs.d/foo.
- mkfs.xfs -c ../foo works and so should ./foo, etc.
- The MKFS_XFS_CONFIG variable support was dropped in favor or just
allowing the user to specify the full path now.
- Embraces xfsprogs coding style, c'est la vie.
Changes on v2:
- Stayed with our own parser as its the smallest and we're willing to
maintain it as its simple and clear.
- Use -c for the configuration file, and drop the "type" nomenclature to
avoid confusion on the interwebs.
- Start to split files off
- Duplicate a bit of items as suggested at LSFMM for the configuration
parser structures. We can later consolidate if we think its really
needed, however we want the freedom to change these as we see fit and
most importantly keep the code apart.
- Conflict resolution and validation is managed now by piggy backing off
of the idea of using the defaults to instantiate CLI parameters. CLI
always overrides.
Luis R. Rodriguez (4):
mkfs: distinguish between struct sb_feat_args and struct cli_params
mkfs: move shared config structs and into their own headers
mkfs.xfs: add configuration file parsing support using our own parser
debian/rules: use the new sysconfdir configuration setting
configure.ac | 6 +-
debian/rules | 4 +-
include/builddefs.in | 2 +
man/man5/Makefile | 2 +
man/man5/mkfs.xfs.d.5.in | 151 ++++++++
man/man8/Makefile | 2 +
man/man8/{mkfs.xfs.8 => mkfs.xfs.8.in} | 27 ++
mkfs/Makefile | 2 +-
mkfs/config.c | 645 +++++++++++++++++++++++++++++++++
mkfs/config.h | 86 +++++
mkfs/xfs_mkfs.c | 130 ++++---
11 files changed, 994 insertions(+), 63 deletions(-)
create mode 100644 man/man5/mkfs.xfs.d.5.in
rename man/man8/{mkfs.xfs.8 => mkfs.xfs.8.in} (96%)
create mode 100644 mkfs/config.c
create mode 100644 mkfs/config.h
--
2.16.3
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v4 1/4] mkfs: distinguish between struct sb_feat_args and struct cli_params
2018-05-29 22:05 [PATCH v4 0/4] xfsprogs: add mkfs.xfs configuration file parsing support Luis R. Rodriguez
@ 2018-05-29 22:06 ` Luis R. Rodriguez
2018-05-29 22:06 ` [PATCH v4 2/4] mkfs: move shared config structs and into their own headers Luis R. Rodriguez
` (2 subsequent siblings)
3 siblings, 0 replies; 21+ messages in thread
From: Luis R. Rodriguez @ 2018-05-29 22:06 UTC (permalink / raw)
To: sandeen, linux-xfs
Cc: darrick.wong, jack, jeffm, okurz, lpechacek, jtulak, Luis R. Rodriguez
The struct sb_feat_args will actually be shared between the code which
processes command line options and the configuration file, as such we
need to clarify and reflect this clearly in documentation.
Reviewed-by: Dave Chinner <dchinner@redhat.com>
Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
---
mkfs/xfs_mkfs.c | 45 ++++++++++++++++++++++++++++-----------------
1 file changed, 28 insertions(+), 17 deletions(-)
diff --git a/mkfs/xfs_mkfs.c b/mkfs/xfs_mkfs.c
index 2de017130831..84e9d6b2562a 100644
--- a/mkfs/xfs_mkfs.c
+++ b/mkfs/xfs_mkfs.c
@@ -707,26 +707,18 @@ cli_opt_set(
}
/*
- * Options configured on the command line.
- *
- * This stores all the specific config parameters the user sets on the command
- * line. We do not use these values directly - they are inputs to the mkfs
- * geometry validation and override any default configuration value we have.
+ * Shared superblock configuration options
*
- * We don't keep flags to indicate what parameters are set - if we need to check
- * if an option was set on the command line, we check the relevant entry in the
- * option table which records whether it was specified in the .seen and
- * .str_seen variables in the table.
+ * These options provide shared configuration tunables for the filesystem
+ * superblock. There are three possible sources for these options set, each
+ * source can overriding the later source:
*
- * Some parameters are stored as strings for post-parsing after their dependent
- * options have been resolved (e.g. block size and sector size have been parsed
- * and validated).
+ * o built-in defaults
+ * o configuration file (XXX)
+ * o command line
*
- * This allows us to check that values have been set without needing separate
- * flags for each value, and hence avoids needing to record and check for each
- * specific option that can set the value later on in the code. In the cases
- * where we don't have a cli_params structure around, the above cli_opt_set()
- * function can be used.
+ * These values are not used directly - they are inputs into the mkfs geometry
+ * validation.
*/
struct sb_feat_args {
int log_version;
@@ -747,6 +739,25 @@ struct sb_feat_args {
bool nortalign;
};
+/*
+ * Options configured on the command line.
+ *
+ * This stores all the specific config parameters the user sets on the command
+ * line. We don't keep flags to indicate what parameters are set - if we need
+ * to check if an option was set on the command line, we check the relevant
+ * entry in the option table which records whether it was specified in the
+ * .seen and .str_seen variables in the table.
+ *
+ * Some parameters are stored as strings for post-parsing after their dependent
+ * options have been resolved (e.g. block size and sector size have been parsed
+ * and validated).
+ *
+ * This allows us to check that values have been set without needing separate
+ * flags for each value, and hence avoids needing to record and check for each
+ * specific option that can set the value later on in the code. In the cases
+ * where we don't have a cli_params structure around, the function cli_opt_set()
+ * function can be used.
+ */
struct cli_params {
int sectorsize;
int blocksize;
--
2.16.3
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH v4 2/4] mkfs: move shared config structs and into their own headers
2018-05-29 22:05 [PATCH v4 0/4] xfsprogs: add mkfs.xfs configuration file parsing support Luis R. Rodriguez
2018-05-29 22:06 ` [PATCH v4 1/4] mkfs: distinguish between struct sb_feat_args and struct cli_params Luis R. Rodriguez
@ 2018-05-29 22:06 ` Luis R. Rodriguez
2018-05-30 1:28 ` Dave Chinner
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
2018-05-29 22:06 ` [PATCH v4 4/4] debian/rules: use the new sysconfdir configuration setting Luis R. Rodriguez
3 siblings, 1 reply; 21+ messages in thread
From: Luis R. Rodriguez @ 2018-05-29 22:06 UTC (permalink / raw)
To: sandeen, linux-xfs
Cc: darrick.wong, jack, jeffm, okurz, lpechacek, jtulak, Luis R. Rodriguez
Both struct sb_feat_args and struct mkfs_default_params will be shared
between CLI processing and the configuration file processing added later,
so move these to their own header.
This will help ensure we split things neatly later and also will help
ensure the configuration file processing code from the CLI code are kept
separate and cannot touch each other's data structures. This also makes
it clear what is actually shared between both.
There are no introduced functional changes in this commit and no
documentation changes, this is just code shuffling.
Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
---
mkfs/config.h | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
mkfs/xfs_mkfs.c | 55 +---------------------------------------
2 files changed, 79 insertions(+), 54 deletions(-)
create mode 100644 mkfs/config.h
diff --git a/mkfs/config.h b/mkfs/config.h
new file mode 100644
index 000000000000..e5ea968e2d65
--- /dev/null
+++ b/mkfs/config.h
@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2000-2005 Silicon Graphics, Inc.
+ * Copyright (c) 2016-2017 Red Hat, Inc.
+ * All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it would be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+#ifndef _XFS_MKFS_CONFIG_H
+#define _XFS_MKFS_CONFIG_H
+
+struct fsxattr;
+
+/*
+ * Shared superblock configuration options
+ *
+ * These options provide shared configuration tunables for the filesystem
+ * superblock. There are three possible sources for these options set, each
+ * source can overriding the later source:
+ *
+ * o built-in defaults
+ * o configuration file (XXX)
+ * o command line
+ *
+ * These values are not used directly - they are inputs into the mkfs geometry
+ * validation.
+ */
+struct sb_feat_args {
+ int log_version;
+ int attr_version;
+ int dir_version;
+ bool inode_align; /* XFS_SB_VERSION_ALIGNBIT */
+ bool nci; /* XFS_SB_VERSION_BORGBIT */
+ bool lazy_sb_counters; /* XFS_SB_VERSION2_LAZYSBCOUNTBIT */
+ bool parent_pointers; /* XFS_SB_VERSION2_PARENTBIT */
+ bool projid32bit; /* XFS_SB_VERSION2_PROJID32BIT */
+ bool crcs_enabled; /* XFS_SB_VERSION2_CRCBIT */
+ bool dirftype; /* XFS_SB_VERSION2_FTYPE */
+ bool finobt; /* XFS_SB_FEAT_RO_COMPAT_FINOBT */
+ bool spinodes; /* XFS_SB_FEAT_INCOMPAT_SPINODES */
+ bool rmapbt; /* XFS_SB_FEAT_RO_COMPAT_RMAPBT */
+ bool reflink; /* XFS_SB_FEAT_RO_COMPAT_REFLINK */
+ bool nodalign;
+ bool nortalign;
+};
+
+/*
+ * Default filesystem features and configuration values
+ *
+ * This structure contains the default mkfs values that are to be used when
+ * a user does not specify the option on the command line. We do not use these
+ * values directly - they are inputs to the mkfs geometry validation and
+ * calculations.
+ */
+struct mkfs_default_params {
+ char *source; /* where the defaults came from */
+
+ int sectorsize;
+ int blocksize;
+
+ /* feature flags that are set */
+ struct sb_feat_args sb_feat;
+
+ /* root inode characteristics */
+ struct fsxattr fsx;
+};
+
+#endif /* _XFS_MKFS_CONFIG_H */
diff --git a/mkfs/xfs_mkfs.c b/mkfs/xfs_mkfs.c
index 84e9d6b2562a..4664e507afbf 100644
--- a/mkfs/xfs_mkfs.c
+++ b/mkfs/xfs_mkfs.c
@@ -21,6 +21,7 @@
#include "xfs_multidisk.h"
#include "libxcmd.h"
#include "fsgeom.h"
+#include "config.h"
#define TERABYTES(count, blog) ((uint64_t)(count) << (40 - (blog)))
@@ -706,39 +707,6 @@ cli_opt_set(
opts->subopt_params[subopt].str_seen;
}
-/*
- * Shared superblock configuration options
- *
- * These options provide shared configuration tunables for the filesystem
- * superblock. There are three possible sources for these options set, each
- * source can overriding the later source:
- *
- * o built-in defaults
- * o configuration file (XXX)
- * o command line
- *
- * These values are not used directly - they are inputs into the mkfs geometry
- * validation.
- */
-struct sb_feat_args {
- int log_version;
- int attr_version;
- int dir_version;
- bool inode_align; /* XFS_SB_VERSION_ALIGNBIT */
- bool nci; /* XFS_SB_VERSION_BORGBIT */
- bool lazy_sb_counters; /* XFS_SB_VERSION2_LAZYSBCOUNTBIT */
- bool parent_pointers; /* XFS_SB_VERSION2_PARENTBIT */
- bool projid32bit; /* XFS_SB_VERSION2_PROJID32BIT */
- bool crcs_enabled; /* XFS_SB_VERSION2_CRCBIT */
- bool dirftype; /* XFS_SB_VERSION2_FTYPE */
- bool finobt; /* XFS_SB_FEAT_RO_COMPAT_FINOBT */
- bool spinodes; /* XFS_SB_FEAT_INCOMPAT_SPINODES */
- bool rmapbt; /* XFS_SB_FEAT_RO_COMPAT_RMAPBT */
- bool reflink; /* XFS_SB_FEAT_RO_COMPAT_REFLINK */
- bool nodalign;
- bool nortalign;
-};
-
/*
* Options configured on the command line.
*
@@ -850,27 +818,6 @@ struct mkfs_params {
struct sb_feat_args sb_feat;
};
-/*
- * Default filesystem features and configuration values
- *
- * This structure contains the default mkfs values that are to be used when
- * a user does not specify the option on the command line. We do not use these
- * values directly - they are inputs to the mkfs geometry validation and
- * calculations.
- */
-struct mkfs_default_params {
- char *source; /* where the defaults came from */
-
- int sectorsize;
- int blocksize;
-
- /* feature flags that are set */
- struct sb_feat_args sb_feat;
-
- /* root inode characteristics */
- struct fsxattr fsx;
-};
-
static void __attribute__((noreturn))
usage( void )
{
--
2.16.3
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser
2018-05-29 22:05 [PATCH v4 0/4] xfsprogs: add mkfs.xfs configuration file parsing support Luis R. Rodriguez
2018-05-29 22:06 ` [PATCH v4 1/4] mkfs: distinguish between struct sb_feat_args and struct cli_params Luis R. Rodriguez
2018-05-29 22:06 ` [PATCH v4 2/4] mkfs: move shared config structs and into their own headers Luis R. Rodriguez
@ 2018-05-29 22:06 ` Luis R. Rodriguez
2018-05-29 23:31 ` Darrick J. Wong
` (7 more replies)
2018-05-29 22:06 ` [PATCH v4 4/4] debian/rules: use the new sysconfdir configuration setting Luis R. Rodriguez
3 siblings, 8 replies; 21+ messages in thread
From: Luis R. Rodriguez @ 2018-05-29 22:06 UTC (permalink / raw)
To: sandeen, linux-xfs
Cc: darrick.wong, jack, jeffm, okurz, lpechacek, jtulak, Luis R. Rodriguez
You may want to stick to specific set of configuration options when
creating filesystems with mkfs.xfs -- sometimes due to pure technical
reasons, but some other times to ensure systems remain compatible as
new features are introduced with older kernels, or if you always want
to take advantage of some new feature which would otherwise typically
be disruptive.
This adds support for parsing a configuration file to override defaults
parameters to be used for mkfs.xfs.
We define an XFS configuration directory, /etc/mkfs.xfs.d/ and allow for
different configuration files, if none is specified we look for the
default configuration file, /etc/mkfs.xfs.d/default. You can override
with -c. For instance, if you specify:
mkfs.xfs -c experimental -f /dev/loop0
The search path for the configuration file will be:
1) $PWD/experimental
2) /etc/mkfs.xfs.d/experimental
Absolute paths are supported, in which case they will be used directly
and the mkfs.xfs.d directory is ignored.
To verify what configuration file is used on a system use the typical:
mkfs.xfs -N
There is only a subset of options allowed to be set on the configuration
file. The default parameters you can override on a configuration file and
their current built-in default settings are:
[data]
noalign=0
[inode]
align=1
projid32bit=1
sparse=0
[log]
lazy-count=1
[metadata]
crc=1
finobt=1
rmapbt=0
reflink=0
[naming]
ftype=1
[rtdev]
noalign=0
Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
---
configure.ac | 6 +-
include/builddefs.in | 2 +
man/man5/Makefile | 2 +
man/man5/mkfs.xfs.d.5.in | 151 ++++++++
man/man8/Makefile | 2 +
man/man8/{mkfs.xfs.8 => mkfs.xfs.8.in} | 27 ++
mkfs/Makefile | 2 +-
mkfs/config.c | 645 +++++++++++++++++++++++++++++++++
mkfs/config.h | 10 +-
mkfs/xfs_mkfs.c | 76 +++-
10 files changed, 909 insertions(+), 14 deletions(-)
create mode 100644 man/man5/mkfs.xfs.d.5.in
rename man/man8/{mkfs.xfs.8 => mkfs.xfs.8.in} (96%)
create mode 100644 mkfs/config.c
diff --git a/configure.ac b/configure.ac
index 508eefede073..94c5bda725f2 100644
--- a/configure.ac
+++ b/configure.ac
@@ -233,5 +233,9 @@ AC_CHECK_SIZEOF([char *])
AC_TYPE_UMODE_T
AC_MANUAL_FORMAT
-AC_CONFIG_FILES([include/builddefs])
+AC_CONFIG_FILES([
+ include/builddefs
+ man/man5/mkfs.xfs.d.5
+ man/man8/mkfs.xfs.8
+])
AC_OUTPUT
diff --git a/include/builddefs.in b/include/builddefs.in
index 8aac06cf90dc..e1ee9f7ba086 100644
--- a/include/builddefs.in
+++ b/include/builddefs.in
@@ -62,6 +62,7 @@ PKG_LIB_DIR = @libdir@@libdirsuffix@
PKG_INC_DIR = @includedir@/xfs
DK_INC_DIR = @includedir@/disk
PKG_MAN_DIR = @mandir@
+PKG_ETC_DIR = @sysconfdir@
PKG_DOC_DIR = @datadir@/doc/@pkg_name@
PKG_LOCALE_DIR = @datadir@/locale
@@ -196,6 +197,7 @@ endif
GCFLAGS = $(DEBUG) \
-DVERSION=\"$(PKG_VERSION)\" -DLOCALEDIR=\"$(PKG_LOCALE_DIR)\" \
+ -DROOT_SYSCONFDIR=\"$(PKG_ETC_DIR)\" \
-DPACKAGE=\"$(PKG_NAME)\" -I$(TOPDIR)/include -I$(TOPDIR)/libxfs
ifeq ($(ENABLE_GETTEXT),yes)
diff --git a/man/man5/Makefile b/man/man5/Makefile
index fe0aef6f016b..0b33122b064e 100644
--- a/man/man5/Makefile
+++ b/man/man5/Makefile
@@ -19,3 +19,5 @@ install : default
$(INSTALL) -m 755 -d $(MAN_DEST)
$(INSTALL_MAN)
install-dev :
+
+LDIRT += mkfs.xfs.d.5
diff --git a/man/man5/mkfs.xfs.d.5.in b/man/man5/mkfs.xfs.d.5.in
new file mode 100644
index 000000000000..287877ce029d
--- /dev/null
+++ b/man/man5/mkfs.xfs.d.5.in
@@ -0,0 +1,151 @@
+.TH mkfs.xfs.d 5
+.SH NAME
+mkfs.xfs.d \- mkfs.xfs configuration directory
+.SH DESCRIPTION
+.B mkfs.xfs (8)
+uses a set of initial default parameters for configuration.
+
+The built-in mkfs defaults are decided by the XFS community. New features are
+only enabled by default when the community consider them stable. One can
+override these defaults on the
+.B mkfs.xfs (8)
+command line, but there are cases where it is desirable for the distro or the
+system administrator to establish their own supported defaults in a uniform
+manner, regardless of the version of
+.B mkfs.xfs (8)
+used. This may be desirable for example on systems with old kernels
+where the built-in default
+.B mkfs.xfs (8)
+parameters create a filesystem that is not supported by the old kernel.
+In such situations it would also be unclear what parameters are needed to
+produce a compatible filesystem, having a configuration file present ensures
+that if newer versions of
+.B mkfs.xfs (8)
+are deployed, creating a filesystem will remain compatible. Overriding
+.B mkfs.xfs (8)
+built-in defaults may also be desirable if you have a series of systems with
+different kernels and want to be able to create filesystems which all systems
+are able to support properly.
+.PP
+The XFS configuration directory
+.B mkfs.xfs.d (5)
+can be used as a home to define different configuration files which can be used
+to override the built-in default parameters by
+.B mkfs.xfs (8).
+If the
+.B -c
+parameter is not used, the default configuration file:
+.IP
+.I @sysconfdir@/mkfs.xfs.d/default
+.PP
+will be looked for first and if present will be used to override
+.B mkfs.xfs (8)
+built-in default parameters.
+.PP
+You can override the default configuration file by specifying its name when
+using
+.B mkfs.xfs (8)
+by using the
+.B -c
+parameter.
+.PP
+If the path does not start with a '.', the current working directory is
+searched for the file. If the file is not found there, the
+.B mkfs.xfs.d (5)
+directory is searched for the file.
+.PP
+If
+.B -c
+is used with relative path with which has a leading '.' character, the given
+path is used directly, so the configuration file will be relative to the
+current working directory.
+.PP
+If the
+.B -c
+argument starts with a '/', it is considered an absolute path, and opened.
+.PP
+For example:
+.IP
+.B mkfs.xfs -c experimental -f /dev/sda1
+.PP
+Will make
+.B mkfs.xfs (8)
+look for the following configuration files and use the first one it finds:
+.IP
+.B $PWD/experimental
+.br
+.B @sysconfdir@/mkfs.xfs.d/experimental
+.PP
+If you used an absolute path, for example:
+.IP
+.B mkfs.xfs -c /tmp/experimental -f /dev/sda1
+.PP
+Then only the configuration file /tmp/experimental will be looked for and
+used if present.
+.PP
+If you use the
+.B -c
+parameter the configuration file must be present and must parse correctly.
+.PP
+Parameters passed to the
+.B mkfs.xfs (8)
+command line always override any defaults set by the configuration file.
+.PP
+.B mkfs.xfs (8)
+will always describe what configuration file was used, if any
+was used at all. To verify which configuration file would be used prior to
+execution of
+.B mkfs.xfs (8)
+you can use
+.I mkfs.xfs -N.
+.PP
+.SH DEFAULT PARAMETERS
+Default parameters for
+.B mkfs.xfs (8)
+consists of a small subset of the parameters one can set with on the command
+line. Currently all default parameters can only be either enabled or disabled,
+you can set their value to 1 to enable or 0 to disable. Below we list the
+different supported default parameters which can be defined on configuration
+files, along with the current built-in setting.
+.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 mkfs.xfs (8),
+.BR xfsctl (3),
+.BR xfs_info (8),
+.BR xfs_admin (8),
+.BR xfsdump (8),
+.BR xfsrestore (8).
diff --git a/man/man8/Makefile b/man/man8/Makefile
index 36620da172ae..2a6548079997 100644
--- a/man/man8/Makefile
+++ b/man/man8/Makefile
@@ -19,3 +19,5 @@ install : default
$(INSTALL) -m 755 -d $(MAN_DEST)
$(INSTALL_MAN)
install-dev :
+
+LDIRT += mkfs.xfs.8
diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8.in
similarity index 96%
rename from man/man8/mkfs.xfs.8
rename to man/man8/mkfs.xfs.8.in
index 4b8c78c37806..81e2753bd2b5 100644
--- a/man/man8/mkfs.xfs.8
+++ b/man/man8/mkfs.xfs.8.in
@@ -83,6 +83,24 @@ and
.B \-l internal \-l size=10m
are equivalent.
.PP
+An optional XFS configuration file directory
+.B mkfs.xfs.d (5)
+exists to help fine tune different default parameters which can be used when
+calling
+.B mkfs.xfs (8).
+If present, and if
+.B -c
+is not used, the default configuration file @sysconfigdir@/mkfs.xfs.d/default
+will be used to override system build-in defaults. Refer to mkfs.xfs.d (5)
+for a list of current defaults and further details.
+Command line arguments directly passed to
+.B mkfs.xfs (8)
+will always override parameters set in the configuration file.
+You can override the configuration file used by using the
+.B -c
+parameter, further explained below and in
+.B mkfs.xfs.d (5)
+.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,
@@ -123,6 +141,14 @@ Many feature options allow an optional argument of 0 or 1, to explicitly
disable or enable the functionality.
.SH OPTIONS
.TP
+.BI \-c " configuration-file"
+Override the configuration file used. If a relative path is given the search
+path for the configuration file is your current directory and then the
+.B mkfs.xfs.d (5)
+directory. If an absolute path is given it is used directly. For more details
+refer to
+.B mkfs.xfs.d (5)
+.TP
.BI \-b " block_size_options"
This option specifies the fundamental block size of the filesystem.
The valid
@@ -923,6 +949,7 @@ Prints the version number and exits.
.SH SEE ALSO
.BR xfs (5),
.BR mkfs (8),
+.BR mkfs.xfs.d (5),
.BR mount (8),
.BR xfs_info (8),
.BR xfs_admin (8).
diff --git a/mkfs/Makefile b/mkfs/Makefile
index c84f9b6ae63b..c7815b3e106b 100644
--- a/mkfs/Makefile
+++ b/mkfs/Makefile
@@ -8,7 +8,7 @@ include $(TOPDIR)/include/builddefs
LTCOMMAND = mkfs.xfs
HFILES =
-CFILES = proto.c xfs_mkfs.c
+CFILES = proto.c xfs_mkfs.c config.c
LLDLIBS += $(LIBXFS) $(LIBXCMD) $(LIBFROG) $(LIBRT) $(LIBPTHREAD) $(LIBBLKID) \
$(LIBUUID)
diff --git a/mkfs/config.c b/mkfs/config.c
new file mode 100644
index 000000000000..0b4aebe51903
--- /dev/null
+++ b/mkfs/config.c
@@ -0,0 +1,645 @@
+/*
+ * Copyright (c) 2018 Luis R. Rodriguez <mcgrof@kernel.org>
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it would be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
+
+#include <ctype.h>
+#include <dirent.h>
+#include <fcntl.h>
+
+#include "libxfs.h"
+#include "config.h"
+
+/*
+ * Enums for each configuration option. All these currently match the CLI
+ * parameters for now but this may change later, so we keep all this code
+ * and definitions separate. The rules for configuration parameters may also
+ * differ.
+ *
+ * We only provide definitions for what we currently support parsing.
+ */
+
+enum data_subopts {
+ D_NOALIGN = 0,
+};
+
+enum inode_subopts {
+ I_ALIGN = 0,
+ I_PROJID32BIT,
+ I_SPINODES,
+};
+
+enum log_subopts {
+ L_LAZYSBCNTR = 0,
+};
+
+enum metadata_subopts {
+ M_CRC = 0,
+ M_FINOBT,
+ M_RMAPBT,
+ M_REFLINK,
+};
+
+enum naming_subopts {
+ N_FTYPE = 0,
+};
+
+enum rtdev_subopts {
+ R_NOALIGN = 0,
+};
+
+/* Just define the max options array size manually right now */
+#define MAX_SUBOPTS 4
+
+static int
+data_config_parser(
+ struct mkfs_default_params *dft,
+ int psubopt,
+ uint64_t value)
+{
+ enum data_subopts subopt = psubopt;
+
+ switch (subopt) {
+ case D_NOALIGN:
+ dft->sb_feat.nodalign = value;
+ return 0;
+ }
+ return EINVAL;
+}
+
+static int
+inode_config_parser(
+ struct mkfs_default_params *dft,
+ int psubopt,
+ uint64_t value)
+{
+ enum inode_subopts subopt = psubopt;
+
+ switch (subopt) {
+ case I_ALIGN:
+ dft->sb_feat.inode_align = value;
+ return 0;
+ case I_PROJID32BIT:
+ dft->sb_feat.projid32bit = value;
+ return 0;
+ case I_SPINODES:
+ dft->sb_feat.spinodes = value;
+ return 0;
+ }
+ return EINVAL;
+}
+
+static int
+log_config_parser(
+ struct mkfs_default_params *dft,
+ int psubopt,
+ uint64_t value)
+{
+ enum log_subopts subopt = psubopt;
+
+ switch (subopt) {
+ case L_LAZYSBCNTR:
+ dft->sb_feat.lazy_sb_counters = value;
+ return 0;
+ }
+ return EINVAL;
+}
+
+static int
+metadata_config_parser(
+ struct mkfs_default_params *dft,
+ int psubopt,
+ uint64_t value)
+{
+ enum metadata_subopts subopt = psubopt;
+
+ switch (subopt) {
+ case M_CRC:
+ dft->sb_feat.crcs_enabled = value;
+ if (dft->sb_feat.crcs_enabled)
+ dft->sb_feat.dirftype = true;
+ return 0;
+ case M_FINOBT:
+ dft->sb_feat.finobt = value;
+ return 0;
+ case M_RMAPBT:
+ dft->sb_feat.rmapbt = value;
+ return 0;
+ case M_REFLINK:
+ dft->sb_feat.reflink = value;
+ return 0;
+ }
+ return EINVAL;
+}
+
+static int
+naming_config_parser(
+ struct mkfs_default_params *dft,
+ int psubopt,
+ uint64_t value)
+{
+ enum naming_subopts subopt = psubopt;
+
+ switch (subopt) {
+ case N_FTYPE:
+ dft->sb_feat.dirftype = value;
+ return 0;
+ }
+ return EINVAL;
+}
+
+static int
+rtdev_config_parser(
+ struct mkfs_default_params *dft,
+ int psubopt,
+ uint64_t value)
+{
+ enum rtdev_subopts subopt = psubopt;
+
+ switch (subopt) {
+ case R_NOALIGN:
+ dft->sb_feat.nortalign = value;
+ return 0;
+ }
+ return EINVAL;
+}
+
+struct confopts {
+ const char *name;
+ const char *subopts[MAX_SUBOPTS];
+ int (*parser)(struct mkfs_default_params *dft,
+ int psubopt, uint64_t value);
+ bool seen;
+} confopts_tab[] = {
+ {
+ .name = "data",
+ .subopts = {
+ [D_NOALIGN] = "noalign",
+ },
+ .parser = data_config_parser,
+ },
+ {
+ .name = "inode",
+ .subopts = {
+ [I_ALIGN] = "align",
+ [I_PROJID32BIT] = "projid32bit",
+ [I_SPINODES] = "sparse",
+ },
+ .parser = inode_config_parser,
+ },
+ {
+ .name = "log",
+ .subopts = {
+ [L_LAZYSBCNTR] = "lazy-count",
+ },
+ .parser = log_config_parser,
+ },
+ {
+ .name = "naming",
+ .subopts = {
+ [N_FTYPE] = "ftype",
+ },
+ .parser = naming_config_parser,
+ },
+ {
+ .name = "rtdev",
+ .subopts = {
+ [R_NOALIGN] = "noalign",
+ },
+ .parser = rtdev_config_parser,
+ },
+ {
+ .name = "metadata",
+ .subopts = {
+ [M_CRC] = "crc",
+ [M_FINOBT] = "finobt",
+ [M_RMAPBT] = "rmapbt",
+ [M_REFLINK] = "reflink",
+ },
+ .parser = metadata_config_parser,
+ },
+};
+
+static struct confopts *
+get_confopts(
+ const char *section)
+{
+ unsigned int i;
+ struct confopts *opts;
+
+ for (i=0; i < ARRAY_SIZE(confopts_tab); i++) {
+ opts = &confopts_tab[i];
+ if (!opts)
+ return NULL;
+ if (strcmp(opts->name, section) == 0) {
+ return opts;
+ }
+ }
+ return NULL;
+}
+
+enum parse_line_type {
+ PARSE_COMMENT = 0,
+ PARSE_EMPTY,
+ PARSE_SECTION,
+ PARSE_TAG_VALUE,
+ PARSE_INVALID,
+ PARSE_EOF,
+};
+
+static bool
+isempty(
+ const char *line,
+ ssize_t linelen)
+{
+ ssize_t i = 0;
+ char p;
+
+ while (i != linelen) {
+ p = line[i];
+ i++;
+
+ /* tab or space */
+ if (isblank(p))
+ continue;
+ else
+ return false;
+ }
+
+ return true;
+}
+
+static bool
+iscomment(
+ const char *line,
+ ssize_t linelen)
+{
+ ssize_t i = 0;
+ char p;
+
+ while (i != linelen) {
+ p = line[i];
+ i++;
+
+ /* tab or space */
+ if (isblank(p))
+ continue;
+
+ if (p == '#')
+ return true;
+
+ return false;
+ }
+
+ return false;
+}
+
+static int
+parse_line_section(
+ const char *line,
+ char **tag)
+{
+ return sscanf(line, " [%m[^]]]", tag);
+}
+
+static int
+parse_line_tag_value(
+ const char *line,
+ char **tag,
+ uint64_t *value)
+{
+ return sscanf(line, " %m[^ \t=]"
+ " = "
+ "%lu ",
+ tag, value);
+}
+
+static enum parse_line_type
+parse_get_line_type(
+ const char *line,
+ ssize_t linelen,
+ char **tag,
+ uint64_t *value)
+{
+ int ret;
+ uint64_t u64_value;
+
+ if (isempty(line, linelen))
+ return PARSE_EMPTY;
+
+ if (iscomment(line, linelen))
+ return PARSE_COMMENT;
+
+ ret = parse_line_section(line, tag);
+ if (ret == 1)
+ return PARSE_SECTION;
+
+ if (ret == EOF)
+ return PARSE_EOF;
+
+ ret = parse_line_tag_value(line, tag, &u64_value);
+ if (ret == 2) {
+ *value = u64_value;
+
+ return PARSE_TAG_VALUE;
+ }
+
+ if (ret == EOF)
+ return PARSE_EOF;
+
+ return PARSE_INVALID;
+}
+
+static int
+parse_config_stream(
+ struct mkfs_default_params *dft,
+ const char *config_file,
+ FILE *fp)
+{
+ int ret;
+ char *line = NULL;
+ ssize_t linelen;
+ size_t len = 0, lineno = 0;
+ uint64_t value;
+ enum parse_line_type parse_type;
+ struct confopts *confopt = NULL;
+ int subopt;
+
+ while ((linelen = getline(&line, &len, fp)) != -1) {
+ char *ignore_value;
+ char *p, *tag = NULL;
+
+ lineno++;
+
+ /*
+ * tag is allocated for us by scanf(), it must freed only on any
+ * successful parse of a section or tag-value pair.
+ */
+ parse_type = parse_get_line_type(line, linelen, &tag, &value);
+
+ switch (parse_type) {
+ case PARSE_EMPTY:
+ case PARSE_COMMENT:
+ /* Nothing tag to free for these */
+ continue;
+ case PARSE_EOF:
+ break;
+ case PARSE_INVALID:
+ ret = EINVAL;
+ fprintf(stderr, _("Invalid line %s:%zu : %s\n"),
+ config_file, lineno, line);
+ goto out;
+ case PARSE_SECTION:
+ confopt = get_confopts(tag);
+ if (!confopt) {
+ ret = EINVAL;
+ fprintf(stderr, _("Invalid section on line %s:%zu : %s\n"),
+ config_file, lineno, tag);
+ free(tag);
+ goto out;
+ }
+ if (!confopt->subopts) {
+ ret = EINVAL;
+ fprintf(stderr, _("Section not yet supported on line %s:%zu : %s\n"),
+ config_file, lineno, tag);
+ free(tag);
+ goto out;
+ }
+ if (confopt->seen) {
+ ret = EINVAL;
+ fprintf(stderr, _("Section '%s' respecified\n"),
+ tag);
+ free(tag);
+ goto out;
+ }
+ confopt->seen = true;
+ free(tag);
+ break;
+ case PARSE_TAG_VALUE:
+ if (!confopt) {
+ ret = EINVAL;
+ fprintf(stderr, _("No section specified yet on line %s:%zu : %s\n"),
+ config_file, lineno, line);
+ free(tag);
+ goto out;
+ }
+
+ /*
+ * We re-use the line buffer allocated by getline(),
+ * however line must be kept pointing to its original
+ * value to free it later. A separate pointer is needed
+ * as getsubopt() will otherwise muck with the value
+ * passed.
+ */
+ p = line;
+
+ /*
+ * Trims white spaces. getsubopt() does not grok
+ * white space, it would fail otherwise.
+ */
+ snprintf(p, len, "%s=%lu", tag, value);
+
+ /* Not needed anymore */
+ free(tag);
+
+ /*
+ * We only use getsubopt() to validate the possible
+ * subopt, we already parsed the value and its already
+ * in a more preferred data type.
+ */
+ subopt = getsubopt(&p, (char **) confopt->subopts,
+ &ignore_value);
+
+ ret = confopt->parser(dft, subopt, value);
+ if (ret) {
+ fprintf(stderr, _("Error parsine line %s:%zu : %s\n"),
+ config_file, lineno, line);
+ goto out;
+ }
+
+ break;
+ }
+ }
+out:
+ /* We must free even if getline() failed */
+ free(line);
+ return ret;
+}
+
+static const char *conf_paths[] = {
+ ".",
+ MKFS_XFS_CONF_DIR,
+};
+
+/*
+ * If the file is not found -1 is returned and errno set. Otherwise
+ * the file descriptor is returned.
+ */
+int
+open_cli_config(
+ char *cli_config_file,
+ char **fpath)
+{
+ int fd, len;
+ char *final_path = NULL;
+ char *relative_path= NULL;
+ unsigned int i;
+
+ if (strlen(cli_config_file) > 2) {
+ if (cli_config_file[0] == '.' && cli_config_file[1] == '/')
+ final_path = cli_config_file;
+ else if (cli_config_file[0] == '.' && cli_config_file[1] == '.')
+ final_path = cli_config_file;
+ else if (cli_config_file[0] == '/')
+ final_path = cli_config_file;
+ else
+ relative_path = cli_config_file;
+ } else if (strlen(cli_config_file) == 1) {
+ if (cli_config_file[0] == '.' || cli_config_file[0] == '/') {
+ errno = EINVAL;
+ return -1;
+ } else
+ relative_path = cli_config_file;
+ }
+
+ if (final_path) {
+ fd = open(final_path, O_RDONLY);
+ if (fd >= 0)
+ memcpy(*fpath, final_path, strlen(final_path));
+ return fd;
+ }
+
+ /* We finally know the path is relative but just to be sure */
+ if (!relative_path) {
+ errno = ENXIO;
+ return -1;
+ }
+
+ for (i = 0; i < ARRAY_SIZE(conf_paths); i++) {
+ memset(*fpath, 0, PATH_MAX);
+ /*
+ * For current directory evaluation, skip concatenating the
+ * ./ from the file passed. We only concatenate for the other
+ * paths we look up on.
+ */
+ if (i == 0)
+ memcpy(*fpath, relative_path, strlen(relative_path));
+ else {
+ len = snprintf(*fpath, PATH_MAX, "%s/%s", conf_paths[i],
+ relative_path);
+ /* Indicates truncation */
+ if (len >= PATH_MAX) {
+ errno = ENAMETOOLONG;
+ return -1;
+ }
+ }
+ fd = open(*fpath, O_RDONLY);
+ if (fd < 0)
+ continue;
+ return fd;
+ }
+
+ errno = ENOENT;
+ return -1;
+}
+
+/*
+ * This is only called *iff* there is a configuration file which we know we
+ * *must* parse.
+ *
+ * If default_fd is set and is a valid file descriptor then the configuration
+ * file passed is the system default configuraiton file, and we already know
+ * it exists. If default_fd is not set we assume we've been passed a
+ * configuration file from the command line and must it must exist, otherwise
+ * we have to error out.
+ */
+int
+parse_defaults_file(
+ struct mkfs_default_params *dft,
+ int default_fd,
+ char *config_file)
+{
+ char *fpath;
+ int fd;
+ FILE *fp;
+ int ret;
+ struct stat sp;
+
+ if (strlen(config_file) > PATH_MAX)
+ return ENAMETOOLONG;
+
+ fpath = malloc(PATH_MAX);
+ if (!fpath)
+ return ENOMEM;
+ memset(fpath, 0, PATH_MAX);
+
+ if (default_fd < 0) {
+ fd = open_cli_config(config_file, &fpath);
+ if (fd < 0) {
+ free(fpath);
+ return errno;
+ }
+ } else {
+ fd = default_fd;
+ memcpy(fpath, config_file, strlen(config_file));
+ }
+
+ /*
+ * At this point we know we have a valid file descriptor and have
+ * figured out the path to the file used on fpath. Get the file stream
+ * and do a bit of sanity checks before parsing the file.
+ */
+
+ fp = fdopen(fd, "r");
+ if (!fp) {
+ perror(fpath);
+ ret = errno;
+ goto out_close_fd;
+ }
+
+ ret = fstat(fd, &sp);
+ if (ret) {
+ ret = errno;
+ fprintf(stderr, _("Could not fstat() config file: %s: %s\n"),
+ fpath, strerror(errno));
+ goto out;
+ }
+
+ if (S_ISDIR(sp.st_mode)) {
+ ret = EBADF;
+ fprintf(stderr, _("Config file is a directory: %s\n"), fpath);
+ goto out;
+ }
+
+ /* Anything beyond 1 MiB is kind of silly right now */
+ if (sp.st_size > 1 * 1024 * 1024) {
+ ret = E2BIG;
+ goto out;
+ }
+
+ ret = parse_config_stream(dft, config_file, fp);
+ if (ret)
+ goto out;
+
+ printf(_("config-file=%s\n"), fpath);
+
+out:
+ fclose(fp);
+out_close_fd:
+ close(fd);
+ free(fpath);
+ return ret;
+}
diff --git a/mkfs/config.h b/mkfs/config.h
index e5ea968e2d65..0f429d9b7fd7 100644
--- a/mkfs/config.h
+++ b/mkfs/config.h
@@ -19,6 +19,8 @@
#ifndef _XFS_MKFS_CONFIG_H
#define _XFS_MKFS_CONFIG_H
+#define MKFS_XFS_CONF_DIR ROOT_SYSCONFDIR "/mkfs.xfs.d"
+
struct fsxattr;
/*
@@ -29,7 +31,7 @@ struct fsxattr;
* source can overriding the later source:
*
* o built-in defaults
- * o configuration file (XXX)
+ * o configuration file
* o command line
*
* These values are not used directly - they are inputs into the mkfs geometry
@@ -75,4 +77,10 @@ struct mkfs_default_params {
struct fsxattr fsx;
};
+int
+parse_defaults_file(
+ struct mkfs_default_params *dft,
+ int default_fd,
+ char *config_file);
+
#endif /* _XFS_MKFS_CONFIG_H */
diff --git a/mkfs/xfs_mkfs.c b/mkfs/xfs_mkfs.c
index 4664e507afbf..81ef7ab584ed 100644
--- a/mkfs/xfs_mkfs.c
+++ b/mkfs/xfs_mkfs.c
@@ -3743,6 +3743,11 @@ main(
.nortalign = false,
},
};
+ char *default_config = MKFS_XFS_CONF_DIR "/default";
+ char *cli_config_file = NULL;
+ char *config_file = NULL;
+ int default_fd = -1;
+ int ret;
platform_uuid_generate(&cli.uuid);
progname = basename(argv[0]);
@@ -3751,25 +3756,74 @@ main(
textdomain(PACKAGE);
/*
- * TODO: Sourcing defaults from a config file
- *
* Before anything else, see if there's a config file with different
- * defaults. If a file exists in <package location>, read in the new
- * default values and overwrite them in the &dft structure. This way the
- * new defaults will apply before we parse the CLI, and the CLI will
- * still be able to override them. When more than one source is
- * implemented, emit a message to indicate where the defaults being
- * used came from.
+ * defaults. If the CLI specified a full path we use and require that.
+ * If a relative path was provided on the CLI we search the allowed
+ * search paths for the file. If no config file was specified on the
+ * CLI we will look for MKFS_XFS_CONF_DIR/default and use that if
+ * present, however this file is optional.
*
- * printf(_("Default configuration sourced from %s\n"), dft.source);
+ * If a configuration file is found we use it to help overwrite default
+ * values in the &dft structure. This way the new defaults will apply
+ * before we parse the CLI, and the user will still be able to override
+ * them through the CLI.
+ */
+
+ /*
+ * Pull config line options from command line
*/
+ while ((c = getopt(argc, argv, "b:c:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
+ switch (c) {
+ case 'c':
+ if (cli_config_file) {
+ fprintf(stderr, _("respecification of configuration not allowed\n"));
+ exit(1);
+ }
+ cli_config_file = optarg;
+ dft.source = _("command line");
+ break;
+ default:
+ continue;
+ }
+ }
+
+ if (cli_config_file)
+ config_file = cli_config_file;
+ else {
+ default_fd = open(default_config, O_RDONLY);
+ if (default_fd >= 0) {
+ dft.source = _("system default configuration file");
+ config_file = default_config;
+ }
+ }
+
+ if (config_file) {
+ /* If default_fd is set it will be closed for us */
+ ret = parse_defaults_file(&dft, default_fd, config_file);
+ if (ret) {
+ fprintf(stderr, _("Error parsing %s config file: %s : %s\n"),
+ dft.source, config_file,
+ strerror(ret));
+ exit(1);
+ }
+ }
- /* copy new defaults into CLI parsing structure */
+ printf(_("Default configuration sourced from %s\n"), dft.source);
+
+ /*
+ * Done parsing defaults now, so memcpy defaults into CLI
+ * structure, reset getopt and start parsing CLI options
+ */
memcpy(&cli.sb_feat, &dft.sb_feat, sizeof(cli.sb_feat));
memcpy(&cli.fsx, &dft.fsx, sizeof(cli.fsx));
- while ((c = getopt(argc, argv, "b:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
+ platform_getoptreset();
+
+ while ((c = getopt(argc, argv, "b:c:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
switch (c) {
+ case 'c':
+ /* already validated and parsed, ignore */
+ break;
case 'C':
case 'f':
force_overwrite = 1;
--
2.16.3
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH v4 4/4] debian/rules: use the new sysconfdir configuration setting
2018-05-29 22:05 [PATCH v4 0/4] xfsprogs: add mkfs.xfs configuration file parsing support Luis R. Rodriguez
` (2 preceding siblings ...)
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
@ 2018-05-29 22:06 ` Luis R. Rodriguez
3 siblings, 0 replies; 21+ messages in thread
From: Luis R. Rodriguez @ 2018-05-29 22:06 UTC (permalink / raw)
To: sandeen, linux-xfs
Cc: darrick.wong, jack, jeffm, okurz, lpechacek, jtulak, Luis R. Rodriguez
Configuration file support requires setting --sysconfdir=/etc/ if your
distribution expects mkfs.xfs.d directory to be in /etc.
Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
---
debian/rules | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/debian/rules b/debian/rules
index cb4fa22c1584..599d7998052e 100755
--- a/debian/rules
+++ b/debian/rules
@@ -20,9 +20,9 @@ stdenv = @GZIP=-q; export GZIP;
options = export DEBUG=-DNDEBUG DISTRIBUTION=debian \
INSTALL_USER=root INSTALL_GROUP=root \
- LOCAL_CONFIGURE_OPTIONS="--enable-readline=yes --enable-blkid=yes --disable-ubsan --disable-addrsan --disable-threadsan --enable-lto" ;
+ LOCAL_CONFIGURE_OPTIONS="--enable-readline=yes --enable-blkid=yes --disable-ubsan --disable-addrsan --disable-threadsan --enable-lto --sysconfdir=/etc/" ;
diopts = $(options) \
- export OPTIMIZER=-Os LOCAL_CONFIGURE_OPTIONS="--enable-gettext=no --disable-ubsan --disable-addrsan --disable-threadsan --enable-lto" ;
+ export OPTIMIZER=-Os LOCAL_CONFIGURE_OPTIONS="--enable-gettext=no --disable-ubsan --disable-addrsan --disable-threadsan --enable-lto --sysconfdir=/etc/" ;
checkdir = test -f debian/rules
build: build-arch build-indep
--
2.16.3
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
@ 2018-05-29 23:31 ` Darrick J. Wong
2018-06-01 21:56 ` Luis R. Rodriguez
2018-05-30 2:09 ` Eric Sandeen
` (6 subsequent siblings)
7 siblings, 1 reply; 21+ messages in thread
From: Darrick J. Wong @ 2018-05-29 23:31 UTC (permalink / raw)
To: Luis R. Rodriguez
Cc: sandeen, linux-xfs, jack, jeffm, okurz, lpechacek, jtulak
On Tue, May 29, 2018 at 03:06:02PM -0700, Luis R. Rodriguez wrote:
> You may want to stick to specific set of configuration options when
> creating filesystems with mkfs.xfs -- sometimes due to pure technical
> reasons, but some other times to ensure systems remain compatible as
> new features are introduced with older kernels, or if you always want
> to take advantage of some new feature which would otherwise typically
> be disruptive.
>
> This adds support for parsing a configuration file to override defaults
> parameters to be used for mkfs.xfs.
>
> We define an XFS configuration directory, /etc/mkfs.xfs.d/ and allow for
> different configuration files, if none is specified we look for the
> default configuration file, /etc/mkfs.xfs.d/default. You can override
> with -c. For instance, if you specify:
>
> mkfs.xfs -c experimental -f /dev/loop0
>
> The search path for the configuration file will be:
>
> 1) $PWD/experimental
> 2) /etc/mkfs.xfs.d/experimental
>
> Absolute paths are supported, in which case they will be used directly
> and the mkfs.xfs.d directory is ignored.
>
> To verify what configuration file is used on a system use the typical:
>
> mkfs.xfs -N
>
> There is only a subset of options allowed to be set on the configuration
> file. The default parameters you can override on a configuration file and
> their current built-in default settings are:
>
> [data]
> noalign=0
>
> [inode]
> align=1
> projid32bit=1
> sparse=0
>
> [log]
> lazy-count=1
>
> [metadata]
> crc=1
> finobt=1
> rmapbt=0
> reflink=0
>
> [naming]
> ftype=1
>
> [rtdev]
> noalign=0
>
> Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
> ---
> configure.ac | 6 +-
> include/builddefs.in | 2 +
> man/man5/Makefile | 2 +
> man/man5/mkfs.xfs.d.5.in | 151 ++++++++
> man/man8/Makefile | 2 +
> man/man8/{mkfs.xfs.8 => mkfs.xfs.8.in} | 27 ++
> mkfs/Makefile | 2 +-
> mkfs/config.c | 645 +++++++++++++++++++++++++++++++++
> mkfs/config.h | 10 +-
> mkfs/xfs_mkfs.c | 76 +++-
> 10 files changed, 909 insertions(+), 14 deletions(-)
> create mode 100644 man/man5/mkfs.xfs.d.5.in
> rename man/man8/{mkfs.xfs.8 => mkfs.xfs.8.in} (96%)
> create mode 100644 mkfs/config.c
>
> diff --git a/configure.ac b/configure.ac
> index 508eefede073..94c5bda725f2 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -233,5 +233,9 @@ AC_CHECK_SIZEOF([char *])
> AC_TYPE_UMODE_T
> AC_MANUAL_FORMAT
>
> -AC_CONFIG_FILES([include/builddefs])
> +AC_CONFIG_FILES([
> + include/builddefs
> + man/man5/mkfs.xfs.d.5
> + man/man8/mkfs.xfs.8
> +])
> AC_OUTPUT
> diff --git a/include/builddefs.in b/include/builddefs.in
> index 8aac06cf90dc..e1ee9f7ba086 100644
> --- a/include/builddefs.in
> +++ b/include/builddefs.in
> @@ -62,6 +62,7 @@ PKG_LIB_DIR = @libdir@@libdirsuffix@
> PKG_INC_DIR = @includedir@/xfs
> DK_INC_DIR = @includedir@/disk
> PKG_MAN_DIR = @mandir@
> +PKG_ETC_DIR = @sysconfdir@
> PKG_DOC_DIR = @datadir@/doc/@pkg_name@
> PKG_LOCALE_DIR = @datadir@/locale
>
> @@ -196,6 +197,7 @@ endif
>
> GCFLAGS = $(DEBUG) \
> -DVERSION=\"$(PKG_VERSION)\" -DLOCALEDIR=\"$(PKG_LOCALE_DIR)\" \
> + -DROOT_SYSCONFDIR=\"$(PKG_ETC_DIR)\" \
> -DPACKAGE=\"$(PKG_NAME)\" -I$(TOPDIR)/include -I$(TOPDIR)/libxfs
>
> ifeq ($(ENABLE_GETTEXT),yes)
> diff --git a/man/man5/Makefile b/man/man5/Makefile
> index fe0aef6f016b..0b33122b064e 100644
> --- a/man/man5/Makefile
> +++ b/man/man5/Makefile
> @@ -19,3 +19,5 @@ install : default
> $(INSTALL) -m 755 -d $(MAN_DEST)
> $(INSTALL_MAN)
> install-dev :
> +
> +LDIRT += mkfs.xfs.d.5
> diff --git a/man/man5/mkfs.xfs.d.5.in b/man/man5/mkfs.xfs.d.5.in
> new file mode 100644
> index 000000000000..287877ce029d
> --- /dev/null
> +++ b/man/man5/mkfs.xfs.d.5.in
> @@ -0,0 +1,151 @@
> +.TH mkfs.xfs.d 5
> +.SH NAME
> +mkfs.xfs.d \- mkfs.xfs configuration directory
> +.SH DESCRIPTION
> +.B mkfs.xfs (8)
> +uses a set of initial default parameters for configuration.
> +
> +The built-in mkfs defaults are decided by the XFS community. New features are
> +only enabled by default when the community consider them stable. One can
> +override these defaults on the
> +.B mkfs.xfs (8)
> +command line, but there are cases where it is desirable for the distro or the
> +system administrator to establish their own supported defaults in a uniform
> +manner, regardless of the version of
> +.B mkfs.xfs (8)
> +used. This may be desirable for example on systems with old kernels
> +where the built-in default
> +.B mkfs.xfs (8)
> +parameters create a filesystem that is not supported by the old kernel.
> +In such situations it would also be unclear what parameters are needed to
> +produce a compatible filesystem, having a configuration file present ensures
> +that if newer versions of
> +.B mkfs.xfs (8)
> +are deployed, creating a filesystem will remain compatible. Overriding
> +.B mkfs.xfs (8)
> +built-in defaults may also be desirable if you have a series of systems with
> +different kernels and want to be able to create filesystems which all systems
> +are able to support properly.
> +.PP
> +The XFS configuration directory
> +.B mkfs.xfs.d (5)
> +can be used as a home to define different configuration files which can be used
> +to override the built-in default parameters by
> +.B mkfs.xfs (8).
> +If the
> +.B -c
> +parameter is not used, the default configuration file:
> +.IP
> +.I @sysconfdir@/mkfs.xfs.d/default
> +.PP
> +will be looked for first and if present will be used to override
> +.B mkfs.xfs (8)
> +built-in default parameters.
> +.PP
> +You can override the default configuration file by specifying its name when
> +using
> +.B mkfs.xfs (8)
> +by using the
> +.B -c
> +parameter.
> +.PP
> +If the path does not start with a '.', the current working directory is
> +searched for the file. If the file is not found there, the
> +.B mkfs.xfs.d (5)
> +directory is searched for the file.
> +.PP
> +If
> +.B -c
> +is used with relative path with which has a leading '.' character, the given
> +path is used directly, so the configuration file will be relative to the
> +current working directory.
> +.PP
> +If the
> +.B -c
> +argument starts with a '/', it is considered an absolute path, and opened.
> +.PP
> +For example:
> +.IP
> +.B mkfs.xfs -c experimental -f /dev/sda1
> +.PP
> +Will make
> +.B mkfs.xfs (8)
> +look for the following configuration files and use the first one it finds:
> +.IP
> +.B $PWD/experimental
> +.br
> +.B @sysconfdir@/mkfs.xfs.d/experimental
> +.PP
> +If you used an absolute path, for example:
> +.IP
> +.B mkfs.xfs -c /tmp/experimental -f /dev/sda1
> +.PP
> +Then only the configuration file /tmp/experimental will be looked for and
> +used if present.
> +.PP
> +If you use the
> +.B -c
> +parameter the configuration file must be present and must parse correctly.
> +.PP
> +Parameters passed to the
> +.B mkfs.xfs (8)
> +command line always override any defaults set by the configuration file.
> +.PP
> +.B mkfs.xfs (8)
> +will always describe what configuration file was used, if any
> +was used at all. To verify which configuration file would be used prior to
> +execution of
> +.B mkfs.xfs (8)
> +you can use
> +.I mkfs.xfs -N.
> +.PP
> +.SH DEFAULT PARAMETERS
> +Default parameters for
> +.B mkfs.xfs (8)
> +consists of a small subset of the parameters one can set with on the command
> +line. Currently all default parameters can only be either enabled or disabled,
> +you can set their value to 1 to enable or 0 to disable. Below we list the
> +different supported default parameters which can be defined on configuration
> +files, along with the current built-in setting.
> +.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 mkfs.xfs (8),
> +.BR xfsctl (3),
> +.BR xfs_info (8),
> +.BR xfs_admin (8),
> +.BR xfsdump (8),
> +.BR xfsrestore (8).
> diff --git a/man/man8/Makefile b/man/man8/Makefile
> index 36620da172ae..2a6548079997 100644
> --- a/man/man8/Makefile
> +++ b/man/man8/Makefile
> @@ -19,3 +19,5 @@ install : default
> $(INSTALL) -m 755 -d $(MAN_DEST)
> $(INSTALL_MAN)
> install-dev :
> +
> +LDIRT += mkfs.xfs.8
> diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8.in
> similarity index 96%
> rename from man/man8/mkfs.xfs.8
> rename to man/man8/mkfs.xfs.8.in
> index 4b8c78c37806..81e2753bd2b5 100644
> --- a/man/man8/mkfs.xfs.8
> +++ b/man/man8/mkfs.xfs.8.in
> @@ -83,6 +83,24 @@ and
> .B \-l internal \-l size=10m
> are equivalent.
> .PP
> +An optional XFS configuration file directory
> +.B mkfs.xfs.d (5)
> +exists to help fine tune different default parameters which can be used when
> +calling
> +.B mkfs.xfs (8).
> +If present, and if
> +.B -c
> +is not used, the default configuration file @sysconfigdir@/mkfs.xfs.d/default
> +will be used to override system build-in defaults. Refer to mkfs.xfs.d (5)
> +for a list of current defaults and further details.
> +Command line arguments directly passed to
> +.B mkfs.xfs (8)
> +will always override parameters set in the configuration file.
> +You can override the configuration file used by using the
> +.B -c
> +parameter, further explained below and in
> +.B mkfs.xfs.d (5)
> +.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,
> @@ -123,6 +141,14 @@ Many feature options allow an optional argument of 0 or 1, to explicitly
> disable or enable the functionality.
> .SH OPTIONS
> .TP
> +.BI \-c " configuration-file"
> +Override the configuration file used. If a relative path is given the search
> +path for the configuration file is your current directory and then the
> +.B mkfs.xfs.d (5)
> +directory. If an absolute path is given it is used directly. For more details
> +refer to
> +.B mkfs.xfs.d (5)
> +.TP
> .BI \-b " block_size_options"
> This option specifies the fundamental block size of the filesystem.
> The valid
> @@ -923,6 +949,7 @@ Prints the version number and exits.
> .SH SEE ALSO
> .BR xfs (5),
> .BR mkfs (8),
> +.BR mkfs.xfs.d (5),
> .BR mount (8),
> .BR xfs_info (8),
> .BR xfs_admin (8).
> diff --git a/mkfs/Makefile b/mkfs/Makefile
> index c84f9b6ae63b..c7815b3e106b 100644
> --- a/mkfs/Makefile
> +++ b/mkfs/Makefile
> @@ -8,7 +8,7 @@ include $(TOPDIR)/include/builddefs
> LTCOMMAND = mkfs.xfs
>
> HFILES =
> -CFILES = proto.c xfs_mkfs.c
> +CFILES = proto.c xfs_mkfs.c config.c
>
> LLDLIBS += $(LIBXFS) $(LIBXCMD) $(LIBFROG) $(LIBRT) $(LIBPTHREAD) $(LIBBLKID) \
> $(LIBUUID)
> diff --git a/mkfs/config.c b/mkfs/config.c
> new file mode 100644
> index 000000000000..0b4aebe51903
> --- /dev/null
> +++ b/mkfs/config.c
> @@ -0,0 +1,645 @@
> +/*
> + * Copyright (c) 2018 Luis R. Rodriguez <mcgrof@kernel.org>
> + *
> + * This program is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU General Public License
> + * as published by the Free Software Foundation; either version 2
> + * of the License, or (at your option) any later version.
> + *
> + * This program is distributed in the hope that it would be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> + * GNU General Public License for more details.
> + *
> + * You should have received a copy of the GNU General Public License
> + * along with this program; if not, write the Free Software Foundation,
> + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
> + */
> +
> +#include <ctype.h>
> +#include <dirent.h>
> +#include <fcntl.h>
> +
> +#include "libxfs.h"
> +#include "config.h"
> +
> +/*
> + * Enums for each configuration option. All these currently match the CLI
> + * parameters for now but this may change later, so we keep all this code
> + * and definitions separate. The rules for configuration parameters may also
> + * differ.
> + *
> + * We only provide definitions for what we currently support parsing.
> + */
> +
> +enum data_subopts {
> + D_NOALIGN = 0,
> +};
> +
> +enum inode_subopts {
> + I_ALIGN = 0,
> + I_PROJID32BIT,
> + I_SPINODES,
> +};
> +
> +enum log_subopts {
> + L_LAZYSBCNTR = 0,
> +};
> +
> +enum metadata_subopts {
> + M_CRC = 0,
> + M_FINOBT,
> + M_RMAPBT,
> + M_REFLINK,
> +};
> +
> +enum naming_subopts {
> + N_FTYPE = 0,
> +};
> +
> +enum rtdev_subopts {
> + R_NOALIGN = 0,
> +};
> +
> +/* Just define the max options array size manually right now */
> +#define MAX_SUBOPTS 4
> +
> +static int
> +data_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum data_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case D_NOALIGN:
> + dft->sb_feat.nodalign = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +static int
> +inode_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum inode_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case I_ALIGN:
> + dft->sb_feat.inode_align = value;
> + return 0;
> + case I_PROJID32BIT:
> + dft->sb_feat.projid32bit = value;
> + return 0;
> + case I_SPINODES:
> + dft->sb_feat.spinodes = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +static int
> +log_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum log_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case L_LAZYSBCNTR:
> + dft->sb_feat.lazy_sb_counters = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +static int
> +metadata_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum metadata_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case M_CRC:
> + dft->sb_feat.crcs_enabled = value;
> + if (dft->sb_feat.crcs_enabled)
> + dft->sb_feat.dirftype = true;
> + return 0;
> + case M_FINOBT:
> + dft->sb_feat.finobt = value;
> + return 0;
> + case M_RMAPBT:
> + dft->sb_feat.rmapbt = value;
> + return 0;
> + case M_REFLINK:
> + dft->sb_feat.reflink = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +static int
> +naming_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum naming_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case N_FTYPE:
> + dft->sb_feat.dirftype = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +static int
> +rtdev_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum rtdev_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case R_NOALIGN:
> + dft->sb_feat.nortalign = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +struct confopts {
> + const char *name;
> + const char *subopts[MAX_SUBOPTS];
> + int (*parser)(struct mkfs_default_params *dft,
> + int psubopt, uint64_t value);
> + bool seen;
> +} confopts_tab[] = {
> + {
> + .name = "data",
> + .subopts = {
> + [D_NOALIGN] = "noalign",
> + },
> + .parser = data_config_parser,
> + },
> + {
> + .name = "inode",
> + .subopts = {
> + [I_ALIGN] = "align",
> + [I_PROJID32BIT] = "projid32bit",
> + [I_SPINODES] = "sparse",
> + },
> + .parser = inode_config_parser,
> + },
> + {
> + .name = "log",
> + .subopts = {
> + [L_LAZYSBCNTR] = "lazy-count",
> + },
> + .parser = log_config_parser,
> + },
> + {
> + .name = "naming",
> + .subopts = {
> + [N_FTYPE] = "ftype",
> + },
> + .parser = naming_config_parser,
> + },
> + {
> + .name = "rtdev",
> + .subopts = {
> + [R_NOALIGN] = "noalign",
> + },
> + .parser = rtdev_config_parser,
> + },
> + {
> + .name = "metadata",
> + .subopts = {
> + [M_CRC] = "crc",
> + [M_FINOBT] = "finobt",
> + [M_RMAPBT] = "rmapbt",
> + [M_REFLINK] = "reflink",
> + },
> + .parser = metadata_config_parser,
> + },
> +};
> +
> +static struct confopts *
> +get_confopts(
> + const char *section)
> +{
> + unsigned int i;
> + struct confopts *opts;
> +
> + for (i=0; i < ARRAY_SIZE(confopts_tab); i++) {
> + opts = &confopts_tab[i];
> + if (!opts)
> + return NULL;
> + if (strcmp(opts->name, section) == 0) {
> + return opts;
> + }
> + }
> + return NULL;
> +}
> +
> +enum parse_line_type {
> + PARSE_COMMENT = 0,
> + PARSE_EMPTY,
> + PARSE_SECTION,
> + PARSE_TAG_VALUE,
> + PARSE_INVALID,
> + PARSE_EOF,
> +};
> +
> +static bool
> +isempty(
> + const char *line,
> + ssize_t linelen)
> +{
> + ssize_t i = 0;
> + char p;
> +
> + while (i != linelen) {
> + p = line[i];
> + i++;
> +
> + /* tab or space */
> + if (isblank(p))
> + continue;
> + else
> + return false;
> + }
> +
> + return true;
> +}
> +
> +static bool
> +iscomment(
> + const char *line,
> + ssize_t linelen)
> +{
> + ssize_t i = 0;
> + char p;
> +
> + while (i != linelen) {
> + p = line[i];
> + i++;
> +
> + /* tab or space */
> + if (isblank(p))
> + continue;
> +
> + if (p == '#')
> + return true;
> +
> + return false;
> + }
> +
> + return false;
> +}
> +
> +static int
> +parse_line_section(
> + const char *line,
> + char **tag)
> +{
> + return sscanf(line, " [%m[^]]]", tag);
> +}
> +
> +static int
> +parse_line_tag_value(
> + const char *line,
> + char **tag,
> + uint64_t *value)
> +{
> + return sscanf(line, " %m[^ \t=]"
> + " = "
> + "%lu ",
> + tag, value);
> +}
> +
> +static enum parse_line_type
> +parse_get_line_type(
> + const char *line,
> + ssize_t linelen,
> + char **tag,
> + uint64_t *value)
> +{
> + int ret;
> + uint64_t u64_value;
> +
> + if (isempty(line, linelen))
> + return PARSE_EMPTY;
> +
> + if (iscomment(line, linelen))
> + return PARSE_COMMENT;
> +
> + ret = parse_line_section(line, tag);
> + if (ret == 1)
> + return PARSE_SECTION;
> +
> + if (ret == EOF)
> + return PARSE_EOF;
> +
> + ret = parse_line_tag_value(line, tag, &u64_value);
> + if (ret == 2) {
> + *value = u64_value;
> +
> + return PARSE_TAG_VALUE;
> + }
> +
> + if (ret == EOF)
> + return PARSE_EOF;
> +
> + return PARSE_INVALID;
> +}
> +
> +static int
> +parse_config_stream(
> + struct mkfs_default_params *dft,
> + const char *config_file,
> + FILE *fp)
> +{
> + int ret;
> + char *line = NULL;
> + ssize_t linelen;
> + size_t len = 0, lineno = 0;
> + uint64_t value;
> + enum parse_line_type parse_type;
> + struct confopts *confopt = NULL;
> + int subopt;
> +
> + while ((linelen = getline(&line, &len, fp)) != -1) {
> + char *ignore_value;
> + char *p, *tag = NULL;
> +
> + lineno++;
> +
> + /*
> + * tag is allocated for us by scanf(), it must freed only on any
> + * successful parse of a section or tag-value pair.
> + */
> + parse_type = parse_get_line_type(line, linelen, &tag, &value);
> +
> + switch (parse_type) {
> + case PARSE_EMPTY:
> + case PARSE_COMMENT:
> + /* Nothing tag to free for these */
> + continue;
> + case PARSE_EOF:
> + break;
> + case PARSE_INVALID:
> + ret = EINVAL;
> + fprintf(stderr, _("Invalid line %s:%zu : %s\n"),
> + config_file, lineno, line);
> + goto out;
> + case PARSE_SECTION:
> + confopt = get_confopts(tag);
> + if (!confopt) {
> + ret = EINVAL;
> + fprintf(stderr, _("Invalid section on line %s:%zu : %s\n"),
> + config_file, lineno, tag);
> + free(tag);
> + goto out;
> + }
> + if (!confopt->subopts) {
> + ret = EINVAL;
> + fprintf(stderr, _("Section not yet supported on line %s:%zu : %s\n"),
> + config_file, lineno, tag);
> + free(tag);
> + goto out;
> + }
> + if (confopt->seen) {
> + ret = EINVAL;
> + fprintf(stderr, _("Section '%s' respecified\n"),
> + tag);
> + free(tag);
> + goto out;
> + }
> + confopt->seen = true;
> + free(tag);
> + break;
> + case PARSE_TAG_VALUE:
> + if (!confopt) {
> + ret = EINVAL;
> + fprintf(stderr, _("No section specified yet on line %s:%zu : %s\n"),
> + config_file, lineno, line);
> + free(tag);
> + goto out;
> + }
> +
> + /*
> + * We re-use the line buffer allocated by getline(),
> + * however line must be kept pointing to its original
> + * value to free it later. A separate pointer is needed
> + * as getsubopt() will otherwise muck with the value
> + * passed.
> + */
> + p = line;
> +
> + /*
> + * Trims white spaces. getsubopt() does not grok
> + * white space, it would fail otherwise.
> + */
> + snprintf(p, len, "%s=%lu", tag, value);
> +
> + /* Not needed anymore */
> + free(tag);
> +
> + /*
> + * We only use getsubopt() to validate the possible
> + * subopt, we already parsed the value and its already
> + * in a more preferred data type.
> + */
> + subopt = getsubopt(&p, (char **) confopt->subopts,
> + &ignore_value);
> +
> + ret = confopt->parser(dft, subopt, value);
> + if (ret) {
> + fprintf(stderr, _("Error parsine line %s:%zu : %s\n"),
> + config_file, lineno, line);
> + goto out;
> + }
> +
> + break;
> + }
> + }
> +out:
> + /* We must free even if getline() failed */
> + free(line);
> + return ret;
> +}
> +
> +static const char *conf_paths[] = {
> + ".",
> + MKFS_XFS_CONF_DIR,
> +};
> +
> +/*
> + * If the file is not found -1 is returned and errno set. Otherwise
> + * the file descriptor is returned.
> + */
> +int
> +open_cli_config(
> + char *cli_config_file,
> + char **fpath)
> +{
> + int fd, len;
> + char *final_path = NULL;
> + char *relative_path= NULL;
> + unsigned int i;
> +
> + if (strlen(cli_config_file) > 2) {
> + if (cli_config_file[0] == '.' && cli_config_file[1] == '/')
> + final_path = cli_config_file;
> + else if (cli_config_file[0] == '.' && cli_config_file[1] == '.')
> + final_path = cli_config_file;
> + else if (cli_config_file[0] == '/')
> + final_path = cli_config_file;
> + else
> + relative_path = cli_config_file;
> + } else if (strlen(cli_config_file) == 1) {
> + if (cli_config_file[0] == '.' || cli_config_file[0] == '/') {
> + errno = EINVAL;
> + return -1;
> + } else
> + relative_path = cli_config_file;
> + }
> +
> + if (final_path) {
> + fd = open(final_path, O_RDONLY);
> + if (fd >= 0)
> + memcpy(*fpath, final_path, strlen(final_path));
> + return fd;
> + }
> +
> + /* We finally know the path is relative but just to be sure */
> + if (!relative_path) {
> + errno = ENXIO;
> + return -1;
> + }
> +
> + for (i = 0; i < ARRAY_SIZE(conf_paths); i++) {
> + memset(*fpath, 0, PATH_MAX);
> + /*
> + * For current directory evaluation, skip concatenating the
> + * ./ from the file passed. We only concatenate for the other
> + * paths we look up on.
> + */
> + if (i == 0)
> + memcpy(*fpath, relative_path, strlen(relative_path));
> + else {
> + len = snprintf(*fpath, PATH_MAX, "%s/%s", conf_paths[i],
> + relative_path);
> + /* Indicates truncation */
> + if (len >= PATH_MAX) {
> + errno = ENAMETOOLONG;
> + return -1;
> + }
> + }
> + fd = open(*fpath, O_RDONLY);
> + if (fd < 0)
> + continue;
> + return fd;
> + }
> +
> + errno = ENOENT;
> + return -1;
> +}
> +
> +/*
> + * This is only called *iff* there is a configuration file which we know we
> + * *must* parse.
> + *
> + * If default_fd is set and is a valid file descriptor then the configuration
> + * file passed is the system default configuraiton file, and we already know
> + * it exists. If default_fd is not set we assume we've been passed a
> + * configuration file from the command line and must it must exist, otherwise
> + * we have to error out.
> + */
> +int
> +parse_defaults_file(
> + struct mkfs_default_params *dft,
> + int default_fd,
> + char *config_file)
> +{
> + char *fpath;
> + int fd;
> + FILE *fp;
> + int ret;
> + struct stat sp;
> +
> + if (strlen(config_file) > PATH_MAX)
> + return ENAMETOOLONG;
> +
> + fpath = malloc(PATH_MAX);
> + if (!fpath)
> + return ENOMEM;
> + memset(fpath, 0, PATH_MAX);
> +
> + if (default_fd < 0) {
> + fd = open_cli_config(config_file, &fpath);
> + if (fd < 0) {
> + free(fpath);
> + return errno;
> + }
> + } else {
> + fd = default_fd;
> + memcpy(fpath, config_file, strlen(config_file));
> + }
> +
> + /*
> + * At this point we know we have a valid file descriptor and have
> + * figured out the path to the file used on fpath. Get the file stream
> + * and do a bit of sanity checks before parsing the file.
> + */
> +
> + fp = fdopen(fd, "r");
> + if (!fp) {
> + perror(fpath);
It occurred to me just now (sorry...) that the caller of this function
prints out a string with strerror() contents, so the perror here is
unnecessary since the caller will cough up an error anyway. Then all of
these constructions here become:
fp = fdopen(...);
if (!fp)
return -1;
ret = fstat(...);
if (ret)
goto out;
if (S_ISDIR(...)) {
errno = EISDIR;
goto out;
}
...
return 0;
out:
return -1;
and the call site now becomes:
if (parse_defaults_file(...)) {
fprintf(stderr, "%s: file is bad: %s\n", path, strerror(errno));
...
}
Granted maybe we should just merge this and do all those cleanups
separately.
> + ret = errno;
> + goto out_close_fd;
> + }
> +
> + ret = fstat(fd, &sp);
> + if (ret) {
> + ret = errno;
> + fprintf(stderr, _("Could not fstat() config file: %s: %s\n"),
> + fpath, strerror(errno));
> + goto out;
> + }
> +
> + if (S_ISDIR(sp.st_mode)) {
> + ret = EBADF;
ret = EISDIR?
> + fprintf(stderr, _("Config file is a directory: %s\n"), fpath);
> + goto out;
> + }
> +
> + /* Anything beyond 1 MiB is kind of silly right now */
> + if (sp.st_size > 1 * 1024 * 1024) {
> + ret = E2BIG;
> + goto out;
> + }
> +
> + ret = parse_config_stream(dft, config_file, fp);
> + if (ret)
> + goto out;
> +
> + printf(_("config-file=%s\n"), fpath);
> +
> +out:
> + fclose(fp);
> +out_close_fd:
> + close(fd);
> + free(fpath);
> + return ret;
> +}
> diff --git a/mkfs/config.h b/mkfs/config.h
> index e5ea968e2d65..0f429d9b7fd7 100644
> --- a/mkfs/config.h
> +++ b/mkfs/config.h
> @@ -19,6 +19,8 @@
> #ifndef _XFS_MKFS_CONFIG_H
> #define _XFS_MKFS_CONFIG_H
>
> +#define MKFS_XFS_CONF_DIR ROOT_SYSCONFDIR "/mkfs.xfs.d"
> +
> struct fsxattr;
>
> /*
> @@ -29,7 +31,7 @@ struct fsxattr;
> * source can overriding the later source:
> *
> * o built-in defaults
> - * o configuration file (XXX)
> + * o configuration file
> * o command line
> *
> * These values are not used directly - they are inputs into the mkfs geometry
> @@ -75,4 +77,10 @@ struct mkfs_default_params {
> struct fsxattr fsx;
> };
>
> +int
> +parse_defaults_file(
> + struct mkfs_default_params *dft,
> + int default_fd,
> + char *config_file);
> +
> #endif /* _XFS_MKFS_CONFIG_H */
> diff --git a/mkfs/xfs_mkfs.c b/mkfs/xfs_mkfs.c
> index 4664e507afbf..81ef7ab584ed 100644
> --- a/mkfs/xfs_mkfs.c
> +++ b/mkfs/xfs_mkfs.c
> @@ -3743,6 +3743,11 @@ main(
> .nortalign = false,
> },
> };
> + char *default_config = MKFS_XFS_CONF_DIR "/default";
> + char *cli_config_file = NULL;
> + char *config_file = NULL;
> + int default_fd = -1;
> + int ret;
>
> platform_uuid_generate(&cli.uuid);
> progname = basename(argv[0]);
> @@ -3751,25 +3756,74 @@ main(
> textdomain(PACKAGE);
>
> /*
> - * TODO: Sourcing defaults from a config file
> - *
> * Before anything else, see if there's a config file with different
> - * defaults. If a file exists in <package location>, read in the new
> - * default values and overwrite them in the &dft structure. This way the
> - * new defaults will apply before we parse the CLI, and the CLI will
> - * still be able to override them. When more than one source is
> - * implemented, emit a message to indicate where the defaults being
> - * used came from.
> + * defaults. If the CLI specified a full path we use and require that.
> + * If a relative path was provided on the CLI we search the allowed
> + * search paths for the file. If no config file was specified on the
> + * CLI we will look for MKFS_XFS_CONF_DIR/default and use that if
> + * present, however this file is optional.
> *
> - * printf(_("Default configuration sourced from %s\n"), dft.source);
> + * If a configuration file is found we use it to help overwrite default
> + * values in the &dft structure. This way the new defaults will apply
> + * before we parse the CLI, and the user will still be able to override
> + * them through the CLI.
> + */
> +
> + /*
> + * Pull config line options from command line
> */
> + while ((c = getopt(argc, argv, "b:c:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
> + switch (c) {
> + case 'c':
> + if (cli_config_file) {
> + fprintf(stderr, _("respecification of configuration not allowed\n"));
> + exit(1);
> + }
> + cli_config_file = optarg;
> + dft.source = _("command line");
> + break;
> + default:
> + continue;
> + }
> + }
> +
> + if (cli_config_file)
> + config_file = cli_config_file;
> + else {
> + default_fd = open(default_config, O_RDONLY);
> + if (default_fd >= 0) {
> + dft.source = _("system default configuration file");
> + config_file = default_config;
> + }
> + }
> +
> + if (config_file) {
> + /* If default_fd is set it will be closed for us */
> + ret = parse_defaults_file(&dft, default_fd, config_file);
> + if (ret) {
> + fprintf(stderr, _("Error parsing %s config file: %s : %s\n"),
> + dft.source, config_file,
> + strerror(ret));
> + exit(1);
> + }
> + }
>
> - /* copy new defaults into CLI parsing structure */
> + printf(_("Default configuration sourced from %s\n"), dft.source);
> +
> + /*
> + * Done parsing defaults now, so memcpy defaults into CLI
> + * structure, reset getopt and start parsing CLI options
> + */
> memcpy(&cli.sb_feat, &dft.sb_feat, sizeof(cli.sb_feat));
> memcpy(&cli.fsx, &dft.fsx, sizeof(cli.fsx));
>
> - while ((c = getopt(argc, argv, "b:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
> + platform_getoptreset();
> +
> + while ((c = getopt(argc, argv, "b:c:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
> switch (c) {
> + case 'c':
> + /* already validated and parsed, ignore */
> + break;
> case 'C':
> case 'f':
> force_overwrite = 1;
> --
> 2.16.3
>
> --
> 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
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v4 2/4] mkfs: move shared config structs and into their own headers
2018-05-29 22:06 ` [PATCH v4 2/4] mkfs: move shared config structs and into their own headers Luis R. Rodriguez
@ 2018-05-30 1:28 ` Dave Chinner
0 siblings, 0 replies; 21+ messages in thread
From: Dave Chinner @ 2018-05-30 1:28 UTC (permalink / raw)
To: Luis R. Rodriguez
Cc: sandeen, linux-xfs, darrick.wong, jack, jeffm, okurz, lpechacek, jtulak
On Tue, May 29, 2018 at 03:06:01PM -0700, Luis R. Rodriguez wrote:
> Both struct sb_feat_args and struct mkfs_default_params will be shared
> between CLI processing and the configuration file processing added later,
> so move these to their own header.
>
> This will help ensure we split things neatly later and also will help
> ensure the configuration file processing code from the CLI code are kept
> separate and cannot touch each other's data structures. This also makes
> it clear what is actually shared between both.
>
> There are no introduced functional changes in this commit and no
> documentation changes, this is just code shuffling.
>
> Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>
> Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
looks good.
Reviewed-by: Dave Chinner <dchinner@redhat.com>
--
Dave Chinner
david@fromorbit.com
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
2018-05-29 23:31 ` Darrick J. Wong
@ 2018-05-30 2:09 ` Eric Sandeen
2018-05-30 3:33 ` Eric Sandeen
` (5 subsequent siblings)
7 siblings, 0 replies; 21+ messages in thread
From: Eric Sandeen @ 2018-05-30 2:09 UTC (permalink / raw)
To: Luis R. Rodriguez, linux-xfs
Cc: darrick.wong, jack, jeffm, okurz, lpechacek, jtulak
On 5/29/18 5:06 PM, Luis R. Rodriguez wrote:
> +/*
> + * If the file is not found -1 is returned and errno set. Otherwise
> + * the file descriptor is returned.
> + */
> +int
> +open_cli_config(
> + char *cli_config_file,
> + char **fpath)
> +{
> + int fd, len;
> + char *final_path = NULL;
> + char *relative_path= NULL;
> + unsigned int i;
> +
> + if (strlen(cli_config_file) > 2) {
> + if (cli_config_file[0] == '.' && cli_config_file[1] == '/')
> + final_path = cli_config_file;
> + else if (cli_config_file[0] == '.' && cli_config_file[1] == '.')
> + final_path = cli_config_file;
> + else if (cli_config_file[0] == '/')
> + final_path = cli_config_file;
> + else
> + relative_path = cli_config_file;
> + } else if (strlen(cli_config_file) == 1) {
> + if (cli_config_file[0] == '.' || cli_config_file[0] == '/') {
> + errno = EINVAL;
> + return -1;
> + } else
> + relative_path = cli_config_file;
> + }
so you have 2 cases, strlen > 2 and strlen == 1. What about == 2?
# ls /a
/a
# mkfs/mkfs.xfs -c /a /dev/sdb1
Error parsing command line config file: /a : No such device or address
so that looks like a bug here.
-Eric
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
2018-05-29 23:31 ` Darrick J. Wong
2018-05-30 2:09 ` Eric Sandeen
@ 2018-05-30 3:33 ` Eric Sandeen
2018-05-30 3:33 ` Dave Chinner
` (4 subsequent siblings)
7 siblings, 0 replies; 21+ messages in thread
From: Eric Sandeen @ 2018-05-30 3:33 UTC (permalink / raw)
To: Luis R. Rodriguez, linux-xfs
Cc: darrick.wong, jack, jeffm, okurz, lpechacek, jtulak
On 5/29/18 5:06 PM, Luis R. Rodriguez wrote:
> You may want to stick to specific set of configuration options when
> creating filesystems with mkfs.xfs -- sometimes due to pure technical
> reasons, but some other times to ensure systems remain compatible as
> new features are introduced with older kernels, or if you always want
> to take advantage of some new feature which would otherwise typically
> be disruptive.
>
> This adds support for parsing a configuration file to override defaults
> parameters to be used for mkfs.xfs.
>
> We define an XFS configuration directory, /etc/mkfs.xfs.d/ and allow for
> different configuration files, if none is specified we look for the
> default configuration file, /etc/mkfs.xfs.d/default. You can override
> with -c. For instance, if you specify:
>
> mkfs.xfs -c experimental -f /dev/loop0
>
> The search path for the configuration file will be:
>
> 1) $PWD/experimental
> 2) /etc/mkfs.xfs.d/experimental
by default this still lands in /usr/etc/mkfs.xfs.d - is there a way to
default to /etc ? (see below)
> Absolute paths are supported, in which case they will be used directly
> and the mkfs.xfs.d directory is ignored.
>
> To verify what configuration file is used on a system use the typical:
>
> mkfs.xfs -N
>
> There is only a subset of options allowed to be set on the configuration
> file. The default parameters you can override on a configuration file and
> their current built-in default settings are:
>
> [data]
> noalign=0
>
> [inode]
> align=1
> projid32bit=1
> sparse=0
>
> [log]
> lazy-count=1
>
> [metadata]
> crc=1
> finobt=1
> rmapbt=0
> reflink=0
>
> [naming]
> ftype=1
>
> [rtdev]
> noalign=0
>
> Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
> ---
> configure.ac | 6 +-
> include/builddefs.in | 2 +
> man/man5/Makefile | 2 +
> man/man5/mkfs.xfs.d.5.in | 151 ++++++++
> man/man8/Makefile | 2 +
> man/man8/{mkfs.xfs.8 => mkfs.xfs.8.in} | 27 ++
> mkfs/Makefile | 2 +-
> mkfs/config.c | 645 +++++++++++++++++++++++++++++++++
> mkfs/config.h | 10 +-
> mkfs/xfs_mkfs.c | 76 +++-
> 10 files changed, 909 insertions(+), 14 deletions(-)
> create mode 100644 man/man5/mkfs.xfs.d.5.in
> rename man/man8/{mkfs.xfs.8 => mkfs.xfs.8.in} (96%)
> create mode 100644 mkfs/config.c
>
> diff --git a/configure.ac b/configure.ac
> index 508eefede073..94c5bda725f2 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -233,5 +233,9 @@ AC_CHECK_SIZEOF([char *])
> AC_TYPE_UMODE_T
> AC_MANUAL_FORMAT
>
> -AC_CONFIG_FILES([include/builddefs])
> +AC_CONFIG_FILES([
> + include/builddefs
> + man/man5/mkfs.xfs.d.5
> + man/man8/mkfs.xfs.8
> +])
> AC_OUTPUT
> diff --git a/include/builddefs.in b/include/builddefs.in
> index 8aac06cf90dc..e1ee9f7ba086 100644
> --- a/include/builddefs.in
> +++ b/include/builddefs.in
> @@ -62,6 +62,7 @@ PKG_LIB_DIR = @libdir@@libdirsuffix@
> PKG_INC_DIR = @includedir@/xfs
> DK_INC_DIR = @includedir@/disk
> PKG_MAN_DIR = @mandir@
> +PKG_ETC_DIR = @sysconfdir@
can configure scripts somehow default this to /etc ? I think this works:
diff --git a/configure.ac b/configure.ac
index 94c5bda..8f6c793 100644
--- a/configure.ac
+++ b/configure.ac
@@ -6,6 +6,8 @@ AC_CONFIG_SRCDIR([include/libxfs.h])
AC_CONFIG_HEADER(include/platform_defs.h)
AC_PREFIX_DEFAULT(/usr)
+test "$sysconfdir" = '${prefix}/etc' && sysconfdir=/etc
+
AC_PROG_INSTALL
AC_PROG_LIBTOOL
> PKG_DOC_DIR = @datadir@/doc/@pkg_name@
> PKG_LOCALE_DIR = @datadir@/locale
>
> @@ -196,6 +197,7 @@ endif
>
> GCFLAGS = $(DEBUG) \
> -DVERSION=\"$(PKG_VERSION)\" -DLOCALEDIR=\"$(PKG_LOCALE_DIR)\" \
> + -DROOT_SYSCONFDIR=\"$(PKG_ETC_DIR)\" \
> -DPACKAGE=\"$(PKG_NAME)\" -I$(TOPDIR)/include -I$(TOPDIR)/libxfs
>
> ifeq ($(ENABLE_GETTEXT),yes)
> diff --git a/man/man5/Makefile b/man/man5/Makefile
> index fe0aef6f016b..0b33122b064e 100644
> --- a/man/man5/Makefile
> +++ b/man/man5/Makefile
> @@ -19,3 +19,5 @@ install : default
> $(INSTALL) -m 755 -d $(MAN_DEST)
> $(INSTALL_MAN)
> install-dev :
> +
> +LDIRT += mkfs.xfs.d.5
> diff --git a/man/man5/mkfs.xfs.d.5.in b/man/man5/mkfs.xfs.d.5.in
> new file mode 100644
> index 000000000000..287877ce029d
> --- /dev/null
> +++ b/man/man5/mkfs.xfs.d.5.in
> @@ -0,0 +1,151 @@
> +.TH mkfs.xfs.d 5
> +.SH NAME
> +mkfs.xfs.d \- mkfs.xfs configuration directory
> +.SH DESCRIPTION
> +.B mkfs.xfs (8)
.BR mkfs.xfs (8)
so that it alternates bold/regular, similar fix for all instances below.
> +uses a set of initial default parameters for configuration.
> +
> +The built-in mkfs defaults are decided by the XFS community. New features are
> +only enabled by default when the community consider them stable. One can
> +override these defaults on the
> +.B mkfs.xfs (8)
> +command line, but there are cases where it is desirable for the distro or the
colloquial, "distribution" please
(actually I'd like to edit this a lot still - maybe just leave it as is and
I'll take a crack at it)
...
> +look for the following configuration files and use the first one it finds:
> +.IP
> +.B $PWD/experimental
> +.br
> +.B @sysconfdir@/mkfs.xfs.d/experimental
> +.PP
This gets replaced as:
${prefix}/etc/mkfs.xfs.d/experimental
which is probably not as intended. (though I think maybe my configure.ac
patch above makes that go away ...)
Anyway, I really still don't like this "look for the file in pwd by default"
thing. I get it that a bare filename is technically a relative path, but
I still think this will lead to surprise, confusion, and sadness when a
similar filename just happens to exist in the hapless admin's $PWD. I may
need to arm-wrestle dave over this.
> diff --git a/man/man8/Makefile b/man/man8/Makefile
> index 36620da172ae..2a6548079997 100644
> --- a/man/man8/Makefile
> +++ b/man/man8/Makefile
> @@ -19,3 +19,5 @@ install : default
> $(INSTALL) -m 755 -d $(MAN_DEST)
> $(INSTALL_MAN)
> install-dev :
> +
> +LDIRT += mkfs.xfs.8
> diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8.in
> similarity index 96%
> rename from man/man8/mkfs.xfs.8
> rename to man/man8/mkfs.xfs.8.in
> index 4b8c78c37806..81e2753bd2b5 100644
> --- a/man/man8/mkfs.xfs.8
> +++ b/man/man8/mkfs.xfs.8.in
-c should be added to the synopsis, yes?
The first mention of -c in this manpage is:
"If present, and if -c is not used" which is a very odd introduction. ;)
> @@ -83,6 +83,24 @@ and
> .B \-l internal \-l size=10m
> are equivalent.
> .PP
> +An optional XFS configuration file directory
> +.B mkfs.xfs.d (5)
> +exists to help fine tune different default parameters which can be used when
> +calling
> +.B mkfs.xfs (8).
> +If present, and if
> +.B -c
> +is not used, the default configuration file @sysconfigdir@/mkfs.xfs.d/default
s/sysconfigdir/sysconfdir/ or this won't get replaced.
...
> diff --git a/mkfs/Makefile b/mkfs/Makefile
> index c84f9b6ae63b..c7815b3e106b 100644
> --- a/mkfs/Makefile
> +++ b/mkfs/Makefile
> @@ -8,7 +8,7 @@ include $(TOPDIR)/include/builddefs
> LTCOMMAND = mkfs.xfs
>
> HFILES =
> -CFILES = proto.c xfs_mkfs.c
> +CFILES = proto.c xfs_mkfs.c config.c
>
> LLDLIBS += $(LIBXFS) $(LIBXCMD) $(LIBFROG) $(LIBRT) $(LIBPTHREAD) $(LIBBLKID) \
> $(LIBUUID)
... snip stuff i'll circle back to, sorry for being a bit rando ...
> +/*
> + * If the file is not found -1 is returned and errno set. Otherwise
> + * the file descriptor is returned.
> + */
> +int
> +open_cli_config(
> + char *cli_config_file,
> + char **fpath)
> +{
> + int fd, len;
> + char *final_path = NULL;
> + char *relative_path= NULL;
> + unsigned int i;
> +
> + if (strlen(cli_config_file) > 2) {
> + if (cli_config_file[0] == '.' && cli_config_file[1] == '/')
> + final_path = cli_config_file;
> + else if (cli_config_file[0] == '.' && cli_config_file[1] == '.')
> + final_path = cli_config_file;
> + else if (cli_config_file[0] == '/')
> + final_path = cli_config_file;
> + else
> + relative_path = cli_config_file;
> + } else if (strlen(cli_config_file) == 1) {
> + if (cli_config_file[0] == '.' || cli_config_file[0] == '/') {
> + errno = EINVAL;
> + return -1;
> + } else
> + relative_path = cli_config_file;
> + }
I mentioned the problem w/ strlen == 2; I also noticed that you can
point -c at i.e. /dev/sdb1 and it'll try to read it. Dave suggested that
a stat and rejection of anything but a regular file is in order here.
bed();
will look more tomorrow.
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
` (2 preceding siblings ...)
2018-05-30 3:33 ` Eric Sandeen
@ 2018-05-30 3:33 ` Dave Chinner
2018-06-01 21:13 ` Luis R. Rodriguez
2018-05-30 7:36 ` Martin Steigerwald
` (3 subsequent siblings)
7 siblings, 1 reply; 21+ messages in thread
From: Dave Chinner @ 2018-05-30 3:33 UTC (permalink / raw)
To: Luis R. Rodriguez
Cc: sandeen, linux-xfs, darrick.wong, jack, jeffm, okurz, lpechacek, jtulak
On Tue, May 29, 2018 at 03:06:02PM -0700, Luis R. Rodriguez wrote:
> You may want to stick to specific set of configuration options when
> creating filesystems with mkfs.xfs -- sometimes due to pure technical
> reasons, but some other times to ensure systems remain compatible as
> new features are introduced with older kernels, or if you always want
> to take advantage of some new feature which would otherwise typically
> be disruptive.
>
> This adds support for parsing a configuration file to override defaults
> parameters to be used for mkfs.xfs.
.....
> +static int
> +data_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum data_subopts subopt = psubopt;
This is unnecessary. enums and ints are the same thing when it comes
to comparisons.
> +
> + switch (subopt) {
> + case D_NOALIGN:
> + dft->sb_feat.nodalign = value;
> + return 0;
> + }
> + return EINVAL;
Negative errors, please. All xfsprogs use negative error numbers
like the kernel now, so please don't take us back to the bad old
days of having to change error signs depending on where the error
came from....
Actually, I'm surprised that the compiler isn't complaining about
not having a default statement in the switch statement. Can they be
structured like the cli options to avoid this in future?
switch (subopt) {
case D_NOALIGN:
.....
break;
default:
return -EINVAL;
}
return 0;
> +enum parse_line_type {
> + PARSE_COMMENT = 0,
> + PARSE_EMPTY,
> + PARSE_SECTION,
> + PARSE_TAG_VALUE,
> + PARSE_INVALID,
> + PARSE_EOF,
> +};
> +
> +static bool
> +isempty(
> + const char *line,
> + ssize_t linelen)
> +{
> + ssize_t i = 0;
> + char p;
> +
> + while (i != linelen) {
while (i < linelen) {
> + p = line[i];
> + i++;
p = line[i++];
> +
> + /* tab or space */
> + if (isblank(p))
> + continue;
> + else
> + return false;
> + }
if (!isblank(p))
return false;
}
> +
> + return true;
> +}
> +
> +static bool
> +iscomment(
> + const char *line,
> + ssize_t linelen)
> +{
> + ssize_t i = 0;
> + char p;
> +
> + while (i != linelen) {
> + p = line[i];
> + i++;
> +
> + /* tab or space */
> + if (isblank(p))
> + continue;
> +
> + if (p == '#')
> + return true;
> +
> + return false;
> + }
> +
> + return false;
> +}
> +
> +static int
> +parse_line_section(
> + const char *line,
> + char **tag)
> +{
> + return sscanf(line, " [%m[^]]]", tag);
> +}
> +
> +static int
> +parse_line_tag_value(
> + const char *line,
> + char **tag,
> + uint64_t *value)
> +{
> + return sscanf(line, " %m[^ \t=]"
> + " = "
> + "%lu ",
> + tag, value);
> +}
%lu won't match uint64_t on 32 bit builds. Doesn't this need to be
PRIu64 to be correct? Hmmm, I thought the compiler checked this
format stuff and threw warnings when you get it wrong?
Also, I'm not sure there's any value to these single line functions.
Why not just call them directly in the next function?
> +
> +static enum parse_line_type
> +parse_get_line_type(
> + const char *line,
> + ssize_t linelen,
> + char **tag,
> + uint64_t *value)
> +{
> + int ret;
> + uint64_t u64_value;
> +
> + if (isempty(line, linelen))
> + return PARSE_EMPTY;
> +
> + if (iscomment(line, linelen))
> + return PARSE_COMMENT;
> +
> + ret = parse_line_section(line, tag);
> + if (ret == 1)
> + return PARSE_SECTION;
i.e.
/* check if we have a section header */
ret = sscanf(line, " [%m[^]]]", tag);
if (ret == 1)
return PARSE_SECTION;
> +
> + if (ret == EOF)
> + return PARSE_EOF;
> +
> + ret = parse_line_tag_value(line, tag, &u64_value);
> + if (ret == 2) {
> + *value = u64_value;
> +
> + return PARSE_TAG_VALUE;
> + }
/* should be a "tag = value" config option */
ret = sscanf(line, " %m[^ \t=] = %" PRIu64 " ", tag, value);
if (ret == 2)
return PARSE_TAG_VALUE;
> +
> + if (ret == EOF)
> + return PARSE_EOF;
> +
> + return PARSE_INVALID;
> +}
> +
> +static int
> +parse_config_stream(
> + struct mkfs_default_params *dft,
> + const char *config_file,
> + FILE *fp)
> +{
> + int ret;
> + char *line = NULL;
> + ssize_t linelen;
> + size_t len = 0, lineno = 0;
> + uint64_t value;
> + enum parse_line_type parse_type;
> + struct confopts *confopt = NULL;
> + int subopt;
> +
> + while ((linelen = getline(&line, &len, fp)) != -1) {
> + char *ignore_value;
> + char *p, *tag = NULL;
> +
> + lineno++;
> +
> + /*
> + * tag is allocated for us by scanf(), it must freed only on any
> + * successful parse of a section or tag-value pair.
> + */
> + parse_type = parse_get_line_type(line, linelen, &tag, &value);
> +
> + switch (parse_type) {
> + case PARSE_EMPTY:
> + case PARSE_COMMENT:
> + /* Nothing tag to free for these */
> + continue;
> + case PARSE_EOF:
> + break;
> + case PARSE_INVALID:
> + ret = EINVAL;
Negative errors.
> + fprintf(stderr, _("Invalid line %s:%zu : %s\n"),
> + config_file, lineno, line);
> + goto out;
> + case PARSE_SECTION:
> + confopt = get_confopts(tag);
> + if (!confopt) {
> + ret = EINVAL;
> + fprintf(stderr, _("Invalid section on line %s:%zu : %s\n"),
> + config_file, lineno, tag);
> + free(tag);
> + goto out;
goto out_free_tag;
....
out_free_tag:
free(tag);
ret = -EINVAL;
goto out;
Same for all thers others.
> + }
> + if (!confopt->subopts) {
> + ret = EINVAL;
> + fprintf(stderr, _("Section not yet supported on line %s:%zu : %s\n"),
> + config_file, lineno, tag);
> + free(tag);
> + goto out;
> + }
> + if (confopt->seen) {
> + ret = EINVAL;
> + fprintf(stderr, _("Section '%s' respecified\n"),
> + tag);
> + free(tag);
> + goto out;
> + }
> + confopt->seen = true;
> + free(tag);
> + break;
> + case PARSE_TAG_VALUE:
> + if (!confopt) {
> + ret = EINVAL;
> + fprintf(stderr, _("No section specified yet on line %s:%zu : %s\n"),
> + config_file, lineno, line);
> + free(tag);
> + goto out;
> + }
> +
> + /*
> + * We re-use the line buffer allocated by getline(),
> + * however line must be kept pointing to its original
> + * value to free it later. A separate pointer is needed
> + * as getsubopt() will otherwise muck with the value
> + * passed.
> + */
> + p = line;
> +
> + /*
> + * Trims white spaces. getsubopt() does not grok
> + * white space, it would fail otherwise.
> + */
> + snprintf(p, len, "%s=%lu", tag, value);
> +
> + /* Not needed anymore */
> + free(tag);
> +
> + /*
> + * We only use getsubopt() to validate the possible
> + * subopt, we already parsed the value and its already
> + * in a more preferred data type.
> + */
> + subopt = getsubopt(&p, (char **) confopt->subopts,
> + &ignore_value);
This hoop-jumping cruft can all be replaced with a simple loop that
just compares the tag to the subopts array:
for (i = 0; i < MAX_SUBOPTS; i++) {
if (!confopt->subopts[i]) {
/* option not found, error out */
goto out_free_tag;
}
if (strcmp(confopt->subopts[i], tag) == 0)
break;
}
free(tag);
ret = confopt->parser(dft, i, value);
> + if (ret) {
> + fprintf(stderr, _("Error parsine line %s:%zu : %s\n"),
> + config_file, lineno, line);
> + goto out;
> + }
> +
> + break;
> + }
> + }
> +out:
> + /* We must free even if getline() failed */
> + free(line);
> + return ret;
> +}
> +
> +static const char *conf_paths[] = {
> + ".",
> + MKFS_XFS_CONF_DIR,
> +};
> +
> +/*
> + * If the file is not found -1 is returned and errno set. Otherwise
> + * the file descriptor is returned.
> + */
> +int
> +open_cli_config(
> + char *cli_config_file,
> + char **fpath)
> +{
> + int fd, len;
> + char *final_path = NULL;
> + char *relative_path= NULL;
> + unsigned int i;
> +
> + if (strlen(cli_config_file) > 2) {
> + if (cli_config_file[0] == '.' && cli_config_file[1] == '/')
> + final_path = cli_config_file;
> + else if (cli_config_file[0] == '.' && cli_config_file[1] == '.')
> + final_path = cli_config_file;
> + else if (cli_config_file[0] == '/')
> + final_path = cli_config_file;
> + else
> + relative_path = cli_config_file;
> + } else if (strlen(cli_config_file) == 1) {
> + if (cli_config_file[0] == '.' || cli_config_file[0] == '/') {
> + errno = EINVAL;
> + return -1;
> + } else
> + relative_path = cli_config_file;
> + }
This seems somewhat complex, and it doesn't check what the target of
the path is.
fstatat(AT_FDCWD, fpath, &st, AT_SYMLINK_NOFOLLOW);
will tell us if the file exists, it doesn't end in a symlink
and it will resolve both both relative and absolute paths correctly.
If it succeeds, then we can check that the path points to a regular
file (and not, say, a block device) so that this sort of thing:
[30/5/18 12:08] <sandeen> mkfs/mkfs.xfs -c /dev/sdb1
[30/5/18 12:08] <sandeen> Invalid line /dev/sdb1:1 : XFSB
Gives a sensible error before we get to parsing.
If the file is found and isn't a regular file, then abort.
If the file isn't found, then we need to ensure that we have been
passed a name without any directory component as we are going to
search the sysconf dir for that file. That's where basename(3) comes
in - if the name returned by basename(3) doesn't match fpath, then
there was a directory component in fpath, and we reject it and
abort.
Then we can open the sysconf directory w/ O_PATH|O_DIRECTORY, then
do the same fstatat check and open it w/ openat():
fstatat(dirfd, fpath, &st, AT_SYMLINK_NOFOLLOW);
/* check return */
openat(dirfd, fpath, O_NOFOLLOW, O_RDONLY);
IOWs, I don't think we should be looking at just the first two
characters of the supplied filename to determine the action to take,
nor do i think we shoul dbe trying to resolve relative paths under
the sysconf dir.
> +/*
> + * This is only called *iff* there is a configuration file which we know we
> + * *must* parse.
> + *
> + * If default_fd is set and is a valid file descriptor then the configuration
> + * file passed is the system default configuraiton file, and we already know
> + * it exists. If default_fd is not set we assume we've been passed a
> + * configuration file from the command line and must it must exist, otherwise
> + * we have to error out.
> + */
> +int
> +parse_defaults_file(
> + struct mkfs_default_params *dft,
> + int default_fd,
> + char *config_file)
> +{
> + char *fpath;
> + int fd;
> + FILE *fp;
> + int ret;
> + struct stat sp;
> +
> + if (strlen(config_file) > PATH_MAX)
> + return ENAMETOOLONG;
> +
> + fpath = malloc(PATH_MAX);
> + if (!fpath)
> + return ENOMEM;
> + memset(fpath, 0, PATH_MAX);
> +
> + if (default_fd < 0) {
> + fd = open_cli_config(config_file, &fpath);
> + if (fd < 0) {
> + free(fpath);
> + return errno;
> + }
> + } else {
> + fd = default_fd;
> + memcpy(fpath, config_file, strlen(config_file));
> + }
This is messy - opening the file shoul dbe split from parsing the
config file. I make more comments about the reason below. But I
think this should end up as:
int
open_config_file(
const char *config_file,
char **source)
{
/*
* XXX: should asprintf the source string so it's got the
* config_file opened in it.
*/
dft.source = _("Built in defaults");
dirfd = open(sysconfdir, O_PATH|O_NOFOLLOW);
if (config_file) {
fd = open_cli_config(dirfd, config_file)
if (fd > 0)
*source = _("CLI supplied file");
goto out;
}
fd = openat(dirfd, "default")
if (fd > 0)
*source = ("Package default config file")
out:
close(dirfd);
return fd;
}
and so be completely separated from the act of parsing the config
file.
> +
> + /*
> + * At this point we know we have a valid file descriptor and have
> + * figured out the path to the file used on fpath. Get the file stream
> + * and do a bit of sanity checks before parsing the file.
> + */
> +
> + fp = fdopen(fd, "r");
> + if (!fp) {
> + perror(fpath);
> + ret = errno;
> + goto out_close_fd;
> + }
> +
> + ret = fstat(fd, &sp);
> + if (ret) {
> + ret = errno;
> + fprintf(stderr, _("Could not fstat() config file: %s: %s\n"),
> + fpath, strerror(errno));
> + goto out;
> + }
> +
> + if (S_ISDIR(sp.st_mode)) {
> + ret = EBADF;
if (!S_ISREG(sp.st_mode)) {
ret = -EINVAL;
> + fprintf(stderr, _("Config file is a directory: %s\n"), fpath);
> + goto out;
> + }
> +
> + /* Anything beyond 1 MiB is kind of silly right now */
> + if (sp.st_size > 1 * 1024 * 1024) {
> + ret = E2BIG;
> + goto out;
> + }
As mentioned about, these checks should be done before we even open
the file.
> + ret = parse_config_stream(dft, config_file, fp);
> + if (ret)
> + goto out;
> +
> + printf(_("config-file=%s\n"), fpath);
> +
> +out:
> + fclose(fp);
> +out_close_fd:
> + close(fd);
> + free(fpath);
> + return ret;
> +}
> diff --git a/mkfs/config.h b/mkfs/config.h
> index e5ea968e2d65..0f429d9b7fd7 100644
> --- a/mkfs/config.h
> +++ b/mkfs/config.h
> @@ -19,6 +19,8 @@
> #ifndef _XFS_MKFS_CONFIG_H
> #define _XFS_MKFS_CONFIG_H
>
> +#define MKFS_XFS_CONF_DIR ROOT_SYSCONFDIR "/mkfs.xfs.d"
> +
> struct fsxattr;
>
> /*
> @@ -29,7 +31,7 @@ struct fsxattr;
> * source can overriding the later source:
> *
> * o built-in defaults
> - * o configuration file (XXX)
> + * o configuration file
> * o command line
> *
> * These values are not used directly - they are inputs into the mkfs geometry
> @@ -75,4 +77,10 @@ struct mkfs_default_params {
> struct fsxattr fsx;
> };
>
> +int
> +parse_defaults_file(
> + struct mkfs_default_params *dft,
> + int default_fd,
> + char *config_file);
> +
> #endif /* _XFS_MKFS_CONFIG_H */
> diff --git a/mkfs/xfs_mkfs.c b/mkfs/xfs_mkfs.c
> index 4664e507afbf..81ef7ab584ed 100644
> --- a/mkfs/xfs_mkfs.c
> +++ b/mkfs/xfs_mkfs.c
> @@ -3743,6 +3743,11 @@ main(
> .nortalign = false,
> },
> };
> + char *default_config = MKFS_XFS_CONF_DIR "/default";
> + char *cli_config_file = NULL;
> + char *config_file = NULL;
> + int default_fd = -1;
> + int ret;
>
> platform_uuid_generate(&cli.uuid);
> progname = basename(argv[0]);
> @@ -3751,25 +3756,74 @@ main(
> textdomain(PACKAGE);
>
> /*
> - * TODO: Sourcing defaults from a config file
> - *
> * Before anything else, see if there's a config file with different
> - * defaults. If a file exists in <package location>, read in the new
> - * default values and overwrite them in the &dft structure. This way the
> - * new defaults will apply before we parse the CLI, and the CLI will
> - * still be able to override them. When more than one source is
> - * implemented, emit a message to indicate where the defaults being
> - * used came from.
> + * defaults. If the CLI specified a full path we use and require that.
> + * If a relative path was provided on the CLI we search the allowed
> + * search paths for the file. If no config file was specified on the
> + * CLI we will look for MKFS_XFS_CONF_DIR/default and use that if
> + * present, however this file is optional.
> *
> - * printf(_("Default configuration sourced from %s\n"), dft.source);
> + * If a configuration file is found we use it to help overwrite default
> + * values in the &dft structure. This way the new defaults will apply
> + * before we parse the CLI, and the user will still be able to override
> + * them through the CLI.
> + */
> +
> + /*
> + * Pull config line options from command line
> */
> + while ((c = getopt(argc, argv, "b:c:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
Why specify all the parameters? We're only interested in the "c:"
parameter here, so that's the only one we need to specify, right?
Otherwise we've got two config option strings we need to keep i
check...
> + switch (c) {
> + case 'c':
> + if (cli_config_file) {
> + fprintf(stderr, _("respecification of configuration not allowed\n"));
> + exit(1);
> + }
> + cli_config_file = optarg;
> + dft.source = _("command line");
> + break;
> + default:
> + continue;
> + }
> + }
> +
> + if (cli_config_file)
> + config_file = cli_config_file;
> + else {
> + default_fd = open(default_config, O_RDONLY);
> + if (default_fd >= 0) {
> + dft.source = _("system default configuration file");
> + config_file = default_config;
> + }
> + }
> +
> + if (config_file) {
> + /* If default_fd is set it will be closed for us */
> + ret = parse_defaults_file(&dft, default_fd, config_file);
> + if (ret) {
> + fprintf(stderr, _("Error parsing %s config file: %s : %s\n"),
> + dft.source, config_file,
> + strerror(ret));
> + exit(1);
> + }
> + }
It doesn't make sense to me to open the default config file here
before we know if it going to be needed. I would suggest that this
get split into two parts - one to find and open the config file, the
other to parse the opened file. i.e.:
fd = open_config_file(cli_config_file, &dft.source);
if (fd >= 0) {
ret = parse_defaults_file(fd, &dft);
....
close(fd);
}
Cheers,
Dave.
--
Dave Chinner
david@fromorbit.com
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
` (3 preceding siblings ...)
2018-05-30 3:33 ` Dave Chinner
@ 2018-05-30 7:36 ` Martin Steigerwald
2018-05-30 16:06 ` Darrick J. Wong
` (2 subsequent siblings)
7 siblings, 0 replies; 21+ messages in thread
From: Martin Steigerwald @ 2018-05-30 7:36 UTC (permalink / raw)
To: Luis R. Rodriguez
Cc: sandeen, linux-xfs, darrick.wong, jack, jeffm, okurz, lpechacek, jtulak
Hi Luis.
Luis R. Rodriguez - 30.05.18, 00:06:
> You may want to stick to specific set of configuration options when
> creating filesystems with mkfs.xfs -- sometimes due to pure technical
> reasons, but some other times to ensure systems remain compatible as
> new features are introduced with older kernels, or if you always want
> to take advantage of some new feature which would otherwise typically
> be disruptive.
>
> This adds support for parsing a configuration file to override
> defaults parameters to be used for mkfs.xfs.
>
> We define an XFS configuration directory, /etc/mkfs.xfs.d/ and allow
> for different configuration files, if none is specified we look for
> the default configuration file, /etc/mkfs.xfs.d/default. You can
> override with -c. For instance, if you specify:
>
> mkfs.xfs -c experimental -f /dev/loop0
Just two considerations (I am myself not sure ATM whether it makes sense
to implement them):
Usually for "*.d" directories in /etc all configuration files are
parsed, yet you parse only one which makes perfect sense for the
usecase, but may not be what the admin expects. So it may make sense to
use a different directory name.
Also in case you ever want to implement default mount options or
whatever… it may make sense to use /etc/xfs as a base directory for
everything (unless that is taken by something else, but I think X11 font
server stuff is inside /etc/X11 if at all present).
> The search path for the configuration file will be:
>
> 1) $PWD/experimental
> 2) /etc/mkfs.xfs.d/experimental
>
> Absolute paths are supported, in which case they will be used directly
> and the mkfs.xfs.d directory is ignored.
>
> To verify what configuration file is used on a system use the typical:
>
> mkfs.xfs -N
>
> There is only a subset of options allowed to be set on the
> configuration file. The default parameters you can override on a
> configuration file and their current built-in default settings are:
[…]
--
Martin
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
` (4 preceding siblings ...)
2018-05-30 7:36 ` Martin Steigerwald
@ 2018-05-30 16:06 ` Darrick J. Wong
2018-05-30 18:10 ` [PATCH 3.5/4] mkfs.xfs: document defaults config file details Eric Sandeen
2018-05-30 21:05 ` [PATCH 3.7/4] mkfs.xfs.8: parameterize sysconfdir Eric Sandeen
7 siblings, 0 replies; 21+ messages in thread
From: Darrick J. Wong @ 2018-05-30 16:06 UTC (permalink / raw)
To: Luis R. Rodriguez
Cc: sandeen, linux-xfs, jack, jeffm, okurz, lpechacek, jtulak
On Tue, May 29, 2018 at 03:06:02PM -0700, Luis R. Rodriguez wrote:
> You may want to stick to specific set of configuration options when
> creating filesystems with mkfs.xfs -- sometimes due to pure technical
> reasons, but some other times to ensure systems remain compatible as
> new features are introduced with older kernels, or if you always want
> to take advantage of some new feature which would otherwise typically
> be disruptive.
>
> This adds support for parsing a configuration file to override defaults
> parameters to be used for mkfs.xfs.
>
> We define an XFS configuration directory, /etc/mkfs.xfs.d/ and allow for
> different configuration files, if none is specified we look for the
> default configuration file, /etc/mkfs.xfs.d/default. You can override
> with -c. For instance, if you specify:
>
> mkfs.xfs -c experimental -f /dev/loop0
>
> The search path for the configuration file will be:
>
> 1) $PWD/experimental
> 2) /etc/mkfs.xfs.d/experimental
>
> Absolute paths are supported, in which case they will be used directly
> and the mkfs.xfs.d directory is ignored.
>
> To verify what configuration file is used on a system use the typical:
>
> mkfs.xfs -N
>
> There is only a subset of options allowed to be set on the configuration
> file. The default parameters you can override on a configuration file and
> their current built-in default settings are:
>
> [data]
> noalign=0
>
> [inode]
> align=1
> projid32bit=1
> sparse=0
>
> [log]
> lazy-count=1
>
> [metadata]
> crc=1
> finobt=1
> rmapbt=0
> reflink=0
>
> [naming]
> ftype=1
>
> [rtdev]
> noalign=0
>
> Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
> ---
> configure.ac | 6 +-
> include/builddefs.in | 2 +
> man/man5/Makefile | 2 +
> man/man5/mkfs.xfs.d.5.in | 151 ++++++++
> man/man8/Makefile | 2 +
> man/man8/{mkfs.xfs.8 => mkfs.xfs.8.in} | 27 ++
> mkfs/Makefile | 2 +-
> mkfs/config.c | 645 +++++++++++++++++++++++++++++++++
> mkfs/config.h | 10 +-
> mkfs/xfs_mkfs.c | 76 +++-
> 10 files changed, 909 insertions(+), 14 deletions(-)
> create mode 100644 man/man5/mkfs.xfs.d.5.in
> rename man/man8/{mkfs.xfs.8 => mkfs.xfs.8.in} (96%)
> create mode 100644 mkfs/config.c
>
> diff --git a/configure.ac b/configure.ac
> index 508eefede073..94c5bda725f2 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -233,5 +233,9 @@ AC_CHECK_SIZEOF([char *])
> AC_TYPE_UMODE_T
> AC_MANUAL_FORMAT
>
> -AC_CONFIG_FILES([include/builddefs])
> +AC_CONFIG_FILES([
> + include/builddefs
> + man/man5/mkfs.xfs.d.5
> + man/man8/mkfs.xfs.8
Wait a minute, AC_CONFIG_FILES is for generating configuration files to
feed to the build. Using it for manpages means that the manpages are
only regenerated from the source files at configure time, so if I edit
mkfs.xfs.8.in and run make, the manpage doesn't get regenerated.
I suggest a man/man[58]/Makefile rule similar to the one in
scrub/Makefile that generates xfs_scrub_all.
--D
> +])
> AC_OUTPUT
> diff --git a/include/builddefs.in b/include/builddefs.in
> index 8aac06cf90dc..e1ee9f7ba086 100644
> --- a/include/builddefs.in
> +++ b/include/builddefs.in
> @@ -62,6 +62,7 @@ PKG_LIB_DIR = @libdir@@libdirsuffix@
> PKG_INC_DIR = @includedir@/xfs
> DK_INC_DIR = @includedir@/disk
> PKG_MAN_DIR = @mandir@
> +PKG_ETC_DIR = @sysconfdir@
> PKG_DOC_DIR = @datadir@/doc/@pkg_name@
> PKG_LOCALE_DIR = @datadir@/locale
>
> @@ -196,6 +197,7 @@ endif
>
> GCFLAGS = $(DEBUG) \
> -DVERSION=\"$(PKG_VERSION)\" -DLOCALEDIR=\"$(PKG_LOCALE_DIR)\" \
> + -DROOT_SYSCONFDIR=\"$(PKG_ETC_DIR)\" \
> -DPACKAGE=\"$(PKG_NAME)\" -I$(TOPDIR)/include -I$(TOPDIR)/libxfs
>
> ifeq ($(ENABLE_GETTEXT),yes)
> diff --git a/man/man5/Makefile b/man/man5/Makefile
> index fe0aef6f016b..0b33122b064e 100644
> --- a/man/man5/Makefile
> +++ b/man/man5/Makefile
> @@ -19,3 +19,5 @@ install : default
> $(INSTALL) -m 755 -d $(MAN_DEST)
> $(INSTALL_MAN)
> install-dev :
> +
> +LDIRT += mkfs.xfs.d.5
> diff --git a/man/man5/mkfs.xfs.d.5.in b/man/man5/mkfs.xfs.d.5.in
> new file mode 100644
> index 000000000000..287877ce029d
> --- /dev/null
> +++ b/man/man5/mkfs.xfs.d.5.in
> @@ -0,0 +1,151 @@
> +.TH mkfs.xfs.d 5
> +.SH NAME
> +mkfs.xfs.d \- mkfs.xfs configuration directory
> +.SH DESCRIPTION
> +.B mkfs.xfs (8)
> +uses a set of initial default parameters for configuration.
> +
> +The built-in mkfs defaults are decided by the XFS community. New features are
> +only enabled by default when the community consider them stable. One can
> +override these defaults on the
> +.B mkfs.xfs (8)
> +command line, but there are cases where it is desirable for the distro or the
> +system administrator to establish their own supported defaults in a uniform
> +manner, regardless of the version of
> +.B mkfs.xfs (8)
> +used. This may be desirable for example on systems with old kernels
> +where the built-in default
> +.B mkfs.xfs (8)
> +parameters create a filesystem that is not supported by the old kernel.
> +In such situations it would also be unclear what parameters are needed to
> +produce a compatible filesystem, having a configuration file present ensures
> +that if newer versions of
> +.B mkfs.xfs (8)
> +are deployed, creating a filesystem will remain compatible. Overriding
> +.B mkfs.xfs (8)
> +built-in defaults may also be desirable if you have a series of systems with
> +different kernels and want to be able to create filesystems which all systems
> +are able to support properly.
> +.PP
> +The XFS configuration directory
> +.B mkfs.xfs.d (5)
> +can be used as a home to define different configuration files which can be used
> +to override the built-in default parameters by
> +.B mkfs.xfs (8).
> +If the
> +.B -c
> +parameter is not used, the default configuration file:
> +.IP
> +.I @sysconfdir@/mkfs.xfs.d/default
> +.PP
> +will be looked for first and if present will be used to override
> +.B mkfs.xfs (8)
> +built-in default parameters.
> +.PP
> +You can override the default configuration file by specifying its name when
> +using
> +.B mkfs.xfs (8)
> +by using the
> +.B -c
> +parameter.
> +.PP
> +If the path does not start with a '.', the current working directory is
> +searched for the file. If the file is not found there, the
> +.B mkfs.xfs.d (5)
> +directory is searched for the file.
> +.PP
> +If
> +.B -c
> +is used with relative path with which has a leading '.' character, the given
> +path is used directly, so the configuration file will be relative to the
> +current working directory.
> +.PP
> +If the
> +.B -c
> +argument starts with a '/', it is considered an absolute path, and opened.
> +.PP
> +For example:
> +.IP
> +.B mkfs.xfs -c experimental -f /dev/sda1
> +.PP
> +Will make
> +.B mkfs.xfs (8)
> +look for the following configuration files and use the first one it finds:
> +.IP
> +.B $PWD/experimental
> +.br
> +.B @sysconfdir@/mkfs.xfs.d/experimental
> +.PP
> +If you used an absolute path, for example:
> +.IP
> +.B mkfs.xfs -c /tmp/experimental -f /dev/sda1
> +.PP
> +Then only the configuration file /tmp/experimental will be looked for and
> +used if present.
> +.PP
> +If you use the
> +.B -c
> +parameter the configuration file must be present and must parse correctly.
> +.PP
> +Parameters passed to the
> +.B mkfs.xfs (8)
> +command line always override any defaults set by the configuration file.
> +.PP
> +.B mkfs.xfs (8)
> +will always describe what configuration file was used, if any
> +was used at all. To verify which configuration file would be used prior to
> +execution of
> +.B mkfs.xfs (8)
> +you can use
> +.I mkfs.xfs -N.
> +.PP
> +.SH DEFAULT PARAMETERS
> +Default parameters for
> +.B mkfs.xfs (8)
> +consists of a small subset of the parameters one can set with on the command
> +line. Currently all default parameters can only be either enabled or disabled,
> +you can set their value to 1 to enable or 0 to disable. Below we list the
> +different supported default parameters which can be defined on configuration
> +files, along with the current built-in setting.
> +.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 mkfs.xfs (8),
> +.BR xfsctl (3),
> +.BR xfs_info (8),
> +.BR xfs_admin (8),
> +.BR xfsdump (8),
> +.BR xfsrestore (8).
> diff --git a/man/man8/Makefile b/man/man8/Makefile
> index 36620da172ae..2a6548079997 100644
> --- a/man/man8/Makefile
> +++ b/man/man8/Makefile
> @@ -19,3 +19,5 @@ install : default
> $(INSTALL) -m 755 -d $(MAN_DEST)
> $(INSTALL_MAN)
> install-dev :
> +
> +LDIRT += mkfs.xfs.8
> diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8.in
> similarity index 96%
> rename from man/man8/mkfs.xfs.8
> rename to man/man8/mkfs.xfs.8.in
> index 4b8c78c37806..81e2753bd2b5 100644
> --- a/man/man8/mkfs.xfs.8
> +++ b/man/man8/mkfs.xfs.8.in
> @@ -83,6 +83,24 @@ and
> .B \-l internal \-l size=10m
> are equivalent.
> .PP
> +An optional XFS configuration file directory
> +.B mkfs.xfs.d (5)
> +exists to help fine tune different default parameters which can be used when
> +calling
> +.B mkfs.xfs (8).
> +If present, and if
> +.B -c
> +is not used, the default configuration file @sysconfigdir@/mkfs.xfs.d/default
> +will be used to override system build-in defaults. Refer to mkfs.xfs.d (5)
> +for a list of current defaults and further details.
> +Command line arguments directly passed to
> +.B mkfs.xfs (8)
> +will always override parameters set in the configuration file.
> +You can override the configuration file used by using the
> +.B -c
> +parameter, further explained below and in
> +.B mkfs.xfs.d (5)
> +.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,
> @@ -123,6 +141,14 @@ Many feature options allow an optional argument of 0 or 1, to explicitly
> disable or enable the functionality.
> .SH OPTIONS
> .TP
> +.BI \-c " configuration-file"
> +Override the configuration file used. If a relative path is given the search
> +path for the configuration file is your current directory and then the
> +.B mkfs.xfs.d (5)
> +directory. If an absolute path is given it is used directly. For more details
> +refer to
> +.B mkfs.xfs.d (5)
> +.TP
> .BI \-b " block_size_options"
> This option specifies the fundamental block size of the filesystem.
> The valid
> @@ -923,6 +949,7 @@ Prints the version number and exits.
> .SH SEE ALSO
> .BR xfs (5),
> .BR mkfs (8),
> +.BR mkfs.xfs.d (5),
> .BR mount (8),
> .BR xfs_info (8),
> .BR xfs_admin (8).
> diff --git a/mkfs/Makefile b/mkfs/Makefile
> index c84f9b6ae63b..c7815b3e106b 100644
> --- a/mkfs/Makefile
> +++ b/mkfs/Makefile
> @@ -8,7 +8,7 @@ include $(TOPDIR)/include/builddefs
> LTCOMMAND = mkfs.xfs
>
> HFILES =
> -CFILES = proto.c xfs_mkfs.c
> +CFILES = proto.c xfs_mkfs.c config.c
>
> LLDLIBS += $(LIBXFS) $(LIBXCMD) $(LIBFROG) $(LIBRT) $(LIBPTHREAD) $(LIBBLKID) \
> $(LIBUUID)
> diff --git a/mkfs/config.c b/mkfs/config.c
> new file mode 100644
> index 000000000000..0b4aebe51903
> --- /dev/null
> +++ b/mkfs/config.c
> @@ -0,0 +1,645 @@
> +/*
> + * Copyright (c) 2018 Luis R. Rodriguez <mcgrof@kernel.org>
> + *
> + * This program is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU General Public License
> + * as published by the Free Software Foundation; either version 2
> + * of the License, or (at your option) any later version.
> + *
> + * This program is distributed in the hope that it would be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> + * GNU General Public License for more details.
> + *
> + * You should have received a copy of the GNU General Public License
> + * along with this program; if not, write the Free Software Foundation,
> + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
> + */
> +
> +#include <ctype.h>
> +#include <dirent.h>
> +#include <fcntl.h>
> +
> +#include "libxfs.h"
> +#include "config.h"
> +
> +/*
> + * Enums for each configuration option. All these currently match the CLI
> + * parameters for now but this may change later, so we keep all this code
> + * and definitions separate. The rules for configuration parameters may also
> + * differ.
> + *
> + * We only provide definitions for what we currently support parsing.
> + */
> +
> +enum data_subopts {
> + D_NOALIGN = 0,
> +};
> +
> +enum inode_subopts {
> + I_ALIGN = 0,
> + I_PROJID32BIT,
> + I_SPINODES,
> +};
> +
> +enum log_subopts {
> + L_LAZYSBCNTR = 0,
> +};
> +
> +enum metadata_subopts {
> + M_CRC = 0,
> + M_FINOBT,
> + M_RMAPBT,
> + M_REFLINK,
> +};
> +
> +enum naming_subopts {
> + N_FTYPE = 0,
> +};
> +
> +enum rtdev_subopts {
> + R_NOALIGN = 0,
> +};
> +
> +/* Just define the max options array size manually right now */
> +#define MAX_SUBOPTS 4
> +
> +static int
> +data_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum data_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case D_NOALIGN:
> + dft->sb_feat.nodalign = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +static int
> +inode_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum inode_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case I_ALIGN:
> + dft->sb_feat.inode_align = value;
> + return 0;
> + case I_PROJID32BIT:
> + dft->sb_feat.projid32bit = value;
> + return 0;
> + case I_SPINODES:
> + dft->sb_feat.spinodes = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +static int
> +log_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum log_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case L_LAZYSBCNTR:
> + dft->sb_feat.lazy_sb_counters = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +static int
> +metadata_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum metadata_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case M_CRC:
> + dft->sb_feat.crcs_enabled = value;
> + if (dft->sb_feat.crcs_enabled)
> + dft->sb_feat.dirftype = true;
> + return 0;
> + case M_FINOBT:
> + dft->sb_feat.finobt = value;
> + return 0;
> + case M_RMAPBT:
> + dft->sb_feat.rmapbt = value;
> + return 0;
> + case M_REFLINK:
> + dft->sb_feat.reflink = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +static int
> +naming_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum naming_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case N_FTYPE:
> + dft->sb_feat.dirftype = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +static int
> +rtdev_config_parser(
> + struct mkfs_default_params *dft,
> + int psubopt,
> + uint64_t value)
> +{
> + enum rtdev_subopts subopt = psubopt;
> +
> + switch (subopt) {
> + case R_NOALIGN:
> + dft->sb_feat.nortalign = value;
> + return 0;
> + }
> + return EINVAL;
> +}
> +
> +struct confopts {
> + const char *name;
> + const char *subopts[MAX_SUBOPTS];
> + int (*parser)(struct mkfs_default_params *dft,
> + int psubopt, uint64_t value);
> + bool seen;
> +} confopts_tab[] = {
> + {
> + .name = "data",
> + .subopts = {
> + [D_NOALIGN] = "noalign",
> + },
> + .parser = data_config_parser,
> + },
> + {
> + .name = "inode",
> + .subopts = {
> + [I_ALIGN] = "align",
> + [I_PROJID32BIT] = "projid32bit",
> + [I_SPINODES] = "sparse",
> + },
> + .parser = inode_config_parser,
> + },
> + {
> + .name = "log",
> + .subopts = {
> + [L_LAZYSBCNTR] = "lazy-count",
> + },
> + .parser = log_config_parser,
> + },
> + {
> + .name = "naming",
> + .subopts = {
> + [N_FTYPE] = "ftype",
> + },
> + .parser = naming_config_parser,
> + },
> + {
> + .name = "rtdev",
> + .subopts = {
> + [R_NOALIGN] = "noalign",
> + },
> + .parser = rtdev_config_parser,
> + },
> + {
> + .name = "metadata",
> + .subopts = {
> + [M_CRC] = "crc",
> + [M_FINOBT] = "finobt",
> + [M_RMAPBT] = "rmapbt",
> + [M_REFLINK] = "reflink",
> + },
> + .parser = metadata_config_parser,
> + },
> +};
> +
> +static struct confopts *
> +get_confopts(
> + const char *section)
> +{
> + unsigned int i;
> + struct confopts *opts;
> +
> + for (i=0; i < ARRAY_SIZE(confopts_tab); i++) {
> + opts = &confopts_tab[i];
> + if (!opts)
> + return NULL;
> + if (strcmp(opts->name, section) == 0) {
> + return opts;
> + }
> + }
> + return NULL;
> +}
> +
> +enum parse_line_type {
> + PARSE_COMMENT = 0,
> + PARSE_EMPTY,
> + PARSE_SECTION,
> + PARSE_TAG_VALUE,
> + PARSE_INVALID,
> + PARSE_EOF,
> +};
> +
> +static bool
> +isempty(
> + const char *line,
> + ssize_t linelen)
> +{
> + ssize_t i = 0;
> + char p;
> +
> + while (i != linelen) {
> + p = line[i];
> + i++;
> +
> + /* tab or space */
> + if (isblank(p))
> + continue;
> + else
> + return false;
> + }
> +
> + return true;
> +}
> +
> +static bool
> +iscomment(
> + const char *line,
> + ssize_t linelen)
> +{
> + ssize_t i = 0;
> + char p;
> +
> + while (i != linelen) {
> + p = line[i];
> + i++;
> +
> + /* tab or space */
> + if (isblank(p))
> + continue;
> +
> + if (p == '#')
> + return true;
> +
> + return false;
> + }
> +
> + return false;
> +}
> +
> +static int
> +parse_line_section(
> + const char *line,
> + char **tag)
> +{
> + return sscanf(line, " [%m[^]]]", tag);
> +}
> +
> +static int
> +parse_line_tag_value(
> + const char *line,
> + char **tag,
> + uint64_t *value)
> +{
> + return sscanf(line, " %m[^ \t=]"
> + " = "
> + "%lu ",
> + tag, value);
> +}
> +
> +static enum parse_line_type
> +parse_get_line_type(
> + const char *line,
> + ssize_t linelen,
> + char **tag,
> + uint64_t *value)
> +{
> + int ret;
> + uint64_t u64_value;
> +
> + if (isempty(line, linelen))
> + return PARSE_EMPTY;
> +
> + if (iscomment(line, linelen))
> + return PARSE_COMMENT;
> +
> + ret = parse_line_section(line, tag);
> + if (ret == 1)
> + return PARSE_SECTION;
> +
> + if (ret == EOF)
> + return PARSE_EOF;
> +
> + ret = parse_line_tag_value(line, tag, &u64_value);
> + if (ret == 2) {
> + *value = u64_value;
> +
> + return PARSE_TAG_VALUE;
> + }
> +
> + if (ret == EOF)
> + return PARSE_EOF;
> +
> + return PARSE_INVALID;
> +}
> +
> +static int
> +parse_config_stream(
> + struct mkfs_default_params *dft,
> + const char *config_file,
> + FILE *fp)
> +{
> + int ret;
> + char *line = NULL;
> + ssize_t linelen;
> + size_t len = 0, lineno = 0;
> + uint64_t value;
> + enum parse_line_type parse_type;
> + struct confopts *confopt = NULL;
> + int subopt;
> +
> + while ((linelen = getline(&line, &len, fp)) != -1) {
> + char *ignore_value;
> + char *p, *tag = NULL;
> +
> + lineno++;
> +
> + /*
> + * tag is allocated for us by scanf(), it must freed only on any
> + * successful parse of a section or tag-value pair.
> + */
> + parse_type = parse_get_line_type(line, linelen, &tag, &value);
> +
> + switch (parse_type) {
> + case PARSE_EMPTY:
> + case PARSE_COMMENT:
> + /* Nothing tag to free for these */
> + continue;
> + case PARSE_EOF:
> + break;
> + case PARSE_INVALID:
> + ret = EINVAL;
> + fprintf(stderr, _("Invalid line %s:%zu : %s\n"),
> + config_file, lineno, line);
> + goto out;
> + case PARSE_SECTION:
> + confopt = get_confopts(tag);
> + if (!confopt) {
> + ret = EINVAL;
> + fprintf(stderr, _("Invalid section on line %s:%zu : %s\n"),
> + config_file, lineno, tag);
> + free(tag);
> + goto out;
> + }
> + if (!confopt->subopts) {
> + ret = EINVAL;
> + fprintf(stderr, _("Section not yet supported on line %s:%zu : %s\n"),
> + config_file, lineno, tag);
> + free(tag);
> + goto out;
> + }
> + if (confopt->seen) {
> + ret = EINVAL;
> + fprintf(stderr, _("Section '%s' respecified\n"),
> + tag);
> + free(tag);
> + goto out;
> + }
> + confopt->seen = true;
> + free(tag);
> + break;
> + case PARSE_TAG_VALUE:
> + if (!confopt) {
> + ret = EINVAL;
> + fprintf(stderr, _("No section specified yet on line %s:%zu : %s\n"),
> + config_file, lineno, line);
> + free(tag);
> + goto out;
> + }
> +
> + /*
> + * We re-use the line buffer allocated by getline(),
> + * however line must be kept pointing to its original
> + * value to free it later. A separate pointer is needed
> + * as getsubopt() will otherwise muck with the value
> + * passed.
> + */
> + p = line;
> +
> + /*
> + * Trims white spaces. getsubopt() does not grok
> + * white space, it would fail otherwise.
> + */
> + snprintf(p, len, "%s=%lu", tag, value);
> +
> + /* Not needed anymore */
> + free(tag);
> +
> + /*
> + * We only use getsubopt() to validate the possible
> + * subopt, we already parsed the value and its already
> + * in a more preferred data type.
> + */
> + subopt = getsubopt(&p, (char **) confopt->subopts,
> + &ignore_value);
> +
> + ret = confopt->parser(dft, subopt, value);
> + if (ret) {
> + fprintf(stderr, _("Error parsine line %s:%zu : %s\n"),
> + config_file, lineno, line);
> + goto out;
> + }
> +
> + break;
> + }
> + }
> +out:
> + /* We must free even if getline() failed */
> + free(line);
> + return ret;
> +}
> +
> +static const char *conf_paths[] = {
> + ".",
> + MKFS_XFS_CONF_DIR,
> +};
> +
> +/*
> + * If the file is not found -1 is returned and errno set. Otherwise
> + * the file descriptor is returned.
> + */
> +int
> +open_cli_config(
> + char *cli_config_file,
> + char **fpath)
> +{
> + int fd, len;
> + char *final_path = NULL;
> + char *relative_path= NULL;
> + unsigned int i;
> +
> + if (strlen(cli_config_file) > 2) {
> + if (cli_config_file[0] == '.' && cli_config_file[1] == '/')
> + final_path = cli_config_file;
> + else if (cli_config_file[0] == '.' && cli_config_file[1] == '.')
> + final_path = cli_config_file;
> + else if (cli_config_file[0] == '/')
> + final_path = cli_config_file;
> + else
> + relative_path = cli_config_file;
> + } else if (strlen(cli_config_file) == 1) {
> + if (cli_config_file[0] == '.' || cli_config_file[0] == '/') {
> + errno = EINVAL;
> + return -1;
> + } else
> + relative_path = cli_config_file;
> + }
> +
> + if (final_path) {
> + fd = open(final_path, O_RDONLY);
> + if (fd >= 0)
> + memcpy(*fpath, final_path, strlen(final_path));
> + return fd;
> + }
> +
> + /* We finally know the path is relative but just to be sure */
> + if (!relative_path) {
> + errno = ENXIO;
> + return -1;
> + }
> +
> + for (i = 0; i < ARRAY_SIZE(conf_paths); i++) {
> + memset(*fpath, 0, PATH_MAX);
> + /*
> + * For current directory evaluation, skip concatenating the
> + * ./ from the file passed. We only concatenate for the other
> + * paths we look up on.
> + */
> + if (i == 0)
> + memcpy(*fpath, relative_path, strlen(relative_path));
> + else {
> + len = snprintf(*fpath, PATH_MAX, "%s/%s", conf_paths[i],
> + relative_path);
> + /* Indicates truncation */
> + if (len >= PATH_MAX) {
> + errno = ENAMETOOLONG;
> + return -1;
> + }
> + }
> + fd = open(*fpath, O_RDONLY);
> + if (fd < 0)
> + continue;
> + return fd;
> + }
> +
> + errno = ENOENT;
> + return -1;
> +}
> +
> +/*
> + * This is only called *iff* there is a configuration file which we know we
> + * *must* parse.
> + *
> + * If default_fd is set and is a valid file descriptor then the configuration
> + * file passed is the system default configuraiton file, and we already know
> + * it exists. If default_fd is not set we assume we've been passed a
> + * configuration file from the command line and must it must exist, otherwise
> + * we have to error out.
> + */
> +int
> +parse_defaults_file(
> + struct mkfs_default_params *dft,
> + int default_fd,
> + char *config_file)
> +{
> + char *fpath;
> + int fd;
> + FILE *fp;
> + int ret;
> + struct stat sp;
> +
> + if (strlen(config_file) > PATH_MAX)
> + return ENAMETOOLONG;
> +
> + fpath = malloc(PATH_MAX);
> + if (!fpath)
> + return ENOMEM;
> + memset(fpath, 0, PATH_MAX);
> +
> + if (default_fd < 0) {
> + fd = open_cli_config(config_file, &fpath);
> + if (fd < 0) {
> + free(fpath);
> + return errno;
> + }
> + } else {
> + fd = default_fd;
> + memcpy(fpath, config_file, strlen(config_file));
> + }
> +
> + /*
> + * At this point we know we have a valid file descriptor and have
> + * figured out the path to the file used on fpath. Get the file stream
> + * and do a bit of sanity checks before parsing the file.
> + */
> +
> + fp = fdopen(fd, "r");
> + if (!fp) {
> + perror(fpath);
> + ret = errno;
> + goto out_close_fd;
> + }
> +
> + ret = fstat(fd, &sp);
> + if (ret) {
> + ret = errno;
> + fprintf(stderr, _("Could not fstat() config file: %s: %s\n"),
> + fpath, strerror(errno));
> + goto out;
> + }
> +
> + if (S_ISDIR(sp.st_mode)) {
> + ret = EBADF;
> + fprintf(stderr, _("Config file is a directory: %s\n"), fpath);
> + goto out;
> + }
> +
> + /* Anything beyond 1 MiB is kind of silly right now */
> + if (sp.st_size > 1 * 1024 * 1024) {
> + ret = E2BIG;
> + goto out;
> + }
> +
> + ret = parse_config_stream(dft, config_file, fp);
> + if (ret)
> + goto out;
> +
> + printf(_("config-file=%s\n"), fpath);
> +
> +out:
> + fclose(fp);
> +out_close_fd:
> + close(fd);
> + free(fpath);
> + return ret;
> +}
> diff --git a/mkfs/config.h b/mkfs/config.h
> index e5ea968e2d65..0f429d9b7fd7 100644
> --- a/mkfs/config.h
> +++ b/mkfs/config.h
> @@ -19,6 +19,8 @@
> #ifndef _XFS_MKFS_CONFIG_H
> #define _XFS_MKFS_CONFIG_H
>
> +#define MKFS_XFS_CONF_DIR ROOT_SYSCONFDIR "/mkfs.xfs.d"
> +
> struct fsxattr;
>
> /*
> @@ -29,7 +31,7 @@ struct fsxattr;
> * source can overriding the later source:
> *
> * o built-in defaults
> - * o configuration file (XXX)
> + * o configuration file
> * o command line
> *
> * These values are not used directly - they are inputs into the mkfs geometry
> @@ -75,4 +77,10 @@ struct mkfs_default_params {
> struct fsxattr fsx;
> };
>
> +int
> +parse_defaults_file(
> + struct mkfs_default_params *dft,
> + int default_fd,
> + char *config_file);
> +
> #endif /* _XFS_MKFS_CONFIG_H */
> diff --git a/mkfs/xfs_mkfs.c b/mkfs/xfs_mkfs.c
> index 4664e507afbf..81ef7ab584ed 100644
> --- a/mkfs/xfs_mkfs.c
> +++ b/mkfs/xfs_mkfs.c
> @@ -3743,6 +3743,11 @@ main(
> .nortalign = false,
> },
> };
> + char *default_config = MKFS_XFS_CONF_DIR "/default";
> + char *cli_config_file = NULL;
> + char *config_file = NULL;
> + int default_fd = -1;
> + int ret;
>
> platform_uuid_generate(&cli.uuid);
> progname = basename(argv[0]);
> @@ -3751,25 +3756,74 @@ main(
> textdomain(PACKAGE);
>
> /*
> - * TODO: Sourcing defaults from a config file
> - *
> * Before anything else, see if there's a config file with different
> - * defaults. If a file exists in <package location>, read in the new
> - * default values and overwrite them in the &dft structure. This way the
> - * new defaults will apply before we parse the CLI, and the CLI will
> - * still be able to override them. When more than one source is
> - * implemented, emit a message to indicate where the defaults being
> - * used came from.
> + * defaults. If the CLI specified a full path we use and require that.
> + * If a relative path was provided on the CLI we search the allowed
> + * search paths for the file. If no config file was specified on the
> + * CLI we will look for MKFS_XFS_CONF_DIR/default and use that if
> + * present, however this file is optional.
> *
> - * printf(_("Default configuration sourced from %s\n"), dft.source);
> + * If a configuration file is found we use it to help overwrite default
> + * values in the &dft structure. This way the new defaults will apply
> + * before we parse the CLI, and the user will still be able to override
> + * them through the CLI.
> + */
> +
> + /*
> + * Pull config line options from command line
> */
> + while ((c = getopt(argc, argv, "b:c:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
> + switch (c) {
> + case 'c':
> + if (cli_config_file) {
> + fprintf(stderr, _("respecification of configuration not allowed\n"));
> + exit(1);
> + }
> + cli_config_file = optarg;
> + dft.source = _("command line");
> + break;
> + default:
> + continue;
> + }
> + }
> +
> + if (cli_config_file)
> + config_file = cli_config_file;
> + else {
> + default_fd = open(default_config, O_RDONLY);
> + if (default_fd >= 0) {
> + dft.source = _("system default configuration file");
> + config_file = default_config;
> + }
> + }
> +
> + if (config_file) {
> + /* If default_fd is set it will be closed for us */
> + ret = parse_defaults_file(&dft, default_fd, config_file);
> + if (ret) {
> + fprintf(stderr, _("Error parsing %s config file: %s : %s\n"),
> + dft.source, config_file,
> + strerror(ret));
> + exit(1);
> + }
> + }
>
> - /* copy new defaults into CLI parsing structure */
> + printf(_("Default configuration sourced from %s\n"), dft.source);
> +
> + /*
> + * Done parsing defaults now, so memcpy defaults into CLI
> + * structure, reset getopt and start parsing CLI options
> + */
> memcpy(&cli.sb_feat, &dft.sb_feat, sizeof(cli.sb_feat));
> memcpy(&cli.fsx, &dft.fsx, sizeof(cli.fsx));
>
> - while ((c = getopt(argc, argv, "b:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
> + platform_getoptreset();
> +
> + while ((c = getopt(argc, argv, "b:c:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
> switch (c) {
> + case 'c':
> + /* already validated and parsed, ignore */
> + break;
> case 'C':
> case 'f':
> force_overwrite = 1;
> --
> 2.16.3
>
> --
> 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
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH 3.5/4] mkfs.xfs: document defaults config file details
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
` (5 preceding siblings ...)
2018-05-30 16:06 ` Darrick J. Wong
@ 2018-05-30 18:10 ` Eric Sandeen
2018-05-30 18:30 ` Darrick J. Wong
2018-05-30 20:51 ` [PATCH 3.5/4 V2] " Eric Sandeen
2018-05-30 21:05 ` [PATCH 3.7/4] mkfs.xfs.8: parameterize sysconfdir Eric Sandeen
7 siblings, 2 replies; 21+ messages in thread
From: Eric Sandeen @ 2018-05-30 18:10 UTC (permalink / raw)
To: Luis R. Rodriguez, linux-xfs
Cc: darrick.wong, jack, jeffm, okurz, lpechacek, jtulak
Here's my stab at documenting the defaults/config file behavior.
I've condensed it down to just mkfs.xfs 8 changes, and tried to
make it more concise. I'll let people bikeshed this while I work
out a proper way to substitute %sysconfdir% in the text.
Note that what I describe in terms of bare filename behavior doesn't
match the code today - I think we still need to reach a consensus
on whether a bare filename looks in $PWD first, or only in the
/etc/ path. (I'd prefer the latter, I think, but still slightly
wobbly on this)
Signed-off-by: Eric Sandeen <sandeen@redhat.com>
---
diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8
index 4b8c78c..64853cc 100644
--- a/man/man8/mkfs.xfs.8
+++ b/man/man8/mkfs.xfs.8
@@ -4,6 +4,10 @@ mkfs.xfs \- construct an XFS filesystem
.SH SYNOPSIS
.B mkfs.xfs
[
+.B \-c
+.I configuration
+] [
+[
.B \-b
.I block_size_options
] [
@@ -121,8 +125,38 @@ 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/defaults
+exists, it will be parsed to override built-in defaults as specified in the
+.B defaults
+file, 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 descibed 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/defaults
+to override selected built-in parameter defaults.
+If
+.B configuration
+is a bare filename, it will be searched in the
+.B /etc/xfs/mkfs/
+directory. If
+.B configuration
+is a full pathname or a relative pathname starting with
+.BR \'./\' " or " \'../\'
+then that explicit path to the configuration file will be used.
+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
@@ -920,6 +954,55 @@ 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 follow a simple ini-style format as shown below.
+Available options consist of a small 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),
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH 3.5/4] mkfs.xfs: document defaults config file details
2018-05-30 18:10 ` [PATCH 3.5/4] mkfs.xfs: document defaults config file details Eric Sandeen
@ 2018-05-30 18:30 ` Darrick J. Wong
2018-05-30 18:37 ` Eric Sandeen
2018-05-30 20:51 ` [PATCH 3.5/4 V2] " Eric Sandeen
1 sibling, 1 reply; 21+ messages in thread
From: Darrick J. Wong @ 2018-05-30 18:30 UTC (permalink / raw)
To: Eric Sandeen
Cc: Luis R. Rodriguez, linux-xfs, jack, jeffm, okurz, lpechacek, jtulak
On Wed, May 30, 2018 at 01:10:48PM -0500, Eric Sandeen wrote:
> Here's my stab at documenting the defaults/config file behavior.
>
> I've condensed it down to just mkfs.xfs 8 changes, and tried to
> make it more concise. I'll let people bikeshed this while I work
> out a proper way to substitute %sysconfdir% in the text.
>
> Note that what I describe in terms of bare filename behavior doesn't
> match the code today - I think we still need to reach a consensus
> on whether a bare filename looks in $PWD first, or only in the
> /etc/ path. (I'd prefer the latter, I think, but still slightly
> wobbly on this)
>
> Signed-off-by: Eric Sandeen <sandeen@redhat.com>
> ---
>
> diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8
> index 4b8c78c..64853cc 100644
> --- a/man/man8/mkfs.xfs.8
> +++ b/man/man8/mkfs.xfs.8
> @@ -4,6 +4,10 @@ mkfs.xfs \- construct an XFS filesystem
> .SH SYNOPSIS
> .B mkfs.xfs
> [
> +.B \-c
> +.I configuration
> +] [
> +[
> .B \-b
> .I block_size_options
> ] [
> @@ -121,8 +125,38 @@ 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.
Yay, each sentence starts on its own line, like regular manpages...
> +If the file
> +.B /etc/xfs/mkfs/defaults
@sysconfdir@/xfs/mkfs/defaults ?
> +exists, it will be parsed to override built-in defaults as specified in the
> +.B defaults
> +file, and the defaults described in sections below may no longer apply.
I think "as specified in the defaults file" is redundant? We already
said that we were parsing the defaults file...
> +.PP
> +The
> +.B \-c
> +option may also be used to specify an alternate configuration file
> +as descibed in the OPTIONS section.
...described... (typo)
> .SH OPTIONS
> .TP
> +.BI \-c " configuration"
> +This option may be used to specify a configuration file other than
> +.B /etc/xfs/mkfs/defaults
@sysconfdir@/xfs/mkfs/defaults
> +to override selected built-in parameter defaults.
> +If
> +.B configuration
> +is a bare filename, it will be searched in the
What is a bare filename?
> +.B /etc/xfs/mkfs/
@sysco.... yeah.
> +directory. If
Start new sentence on new line?
> +.B configuration
> +is a full pathname or a relative pathname starting with
Ugh, I still find this a little contorted...
"If $configuration is an absolute pathname, then that path will be used
to find the configuration file.
"Otherwise, if $configuration contains at least one slash, it will be
treated as a pathname relative to the current working directory.
"If $configuration contains no slashes, first the current working
directory and then @sysconfdir@/xfs/mkfs/ will be searched for that
file."
> +.BR \'./\' " or " \'../\'
> +then that explicit path to the configuration file will be used.
> +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
> @@ -920,6 +954,55 @@ 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 follow a simple ini-style format as shown below.
"...must follow the simple ini-style format..."
> +Available options consist of a small 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
Probably we need to add a build-time helper that reads in the default
config and spits out an ini file which can then be rolled into this
manpage and/or used to generate a totally commented out defaults file.
--D
> +.PP
> .SH SEE ALSO
> .BR xfs (5),
> .BR mkfs (8),
>
> --
> 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
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 3.5/4] mkfs.xfs: document defaults config file details
2018-05-30 18:30 ` Darrick J. Wong
@ 2018-05-30 18:37 ` Eric Sandeen
0 siblings, 0 replies; 21+ messages in thread
From: Eric Sandeen @ 2018-05-30 18:37 UTC (permalink / raw)
To: Darrick J. Wong
Cc: Luis R. Rodriguez, linux-xfs, jack, jeffm, okurz, lpechacek, jtulak
On 5/30/18 1:30 PM, Darrick J. Wong wrote:
> On Wed, May 30, 2018 at 01:10:48PM -0500, Eric Sandeen wrote:
>> Here's my stab at documenting the defaults/config file behavior.
>>
>> I've condensed it down to just mkfs.xfs 8 changes, and tried to
>> make it more concise. I'll let people bikeshed this while I work
>> out a proper way to substitute %sysconfdir% in the text.
>>
>> Note that what I describe in terms of bare filename behavior doesn't
>> match the code today - I think we still need to reach a consensus
>> on whether a bare filename looks in $PWD first, or only in the
>> /etc/ path. (I'd prefer the latter, I think, but still slightly
>> wobbly on this)
>>
>> Signed-off-by: Eric Sandeen <sandeen@redhat.com>
>> ---
>>
>> diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8
>> index 4b8c78c..64853cc 100644
>> --- a/man/man8/mkfs.xfs.8
>> +++ b/man/man8/mkfs.xfs.8
>> @@ -4,6 +4,10 @@ mkfs.xfs \- construct an XFS filesystem
>> .SH SYNOPSIS
>> .B mkfs.xfs
>> [
>> +.B \-c
>> +.I configuration
>> +] [
>> +[
>> .B \-b
>> .I block_size_options
>> ] [
>> @@ -121,8 +125,38 @@ 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.
>
> Yay, each sentence starts on its own line, like regular manpages...
>
>> +If the file
>> +.B /etc/xfs/mkfs/defaults
>
> @sysconfdir@/xfs/mkfs/defaults ?
"I'll let people bikeshed this while I work
out a proper way to substitute %sysconfdir% in the text." ;)
>> +exists, it will be parsed to override built-in defaults as specified in the
>> +.B defaults
>> +file, and the defaults described in sections below may no longer apply.
>
> I think "as specified in the defaults file" is redundant? We already
> said that we were parsing the defaults file...
sure
>> +.PP
>> +The
>> +.B \-c
>> +option may also be used to specify an alternate configuration file
>> +as descibed in the OPTIONS section.
>
> ...described... (typo)
thx
>> .SH OPTIONS
>> .TP
>> +.BI \-c " configuration"
>> +This option may be used to specify a configuration file other than
>> +.B /etc/xfs/mkfs/defaults
>
> @sysconfdir@/xfs/mkfs/defaults
grr ;)
>> +to override selected built-in parameter defaults.
>> +If
>> +.B configuration
>> +is a bare filename, it will be searched in the
>
> What is a bare filename?
how would you describe a collection of characters that contains
not absolute or relative path components?
>> +.B /etc/xfs/mkfs/
>
> @sysco.... yeah.
>
>> +directory. If
>
> Start new sentence on new line?
k
>> +.B configuration
>> +is a full pathname or a relative pathname starting with
>
> Ugh, I still find this a little contorted...
>
> "If $configuration is an absolute pathname, then that path will be used
> to find the configuration file.
>
> "Otherwise, if $configuration contains at least one slash, it will be
> treated as a pathname relative to the current working directory.
mkfs.xfs -c foo/bar/baz ?
/me wonders what that does today
> "If $configuration contains no slashes, first the current working
> directory and then @sysconfdir@/xfs/mkfs/ will be searched for that
> file."
if we want that.
>> +.BR \'./\' " or " \'../\'
>> +then that explicit path to the configuration file will be used.
>> +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
>> @@ -920,6 +954,55 @@ 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 follow a simple ini-style format as shown below.
>
> "...must follow the simple ini-style format..."
i suppose. bad grammar from me in any case.
>> +Available options consist of a small 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
>
> Probably we need to add a build-time helper that reads in the default
> config and spits out an ini file which can then be rolled into this
> manpage and/or used to generate a totally commented out defaults file.
Eventually.
-Eric
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH 3.5/4 V2] mkfs.xfs: document defaults config file details
2018-05-30 18:10 ` [PATCH 3.5/4] mkfs.xfs: document defaults config file details Eric Sandeen
2018-05-30 18:30 ` Darrick J. Wong
@ 2018-05-30 20:51 ` Eric Sandeen
2018-05-30 22:08 ` Darrick J. Wong
1 sibling, 1 reply; 21+ messages in thread
From: Eric Sandeen @ 2018-05-30 20:51 UTC (permalink / raw)
To: Luis R. Rodriguez, linux-xfs
Cc: darrick.wong, jack, jeffm, okurz, lpechacek, jtulak
Document the mkfs default config file behavior.
Signed-off-by: Eric Sandeen <sandeen@redhat.com>
---
V2: implement most of darrick's suggestions
diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8
index 4b8c78c..ca8c775 100644
--- a/man/man8/mkfs.xfs.8
+++ b/man/man8/mkfs.xfs.8
@@ -4,6 +4,10 @@ mkfs.xfs \- construct an XFS filesystem
.SH SYNOPSIS
.B mkfs.xfs
[
+.B \-c
+.I configuration
+] [
+[
.B \-b
.I block_size_options
] [
@@ -121,8 +125,41 @@ 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
@@ -920,6 +957,55 @@ 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),
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [PATCH 3.7/4] mkfs.xfs.8: parameterize sysconfdir
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
` (6 preceding siblings ...)
2018-05-30 18:10 ` [PATCH 3.5/4] mkfs.xfs: document defaults config file details Eric Sandeen
@ 2018-05-30 21:05 ` Eric Sandeen
2018-05-30 22:10 ` Darrick J. Wong
7 siblings, 1 reply; 21+ messages in thread
From: Eric Sandeen @ 2018-05-30 21:05 UTC (permalink / raw)
To: Luis R. Rodriguez, linux-xfs
Cc: darrick.wong, jack, jeffm, okurz, lpechacek, jtulak
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 <sandeen@redhat.com>
---
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.
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [PATCH 3.5/4 V2] mkfs.xfs: document defaults config file details
2018-05-30 20:51 ` [PATCH 3.5/4 V2] " Eric Sandeen
@ 2018-05-30 22:08 ` Darrick J. Wong
0 siblings, 0 replies; 21+ messages in thread
From: Darrick J. Wong @ 2018-05-30 22:08 UTC (permalink / raw)
To: Eric Sandeen
Cc: Luis R. Rodriguez, linux-xfs, jack, jeffm, okurz, lpechacek, jtulak
On Wed, May 30, 2018 at 03:51:48PM -0500, Eric Sandeen wrote:
> Document the mkfs default config file behavior.
>
> Signed-off-by: Eric Sandeen <sandeen@redhat.com>
> ---
>
> V2: implement most of darrick's suggestions
>
> diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8
> index 4b8c78c..ca8c775 100644
> --- a/man/man8/mkfs.xfs.8
> +++ b/man/man8/mkfs.xfs.8
> @@ -4,6 +4,10 @@ mkfs.xfs \- construct an XFS filesystem
> .SH SYNOPSIS
> .B mkfs.xfs
> [
> +.B \-c
> +.I configuration
> +] [
> +[
> .B \-b
> .I block_size_options
> ] [
> @@ -121,8 +125,41 @@ 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
> @@ -920,6 +957,55 @@ 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
sparse=1
Otherwise this looks ok provided we ensure the code does what the docs
say.
Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>
--D
> +.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),
>
>
> --
> 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
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH 3.7/4] mkfs.xfs.8: parameterize sysconfdir
2018-05-30 21:05 ` [PATCH 3.7/4] mkfs.xfs.8: parameterize sysconfdir Eric Sandeen
@ 2018-05-30 22:10 ` Darrick J. Wong
0 siblings, 0 replies; 21+ messages in thread
From: Darrick J. Wong @ 2018-05-30 22:10 UTC (permalink / raw)
To: Eric Sandeen
Cc: Luis R. Rodriguez, linux-xfs, jack, jeffm, okurz, lpechacek, jtulak
On Wed, May 30, 2018 at 04:05:47PM -0500, Eric Sandeen wrote:
> 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 <sandeen@redhat.com>
Looks ok modulo comments in the 3.5/4 patch.
Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>
--D
> ---
>
> 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.
>
> --
> 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
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser
2018-05-30 3:33 ` Dave Chinner
@ 2018-06-01 21:13 ` Luis R. Rodriguez
0 siblings, 0 replies; 21+ messages in thread
From: Luis R. Rodriguez @ 2018-06-01 21:13 UTC (permalink / raw)
To: Dave Chinner
Cc: Luis R. Rodriguez, sandeen, linux-xfs, darrick.wong, jack, jeffm,
okurz, lpechacek, jtulak
On Wed, May 30, 2018 at 01:33:29PM +1000, Dave Chinner wrote:
> On Tue, May 29, 2018 at 03:06:02PM -0700, Luis R. Rodriguez wrote:
> > You may want to stick to specific set of configuration options when
> > creating filesystems with mkfs.xfs -- sometimes due to pure technical
> > reasons, but some other times to ensure systems remain compatible as
> > new features are introduced with older kernels, or if you always want
> > to take advantage of some new feature which would otherwise typically
> > be disruptive.
> >
> > This adds support for parsing a configuration file to override defaults
> > parameters to be used for mkfs.xfs.
> .....
> > +static int
> > +data_config_parser(
> > + struct mkfs_default_params *dft,
> > + int psubopt,
> > + uint64_t value)
> > +{
> > + enum data_subopts subopt = psubopt;
>
> This is unnecessary. enums and ints are the same thing when it comes
> to comparisons.
Yes but I have a reason to use enum: if you expand on an enum entry
for a subopt, the compiler will warn if the respective subopt parser
fails to have an entry for it. This is possible when and if you have
no default.
This believe this is purely a bikeshed coding preference style, but its what I
prefer. Let me know what you prefer.
> > +
> > + switch (subopt) {
> > + case D_NOALIGN:
> > + dft->sb_feat.nodalign = value;
> > + return 0;
> > + }
> > + return EINVAL;
>
> Negative errors, please. All xfsprogs use negative error numbers
> like the kernel now, so please don't take us back to the bad old
> days of having to change error signs depending on where the error
> came from....
OK! I used positive values as we want these errors then to be described
later with strerror(ret) but right now this return value comes from
what parse_defaults_file() returns, I suppose I can just set errno to the
positive values and return -1 or whatever. So the caller as Darrick
suggests:
if (parse_defaults_file()) {
fprintf(stderr, _(fError parsing %s config file: %s : %s\n")
dft.source, config_file, strerror(ret));
...
}
> Actually, I'm surprised that the compiler isn't complaining about
> not having a default statement in the switch statement.
Its not complaining as *all* the enums for each type are addressed :)
> Can they be
> structured like the cli options to avoid this in future?
>
> switch (subopt) {
> case D_NOALIGN:
> .....
> break;
> default:
> return -EINVAL;
> }
> return 0;
If we do that we'd loose out on the compiler feature I described above.
Let me know your preference.
> > +enum parse_line_type {
> > + PARSE_COMMENT = 0,
> > + PARSE_EMPTY,
> > + PARSE_SECTION,
> > + PARSE_TAG_VALUE,
> > + PARSE_INVALID,
> > + PARSE_EOF,
> > +};
> > +
> > +static bool
> > +isempty(
> > + const char *line,
> > + ssize_t linelen)
> > +{
> > + ssize_t i = 0;
> > + char p;
> > +
> > + while (i != linelen) {
>
> while (i < linelen) {
amended
>
> > + p = line[i];
> > + i++;
>
> p = line[i++];
amended
>
> > +
> > + /* tab or space */
> > + if (isblank(p))
> > + continue;
> > + else
> > + return false;
> > + }
>
> if (!isblank(p))
> return false;
amended
> }
> > +
> > + return true;
> > +}
> > +
> > +static bool
> > +iscomment(
> > + const char *line,
> > + ssize_t linelen)
> > +{
> > + ssize_t i = 0;
> > + char p;
> > +
> > + while (i != linelen) {
> > + p = line[i];
> > + i++;
> > +
> > + /* tab or space */
> > + if (isblank(p))
> > + continue;
> > +
> > + if (p == '#')
> > + return true;
> > +
> > + return false;
> > + }
> > +
> > + return false;
> > +}
> > +
> > +static int
> > +parse_line_section(
> > + const char *line,
> > + char **tag)
> > +{
> > + return sscanf(line, " [%m[^]]]", tag);
> > +}
> > +
> > +static int
> > +parse_line_tag_value(
> > + const char *line,
> > + char **tag,
> > + uint64_t *value)
> > +{
> > + return sscanf(line, " %m[^ \t=]"
> > + " = "
> > + "%lu ",
> > + tag, value);
> > +}
>
> %lu won't match uint64_t on 32 bit builds. Doesn't this need to be
> PRIu64 to be correct?
PRIu64 indeed seems to be the right thing to use for uint64_t for c99.
> Hmmm, I thought the compiler checked this
> format stuff and threw warnings when you get it wrong?
I get no compiler errors.
> Also, I'm not sure there's any value to these single line functions.
> Why not just call them directly in the next function?
Because they are descriptive and saves us the comment. You seem to prefer
to have the comment so I will use that.
> > +
> > +static enum parse_line_type
> > +parse_get_line_type(
> > + const char *line,
> > + ssize_t linelen,
> > + char **tag,
> > + uint64_t *value)
> > +{
> > + int ret;
> > + uint64_t u64_value;
> > +
> > + if (isempty(line, linelen))
> > + return PARSE_EMPTY;
> > +
> > + if (iscomment(line, linelen))
> > + return PARSE_COMMENT;
> > +
> > + ret = parse_line_section(line, tag);
> > + if (ret == 1)
> > + return PARSE_SECTION;
>
> i.e.
> /* check if we have a section header */
> ret = sscanf(line, " [%m[^]]]", tag);
> if (ret == 1)
> return PARSE_SECTION;
OK
> > +
> > + if (ret == EOF)
> > + return PARSE_EOF;
> > +
> > + ret = parse_line_tag_value(line, tag, &u64_value);
> > + if (ret == 2) {
> > + *value = u64_value;
> > +
> > + return PARSE_TAG_VALUE;
> > + }
>
> /* should be a "tag = value" config option */
> ret = sscanf(line, " %m[^ \t=] = %" PRIu64 " ", tag, value);
> if (ret == 2)
> return PARSE_TAG_VALUE;
Sure.
> > +
> > + if (ret == EOF)
> > + return PARSE_EOF;
> > +
> > + return PARSE_INVALID;
> > +}
> > +
> > +static int
> > +parse_config_stream(
> > + struct mkfs_default_params *dft,
> > + const char *config_file,
> > + FILE *fp)
> > +{
> > + int ret;
> > + char *line = NULL;
> > + ssize_t linelen;
> > + size_t len = 0, lineno = 0;
> > + uint64_t value;
> > + enum parse_line_type parse_type;
> > + struct confopts *confopt = NULL;
> > + int subopt;
> > +
> > + while ((linelen = getline(&line, &len, fp)) != -1) {
> > + char *ignore_value;
> > + char *p, *tag = NULL;
> > +
> > + lineno++;
> > +
> > + /*
> > + * tag is allocated for us by scanf(), it must freed only on any
> > + * successful parse of a section or tag-value pair.
> > + */
> > + parse_type = parse_get_line_type(line, linelen, &tag, &value);
> > +
> > + switch (parse_type) {
> > + case PARSE_EMPTY:
> > + case PARSE_COMMENT:
> > + /* Nothing tag to free for these */
> > + continue;
> > + case PARSE_EOF:
> > + break;
> > + case PARSE_INVALID:
> > + ret = EINVAL;
>
> Negative errors.
Alright.
> > + fprintf(stderr, _("Invalid line %s:%zu : %s\n"),
> > + config_file, lineno, line);
> > + goto out;
> > + case PARSE_SECTION:
> > + confopt = get_confopts(tag);
> > + if (!confopt) {
> > + ret = EINVAL;
> > + fprintf(stderr, _("Invalid section on line %s:%zu : %s\n"),
> > + config_file, lineno, tag);
> > + free(tag);
> > + goto out;
>
> goto out_free_tag;
> ....
> out_free_tag:
> free(tag);
> ret = -EINVAL;
> goto out;
>
> Same for all thers others.
OK.
> > + }
> > + if (!confopt->subopts) {
> > + ret = EINVAL;
> > + fprintf(stderr, _("Section not yet supported on line %s:%zu : %s\n"),
> > + config_file, lineno, tag);
> > + free(tag);
> > + goto out;
> > + }
> > + if (confopt->seen) {
> > + ret = EINVAL;
> > + fprintf(stderr, _("Section '%s' respecified\n"),
> > + tag);
> > + free(tag);
> > + goto out;
> > + }
> > + confopt->seen = true;
> > + free(tag);
> > + break;
> > + case PARSE_TAG_VALUE:
> > + if (!confopt) {
> > + ret = EINVAL;
> > + fprintf(stderr, _("No section specified yet on line %s:%zu : %s\n"),
> > + config_file, lineno, line);
> > + free(tag);
> > + goto out;
> > + }
> > +
> > + /*
> > + * We re-use the line buffer allocated by getline(),
> > + * however line must be kept pointing to its original
> > + * value to free it later. A separate pointer is needed
> > + * as getsubopt() will otherwise muck with the value
> > + * passed.
> > + */
> > + p = line;
> > +
> > + /*
> > + * Trims white spaces. getsubopt() does not grok
> > + * white space, it would fail otherwise.
> > + */
> > + snprintf(p, len, "%s=%lu", tag, value);
> > +
> > + /* Not needed anymore */
> > + free(tag);
> > +
> > + /*
> > + * We only use getsubopt() to validate the possible
> > + * subopt, we already parsed the value and its already
> > + * in a more preferred data type.
> > + */
> > + subopt = getsubopt(&p, (char **) confopt->subopts,
> > + &ignore_value);
>
> This hoop-jumping cruft can all be replaced with a simple loop that
> just compares the tag to the subopts array:
>
> for (i = 0; i < MAX_SUBOPTS; i++) {
> if (!confopt->subopts[i]) {
On the kernel it would be but on userspace this could be uninitialized?
> /* option not found, error out */
> goto out_free_tag;
> }
>
> if (strcmp(confopt->subopts[i], tag) == 0)
> break;
> }
> free(tag);
>
> ret = confopt->parser(dft, i, value);
> > + if (ret) {
> > + fprintf(stderr, _("Error parsine line %s:%zu : %s\n"),
> > + config_file, lineno, line);
> > + goto out;
> > + }
> > +
> > + break;
> > + }
> > + }
> > +out:
> > + /* We must free even if getline() failed */
> > + free(line);
> > + return ret;
> > +}
> > +
> > +static const char *conf_paths[] = {
> > + ".",
> > + MKFS_XFS_CONF_DIR,
> > +};
> > +
> > +/*
> > + * If the file is not found -1 is returned and errno set. Otherwise
> > + * the file descriptor is returned.
> > + */
> > +int
> > +open_cli_config(
> > + char *cli_config_file,
> > + char **fpath)
> > +{
> > + int fd, len;
> > + char *final_path = NULL;
> > + char *relative_path= NULL;
> > + unsigned int i;
> > +
> > + if (strlen(cli_config_file) > 2) {
> > + if (cli_config_file[0] == '.' && cli_config_file[1] == '/')
> > + final_path = cli_config_file;
> > + else if (cli_config_file[0] == '.' && cli_config_file[1] == '.')
> > + final_path = cli_config_file;
> > + else if (cli_config_file[0] == '/')
> > + final_path = cli_config_file;
> > + else
> > + relative_path = cli_config_file;
> > + } else if (strlen(cli_config_file) == 1) {
> > + if (cli_config_file[0] == '.' || cli_config_file[0] == '/') {
> > + errno = EINVAL;
> > + return -1;
> > + } else
> > + relative_path = cli_config_file;
> > + }
>
> This seems somewhat complex, and it doesn't check what the target of
> the path is.
>
> fstatat(AT_FDCWD, fpath, &st, AT_SYMLINK_NOFOLLOW);
>
> will tell us if the file exists, it doesn't end in a symlink
> and it will resolve both both relative and absolute paths correctly.
>
> If it succeeds, then we can check that the path points to a regular
> file (and not, say, a block device) so that this sort of thing:
>
> [30/5/18 12:08] <sandeen> mkfs/mkfs.xfs -c /dev/sdb1
> [30/5/18 12:08] <sandeen> Invalid line /dev/sdb1:1 : XFSB
>
> Gives a sensible error before we get to parsing.
>
> If the file is found and isn't a regular file, then abort.
>
> If the file isn't found, then we need to ensure that we have been
> passed a name without any directory component as we are going to
> search the sysconf dir for that file. That's where basename(3) comes
> in - if the name returned by basename(3) doesn't match fpath, then
> there was a directory component in fpath, and we reject it and
> abort.
>
> Then we can open the sysconf directory w/ O_PATH|O_DIRECTORY, then
> do the same fstatat check and open it w/ openat():
>
> fstatat(dirfd, fpath, &st, AT_SYMLINK_NOFOLLOW);
> /* check return */
> openat(dirfd, fpath, O_NOFOLLOW, O_RDONLY);
>
> IOWs, I don't think we should be looking at just the first two
> characters of the supplied filename to determine the action to take,
> nor do i think we shoul dbe trying to resolve relative paths under
> the sysconf dir.
Alright, I'll give this a shot.
> > +/*
> > + * This is only called *iff* there is a configuration file which we know we
> > + * *must* parse.
> > + *
> > + * If default_fd is set and is a valid file descriptor then the configuration
> > + * file passed is the system default configuraiton file, and we already know
> > + * it exists. If default_fd is not set we assume we've been passed a
> > + * configuration file from the command line and must it must exist, otherwise
> > + * we have to error out.
> > + */
> > +int
> > +parse_defaults_file(
> > + struct mkfs_default_params *dft,
> > + int default_fd,
> > + char *config_file)
> > +{
> > + char *fpath;
> > + int fd;
> > + FILE *fp;
> > + int ret;
> > + struct stat sp;
> > +
> > + if (strlen(config_file) > PATH_MAX)
> > + return ENAMETOOLONG;
> > +
> > + fpath = malloc(PATH_MAX);
> > + if (!fpath)
> > + return ENOMEM;
> > + memset(fpath, 0, PATH_MAX);
> > +
> > + if (default_fd < 0) {
> > + fd = open_cli_config(config_file, &fpath);
> > + if (fd < 0) {
> > + free(fpath);
> > + return errno;
> > + }
> > + } else {
> > + fd = default_fd;
> > + memcpy(fpath, config_file, strlen(config_file));
> > + }
>
> This is messy - opening the file shoul dbe split from parsing the
> config file. I make more comments about the reason below. But I
> think this should end up as:
>
> int
> open_config_file(
> const char *config_file,
> char **source)
> {
> /*
> * XXX: should asprintf the source string
OK
> so it's got the
> * config_file opened in it.
Not sure what you mean by this though, can you clarify?
> */
> dft.source = _("Built in defaults");
This was already set, and dft is not a global, are you suggesting
to remove the global setting you had and *always* make source now an
allocated string?
> dirfd = open(sysconfdir, O_PATH|O_NOFOLLOW);
>
> if (config_file) {
> fd = open_cli_config(dirfd, config_file)
> if (fd > 0)
fd >= 0
> *source = _("CLI supplied file");
> goto out;
> }
>
> fd = openat(dirfd, "default")
> if (fd > 0)
fd >= 0
> *source = ("Package default config file")
I take it you mean to use asprintf(source, _("Package default config file")
but this can also fail... and adds more error paths to check for...
> out:
> close(dirfd);
> return fd;
> }
I think this asprintf() source approach add more complexity as well, which is
why I had used an enum for it a while ago. Think about it and let me know.
> and so be completely separated from the act of parsing the config
> file.
>
> > +
> > + /*
> > + * At this point we know we have a valid file descriptor and have
> > + * figured out the path to the file used on fpath. Get the file stream
> > + * and do a bit of sanity checks before parsing the file.
> > + */
> > +
> > + fp = fdopen(fd, "r");
> > + if (!fp) {
> > + perror(fpath);
> > + ret = errno;
> > + goto out_close_fd;
> > + }
> > +
> > + ret = fstat(fd, &sp);
> > + if (ret) {
> > + ret = errno;
> > + fprintf(stderr, _("Could not fstat() config file: %s: %s\n"),
> > + fpath, strerror(errno));
> > + goto out;
> > + }
> > +
> > + if (S_ISDIR(sp.st_mode)) {
> > + ret = EBADF;
>
> if (!S_ISREG(sp.st_mode)) {
> ret = -EINVAL;
Amended.
>
> > + fprintf(stderr, _("Config file is a directory: %s\n"), fpath);
> > + goto out;
> > + }
> > +
> > + /* Anything beyond 1 MiB is kind of silly right now */
> > + if (sp.st_size > 1 * 1024 * 1024) {
> > + ret = E2BIG;
> > + goto out;
> > + }
>
> As mentioned about, these checks should be done before we even open
> the file.
OK
> > +
> > + /*
> > + * Pull config line options from command line
> > */
> > + while ((c = getopt(argc, argv, "b:c:d:i:l:L:m:n:KNp:qr:s:CfV")) != EOF) {
>
> Why specify all the parameters? We're only interested in the "c:"
> parameter here, so that's the only one we need to specify, right?
Have you tried? I didn't work for me, its why I added the full set of
parameters again.
> Otherwise we've got two config option strings we need to keep i
> check...
Right, which is why I had a macro for it a while ago.
> > + switch (c) {
> > + case 'c':
> > + if (cli_config_file) {
> > + fprintf(stderr, _("respecification of configuration not allowed\n"));
> > + exit(1);
> > + }
> > + cli_config_file = optarg;
> > + dft.source = _("command line");
> > + break;
> > + default:
> > + continue;
> > + }
> > + }
> > +
> > + if (cli_config_file)
> > + config_file = cli_config_file;
> > + else {
> > + default_fd = open(default_config, O_RDONLY);
> > + if (default_fd >= 0) {
> > + dft.source = _("system default configuration file");
> > + config_file = default_config;
> > + }
> > + }
> > +
> > + if (config_file) {
> > + /* If default_fd is set it will be closed for us */
> > + ret = parse_defaults_file(&dft, default_fd, config_file);
> > + if (ret) {
> > + fprintf(stderr, _("Error parsing %s config file: %s : %s\n"),
> > + dft.source, config_file,
> > + strerror(ret));
> > + exit(1);
> > + }
> > + }
>
> It doesn't make sense to me to open the default config file here
> before we know if it going to be needed. I would suggest that this
> get split into two parts - one to find and open the config file, the
> other to parse the opened file. i.e.:
>
> fd = open_config_file(cli_config_file, &dft.source);
> if (fd >= 0) {
> ret = parse_defaults_file(fd, &dft);
> ....
> close(fd);
> }
Let me know what you think of the other things first too.
Luis
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser
2018-05-29 23:31 ` Darrick J. Wong
@ 2018-06-01 21:56 ` Luis R. Rodriguez
0 siblings, 0 replies; 21+ messages in thread
From: Luis R. Rodriguez @ 2018-06-01 21:56 UTC (permalink / raw)
To: Darrick J. Wong
Cc: Luis R. Rodriguez, sandeen, linux-xfs, jack, jeffm, okurz,
lpechacek, jtulak
On Tue, May 29, 2018 at 04:31:46PM -0700, Darrick J. Wong wrote:
> On Tue, May 29, 2018 at 03:06:02PM -0700, Luis R. Rodriguez wrote:
> > +int
> > +parse_defaults_file(
> > + struct mkfs_default_params *dft,
> > + int default_fd,
> > + char *config_file)
> > +{
> > + char *fpath;
> > + int fd;
> > + FILE *fp;
> > + int ret;
> > + struct stat sp;
> > +
> > + if (strlen(config_file) > PATH_MAX)
> > + return ENAMETOOLONG;
> > +
> > + fpath = malloc(PATH_MAX);
> > + if (!fpath)
> > + return ENOMEM;
> > + memset(fpath, 0, PATH_MAX);
> > +
> > + if (default_fd < 0) {
> > + fd = open_cli_config(config_file, &fpath);
> > + if (fd < 0) {
> > + free(fpath);
> > + return errno;
> > + }
> > + } else {
> > + fd = default_fd;
> > + memcpy(fpath, config_file, strlen(config_file));
> > + }
> > +
> > + /*
> > + * At this point we know we have a valid file descriptor and have
> > + * figured out the path to the file used on fpath. Get the file stream
> > + * and do a bit of sanity checks before parsing the file.
> > + */
> > +
> > + fp = fdopen(fd, "r");
> > + if (!fp) {
> > + perror(fpath);
>
> It occurred to me just now (sorry...) that the caller of this function
> prints out a string with strerror() contents, so the perror here is
> unnecessary
Alright.
> since the caller will cough up an error anyway. Then all of
> these constructions here become:
>
> fp = fdopen(...);
> if (!fp)
> return -1;
>
> ret = fstat(...);
> if (ret)
> goto out;
>
> if (S_ISDIR(...)) {
> errno = EISDIR;
> goto out;
> }
> ...
> return 0;
> out:
> return -1;
Sure.
>
> and the call site now becomes:
>
> if (parse_defaults_file(...)) {
> fprintf(stderr, "%s: file is bad: %s\n", path, strerror(errno));
> ...
> }
Works with me.
> Granted maybe we should just merge this and do all those cleanups
> separately.
;)
> > + if (S_ISDIR(sp.st_mode)) {
> > + ret = EBADF;
>
> ret = EISDIR?
Chinner asked we always make a regular file out of the config,
so now a regular file check will suffice, and EISDIR would not
be as descriptive.
So I'll wait to hear back on some other minor things, hopefully next
week we can wrap up this series for good.
--
Do not panic
^ permalink raw reply [flat|nested] 21+ messages in thread
end of thread, other threads:[~2018-06-01 21:56 UTC | newest]
Thread overview: 21+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-05-29 22:05 [PATCH v4 0/4] xfsprogs: add mkfs.xfs configuration file parsing support Luis R. Rodriguez
2018-05-29 22:06 ` [PATCH v4 1/4] mkfs: distinguish between struct sb_feat_args and struct cli_params Luis R. Rodriguez
2018-05-29 22:06 ` [PATCH v4 2/4] mkfs: move shared config structs and into their own headers Luis R. Rodriguez
2018-05-30 1:28 ` Dave Chinner
2018-05-29 22:06 ` [PATCH v4 3/4] mkfs.xfs: add configuration file parsing support using our own parser Luis R. Rodriguez
2018-05-29 23:31 ` Darrick J. Wong
2018-06-01 21:56 ` Luis R. Rodriguez
2018-05-30 2:09 ` Eric Sandeen
2018-05-30 3:33 ` Eric Sandeen
2018-05-30 3:33 ` Dave Chinner
2018-06-01 21:13 ` Luis R. Rodriguez
2018-05-30 7:36 ` Martin Steigerwald
2018-05-30 16:06 ` Darrick J. Wong
2018-05-30 18:10 ` [PATCH 3.5/4] mkfs.xfs: document defaults config file details Eric Sandeen
2018-05-30 18:30 ` Darrick J. Wong
2018-05-30 18:37 ` Eric Sandeen
2018-05-30 20:51 ` [PATCH 3.5/4 V2] " Eric Sandeen
2018-05-30 22:08 ` Darrick J. Wong
2018-05-30 21:05 ` [PATCH 3.7/4] mkfs.xfs.8: parameterize sysconfdir Eric Sandeen
2018-05-30 22:10 ` Darrick J. Wong
2018-05-29 22:06 ` [PATCH v4 4/4] debian/rules: use the new sysconfdir configuration setting Luis R. Rodriguez
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.