2 .. Copyright (c) 2019 AT&T Intellectual Property.
3 .. Copyright (c) 2019 Nokia.
5 .. Licensed under the Creative Commons Attribution 4.0 International
6 .. Public License (the "License"); you may not use this file except
7 .. in compliance with the License. You may obtain a copy of the License at
9 .. https://creativecommons.org/licenses/by/4.0/
11 .. Unless required by applicable law or agreed to in writing, documentation
12 .. distributed under the License is distributed on an "AS IS" BASIS,
13 .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 .. See the License for the specific language governing permissions and
16 .. limitations under the License.
26 ``RMR based interface between xApp and Subscription Manager which is explained in this User-Guide is deprecated and will be removed in the future.
27 See second User-Guide which explains new REST based interface.``
31 Subscription Manager is a basic platform service in RIC. It is responsible for managing E2 subscriptions from xApps to the
32 Radio Access Network (RAN).
34 xApp can subscribe and unsubscribe messages from gNodeB through Subscription Manager. Subscription Manager manages the subscriptions
35 and message routing of the subscribed messages between E2 Termination and xApps. If one xApp has already made a subscription and then
36 another xApp initiates identical subscription, Subscription Manager does not forward the subscription to gNodeB but merges the
37 subscriptions internally. In merge case Subscription Manager just updates the message routing information to Routing Manager and
38 sends response to xApp.
40 There can be only one ongoing RIC Subscription or RIC Subscription Delete procedure towards RAN at any time. That is because Subscription
41 Manager is able to merge new subscriptions only which those it has already received successful response from RAN. Subscriptions
42 and delete subscriptions are therefore queued in Subscription Manager. Subscription Manager may need to do reties during subscribe or
43 unsubscribe procedure. This needs to be considered when retries are implemented in xApp side, as it can increase completion time of the
44 procedure. xApp's retry delay should not be too short.
46 .. image:: images/PlaceInRICSoftwareArchitecture_RMR.png
48 :alt: Place in RIC's software architecture picture
55 Subscribed messages from RAN are transported to RIC inside RIC Indication message. RIC Indication message is transported to xApp
56 inside RMR message, in Payload field of the RMR message. RMR message is routed to xApp based on SubId field (subscription id) in
57 the RMR header. Same routing mechanism is used also for response messages from Subscription Manager to xApp. Subscription Manager is
58 not able to respond to xApp if route for subscription has not been created.
60 When xApp sends message to Subscription Manager it sets -1 in SubId field in the RMR header. It means that messages are routed based
61 on message type (Mtype filed in RMR header). RIC Subscription Request and RIC Subscription delete Request messages are pre configured
62 to be routed to Subscription Manager.
64 Subscription Manager allocates unique RIC Request Sequence Number for every subscription during Subscription procedure. Subscription
65 Manager replaces existing ASN.1 decoded RIC Request Sequence Number in the RIC Subscription Request message allocated by the xApp.
66 That sequence number (subscription id) is then used for the subscription in RIC and RAN as long the subscription lives. xApp gets
67 the sequence number in RIC Subscription Response message from Subscription manager based on the message types.
69 Subscribed messages are routed to xApps based on sequence number. Sequence number is placed in the SubId field of the RMR message
70 header when E2 Termination sends the subscribed message to xApp. When xApp wants to delete the subscription, the same sequence number
71 must be included in the ASN.1 encoded RIC Subscription Delete Request message sent to Subscription Manager.
73 Subscription Manager allocates and substitutes RIC Requestor ID for E2 interface communication. Currently the ID value is always 123.
74 RAN gets the Request of the xApp who makes the first subscription. RAN uses Subscription Manager allocated Requestor ID in all RIC
75 Indication messages it sends to RIC for the subscription. Subscription Manager returns the same RIC Requestor ID in response message
76 to xApp as was in the request. In merge case subscription is created only for the first requestor.
78 TransactionId (Xid) in RMR message header is used to track messages between xApp and Subscription Manager. xApp allocates it. Subscription
79 Manager returns TransactionId received from xApp in response message to xApp. xApp uses it to map response messages to request messages
82 * Subscription procedure
86 xApp sends RIC Subscription Request message to Subscription Manager. Subscription Manager validates request types in the message and sends
87 route create to Routing Manager over REST interface. When route is created successfully Subscription Manager forwards request to E2
88 Termination. When RIC Subscription Response arrives from E2 Termination Subscription Manager forwards it to xApp.
90 Subscription Manager supervises route create and RIC Subscription Request with a timer.
92 RIC Indication messages which are used to transport subscribed messages from RAN are routed from E2 Termination to xApps
93 directly using the routes created during Subscription procedure.
95 Subscription Manager supports REPORT, POLICY and INSERT type subscriptions (RICActionTypes). CONTROL is not supported. POLICY type
96 subscription can be updated. In update case signaling sequence is the same as above, except route is not created to Routing manager.
97 xApp uses initially allocated TransactionId and RIC Request Sequence Number in update case. Route in POLICY type subscription case is needed
98 only that Subscription Manager can send response messages to xApp. RIC Subscription Request message contains list of RICaction-ToBeSetup-ItemIEs.
99 The list cannot have REPORT, POLICY, INSERT action types at the same time. Subscription Manager checks actions types in the message.
100 If both action types is found the message is dropped.
103 .. image:: images/Successful_Subscription_ASN.1.png
105 :alt: Successful subscription picture
110 In failure case Subscription Manager checks the failure cause and acts based on that. If failure cause is "duplicate" Subscription
111 Manager sends delete to RAN and then resends the same subscription. If failure cause is such that Subscription manager cannot do
112 anything to fix the problem, it sends delete to RAN and sends RIC Subscription Failure to xApp. Subscription Manager may retry RIC
113 Subscription Request and RIC Subscription Delete messages also in this case before it responds to xApp.
115 .. image:: images/Subscription_Failure_ASN.1.png
117 :alt: Subscription failure picture
119 * Timeout in Subscription Manager
121 In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Request to RAN. If there is no response
122 after retry, Subscription Manager shall NOT send any response to xApp. xApp may retry RIC Subscription Request, if it wishes to do so.
123 Subscription Manager does no handle the retry if Subscription Manager has ongoing subscription procedure for the same subscription.
124 Subscription just drops the request.
128 xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
129 request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
130 processing previous request.
132 .. image:: images/Subscription_Timeout_ASN.1.png
134 :alt: Subscription timeout picture
136 * Subscription delete procedure
140 xApp sends RIC Subscription Delete Request message to Subscription Manager. xApp must use the same RIC Request Sequence Number which
141 it received in RIC Subscription Response message when subscription is deleted. When Subscription Manager receives RIC Subscription
142 Delete Request message, Subscription Manager first forwards the request to E2 Termination. When RIC Subscription Delete Response arrives
143 from E2 Termination to Subscription Manager, Subscription Manager forwards it to xApp and then request route deletion from Routing Manager.
145 Subscription Manager supervises RIC Subscription Deletion Request and route delete with a timer.
147 .. image:: images/Successful_Subscription_Delete_ASN.1.png
149 :alt: Successful subscription delete picture
153 Delete procedure cannot fail from xApp point of view. Subscription Manager always responds with RIC Subscription Delete Response to xApp.
155 .. image:: images/Subscription_Delete_Failure_ASN.1.png
157 :alt: Subscription delete failure picture
159 * Timeout in Subscription Manager
161 In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Delete Request to RAN. If there is no
162 response after retry, Subscription Manager responds to xApp with RIC Subscription Delete Response.
166 xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
167 request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
168 processing previous request.
170 .. image:: images/Subscription_Delete_Timeout_ASN.1.png
172 :alt: Subscription delete timeout picture
174 * Unknown subscription
176 If Subscription Manager receives RIC Subscription Delete Request for a subscription which does not exist, Subscription Manager cannot respond
177 to xApp as there is no route for the subscription.
179 * Subscription merge procedure
183 xApp sends RIC Subscription Request message to Subscription Manager. Subscription Manager checks is the Subscription mergeable. If not,
184 Subscription Manager continues with normal Subscription procedure. If Subscription is mergeable, Subscription Manager sends route create
185 to Routing Manager and then responds with RIC Subscription Response to xApp.
187 Route create is supervised with a timer.
189 Merge for REPORT type subscription is possible if Action Type and Event Trigger Definition of subscriptions are equal.
191 ``Only REPORT type subscriptions can be be merged.``
193 .. image:: images/Successful_Subscription_Merge_ASN.1.png
195 :alt: Successful subscription merge picture
199 Failure case is basically the same as in normal subscription procedure. Failure can come only from RAN when merge is not yet done.
200 If error happens during route create Subscription Manager drops the RIC Subscription Request message and xApp does not get any response.
202 * Timeout in Subscription Manager
204 Timeout case is basically the same as in normal subscription procedure but timeout can come only in route create during merge operation.
205 If error happens during route create, Subscription Manager drops the RIC Subscription Request message and xApp does not get any response.
209 xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
210 request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
211 processing previous request.
213 * Subscription delete merge procedure
217 xApp sends RIC Subscription Delete Request message to Subscription Manager. If delete concerns merged subscription, Subscription Manager
218 responds with RIC Subscription Delete Response to xApp and then sends route delete request to Routing manager.
220 Subscription Manager supervises route delete with a timer.
222 .. image:: images/Successful_Subscription_Delete_Merge_ASN.1.png
224 :alt: Successful subscription delete merge picture
228 Delete procedure cannot fail from xApp point of view. Subscription Manager responds with RIC Subscription Delete Response message to xApp.
230 * Timeout in Subscription Manager
232 Timeout can only happen in route delete to Routing manager. Subscription Manager responds with RIC Subscription Delete Response message to xApp.
236 xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
237 request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
238 processing previous request.
242 If Subscription Manager receives unknown message, Subscription Manager drops the message.
246 When xApp is restarted for any reason it may resend subscription requests for subscriptions which have already been subscribed. If REPORT or INSERT type
247 subscription already exists and RMR endpoint of requesting xApp is attached to subscription then successful response is sent to xApp directly without
248 updating Routing Manager and BTS. If POLICY type subscription already exists, request is forwarded to BTS and successful response is sent to xApp.
249 BTS is expected to accept duplicate POLICY type requests. In restart IP address of the xApp may change but domain service address name does not.
250 RMR message routing uses domain service address name.
252 * Subscription Manager restart
254 Subscription Manager stores successfully described subscriptions from db (SDL). Subscriptions are restored from db in restart. For subscriptions which
255 were not successfully completed, Subscription Manager sends delete request to BTS and removes routes created for those. Restoring subscriptions from
256 db can be disable via submgr-config.yaml file by setting "readSubsFromDb": "false".
260 Subscription Manager adds following statistic counters:
262 Subscription create counters:
263 - SubReqFromXapp: The total number of SubscriptionRequest messages received from xApp
264 - SubRespToXapp: The total number of SubscriptionResponse messages sent to xApp
265 - SubFailToXapp: The total number of SubscriptionFailure messages sent to xApp
266 - SubReqToE2: The total number of SubscriptionRequest messages sent to E2Term
267 - SubReReqToE2: The total number of SubscriptionRequest messages resent to E2Term
268 - SubRespFromE2: The total number of SubscriptionResponse messages from E2Term
269 - SubFailFromE2: The total number of SubscriptionFailure messages from E2Term
270 - SubReqTimerExpiry: The total number of SubscriptionRequest timer expires
271 - RouteCreateFail: The total number of subscription route create failure
272 - RouteCreateUpdateFail: The total number of subscription route create update failure
273 - MergedSubscriptions: The total number of merged Subscriptions
275 Subscription delete counters:
276 - SubDelReqFromXapp: The total number of SubscriptionDeleteResponse messages received from xApp
277 - SubDelRespToXapp: The total number of SubscriptionDeleteResponse messages sent to xApp
278 - SubDelReqToE2: The total number of SubscriptionDeleteRequest messages sent to E2Term
279 - SubDelReReqToE2: The total number of SubscriptionDeleteRequest messages resent to E2Term
280 - SubDelRespFromE2: The total number of SubscriptionDeleteResponse messages from E2Term
281 - SubDelFailFromE2: The total number of SubscriptionDeleteFailure messages from E2Term
282 - SubDelReqTimerExpiry: The total number of SubscriptionDeleteRequest timer expires
283 - RouteDeleteFail: The total number of subscription route delete failure
284 - RouteDeleteUpdateFail: The total number of subscription route delete update failure
285 - UnmergedSubscriptions: The total number of unmerged Subscriptions
287 SDL failure counters:
288 - SDLWriteFailure: The total number of SDL write failures
289 - SDLReadFailure: The total number of SDL read failures
290 - SDLRemoveFailure: The total number of SDL read failures
292 Configurable parameters
293 -----------------------
294 Subscription Manager has following configurable parameters.
295 - Retry timeout for RIC Subscription Request message
296 - e2tSubReqTimeout_ms: 2000 is the default value
298 - Retry timeout for RIC Subscription Delete Request message
299 - e2tSubDelReqTime_ms: 2000 is the default value
301 - Waiting time for RIC Subscription Response and RIC Subscription Delete Response messages
302 - e2tRecvMsgTimeout_ms: 2000 is the default value
304 - Try count for RIC Subscription Request message
305 - e2tMaxSubReqTryCount: 2 is the default value
307 - Try count for RIC Subscription Delete Request message
308 - e2tMaxSubDelReqTryCount: 2 is the default value
310 - Are subscriptions read from database in Subscription Manager startup
311 - readSubsFromDb: "true" is the default value
313 The parameters can be changed on the fly via Kubernetes Configmap. Default parameters values are defined in Helm chart
315 Use following command to open Subscription Manager's Configmap in Nano editor. Firts change parameter and then store the
316 change by pressing first Ctrl + o. Close editor by pressing the Ctrl + x. The change is visible in Subscription Manager's
317 log after some 20 - 30 seconds.
321 KUBE_EDITOR="nano" kubectl edit cm configmap-ricplt-submgr-submgrcfg -n ricplt
323 REST interface for debugging and testing
324 ----------------------------------------
325 Give following commands to get Subscription Manager pod's IP address
329 kubectl get pods -A | grep submgr
331 ricplt submgr-75bccb84b6-n9vnt 1/1 Running 0 81m
333 Syntax: kubectl exec -t -n ricplt <add-submgr-pod-name> -- cat /etc/hosts | grep submgr | awk '{print $1}'
335 Example: kubectl exec -t -n ricplt submgr-75bccb84b6-n9vnt -- cat /etc/hosts | grep submgr | awk '{print $1}'
343 Example: curl -s GET "http://10.244.0.181:8080/ric/v1/metrics"
349 Example: curl -X GET "http://10.244.0.181:8088/ric/v1/subscriptions"
351 Delete single subscription from db
355 Syntax: curl -X POST "http://10.244.0.181:8080/ric/v1/test/deletesubid={SubscriptionId}"
357 Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/deletesubid=1"
359 Remove all subscriptions from db
363 Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/emptydb"
365 Make Subscription Manager restart
369 Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/restart"
371 Use this command to get Subscription Manager's log writings
375 Example: kubectl logs -n ricplt submgr-75bccb84b6-n9vnt
377 Logger level in configmap.yaml file in Helm chart is by default 2. It means that only info logs are printed.
378 To see debug log writings it has to be changed to 4.
385 RAN services explained
386 ----------------------
387 RIC hosted xApps may use the following RAN services from a RAN node:
389 * REPORT: RIC requests that RAN sends a REPORT message to RIC and continues further call processing in RAN after each occurrence of a defined SUBSCRIPTION
390 * INSERT: RIC requests that RAN sends an INSERT message to RIC and suspends further call processing in RAN after each occurrence of a defined SUBSCRIPTION
391 * CONTROL: RIC sends a Control message to RAN to initiate or resume call processing in RAN
392 * POLICY: RIC requests that RAN executes a specific POLICY during call processing in RAN after each occurrence of a defined SUBSCRIPTION
394 Supported E2 procedures and RAN services
395 ----------------------------------------
396 * RIC Subscription procedure with following RIC action types:
402 * RIC Subscription Delete procedure
404 * Merge and delete of equal REPORT type subscriptions.
406 Recommendations for xApps
407 -------------------------
409 * Recommended retry delay in xApp
411 Recommended retry delay for xApp is >= 5 seconds. Length of supervising timers in Subscription Manager for the requests it sends to BTS is by default 2
412 seconds. Subscription Manager makes one retry by default. There can be only one ongoing request towards per RAN other requests are queued in Subscription