Skip to content

Add README.md for describing bootconfig and oc_cli #209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add README.md for describing bootconfig and oc_cli #209

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a69efd4
Add README.md for describing bootconfig and oc_cli
marcushines Aug 28, 2024
87a06fb
Add section on no use of RPC
marcushines Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions bootconfig/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Bootconfig API

The bootconfig service is responsible for the setting of bootstrap configuration for the device after initial Bootz bootstrap.
This message may include both the base device configuration but also the new gNSI artifacts.

While this is service which can be used out of band it also allows for the development of an industry standard CLI for recovery
Copy link
Member

@robshakir robshakir Jan 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Industry-standard CLI tool? When I read "industry standard" and "CLI" I think CLI format, which I think isn't what you're proposing.

Copy link
Contributor Author

@marcushines marcushines Jan 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i don't quite follow? i am saying that all vendors should provide a binary which has a standard set of sub commands and args

Copy link
Contributor Author

@marcushines marcushines Mar 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if you mean the cli has consistent args / params for calls and always returns structured data that is exactly what i am saying is a requirement here

of devices.

## RPC use case

* From remote rpc client call `gnoi.Bootconfig.Set` using bootconfig message containing elements to override.

## CLI use cases

The CLI should be bundled with the router and exist in the default path.
The CLI must be named `oc_cli` it must have the following heirarchy for calling specific services.
This CLI must not use RPC's to services to interact with services as the use of the service would be
for emergency recovery of the device.

```
oc_cli
gnoi
bootconfig
factoryreset
gnmi
get
set
subscribe
```
Comment on lines +21 to +29
Copy link

@LimeHat LimeHat Aug 28, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are these real gnmi/gnoi calls, e.g. there's a gnmi and gnoi clients on the node that can be accessed using this brand new cli? And, correspondingly, there's a grpc server that listens for these commands?

Copy link
Contributor Author

@marcushines marcushines Dec 10, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no they would use the same expected library that the server on device would use for consistency but would not be an RPC call to those services as the point of this cli is to bypass those services not working due to auth or other system configuration issues

Copy link
Member

@robshakir robshakir Jan 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems quite critical to call out in this documentation -- a comment could be (especially for the gNMI requirements) that we should make this binary just be gnmic, but you're explicitly saying that this isn't the case.

Given this, I wonder whether we have use cases for these that are well understood, and understand how this would be implemented - since (for example) this might mean duplicating code for e.g., OC translation across the daemon that does this, and the CLI tool itself. It's not immediately clear to me whether this comes at a high cost or not -- and how it would be operationally used. Can't I do most "fixing things in the config" by just being able to set the boot config assuming I've bricked the device?

Copy link
Contributor Author

@marcushines marcushines Mar 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so that is the most general of use case yes and that is one of the cli commands (the set boot config has to be standard and recoverable without a remote client being able to call into the device as the breakage may have broken grpc connectivity


### Recovery using bootz.BootConfig.Set

* Access the device CLI using SSH or console.
* Use a CLI command to invoke a gnoi bootconfig.

```
cli> scp remotehost:/filename ./local_bootzdata
cli> oc_cli gnoi bootconfig --reboot ./local_bootzdata
Successfully set boot config to ./local_bootzdata
Are you sure? (y/n): y
Rebooting…
```

### Recovery using gnoi.FactoryReset

* Access the device CLI using SSH or console.
* Use a CLI command to invoke a gnoi factory reset.

```
cli> oc_cli gnoi factoryreset
Are you sure? (y/n): y
Factory reset in progress…
```

* This will cause the device to perform the gnoi.FactoryReset process. The device will return to its factory default configuration and reboot. When booting, the bootz process should be performed, resulting in a gRPC accessible device.
Loading