O1-v2-interface: Subscribe/Unsubscribe for VES events.

Owned by Martin Skorupski
Last updated: Nov 07, 2019
8 min read

NOTE 2019-11-07: The topic will be defined by 3GPP and O-RAN will add O-RAN specifics to 3GPP specifications - if needed. 

This page will not be updated until O-RAN has specified all details and published the final specification. 


DRAFT!
Target: this page becomes obsolete when the content is described in a released O-RAN-SC OAM interface specification. 



Open: All the details about the NetConf operation (rpc, edit-config (Create-MOI, Modify-MOI)).

Scope

A new function should be defined by WG1 for O-RAN-OAM-Interface specification  (O1-interface) version 2. 

The function should provide the ability by the Management-Service-Consumer (MnS Consumer, NMS) to subscribe and unsubscribe for VES events. 

Please see OAM Architecture.

Design guidelines

  1. Each NetConf session should be terminated as soon as possible. Therefore any solution requiring a permanent NetConf session (e.g. for NetConf Notification) should be avoided.
    (TODO: add here the reasons for such requirement/expectation. It may have something to do with avoiding TCP connection for better scale. However, for the required event streaming functionality, a permanent session is necessary. To be continued)
  2. The NetConf client should be informed about the operational-status of the VES connection. In the case of misconfiguration, alarm events can not be sent to the MnS Consumer (alarm blindness). The only channel to troubleshoot such situation is via NetConf.

Subscription

Message flow

Due to the Design Guidelines above the operational-status of the subscription can not be handled asynchronously. The operational-status must be given in the NetConf response.

  1. Establish a NetConf session
    A secure communication channel is required to establish a NetConf session. This can be done via Secure Shell (SSH) connection (RFC6242) or via Transport Layer Security (TLS) (RFC5539).
    Due to the fact that O-RAN-Alliance requires TLS for HTTP traffic, it is preferred and recommended to use also TLS for NetConf.
  2. Subscribe for VES events
    Open: The details about the NetConf operation and the exact data structure are currently (2019-07-28) under discussion. The results of this discussion will be updated later here.
  3. Inform VES client about a new subscription
    An MnS Provider internal mechanism is necessary to verify the VES configuration. 
  4. Check VES connectivity
    The verification of the VES communication channel id done by sending a VES heartbeat. 
    Note: If the MnS Consumer does not subscribe for VES heartbeats, then an HTTP-POST with an empty body should be send. The expected response is "HTTP status: 400 - Bad request". If this is the case the operational-status of the subscription should be mapped to "200 - Ok". 
  5. Response from VES server
    Based on the response from the VES-HTTPS-Server (TCP/TLS/HTTP-POST/VES) the operational-status attribute value of Managed Object instance (MOI) representing the subscription will be updated and exposed as attribute value change to all subscribers. 
    1. SUCCESS
      The HTTP response codes 20x indicate that the VES connection can be established and the subscription operational-status attribute will be changed to the value of the HTTP-status (integer).
    2. FAILED
      The HTTP response codes different from 20x may require operator actions. Also, in this case, the subscription operational-status attribute will be changed to the value of the HTTP-status (integer)

      Open: is a textual status attribute useful? e.g. status: ok and status: "failed" or status: "failed (connection refused)" - Assumption; no - such translation is not subject of an OAM interface, it is subject of customer documentation and/or user interface (UI).
  6. Inform NetConf server about the status of the VES connection
    The NetConf server must be triggered, to response the correct operational-status back to the MnS Consumer.
  7. NetConf response
    The NetConf server sends a response including the VES connection operational-status of the subscription.
    Open: Shall the response also include all other attributes of the MOI representing the subscription?
  8. Terminate NetConf session
    Once the NetConf client received the NetConf response or the NetConf response timed out, the NetConf session should be actively terminated.
    Note: All ODL based NetConf clients until release "Sodium" do not support such functionality yet - Also the ODL based implementation by ONAP CCSDK does not support such function.
    It is currently (2019-07-28) under discussion, which of the involved open-source projects should implement such function - candidates are ODL, ONAP-CCSDK, ONAP-SDNC, ONAP-SDN-R, O-RAN-SC-NON-RT-RIC or O-RAN-SC-OAM. (TODO: add OAM Jira to track it). As a consequence, it is very likely that O-RAN-SC release A does not support the automated termination of the NetConf session after NetConf responses. 

Figure

PlantUml

 Click here to view PlantUml code...
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright 2019 highstreet technologies GmbH
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
' 
'     http://www.apache.org/licenses/LICENSE-2.0
' 
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.
' 
' Author: martin.skorupski@highstreet-technologies.com

@startuml

' Diagram
title 
  O-RAN-SC 
  O1-Interface: VES Subscription procedure
