Skip to content

Commit 0e7710c

Browse files
anand-kumar-subramaniananand-kumar-subramanian
authored
Merge pull request sonic-net#205 from a-barboza/debugsh_klish
Added klish_debugsh_cli_framework.md
2 parents a092576 + 337e63a commit 0e7710c

File tree

1 file changed

+332
-0
lines changed

1 file changed

+332
-0
lines changed

‎manageability/mgmt-framework/klish_debugsh_cli_framework.md

+332
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
# Feature Name
2+
KLISH Debug Shell CLI framework
3+
# High Level Design Document
4+
#### Rev 0.6
5+
6+
# Revision
7+
8+
# About this Manual
9+
This document provides general information about the executing [debugsh](#debugsh) CLI commands from sonic-cli/[KLISH](#KLISH).
10+
11+
# Scope
12+
This document describes the high level design of providing infra structure for running debugsh CLI commands from sonic-cli.
13+
14+
# Definition/Abbreviation
15+
16+
### Table 1: Abbreviations
17+
| **Term** | **Meaning** |
18+
| -------- | ---------------------------- |
19+
| CLI | Command Line Interface |
20+
| KLISH | Kommand Line Interface Shell |
21+
| debugsh | SONiC Debug Shell |
22+
23+
# Feature Overview
24+
25+
This feature provides the framework for integrating backend modules debug CLI commands with sonic-cli and the [Management Framework](#management-framework).
26+
27+
Currently debugsh supports 2 kinds of debug commands
28+
29+
* Backend or remote commands : Used to dump data stored in the heap memory of the backends. This information is typically not available in the redis DB. These commands will be supported in sonic-cli.
30+
31+
* Local or flex CLIs : These commands are used to gather information from various sources. For example backend, redis database, Linux commands, and the SDK shell. The information is then processed to show user friendly output like consistency checking, DB to Hardware mapping etc. These commands will not be supported.
32+
33+
**Only the debugsh backend commands are to be support in sonic-cli, and Management Framework.**
34+
35+
# Requirements
36+
37+
## Functional Requirements
38+
39+
Execute backend modules debugsh CLI commands from sonic-cli.
40+
41+
## Configuration and Management Requirements
42+
N/A
43+
44+
## Scalability Requirements
45+
N/A
46+
47+
## Warm Boot Requirements
48+
N/A
49+
50+
# Design
51+
52+
## Overview
53+
54+
debugsh uses a PUB-SUB mechanism to communicate with the backends to build its CLI tree, and execute commands with the backends. In a similar fashion, the [Management Framework](#management-framework) debugsh app module, will implement a SONiC Yang RPC to communicate with the backends. The KLISH will use this RPC RESTConf operation to execute commands. However, the RPC callback will be unaware of the CLI tree, and it will leave that task to the debugsh infra. Please see the [CLI](#cli) subsection for more details.
55+
56+
Please see the [Flow Diagram](#flow-diagram).
57+
58+
## DB Changes
59+
No planned DB Schema Changes
60+
61+
## User Interface
62+
63+
### Data Models
64+
65+
Outline of RPCs to be implemented
66+
67+
** sonic-debugsh.yang **
68+
69+
```
70+
71+
rpc exec
72+
input: backend tokens
73+
(Eg: vxlanmgrd show system internal vxlanmgr global)
74+
75+
output: list of strings
76+
(Eg:
77+
78+
VxlanHwCapability Enable
79+
Feature Capability: Vxlan(Enable) Vlan_Vni_Num(4096)
80+
81+
============== Pending Request Count===============
82+
tunnel_map:0 nvo:0 tunnel:0 vnet:0
83+
)
84+
85+
rpc option
86+
input: optionName optionVal
87+
(Eg: timeout 2)
88+
89+
output: {}
90+
91+
```
92+
93+
These SONiC RPCs are primarily for supporting the KLISH. Therefore, only the functionality needed for supporting KLISH is being implemented. Nothing prevents additional functionality from being added, say, for example, adding an RPC to get a listing of all the available debugsh CLI in the future.
94+
95+
### CLI
96+
97+
The debugsh infra already builds the CLI tree by parsing the CLI strings obtained from the backend. The debugsh CLI tree Klish XML file will be automatically generated by extending debugsh infra, and making this generated XML file available to the mgmt-framework container. A sanity check could be run on the generated XML file to ensure it is syntactically valid. The generation may take place right before the mgmt-framework container is declared up (i.e. when the RESTConf TCP port is available.). In normal circumstances, by the time networking infra is up, most backends should be ready to accept/process debugsh commands. If, however, a backend is not ready by then, another generation can take place right before the sonic-cli shell is launched for the missing backends. Currently, this operation is estimated to take in the order of 100ms. If greater time magnitudes are observed for this generation, an alternate background generation mechanism could be implemented.
98+
99+
#### Debug Commands
100+
101+
* **debug shell** (To enter the debugsh view/mode)
102+
* **show system internal ...**
103+
* **debug system internal ...**
104+
* **clear system internal ...**
105+
106+
* **timeout <1-180>** (Set the backend communication timeout)
107+
108+
** Due to the sensitive nature of these commands, they will be restricted to the admin user **
109+
110+
111+
For example:
112+
113+
```
114+
sonic-cli# debug shell
115+
sonic-cli(debugsh)# show system internal <tab>
116+
Possible completions:
117+
aclsvcd ACL Services daemon
118+
coppmgr CoppMgr daemon
119+
debugsh Debug Shell command
120+
fdbsync Fdbsync Services daemon
121+
intfmgr intfmgr related commands
122+
nbrmgrd nbrmgrd related commands
123+
orchagent Orchagent related commands
124+
sagmgr sagmgr related commands
125+
sai SAI Debug commands
126+
stpmgr stpmgr related commands
127+
syncd Syncd related commands
128+
teammgr TeamMgr related commands
129+
vxlanmgr vxlanmgr related commands
130+
sonic-cli(debugsh)#
131+
```
132+
133+
```
134+
sonic-cli(debugsh)# show system internal vxlanmgr global
135+
136+
VxlanHwCapability Enable
137+
Feature Capability: Vxlan(Enable) Vlan_Vni_Num(4096)
138+
139+
============== Pending Request Count===============
140+
tunnel_map:0 nvo:0 tunnel:0 vnet:0
141+
sonic-cli(debugsh)#
142+
```
143+
144+
```
145+
sonic-cli(debugsh)# debug system internal logger aclsvcd level info
146+
sonic-cli(debugsh)#
147+
```
148+
149+
```
150+
sonic-cli(debugsh)# clear system internal vlan ifp
151+
sonic-cli(debugsh)#
152+
```
153+
154+
```
155+
sonic-cli(debugsh)# timeout 2
156+
sonic-cli(debugsh)#
157+
```
158+
159+
#### IS-CLI Compliance
160+
debugsh is a SONiC specific implementation, thus there is no need for IS-CLI compliance
161+
162+
163+
### REST API Support
164+
See [Data Models](#data-models)
165+
166+
### gNMI Support
167+
No gNMI/gNOI access support is planned.
168+
169+
# Flow Diagrams
170+
171+
```
172+
173+
User sonic-cli# REST Server Redis Backend
174+
____ __________ ___________ _____ _______
175+
176+
o (1)
177+
-+- CLI
178+
| ----> .
179+
/ \ . (2)
180+
. RPC
181+
. exec
182+
. ------------> .
183+
. . (3)
184+
. . Publish
185+
. . -----------------> .
186+
. . .
187+
. . --+ .
188+
. . | (4) .
189+
. . | Wait .
190+
. . |for o/p .
191+
. ..<-+ .
192+
. .. .
193+
. .. . (5)
194+
. .. . Sub. Msg.
195+
. .. . ------------> .
196+
. .. .
197+
. .. (6) .
198+
. .. Publish .
199+
. .. . <------------ .
200+
. .. . o/p 1 .
201+
. .. (7) . .
202+
. .. Sub. Msg. . .
203+
. ...<---------------- . .
204+
. ... o/p 1 .
205+
. ... .
206+
. (8) ... .
207+
. Chunk ... .
208+
. <------------ ... .
209+
. o/p 1 .. .
210+
. .. .
211+
(9) . .. .
212+
<---- . .. .
213+
o/p 1 . .. .
214+
. .. .
215+
. .. (10) .
216+
. .. Publish .
217+
. .. . <------------ .
218+
. .. . o/p 2 .
219+
. .. (11) . .
220+
. .. Sub. Msg. . .
221+
. ...<---------------- . .
222+
. ... o/p 2 .
223+
. ... .
224+
. (12) ... .
225+
. Chunk ... .
226+
. <------------ ... .
227+
. o/p 2 .. .
228+
. .. .
229+
(13) . .. .
230+
<---- . .. .
231+
o/p 2 . .. .
232+
. .. .
233+
234+
235+
...
236+
237+
. .. .
238+
. .. (n-3) .
239+
. .. Publish .
240+
. .. . <------------ .
241+
. .. . END
242+
. .. (n-2) .
243+
. .. Sub. Msg. .
244+
. ...<---------------- .
245+
. ... END
246+
. ...
247+
. (n-1) ...
248+
. Chunk ...
249+
. <------------ ...
250+
.
251+
.
252+
(n) .
253+
<---- .
254+
255+
256+
```
257+
258+
Notes:
259+
260+
- The o/p returned to the sonic-cli could be sent either buffered or in chunks
261+
- For the initial release, we will implement returning all the data in one response chunk. Should a command which returns a large amount of output data be encountered, we could implement the chunked mechanism to prevent flow-control issues.
262+
263+
# Error Handling
264+
N/A
265+
266+
# Serviceability and Debug
267+
N/A
268+
269+
# Warm Boot Support
270+
N/A
271+
272+
# Scalability
273+
N/A
274+
275+
# Limitations
276+
277+
- Only the debugsh backend commands are to be supported in sonic-cli.
278+
- If a developer adds more backend commands to a backend on a live system, they would have to regenerate the KLISH XML file for debugsh, by restarting the KLISH sonic-cli shell.
279+
- If a backend takes a long amount of time to come online (relative to the mgmt-framework being declared up), the KLISH XML file would have to be regenerated, by restarting the KLISH sonic-cli shell, once that backend came online.
280+
281+
- KLISH sonic-cli handling of newlines is different from debugsh handing of newlines. Thus newlines (or other whitespace) differences between sonic-cli, and debugsh may exist. This behavior is also observed for KLISH sonic-cli save-to-file filter (i.e. a command similar to no-more which may appear after the pipe on the KLISH command line).
282+
283+
- If a backend does not send a newline after the last line, some versions of debugsh erase it while printing the prompt for the next command. This may be confirmed using typescript logs.
284+
285+
- Parameter descriptions, and detected syntax errors by the KLISH sonic-cli will follow KLISH style, and thus will be different from debugsh styles.
286+
287+
- Restriction checking for keyword prefixed integer ranges (Eg: Trigger[1-32]) is an approximation. No known examples exist so far, but the debugsh capability exists for this. A tighter restriction can be developed with more time investment, when an example shows up.
288+
289+
290+
# Unit Test
291+
292+
| **Test** | **Description** |
293+
| ------------------------------ | ---------------------------------------- |
294+
| | |
295+
| KLISH XML Autogeneration | Generate KLISH XML by running sonic-cli |
296+
| | |
297+
| REST Yang RPC (exec) | SONiC debugsh RPC for executing backend |
298+
| | debugsh commands |
299+
| | |
300+
| REST Yang RPC (option) | SONiC debugsh RPC for setting options |
301+
| | for communicating with backend |
302+
| | |
303+
| KLISH show | Execute KLISH debugsh show command and |
304+
| | compare with native debugsh command |
305+
| | |
306+
| KLISH debug | Execute KLISH debugsh debug command and |
307+
| | compare with native debugsh command |
308+
| | |
309+
| KLISH clear | Execute KLISH debugsh clear command and |
310+
| | compare with native debugsh command |
311+
| | |
312+
| KLISH timeout | Execute KLISH debugsh timeout command and|
313+
| | compare with native debugsh command |
314+
| | |
315+
316+
# References
317+
318+
## Management Framework
319+
320+
https://github.com/Azure/SONiC/blob/master/doc/mgmt/Management%20Framework.md
321+
322+
## KLISH
323+
324+
https://github.com/Azure/SONiC/blob/master/doc/mgmt/Management%20Framework.md#3221-cli
325+
326+
## debugsh
327+
328+
https://docs.google.com/document/d/1kMpJ2k4CIBn-08TTKlYqxTBlDrmVNg5El7htcJ5sPxc
329+
330+
"Debugsh provides a mechanism to display backend data which is typically not available in the database. It can also be used to enable certain debug features during runtime on need basis like enabling some debug prints, debug checks etc."
331+
332+

0 commit comments

Comments
 (0)