mirror/icwmp
1
0
Fork 0
mirror of https://dev.iopsys.eu/bbf/icwmp.git synced 2025-12-10 07:44:41 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Added design document

Browse source
This commit is contained in:
Omar Kallel 2023-02-22 03:49:01 +00:00 • committed by Vivek Kumar Dutta
parent 2b067844c3
commit 177a540c8f
7 changed files with 438 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
README.md
View file

@ -63,6 +63,7 @@ uci commit cwmp
* [Supported RPC Methods](./docs/guide/supported_rpc.md)
* [UBUS methods](./docs/guide/ubus_method.md)
* [Command Line Interface](./docs/guide/cli.md)
* [icwmp design](./docs/design.md)
## Dependencies

187
docs/design/design.md Executable file
View file

@ -0,0 +1,187 @@
# Design of icwmp tr-069 client
## General Description
icwmp is client side implementation of CWMP protocol. Its source code is completely conform with TR-069 standard. So it supports all required features described in the TR-069 standard.
So TR-069 features like cwmp session, events management, soap management, RPC methods management ... are supportd in the icwmp implementation.
As descibed in TR-069 standard, CWMP stack comprises several components that are unique to this protocol, and makes use of several standard protocols. Those components are followings:
<table>
<tr><td>
|<div>CWMP Stack </div> and icwmp corresponding source files|
|--|
|__Application__ cwmp.c session.c|
|__RPC Methods__ rpc.c||
|__SOAP__ xml.c|
|__HTTP__ http.c digauth.c|
|__SSL/TLS__ ssl_utils.c|
</td><td>
|Common Source files|
|--|
|<div>backup_session.c </div><div> cwmp_uci.c </div><div> ubus_utils.c </div><div> subprocess.c </div><div> common.c </div><div> config.c </div><div> datamodel_interface.c </div><div> diagnostic.c </div><div> download.c </div><div> upload.c </div> notifications.c|
</td></tr> </table>
- Application: the application uses CWMP protocol on the CPE. In the icwmp client, the main application is defined in cwmp.c source file. It's based on uloop libubox functionality. Multiple timers are running under the main uloop of icwmp like session timer, ubus timer, heartbeat timer, ...
- RPC methods: The specific RPC methods that are defined by CWMP protocol. In icwmp client RPC methods are defined under the source file rpc.c.
- SOAP: A standard XML-based syntax used here to encode remote procedure calls. The SOAP part is developed in xml.c file and it's detailed in the section ...
- HTTP: this part is responsible to send SOAP messages over HTTP. In icwmp it's based on libcurl library. Its corresponding C functions are developed in the file http.c.
- SSL/TLS: The standard Internet transport layer security protocol. icwmp can work with openssl or mbedtls or wolfssl depending on the SSL library selection. Its corresponding functions are defined in ssl_utils.c file.
## Main structure of icwmp app
The main structure in icwmp is the cwmp structure. Just one instance of cwmp structure is needed for the executing icwmp app.
The following schema presents this sctructure with the most important attributes:
```mermaid
classDiagram
class cwmp {
conf: struct config
deviceid: struct deviceid
session: struct session
heart_session: bool
diag_session: bool
event_id: int
cr_socket_desc: int
pid_file: FILE
}
```
- conf: its type is the config structure. config structure is responsible to define the UCI configuration of the application and it's loaded in the start of icwmp. Multiple UCI options are defined in this structure such as configurations related to the CPE like CR credentials, CR port, provisioning code ... and configurations related to the ACS connection like ACS access username/password, periodic_inform_enable, periodic_inform_interval ...
- heart_session: is a boolean attribute. This attribute is used to check if the running session is a Heartbeat session.
- diag_session: is a boolean attribute. This attribute is used to check if the running session contains the event '8 DIAGNOSTICS COMPLETE'
- event_id: is an integer attribute, and is used by the app to store the number of events in the running session.
- cr_socket_des: is an integer attribute. This attribute contains the id of the socket used by the CR.
- pide_file: is a File type attribute. This file used by the app in order to garantuate a single app instance running.
- deviceid: its type is deviceid structure. This struct contains the device information important attributes values: OUI, Manufacturer, SerialNumber, ProductClass, SoftwareVersion.
- session: its type is session structure. This structure contains attributes related to the running application.
```mermaid
classDiagram
class session {
head_rpc_cpe: list
head_rpc_acs: list
events: list
session_status: struct session_status
tree_in: mxml_node_t
tree_out: mxml_node_t
body_in: mxml_node_t
fault_code: int
}
```
session attributes are:
- head_rpc_cpe: its type is struct list_head. It contains RPC methods list that needs to be executed by the CPE in the actual session.
- head_rpc_acs: its type is struct list_head. It contains RPC methods list that the CPE requests to be executed in the ACS side in the actual session.
- events: its type is struct list_head. It contains list of events that the CPE notifies the ACS in the Inform message of the actual session.
- session_status: its type is struct session_status. it contains informations about the running session like start time, end time, if it's successful or failed session, hearbeat session validation ...
## icwmp application
The following diagram shows how icwmp application manage CWMP sessions with uloop:
```mermaid
flowchart TD
A[icwmp init] --> B[uloop init]
A --> C[CR http server init]
B --> D{wait uloop timeout}
D -- ubus timeout --> E[receive tr069 method call]
D -- periodic timeout --> F[Add '2 PERIODIC' event to the list of events]
F --> G[Execute CWMP session]
G --> H[trigger check value change timeout]
H --> D
E --> I{the method is Inform}
I -- yes --> G
I -- no --> J[Execute the ubus method]
J --> D
C --> K[Start CR server thread]
K --> L[listen to coming HTTP requests in the CR port]
L --> M{CR is received}
M -- yes --> E
M -- no --> L
```
As described in the diagram, after initiating the icwmp application (config init, backup init, ...), the application trigger:
1 - uloop initiation by initiating the following timeouts:
- ubus methods timeout
- autonomous policy timeouts
- session timeout
- heartbeat timeout
- periodic session timeout
then the application start the uloop run by waiting uloop timeouts to come.
two kinds of timeouts can be detected:
2 - In the same time a thread is created. It permits a permenant listening of the port , in the purpose to receive connection requests.
In case a CR is received successfully "tr069 inform" ubus call is triggered from this thread in the purpose to trigger a new session with '6 CONNECTION REQUEST' event.
## icwmp tr-069 session
[CWMP session in icwmp client](./session.md)
## Inform ACS method
The Inform ACS request is sent by the CPE to the ACS in the start of the CWMP session, in order to inform him about some informations like the device id, events, software version, the CR url ...
In icwmp the corresponding function responsible to create the Inform message is cwmp_rpc_acs_prepare_message_inform. It starts by getting the device ID attributes and the list of events that needs to be included in the inform message and then parameters that are amended in the ParameterList including default Inform Parameter and other parameters like parameters related to the Value Change.
## Events manipulation
As described in TR069 standard, events in CWMP protocol must be sent by the CPE in an Inform request in order to notify the ACS when something of interest has happened.
In icwmp when creating the inform message events are loaded from events list_head attribute of the session structure attribute.
As soon as the event is reached, it's added to the list events. Different scenarios are presents to reach event in icwmp:
- Start app events: this scenario includes following events: "0 BOOTSTRAP" (if it's the first Inform to be sent to the specified ACS), "1 BOOT"
- Get the event from the backupSession in the start of the App: Just after starting the icwmp app in the init step, the app loads the backupsession events in events list from "cwmp_event" xml tag. Then add the to the events list. This case includes events that occurs before the restart of the icwmp or reboot/upgrade of the system. In this scenario events included are: "M Reboot", "M Download", "M ScheduleDownload", "7 TRANSFER COMPLETE".
- Events when running CWMP session. Events for this scenario are detected and added to the events while executing the CWMP session especially in RPC calls. Such as "3 SHEDULED" for ScheduleInform method, "7 TRANSFER COMPLETE" (in the call of Download, Upload), "8 DIAGNOSTIC COMPLETE" (after completing diagnostic execution triggered by the ACS), "11 DU STATE CHANGE COMPLETE" after completing CDU request execution triggered by the ACS), "M Download", "M Upload" ...
- Events are detected at specific time using uloop_timeout_set:"2 PERIODIC", "14 HEARTBEAT"
- External Events: "6 CONNECTION REQUEST" when receiving a connection request from the ACS in order to start a new session. CR thread is permenantly listening on the CR port in order to detect such event and then trigger a new session. "4 VALUE CHANGE" (check notifications part), "10 AUTONOMOUS Single TRANSFER COMPLETE", "12 AUTONOMOUS DU STATE CHANGE COMPLETE"
### Notifications
[Notifications in icwmp client](./notifications.md)
## XML in icwmp
__TODO__
xml structures: struct xml_node_data, struct xml_tag, struct xml_list_data, struct xml_data_struct, struct xml_tag_validation
struct xml_node_data xml_nodes_data[] array
xml load functions: load_xml_node_data, load_xml_list_node_data, load_single_xml_node_data
build_xml_node_data: build_xml_list_node_data, build_single_xml_node_data
## Backup Session management
**TODO**
Methods that needs backupsession
find node by id
insert functions
load functions
## UCI and config mangement
**TODO**

