From f521ac7ef3e080eb8c4e888f6a5f27ed5eeb3aa7 Mon Sep 17 00:00:00 2001 From: Vivek Kumar Dutta Date: Wed, 18 Dec 2024 12:27:26 +0000 Subject: [PATCH] Update Documentation --- README.md | 23 ++- docs/api/ubus/bbfdm.json | 61 +++---- docs/api/ubus/bbfdm.md | 287 +++++++++++++----------------- docs/api/uci/bbfdm.json | 17 +- docs/api/uci/bbfdm.md | 96 +--------- docs/guide/bbfdmd.md | 26 +-- docs/guide/dm-service.md | 127 ++++++++++--- docs/guide/libbbfdm-ubus.md | 22 +-- gitlab-ci/install-dependencies.sh | 2 +- gitlab-ci/shared.sh | 4 +- utilities/README.md | 68 +++++++ 11 files changed, 380 insertions(+), 353 deletions(-) diff --git a/README.md b/README.md index 3a31286c..5ef60a50 100644 --- a/README.md +++ b/README.md @@ -33,15 +33,30 @@ ## Important Topics * [BBFDMD Design](./docs/guide/bbfdmd.md) -* [API Documentation](./docs/guide/libbbfdm-api.md) +* [Micro-Service Design](./docs/guide/dm-service.md) +* [LIBBBFDM-API Documentation](./docs/guide/libbbfdm-api.md) +* [LIBBBFDM-UBUS Documentation](./docs/guide/libbbfdm-ubus.md) +* [Utilities Documentation](./utilities/README.md) * [Tools](./tools/README.md) -* [Utilities](./utilities/README.md) * [How to extend datamodel with C Code](./docs/guide/How_to_extend_datamodel_with_C_Code.md) * [How to extend datamodel with JSON](./docs/guide/How_to_extend_datamodel_with_JSON.md) -### Datamodel related topics +## Good To Know + +- The current data model implementation follows the latest version of the data model, version `2.18``. + +- Instance alias handling has been moved to the icwmp repository since `bbfdm` repository only supports the common functionality provided by CWMP and USP protocols. + +- The current data model implementation does not support the delete method for all instances (e.g., Device.Users.User.) since CWMP and USP protocols do not provide support for this operation. + +- The data model implementation uses different directories to store temporary UCI configurations based on the protocol being used. The details are as follows: + +| Protocol | Save Config Directory | Config Directory | Save Dmmap Directory | Dmmap Directory | +| -------- | ------------------------ ---------------- | ---------------------- | ---------------- | +| cwmp | /tmp/bbfdm/.cwmp/config | /etc/config | /tmp/bbfdm/.cwmp/dmmap | /etc/bbfdm/dmmap | +| usp | /tmp/bbfdm/.usp/config | /etc/config | /tmp/bbfdm/.usp/dmmap | /etc/bbfdm/dmmap | +| both | /tmp/bbfdm/.bbfdm/config | /etc/config | /tmp/bbfdm/.cwmp/dmmap | /etc/bbfdm/dmmap | -* [Design for firmware activation](./docs/guide/libbbfdm_DeviceInfo_FirmwareImage.md) ### Compilation helper utilities diff --git a/docs/api/ubus/bbfdm.json b/docs/api/ubus/bbfdm.json index 40648def..39f4c98d 100644 --- a/docs/api/ubus/bbfdm.json +++ b/docs/api/ubus/bbfdm.json @@ -710,51 +710,38 @@ } }, "service": { - "title": "Register a micro-service in the main service", + "title": "show the list of micro-service registred in the core Data Model", "type": "object", + "required": [ + "output" + ], "properties": { - "input": { - "type": "object", - "properties": { - "cmd": { - "$ref": "#/definitions/srv_type_t" - }, - "name": { - "type": "string", - "description": "Name of the micro-service ubus object" - }, - "parent_dm": { - "type": "string", - "description": "Object path where the micro-service object will be added" - }, - "object": { - "type": "string", - "description": "Name of the micro-service object" - } - }, - "required": [ - "cmd" - ] - }, + "intput": {}, "output": { "type": "object", "properties": { - "status": { - "type": "boolean" + "name": { + "type": "string", + "Description": "Name of the micro-service ubus object" }, - "error": { - "type": "string" + "parent_dm": { + "type": "string", + "Description": "Object path where the micro-service object will be added" + }, + "object": { + "type": "string", + "Description": "Name of the micro-service object" + }, + "proto": { + "$ref": "#/definitions/proto_t" + }, + "unified_daemon": { + "type": "boolean", + "Description": "type of micro-service: unified daemon or dm-service" } - }, - "required": [ - "status" - ] + } } - }, - "required": [ - "input", - "output" - ] + } }, "notify_event": { "title": "notify occurance of an event on ubus", diff --git a/docs/api/ubus/bbfdm.md b/docs/api/ubus/bbfdm.md index 61216fbb..e8754af4 100644 --- a/docs/api/ubus/bbfdm.md +++ b/docs/api/ubus/bbfdm.md @@ -109,7 +109,7 @@ Device.WiFi. ### Ubus CLI Example ``` -ubus call bbf add {"path":"anim consequat","obj_path":{}} +ubus call bbf add {"path":"eu commodo Ut ut ","obj_path":{}} ``` ### JSONRPC Example @@ -119,7 +119,7 @@ ubus call bbf add {"path":"anim consequat","obj_path":{}} "jsonrpc": "2.0", "id": 0, "method": "call", - "params": ["", "bbf", "add", { "path": "anim consequat", "obj_path": {} }] + "params": ["", "bbf", "add", { "path": "eu commodo Ut ut ", "obj_path": {} }] } ``` @@ -183,7 +183,16 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ "results": [{ "path": "dolor in sunt eiusmod", "data": "sunt pariatur", "fault": 8972, "fault_msg": "ea culpa" }] } +{ + "results": [ + { + "path": "eused exercitation", + "data": "pariatur nostrud in aute Excepteur", + "fault": 7415, + "fault_msg": "dolor magna" + } + ] +} ``` ## del @@ -284,7 +293,7 @@ All items must be of the type: Unknown type ``. ### Ubus CLI Example ``` -ubus call bbf del {"path":"eu venia","paths":["adipisicing ad dolor do"]} +ubus call bbf del {"path":"fugiat adipisicing","paths":["do laborum occaecat et"]} ``` ### JSONRPC Example @@ -294,7 +303,7 @@ ubus call bbf del {"path":"eu venia","paths":["adipisicing ad dolor do"]} "jsonrpc": "2.0", "id": 0, "method": "call", - "params": ["", "bbf", "del", { "path": "eu venia", "paths": ["adipisicing ad dolor do"] }] + "params": ["", "bbf", "del", { "path": "fugiat adipisicing", "paths": ["do laborum occaecat et"] }] } ``` @@ -358,16 +367,7 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ - "results": [ - { - "path": "incididunt laborum Duis", - "data": "nostrud aliquip velit", - "fault": 7729, - "fault_msg": "culpa nisi adipisicing dolore eiusmod" - } - ] -} +{ "results": [{ "path": "occaecat sit elit i", "data": "non", "fault": 7119, "fault_msg": "elit sunt" }] } ``` ## get @@ -546,7 +546,7 @@ All items must be of the type: Unknown type ``. ### Ubus CLI Example ``` -ubus call bbf get {"path":"veniam sunt","paths":["nisi ad et veniam"],"maxdepth":-3902100,"optional":{"format":"raw","proto":"both"}} +ubus call bbf get {"path":"occaecat aliqua mollit","paths":["occaecat Duis Lorem velit aliq"],"maxdepth":-48387650,"optional":{"format":"raw","proto":"usp"}} ``` ### JSONRPC Example @@ -561,10 +561,10 @@ ubus call bbf get {"path":"veniam sunt","paths":["nisi ad et veniam"],"maxdepth" "bbf", "get", { - "path": "veniam sunt", - "paths": ["nisi ad et veniam"], - "maxdepth": -3902100, - "optional": { "format": "raw", "proto": "both" } + "path": "occaecat aliqua mollit", + "paths": ["occaecat Duis Lorem velit aliq"], + "maxdepth": -48387650, + "optional": { "format": "raw", "proto": "usp" } } ] } @@ -633,11 +633,7 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ - "results": [ - { "path": "anim consectetur", "data": "dolore d", "type": "xsd:command", "fault": 8024, "fault_msg": "quis minim" } - ] -} +{ "results": [{ "path": "dolore dolor", "data": "in", "type": "xsd:int", "fault": 7367, "fault_msg": "laborum nis" }] } ``` ## instances @@ -767,7 +763,7 @@ Device.WiFi. ### Ubus CLI Example ``` -ubus call bbf instances {"path":"veniam mollit occaecat cillum","first_level":true,"optional":{"proto":"cwmp"}} +ubus call bbf instances {"path":"commodo aliqu","first_level":true,"optional":{"proto":"cwmp"}} ``` ### JSONRPC Example @@ -781,7 +777,7 @@ ubus call bbf instances {"path":"veniam mollit occaecat cillum","first_level":tr "", "bbf", "instances", - { "path": "veniam mollit occaecat cillum", "first_level": true, "optional": { "proto": "cwmp" } } + { "path": "commodo aliqu", "first_level": true, "optional": { "proto": "cwmp" } } ] } ``` @@ -843,7 +839,7 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ "results": [{ "path": "labore occaecat a", "fault": 9010, "fault_msg": "Lorem" }] } +{ "results": [{ "path": "ametest minim ut sit ex", "fault": 7415, "fault_msg": "nostrud" }] } ``` ## notify_event @@ -904,7 +900,7 @@ Array type: `array` ### Ubus CLI Example ``` -ubus call bbf notify_event {"name":"eu laboris anim","input":[]} +ubus call bbf notify_event {"name":"Duis dolor officia anim Ut","input":[]} ``` ### JSONRPC Example @@ -914,7 +910,7 @@ ubus call bbf notify_event {"name":"eu laboris anim","input":[]} "jsonrpc": "2.0", "id": 0, "method": "call", - "params": ["", "bbf", "notify_event", { "name": "eu laboris anim", "input": [] }] + "params": ["", "bbf", "notify_event", { "name": "Duis dolor officia anim Ut", "input": [] }] } ``` @@ -1258,7 +1254,7 @@ The value of this property **must** be equal to one of the [known values below]( ### Ubus CLI Example ``` -ubus call bbf operate {"command":"velit magna laboris aliquip culpa","command_key":"voluptate ad cupidatat","input":{},"optional":{"format":"pretty","proto":"usp"}} +ubus call bbf operate {"command":"dolore anim dolor","command_key":"in eiusmod in culpa non","input":{},"optional":{"format":"pretty","proto":"both"}} ``` ### JSONRPC Example @@ -1273,10 +1269,10 @@ ubus call bbf operate {"command":"velit magna laboris aliquip culpa","command_ke "bbf", "operate", { - "command": "velit magna laboris aliquip culpa", - "command_key": "voluptate ad cupidatat", + "command": "dolore anim dolor", + "command_key": "in eiusmod in culpa non", "input": {}, - "optional": { "format": "pretty", "proto": "usp" } + "optional": { "format": "pretty", "proto": "both" } } ] } @@ -1364,11 +1360,11 @@ All items must be of the type: Unknown type ``. { "results": [ { - "path": "commodo dolor laboris", + "path": "eteu veniam fugiat al", "data": "1", - "fault": 7192, - "fault_msg": "non Lorem", - "output": [{ "path": "fugiat in qui", "data": "0", "type": "xsd:string" }] + "fault": 8377, + "fault_msg": "cillum magna", + "output": [{ "path": "irurein", "data": "0", "type": "xsd:boolean" }] } ] } @@ -1570,7 +1566,7 @@ All items must be of the type: Unknown type ``. ### Ubus CLI Example ``` -ubus call bbf schema {"path":"qui dolor nisi","paths":["veniam in dolor deserunt"],"first_level":true,"commands":true,"events":false,"params":false,"optional":{"proto":"cwmp"}} +ubus call bbf schema {"path":"ipsum aliqua","paths":["enim quis laborum"],"first_level":false,"commands":true,"events":false,"params":false,"optional":{"proto":"usp"}} ``` ### JSONRPC Example @@ -1585,13 +1581,13 @@ ubus call bbf schema {"path":"qui dolor nisi","paths":["veniam in dolor deserunt "bbf", "schema", { - "path": "qui dolor nisi", - "paths": ["veniam in dolor deserunt"], - "first_level": true, + "path": "ipsum aliqua", + "paths": ["enim quis laborum"], + "first_level": false, "commands": true, "events": false, "params": false, - "optional": { "proto": "cwmp" } + "optional": { "proto": "usp" } } ] } @@ -1701,13 +1697,13 @@ All items must be of the type: Unknown type ``. { "results": [ { - "path": "pariatur ", - "data": "1", - "type": "xsd:boolean", - "fault": 7493, - "fault_msg": "mollit ", - "input": [{ "path": "aliquip", "data": "1", "type": "xsd:int" }], - "output": [{ "path": "elit est dolor do", "data": "1", "type": "xsd:int" }] + "path": "et sunt id", + "data": "0", + "type": "xsd:command", + "fault": 8958, + "fault_msg": "vel", + "input": [{ "path": "nisi elit amet", "data": "0", "type": "xsd:object" }], + "output": [{ "path": "anim pariatur ipsum et", "data": "1", "type": "xsd:unsignedLong" }] } ] } @@ -1715,7 +1711,7 @@ All items must be of the type: Unknown type ``. ## service -### Register a micro-service in the main service +### show the list of micro-service registred in the core Data Model `service` @@ -1727,105 +1723,23 @@ All items must be of the type: Unknown type ``. | Property | Type | Required | | -------- | ------ | ------------ | -| `input` | object | **Required** | +| `intput` | | Optional | | `output` | object | **Required** | -#### input +#### intput -`input` - -- is **required** -- type: `object` - -##### input Type - -`object` with following properties: - -| Property | Type | Required | -| ----------- | ------ | ------------ | -| `cmd` | string | **Required** | -| `name` | string | Optional | -| `object` | string | Optional | -| `parent_dm` | string | Optional | - -#### cmd - -`cmd` - -- is **required** -- type: reference - -##### cmd Type - -`string` - -The value of this property **must** be equal to one of the [known values below](#service-known-values). - -##### cmd Known Values - -| Value | -| -------- | -| register | -| list | - -#### name - -Name of the micro-service ubus object - -`name` +`intput` - is optional -- type: `string` +- type: complex -##### name Type +##### intput Type -`string` - -#### object - -Name of the micro-service object - -`object` - -- is optional -- type: `string` - -##### object Type - -`string` - -#### parent_dm - -Object path where the micro-service object will be added - -`parent_dm` - -- is optional -- type: `string` - -##### parent_dm Type - -`string` - -### Ubus CLI Example - -``` -ubus call bbf service {"cmd":"list","name":"ex fugiat","parent_dm":"esse ipsum dolore Ut et","object":"sed amet Duis"} -``` - -### JSONRPC Example +Unknown type ``. ```json { - "jsonrpc": "2.0", - "id": 0, - "method": "call", - "params": [ - "", - "bbf", - "service", - { "cmd": "list", "name": "ex fugiat", "parent_dm": "esse ipsum dolore Ut et", "object": "sed amet Duis" } - ] + "simpletype": "complex" } ``` @@ -1840,37 +1754,90 @@ ubus call bbf service {"cmd":"list","name":"ex fugiat","parent_dm":"esse ipsum d `object` with following properties: -| Property | Type | Required | -| -------- | ------- | ------------ | -| `error` | string | Optional | -| `status` | boolean | **Required** | +| Property | Type | Required | Default | +| ---------------- | ------- | -------- | -------- | +| `name` | string | Optional | | +| `object` | string | Optional | | +| `parent_dm` | string | Optional | | +| `proto` | string | Optional | `"both"` | +| `unified_daemon` | boolean | Optional | | -#### error +#### name -`error` +`name` - is optional - type: `string` -##### error Type +##### name Type `string` -#### status +#### object -`status` +`object` -- is **required** +- is optional +- type: `string` + +##### object Type + +`string` + +#### parent_dm + +`parent_dm` + +- is optional +- type: `string` + +##### parent_dm Type + +`string` + +#### proto + +`proto` + +- is optional +- type: reference +- default: `"both"` + +##### proto Type + +`string` + +The value of this property **must** be equal to one of the [known values below](#service-known-values). + +##### proto Known Values + +| Value | +| ----- | +| usp | +| cwmp | +| both | + +#### unified_daemon + +`unified_daemon` + +- is optional - type: `boolean` -##### status Type +##### unified_daemon Type `boolean` ### Output Example ```json -{ "status": true, "error": "eu aliq" } +{ + "name": "incididunt cillum Excepteur ipsum laborum", + "parent_dm": "consectetur Excepteur eiusmod aliqua minim", + "object": "nostrud incididunt", + "proto": "usp", + "unified_daemon": false +} ``` ## set @@ -2072,7 +2039,7 @@ value of the object element provided in path, path should contains valid writabl ### Ubus CLI Example ``` -ubus call bbf set {"path":"occaecat veniam consequa","value":"et Excepteur occaecat fugiat","datatype":"dateTime","obj_path":{}} +ubus call bbf set {"path":"aliqua aliquip","value":"aliqua","datatype":"int","obj_path":{}} ``` ### JSONRPC Example @@ -2082,17 +2049,7 @@ ubus call bbf set {"path":"occaecat veniam consequa","value":"et Excepteur occae "jsonrpc": "2.0", "id": 0, "method": "call", - "params": [ - "", - "bbf", - "set", - { - "path": "occaecat veniam consequa", - "value": "et Excepteur occaecat fugiat", - "datatype": "dateTime", - "obj_path": {} - } - ] + "params": ["", "bbf", "set", { "path": "aliqua aliquip", "value": "aliqua", "datatype": "int", "obj_path": {} }] } ``` @@ -2156,5 +2113,5 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ "results": [{ "path": "cillum Ut laborum proident", "data": "0", "fault": 7277, "fault_msg": "dolore ut aliquip" }] } +{ "results": [{ "path": "in est veniam incididunt", "data": "1", "fault": 7720, "fault_msg": "anim" }] } ``` diff --git a/docs/api/uci/bbfdm.json b/docs/api/uci/bbfdm.json index 040dd480..24a35e95 100644 --- a/docs/api/uci/bbfdm.json +++ b/docs/api/uci/bbfdm.json @@ -46,13 +46,20 @@ "required": "no", "default": "0", "description": "Sets core flag in procd for datamodel microservices" - }, + } + ] + }, + { + "section": "reload_handler", + "description": "bbf_configd Settings", + "multi": false, + "options": [ { - "name": "enable_respawn", - "type": "boolean", + "name": "log_level", + "type": "unsigned integer", "required": "no", - "default": "0", - "description": "Enable respawning of datamodel micro-service process" + "default": "2", + "description": "Log verbosity value as per standard syslog" } ] } diff --git a/docs/api/uci/bbfdm.md b/docs/api/uci/bbfdm.md index 4eeb20ba..af397210 100644 --- a/docs/api/uci/bbfdm.md +++ b/docs/api/uci/bbfdm.md @@ -1,95 +1 @@ -# UCI Config - - - - -
bbfdmd
- - - - - - - - - - - - - - - -
-
section
- 		-
description
- 		-
multi
- 		-
options
-
-
bbfdmd
- 		-
BBFDM daemon Settings
- 		-
false
- 		- - - - - - - - - - - - - - - - - - - - - - - - -
-
name
- 		-
type
- 		-
required
- 		-
default
- 		-
description
-
-
debug
- 		-
boolean
- 		-
no
- 		-
- 		-
Enabled debug logging
-
-
loglevel
- 		-
unsigned integer
- 		-
no
- 		-
3
- 		-
Log verbosity value as per standard syslog
-
-
- - - +
bbfdmd
section
description
multi
options
bbfdmd
BBFDM daemon Settings
false
name
type
required
default
description
enable
boolean
no
1
Enables bbfdmd
debug
boolean
no
Enabled debug logging
loglevel
unsigned integer
no
3
Log verbosity value as per standard syslog
micro_services
Datamodel micro-service
false
name
type
required
default
description
enable
boolean
no
1
Enables bbfdmd
enable_core
boolean
no
0
Sets core flag in procd for datamodel microservices
reload_handler
bbf_configd Settings
false
name
type
required
default
description
log_level
unsigned integer
no
2
Log verbosity value as per standard syslog
\ No newline at end of file diff --git a/docs/guide/bbfdmd.md b/docs/guide/bbfdmd.md index 612d96eb..39495853 100644 --- a/docs/guide/bbfdmd.md +++ b/docs/guide/bbfdmd.md @@ -12,13 +12,15 @@ `bbfdmd` daemon use `libbbfdm-ubus` library to expose datamodel over ubus. -When a ubus method is called it first fills `bbfdm_data_t` structure with the necessary information, then proceeds the `Get/Set/Operate/Add/Del` operation based on that information. +When a ubus method is called it first fills `bbfdm_data_t` structure with the necessary information, then register the micro-services information defined for each JSON service file after that proceeds the `Get/Set/Operate/Add/Del` operation based on that information. To load the datamodel definitions from a DotSO file, it looks for a 'tDynamicObj' symbol and use it to create the base entry object, for datamodel operations it rely on libbbfdm-api's `bbf_entry_method` which process the datamodel operation on input path and produces result in list/blob, which further gets responded over ubus. In short, it covers/supports all methods introduced in `TR-069` and `TR-369` by using the `bbf_entry_method` API from `libbbfdm-api` with the different methods and the existing data-model available with `libbbfdm`. -> Note: In general, bbfdmd does not reload the services after updating the configs, higher layer applications (i.e. icwmp, obuspa) usages `bbf.config` to apply the configs and reloads the services, please check `bbf.config` documentation for more details. +> Note1: In general, bbfdmd does not reload the services after updating the configs, higher layer applications (i.e. icwmp, obuspa) usages `bbf.config` to apply the configs and reloads the services, please check `bbf.config` documentation for more details. + +> Note2: All RPC method's output is stored directly in a blob buffer, which can be used at the end by Ubus reply API to expose the data and reducing CPU usage of `bbfdmd` daemon. ## Input and output Schema(s) @@ -36,16 +38,16 @@ Following are the ubus methods exposed by `bbfdmd` main process: ```bash # ubus -v list bbfdm -'bbfdm' @9e9928ef - "get":{"path":"String","paths":"Array","maxdepth":"Integer","optional":"Table"} - "schema":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} - "instances":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} - "set":{"path":"String","value":"String","obj_path":"Table","optional":"Table"} - "operate":{"command":"String","command_key":"String","input":"Table","optional":"Table"} - "add":{"path":"String","obj_path":"Table","optional":"Table"} - "del":{"path":"String","paths":"Array","optional":"Table"} - "service":{"cmd":"String","name":"String","parent_dm":"String","objects":"Array"} - "notify_event":{"name":"String","input":"Array"} +'bbfdm' @b93b62aa + "get":{"path":"String","paths":"Array","maxdepth":"Integer","optional":"Table"} + "schema":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} + "instances":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} + "set":{"path":"String","value":"String","datatype":"String","obj_path":"Table","optional":"Table"} + "operate":{"command":"String","command_key":"String","input":"Table","optional":"Table"} + "add":{"path":"String","obj_path":"Table","optional":"Table"} + "del":{"path":"String","paths":"Array","optional":"Table"} + "notify_event":{"name":"String","input":"Array"} + "service":{} ``` > Note1: `optional` table are present in all methods and it supports below options: diff --git a/docs/guide/dm-service.md b/docs/guide/dm-service.md index 5c749f7c..6bc9249c 100644 --- a/docs/guide/dm-service.md +++ b/docs/guide/dm-service.md @@ -6,7 +6,7 @@ ## Concepts and Workflow -`dm-service` daemon gets started by `/etc/init.d/bbfdm.services` service. This init script reads input from `bbfdm` UCI file, particularly from `micro_services` section. It then parses each micro-service configuration file located in `/etc/bbfdm/micro_services/`. Each micro-service’s configuration, written in JSON, is used to start the service using the APIs provided by `libbbfdm-ubus` and `libbbfdm-api` libraries. +`dm-service` daemon gets started by `/etc/init.d/bbfdm.services` service. This init script reads input from `bbfdm` UCI file, particularly from `micro_services` section. It then parses each micro-service configuration file located in `/etc/bbfdm/services/`. Each micro-service’s configuration, written in JSON, is used to start the service using the APIs provided by `libbbfdm-ubus` and `libbbfdm-api` libraries. `dm-service` daemon use `libbbfdm-api` library to traverse the datamodel tree defined by DotSo or JSON plugin located in `/usr/share/bbfdm/micro_services/$micro-service-name{.so,.json}` and its plugins defined in `/usr/share/bbfdm/micro_services/$micro-service-name/`. @@ -23,23 +23,72 @@ Datamodel micro-service is nothing but another `bbfdmd` instance running with sm 12167 root 7800 S {dm_ethmngr} /usr/sbin/dm-service -m ethmngr -l 3 ``` -Each `dm-service` instance must be started with -m input to define its service name and run its module(sub-tree) datamodel. These micro-services exposed their own ubus objects +Each `dm-service` instance must be started with -m input to define its service name and run its module(sub-tree) datamodel. These micro-services exposed their own ubus objects. ```bash # ubus list bbfdm.* -bbfdm.Bridging -bbfdm.BulkData -bbfdm.DHCPv4_DHCPv6 -bbfdm.DNS +bbfdm.bridgemngr +bbfdm.bulkdata +bbfdm.ddnsmngr +bbfdm.dhcpmngr +bbfdm.dnsmngr +bbfdm.ethmngr +bbfdm.firewallmngr ``` -When a datamodel started as micro-service, it looks/waits for `bbfdm` UBUS object(added by main `bbfdmd` process), once its available micro-service registers with the main `bbfdmd` process by calling the 'service' method +## Setting Up a Datamodel as a Micro-Service + +Before starting a datamodel as a micro-service, ensure that the datamodel definition file is correctly placed and configured. The file should be located at: +`/etc/bbfdm/services/${micro_service_name}.json`. + +This file must include the following required fields: + +- service_name: The name of the service. +- unified_daemon: A boolean indicating whether the service uses a unified daemon. +- services: An array containing sub-options: + - parent_dm: Specifies the parent data model. + - object: Defines the object type. + - proto: Indicates the protocol (e.g., cwmp, both). + +Once all required fields are defined, the datamodel can be registered and started when the `bbfdmd` is initialized + + +## Verifying Micro-Service Registration + +After defining the datamodel, wait for the `bbfdmd` to start. Then, verify that the micro-service has been successfully registered to the core data model. You can do this by listing the registered services using the following command: ```bash -# ubus -v list bbfdm -'bbfdm' @e970413c - "service":{"cmd":"String","name":"String","parent_dm":"String","objects":"Array"} +# ubus call bbfdm service +{ + "registered_service": [ + { + "name": "bbfdm.bridgemngr", + "parent_dm": "Device.", + "object": "Bridging", + "proto": "both", + "unified_daemon": false + }, + { + "name": "bbfdm.bulkdata", + "parent_dm": "Device.", + "object": "BulkData", + "proto": "cwmp", + "unified_daemon": true + }, + { + "name": "bbfdm.ddnsmngr", + "parent_dm": "Device.", + "object": "DynamicDNS", + "proto": "both", + "unified_daemon": false + } +} ``` +In this example: + +- Each entry in `registered_service` represents a micro-service. +- Verify that your service is included in this list, and that its properties (`name`, `parent_dm`, `object`, `proto`, `unified_daemon`) are correctly configured. + ## Input and output Schema(s) @@ -48,7 +97,7 @@ When a datamodel started as micro-service, it looks/waits for `bbfdm` UBUS objec - [datamodel micro-service](../api/ubus/bbfdm_micro_service.md) - [datamodel micro-service schema](../api/ubus/bbfdm_micro_service.json) -Apart from these, datamodel micro-services can also be configured by updating their input files directly at runtime, micro-service input files present in `/etc/bbfdm/micro_services/` in CPE. +Apart from these, datamodel micro-services can also be configured by updating their input files directly at runtime, micro-service input files present in `/etc/bbfdm/services/` in CPE. A typical micro-service input file looks like below: @@ -56,15 +105,21 @@ A typical micro-service input file looks like below: { "daemon": { "enable": "1", - "service_name": "netmngr", + "service_name": "bulkdata", + "unified_daemon": true, + "services": [ + { + "parent_dm": "Device.", + "object": "BulkData", + "proto": "cwmp" + } + ], "config": { "loglevel": "3" - }, - "output": { - "name": "Network" } } } + ``` ### Ubus methods @@ -122,7 +177,17 @@ When not to use micro-service: ### How to Use micro-service Manually configuring and starting a micro-services requires multiple steps, but its made simple by using `bbfdm.mk` compile time helper utility. -To launch a datamodel definition as a datamodel micro-service, user need to install the datamodel definition/plugin using + +First of all, To register a datamodel definition as a datamodel micro-service, user needs to register the datamodel definition/plugin using + +`BBFDM_REGISTER_SERVICES` API from `bbfdm.mk` + +```bash +bulkdata/Makefile: $(BBFDM_REGISTER_SERVICES) ./bbfdm_service.json $(1) $(PKG_NAME) +ddnsmngr/Makefile: $(BBFDM_REGISTER_SERVICES) ./bbfdm_service.json $(1) $(PKG_NAME) +``` + +Then to launch a datamodel definition as a datamodel micro-service, user needs to install the datamodel definition/plugin using `BBFDM_INSTALL_MS_DM` API from `bbfdm.mk` @@ -134,7 +199,7 @@ ddnsmngr/Makefile: $(BBFDM_INSTALL_MS_DM) $(PKG_BUILD_DIR)/src/libddnsmngr. Please check [bbfdm.mk](https://dev.iopsys.eu/feed/iopsys/-/blob/devel/bbfdm/bbfdm.mk) documentation for more details. -In Devices, datamodel micro-services started and managed by `/etc/init.d/bbfdm.services` init script, which reads the global micro-service related configuration from `bbfdm` uci file, and reads module specific configuration for each module's input file present in `/etc/bbfdm/micro_services/` directory. +In Devices, datamodel micro-services started and managed by `/etc/init.d/bbfdm.services` init script, which reads the global micro-service related configuration from `bbfdm` uci file, and reads module specific configuration for each module's input file present in `/etc/bbfdm/services/` directory. > In plugins approach, the 3rd party datamodel gets attached to main bbfdm process, which further increases nodes in main datamodel tree, which overtime become a huge tree, results in slower turn around service time for the APIs. Also, any unhandled fault in plugin result in segfault in main bbfdmd process, which takes down the whole tree along with plugin, resulting in complete failure from cwmp and USP, with micro-services plugins runs as an individual processes, so impact of fault limited to its own micro-service only. @@ -145,16 +210,36 @@ Micro-service approach, disintegrate the plugins further and run them as individ To configure the log_level in micro-service, update the `loglevel` module json file, ```json -# cat /etc/bbfdm/micro_services/netmngr.json +# cat /etc/bbfdm/services/netmngr.json { "daemon": { "enable": "1", "service_name": "netmngr", + "unified_daemon": false, + "services": [ + { + "parent_dm": "Device.", + "object": "IP" + }, + { + "parent_dm": "Device.", + "object": "GRE" + }, + { + "parent_dm": "Device.", + "object": "PPP" + }, + { + "parent_dm": "Device.", + "object": "Routing" + }, + { + "parent_dm": "Device.", + "object": "RouterAdvertisement" + } + ], "config": { "loglevel": "7" - }, - "output": { - "name": "Network" } } } diff --git a/docs/guide/libbbfdm-ubus.md b/docs/guide/libbbfdm-ubus.md index b5fdfe23..74dfa72c 100644 --- a/docs/guide/libbbfdm-ubus.md +++ b/docs/guide/libbbfdm-ubus.md @@ -8,7 +8,7 @@ - `bbfdmd`: to expose the core data model - `dm-service`: to expose a sub-data model as micro-service, example: [Netmngr](https://dev.iopsys.eu/network/netmngr/-/blob/devel/src/net_plugin.c) - - Higher-level applications: to expose custom data models as microservices within their daemon, example: [Timemngr](https://dev.iopsys.eu/bbf/timemngr/-/blob/devel/src/main.c) + - Higher-level applications(unified daemon): to expose custom data models as microservices within their daemon, example: [Timemngr](https://dev.iopsys.eu/bbf/timemngr/-/blob/devel/src/main.c) ## libbbfdm-ubus APIs @@ -104,16 +104,16 @@ Following are the ubus methods exposed by `libbbfdm-ubus` when registering a new ```bash # ubus -v list bbfdm -'bbfdm' @9e9928ef - "get":{"path":"String","paths":"Array","maxdepth":"Integer","optional":"Table"} - "schema":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} - "instances":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} - "set":{"path":"String","value":"String","obj_path":"Table","optional":"Table"} - "operate":{"command":"String","command_key":"String","input":"Table","optional":"Table"} - "add":{"path":"String","obj_path":"Table","optional":"Table"} - "del":{"path":"String","paths":"Array","optional":"Table"} - "service":{"cmd":"String","name":"String","parent_dm":"String","objects":"Array"} - "notify_event":{"name":"String","input":"Array"} +bbfdm' @b93b62aa + "get":{"path":"String","paths":"Array","maxdepth":"Integer","optional":"Table"} + "schema":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} + "instances":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} + "set":{"path":"String","value":"String","datatype":"String","obj_path":"Table","optional":"Table"} + "operate":{"command":"String","command_key":"String","input":"Table","optional":"Table"} + "add":{"path":"String","obj_path":"Table","optional":"Table"} + "del":{"path":"String","paths":"Array","optional":"Table"} + "notify_event":{"name":"String","input":"Array"} + "service":{} ``` ## libbbfdm-ubus example(s) diff --git a/gitlab-ci/install-dependencies.sh b/gitlab-ci/install-dependencies.sh index 899e26bb..44a65fc7 100755 --- a/gitlab-ci/install-dependencies.sh +++ b/gitlab-ci/install-dependencies.sh @@ -24,7 +24,7 @@ if [ -z "${1}" ]; then echo "Skip installation of micro-services ...." else # Create directories for micro-service configuration and shared files - mkdir -p /etc/bbfdm/micro_services + mkdir -p /etc/bbfdm/services mkdir -p /usr/share/bbfdm/micro_services #install SYSMNGR Data Model as a micro-service diff --git a/gitlab-ci/shared.sh b/gitlab-ci/shared.sh index 740a23bc..8cfc337b 100755 --- a/gitlab-ci/shared.sh +++ b/gitlab-ci/shared.sh @@ -131,7 +131,7 @@ function install_wifidmd_as_micro_service() exec_cmd mkdir -p /usr/share/bbfdm/micro_services/wifidmd exec_cmd cp -f /opt/dev/wifidmd/src/libdataelements.so /usr/share/bbfdm/micro_services/wifidmd - generate_input_schema_with_output_name "wifidmd" "WiFi" > /etc/bbfdm/micro_services/wifidmd.json + generate_input_schema_with_output_name "wifidmd" "WiFi" > /etc/bbfdm/services/wifidmd.json } function install_netmngr_as_micro_service() @@ -145,7 +145,7 @@ function install_netmngr_as_micro_service() exec_cmd cp -f /opt/dev/netmngr/src/libinterface_stack.so /usr/share/bbfdm/plugins exec_cmd mkdir -p /usr/share/bbfdm/micro_services/netmngr - generate_input_schema_with_output_name "netmngr" "Network" > /etc/bbfdm/micro_services/netmngr.json + generate_input_schema_with_output_name "netmngr" "Network" > /etc/bbfdm/services/netmngr.json exec_cmd git clone https://dev.iopsys.eu/bbf/tr143d.git /opt/dev/tr143d exec_cmd make -C /opt/dev/tr143d/src/ clean && make -C /opt/dev/tr143d/src/ diff --git a/utilities/README.md b/utilities/README.md index 7e3fa85b..08d0feec 100644 --- a/utilities/README.md +++ b/utilities/README.md @@ -78,3 +78,71 @@ Currently have two variants of bbf.config, which can be enabled with below compi 1. CONFIG_BBF_CONFIGMNGR_SCRIPT_BACKEND => Simple rpcd script based backend 2. CONFIG_BBF_CONFIGMNGR_C_BACKEND => C based application backend with PID monitoring (default) + +### bbf.config Supported methods + +`bbf.config` provides several methods for managing and monitoring configuration changes in services. These methods can be accessed using the ubus command. + +```bash +$ ubus -v list bbf.config +'bbf.config' @da2cc0d9 + "commit":{"services":"Array","proto":"String","reload":"Boolean"} + "revert":{"services":"Array","proto":"String","reload":"Boolean"} + "changes":{"services":"Array","proto":"String","reload":"Boolean"} +``` +#### bbf.config commit method: + +This method commits configuration changes to the specified services based on the given `proto` option (protocol). It reloads services according to `reload` option but handles critical services differently. + +The Critical services are defined in `/etc/bbfdm/critical_services.json` file. +- If a service is critical, the process waits until the service's timeout expires or the service's PID changes and then it does reload the service. +- Non-critical services are reloaded immediately. + +Critical Services File + +The following file defines critical services for each protocol: + +```bash +cat /etc/bbfdm/critical_services.json +{ + "usp": [ + "firewall", + "network", + "dhcp", + "wireless", + "time" + ], + "cwmp": [ + "firewall", + "network", + "dhcp", + "stunc", + "xmpp", + "wireless", + "time" + ] +} +``` + +#### bbf.config revert method: +this method commits the changes in the required services based on proto option. + +#### bbf.config changes method: + +this method provides the list of certical services based on protocol (proto option) and provide the available config changes based on protocol. +```bash +ubus call bbf.config changes '{"proto":"usp"}' +{ + "configs": [ + "users", + "wireless" + ], + "critical_services": [ + "firewall", + "network", + "dhcp", + "wireless", + "time" + ] +} +```