From 301469d5287fec17a9c404c27fd3805dbb96593e Mon Sep 17 00:00:00 2001 From: Andreas Dilger Date: Sun, 10 Oct 2021 15:52:19 -0600 Subject: [PATCH] EX-4006 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. Test-Parameters: trivial testlist=sanity-pcc Signed-off-by: Andreas Dilger Change-Id: Ieff40b7b133aef64200a9a3f6c1a948d7c3ebbe5 Reviewed-on: https://review.whamcloud.com/45178 Tested-by: jenkins Reviewed-by: Yingjin Qian Reviewed-by: Feng, Lei Tested-by: Maloo --- lustre/doc/lfs-pcc-attach.1 | 52 +++++++++++++++++++++++++++++++++++++++++ lustre/doc/lfs-pcc-attach_fid.1 | 1 + lustre/doc/lfs-pcc-detach.1 | 43 ++++++++++++++++++++-------------- lustre/doc/lfs-pcc-detach_fid.1 | 1 + lustre/doc/lfs-pcc-state.1 | 30 ++++++++++++++++++++++++ lustre/utils/lfs.c | 51 +++++++++++++++++++++++----------------- lustre/utils/liblustreapi_pcc.c | 2 +- 7 files changed, 140 insertions(+), 40 deletions(-) create mode 100644 lustre/doc/lfs-pcc-attach.1 create mode 100644 lustre/doc/lfs-pcc-attach_fid.1 create mode 100644 lustre/doc/lfs-pcc-detach_fid.1 create mode 100644 lustre/doc/lfs-pcc-state.1 diff --git a/lustre/doc/lfs-pcc-attach.1 b/lustre/doc/lfs-pcc-attach.1 new file mode 100644 index 0000000..b7bdeca --- /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-detach.1 b/lustre/doc/lfs-pcc-detach.1 index 7ac48c9..345c49a 100644 --- a/lustre/doc/lfs-pcc-detach.1 +++ b/lustre/doc/lfs-pcc-detach.1 @@ -2,43 +2,50 @@ .SH NAME lfs pcc detach|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 new file mode 100644 index 0000000..a3d0159 --- /dev/null +++ b/lustre/doc/lfs-pcc-state.1 @@ -0,0 +1,30 @@ +.TH LFS-PCC-STATE 1 2021-10-07 "Lustre" "Lustre Utilities" +.SH NAME +lfs pcc state \- display current PCC state of file +.SH SYNOPSIS +.BR "lfs pcc state " "\fIFILE \fR...>" +.SH DESCRIPTION +Display the current PCC cache state of +.I FILE +.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 EXAMPLES +.TP +.B $ lfs pcc state /mnt/lustre/file +Show the PCC cache state of +.BR file . +This shows the cache attach type: +as +.BR none , +.BR readonly , +or +.BR readwrite . +.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 4b77cab..446829f 100644 --- a/lustre/utils/lfs.c +++ b/lustre/utils/lfs.c @@ -374,28 +374,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 [--readonly|-r] [--write|-w] " - "[--id|-i NUM] ...\n" - "\t-i: archive id for RW-PCC\n" + "usage: lfs pcc attach [--id|-i ID] [--readonly|-r] [--write|-w] ...\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 [--readonly|-r] [--write|-w] " - "[--id|-i NUM] <--mnt|-m mnt> ...\n" - "\t-i: archive id for RW-PCC\n" + "usage: lfs pcc attach_fid [--id|-i ID] {--mnt|-m MOUNTPATH} [--readonly|-r] [--write|-w] ...\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 ...\n" }, + { .pc_name = "status", .pc_func = lfs_pcc_state, + .pc_help = "Display the PCC state for given files.\n" + "usage: lfs pcc status ...\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_name = "list-commands", .pc_func = lfs_pcc_list_commands, .pc_help = "list commands supported by lfs pcc"}, { .pc_name = "help", .pc_func = Parser_help, .pc_help = "help" }, @@ -11867,13 +11868,14 @@ static int lfs_pcc_detach_fid(int argc, char **argv) { struct option long_opts[] = { { .val = 'k', .name = "keep", .has_arg = no_argument }, + { .val = 'm', .name = "mnt", .has_arg = required_argument }, { .name = NULL } }; - char short_opts[] = "k"; - int c; - int rc = 0; + char short_opts[] = "km:"; + 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; @@ -11883,6 +11885,9 @@ 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: @@ -11892,22 +11897,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 35aca6a..7a37d28 100644 --- a/lustre/utils/liblustreapi_pcc.c +++ b/lustre/utils/liblustreapi_pcc.c @@ -275,11 +275,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; -- 1.8.3.1