| Message ID | 20180711030012.9186-5-qi.fuli@jp.fujitsu.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Wed, 2018-07-11 at 12:00 +0900, QI Fuli wrote: > This patch is used to add manpage for ndctl monitor command. > > Signed-off-by: QI Fuli <qi.fuli@jp.fujitsu.com> > --- > Documentation/ndctl/Makefile.am | 3 +- > Documentation/ndctl/ndctl-monitor.txt | 96 +++++++++++++++++++++++++++ > 2 files changed, 98 insertions(+), 1 deletion(-) > create mode 100644 Documentation/ndctl/ndctl-monitor.txt > > diff --git a/Documentation/ndctl/Makefile.am b/Documentation/ndctl/Makefile.am > index 4fd9636..a30b139 100644 > --- a/Documentation/ndctl/Makefile.am > +++ b/Documentation/ndctl/Makefile.am > @@ -46,7 +46,8 @@ man1_MANS = \ > ndctl-inject-error.1 \ > ndctl-inject-smart.1 \ > ndctl-update-firmware.1 \ > - ndctl-list.1 > + ndctl-list.1 \ > + ndctl-monitor.1 > > CLEANFILES = $(man1_MANS) > > diff --git a/Documentation/ndctl/ndctl-monitor.txt b/Documentation/ndctl/ndctl-monitor.txt > new file mode 100644 > index 0000000..037fdc7 > --- /dev/null > +++ b/Documentation/ndctl/ndctl-monitor.txt > @@ -0,0 +1,96 @@ Missing SPDX license header > +ndctl-monitor(1) > +================ > + > +NAME > +---- > +ndctl-monitor - Monitor the smart events of nvdimm objects > + > +SYNOPSIS > +-------- > +[verse] > +'ndctl monitor' [<options>] > + > +DESCRIPTION > +----------- > +Ndctl monitor is used for monitoring the smart events of nvdimm > +objects and dumping the json format notifications to syslog or > +a logfile. > + > +The objects to monitor and smart evnets to notify can be selected ^ s/evnets/events/ > +by setting options and/or the default configuration file > +(/etc/ndctl/monitor.conf). Both of the values in configuration file > +and in options will work. If conflict, the values in options will ^ "If there is a conflict..." > +override the values in configuration file. The changed values in > +configuration file will work after restart ndctl monitor. ^ "..after the monitor is restarted." > + > +EXAMPLES > +-------- > + > +Run a monitor as a daemon to monitor DIMMs on a provider named ndbus1 > +[verse] > +ndctl monitor -b ndbus1 -f > + > +Run a monitor as a one-shot command and output the notifications to > +/var/log/ndctl.log > +[verse] > +ndctl monitor -l /var/log/ndctl.log > + > +Run a monitor daemon as a system service > +[verse] > +systemctl start ndctl-monitor.service For man page examples, I prefer using the long format options as it is easier for the user to understand what is going on. Also for examples, perhaps use the actual bus name (such as ACPI.NFIT) instead of the identifier libnvdimm assigns to it (since that is also what bash completion provides) > + > +OPTIONS > +------- > +-b:: > +--bus=:: > + Enforce that the operation only be carried on devices that are > + attached to the given bus. Where 'bus' can be a provider name > + or a bus id number. > + > +-d:: > +--dimm=:: > + A 'nmemX' device name, or dimm id number. Select the devices to > + monitor refrerence the given dimm. ^ s/refrerence/reference/ > + > +-r:: > +--region=:: > + A 'regionX' device name, or a region id number. The keyword 'all' > + can be specified to carry out the operation on every region in > + the system, optionally filtered by bus id (see --bus= option). > + > +-n:: > +--namespace=:: > + A 'namespaceX.Y' device name, or namespace region plus id tuple > + 'X.Y'. > + > +-l <file | syslog>:: > +--logfile=<file | syslog>:: > + Output notifications to <file> or syslog. > + > +-f:: -f could be construed as --foreground, which would be the opposite of what --daemon is trying to do. I would suggest -B for 'background' (since 'b' is in use for bus), but -B could come in handy for a future bus-events option.. I think I'd prefer to set the short option to something like -x (since option parsing doesn't allow for an empty short option), and not advertise it in the man page at all (similar to inject-smart). > +--daemon:: > + Run a monitor as a daemon. > + > +-D:: > +--dimm-event=:: > + A name of smart events come NVDIMM DIMMs. s/NVDIMM DIMMs/NVDIMMs/ Also perhaps something like this makes more sense: "Name of an smart health event from the following:" > + - "dimm-spares-remaining": Spare Blocks Remaining value has gone > + below the pre-programmed threshold limit in all of these: s/threshold limit/threshold/ 'threshold' already implies a limit. > + - "dimm-media-temperature": NVDIMM Media temperature value has > + gone above the pre-programmed threshold limit > + - "dimm-controller-temperature": NVDIMM Controller temperature > + value has gone above the pre-programmed threshold limit > + - "dimm-health-state": NVDIMM Normal Health Status has changed > + - "dimm-unclean-shutdown": NVDIMM Last Shutdown Status was a dirty > + shutdown. s/dirty/unclean/ to stay consistent with the name. These (and some other minor details like the logfile) will need updates to the bash completion script (contrib/ndctl). But I can do that easily enough if you don't want to spend the time to grok how that works :) > + > +COPYRIGHT > +--------- > +Copyright (c) 2018, FUJITSU LIMITED. License GPLv2: GNU GPL version 2 > +<http://gnu.org/licenses/gpl.html>. This is free software: you are > +free to change and redistribute it. There is NO WARRANTY, to the > +extent permitted by law. > + > +SEE ALSO > +-------- > +linkndctl:ndctl-list[1] In addition to ndctl-list, also add ndctl-inject-smart here since that is used for setting thresholds and alarms.
diff --git a/Documentation/ndctl/Makefile.am b/Documentation/ndctl/Makefile.am index 4fd9636..a30b139 100644 --- a/Documentation/ndctl/Makefile.am +++ b/Documentation/ndctl/Makefile.am @@ -46,7 +46,8 @@ man1_MANS = \ ndctl-inject-error.1 \ ndctl-inject-smart.1 \ ndctl-update-firmware.1 \ - ndctl-list.1 + ndctl-list.1 \ + ndctl-monitor.1 CLEANFILES = $(man1_MANS) diff --git a/Documentation/ndctl/ndctl-monitor.txt b/Documentation/ndctl/ndctl-monitor.txt new file mode 100644 index 0000000..037fdc7 --- /dev/null +++ b/Documentation/ndctl/ndctl-monitor.txt @@ -0,0 +1,96 @@ +ndctl-monitor(1) +================ + +NAME +---- +ndctl-monitor - Monitor the smart events of nvdimm objects + +SYNOPSIS +-------- +[verse] +'ndctl monitor' [<options>] + +DESCRIPTION +----------- +Ndctl monitor is used for monitoring the smart events of nvdimm +objects and dumping the json format notifications to syslog or +a logfile. + +The objects to monitor and smart evnets to notify can be selected +by setting options and/or the default configuration file +(/etc/ndctl/monitor.conf). Both of the values in configuration file +and in options will work. If conflict, the values in options will +override the values in configuration file. The changed values in +configuration file will work after restart ndctl monitor. + +EXAMPLES +-------- + +Run a monitor as a daemon to monitor DIMMs on a provider named ndbus1 +[verse] +ndctl monitor -b ndbus1 -f + +Run a monitor as a one-shot command and output the notifications to +/var/log/ndctl.log +[verse] +ndctl monitor -l /var/log/ndctl.log + +Run a monitor daemon as a system service +[verse] +systemctl start ndctl-monitor.service + +OPTIONS +------- +-b:: +--bus=:: + Enforce that the operation only be carried on devices that are + attached to the given bus. Where 'bus' can be a provider name + or a bus id number. + +-d:: +--dimm=:: + A 'nmemX' device name, or dimm id number. Select the devices to + monitor refrerence the given dimm. + +-r:: +--region=:: + A 'regionX' device name, or a region id number. The keyword 'all' + can be specified to carry out the operation on every region in + the system, optionally filtered by bus id (see --bus= option). + +-n:: +--namespace=:: + A 'namespaceX.Y' device name, or namespace region plus id tuple + 'X.Y'. + +-l <file | syslog>:: +--logfile=<file | syslog>:: + Output notifications to <file> or syslog. + +-f:: +--daemon:: + Run a monitor as a daemon. + +-D:: +--dimm-event=:: + A name of smart events come NVDIMM DIMMs. + - "dimm-spares-remaining": Spare Blocks Remaining value has gone + below the pre-programmed threshold limit + - "dimm-media-temperature": NVDIMM Media temperature value has + gone above the pre-programmed threshold limit + - "dimm-controller-temperature": NVDIMM Controller temperature + value has gone above the pre-programmed threshold limit + - "dimm-health-state": NVDIMM Normal Health Status has changed + - "dimm-unclean-shutdown": NVDIMM Last Shutdown Status was a dirty + shutdown. + +COPYRIGHT +--------- +Copyright (c) 2018, FUJITSU LIMITED. License GPLv2: GNU GPL version 2 +<http://gnu.org/licenses/gpl.html>. This is free software: you are +free to change and redistribute it. There is NO WARRANTY, to the +extent permitted by law. + +SEE ALSO +-------- +linkndctl:ndctl-list[1]
This patch is used to add manpage for ndctl monitor command. Signed-off-by: QI Fuli <qi.fuli@jp.fujitsu.com> --- Documentation/ndctl/Makefile.am | 3 +- Documentation/ndctl/ndctl-monitor.txt | 96 +++++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 1 deletion(-) create mode 100644 Documentation/ndctl/ndctl-monitor.txt