diff --git a/doc/mgmt/Management Framework.md b/doc/mgmt/Management Framework.md index b7728bbcd2..36d7921ccc 100644 --- a/doc/mgmt/Management Framework.md +++ b/doc/mgmt/Management Framework.md @@ -82,6 +82,7 @@ * [3.2.2.8.3 CVL APIs](#32283-cvl-apis) * [3.2.2.9 Redis DB](#3229-redis-db) * [3.2.2.10 Non DB data provider](#32210-non-db-data-provider) + * [3.2.2.11 NETCONF Server](#32211-netconf-server) * [4 Flow Diagrams](#4-flow-diagrams) * [4.1 REST SET flow](#41-REST-set-flow) * [4.2 REST GET flow](#42-REST-get-flow) @@ -139,6 +140,7 @@ | 0.17 | 04/08/2020 | Mohammed Faraaz | OpenAPI 3.0 enhancements | | 0.18 | 04/09/2020 | Kwangsuk Kim | Updated CLI and Transformer enhancement | | 0.19 | 04/15/2020 | Mohammed Faraaz | Generic REST client for CLI | +| 0.20 | 07/03/2023 | Abdelmuhaimen Seaudi | Netconf Server | ## About this Manual @@ -174,30 +176,37 @@ Management framework is a SONiC application which is responsible for providing v 1. Standard [YANG](https://tools.ietf.org/html/rfc7950) models (e.g. OpenConfig, IETF, IEEE) 2. Custom YANG models ([SONiC YANG](https://github.com/sonic-net/SONiC/blob/master/doc/mgmt/SONiC_YANG_Model_Guidelines.md)) 3. Industry-standard CLI / Cisco like CLI - * Must provide support for [OpenAPI spec](http://spec.openapis.org/oas/v3.0.3) to generate REST server side code * Must provide support for NBIs such as: 1. CLI 2. gNMI 3. REST/RESTCONF - +4. NETCONF * Must support the following security features: 1. Certificate-based authentication 2. User/password based authentication 3. Role based authorization - * Ease of use for developer workflow 1. Specify data model and auto-generate as much as possible from there - * Must support Validation and Error Handling - data model, platform capability/scale, dynamic resources * SNMP integration in SONiC is left for future study ### 1.2 Design Overview -Management framework makes use of the translation library (Translib) written in golang to convert the data models exposed to the management clients into the Redis ABNF schema format. Supported management servers can make use of the Translib to convert the incoming payload to SONiC ABNF schema and vice versa depending on the incoming request. Translib will cater to the needs of REST and gNMI servers. Later the Translib can be enhanced to support other management servers if needed. This framework will support both standard and custom YANG models for communication with the corresponding management servers. Management framework will also take care of maintaining data consistency, when writes are performed from two different management servers at the same time. Management framework will provide a mechanism to authenticate and authorize any incoming requests. Management framework will also take care of validating the requests before writing them into the Redis DB. Config Validation Library is used for syntactic and semantic validation of ABNF JSON based on YANG derived from Redis ABNF schema. +Management framework makes use of the translation library (Translib) written in golang to convert the data models exposed to the management clients into the Redis ABNF schema format. + +Supported management servers can make use of the Translib to convert the incoming payload to SONiC ABNF schema and vice versa depending on the incoming request. Translib will cater to the needs of REST, NETCONF, and gNMI servers. Later the Translib can be enhanced to support other management servers if needed. + +This framework will support both standard and custom YANG models for communication with the corresponding management servers. + +Management framework will also take care of maintaining data consistency, when writes are performed from two different management servers at the same time. + +Management framework will provide a mechanism to authenticate and authorize any incoming requests. Management framework will also take care of validating the requests before writing them into the Redis DB. + +Config Validation Library is used for syntactic and semantic validation of ABNF JSON based on YANG derived from Redis ABNF schema. #### 1.2.1 Basic Approach @@ -206,7 +215,7 @@ Management framework makes use of the translation library (Translib) written in * Open API spec * Industry standard CLI * Config Validation -* REST server, gNMI server, App module and Translib - all in Go +* REST server, NETCONF server, gNMI server, App module and Translib - all in Go * Translation by using the Translib Library and application specific modules * Marshalling and unmarshalling using YGOT * Redis updated using CAS(Check-and-Set) trans. (No locking, No rollback) @@ -217,6 +226,9 @@ Management framework makes use of the translation library (Translib) written in The management framework is designed to run in a single container named “sonic-mgmt-framework”. The container includes the REST server linked with Translib, and CLI process. The gNMI support requires the gNMI server which is provided as a part of sonic-telemetry container. We would like to rename this container as the sonic-gnmi container as now it can perform configurations as well through the gNMI server. + +The Netconf Server will also run in a seperate container called sonic-netconf-server. + Will introduce a new container sonic-mgmt-common to host the common code that is used both in the mgmt-framework and sonic-telemetry container. This new repo will compile into static libraries that will be used in the other two repos. This way sonic-telemetry repo can be compiled without the mgmt-framework being present in the code base. ## 2 Functionality @@ -225,7 +237,8 @@ Will introduce a new container sonic-mgmt-common to host the common code that is 1. Industry Standard CLI which will use REST client to talk to the corresponding servers to send and receive data. 2. REST client through which the user can perform POST, PUT, PATCH, DELETE, GET operations on the supported YANG paths. -3. gNMI client with support for capabilities, get, set, and subscribe based on the supported YANG models. +3. NETCONF client through which the user can perform NETCONF Operations RFC 6241 , , , etc ... and RFC 6022 . +4. gNMI client with support for capabilities, get, set, and subscribe based on the supported YANG models. ## 3 Design @@ -238,7 +251,7 @@ The SONiC management framework comprises two workflows: as show in the architecture diagram below. -![Management Framework Architecture diagram](images/Mgmt_Frmk_Arch.jpg) +![Management Framework Architecture diagram](images/Mgmt_Frmk_Arch2.jpg) #### 3.1.1 Build time flow @@ -267,7 +280,12 @@ This can be an independent choice on an application by application basis. Howeve 1. REST client will use the OpenAPI generated client SDK to send the request to the REST server. 2. From then on the flow is similar to the one seen in the CLI. -##### 3.1.2.3 gNMI +##### 3.1.2.3 NETCONF + +1. NETCONF client will use the schemas generated and send the request to the NETCONF Server +2. From then on the flow is similar to REST to Translib, and Common App handlers. + +##### 3.1.2.4 gNMI GNMI service defines a gRPC-based protocol for the modification and retrieval of configuration from a target device, as well as the control and generation of telemetry streams from a target device to a data collection system. Refer [GNMI spec](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md) @@ -517,6 +535,7 @@ Following are the run time components in the management framework 7. Config Validation Library (CVL) 8. Redis DB 9. Non DB data provider +10. NETCONF Server ##### 3.2.2.1 CLI @@ -1100,50 +1119,50 @@ Translib is a library that adapts management server requests to SONiC data provi func Subscribe(req SubscribeRequest) ([]*IsSubscribeResponse, error) func IsSubscribeSupported(req IsSubscribeRequest) ([]*IsSubscribeResponse, error) func GetModels() ([]ModelData, error) - + Translib Structures: type ErrSource int - + const ( ProtoErr ErrSource = iota AppErr ) - + type SetRequest struct { Path string Payload []byte User string ClientVersion Version } - + type SetResponse struct { ErrSrc ErrSource Err error } - + type GetRequest struct { Path string User string ClientVersion Version } - + type GetResponse struct { Payload []byte ErrSrc ErrSource } - + type ActionRequest struct { Path string Payload []byte User string ClientVersion Version } - + type ActionResponse struct { Payload []byte ErrSrc ErrSource } - + type BulkRequest struct { DeleteRequest []SetRequest ReplaceRequest []SetRequest @@ -1152,14 +1171,14 @@ Translib is a library that adapts management server requests to SONiC data provi User string ClientVersion Version } - + type BulkResponse struct { DeleteResponse []SetResponse ReplaceResponse []SetResponse UpdateResponse []SetResponse CreateResponse []SetResponse } - + type SubscribeRequest struct { Paths []string Q *queue.PriorityQueue @@ -1167,7 +1186,7 @@ Translib is a library that adapts management server requests to SONiC data provi User string ClientVersion Version } - + type SubscribeResponse struct { Path string Payload []byte @@ -1175,19 +1194,19 @@ Translib is a library that adapts management server requests to SONiC data provi SyncComplete bool IsTerminated bool } - + type NotificationType int - + const ( Sample NotificationType = iota OnChange ) - + type IsSubscribeRequest struct { Paths []string User string } - + type IsSubscribeResponse struct { Path string IsOnChangeSupported bool @@ -1195,13 +1214,13 @@ Translib is a library that adapts management server requests to SONiC data provi Err error PreferredType NotificationType } - + type ModelData struct { Name string Org string Ver string } - + type Version struct { Major uint32 Minor uint32 @@ -1234,7 +1253,7 @@ App Interface helps in identifying the App module responsible for servicing the model - Filled ModelData structure containing the Name, Organisation and version of the model that is being supported. Returns: error - error string - + App Interface Structures: //Structure containing App module information type AppInfo struct { @@ -1243,7 +1262,7 @@ App Interface helps in identifying the App module responsible for servicing the IsNative bool tablesToWatch []*db.TableSpec } - + Example Usages: func init () { log.Info("Init called for ACL module") @@ -1252,11 +1271,11 @@ App Interface helps in identifying the App module responsible for servicing the ygotRootType: reflect.TypeOf(ocbinds.OpenconfigAcl_Acl{}), isNative: false, tablesToWatch: []*db.TableSpec{&db.TableSpec{Name: ACL_TABLE}, &db.TableSpec{Name: RULE_TABLE}}}) - + if err != nil { log.Fatal("Register ACL App module with App Interface failed with error=", err) } - + err = appinterface.AddModel(&gnmi.ModelData{Name:"openconfig-acl", Organization:"OpenConfig working group", Version:"1.0.2"}) @@ -1264,7 +1283,7 @@ App Interface helps in identifying the App module responsible for servicing the log.Fatal("Adding model data to appinterface failed with error=", err) } } - + type AclApp struct { path string YGOTRoot *YGOT.GoStruct @@ -1297,7 +1316,7 @@ This RequestBinder module exposes the below mentioned APIs which will be used to appRootNodeType - pointer to the reflect.Type object of the App module root node's YGOT structure object Returns: requestBinder - pointer to the requestBinder object instance - + func (binder *requestBinder) unMarshall() (*YGOT.GoStruct, *interface{}, error) This method is be used to unmarshall the request into Go structure objects, and validates the request against YANG model schema Returns: @@ -1317,7 +1336,7 @@ These utilities methods provides below mentioned common operations on the YGOT s interface{} - pointer to the parent object of the given target object's URI path YANG.Entry - pointer to the YANG schema of the parent object error - error object to describe the error if this methods fails to return the parent object, otherwise nil - + func getNodeName(targetUri *string, deviceObj *ocbinds.Device) (string, error) This method is used to get the YANG node name of the given target object's uri path. Input parameters: @@ -1326,7 +1345,7 @@ These utilities methods provides below mentioned common operations on the YGOT s Returns: string - YANG node name of the given target object error - error object to describe the error if this methods fails to return the parent object, otherwise nil - + func getObjectFieldName(targetUri *string, deviceObj *ocbinds.Device, YGOTTarget *interface{}) (string, error) This method is used to get the go structure object field name of the given target object. Input parameters: @@ -1415,14 +1434,14 @@ Detail Method Signature: Concurrent Access via Redis CAS transactions: Upto 4 levels of concurrent write access support. - + 1. Table based watch keys (Recommended): At App module registration, the set of Tables that are to be managed by the module are provided. External (i.e. non-Management-Framework) applications may choose to watch and set these same table keys to detect and prevent concurrent write access. The format of the table key is "CONFIG_DB_UPDATED_". (Eg: CONFIG_DB_UPDATED_ACL_TABLE) - + 2. Row based watch keys: For every transaction, the App module provides a list of keys that it would need exclusive access to for the transaction to succeed. Hence, @@ -1431,10 +1450,10 @@ Concurrent Access via Redis CAS transactions: concurrent modification of yet to be created keys (i.e. keys which are not in the DB, but might be created by a concurrent application) may not be detected. - + 3. A combination of 1. and 2.: More complex, but easier concurrent write access detection. - + 4. None: For applications not needing concurrent write access protections. @@ -1950,7 +1969,7 @@ module sonic-acl-deviation { RClient *redis.Client //Redis client } ``` - + ###### 3.2.2.8.3 CVL APIs ``` @@ -2032,7 +2051,7 @@ module sonic-acl-deviation { CVL_INTERNAL_UNKNOWN /*Internal unknown error */ CVL_FAILURE /* Generic failure */ ) -``` +``` 1. func Initialize() CVLRetCode - Initialize the library only once, subsequent calls does not affect once library is already initialized . This automatically called when if ‘cvl’ package is imported. @@ -2079,6 +2098,149 @@ Please see [3.2.2.6.5 DB access layer](#32265-db-access-layer) Currently, it is up to each App module to perform the proprietary access mechanism for the app specific configuration. +##### 3.2.2.11 NETCONF Server + +The management NETCONF server is a NETCONF server implemented in Go language. +It supports following operations: + +* NETCONF RPCs for YANG data + +###### 3.2.2.11.1 Transport options + +NETCONF server supports only SSH transport and listens on default port 830. +Server port can be changed through an entry in ConfigDB NETCONF_SERVER table. + +By default a temporary SSH Host Keys is used by the SSH Server. +It can be overridden by specifiying a valid SSH Host key file +paths through the NETCONF_SERVER table. + +NETCONF_SERVER table schema is described in [DB Schema](#322414-db-schema) section. + +###### 3.2.2.11.2 Translib linking + +NETCONF server will statically link with Translib. For each NETCONF request, the server +invokes Translib API which then invokes appropriate App module to process the request. +Below is the mapping of NETCONF operations to Translib APIs: + + NETCONF Method | Translib API | Request data | Response data +----------------|------------------|---------------|--------------- + | translib.Get | path | status, payload + others to be added ... + +More details about Translib APIs are in section [3.2.2.6](#3_2_2_6-Translib). + + +###### 3.2.2.11.3 Media Types + +NETCONF Protocol uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. +Request and response payloads follow [RFC6241](https://tools.ietf.org/html/rfc6241) +defined encoding rules. + +###### 3.2.2.11.4 Payload Validations + +NETCONF server does not validate request payload for YANG defined NETCONF RPCs. +Payload will be validated automatically in lower layers when it gets loaded +into YGOT bindings. + +###### 3.2.2.11.5 Concurrency + +REST server will accept concurrent requests. Translib provides appropriate locking mechanism - parallel reads and sequential writes. + +###### 3.2.2.11.6 Versioning + +NETCONF server will Support Netconf 1.1. + +###### 3.2.2.11.8 NETCONF Discovery + +RNETCONF server supports following RPCs for clients to discover various NETCONF data models supported by the NETCONF server as described in [RFC6022](https://tools.ietf.org/html/rfc6022), via the NETCONF RPC. + + +###### 3.2.2.11.8.1 YANG module library + +NETCONF server allows clients to discover and download all YANG modules supported by the server by retrieving the /netconf-state/schemas subtree via a operation.. Response data includes YANG module information as per [RFC6022](https://tools.ietf.org/html/rfc6022) requirements. + +NETCONF server allows clients to download the YANG files via NETCONF RPC. +YANG module library response includes full yang file for every YANG module entry. + +###### 3.2.2.11.8.2 NETCONF capabilities + +NETCONF server advertise its capabilities as described in [RFC6241, section 8](https://tools.ietf.org/html/rfc6241#section-8). + +Netconf server supports the following capabilities: +* Support Running Configuration Datastore (RFC 8342 Section 5.1.2) +* Support Writeable-Running Capability (RFC 6241 Section 8.2) + urn:ietf:params:netconf:capability:writable-running:1.0 +* Support Startup Configuration Datastore (RFC 8342 Section 5.1.1) +* Support Distinct Startup Capability (RFC 6241 Section 8.7) + urn:ietf:params:netconf:capability:startup:1.0 +* Support Copy running config to startup config (RFC 6241 Section 7.3) + runningstartup +* Support Lock and Unlock running config datastore (RFC 6241 Section 7.5 and 7.6) + +Netconf server does not support the following capabilities: +* No Support for Candidate Configuration Capability (RFC 6241 Section 8.3) +* No Support for Confirmed Commit Capability (RFC 6241 Section 8.4) + +###### 3.2.2.11.9 NETCONF Operations + +The NETCONF server uses an RPC-based communication model. NETCONF peers use and elements to provide framing of NETCONF requests and responses. + +YGOT binding objects are not available for YANG RPC input and output data model. +Hence payload validation is not performed by REST server or Translib for these APIs. +App modules will receive raw JSON data. + +Netconf server supports the following operations: +* (RFC 6241 Section 7.7) +* (RFC 6241 Section 7.1) +* (RFC 6241 Section 7.3) +* (RFC 6241 Section 7.5) +* (RFC 6241 Section 7.6) +* (RFC 6241 Section 7.8) +* (RFC 6241 Section 7.9) +* (RFC 6022 Section 3.1) + +###### 3.2.2.11.10 RESTCONF Notifications + +NETCONF Notification are not supported by framework. Clients can use gNMI for monitoring and notifications. + +###### 3.2.2.11.11 Authentication + +NETCONF server supports following authentication modes. + +* Password authentication (username/password authentication) +* TACACS authenticaation. +* No authentication + +Details are in [SONiC RBAC HLD](https://github.com/project-arlo/SONiC/blob/master/doc/aaa/SONiC%20RBAC%20HLD.md). + +By default password authentication is enabled. +It can be overridden through ConfigDB [NETCONF_SERVER table](#322414-db-schema) entry. + +###### 3.2.2.11.12 Error Response + +The NETCONF server will reply back with error in several situations, to be defined ... + +###### 3.2.2.4.13 DB Schema + +A new table "NETCONF_SERVER" is introduced in ConfigDB for maintaining NETCONF server configurations. + + key = NETCONF_SERVER|default ; NETCONF server configurations. + ;field = value + port = 1*5DIGIT ; server port - defaults to 830 + client_auth = "none" / "password" / "jwt" / "cert" + ; Client authentication mode. + ; none: No authentication, all clients + ; are allowed. Should be used only + ; for debugging. + ; password: password authentication. + log_level = DIGIT ; Verbosity for glog.V logs + ssh_key = 1*VCHAR ; Path to SSH Host Key file + + +###### 3.2.2.11.14 API Documentation + +NETCONF server will provide all schemas, check section 3.2.2.11.8.3. + ## 4 Flow Diagrams ### 4.1 REST SET flow @@ -2196,6 +2358,27 @@ Above is the sequence diagram explaining the CVL steps. Note that interaction be 25. Write lock acquired in Step 3 is released. 26. Final response is returned from the Translib infra to REST/GNMI. +### 4.3 NETCONF flow + +1. NETCONF request from the NETCONF client is sent to the NETCONF Server. +2. NETCONF Server invokes a common request handler. +3. Authentication of the incoming request is performed. +4. Request handler calls the Translib exposed GET API with the uri of the request. +5. Translib infra gets the App module corresponding to the incoming uri. +6. Translib infra calls the initialize function of the App module with the YGOT structures and path. App module caches them. +7. Status retuned from App module. +8. App module queries Transformer to translate the path to the Redis keys that need to be queried. +9. Status returned from App module. +10. Translib infra calls the processGet function on the App module +11. App modules calls read APIs exposed by the DB access layer to read data from the Redis DB. +12. Data is read from the Redis DB is returned to the App module +13. App module fills the YGOT structure with the data from the Redis DB and validated the filled YGOT structure for the syntax. +14. App module converts the YGOT structures to JSON format. +15. IETF JSON payload is returned to the Translib infra. +16. IETF JSON payload is returned to the request handler. +17. Response is returned to NETCONF Server. +18. NETCONF response is returned to the NETCONF client from the NETCONF server. + ## 5 Developer Work flow Developer work flow differs for standard YANG (IETF/OpenConfig) vs proprietary YANG used for a feature. When a standards-based YANG model is chosen for a new feature, the associated Redis DB design should take the design of this model into account - the closer the mapping between these, then the less translation logic is required in the Management path. This simplifies the work flow as translation intelligence can be avoided as both Redis schema and NB YANG schema are aligned. diff --git a/doc/mgmt/images/Mgmt_Frmk_Arch2.jpg b/doc/mgmt/images/Mgmt_Frmk_Arch2.jpg new file mode 100644 index 0000000000..b98497d4a1 Binary files /dev/null and b/doc/mgmt/images/Mgmt_Frmk_Arch2.jpg differ diff --git a/doc/mgmt/images/Mgmt_Frmk_Arch2.png b/doc/mgmt/images/Mgmt_Frmk_Arch2.png new file mode 100644 index 0000000000..a60ede781a Binary files /dev/null and b/doc/mgmt/images/Mgmt_Frmk_Arch2.png differ