project-arlo · olivier-singla · Jul 30, 2019 · Jul 30, 2019 · Jul 30, 2019 · Jul 30, 2019
diff --git a/doc/aaa/Persistent HTTP Connections from CLI.md b/doc/aaa/Persistent HTTP Connections from CLI.md
@@ -0,0 +1,60 @@
+Persistent HTTP connections from CLI
+====================================
+
+The SONiC CLI provided by the management framework container runs an instance of
+klish, which provides a fixed set of commands. The CLI is simply a front-end to
+the REST server, and each command is mapped to a corresponding REST endpoint.
+
+# Command Flow
+
+When the user enters a specific command on the CLI, the corresponding `ACTION`
+tag in the CLI XML specification shells out to a Python script with any
+arguments and an optional template to format the returned values. This script
+connects to the REST server on the local machine over HTTPS, retrieves and
+formats the JSON response. The Python script then exits, terminating any HTTP
+connection that had been set up.
+
+This is the current behavior, even without RBAC support, which means that every
+command will need to set up a new HTTPS connection. However, when RBAC is
+enabled, it is not likely to cause a noticeable performance impact, since the
+system is already incurring the TLS overhead.
+
+As can be seen from the flow above, it is not possible to set up a persistent
+HTTP connection, since every command spawns a new connection.
+
+# Alternative Designs
+
+This section describes some alternative designs that will enable the CLI to
+create a persistent connection.
+
+## Proxy service
+
+As part of the management framework, we can add a "proxy" service that is
+spawned with the CLI. This service will set up a secure HTTP connection for the
+authenticated user, and create a local unix socket that is accessible only by
+that user. The CLI XML will remain unchanged, but the Python ApiClient class
+will be changed to connect to the local socket.
+
+This will still create independent HTTP connections, but they can be insecure
+connections, while the proxy service will transfer the connections from the
+insecure unix socket to the secure tunnel, which will reduce the TLS connection
+time.
+
+**Note:** The security considerations have not been completely mapped out, and
+this may open the system up to security holes.
+
+## Klish modification
+
+This approach considers modifying the Klish executable.  When Klish is spawned,
+it will set up the HTTPS connection and keep it alive as long as the CLI is
+active. Each `ACTION` tag will call into klish functions that will connect to
+the existing HTTPS connection.
+
+This approach is the most secure option, however, it needs heavy modification to
+klish, and there are several unknowns at this time.
+
+## No modification - Buzznik
+
+This approach leaves the design as is for the Buzznik release. Every command
+will continue to create a new HTTPS connection, as it does today, and will tear
+down the connection on completion of the request.
diff --git a/doc/aaa/SONiC RBAC HLD.md b/doc/aaa/SONiC RBAC HLD.md
diff --git a/doc/ifa-hld.md b/doc/ifa-hld.md
@@ -0,0 +1,284 @@
+# Feature Name
+Inband Flow Analyzer.
+# High Level Design Document
+#### Rev 0.1
+
+# Table of Contents
+  * [List of Tables](#list-of-tables)
+  * [Revision](#revision)
+  * [About This Manual](#about-this-manual)
+  * [Scope](#scope)
+  * [Definition/Abbreviation](#definitionabbreviation)
+
+# List of Tables
+[Table 1: Abbreviations](#table-1-abbreviations)
+
+# Revision
+| Rev |     Date    |       Author       | Change Description                |
+|:---:|:-----------:|:------------------:|-----------------------------------|
+| 0.1 | 10/30/2019  |   Srinadh Penugonda| Initial version                   |
+
+# About this Manual
+This document provides general information about the Inband Flow Analyzer feature implementation in SONiC.
+# Scope
+This document describes the north bound interface and unit tests for Inband Flow Analyzer feature.
+
+# Definition/Abbreviation
+
+### Table 1: Abbreviations
+| **Term**                 | **Meaning**                         |
+|--------------------------|-------------------------------------|
+| IFA                      | Inband Flow Analyzer                |
+| TAM                      | Telemetry and Monitoring            |
+# 1 Feature Overview
+
+Inband Flow Analyzer is a flexible packet and flow monitoring inband telemtry solution. The feature allows configuration of IFA sessions that provide Inband telemetry over sampled traffic to collectors.
+
+It provides mechanism to monitor and analyze when packets enter/exit the network, the path packets and flows take through the network, the rate at which packets arrive at each hop and how log packets spend at each hop etc., Out of band management technhiques can not measure such details.
+
+## 1.1 Requirements
+
+### 1.1.1 Functional Requirements
+
+Provide management framework support to existing SONiC capabilities with respect to IFA.
+
+1.1 IFA feature is accomplished by configuring IFA session on various nodes that act as ingress,
+intermediate and egress devices. Device role is per flow in a node and a single node can act as ingress
+device for one flow and intermediate device for another flow.
+
+2.0.0.1 TAM device identifier to uniquely identify a device in network and insert the same in INT header.
+2.0.0.2 ACL configuration to identify a flow and sample packets from that flow to insert IFA headers.
+2.0.0.3 TAM collector configuration that can be attached to IFA flow on egress device to forward telemetry
+data.
+3.0 UI commands available to configure TAM device identifier, TAM collector and IFA configuration.
+3.1 UI commands available to show TAM device identifier, TAM collector, IFA configuration
+3.2 UI commands available to clear IFA configuration
+4.0 The maximum number of IFA 􀃖ows are platform dependent.
+4.1 Only one collector can be con􀃕gured in a device.
+4.5 Some platforms may require provisioning to enable IFA. 'ifa -config -enable' command to be issued to
+provision such platforms for IFA functionality. 'ifa -config -disable' command can be issued to disable
+provisioning of IFA on such platforms.
+
+### 1.1.2 Configuration and Management Requirements
+1. CLI configuration/show support
+2. REST API support
+3. gNMI support
+
+## 1.2 Design Overview
+### 1.2.1 Basic Approach
+
+As there is no opeconfig/ietf yang file exists for this feature, it is decided to go with sonic yang. 
+
+### 1.2.2 Container
+The changes are in sonic-management-framework container.
+
+There will be additional files added.
+1. XML file for the CLI
+2. Python script to handle CLI request (actioner)
+3. Jinja template to render CLI output (renderer)
+4. YANG models 
+	sonic-ifa.yang
+
+### 1.2.3 SAI Overview
+N/A
+
+# 2 Functionality
+## 2.1 Target Deployment Use Cases
+Whenever operator want to track packet latency/congestion metrics. 
+## 2.2 Functional Description
+The management UI provides an user friendly interface to configure Inband Flow Analyzer.
+# 3 Design
+## 3.1 Overview
+The packet action field in acl rule indicates the type of IFA device: ingress and egress. 'int_insert' makes the device as ingress IAF device and 'int_delete' as egress IFA device. Ingress IAF device makes a sample of a flow and tags them for analysis and data collection. Egress device is responsible for terminating IFA flow by summarizing the telemtry data of the entire path and sending it to the collector.
+
+The device identifer uniquely identifies the device in the network and inserts the ID in the IFA header.
+
+Collectors receive the telemetry data from egress devices.
+
+Flow configuration will contain sampling rate at which rate traffic will be sampled.
+
+IFA feature can be enabled or disabled.
+## 3.6 User Interface
+### 3.6.1 Data Models
+
+https://github.com/project-arlo/sonic-mgmt-framework/blob/master/models/yang/sonic/sonic-ifa.yang
+
+module: sonic-ifa
+    +--rw sonic-ifa
+       +--rw TAM_INT_IFA_FEATURE_TABLE
+       |  +--rw TAM_INT_IFA_FEATURE_TABLE_LIST* [name]
+       |     +--rw name      enumeration
+       |     +--rw enable?   boolean
+       +--rw TAM_INT_IFA_FLOW_TABLE
+          +--rw TAM_INT_IFA_FLOW_TABLE_LIST* [name]
+             +--rw name              string
+             +--rw acl-table-name    string
+             +--rw acl-rule-name     string
+             +--rw sampling-rate?    uint16
+             +--rw collector-name?   string
+
+https://github.com/project-arlo/sonic-mgmt-framework/blob/master/models/yang/sonic/sonic-tam.yang
+
+module: sonic-tam
+    +--rw sonic-tam
+       +--rw TAM_DEVICE_TABLE
+       |  +--rw TAM_DEVICE_TABLE_LIST* [name]
+       |     +--rw name        enumeration
+       |     +--rw deviceid?   uint16
+       +--rw TAM_COLLECTOR_TABLE
+          +--rw TAM_COLLECTOR_TABLE_LIST* [name]
+             +--rw name              string
+             +--rw ipaddress-type?   enumeration
+             +--rw ipaddress?        inet:ip-address
+             +--rw port?             inet:port-number
+
+### 3.6.2 CLI
+#### 3.6.2.1 Configuration Commands
+1. Command   : confg tam device-id 
+Attribute    : <id>
+The command is used to configure TAM device identifier.
+
+2. Command   : config tam collector
+Attribute(s) : {collector-name} ip-type <ipv4 | ipv6> ip-addr <address> port <port>
+The command is used to configure TAM collector and IFA report will be forwarded to the collector.
+
+3. Command   : config tam int-ifa feature
+Attribute    : <enable | disable>
+The command is used to enable or disable the IFA feature.
+
+4. Command   : config tam int-ifa flow 
+Attribute(s) : <flow-name> acl-rule <rule-name> acl-table <table-name> { sampling-rate <val> collector <name> }
+The command is used to specify flow criteria to match against incoming flow and tag with IFA data. When sampling rate is specified, one packet will be sampled out of its value. When collector is specified, IFA report will be forwarded to it.
+
+5. Command  : config-tam no device-id
+The command is used to clear user configured device identifier. Default device identifier is used.
+
+6. Command  : config-tam no collector 
+Attribute    : <name>
+The command is used to delete previously configured collector information.
+
+7. Command  : config-tam-int-ifa no flow
+Attribute    : <name>
+The command is used to delete previously configure flow information.
+
+#### 3.6.2.2 Show Commands
+1. Command   : show tam device
+The command is used to show TAM device identifier.
+
+2. Command   : show tam collector 
+Attribute    : { <name> | all }
+The command is used to show TAM collector information.
+
+3. Command   : show tam int-ifa flow
+Attribute(s) : { <name> | all }
+The command is used to display configured IFA flow information.
+
+4. Command   : show tam int-ifa statistics
+Attribute(s) : { <name> | all }
+The command is used to display statisitcs of IFA flow.
+
+5. Command   : show tam int-ifa status
+The command is used to display status of TAM.
+
+#### 3.6.2.3 Debug Commands
+N/A
+
+### 3.6.3 REST API Support
+
+1. Get Device Information
+sonic-tam:sonic-tam/TAM_DEVICE_TABLE
+
+2. Get Collector information
+sonic-tam:sonic-tam/TAM_COLLECTOR_TABLE
+
+3. Get particular collector information
+sonic-tam:sonic-tam/TAM_COLLECTOR_TABLE/TAM_COLLECTOR_TABLE_LIST={name}
+
+4. Get IFA feature information
+sonic-ifa:sonic-ifa/TAM_INT_IFA_FEATURE_TABLE
+
+5. Get IFA flow information
+sonic-ifa:sonic-ifa/TAM_INT_IFA_FLOW_TABLE
+
+6. Get particular IFA flow information
+sonic-ifa:sonic-ifa/TAM_INT_IFA_FLOW_TABLE/TAM_INT_IFA_FLOW_TABLE_LIST={name}
+
+7. Set device identifier
+sonic-tam:sonic-tam/TAM_DEVICE_TABLE/TAM_DEVICE_TABLE_LIST={device}/deviceid
+{
+  "sonic-tam:deviceid": 0
+}
+
+8. Set TAM collector
+sonic-tam:sonic-tam/TAM_COLLECTOR_TABLE/TAM_COLLECTOR_TABLE_LIST
+{
+  "sonic-tam:TAM_COLLECTOR_TABLE_LIST": [
+    {
+      "name": "string",
+      "ipaddress-type": "ipv4",
+      "v4addr": "string",
+      "v6addr": "string",
+      "port": 0
+    }
+  ]
+}
+
+9. Set TAM INT IFA feature
+sonic-ifa:sonic-ifa/TAM_INT_IFA_FEATURE_TABLE/TAM_INT_IFA_FEATURE_TABLE_LIST={feature}/enable
+{
+  "sonic-ifa:enable": true
+}
+
+10. Set TAM INT IFA flow
+sonic-ifa:sonic-ifa/TAM_INT_IFA_FLOW_TABLE/TAM_INT_IFA_FLOW_TABLE_LIST={name}
+{
+  "sonic-ifa:TAM_INT_IFA_FLOW_TABLE_LIST": [
+    {
+      "name": "string",
+      "acl-table-name": "string",
+      "acl-rule-name": "string",
+      "sampling-rate": 0,
+      "collector": "string"
+    }
+  ]
+}
+
+11. Delete TAM device identifier
+sonic-tam:sonic-tam/TAM_DEVICE_TABLE/TAM_DEVICE_TABLE_LIST={device}/deviceid
+
+12. Delete TAM collector
+sonic-tam:sonic-tam/TAM_COLLECTOR_TABLE/TAM_COLLECTOR_TABLE_LIST={name}
+
+13. Delete IFA flow
+sonic-ifa:sonic-ifa/TAM_INT_IFA_FLOW_TABLE/TAM_INT_IFA_FLOW_TABLE_LIST={name}
+
+
+# 4 Flow Diagrams
+N/A
+# 5 Error Handling
+N/A
+# 6 Serviceability and Debug
+TBD
+
+# 7 Warm Boot Support
+N/A
+# 8 Scalability
+N/A
+# 9 Unit Test
+| Test Name | Test Description |
+| :------ | :----- |
+| Create TAM DEvice Identifier | Verify device-id is configured. Verify a value with more than five digits will be rejected |
+| Delete TAM device Identifier | Verify when device-id is deleted, it defaults to default value of 0 |
+| Create TAM collector | Verify TAM collector is configured ( ip address validation is does by application ) |
+| Delete TAM collector | Verify TAM collector can be deleted |
+| Enable TAM INT IFA Feature | Verify user can enable/disable IFA feature |
+| Create IFA Flow | Verify IFA flow is configured. Verify configuration fails when user uses invalid acl table/rule. Verify configuration fails when user uses invalid collector name |
+| Delete IFA flow | Verify IFA flow is deleted |
+| Show TAM Device | Verify configured device identifier is displayed with the show command |
+| Show TAM collector | Verify all collectors are displayed with 'all' keyword. Verify specified collector is displayed with the name. Verify command fails when an invalid flow name is used to display |
+| Show TAM INT IFA flow | Verify all flow information is displayed when used with 'all'. Verify particular flow is displayed when name is supplied. Verify command fails when an non-existent flow name is given |
+| show tam int ifa supported | Verify feature status is correctly displayed |
+
+
+# 10 Internal Design Information
+N/A