From: Andreas Dilger Date: Sun, 10 Oct 2021 21:52:19 +0000 (-0600) Subject: LU-10499 pcc: improve pcc-detach and man pages X-Git-Tag: 2.15.91~42 X-Git-Url: https://git.whamcloud.com/?a=commitdiff_plain;h=cddda7c1b5a9c31370b7e7d0c2152e01e0867475;p=fs%2Flustre-release.git 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 Change-Id: Ieff40b7b133aef64200a9a3f6c1a948d7c3ebbe5 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/54454 Tested-by: jenkins Tested-by: Maloo Reviewed-by: James Simmons Reviewed-by: Oleg Drokin --- diff --git a/lustre/doc/lfs-pcc-attach.1 b/lustre/doc/lfs-pcc-attach.1 new file mode 100644 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 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 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 --- 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 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 --- 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 --- 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] ...\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 ...\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 ...\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 ...\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 --- 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;