LU-10499 pcc: improve pcc-detach and man pages

Improve "lfs pcc detach_fid" to have a "--mnt|-m" option to match
the corresponding option for "lfs pcc attach_fid".  There isn't
any reason that they should be different.

Separate lfs-pcc-attach.1 and lfs-pcc-detach.1 from the
lfs-pcc.1 man page and improve descriptions of these commands.
Add links for lfs-pcc-attach_fid.1 and lfs-pcc-detach_fid.1.

Describe fields in lfs-pcc-state.1.  Add lfs-pcc-delete.1 page.

EX-bug-id: EX-4006
Test-Parameters: trivial testlist=sanity-pcc
Signed-off-by: Andreas Dilger <adilger@whamcloud.com>
Change-Id: Ieff40b7b133aef64200a9a3f6c1a948d7c3ebbe5
Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/54454
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>
Reviewed-by: James Simmons <jsimmons@infradead.org>
Reviewed-by: Oleg Drokin <green@whamcloud.com>

diff --git a/lustre/doc/lfs-pcc-attach.1 b/lustre/doc/lfs-pcc-attach.1
new file mode 100644 (file)
index 0000000..a5f0d87
--- /dev/null
+++ b/lustre/doc/lfs-pcc-attach.1
@@ -0,0 +1,52 @@
+.TH LFS-PCC-ATTACH 1 2021-10-07 "Lustre" "Lustre Utilities"
+.SH NAME
+lfs pcc attach \- attach file to local cache filesystem
+.SH SYNOPSIS
+.BR "lfs pcc attach " [ -rw "] [" --id | -i "\fIID\fR] " \fIFILE [...]
+.br
+.BR "lfs pcc attach_fid " [ -rw "] [" --id | -i "\fIID\fR] {" --mnt | -m "\fIMNTPATH\fR}" \fIFID [...]
+.SH DESCRIPTION
+Attach and copy the specified files into the persistent client cache. Use
+.B lfs pcc detach
+to remove the cached files from PCC either manually, or through automatic
+mechanisms for the purpose of the cache space management.
+.SH OPTIONS
+.TP
+.BR --id | -i
+The ARCHIVE
+.I ID
+to choose which backend for the cached
+.IR FILE .
+If
+.I ID
+is not specified, then use the first archive attached to the mounted
+filesystem by default.
+.TP
+.BR --mnt | -m
+Specify the Lustre client mountpoint for the file
+.IR FID
+to be attached.
+.TP
+.BR --readonly | -r
+Attach the file in read-only mode.  This is the default.
+.TP
+.BR --write | -w
+Attach the file in read-write mode.
+.SH EXAMPLES
+.TP
+.B $ lfs pcc attach -i 1 /mnt/lustre/file
+Attach an existing file into PCC with archive ID 1 and copy data from Lustre
+to cache device. Reads from the Lustre file will direct to the PCC-RO copy.
+.TP
+.B $ lfs pcc attach_fid -r -m /mnt/lustre 0x200000401:0x1:0x0
+Read-only attach file referenced by FID "0x200000401:0x1:0x0" in filesystem
+.B /mnt/lustre
+using the first/only cache ID for that mountpoint.
+.TP
+.SH SEE ALSO
+.BR lfs (1),
+.BR lfs-pcc (1),
+.BR lfs-pcc-detach (1),
+.BR lfs-pcc-state (1),
+.BR lctl-pcc (8),
+.BR llapi_pcc_attach (3)

diff --git a/lustre/doc/lfs-pcc-attach_fid.1 b/lustre/doc/lfs-pcc-attach_fid.1
new file mode 100644 (file)
index 0000000..f7147b2
--- /dev/null
+++ b/lustre/doc/lfs-pcc-attach_fid.1
@@ -0,0 +1 @@
+.so man1/lfs-pcc-attach.1

diff --git a/lustre/doc/lfs-pcc-delete.1 b/lustre/doc/lfs-pcc-delete.1
new file mode 100644 (file)
index 0000000..7bdeaf5
--- /dev/null
+++ b/lustre/doc/lfs-pcc-delete.1
@@ -0,0 +1,17 @@
+.TH LFS-PCC-DELETE 1 2019-04-15 "Lustre" "Lustre Utilities"
+.SH NAME
+lfs pcc delete \- delete PCC component from file
+.SH SYNOPSIS
+.BR "lfs pcc delete" \fIFILE [...]
+.SH DESCRIPTION
+Delete PCC component from specified
+.IR FILE (s).
+This will remove the cached file from all connected clients, and
+allow the file to be accessed by older clients that do not have
+PCC support.
+.SH SEE ALSO
+.BR lfs (1),
+.BR lfs-pcc (1),
+.BR lfs-pcc-attach (1),
+.BR lfs-pcc-detach (1),
+.BR lctl-pcc (8)

diff --git a/lustre/doc/lfs-pcc-detach.1 b/lustre/doc/lfs-pcc-detach.1
index fca82a5..8f0b15e 100644 (file)
--- a/lustre/doc/lfs-pcc-detach.1
+++ b/lustre/doc/lfs-pcc-detach.1
@@ -2,43 +2,50 @@
 .SH NAME
 lfs-pcc-detach, lfs-pcc-detach_fid \- Detach given files from PCC
 .SH SYNOPSIS
-.B lfs pcc detach [\fB--keep\fR|\fB-k\fR] <\fIfile \fR...>
+.BR "lfs pcc detach " [ --keep | -k ] \fIFILE [...]
 .br
-.B lfs pcc detach_fid [\fB--keep\fR|\fB-k\fR] <\fImntpath\fR> <\fIfid \fR...>
+.BR "lfs pcc detach_fid " [ --keep | -k "] {" --mnt | -m "\fIMNTPATH\fR}" \fIFID [...]
 .SH DESCRIPTION
-.TP
-.B lfs pcc detach [\fB--keep\fR|\fB-k\fR] <\fIfile \fR...>
-Detach given files from the persistent client cache.
-.TP
-.B lfs pcc detach_fid [\fB--keep\fR|\fB-k\fR] <\fImntpath\fR> <\fIfid \fR...>
-Detach files from the persistent client cache by FID(s).
+Detach specified
+.I FILE
+or
+.I FID
+from the persistent client cache.
 .SH OPTIONS
 .TP
-.B --keep | -k
-By default, the detach command will detach the file from PCC permanently and
-remove the PCC copy after detach. This option will only detach the file, but
-keep the PCC copy in cache. It allows the detaching file to be attached
+.BR --keep | -k
+By default, the detach command will detach
+.I FILE
+from PCC permanently and remove the PCC copy after detach. This option
+will only detach the file in memory, but keep the PCC copy in cache.
+It allows the detached file to be attached
 automatically at next open if the cached copy of the file is still valid.
+.TP
+.BR --mnt | -m
+Specify the Lustre client mountpoint for the file
+.I FID
+to be detached.
 .SH EXAMPLES
 .TP
 .B $ lfs pcc detach /mnt/lustre/test
 Detach the file permanently from PCC. The cached file on PCC will be removed
 after detach. IO to the file will come to Lustre OSTs after this command.
 .TP
-.B $ lfs pcc detach_fid /mnt/lustre 0x200000401:0x1:0x0
-Detach the file referenced by FID "0x200000401:0x1:0x0" from PCC permanently, and
-the cached file on PCC will be removed after detach.
+.B $ lfs pcc detach_fid -m /mnt/lustre 0x200005348:0x101:0x0
+Detach the file referenced by FID "0x200005348:0x101:0x0" from PCC
+permanently, and the cached file on PCC will be removed after detach.
 .TP
 .B $ lfs pcc detach -k /mnt/lustre/test
 Detach the file "/mnt/lustre/test" from PCC. The client will try to attach
 this file again at the next open if the cached copy is still valid.
 .TP
-.B $ lfs pcc detach_fid -k /mnt/lustre 0x200000401:0x1:0x0
+.B $ lfs pcc detach_fid -k -m /mnt/lustre 0x200000401:0x1:0x0
 Detach the file referenced by FID "0x200000401:0x1:0x0" from PCC. The client
 will try to attach this file again at the next open if the cached copy is still
 valid.
 .SH SEE ALSO
 .BR lfs (1),
-.BR lfs-hsm (1),
 .BR lfs-pcc (1),
-.BR lctl-pcc (8)
+.BR lfs-pcc-attach (1),
+.BR lctl-pcc (8),
+.BR llapi_pcc_detach (3)

diff --git a/lustre/doc/lfs-pcc-detach_fid.1 b/lustre/doc/lfs-pcc-detach_fid.1
new file mode 100644 (file)
index 0000000..c48e51d
--- /dev/null
+++ b/lustre/doc/lfs-pcc-detach_fid.1
@@ -0,0 +1 @@
+.so man1/lfs-pcc-detach.1

diff --git a/lustre/doc/lfs-pcc-state.1 b/lustre/doc/lfs-pcc-state.1
index 99dc3b2..3616286 100644 (file)
--- a/lustre/doc/lfs-pcc-state.1
+++ b/lustre/doc/lfs-pcc-state.1
@@ -1 +1,39 @@
-.so man1/lfs-pcc.1
+.TH LFS-PCC-STATE 1 2021-10-07 "Lustre" "Lustre Utilities"
+.SH NAME
+lfs pcc state \- display current PCC state of file
+.SH SYNOPSIS
+.BI "lfs pcc state " FILE \fR[...]
+.SH DESCRIPTION
+Display the current PCC cache state of
+.I FILE
+on the local client.
+This shows several fields for each file.  The cache attach
+.B type
+is one of
+.BR none ,
+.BR readonly ,
+or
+.BR readwrite .
+The
+.B PCC_file
+shows relative pathname of the file within the local cache filesystem.
+The
+.B open_count
+is the number of processes that have the local cache file open, and
+.B flags
+shows additional file states, including
+.B attaching
+for files that are not fully copied into cache,
+.SH EXAMPLES
+.TP
+.B $ lfs pcc state /mnt/lustre/file
+Show the PCC cache state of
+.BR file .
+.TP
+.SH SEE ALSO
+.BR lfs (1),
+.BR lfs-pcc (1),
+.BR lfs-pcc-detach (1),
+.BR lfs-pcc-state (1),
+.BR lctl-pcc (8),
+.BR llapi_pcc_attach (3)

diff --git a/lustre/utils/lfs.c b/lustre/utils/lfs.c
index abe0c56..fa45994 100755 (executable)
--- a/lustre/utils/lfs.c
+++ b/lustre/utils/lfs.c
@@ -324,26 +324,29 @@ command_t mirror_cmdlist[] = {
 command_t pcc_cmdlist[] = {
        { .pc_name = "attach", .pc_func = lfs_pcc_attach,
          .pc_help = "Attach given files to the Persistent Client Cache.\n"
-               "usage: lfs pcc attach [--id|-i ID] [--readonly|-r] [--write|-w] <file> ...\n"
-               "\t-i: archive id for PCC\n"
+               "usage: lfs pcc attach [--id|-i ID] [--readonly|-r] [--write|-w] FILE [...]\n"
+               "\t-i: archive ID for PCC\n"
                "\t-r: readonly attach\n"
                "\t-w: writeable attach\n" },
        { .pc_name = "attach_fid", .pc_func = lfs_pcc_attach_fid,
          .pc_help = "Attach given files into PCC by FID(s).\n"
-               "usage: lfs pcc attach_id [--id|-i ID] {--mnt|-m MOUNTPOINT} [--readonly|-r] [--write|-w] FID ...\n"
-               "\t-i: archive id for PCC\n"
+               "usage: lfs pcc attach_id [--id|-i ID] {--mnt|-m MOUNTPOINT} [--readonly|-r] [--write|-w] FID [...]\n"
+               "\t-i: archive ID for PCC\n"
                "\t-m: Lustre mount point\n"
                "\t-r: readonly attach\n"
                "\t-w: writeable attach\n" },
        { .pc_name = "state", .pc_func = lfs_pcc_state,
          .pc_help = "Display the PCC state for given files.\n"
-               "usage: lfs pcc state <file> ...\n" },
+               "usage: lfs pcc state FILE [...]\n" },
+       { .pc_name = "status", .pc_func = lfs_pcc_state,
+         .pc_help = "Display the PCC state for given files.\n"
+               "usage: lfs pcc status FILE [...]\n" },
        { .pc_name = "detach", .pc_func = lfs_pcc_detach,
          .pc_help = "Detach given files from the Persistent Client Cache.\n"
-               "usage: lfs pcc detach <file> ...\n" },
+               "usage: lfs pcc detach [-k] FILE [...]\n" },
        { .pc_name = "detach_fid", .pc_func = lfs_pcc_detach_fid,
          .pc_help = "Detach given files from PCC by FID(s).\n"
-               "usage: lfs pcc detach_fid <mntpath> <fid>...\n" },
+               "usage: lfs pcc detach_fid {--mnt|-m MOUNTPATH} FID...\n" },
        { .pc_help = NULL }
 };
 
@@ -14000,13 +14003,14 @@ static int lfs_pcc_detach_fid(int argc, char **argv)
        struct option long_opts[] = {
        { .val = 'h',   .name = "help", .has_arg = no_argument },
        { .val = 'k',   .name = "keep", .has_arg = no_argument },
+       { .val = 'm',   .name = "mnt",  .has_arg = required_argument },
        { .name = NULL } };
-       char short_opts[] = "hk";
-       int c;
-       int rc = 0;
+       char short_opts[] = "hkm:";
+       const char *mntpath = NULL;
        const char *fidstr;
-       const char *mntpath;
        __u32 detach_flags = PCC_DETACH_FL_UNCACHE;
+       int rc = 0;
+       int c;
        int dirfd;
 
        optind = 0;
@@ -14016,6 +14020,11 @@ static int lfs_pcc_detach_fid(int argc, char **argv)
                case 'k':
                        detach_flags = PCC_DETACH_FL_NONE;
                        break;
+               case 'm':
+                       mntpath = optarg;
+                       break;
+               case '?':
+                       return CMD_HELP;
                default:
                        fprintf(stderr, "%s: unrecognized option '%s'\n",
                                progname, argv[optind - 1]);
@@ -14025,22 +14034,26 @@ static int lfs_pcc_detach_fid(int argc, char **argv)
                }
        }
 