end title

box "\nManagement-Service (MnS)Provider\nManagedElement" #ED7D31
  participant "<b>Client</b>" as vesc <<VES>> 
  participant "<b>Server</b>" as ncs <<NetConf>>
end box 

box "\nManagement-Service (MnS) Consumer\nOAMController" #8064A2
  participant "<b>Client</b>" as ncc <<NetConf>>
  participant "<b>Server</b>" as vess <<VES>>
end box

autonumber "<b>[00]"
  
group VES Subscription

  ncc <-> ncs: tcp/tls/netconf/830\nEstablish NetConf Session (hello, ...)
  ncc -> ncs: subscribe for VES events
  activate ncs
    ncs -> vesc: inform about a new subscription
    vesc -> vess: Check connectivity (e.g. tcp/tls/http/ves/heartbeat)
    vesc <- vess: expected response "SUCCESS" (http status: 200)
    vesc-> ncs: inform about status of the VES connection
    ncs -> ncc: Response (expected: success, unexpected: failure)
  deactivate ncs
  ncc -> ncs: Terminate NetConf Session
end group

' End Diagram
' Format
header
  <b><font color=#8888ff>License</font></b>
  <b><font color=#8888ff>Apache 2.0</font></b>
end header
'caption "\n UML Formatting"

right footer 
  VES Subscription
  Thanks to plantUml! 
  2019-07-27 | o-ran-sc.org
end footer

skinparam backgroundColor #fefefe

skinparam backgroundColor #fefefe
'skinparam handwritten true
skinparam roundcorner 15

skinparam databaseBorderColor #666666
skinparam databaseBackgroundColor #fefefe
skinparam databaseFontColor #666666

skinparam sequence {
  MessageAlign left
  ArrowColor #2277dd
  ArrowFontColor #666666
  ActorBorderColor #666666
  LifeLineBorderColor #666666
  LifeLineBackgroundColor #eeeeee
 
  BoxFontColor #ffffff
  BoxBorderColor #666666
    
  GroupBorderColor #666666
  GroupBackgroundColor #eeeeee
  
  ParticipantBorderColor #666666
  ParticipantBackgroundColor #ffffdd
  'ParticipantFontName Impact
  'ParticipantFontSize 17
  ParticipantFontColor #666666
    
  ActorBackgroundColor #ffffdd
  'ActorFontColor DeepSkyBlue
  'ActorFontSize 17
  'ActorFontName Aapex
}

@enduml

Message data

As a consequence of the protocol split for configuration (NetConf) and events (HTTP/VES) information form TCP header cant be re-used, and the entire VES end-point must be described in the Subscription request message. Under the assumption  that not every MnS Consumer is interested about every VES message, a filter can be applied to the Subscription request message. If no filter is set, all supported VES messages by the MnS Provider (ME) will be forwarded. 

There should be three kinds of filters.

  1. VES-Domain-Filter
    A list of all VES domains the MnS Consumer is interested. 
  2. Subtree-Filter
    A filter analog to RFC6241 chapter 6.
  3. xPath-Filter
    A filter analog to RFC6241 chapter 8.9.

The MnS Consumer is responsible for a correct filter setting, in case the combination for all three filters lead to the consequence that no VES message is sent to the MnS Consumer, then the MnS Consumer is simply not updated, even the subscription operational-status indicates "ok". 

Proposal: not aligned yet! Very likely to be changed - I mean: for sure!!!

MOI: Subscription

  • administrative-status: ENUM = {"unlocked", "locked"; default: "unlocked"}; ACCESS: read-write; OPTIONAL
  • operational-status: ENUM = {"enabled", "disabled"}; ACCESS: read-only
  • ves-end-point: object; ACCESS: read-write; MANDATORY
    • protocol: ENUM = {"http", "https"; default "https" }
    • host: 
      • Fully qualified domain name OR
      • IP Address (IP version: v4 or v6)
    • port: integer = {0..65535 }
    • cert-for-authorization: Open: string or binary or ...; MANDATORY, when protocol=https
    • pass-phrase: string; OPTIONAL
    • compression: boolean; default false
  • filter: object; OPTIONAL
    • ves-domain: list of an extensible ENUM according to supported VES message specification; ACCESS: read-write;  OPTIONAL; 
    • subtree: string; ACCESS: read-write; OPTIONAL; Open: support of multiple subtrees?)
    • x-path-expression: ACCESS: read-write; OPTIONAL; Open: support of multiple subtrees?)

Un-subscription

Message flow

