What we call "Orbit" is actually a group of components:
1. Orbit executable: Orbit is the director of the orchestra. It manages itself all the other components.
2. Osquery executable/bundle.
3. "Fleet Desktop" application: Renders Fleet's tray icon on the user desktop session and provides transparency to the end-user about what Fleet collects from the device.
# Auto-update
Orbit runs an auto-updater routine that polls a [TUF](https://theupdateframework.io/) server for new
updates in any of the three
components mentioned above. Each component (also known as "target") can be updated independently. This document aims to
describe all the steps needed to release a new version of each target.
8. Download and extract the assets (one for each platform Orbit supports).
9. Push the downloaded+extracted assets to the `edge` channel on our TUF repository (https://tuf.fleetctl.com/):
```sh
# Having extracted the asset for Linux in `./orbit-linux`
fleetctl updates add \
--path $STAGING_TUF_PATH_LOCATION \
--target orbit \
--platform linux \
--name ./orbit-linux \
--version X.Y.Z -t X.Y -t X -t edge
# Having extracted the asset for Linux in `./orbit-darwin`
fleetctl updates add \
--path $STAGING_TUF_PATH_LOCATION \
--target orbit \
--platform macos \
--name ./orbit-darwin \
--version X.Y.Z -t X.Y -t X -t edge
# Having extracted the asset for Windows in `./orbit.exe`
fleetctl updates add \
--path $STAGING_TUF_PATH_LOCATION \
--target orbit \
--platform windows \
--name ./orbit.exe \
--version X.Y.Z -t X.Y -t X -t edge
```
### Verification
Verifier will make sure all the hosts have updated the target successfully. The update interval delay can be up to 15 minutes.
Verifier can run `SELECT * from orbit_info;` live query on the hosts, which will provide the orbit version (confirming the update was successful).
Once orbit has auto-updated on all hosts, Verifier runs the usual smoke testing on the 4 OSs (e.g. refetching & live querying hosts, listing software, etc.).
## 2. Stable Release
### Setup
Verifier runs the same setup as `edge`, but without setting the `--orbit-channel` flag (the default value is `stable`).
### Steps
Run the same `fleetctl updates add` command as the `edge` case with the same targets, but with `-t stable`.
### Verification
Verification is the same as with the `edge` case.
# Updating Osquery
## 1. Edge Release
### Setup
The Verifier will setup a CentOS, Ubuntu, Windows and macOS host with `osqueryd` that uses the `edge` channel:
It generates the osqueryd targets for macOS, Windows and Linux as artifacts.
4. Download the artifacts from the previous step and push them to the `edge` channel:
```sh
# Having extracted the asset for Linux in `./osqueryd`
fleetctl updates add \
--path $STAGING_TUF_PATH_LOCATION \
--target osqueryd \
--platform linux \
--name ./osqueryd \
--version X.Y.Z -t X.Y -t X -t edge
# Having extracted the asset for Linux in `./osqueryd.app.tar.gz`
fleetctl updates add \
--path $STAGING_TUF_PATH_LOCATION \
--target osqueryd \
--platform macos-app \
--name ./osqueryd.app.tar.gz \
--version X.Y.Z -t X.Y -t X -t edge
# Having extracted the asset for Windows in `./osqueryd.exe`
fleetctl updates add \
--path $STAGING_TUF_PATH_LOCATION \
--target osqueryd \
--platform windows \
--name ./osqueryd.exe \
--version X.Y.Z -t X.Y -t X -t edge
```
### Verification
Verifier will make sure all the hosts have updated the target successfully. The update interval delay can be up to 15 minutes.
Verifier can run `SELECT * from osquery_info;` live query on the hosts, which will provide the osquery version (confirming the update was successful).
Once osqueryd has auto-updated on all hosts, Verifier runs the usual smoke testing on the 4 OSs (e.g. refetching & live querying hosts, listing software, etc.).
## 2. Stable Release
### Setup
Verifier runs the same setup as `edge`, but without setting the `--osqueryd-channel` flag (the default value is `stable`).
### Steps
Run the same `fleetctl updates add` command as the `edge` case with the same targets, but with `-t stable`.
### Verification
Verification is the same as with the `edge` case.
# Updating Fleet Desktop
## 1. Edge Release
### Setup
The Verifier will setup a CentOS, Ubuntu, Windows and macOS host with `desktop` that uses the `edge` channel:
It generates the desktop targets for macOS, Windows and Linux as artifacts.
4. Download the artifacts from the previous step and push them to the `edge` channel:
```sh
# Having extracted the asset for Linux in `./desktop.tar.gz`
fleetctl updates add \
--path $STAGING_TUF_PATH_LOCATION \
--target desktop \
--platform linux \
--name ./desktop.tar.gz \
--version X.Y.Z -t X.Y -t X -t edge
# Having extracted the asset for Linux in `./desktop.app.tar.gz`
fleetctl updates add \
--path $STAGING_TUF_PATH_LOCATION \
--target desktop \
--platform macos \
--name ./desktop.app.tar.gz \
--version X.Y.Z -t X.Y -t X -t edge
# Having extracted the asset for Windows in `./fleet-desktop.exe`
fleetctl updates add \
--path $STAGING_TUF_PATH_LOCATION \
--target desktop \
--platform windows \
--name ./fleet-desktop.exe \
--version X.Y.Z -t X.Y -t X -t edge
```
### Verification
Verifier will make sure all the hosts have updated the target successfully. The update interval delay can be up to 15 minutes.
Currently, there's no direct way to verify the auto-update for the Fleet Desktop application.
One way to verify is to check for `INF exiting due to successful update` in the Orbit logs.
Once the Fleet Desktop Application has auto-updated on all hosts, Verifier runs the usual smoke testing on the 4 OSs (e.g. refetching & live querying hosts, listing software, etc.).
## 2. Stable Release
### Setup
Verifier runs the same setup as `edge`, but without setting the `--desktop-channel` flag (the default value is `stable`).
### Steps
Run the same `fleetctl updates add` command as the `edge` case with the same targets, but with `-t stable`.
