package gnoi.os

Get desktop application:
View/edit binary Protocol Buffers messages

The OS service provides an interface for OS installation on a Target. The Client progresses through 3 RPCs: 1) Installation - provide the Target with the OS package. 2) Activation - activate an installed OS package. 3) Verification - verify that the Activation was successful. Dual Supervisor Target is supported, where the above process is executed once for each Supervisor. Note that certain platforms may have particular approaches to upgrade the firmware of specific components, eg., power supply units, etc.. In addition, platforms may have processes to apply patches to the running OS. Handling these exceptions introduces extra complexities. For Targets that implement this service, component firmware upgrade or OS patching MUST be embedded within an OS upgrade.

• rpc Install (stream InstallRequest, stream InstallResponse)

  os.proto:107

  Install transfers an OS package into the Target. No concurrent Install RPCs MUST be allowed to the same Target. The OS package file format is platform dependent. The platform MUST validate that the OS package that is supplied is valid and bootable. This SHOULD include a hash check against a known good hash. It is recommended that the hash is embedded in the OS package. The Target manages its own persistent storage, and OS installation process. It stores a set of distinct OS packages, and always proactively frees up space for incoming new OS packages. It is guaranteed that the Target always has enough space for a valid incoming OS package. The currently running OS packages MUST never be removed. The Client MUST expect that the last successfully installed package is available. The Install RPC allows the Client to specify the OS package version. If the Target already has an OS package with the same version then there is no need to transfer the OS package to the Target. If the Target does not have an OS package with the same version, then the OS package is copied. Scenario 1 - When the Target already has the OS package: Client :--------------|--------------> Target TransferRequest --> <-- [Validated|InstallError] Scenario 2 - When the Target does not have the OS package: Client :--------------|--------------> Target TransferRequest --> <-- [TransferReady|InstallError] transfer_content --> ... <-- [TransferProgress|InstallError] ... TransferEnd --> <-- [Validated|InstallError] On a dual Supervisor Target, only the Active Supervisor runs this gNOI Service. The Install RPC applies to the Active Supervisor unless InstallRequest->TransferRequest->standby_supervisor is set, in which case it applies to the Standby Supervisor. One Install RPC is required for each Supervisor. The Supervisor order of package installation MUST not be fixed. The Target MUST always attempt to copy the OS package between Supervisors first before accepting the transfer from the Client. The syncing progress is reported to the client with InstallResponse->SyncProgress messages. If a switchover is triggered during the Install RPC, the RPC MUST immediately abort with Error->type->UNEXPECTED_SWITCHOVER. Scenario 3 - When both Supervisors already have the OS package, regardless of the value in Start.standby_supervisor: Client :--------------|--------------> Target TransferRequest --> <-- [Validated|InstallError] Scenario 4 - When one of the Supervisors already has the OS package but the other Supervisor is the target of the Install: Client :--------------|--------------> Target TransferRequest --> <-- [SyncProgress|InstallError] ... <-- [Validated|InstallError] Scenario 5 - When neither of the two Supervisors has the OS package: Client :--------------|--------------> Target TransferRequest --> <-- [TransferReady|InstallError] transfer_content --> ... <-- [TransferProgress|InstallError] ... TransferEnd --> <-- [Validated|InstallError]

  message InstallRequest

  os.proto:119

  • oneof request

    • TransferRequest transfer_request = 1

    • bytes transfer_content = 2

    • TransferEnd transfer_end = 3

  message InstallResponse

  os.proto:167

  The InstallResponse is used by the Target to inform the Client about the state of the Install RPC. At any stage of the process the Target can reply with an Error message which MUST terminate the stream.

  • oneof response

    • TransferReady transfer_ready = 1

    • TransferProgress transfer_progress = 2

    • SyncProgress sync_progress = 3

    • Validated validated = 4

    • InstallError install_error = 5

• rpc Activate (ActivateRequest, ActivateResponse)

  os.proto:112

  Activate sets the requested OS version as the version which is used at the next reboot, and reboots the Target. When booting the requested OS version fails, the Target recovers by booting the previously running OS package.

  message ActivateRequest

  os.proto:247

  The ActivateRequest is sent by the Client to the Target to initiate a change in the next bootable OS version that is to be used on the Target.

  • string version = 1

    The version that is required to be activated and booted.

  • bool standby_supervisor = 2

    For dual Supervisors setting this flag instructs the Target to perform the action on the Standby Supervisor.

  message ActivateResponse

  os.proto:258

  The ActivateResponse is sent from the Target to the Client in response to the Activate RPC. It indicates the success of making the OS package version active.

  • oneof response

    • ActivateOK activate_ok = 1

    • ActivateError activate_error = 2

• rpc Verify (VerifyRequest, VerifyResponse)

  os.proto:116

  Verify checks the running OS version. This RPC may be called multiple times while the Target boots, until successful.

  message VerifyRequest

  os.proto:286

  (message has no fields)

  message VerifyResponse

  os.proto:288

  • string version = 1

    The OS version currently running.

  • string activation_fail_message = 2

    Informational message describing fail details of the last boot. This MUST be set when a newly transferred OS fails to boot and the system falls back to the previously running OS version. It MUST be cleared whenever the systems successfully boots the activated OS version.

  • optional VerifyStandby verify_standby = 3

Used in: ActivateResponse

• ActivateError.Type type = 1

• string detail = 2

Used in: ActivateError

