diff --git a/OPERATOR_CONSOLE.md b/OPERATOR_CONSOLE.md new file mode 100644 index 00000000..36327b94 --- /dev/null +++ b/OPERATOR_CONSOLE.md @@ -0,0 +1,98 @@ +# Local Operator Console (LOC) API + +This document explains the Local Operator Console(LOC) from the API point of view. + +This document is similarly structured as PROFILE.md, because the topic is very similar. + +## What is Local Operator Console? + +Local Operator Console is kind of a miniature controller that allows to run certain +commands (see [Compound Config](###Compound-Config)) without connection to the real +controller. One main usage is for air-gap environments, where devices are offline +and connection to the remote controller is not available or when the connection +to the controller is slow or lots of packets get lost. + +## Differences Between Local Operator Console and Local Profile Server + +| | LOC | LPS | +|----------------------------------------|----------|--------------------| +| Can Handle more than 1 device | Y | N | +| Uses security token for authentication | N | Y | +| Needs config from controller | Y | N | +| Runs on | Edge App | Anywhere reachable | + +## Server endpoint + +EVE periodically sends a `CompoundEdgeDevConfigRequest` to the Local Operator Console. +EVE can find the URL to the LOC in `loc_url` which is part of the +`EdgeDevConfig` that EVE received from the controller. + +## Endpoints + +In the following `$UUID` is the uuid of the edge node contacting LOC. +All endpoints return with `Content-Type` set to `application/x-proto-binary`. + +### Certs + +```http + + GET /api/v2/edgedevice/certs +``` + +Returns the controller certificates as defined in `ZControllerCert` in `certs/certs.proto` +file. It is encapsulated in an `AuthContainer` as defined in `auth/auth.proto` file. +The container is not verified. + +### Config + +```http + POST /api/v2/edgedevice/id/$UUID/config +``` + +Returns the signed config from the controller. It is an `config/EdgeDevConfig` +and the definition can be found in the `devconfig.proto` file. + +### Compound Config + +```http + POST /api/v2/edgedevice/id/$UUID/compound-config +``` + +Returns the signed edge device config as part of the compound config. It also includes: + +* current Unix timestamp in nano seconds precision +* device command +* app commands +* radio config + +The device command can be: + +* shutdown of the device +* shutdown and poweroff of the device +* reboot of the device +* run collect-info and upload the tarball to the configured datastore via POST/PUT + +The app commands can be: + +* restart of the app +* purge of the app + +The definition can be found as `CompoundEdgeDevConfig` in `config/compound_devconfig.proto`. + +### Edge Metrics + +```http + POST /api/v2/edgedevice/id/$UUID/metrics +``` + +This is where the metrics are sent. Similar to the controller API. +It is a `ZMetricMsg` as defined in `metrics/metrics.proto`. + +### Edge Info + +```http + POST /api/v2/edgedevice/id/$UUID/info +``` + +This is where the info messages are sent. Similar to the controller API. +It is a `ZInfoMsg` as defined in `logs/log.proto`.