-       if (argc <= optind) {
-               fprintf(stderr, "%s: must specify Lustre mount point\n",
-                       argv[0]);
-               return CMD_HELP;
+       /* for backward compatibility, allow mntpath without -m */
+       if (!mntpath) {
+               if (argc <= optind) {
+                       fprintf(stderr, "%s: must specify Lustre mount point\n",
+                               argv[0]);
+                       return CMD_HELP;
+               }
+
+               mntpath = argv[optind++];
        }
 
-       mntpath = argv[optind++];
        if (argc <= optind) {
-               fprintf(stderr, "%s: must specify one or more fids\n", argv[0]);
+               fprintf(stderr, "%s: must specify one or more FIDs\n", argv[0]);
                return CMD_HELP;
        }
 
-       dirfd = open(mntpath, O_RDONLY);
+       dirfd = open(mntpath, O_RDONLY | O_DIRECTORY);
        if (dirfd < 0) {
                rc = -errno;
-               fprintf(stderr, "%s: cannot open '%s': %s",
+               fprintf(stderr, "%s: cannot open directory '%s': %s",
                        argv[0], mntpath, strerror(errno));
                return rc;
        }

diff --git a/lustre/utils/liblustreapi_pcc.c b/lustre/utils/liblustreapi_pcc.c
index 1f263c9..f1ddba5 100644 (file)
--- a/lustre/utils/liblustreapi_pcc.c
+++ b/lustre/utils/liblustreapi_pcc.c
@@ -280,11 +280,11 @@ int llapi_pcc_detach_fd(int fd, __u32 flags)
 int llapi_pcc_detach_at(int dirfd, const struct lu_fid *fid,
                        enum lu_pcc_detach_flags flags)
 {
-       int rc;
        struct lu_pcc_detach_fid detach = {
                .pccd_fid = *fid,
                .pccd_flags = flags,
        };
+       int rc;
 
        rc = ioctl(dirfd, LL_IOC_PCC_DETACH_BY_FID, &detach);
        return rc ? -errno : 0;