113
docs/design/notifications.md Normal file
View file

@ -0,0 +1,113 @@
# Notifications in icwmp client
Notifications in TR-069 standard are used by the CPE to notify the ACS about parameters value change.
Notifications in CWMP protocol are based on three things:
- SetParameterAttributes RPC method
- GetParameterAttributes RPC method
- '4 VALUE CHANGE' event
Parameters notifications in icwmp are stored in /etc/icwmpd/cwmp_notifications uci package the notifications section.
Seven possible uci list can be present under the notifications section: disabled , passive, active, passive_lw, passive_passive_lw, active_lw, passive_active_lw
## SetParameterAttributes RPC method
cwmp_set_parameter_attributes is the C function that is executed in case the SetParameterAttributes is called by the ACS. Its activity diagram is the following:
```mermaid
flowchart TD
A[Check valid parameter_name] --> B{fault?}
B -- no --> C{parameter_name is forced notification}
B -- yes --> D[return 9005]
D --> H[END]
C -- no --> E[update_notifications_list => update_ret]
C -- yes --> D1[return 9009]
D1 --> H
E --> F{update_ret == true}
F -- yes --> G[Add parameter_name to suitable notifications uci list]
F -- no --> H
```
Two input arguments are present for this function: the parameter_name and the notification value.
As a first step the SPA function check if the parameter path is valid, then it checks if it's a forced notifications parameter. After that it checks if the notifications lists need to be updated by the call of the function **update_notifications_list**, if yes the input parameter is added to the suitable notification uci list.
The following decribe the algorithm of the function **update_notifications_list**:
```mermaid
flowchart TD
A[Iterate notifications list => param_iter notif_iter] --> B{param_name == param_iter && notification != notif_iter}
B -- no --> C{param_iter is suboject of param_name}
B -- yes --> D[Delete param_iter from the notifications list]
C -- no --> E{End iterations?}
C -- yes --> F[update_ret = false]
F --> E
E -- yes --> G[return update_ret]
E -- no --> A
```
Two input arguments are present: the parameter name and the notification.
update_ret is the output value to indicate if notification value needs to be updated in the uci list. Its default value is true.
All parameters under all present notifcations list are iterated one by one. While iterating all sub-parameters of the input parameter that has notification different from the input are deleted from their list.
false value is affected to update_ret only if the parameter_name parameter is subobject of already existing object and with the same requested notification.
## GetParameterAttributes RPC method
cwmp_get_parameter_attributes is the C function that is executed in case the GetParameterAttributes is called by the ACS. Its input argument is the requester parameter name: param_name. Its activity diagram is the following:
```mermaid
flowchart TD
A[check valid parameter path of param_name] --> B{valid?}
B -- yes --> C[get_parameter_family_notifications of param_name => ret_notif, children_notif]
B -- no --> D[END]
C --> E[GPV of param_name => list_params]
E --> F[iterate of list_params => param_iter]
F --> G{param_iter is forced notification => force_notif}
G -- no --> H{param_iter is among children notif => child_notif}
H -- yes --> I[Assign to param_iter child_notif as notification]
G -- yes --> J[Assign to param_iter for_notif as notification]
H -- no --> K[Assign to param_iter ret_notif as notification]
I --> L{End iterations?}
J --> L
K --> L
L -- no --> F
L -- yes --> M[return the list of parameters with notifications]
```
As a first step the GPA function check if the parameter path is valid, after that it calls the function get_parameter_family_notifications that has the below algorithm. This function permits to get the list of all childs parameters notifications of parameter_name presents in uci notifications list. Its input argument is the requester parameter name: param_name.
```mermaid
flowchart TD
A[iterate parameters_notifications list => param_iter notif_iter] --> B{param_name is subobject of param_iter or param_name == param_iter}
B -- no --> C{param_iter is subobject of param_name}
B -- yes --> D[notif_ret = notif_iter]
C -- yes --> E[Add param_iter,notif_ret to children_list]
E --> F{End iterations?}
C -- no --> F
D --> F
F -- yes --> G[return notif_ret and children_list]
F -- no --> A
```
The function trigger an iteration of parameters under the requested parameter parameter_name, for each parameter it gets its notification and the parameter with its notification to the result list.
## VALUE CHANGE event
**TODO**
## check_value_change
**TODO**
## update parameter notifications list
**TODO**

