From 4f70901a8c19362e598b1807f88feeb7db681d2e Mon Sep 17 00:00:00 2001 From: Vivek Kumar Dutta Date: Fri, 3 Nov 2023 15:26:05 +0530 Subject: [PATCH] self-diagnostics: added documentation --- self-diagnostics/Makefile | 2 +- self-diagnostics/README.md | 188 ++++++++++++++++++ .../files/usr/sbin/self-diagnostics | 11 +- 3 files changed, 197 insertions(+), 4 deletions(-) create mode 100644 self-diagnostics/README.md diff --git a/self-diagnostics/Makefile b/self-diagnostics/Makefile index d4c2f980d..d5bf44c11 100644 --- a/self-diagnostics/Makefile +++ b/self-diagnostics/Makefile @@ -1,7 +1,7 @@ include $(TOPDIR)/rules.mk PKG_NAME:=self-diagnostics -PKG_VERSION:=1.0.0 +PKG_VERSION:=1.0.1 PKG_RELEASE:=1 PKG_LICENSE:=GPL-2.0-only diff --git a/self-diagnostics/README.md b/self-diagnostics/README.md new file mode 100644 index 000000000..932c0496e --- /dev/null +++ b/self-diagnostics/README.md @@ -0,0 +1,188 @@ +# Self Test Diagnostics and Reports + +Self test diagnostics package provides a set of tools and recipes to run diagnostics/commands and collect logs. + +It provides a cli utility called `self-diagnostics`, which executes recipes defined in json files and collect logs. +```bash +# self-diagnostics -h +Generate self diagnostics report + +Syntax: /usr/sbin/self-diagnostics [-m|h|l|j] + +Options: + l List available module(s) + m Generate system report of specific module(s) + j Enable JSON output + h Print this help +``` + +It also has an uci file to configure the various parameters: + +```bash +# cat /etc/config/self-diagnostics +config globals 'globals' + option extended_spec_dir '/etc/self-diagnostics/spec' + option exec_timeout '5' + option report_name 'self-diagnostics-report-$MODEL-$SERIAL' + option verbose '0' + option compression_level '9' +``` + +Here: + +| Options | Description | +| ------------------ | ------------------------------- | +| extended_spec_dir | Directory path to store 3rd-party/user diagnostics recipes | +| exec_timeout | Timeout used for each command | +| report_name | Name of the generated report file, here $MODEL and $SERIAL replaced with ProductModel and SerialNumber | +| verbose | Logs everythings to logread as well | +| commpression_level | Gzip compression_level 0-9, if not set, then report will not gziped | + + +It also provide, a rpcd script to expose `self-diagnostics` over ubus + +```bash +# ubus -v list self-diagnostics +'self-diagnostics' @2c0b768d + "list":{} + "generate":{"modules":"String"} +``` + +## Recipe(s) + +It has core modules and extended modules. + +Core module recipes are present in `/usr/share/self-diagnostics/spec/` path, where as +extended module recipes are defined in uci option 'self-diagnostics.globals.extended_spec_dir' + +Both the spec directories has recipes to run diagnostics and collect logs, these recipes are defined in json files. + +```bash +# ls /usr/share/self-diagnostics/spec/ +config.json network.json trx69.json wifi.json +multiap.json system.json voice.json +``` + +Each json file need to follow below structure: + +```json +{ + "description": "", + "dependency": [ + { + "type": "file", + "file": "" + } + ], + "exec": [ + { + "description": "", + "cmd": "", + "dependency": [ + { + "type": "file", + "file": "" + } + ] + }, + { + "description": "", + "cmd": "" + } + ] +} +``` + +## How to use + +This can be run from command line, ubus , USP-Controller and ACS. + +### List available core/extension modules + +```bash +# self-diagnostics -l + +Core Module(s): + - config + - multiap + - network + - system + - trx69 + - voice + - wifi + +Extension Module(s): +``` + +### Run and collect logs + +```bash +# self-diagnostics +/tmp/self-diagnostics-report-EX600-Y.0721140081.tar.gz +``` + +### List available core/extension modules over ubus + +```bash +# ubus call self-diagnostics list +{ + "CoreModules": [ + "config", + "multiap", + "network", + "system", + "trx69", + "voice", + "wifi" + ], + "ExtensionModules": [ + + ] +} +``` + +### Run specific module from ubus + +```bash +# ubus call self-diagnostics generate '{"modules":"config"}' +{ + "result": "/tmp/self-diagnostics-report-EX600-Y.0721140081.tar.gz" +} +``` + +## TR-181 Integration + + +TR-181 (USP) provides an Operate command `Device.SelfTestDiagnostics()` to execute it from USP-controllers. +TR-181 (CWMP) provides a diagnostics object `Device.SelfTestDiagnostics.` for the same, so its can be triggered from ACS as well. + +```bash +# ubus call bbfdm operate '{"command":"Device.SelfTestDiagnostics()"}' +{ + "results": [ + { + "path": "Device.SelfTestDiagnostics()", + "data": "", + "output": [ + { + "Results": "Device.DeviceInfo.VendorLogFile.2", + "Status": "Complete" + } + ] + } + ] +} +``` + + +Once the opreate command is done, it generate a new entry in VendorLogFile, like below: + +```bash +# bbfdmd -c get Device.DeviceInfo.VendorLogFile.2. +Device.DeviceInfo.VendorLogFile.2.Alias => cpe-2 +Device.DeviceInfo.VendorLogFile.2.Name => /tmp/self-diagnostics-report-EX600-Y.0721140081.tar.gz +Device.DeviceInfo.VendorLogFile.2.MaximumSize => 0 +Device.DeviceInfo.VendorLogFile.2.Persistent => 0 +``` + +Which is then can be uploaded to a server using `Device.DeviceInfo.VendorLogFile.{i}.Upload()` operate command. diff --git a/self-diagnostics/files/usr/sbin/self-diagnostics b/self-diagnostics/files/usr/sbin/self-diagnostics index 39891caca..56f9159d3 100755 --- a/self-diagnostics/files/usr/sbin/self-diagnostics +++ b/self-diagnostics/files/usr/sbin/self-diagnostics @@ -192,8 +192,13 @@ exec_spec() echo $description >> $export_path echo "##################" >> $export_path if [ "$VERBOSE" -eq 1 ]; then - eval timeout ${exec_timeout} $cmd 2>&1 | tee -a $export_path | logger -t self-diagnostics - rc=$? + if [[ "$cmd" == *"logread "* ]]; then + eval timeout ${exec_timeout} $cmd 2>&1 | tee -a $export_path + rc=$? + else + eval timeout ${exec_timeout} $cmd 2>&1 | tee -a $export_path | logger -t self-diagnostics + rc=$? + fi else eval timeout ${exec_timeout} $cmd >> $export_path 2>&1 rc=$? @@ -226,7 +231,7 @@ generate_module() file="$(find $SPEC_DIR -type f -name ${module}.json)" [ -z "$file" ] && { [ -d "${SPEC_EXT_DIR}" ] && \ - file="$(find $SPEC_EXT_DIR -type f -name ${file}.json)" + file="$(find $SPEC_EXT_DIR -type f -name ${module}.json)" } [ -f "$file" ] && \