LU-16134 utils: un-deprecate 'lctl set_param -F'

The "lctl set_param -F" command was accidentally disabled in 2.16 due
to a mis-merge between two in-flight patches.  Restore this command.

Change some functions to use "const char" for string arguments.

Add an example usage of "lctl set_param -F" in the lctl-set_param.8
man page, and update it to match style guidelines.  Add descriptions
of the usage examples in the EXAMPLES section.

Update checkpatch-man.pl to quiet spurious warnings about examples
with client#, mgs#, mds#, or oss# in the command-line prompt text.

Test-Parameters: trivial
Test-Parameters: testlist=conf-sanity env=ONLY=123 combinedmdsmgs=false
Test-Parameters: testlist=conf-sanity env=ONLY=123 combinedmdsmgs=true
Fixes: 8be38f4bd8 ("LU-11077 utils: move get/set/list_param into own file")
Fixes: 29cfdc2f1e ("LU-16134 utils: adds lctl apply_yaml")
Signed-off-by: Andreas Dilger <adilger@whamcloud.com>
Change-Id: I7e8140bf5e1c5747df4785539a6fda491d500c1e
Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/58532
Tested-by: Maloo <maloo@whamcloud.com>
Tested-by: jenkins <devops@whamcloud.com>
Reviewed-by: Jian Yu <yujian@whamcloud.com>
Reviewed-by: Oleg Drokin <green@whamcloud.com>
Reviewed-by: Alexander Boyko <alexander.boyko@hpe.com>

