From deffab986863a476906e6b7206588de69430086e Mon Sep 17 00:00:00 2001 From: Andreas Dilger Date: Fri, 23 May 2025 22:51:39 -0600 Subject: [PATCH] LU-16974 utils: make bandwidth options consistent The "lfs mirror extend|resync" and "lfs migrate" commands all have the ability to limit IO bandwidth. Some used "--bandwidth" and others used "--bandwidth-limit". Make them all the same. They accept the longer "--bandwidth-limit" for compatibility, but only "--bandwidth" will be documented for brevity and ease of use. The getopt_long() options can be abbreviated to any unique prefix, so both do not need to be specified. Update the usage messages and man pages to reflect these options. Minor nearby code style fixes to the man pages as well. Test-Parameters: trivial Signed-off-by: Andreas Dilger Change-Id: Ie8702bedba9fbfa5b0ea473853a7b5480e61abb5 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/59411 Tested-by: Oleg Drokin Reviewed-by: Oleg Drokin --- Documentation/man1/lfs-migrate.1 | 82 ++++++++++++++++++---------------- Documentation/man1/lfs-mirror-extend.1 | 28 ++++++------ Documentation/man1/lfs-mirror-resync.1 | 15 +++---- lustre/utils/lfs.c | 35 +++++++-------- 4 files changed, 82 insertions(+), 78 deletions(-) diff --git a/Documentation/man1/lfs-migrate.1 b/Documentation/man1/lfs-migrate.1 index f39ef89..34e3063 100644 --- a/Documentation/man1/lfs-migrate.1 +++ b/Documentation/man1/lfs-migrate.1 @@ -1,4 +1,4 @@ -.TH LFS-MIGRATE 1 2024-08-20 Lustre "Lustre User Utilities" +.TH LFS-MIGRATE 1 2025-05-23 Lustre "Lustre User Utilities" .SH NAME lfs-migrate \- migrate files or directories between MDTs or OSTs. .SH SYNOPSIS @@ -21,7 +21,14 @@ and all inodes/directories therein between MDTs. .SH OPTIONS .SS OST MIGRATE OPTIONS -.P +The +.B lfs migrate +command can be used for moving files from one (or more) OSTs to other +OSTs (e.g. for space balancing between OSTs, or to evacuate an OST for +hardware reasons), to change the stripe count or other layout parameters +of a file (e.g. to increase the bandwidth of a file by striping it over +multiple OSTs), or to move the file between different classes of storage +(e.g. SSD vs. HDD OSTs, or local vs. remote OSTs in different pools). .IR FILES_FROM may be: .TP @@ -35,20 +42,9 @@ Usually is used after a pipeline from \fBlfs find --print0\fR command. .TP .BR --files-from = \fILIST_FILE Read file names from file \fILIST_FILE\fR. One line for each file name. -If \fILIST_FILE\fR is \fB-\fR, read from stdin. -If \fB--null\fR is specified at the same time, -file names are separated by a NUL char. +If \fILIST_FILE\fR is \fB-\fR, read from stdandard input. +If \fB--null\fR is also specified, file names are separated by a NUL char. -.SH OST MIGRATE OPTIONS -.P -The -.B lfs migrate -command can be used for moving files from one (or more) OSTs to other -OSTs (e.g. for space balancing between OSTs, or to evacuate an OST for -hardware reasons), to change the stripe count or other layout parameters -of a file (e.g. to increase the bandwidth of a file by striping it over -multiple OSTs), or to move the file between different classes of storage -(e.g. SSD vs. HDD OSTs, or local vs. remote OSTs in different pools). .P In OST object migration mode, the command supports the same .I SETSTRIPE_OPTIONS @@ -105,13 +101,19 @@ This option cannot be used on encrypted files when the encryption key is not available. It will result in .BR -ENOKEY . .TP -.BR -W ", " --bandwidth -Limit how much file system bandwidth a migrate job can consume. +.BR -W ", " --bandwidth " \fIBANDWIDTH_MB\fR[" MG ] +Limit the read and write bandwidth a migrate job consumes to no more than +.I BANDWIDTH_MB +MiB/s. An optional suffix can be used to specify units in +.BR M ebibytes +or +.BR G ibibytes +per second. .TP .BR --stats Output verbose stats about migrate job progress in YAML format. .TP -.BR --stats-interval +.BI --stats-interval " SECONDS" Controls how often the stats are output; this defaults to 5 seconds. .TP .BR -v ", " --verbose @@ -146,7 +148,7 @@ across all of the specified MDT indices as if an equivalent .BI -c N option were given. .TP -.BR -c ", " --mdt-count=\fICOUNT\fR +.BR -c ", " --mdt-count= \fICOUNT All directories and subdirectories in the tree will be striped across .I COUNT MDTs, always using @@ -174,10 +176,10 @@ and .RB ' "lfs getstripe -d" '. .TP .BR --clear-fixed -Do not set LMV_HASH_FLAG_FIXED upon migrating the directory. It allows a striped dir -with only one stripe to be converted to a plain directory. +Do not set LMV_HASH_FLAG_FIXED upon migrating the directory. It allows a +striped dir with only one stripe to be converted to a plain directory. .TP -.BR -H ", " --mdt-hash=\fIHASH_TYPE\fR +.BR -H ", " --mdt-hash= \fIHASH_TYPE Use .I HASH_TYPE for the new directory layout. @@ -223,67 +225,71 @@ migrated file(s) to be a new, and cause them to be backed up again. This migrates the data in .B file1 into a new layout with 2 stripes: -.RS .EX +.RS .B # lfs migrate -c 2 /mnt/lustre/file1 -.EE .RE +.EE .PP This migrates the data in .B file2 into a three component composite layout (number of stripes depends on file size): -.RS .EX +.RS .B # lfs migrate -E 256M -c 1 -E 16G -c 4 -E eof -c 40 /mnt/lustre/file2 -.EE .RE +.EE .PP Recursively move the subdirectories and inodes contained in directory .B remotedir from its current MDT to MDT0000 and MDT0002. The .B testremote directory and all of its subdirectories will be striped across both MDTs: -.RS .EX +.RS .B # lfs migrate -m 0,2 testremote -.EE .RE +.EE .PP -Move ./testremote and the first level of sub files from their current MDT +Move +.B ./testremote +and the first level of sub files from their current MDT to the MDT with index 0 and 2. Different from above case, the layout of -subdirectories under ./testremote won't be changed: -.RS +subdirectories under +.B ./testremote +won't be changed: .EX +.RS .B # lfs migrate -m 0,2 -d ./testremote -.EE .RE +.EE .PP Set a default PFL layout (without any DoM component) on the directory .BR topdir : -.RS .EX +.RS .B # lfs setstripe -E 256M -c 1 -E 16G -c 4 -E eof -c 40 topdir -.EE .RE +.EE then find and migrate all regular files that have an .B mdt component to copy the default layout from the specified .BR topdir : -.RS .EX +.RS .B # lfs find dir -type f -L mdt -0 | lfs migrate -0 --copy topdir -.EE .RE +.EE and finally migrate the directory .B topdir and all files and subdirectories in that tree to MDT0002. This allows migrating files with DoM components off an MDT: -.RS .EX +.RS .B # lfs migrate -m 2 topdir -.EE .RE +.EE .SH AVAILABILITY The .B lfs migrate diff --git a/Documentation/man1/lfs-mirror-extend.1 b/Documentation/man1/lfs-mirror-extend.1 index 371d679..a492d51 100644 --- a/Documentation/man1/lfs-mirror-extend.1 +++ b/Documentation/man1/lfs-mirror-extend.1 @@ -1,14 +1,14 @@ -.TH LFS-MIRROR-EXTEND 1 2024-08-20 Lustre "Lustre User Utilities" +.TH LFS-MIRROR-EXTEND 1 2025-05-23 Lustre "Lustre User Utilities" .SH NAME lfs-mirror-extend \- add mirror(s) to an existing file .SH SYNOPSIS .SY "lfs mirror extend" - [\fB--bandwidth-limit\fR|\fB-W\fR \fIMB_PER_SEC\fR] - [\fB--mirror-count\fR|\fB-N\fR[\fIMIRROR_COUNT\fR]] - [\fB--no-verify\fR] - [\fB--stats\fR|\fB--stats-interval\fR=\fISECONDS\fR] - [\fISETSTRIPE_OPTIONS\fR|\fB-f\fR \fIVICTIM_FILE\fR] - \fIFILES_FROM\fR +.RB [ --bandwidth | "-W \fIBANDWIDTH_MB" [ MG ] +.RB [ --mirror-count | -N [[ = ] \fIMIRROR_COUNT ]] +.RB [ --no-verify ] +.RB [ --stats | --stats-interval=\fISECONDS ] +.RI [ SETSTRIPE_OPTIONS "|\fB-f " VICTIM_FILE ] +.I FILES_FROM .YS .SH DESCRIPTION This command adds mirror(s) to existing file(s) specified by \fIFILES_FROM\fR. @@ -136,14 +136,14 @@ This option enables progress updates every .I STATS_INTERVAL seconds, in YAML format. .TP -.BR -W ", " --bandwidth-limit " \fIBANDWIDTH" -This option enables throttling so that mirror extending writes no more than -.I BANDWIDTH -bytes a second. An optional suffix can be used to specify the units in -.BR K ilobytes, -.BR M egabytes +.BR -W ", " --bandwidth " \fIBANDWIDTH_MB\fR[" MG ] +Limit the read and write bandwidth a mirror extend consumes to no more than +.I BANDWIDTH_MB +MiB/s. An optional suffix can be used to specify units in +.BR M ebibytes or -.BR G igabytes. +.BR G ibibytes +per second. .SH EXAMPLES Add 2 mirrors to /mnt/lustre/file1. If file1 is a non-mirrored file, then the command will convert it to a mirrored file first and then add mirrors. Each diff --git a/Documentation/man1/lfs-mirror-resync.1 b/Documentation/man1/lfs-mirror-resync.1 index fb3e63f..807333d 100644 --- a/Documentation/man1/lfs-mirror-resync.1 +++ b/Documentation/man1/lfs-mirror-resync.1 @@ -1,11 +1,11 @@ -.TH LFS-MIRROR-RESYNC 1 2024-08-20 Lustre "Lustre User Utilities" +.TH LFS-MIRROR-RESYNC 1 2025-05-23 Lustre "Lustre User Utilities" .SH NAME lfs-mirror-resync \- resynchronize an out-of-sync mirrored file .SH SYNOPSIS .SY "lfs mirror resync" .RB [ --only .IR MIRROR_ID [,...]] -.RB [ --bandwidth-limit= | -W +.RB [ --bandwidth= | -W .IR BANDWIDTH_MB ] .RB [ --stats ] .RB [ --stats-interval=\c @@ -58,15 +58,14 @@ This option enables progress updates every .I STATS_INTERVAL seconds, in YAML format. .TP -.BR -W ", " --bandwidth-limit " \fIBANDWIDTH_MB" -This option enables throttling so that mirror extending writes no more than +.BR -W ", " --bandwidth " \fIBANDWIDTH_MB\fR[" MG ] +Limit the read and write bandwidth a mirror resync consumes to no more than .I BANDWIDTH_MB -(default unit megabyte) a second. An optional suffix can be used to specify the -units in -.BR K ilobytes, +MiB/s. An optional suffix can be used to specify units in .BR M egabytes or -.BR G igabytes. +.BR G igabytes +per second. .SH EXAMPLES Resynchronize all of the stale and sync-able mirror(s) for /mnt/lustre/file1 and /mnt/lustre/file2: diff --git a/lustre/utils/lfs.c b/lustre/utils/lfs.c index f9cfcc2..b2efbe9 100644 --- a/lustre/utils/lfs.c +++ b/lustre/utils/lfs.c @@ -236,19 +236,20 @@ static inline int lfs_mirror_delete(int argc, char **argv) #define MIGRATE_USAGE \ SSM_CMD_COMMON("migrate ") \ + "\t\t[--bandwidth|-W BANDWIDTH_MB[MG]]\n" \ "\t\t[--block|-b] [--non-block|-n]\n" \ "\t\t[--non-direct|-D] [--verbose|-v] FILENAME\n" \ - "\t\t[--non-direct|-D] [--verbose|-v]\n" \ + "\t\t[--stats-interval SECONDS]\n" \ "\t\t-0|--null|--files-from=LIST_FILE|FILENAME ...\n" #define SETDIRSTRIPE_USAGE \ - " [--mdt-count|-c stripe_count>\n" \ - " [--help|-h] [--mdt-hash|-H mdt_hash]\n" \ - " [--mdt-index|-i mdt_index[,mdt_index,...]\n" \ - " [--mdt-overcount|-C stripe_count>\n" \ - " [--default|-D] [--mode|-o mode]\n" \ - " [--max-inherit|-X max_inherit]\n" \ - " [--max-inherit-rr max_inherit_rr] \n" \ + "\t\t[--mdt-count|-c stripe_count>\n" \ + "\t\t[--help|-h] [--mdt-hash|-H mdt_hash]\n" \ + "\t\t[--mdt-index|-i mdt_index[,mdt_index,...]\n" \ + "\t\t[--mdt-overcount|-C stripe_count>\n" \ + "\t\t[--default|-D] [--mode|-o mode]\n" \ + "\t\t[--max-inherit|-X max_inherit]\n" \ + "\t\t[--max-inherit-rr max_inherit_rr] \n" \ "To create dir with a foreign (free format) layout :\n" \ "setdirstripe|mkdir --foreign[=FOREIGN_TYPE] -x|-xattr STRING " \ " [--mode|-o MODE] [--flags HEX] DIRECTORY\n" @@ -297,7 +298,7 @@ command_t mirror_cmdlist[] = { .pc_help = "Extend a mirrored file.\n" "Usage: lfs mirror extend [--mirror-count|-N[MIRROR_COUNT]]\n" "\t\t[--no-verify] [--stats|--stats-interval=STATS_INTERVAL]\n" - "\t\t[--bandwidth-limit|--W BANDWIDTH]\n" + "\t\t[--bandwidth|-W BANDWIDTH_MB[MG]]\n" "\t\t[-f VICTIM_FILE]\n" "\t\t" SSM_SETSTRIPE_OPT "]\n" "\t\t-0|--null|--files-from=LIST_FILE|FILENAME ...\n" }, @@ -322,7 +323,7 @@ command_t mirror_cmdlist[] = { .pc_help = "Resynchronizes out-of-sync mirrored file(s).\n" "usage: lfs mirror resync [--only MIRROR_ID[,...]]|\n" "\t\t[--stats|--stats-interval=SECONDS]\n" - "\t\t[--W |--bandwidth-limit=BANDWIDTH_MB]\n" + "\t\t[--bandwidth|-W BANDWIDTH_MB[MG]]\n" "\t\tMIRRORED_FILE [MIRRORED_FILE2...]\n" }, { .pc_name = "verify", .pc_func = lfs_mirror_verify, .pc_help = "Verify mirrored file(s).\n" @@ -3818,7 +3819,7 @@ static int lfs_setstripe_internal(int argc, char **argv, /* find { .val = 'U', .name = "user", .has_arg = required_argument }*/ /* --verbose is only valid in migrate mode */ { .val = 'v', .name = "verbose", .has_arg = no_argument}, - { .val = 'W', .name = "bandwidth", .has_arg = required_argument }, + { .val = 'W', .name = "bandwidth-limit", .has_arg = required_argument}, { .val = 'x', .name = "xattr", .has_arg = required_argument }, /* dirstripe { .val = 'X',.name = "max-inherit",.has_arg = required_argument }*/ { .val = 'y', .name = "yaml", .has_arg = required_argument }, @@ -5724,7 +5725,7 @@ static int lfs_find(int argc, char **argv) { .val = 'u', .name = "uid", .has_arg = required_argument }, { .val = 'U', .name = "user", .has_arg = required_argument }, /* getstripe { .val = 'v', .name = "verbose", .has_arg = no_argument }, */ -/* setstripe { .val = 'W', .name = "bandwidth", .has_arg = required_argument }, */ +/*migrate{.val = 'W', .name = "bandwidth-limit",.has_arg = required_argument},*/ { .val = LFS_XATTRS_MATCH_OPT, .name = "xattr", .has_arg = required_argument }, { .val = 'z', .name = "extension-size", @@ -6690,7 +6691,7 @@ static int lfs_getstripe_internal(int argc, char **argv, /* find { .val = 'U', .name = "user", .has_arg = required_argument }*/ { .val = 'v', .name = "verbose", .has_arg = no_argument }, /* dirstripe { .val = 'X',.name = "max-inherit",.has_arg = required_argument }*/ -/* setstripe { .val = 'W', .name = "bandwidth", .has_arg = required_argument }*/ +/* migrate{.val = 'W', .name = "bandwidth-limit",.has_arg = required_argument}*/ { .val = 'y', .name = "yaml", .has_arg = no_argument }, { .val = 'z', .name = "extension-size", .has_arg = no_argument }, { .val = 'z', .name = "ext-size", .has_arg = no_argument }, @@ -12608,12 +12609,10 @@ static inline int lfs_mirror_resync(int argc, char **argv) struct option long_opts[] = { { .val = 'h', .name = "help", .has_arg = no_argument }, { .val = 'o', .name = "only", .has_arg = required_argument }, - { .val = 'W', .name = "bandwidth", .has_arg = required_argument }, - { .val = LFS_STATS_OPT, - .name = "stats", .has_arg = no_argument}, + { .val = 'W', .name = "bandwidth-limit", .has_arg = required_argument}, + { .val = LFS_STATS_OPT, .name = "stats", .has_arg = no_argument}, { .val = LFS_STATS_INTERVAL_OPT, - .name = "stats-interval", - .has_arg = required_argument}, + .name = "stats-interval", .has_arg = required_argument}, { .name = NULL } }; struct ll_ioc_lease *ioc = NULL; __u16 mirror_ids[128] = { 0 }; -- 1.8.3.1