123
docs/design/session.md Normal file
View file

@ -0,0 +1,123 @@
# CWMP session in icwmp client
In icwmp client, the CWMP session is executed under a uloop timeout handler that calls the C function responsible on the CWMP session execution: start_cwmp_session that has the following activity diagram:
```mermaid
flowchart TD
A[init cwmp session] --> B[check notification value change]
B --> C{value change?}
C -- no --> D[send Inform Request to the ACS]
C -- yes --> E[Add '4 VALUE CHANGE' and corresponding parameters to the Inform message]
E --> D
D --> F[Receive Inform Response from the ACS]
F --> G[Parse rest of other ACS methods list]
G --> H{End of ACS methods list?}
H -- no --> G
H -- yes --> I[Send empty HTTP message to the ACS]
I --> J[Receive HTTP Request from the ACS]
J --> K[Is request body empty]
K -- yes --> N[Execute end session function]
N --> O[exit session]
K -- no --> L[Execute CPE method]
L --> M[Send CPE method response to the ACS]
M --> J
```
The CWMP session starts by initiating. The session initialisation contains essentially:
- The uci initialisation
- RPC ACS methods list initialisation
After that it checks if values of active/passive parameters are changed. Then it parses the RPC ACS methods list and starts with Inform method by sending its corresponding SOAP message in a HTTP Request to the ACS and then receives its corresponding response.
Then it completes following the other ACS methods in the list and make send/receive to the ACS.
In the next step the session sends an empty message to the ACS, therefore it starts receiving the RPC CPE methods requests from the ACS until it receives an empty message from the ACS. After that, after completing the execution of CPE methods Requests it execute the end session tasks (run_session_end_func), that includes all tasks that are requested in the session and need to be complete execution in the end session, like reloading config, restart services, download and apply files ...
In the last step the session completes by exiting. The session exit contain essentially:
- uci exit
- memory clean
- rpc methods list clean
## RPC ACS methods
RPC ACS methods are called just after initiating the session. It starts by the call of Inform method then GetRPCMethods. after that it complete other methods in the head_rpc_acs list.
In icwmp RPC ACS methods are defined in the array rpc_acs_methods of the structure rpc_acs_method.
```mermaid
classDiagram
class rpc_acs_method {
name: string
prepare_message: function
parse_message: function
}
```
- name: is a string attribute. It contains the name the RPC.
- prepare_message: it's a function attribute. This function is responsible to create the SOAP message that will be sent as the RPC method call to the ACS.
- parse_response: it's a function attribute. This function is responsible to to parse the SOAP message coming from the ACS
RPC ACS method is executed in a process respecting the tr-069 protocol layer as described in the following communication diagram:
```mermaid
graph RL
A[RPC] --> |2 related data| B[SOAP]
A --> |1 execute related routine and get data| A
B --> |3 prepare rpc soap message| B
B --> |4 SOAP RPC call| C[HTTP]
C --> |5 HTTP request| D[ACS]
D --> |6 HTTP response| C
C --> |7 SOAP RPC response message| B
```
The RPC ACS call starts by preparing needed data after executing some features in RPC layer. Features that are executed differs from ACS method to an other:
- **Inform**
Data present in the Inform call message are gotten form runtime variables and lists like events and also by execting internal get value (ubus usp.raw call) of some parameters for DeviceId and ParameterList.
- **TransferComplete**
Transfer complete data can be gotten from backup session (in case of reboot or sysupgrade) or internal variables
- **AutonomousTransferComplete and AutonomousDUStateChangeComplete**
Corresponding data are gotten from when receiving the ubus event usp.event.
After getting needed data, the corresponding RPC ACS prepare_message prepare the SOAP message that will be after that integrating as a body of a HTTP Request message. Then using curl library the HTTP layer part sends the HTTP Request to the ACS..
In the next step after the CPE receive the HTTP response from the ACS, it extracts the SOAP message and then needed data from the SOAP message.
## RPC CPE methods
In icwmp RPC CPE methods are defined in the array rpc_cpe_methods of the structure rpc_cpe_method.
```mermaid
classDiagram
class rpc_cpe_method {
name: string
prepare_message: function
parse_message: function
}
```
- name: is a string attribute. It contains the name the RPC.
- handler: the corresponding the handler function responsible to extract data from the SOAP message and then execute corresponding features
RPC CPE method is executed in a process respecting the tr-069 protocol layer as described in the following communication diagram:
```mermaid
graph LR
A[ACS] --> |1 HTTP Request| B[HTTP]
B --> |2 SOAP RPC call| C[SOAP]
C --> |3 extract RPC call| C
C --> |4 extracted data| D[RPC]
D --> |5 execute corresponding RPC features| D
D --> |6 Result data| C
C --> |7 Build SOAP response message| C
C --> |8 SOAP RPC response| B
B --> |9 HTTP response| A
```
The scenario starts by receiving the HTTP Request from the ACS. The HTTP body should be a SOAP RPC call message. The RPC method and its arguments are extracted from the SOAP message in the SOAP layer. Basing on this extracted data the corresponding function is executed in the RPC layer.
After that the SOAP component received returned and build the SOAP RPC response and it's encapsulated in a HTTP message and sent by curl as HTTP response to the ACS.

