31 KiB
UBUS Methods
uspd needs to be started on startup after ubusd, as it exposes the data-model
objects over ubus. By default(when granularity is not set in uci), uspd registers
below two namespaces with ubus.
root@iopsys:~# ubus list |grep usp
usp
usp.raw
usp namespace is to provide the output as required by End User or in pretty format,
whereas usp.raw namespace is to provide output in raw JSON format for easy API integration,
which can be used by other USP front-end applications(like: obuspa, icwmp).
usp namespace has fewer methods defined to provide a simple interface to end users,
whereas usp.raw has more features/methods to provide more customization options.
Default namespace with functionalities:
root@iopsys:~# ubus -v list usp
'usp' @78f3eaca
"list_operate":{}
"get":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"object_names":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"instances":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"validate":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"set":{"path":"String","value":"String","values":"Table","proto":"String","instance_mode":"Integer"}
"operate":{"path":"String","action":"String","input":"Table","proto":"String","instance_mode":"Integer"}
"add_object":{"path":"String","proto":"String","instance_mode":"Integer"}
"del_object":{"path":"String","proto":"String","instance_mode":"Integer"}
root@iopsys:~#
root@iopsys:~# ubus -v list usp.raw
'usp.raw' @08a13407
"dump_schema":{}
"list_operate":{}
"list_events":{}
"get":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"getm_values":{"paths":"Array","proto":"String","next-level":"Boolean","instance_mode":"Integer"}
"getm_names":{"paths":"Array","proto":"String","next-level":"Boolean","instance_mode":"Integer"}
"object_names":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"instances":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"validate":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"transaction_start":{"app":"String","max_timeout":"Integer"}
"set":{"path":"String","value":"String","values":"Table","proto":"String","instance_mode":"Integer","transaction_id":"Integer"}
"operate":{"path":"String","action":"String","input":"Table","proto":"String","instance_mode":"Integer"}
"add_object":{"path":"String","proto":"String","instance_mode":"Integer","transaction_id":"Integer"}
"del_object":{"path":"String","proto":"String","instance_mode":"Integer","transaction_id":"Integer"}
"setm_values":{"pv_tuple":"Array","proto":"String","instance_mode":"Integer","transaction_id":"Integer"}
"transaction_commit":{"transaction_id":"Integer"}
"transaction_abort":{"transaction_id":"Integer"}
"transaction_status":{"transaction_id":"Integer"}
"notify_event":{"name":"String","input":"Table"}
root@iopsys:~#
Note1:
protoin each method specify the data-model prototype('cwmp', 'usp') to use, if not provided default data-model will be used.
Note2:
instance_modecould be 0 or 1, for instance number, instance alias respectively.
Note3:
next-leveltrue means only get next level objects and false means get all objects recursively
Note4:
maxdepthis measured on max number of .(Dot) present in object name
Note5:
keyis used specifically for cwmp param_key
The objects registered with the above namespaces can be called with appropriate
parameters to perform a USP Get/Set/Operate/Add Object/Delete Object operation as below.
Granularity
Granularity feature is basically exposes the same USP functionality by registering
additional ubus namespaces to reduce the path length in ubus parameter.
It is the number of levels(Dots) up to which we want to shorten the length.
Ex:
- When Granularity is set to 1, exposed ubus namespaces are
root@iopsys:~# ubus list|grep usp
usp
usp.Device.
usp.raw
- When Granularity is set to 2, exposed ubus namespaces are
root@iopsys:~# ubus list|grep usp
usp
usp.Device.
usp.Device.Bridging.
usp.Device.DHCPv4.
usp.Device.DHCPv6.
usp.Device.DNS.
usp.Device.DeviceInfo.
usp.Device.DynamicDNS.
usp.Device.Ethernet.
usp.Device.Firewall.
usp.Device.Hosts.
usp.Device.IP.
usp.raw
root@iopsys:~#
These granular ubus objects provides the same functionality as of usp ubus namespace
root@iopsys:~# ubus -v list usp.Device.WiFi.
'usp.Device.WiFi.' @6fd43aca
"list_operate":{}
"get":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"object_names":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"instances":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"validate":{"path":"String","proto":"String","maxdepth":"Integer","next-level":"Boolean","instance_mode":"Integer"}
"set":{"path":"String","value":"String","values":"Table","proto":"String","instance_mode":"Integer"}
"operate":{"path":"String","action":"String","input":"Table","proto":"String","instance_mode":"Integer"}
"add_object":{"path":"String","proto":"String","instance_mode":"Integer"}
"del_object":{"path":"String","proto":"String","instance_mode":"Integer"}
root@iopsys:~#
Registered method can be called with appropriate parameters, like:
root@iopsys:~# ubus call usp.Device. get '{"path":"Users."}'
{
"Users": {
"User": [
{
"Alias": "cpe-1",
"Enable": true,
"Language": "",
"Password": "",
"RemoteAccessCapable": true,
"Username": "user"
},
{
"Alias": "cpe-2",
"Enable": true,
"Language": "",
"Password": "",
"RemoteAccessCapable": true,
"Username": "support"
},
{
"Alias": "cpe-3",
"Enable": true,
"Language": "",
"Password": "",
"RemoteAccessCapable": true,
"Username": "admin"
}
],
"UserNumberOfEntries": 3
}
}
root@iopsys:~#
Overview
uspd provides below commands in pretty(usp) or raw(usp.raw) formats, some methods only available for API integration in usp.raw namespace:
- Get
- Get multiple values
- Get multiple names
- Set
- Operate
- Add object
- Delete object
- Object names
- Instances
- Validate
- List operate
- Dump schema
- Set multiple values
- Transaction start
- Transaction status
- Transaction commit
- Transaction abort
- List supported usp events
- Send notification for an event
It also provide a granularity layer which can be configured using uci parameter and provide additional ubus objects.
Get
API to query the value of a specific object.
root@iopsys:~# ubus call usp get '{"path":"Device.IP.Diagnostics.", "proto":"usp"}'
{
"Diagnostics": {
"IPv4DownloadDiagnosticsSupported": true,
"IPv4PingSupported": true,
"IPv4ServerSelectionDiagnosticsSupported": true,
"IPv4TraceRouteSupported": true,
"IPv4UDPEchoDiagnosticsSupported": true,
"IPv4UploadDiagnosticsSupported": true,
"IPv6DownloadDiagnosticsSupported": true,
"IPv6PingSupported": true,
"IPv6ServerSelectionDiagnosticsSupported": true,
"IPv6TraceRouteSupported": true,
"IPv6UDPEchoDiagnosticsSupported": true,
"IPv6UploadDiagnosticsSupported": true
}
}
root@iopsys:~#
root@iopsys:~# ubus call usp get '{"path":"Device.IP.Diagnostics.", "proto":"cwmp"}'
{
"Diagnostics": {
"DownloadDiagnostics": {
"BOMTime": "0",
"DSCP": 0,
"DiagnosticsState": "None",
"DownloadDiagnosticMaxConnections": 1,
"TotalBytesSent": 0,
"TotalBytesSentUnderFullLoading": 0
},
"IPPing": {
"AverageResponseTime": 0,
"AverageResponseTimeDetailed": 0,
"DSCP": 0,
"DataBlockSize": 64,
"ProtocolVersion": "Any",
"SuccessCount": 0,
"Timeout": 1000
},
"IPv4DownloadDiagnosticsSupported": true,
"IPv4PingSupported": true,
"IPv4ServerSelectionDiagnosticsSupported": true,
"IPv6UDPEchoDiagnosticsSupported": true,
"IPv6UploadDiagnosticsSupported": true,
}
}
}
root@iopsys:~#
root@iopsys:~# ubus call usp get '{"path":"Device.Users."}'
{
"Users": {
"User": [
{
"Alias": "cpe-1",
"Enable": true,
"Language": "",
"Password": "",
"RemoteAccessCapable": true,
"Username": "user"
},
{
"Alias": "cpe-2",
"Enable": true,
"Language": "",
"Password": "",
"RemoteAccessCapable": true,
"Username": "support"
},
{
"Alias": "cpe-3",
"Enable": true,
"Language": "",
"Password": "",
"RemoteAccessCapable": true,
"Username": "admin"
}
],
"UserNumberOfEntries": 3
}
}
root@iopsys:~#
root@iopsys:~# ubus call usp.raw get '{"path":"Device.Users."}'
{
"parameters": [
{
"parameter": "Device.Users.User.1.Alias",
"value": "cpe-1",
"type": "xsd:string"
},
{
"parameter": "Device.Users.User.1.Enable",
"value": "1",
"type": "xsd:boolean"
},
{
"parameter": "Device.Users.User.1.Language",
"value": "",
"type": "xsd:string"
},
{
"parameter": "Device.Users.User.1.Password",
"value": "",
"type": "xsd:string"
}
]
}
Get multiple values
API to get values of multiple objects at once, object name must be provided in paths parameter array as below.
Note: This method is only available in
usp.rawnamespace.
root@iopsys:~# ubus call usp.raw getm_values '{"paths":["Device.Users.User.1.Username","Device.DeviceInfo.SerialNumber"]}'
{
"parameters": [
{
"parameter": "Device.Users.User.1.Username",
"value": "user",
"type": "xsd:string"
},
{
"parameter": "Device.DeviceInfo.SerialNumber",
"value": "E40A24H185027824",
"type": "xsd:string"
}
]
}
Get multiple objects
API to get multiple objects from multiple paths at once.
Note: This method only available in
usp.rawnamespace
root@iopsys:~# ubus call usp.raw getm_names '{"paths":["Device.Users.User.1.","Device.DeviceInfo.SerialNumber"]}'
{
"parameters": [
{
"parameter": "Device.Users.User.1.",
"value": "1",
"type": "xsd:object"
},
{
"parameter": "Device.Users.User.1.Alias",
"value": "1",
"type": "xsd:string"
},
{
"parameter": "Device.Users.User.1.Enable",
"value": "1",
"type": "xsd:boolean"
},
{
"parameter": "Device.Users.User.1.Language",
"value": "1",
"type": "xsd:string"
},
{
"parameter": "Device.Users.User.1.Password",
"value": "1",
"type": "xsd:string"
},
{
"parameter": "Device.Users.User.1.RemoteAccessCapable",
"value": "1",
"type": "xsd:boolean"
},
{
"parameter": "Device.Users.User.1.Username",
"value": "1",
"type": "xsd:string"
},
{
"parameter": "Device.DeviceInfo.SerialNumber",
"value": "0",
"type": "xsd:string"
}
]
}
root@iopsys:~#
Set
API to set value to specific object, object name must be provided in path parameter and value to be set in value option.
Note 1: In usp namespace, set method creates a internal transaction before actually setting the value. After set operation it automatically commits the transaction.
Note 2: In usp.raw namespace, set method requires a transaction to be created before calling the set method. Please refer to transaction APIs for more details.
root@iopsys:/tmp# ubus call usp set '{"path":"Device.WiFi.SSID.[BSSID==\"00:22:07:ae:ee:03\"].SSID", "value":"test-2g"}'
{
"status": true
}
root@iopsys:/tmp# ubus call usp.raw set '{"path":"Device.WiFi.SSID.[BSSID==\"00:22:07:ae:ee:03\"].SSID", "value":"test-2g", "transaction_id":12345}'
{
"status": true
}
root@iopsys:~# ubus call usp get '{"path":"Device.WiFi.SSID.[BSSID==\"00:22:07:ae:ee:03\"].SSID"}'
{
"SSID": [
{
"SSID": "test-2g"
}
]
}
Operate
API to run operate/diagnostics commands as defined in TR-369
root@iopsys:~# ubus call usp operate '{"path":"Device.IP.Diagnostics.", "action":"IPPing()","input":{"Host":"iopsys.eu"}}'
{
"Results": [
{
"path": "Device.IP.Diagnostics.IPPing",
"result": [
{
"AverageResponseTime": 0,
"AverageResponseTimeDetailed": 0,
"FailureCount": 3,
"MaximumResponseTime": 0,
"MaximumResponseTimeDetailed": 0,
"MinimumResponseTime": 9999,
"MinimumResponseTimeDetailed": 999999999,
"SuccessCount": 0
}
]
}
]
}
root@iopsys:~# ubus call usp.raw operate '{"path":"Device.IP.Diagnostics.", "action":"IPPing()","input":{"Host":"iopsys.eu"}}'
{
"Results": [
{
"path": "Device.IP.Diagnostics.IPPing",
"parameters": [
{
"parameter": "AverageResponseTime",
"value": "0",
"type": "xsd:unsignedInt"
},
{
"parameter": "AverageResponseTimeDetailed",
"value": "0",
"type": "xsd:unsignedInt"
},
{
"parameter": "FailureCount",
"value": "3",
"type": "xsd:unsignedInt"
},
{
}
]
}
root@iopsys:~# ubus call usp operate '{"path":"Device.IP.Interface.[Name==\"wan\"].", "action":"Reset()"}'
{
"Results": [
{
"path": "Device.IP.Interface.2.Reset",
"result": [
{
}
]
}
]
}
root@iopsys:~# ubus call usp.raw operate '{"path":"Device.IP.Interface.[Name==\"wan\"].", "action":"Reset()"}'
{
"Results": [
{
"path": "Device.IP.Interface.2.Reset",
"parameters": [
]
}
]
}
Add object
API to add new objects in multi-instance object
Note 1: In usp namespace,
add_objectmethod creates a internal transaction before actually setting the value. After set operation it automatically commits the transaction. Note 2: In usp.raw namespace,add_objectmethod requires a transaction to be created before calling the set method. Please refer to transaction APIs for more details.
root@iopsys:~# ubus call usp add_object '{"path":"Device.Users.User."}'
{
"parameters": [
{
"parameter": "Device.Users.User.",
"status": true,
"instance": "4"
}
]
}
root@iopsys:~# ubus call usp.raw add_object '{"path":"Device.Users.User.", "transaction_id":12345}'
{
"parameters": [
{
"parameter": "Device.Users.User.",
"status": true,
"instance": "5"
}
]
}
Delete object
API to delete an existing object from multi-instance object
Note 1: In usp namespace,
del_objectmethod creates a internal transaction before actually setting the value. After set operation it automatically commits the transaction. Note 2: In usp.raw namespace,del_objectmethod requires a transaction to be created before calling the set method. Please refer to transaction APIs for more details.
root@iopsys:/tmp# ubus call usp del_object '{"path":"Device.Users.User.4"}'
{
"parameters": [
{
"parameter": "Device.Users.User.4.",
"status": true
}
]
}
root@iopsys:/tmp# ubus call usp.raw del_object '{"path":"Device.Users.User.3", "transaction_id": 12345}'
{
"parameters": [
{
"parameter": "Device.Users.User.3.",
"status": true
}
]
}
Object names
API to get the available list of object names.
root@iopsys:~# ubus call usp object_names '{"path":"Device.DeviceInfo.SerialNumber"}'
{
"parameters": [
{
"parameter": "Device.DeviceInfo.SerialNumber",
"writable": "0",
"type": "xsd:string"
}
]
}
root@iopsys:~#
root@iopsys:~# ubus call usp.raw object_names '{"path":"Device.Users.User.1."}'
{
"parameters": [
{
"parameter": "Device.Users.User.1.",
"writable": "1",
"type": "xsd:object"
},
{
"parameter": "Device.Users.User.1.Alias",
"writable": "1",
"type": "xsd:string"
},
{
"parameter": "Device.Users.User.1.Enable",
"writable": "1",
"type": "xsd:boolean"
},
{
"parameter": "Device.Users.User.1.Language",
"writable": "1",
"type": "xsd:string"
},
{
"parameter": "Device.Users.User.1.Password",
"writable": "1",
"type": "xsd:string"
},
{
"parameter": "Device.Users.User.1.RemoteAccessCapable",
"writable": "1",
"type": "xsd:boolean"
},
{
"parameter": "Device.Users.User.1.Username",
"writable": "1",
"type": "xsd:string"
}
]
}
root@iopsys:~#
Instances
API to get the available instances of an multi-instance object. USP Instances method returns the registered instances.
root@iopsys:~# ubus call usp instances '{"path":"Device.IP.Interface.", "proto":"usp"}'
{
"parameters": [
{
"parameter": "Device.IP.Interface.1."
},
{
"parameter": "Device.IP.Interface.1.IPv4Address.1."
},
{
"parameter": "Device.IP.Interface.2."
},
{
"parameter": "Device.IP.Interface.3."
},
{
"parameter": "Device.IP.Interface.3.IPv4Address.1."
},
{
"parameter": "Device.IP.Interface.3.IPv6Address.1."
},
{
"parameter": "Device.IP.Interface.3.IPv6Prefix.1."
}
]
}
Validate
API to validate a object in data-model. This api shall simply return the object name if present in data-model objects or generates a fault if object not available in data-model.
root@iopsys:~# ubus call usp validate '{"path":"Device.DeviceInfo."}'
{
"parameter": "Device.DeviceInfo"
}
root@iopsys:~# ubus call usp.raw validate '{"path":"invalid.object"}'
{
"fault": 9005
}
List Operate
API to list all available operate commands with supported input and output parameters
root@iopsys:~# ubus call usp list_operate
{
"parameters": [
{
"parameter": "Device.DHCPv4.Client.{i}.Renew()",
"type": "sync"
},
{
"parameter": "Device.DNS.Diagnostics.NSLookupDiagnostics()",
"type": "async",
"in": [
"HostName",
"Interface",
"DNSServer",
"Timeout",
"NumberOfRepetitions"
],
"out": [
"Status",
"AnswerType",
"HostNameReturned",
"IPAddresses",
"DNSServerIP",
"ResponseTime"
]
},
{
"parameter": "Device.DeviceInfo.FirmwareImage.{i}.Activate()",
"type": "async"
},
{
"parameter": "Device.IP.Diagnostics.IPPing()",
"type": "async",
"in": [
"Interface",
"ProtocolVersion",
"Host",
"NumberOfRepetitions",
"Timeout",
"DataBlockSize",
"DSCP"
],
"out": [
"Status",
"IPAddressUsed",
"SuccessCount",
"FailureCount",
"AverageResponseTime",
"MinimumResponseTime",
"MaximumResponseTime",
"AverageResponseTimeDetailed",
"MinimumResponseTimeDetailed",
"MaximumResponseTimeDetailed"
]
},
{
Dump schema
API to dump all registered schema paths,
root@iopsys:~# ubus call usp dump_schema
{
"parameters": [
{
"parameter": "Device.ATM.Link.{i}.",
"writable": "1",
"type": "xsd:object"
},
{
"parameter": "Device.ATM.Link.{i}.Alias",
"writable": "1",
"type": "xsd:string"
},
{
"parameter": "Device.ATM.Link.{i}.DestinationAddress",
"writable": "1",
"type": "xsd:string"
},
{
"parameter": "Device.ATM.Link.{i}.Enable",
"writable": "1",
"type": "xsd:boolean"
},
{
Set multiple values
API to set value of multiple parameters at once.
Note: This method only available in usp.raw namespace
root@iopsys:~# ubus call usp.raw setm_values '{"pv_tuple":[{"path":"Device.Users.User.2.Username", "value":"xzzz"}, {"path":"Device.Users.User.2.RemoteAccessCapable", "value":"true"}, {"path":"Device.Users.User.2.Password", "value":"zzzzzzz"}], "proto":"usp", "transaction_id":1249743667}'
{
"status": true
}
root@iopsys:~#
root@iopsys:~#
root@iopsys:~# ubus call usp.raw setm_values '{"pv_tuple":[{"path":"Device.Users.User.2.Username", "value":"xzzz"}, {"path":"Device.Users.User.2.RemoteAccessCapable", "value":"dummy"}, {"path":"Device.Users.User.2.Password", "value":"zzzzzzz"}], "proto":"usp", "transaction_id":738335779}'
{
"parameters": [
{
"path": "Device.Users.User.2.RemoteAccessCapable",
"status": false,
"fault": 7012
}
]
}
Transaction start
To support the allow_partial and required parameters in Add/Del/Set operation as defined in TR-369, transaction_* APIs introduced.
It basically works around data-model objects which has dependent uci config files for each CUD operation.
API to start a transaction in usp.raw namespace for add/del/set operations in usp.raw namespace
Note: This API only available in usp.raw namespace
root@iopsys:~# ubus call usp.raw transaction_start '{"app":"test"}'
{
"status": true,
"transaction_id": 955001092
}
It's sometime required to have a per transaction timeout, which can be defined along with transaction_start
root@4949e4da3d27:~# ubus call usp.raw transaction_start '{"app":"test", "max_timeout":5000}'
{
"status": true,
"transaction_id": 491944812
}
Note: max_timeout is time in milliseconds, its an optional input argument if not provided, uci default (uspd.usp.transaction_timeout) is used which is defined in seconds If uci option uspd.usp.transaction_timeout not set than a default 10 second timeout is used for the transactions.
Get status of a transaction
API to get details and check status of a transaction id in usp.raw namespace
root@iopsys:~# ubus call usp.raw transaction_status '{"transaction_id":955001092}'
{
"app": "test",
"status": "on-going",
"remaining_time": 634
}
root@iopsys:~#
root@iopsys:~# ubus call usp.raw transaction_status '{"transaction_id":869066287}'
{
"status": "not-exists"
}
root@iopsys:~#
Transaction commit
API to commit an on-going transaction, on calling this api, uci changes shall be committed and required services shall be restarted.
root@iopsys:~# ubus call usp.raw transaction_commit '{"transaction_id":955001092}'
{
"status": true
}
root@iopsys:~#
Transaction abort
API to abort an on-going transaction, on calling this api, staged changes in uci shall be reverted to earlier values.
root@iopsys:~# ubus call usp.raw transaction_abort '{"transaction_id":955001092}'
{
"status": true
}
root@iopsys:~#
List supported usp events
API to list down the data-model events for usp notification supported by uspd.
root@iopsys:~# ubus call usp.raw list_events
{
"parameters": [
{
"parameter": "Device.LocalAgent.TransferComplete!",
"in": [
"Command",
"CommandKey",
"Requestor",
"TransferType",
"Affected",
"TransferURL",
"StartTime",
"CompleteTime",
"FaultCode",
"FaultString"
]
}
]
}