diff --git a/contrib/scripts/checkpatch-man.pl b/contrib/scripts/checkpatch-man.pl
index 85b74c9..2d05908 100755 (executable)
--- a/contrib/scripts/checkpatch-man.pl
+++ b/contrib/scripts/checkpatch-man.pl
@@ -531,8 +531,8 @@ sub process {
 # check if \f is being used to format man pages
                if ($line =~ /\\f[BIR]/) {
                        if ($prevline =~ /^\.TP/) {
-                               CHK("ESCAPE_SEQUENCE_AFTER_TP",
-                                   "IGNORE THIS CHECK. Avoid using \\f[BIR] for formatting purposes, however \\c is not supported when following .TP in groff 1.22.3 or older\n" . $hereprev);
+                               #CHK("ESCAPE_SEQUENCE_AFTER_TP",
+                               #    "IGNORE THIS CHECK. Avoid using \\f[BIR] for formatting purposes, however \\c is not supported when following .TP in groff 1.22.3 or older\n" . $hereprev);
                        } else {
                                WARN("AVOID_ESCAPE_SEQUENCE",
                                     "Avoid using \\f[BIR] for formatting purposes, instead use .[BI] or .[BIR][BIR] on a new line. Use \\c at the end of the previous line to use a different format without a space.\n" . $herecurr);
@@ -832,7 +832,7 @@ EOM
                                } else {
                                        foreach my $subject (split(", ", $subjectline)) {
                                                $subject =~ s/\-/ /;
-                                               if ($line =~ /$subject/ && $line !~ /^\.B [#\$]/) {
+                                               if ($line =~ /$subject/ && $line !~ /^\.B [clientmgods]*[#\$]/) {
                                                        CHK("EXAMPLES_FORMAT_USER_INPUT",
                                                            "If this line is user input, it should be bold (.B) and prefaced with either '#'/'\$' for root/non-root users respectively\n" . $herecurr);
                                                }
@@ -955,4 +955,4 @@ EOM
                }
        }
        return $clean
-}
\ No newline at end of file
+}

diff --git a/lustre/doc/lctl-llog_print.8 b/lustre/doc/lctl-llog_print.8
index 4333a69..60af890 100644 (file)
--- a/lustre/doc/lctl-llog_print.8
+++ b/lustre/doc/lctl-llog_print.8
@@ -47,10 +47,12 @@ or
 .BR lustrefs-MDT0000 .
 .SH EXAMPLES
 To print the configuration records from the
-.BR testfs-client logfile:
+.BR testfs-client
+logfile, and save it to a file for later restoration by
+.BR lctl-set_param (8):
 .RS
 .EX
-.B # lctl llog_print testfs-client
+.B # lctl llog_print testfs-client | tee /root/testfs-client.yaml
 - { index: 3, event: attach, device: testfs-clilov, type: lov,
     UUID: testfs-clilov_UUID }
 - { index: 6, event: setup, device: testfs-clilov, UUID: }
@@ -86,4 +88,5 @@ filesystem package since release 0.10.0
 .BR lctl (8),
 .BR lctl-llog_cancel (8),
 .BR lctl-llog_catlist (8),
-.BR lctl-llog_info (8)
+.BR lctl-llog_info (8),
+.BR lctl-set_param (8)

diff --git a/lustre/doc/lctl-set_param.8 b/lustre/doc/lctl-set_param.8
index 0e3d675..5af9add 100644 (file)
--- a/lustre/doc/lctl-set_param.8
+++ b/lustre/doc/lctl-set_param.8
@@ -1,4 +1,4 @@
-.TH LCTL-SET_PARAM 8 2024-08-14 Lustre "Lustre Configuration Utilities"
+.TH LCTL-SET_PARAM 8 2025-03-26 Lustre "Lustre Configuration Utilities"
 .SH NAME
 lctl-set_param \- Lustre filesystem set parameter utility
 .SH SYNOPSIS
@@ -12,7 +12,7 @@ lctl-set_param \- Lustre filesystem set parameter utility
 .RB [ --thread | -t\c
 .RI [ THREAD_COUNT ]]
 .IR PARAMETER \= VALUE " ..."
-.SY lctl set_param -F
+.SY "lctl set_param -F"
 .I FILENAME
 .YS
 .SH DESCRIPTION
@@ -65,12 +65,12 @@ Set parameters from
 .I FILENAME
 instead of from the command-line. The contents of
 .I FILENAME
-is YAML format, created as an output from
-.RB ' "lctl --device MGS llog_print"
+is YAML format, created by the output from running
+.RB ' "lctl llog_print"
 .I FSNAME\c
-.BR -client '
-or any other valid llog configuration log as listed by
-.RB ' "lctl --device MGS llog_catlist" '
+.BR -client ',
+or from any other valid llog configuration log as listed by
+.RB ' "lctl llog_catlist" '.
 .TP
 .BR -n ", " --no-name
 Disable printing of the parameter name after setting it.
@@ -106,32 +106,65 @@ printed and parameters will be set serially. If
 .B -t
 is specified without any argument, it runs up to 8 threads by default.
 .SH EXAMPLES
+Set two parameters temporarily on the local node:
+.RS
+.EX
+.B client# lctl set_param jobid_name=%H:%e:%u debug_mb=1024
+jobid_name=%H:%e:%u
+debug_mb=1024
+.EE
+.RE
+.PP
+Set two parameters, but don't print parameter names with the values:
+.RS
 .EX
-.B # lctl set_param fail_loc=0 timeout=20
-fail_loc=0
-timeout=20
-.B # lctl set_param -n fail_loc=0 timeout=20
-0
-20
-.B # lctl set_param -t2 "ldlm.namespaces.*osc*.lru_size=clear"
+.B client# lctl set_param -n jobid_name=%H:%e:%u debug_mb=1024
+%H:%e:%u
+1024
+.EE
+.RE
+.PP
+Run two parallel threads to set parameters that may do a lot of work:
+.RS
+.EX
+.B client# lctl set_param -t2 "ldlm.namespaces.*osc*.lru_size=clear"
 ldlm.namespaces.fsname-OST0001-osc-MDT0000.lru_size=clear
 ldlm.namespaces.fsname-OST0000-osc-MDT0000.lru_size=clear
-.B # lctl set_param -P osc.testfs-OST*.max_dirty_mb=512
+.EE
+.RE
+.PP
+Permanently set a parameter with a wildcard in the MGS config llog:
+.RS
+.EX
+.B mgs# lctl set_param -P osc.testfs-OST*.max_dirty_mb=512
 osc.testfs-OST0000-osc-ffff8803c9c0f000.max_dirty_mb=512
 osc.testfs-OST0001-osc-ffff8803c9c0f000.max_dirty_mb=512
 osc.testfs-OST0002-osc-ffff8803c9c0f000.max_dirty_mb=512
 osc.testfs-OST0003-osc-ffff8803c9c0f000.max_dirty_mb=512
 osc.testfs-OST0004-osc-ffff8803c9c0f000.max_dirty_mb=512
+.EE
+.RE
 .PP
-Set
+Permanently set
 .B osc.testfs-*.max_dirty_mb=2000
 when mounting 'testfs' and
 .B osc.testfs-*.max_dirty_mb=1024
-for other Lustre mountpoints on this client node
+for other Lustre mountpoints on this client node:
+.RS
 .EX
+.B client# lctl set_param -C=test_fs osc.testfs-*.max_dirty_mb=2000
+.B client# lctl set_param -C osc.*.max_dirty_mb=1024
+.RE
+.EE
+.PP
+Backup the
+.RB ' params '
+configuration log, and then restore it (at some later time):
 .RS
-.B # lctl set_param -C=test_fs osc.testfs-*.max_dirty_mb=2000
-.B # lctl set_param -C osc.testfs-*.max_dirty_mb=1024
+.EX
+.B mgs# lctl llog_print params > /tmp/params.yaml
+[ params log is erased, not shown here ]
+.B mgs# lctl set_param -F /tmp/params.yaml
 .RE
 .EE
 .SH AVAILABILITY

diff --git a/lustre/tests/conf-sanity.sh b/lustre/tests/conf-sanity.sh
index 8f8040b..4dd2c81 100755 (executable)
--- a/lustre/tests/conf-sanity.sh
+++ b/lustre/tests/conf-sanity.sh
@@ -10904,7 +10904,8 @@ test_123F() {
 
        # Reapply the config from before
        echo "Setting configuration parameters"
-       do_facet mgs "lctl set_param -F $yaml_file"
+       do_facet mgs "$LCTL set_param -F $yaml_file" ||
+               error "'set_param -F $yaml_file' failed"
 
        test_123_restore
 }
@@ -10920,7 +10921,8 @@ test_123G() {
 
        # Reapply the config from before
        echo "Setting configuration parameters"
-       do_facet mgs "lctl apply_yaml $yaml_file"
+       do_facet mgs "$LCTL apply_yaml $yaml_file" ||
+               error "'apply_yaml $yaml_file' failed"
 
        test_123_restore
 }

diff --git a/lustre/utils/lctl.c b/lustre/utils/lctl.c
index 6e2d5da..b8ceb44 100644 (file)
--- a/lustre/utils/lctl.c
+++ b/lustre/utils/lctl.c
@@ -452,30 +452,29 @@ command_t cmdlist[] = {
         "                 [--no-links|-L] [--no-name|-n] [--only-name|-N]\n"
         "                 [--readable|-r] [--recursive|-R]\n"
         "                 [--tunable|-t] [--writable|-w] [--yaml|-y]\n"
-        "                 <param_path1 param_path2 ...>\n"
+        "                 PARAM_PATH1 [PARAM_PATH2 ...]\n"
         "Get the value of Lustre or LNET parameter from the specified path.\n"
         "The path can contain shell-style filename patterns.\n"},
        {"set_param", jt_lcfg_setparam, 0, "set the Lustre or LNET parameter\n"
-        "usage: set_param [--client|-C[FSNAME]] [--delete|-d] [--file|-F]\n"
-        "                 [--no-name|-n] [--permanent|-P]"
+        "usage: set_param [--client|-C[FSNAME]] [--delete|-d] [--no-name|-n]\n"
+        "                 [--file|-F YAML_PARAM FILE] [--permanent|-P]"
 #ifdef HAVE_LIBPTHREAD
         " [--thread|-t[THREAD_COUNT]]"
 #endif
         "\n"
         "                 PARAM1=VALUE1 [PARAM2=VALUE2 ...]\n"
         "Set the value of the Lustre or LNET parameter at the specified path.\n"},
-       {"apply_yaml", jt_lcfg_applyyaml, 0, "set/config the Lustre or LNET "
-        "parameters using configuration from a YAML file.\n"
-        "usage: apply_yaml file\n"},
+       {"apply_yaml", jt_lcfg_applyyaml, 0, "alias for 'set_param -F'\n"
+        "usage: apply_yaml YAML_PARAM_FILE\n"},
        {"list_param", jt_lcfg_listparam, 0,
         "list the Lustre or LNET parameter name\n"
         "usage: list_param [--dir-only|-D] [--classify|-F] [--links|-l]\n"
         "                  [--no-links|-L] [--path|-p] [--readable|-r]\n"
         "                  [--recursive|-R] [--tunable|-t] [--writable|-w]\n"
-        "                  <param_path1 param_path2 ...>\n"
+        "                  PARAM_PATH1 [PARAM_PATH2 ...]\n"
         "List the name of Lustre or LNet parameter from the specified path.\n"},
        {"del_ost", jt_del_ost, 0, "permanently delete OST records\n"
-        "usage: del_ost [--dryrun] --target <$fsname-OSTxxxx>\n"
+        "usage: del_ost [--dryrun] --target FSNAME-OSTxxxx\n"
         "Cancel the config records for a specific OST to forget about it.\n"},
 
        /* Debug commands */

diff --git a/lustre/utils/lustre_cfg.c b/lustre/utils/lustre_cfg.c
index 972b741..22a3013 100644 (file)
--- a/lustre/utils/lustre_cfg.c
+++ b/lustre/utils/lustre_cfg.c
@@ -75,6 +75,8 @@
 #include <stdio.h>
 #include <yaml.h>
 
+static int lcfg_apply_param_yaml(const char *func, const char *filename);
+
 static char *lcfg_devname;
 
 int lcfg_set_devname(char *name)
@@ -412,7 +414,7 @@ int jt_lcfg_param(int argc, char **argv)
        return jt_lcfg_ioctl(&bufs, argv[0], LCFG_PARAM);
 }
 
-static int lcfg_setparam_perm(char *func, char *buf)
+static int lcfg_setparam_perm(const char *func, char *buf)
 {
        int rc = 0;
        struct lustre_cfg_bufs bufs;
@@ -465,14 +467,15 @@ int jt_lcfg_setparam_perm(int argc, char **argv, struct param_opts *popt)
 {
        int rc;
        int i;
-       int first_param;
        char *buf = NULL;
 
-       first_param = optind;
-       if (first_param < 0 || first_param >= argc)
+       if (optind < 0 || optind >= argc)
                return CMD_HELP;
 
-       for (i = first_param, rc = 0; i < argc; i++) {
+       if (popt->po_file)
+               return lcfg_apply_param_yaml(argv[0], argv[optind]);
+
+       for (i = optind, rc = 0; i < argc; i++) {
                buf = argv[i];
                if (popt->po_delete) {
                        char *end_pos;
@@ -501,7 +504,7 @@ int jt_lcfg_setparam_perm(int argc, char **argv, struct param_opts *popt)
        return rc;
 }
 
-static int lcfg_conf_param(char *func, char *buf)
+static int lcfg_conf_param(const char *func, char *buf)
 {
        int rc;
        struct lustre_cfg_bufs bufs;
@@ -1053,7 +1056,7 @@ static enum paramtype construct_param(enum paramtype confset, const char *param,
        return PT_NONE;
 }
 
-static int lcfg_apply_param_yaml(char *func, char *filename)
+static int lcfg_apply_param_yaml(const char *func, const char *filename)
 {
        FILE *file;
        yaml_parser_t parser;
@@ -1068,7 +1071,7 @@ static int lcfg_apply_param_yaml(char *func, char *filename)
        char device[PARAM_SZ + 1];
        bool convert;
 
-       convert = !strncmp(func, "set_param", 9);
+       convert = strncmp(func, "set_param", 9) == 0;
        file = fopen(filename, "rb");
        if (!file) {
                rc1 = -errno;

diff --git a/lustre/utils/lustre_param.c b/lustre/utils/lustre_param.c
index 0676990..0ceabd8 100644 (file)
--- a/lustre/utils/lustre_param.c
+++ b/lustre/utils/lustre_param.c
@@ -1006,12 +1006,8 @@ static int setparam_cmdline(int argc, char **argv, struct param_opts *popt)
                        return -1;
                }
        }
-       if (popt->po_perm && popt->po_file) {
-               fprintf(stderr, "warning: ignoring -P option\n");
-               popt->po_perm = 0;
-       }
        if (popt->po_delete && !popt->po_perm && !popt->po_client) {
-               fprintf(stderr, "warning: setting -P option\n");
+               fprintf(stderr, "warning: setting '-P' option with '-d'\n");
                popt->po_perm = 1;
        }
        return optind;
@@ -1039,7 +1035,7 @@ int jt_lcfg_setparam(int argc, char **argv)
        if (index < 0 || index >= argc)
                return CMD_HELP;
 
-       if (popt.po_perm)
+       if (popt.po_perm || popt.po_file)
                /*
                 * We can't delete parameters that were
                 * set with old conf_param interface
@@ -1049,12 +1045,6 @@ int jt_lcfg_setparam(int argc, char **argv)
        if (popt.po_client)
                return jt_lcfg_setparam_client(argc, argv, &popt);
 
-       if (popt.po_file) {
-               fprintf(stderr,
-                       "warning: 'lctl set_param -F' is deprecated, use 'lctl apply_yaml' instead\n");
-               return -EINVAL;
-       }
-
        if (popt_is_parallel(popt)) {
                rc = spwq_init(&wq, &popt);
                if (rc < 0) {

diff --git a/lustre/utils/mount_lustre.c b/lustre/utils/mount_lustre.c
index a6cbb56..257b528 100644 (file)
--- a/lustre/utils/mount_lustre.c
+++ b/lustre/utils/mount_lustre.c
@@ -818,7 +818,7 @@ int jt_lcfg_setparam_perm(int argc, char **argv, struct param_opts *popt)
        return 0;
 }
 
-char *jt_cmdname(char *func)
+const char *jt_cmdname(const char *func)
 {
        return func;
 }

diff --git a/lustre/utils/obd.c b/lustre/utils/obd.c
index 29b1c9b..cb0e0e5 100644 (file)
--- a/lustre/utils/obd.c
+++ b/lustre/utils/obd.c
@@ -166,7 +166,7 @@ static int get_mgs_device(void)
 }
 
 /* Returns 0 on success, -errno on failure */
-int lcfg_mgs_ioctl(char *func, int dev_id, struct lustre_cfg *lcfg)
+int lcfg_mgs_ioctl(const char *func, int dev_id, struct lustre_cfg *lcfg)
 {
        struct obd_ioctl_data data;
        char rawbuf[MAX_IOC_BUFLEN], *buf = rawbuf;
@@ -215,7 +215,7 @@ char *obdo_print(struct obdo *obd)
 
 #define BAD_VERBOSE (-999999999)
 
-char *jt_cmdname(char *func)
+const char *jt_cmdname(const char *func)
 {
        static char buf[512];
 

diff --git a/lustre/utils/obdctl.h b/lustre/utils/obdctl.h
index 78a26ed..4c68391 100644 (file)
--- a/lustre/utils/obdctl.h
+++ b/lustre/utils/obdctl.h
@@ -135,9 +135,9 @@ int jt_llog_check(int argc, char **argv);
 
 struct lustre_cfg;
 int lcfg_ioctl(char * func, int dev_id, struct lustre_cfg *lcfg);
-int lcfg_mgs_ioctl(char *func, int dev_id, struct lustre_cfg *lcfg);
+int lcfg_mgs_ioctl(const char *func, int dev_id, struct lustre_cfg *lcfg);
 int parse_devname(char *func, char *name, int dev_id);
-char *jt_cmdname(char *func);
+const char *jt_cmdname(const char *func);
 
 /* lustre_param.c */
 struct param_opts;