• UNSPECIFIED = 0

  An unspecified error. Must use the detail value to describe the issue.

• NON_EXISTENT_VERSION = 1

  There is no OS package with the version requested for activation. This is also used for an empty version string.

If the Target is already running the requested version in ActivateRequest, then it replies with ActivateOK. If the Target has the OS package version requested in ActivateRequest then it replies with ActivateOK and proceeds to boot. In a Target with dual Supervisor, performing this RPC on the Active Supervisor triggers a switchover before booting the (old)Active Supervisor. The Target should always perform a switchover with the least impact possible to forwarding.

Used in: ActivateResponse

(message has no fields)

The InstallError message MUST be sent by the Target to the Client whenever an issue occurs. The Target MUST immediately close the RPC without a gRPC error.

Used in: InstallResponse

• InstallError.Type type = 1

• string detail = 2

Used in: InstallError

• UNSPECIFIED = 0

  An unspecified error. Must use the detail value to describe the issue.

• INCOMPATIBLE = 1

  The newly transferred package is not compatible with the Target platform. The detail field MUST contain the detailed error message.

• TOO_LARGE = 2

  The OS package being transferred is larger than the available size the Target provisioned. This is unexpected since the Target MUST clear disk space for the new OS packages. The available space and the OS package size MUST be guaranteed by the platform maker, therefore the most likely cause of this error is that a wrong package is being transferred.

• PARSE_FAIL = 3

  Used whenever the system is unable to parse the newly transferred package, like reading the OS version or the integrity checksums.

• INTEGRITY_FAIL = 4

  The transferred OS package fails integrity check.

• INSTALL_RUN_PACKAGE = 5

  Attempting to force transfer an OS package with the same version as the currently running.

• INSTALL_IN_PROGRESS = 6

  Another Install RPC to this Target is already in progress.

• UNEXPECTED_SWITCHOVER = 7

  A switchover happened during the Install RPC.

• SYNC_FAIL = 8

  Failed to sync the transferred OS package to the standby Supervisor. The detail value MUST have more information.

Used in: VerifyStandby

• string id = 1

  Standby Supervisor ID, usually the slot number.

• string version = 2

• string activation_fail_message = 3

Used in: VerifyStandby

• StandbyState.State state = 1

Used in: StandbyState

• UNSPECIFIED = 0

• UNSUPORTED = 1

  The Target does not support dual Supervisors.

• NON_EXISTENT = 2

  Standby Supervisor is supported but does not exist.

• UNAVAILABLE = 3

  Standby Supervisor is supported but is not available, eg.: rebooting.

The SyncProgress message signals the Client about the progress of transferring the OS package between Supervisors.

Used in: InstallResponse

• uint32 percentage_transferred = 1

  The percentage that has transferred between Supervisors.

The TransferEnd message is sent whenever the Client finishes transferring the OS package to the Target. At this point the Target MUST perform a general health check to the OS package. If the Target fails to parse the OS package it MUST immediately reply with an InstallError->type->PARSE_FAIL. If the integrity check of the OS package fails it MUST immediately reply with an InstallError->type->INTEGRITY_FAIL. If the identified OS version contained in the package is not compatible with the Target either because of the platform type or the running OS, it MUST immediately reply with an InstallError->type->INCOMPATIBLE. If the image is force transferred by omitting the InstallRequest->TransferRequest->version value, and the OS package is the same as the one running in the Target, the RPC MUST immediately abort and reply with an InstallError->type->INSTALL_RUN_PACKAGE.

Used in: InstallRequest

(message has no fields)

The TransferProgress message is sent by the target asynchronously during a file transfer. The device SHOULD not respond to each input block received from the client, but rather determine reasonable intervals at which to send the message (e.g., 5MB).

Used in: InstallResponse

• uint64 bytes_received = 1

  The number of bytes transferred.

The TransferReady message tells the Client that the Target is ready to accept the transfer of the OS package. At this stage the Target MUST have cleared enough space to accept the incoming OS package.

Used in: InstallResponse

(message has no fields)

Used in: InstallRequest

• string version = 1

  The version string is a vendor defined string that identifies the OS version. It is provided by the vendor and embedded in the OS package. This value states the desired OS package version to transfer to the Target. If the Target already has the OS package version it will reply with InstallResponse->Validated. In the case that the target is a single Supervisor device, or the partner Supervisor does not have the OS image specified, it will respond with InstallResponse->TransferReady. In this case, the client MUST subsequently transfer the image. In the case that the image is available on the peer Supervisor of a dual Supervisor system, it will respond with InstallResponse->SyncProgress. In this, latter, case - the client does not need to transfer the OS image. This value can also be set empty, in which case the OS package is forced transferred to the Target. The Target MUST never validate that this value matches the one in the InstallResponse->Validated message, that is the Client's responsibility.

• bool standby_supervisor = 2

  For a Target with dual Supervisors setting this flag instructs the Target to perform the action on the Standby Supervisor.

The Validated message asserts that the Target was able to parse the package and perform integrity checks to its contents.

Used in: InstallResponse

• string version = 1

  The OS version string that identifies the OS version in the OS package.

• string description = 2

  Informational field that SHOULD be used for providing more details about the OS package and its version. This MUST be strictly informational if used, and can contain information such as build date, target platform, developer, etc.

Used in: VerifyResponse

• oneof state

  • StandbyState standby_state = 1

  • StandbyResponse verify_response = 2