1
src/common.h
View file

@ -159,7 +159,6 @@ typedef struct cwmp {
bool diag_session;
int prev_periodic_interval;
int prev_heartbeat_interval;
int count_handle_notify;
int retry_count_session;
FILE *pid_file;
time_t start_time;

16
src/notifications.c
View file

@ -98,6 +98,7 @@ char *check_valid_parameter_path(char *parameter_name)
char *error = NULL;
LIST_HEAD(parameters_list);
/*check if parameter name is valid parameter path*/
error = cwmp_get_parameter_names(parameter_name, true, &parameters_list);
if (error != NULL && strcmp(error, "9003") == 0)
@ -111,6 +112,8 @@ char *check_valid_parameter_path(char *parameter_name)
/*
* SetParameterAttributes
*/
// Add parameter_name to the suitable notifications list
int add_uci_option_notification(char *parameter_name, int notification)
{
char *notification_type = NULL;
@ -165,14 +168,19 @@ bool update_notifications_list(char *parameter_name, int notification)
if (parameter_name == NULL)
parameter_name = "Device.";
/*
* Parse all possible lists of of notifications one by one
*/
for (i = 0; i < 7; i++) {
int option_type;
option_type = cwmp_uci_get_option_value_list("cwmp_notifications", "@notifications[0]", notifications[i], UCI_ETCICWMPD_CONFIG, &list_notif);
if (list_notif) {
uci_foreach_element_safe(list_notif, tmp, e) {
if (e->name == NULL)
continue;
ename = strdup(e->name);
if ((strcmp(parameter_name, e->name) == 0 && (i != notification)) || parameter_is_subobject_of_parameter(parameter_name, e->name))
cwmp_uci_del_list_value("cwmp_notifications", "@notifications[0]", notifications[i], e->name, UCI_ETCICWMPD_CONFIG);
if (ename && (strcmp(parameter_name, ename) == 0 || parameter_is_subobject_of_parameter(ename, parameter_name) ) && (i == notification))
@ -196,14 +204,18 @@ char *cwmp_set_parameter_attributes(char *parameter_name, int notification)
if (parameter_name == NULL)
parameter_name = "Device.";
/*Check if the parameter name is present in TR-181 datamodel*/
error = check_valid_parameter_path(parameter_name);
if (error != NULL)
return error;
/*Mustn't set notifications for forced notifications parameter*/
if (check_parameter_forced_notification(parameter_name))
return "9009";
/*checks if the notifications lists need to be updated*/
if (update_notifications_list(parameter_name, notification) == true)
add_uci_option_notification(parameter_name, notification);
@ -294,10 +306,10 @@ char *cwmp_get_parameter_attributes(char *parameter_name, struct list_head *para
continue;
}
notif_leaf = get_parameter_leaf_notification_from_childs_list(param_value->name, &childs_notifs);
if (notif_leaf == -1) {
if (notif_leaf == -1) { //param_value is not among childs_notifs
add_dm_parameter_to_list(parameters_list, param_value->name, "", "", notification, false);
}
else {
else { //param_value is among childs_notifs
add_dm_parameter_to_list(parameters_list, param_value->name, "", "", notif_leaf, false);
}
}

1
src/session.h
View file

@ -39,7 +39,6 @@ typedef struct session {
mxml_node_t *tree_out;
mxml_node_t *body_in;
bool hold_request;
bool digest_auth;
int fault_code;
int error;
} session;