self-diagnostics: added documentation

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

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": "<Description of module>",
+  "dependency": [
+    {
+      "type": "file",
+      "file": "<filepath>"
+    }
+  ],
+  "exec": [
+    {
+      "description": "<Description of command>",
+      "cmd": "<command To Execute>",
+      "dependency": [
+        {
+          "type": "file",
+          "file": "<filepath>"
+        }
+      ]
+    },
+    {
+      "description": "<Next command description>",
+      "cmd": "<command to execute>"
+    }
+  ]
+}
+```
+
+## 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.

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
+					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" ] && \