Open: administrative-status locked versus delete corresponding MOI versus ... This chapter depends on the results of the Subscription chapter. 

  1. Establish a NetConf session
    A secure communication channel is required to establish a NetConf session. This can be done via Secure Shell (SSH) connection (RFC6242) or via Transport Layer Security (TLS) (RFC5539).
    Due to the fact that O-RAN-Alliance requires TLS for HTTP traffic, it is preferred and recommended to use also TLS for NetConf.
  2. Un-subscribe from VES events
    Open: The details about the NetConf operation and the exact data structure are currently (2019-07-28) under discussion. The results of this discussion will be updated later here.
  3. Inform VES client about the un-subscription
    An MnS Provider internal mechanism is necessary to verify the VES configuration. 
  4. Send corresponding VES event
    Open: Config-change? 
  5. Response from VES server
    Based on the response from the VES-HTTPS-Server (TCP/TLS/HTTP-POST/VES) the following scenarios will happen:
    1. SUCCESS
      Ths HTTP response codes 20x indicate that the still subscribed MnS consumer has received the last VES message and "knows" that not more VES messages via this channel will be received.
    2. FAILED
      Open: How to handle this situation? Release A: ignoring; Release B: x retries?!?!?!
  6. Inform NetConf server about the status of the VES connection
    The NetConf server must be triggered, to response the correct status back to the MnS Consumer (NetConf client).
  7. NetConf response
    The NetConf server sends a response including the VES connection status of the un-subscription.
    Open: Shall the response also include all other attributes of the MOI representing the subscription?
  8. Terminate NetConf session
    Once the NetConf client received the NetConf response or the NetConf response timed out, the NetConf session should be actively terminated.
    Note: All ODL based NetConf clients until release "Sodium" do not support such functionality yet - Also the ODL based implementation by ONAP CCSDK does not support such function.
    It is currently (2019-07-28) under discussion, which of the involved open-source projects should implement such function - candidates are ODL, ONAP-CCSDK, ONAP-SDNC, ONAP-SDN-R, O-RAN-SC-NON-RT-RIC or O-RAN-SC-OAM. (TODO: add OAM Jira to track it). As a consequence, it is very likely that O-RAN-SC release A does not support the automated termination of the NetConf session after NetConf responses. 

Figure

PlantUml

 Click here to view PlantUml code...
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright 2019 highstreet technologies GmbH
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
' 
'     http://www.apache.org/licenses/LICENSE-2.0
' 
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.
' 
' Author: martin.skorupski@highstreet-technologies.com

@startuml

' Diagram
title 
  O-RAN-SC 
  O1-Interface: VES Un-subscription procedure
end title

box "\nManagement-Service (MnS) Provider\nManagedElement" #ED7D31
  participant "<b>Client</b>" as vesc <<VES>> 
  participant "<b>Server</b>" as ncs <<NetConf>>
end box 

box "\nManagement-Service (MnS) Consumer\nOAMController" #8064A2
  participant "<b>Client</b>" as ncc <<NetConf>>
  participant "<b>Server</b>" as vess <<VES>>
end box

autonumber "<b>[00]"
  
group VES Un-subscription

  ncc <-> ncs: tcp/tls/netconf/830\nEstablish NetConf Session (hello, ...)
  ncc -> ncs: unsubscribe (which operation)
  activate ncs
    ncs -> vesc: inform about the deleted subscription
    vesc -> vess: send cooresponding event (which domain?)
    vesc <- vess: http status: 200
    vesc -> ncs: successful unsubscription
    ncs -> ncc: Done!
  deactivate ncs
  ncc -> ncs: Terminate NetConf session

end group

' End Diagram
' Format
header
  <b><font color=#8888ff>License</font></b>
  <b><font color=#8888ff>Apache 2.0</font></b>
end header
'caption "\n UML Formatting"

right footer 
  VES Unsubscription
  Thanks to plantUml! 
  2019-07-27 | o-ran-sc.org
end footer

skinparam backgroundColor #fefefe

skinparam backgroundColor #fefefe
'skinparam handwritten true
skinparam roundcorner 15

skinparam databaseBorderColor #666666
skinparam databaseBackgroundColor #fefefe
skinparam databaseFontColor #666666

skinparam sequence {
  MessageAlign left
  ArrowColor #2277dd
  ArrowFontColor #666666
  ActorBorderColor #666666
  LifeLineBorderColor #666666
  LifeLineBackgroundColor #eeeeee
 
  BoxFontColor #ffffff
  BoxBorderColor #666666
    
  GroupBorderColor #666666
  GroupBackgroundColor #eeeeee
  
  ParticipantBorderColor #666666
  ParticipantBackgroundColor #ffffdd
  'ParticipantFontName Impact
  'ParticipantFontSize 17
  ParticipantFontColor #666666
    
  ActorBackgroundColor #ffffdd
  'ActorFontColor DeepSkyBlue
  'ActorFontSize 17
  'ActorFontName Aapex
}

@enduml