Skip to content
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

Jump to bottom

able to uggrade hostOS of openBalena-devices #382

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

able to uggrade hostOS of openBalena-devices #382

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
165 changes: 165 additions & 0 deletions README.md
View file
Open in desktop
@@ -1,6 +1,171 @@
# balenaHUP
Tool for balena host OS updates. It downloads an update bundle that replaces the balenaOS for a balena device, updating both the boot partition and the rootfs (using an inactive rootfs partition).


## Upgrade balenaOS with openBalena-Devices

This version allows you to upgrade official balena-devices and also devices which are connected to an third-party openBalena-api-endpoint.
It combines the public api and your custom
The official balena-API uses an SSH Proxy.
To use the updgrade scripts for your openBalen environment you have to set up the ssh connection with an proxytunnel.
With some modifications in following files it is possible to upgrade balena and openBalena devices.

+ upgrade-ssh-2.x.sh
+ upgrade-2.x.sh

For upgradeing an openBalena device we need also this file:
+ update-balena-supervisor.sh

`update-balena-supervisor.sh` is stored in the balenaOS image (/usr/bin/update-balena-supervisor) but at current developement state it is impossible to upgrade the supervisor with it.
So the upgrade script upload the modified version and uses this custom-version during the upgrade process.


To upgrade your openBalena devices only this command line is neccessary to run:

````
./upgrade-ssh-2.x.sh --uuid <uid_device_1> --uid <uid_device_2> --hostos-version 3.0.5 --no-delta --open-balena
````

### New start parameters for upgrade-ssh-2.x.sh script

1. --open-balena

* use own proxytunnel for ssh-connection
* copy modified update-balena-supervisor.sh to device's /tmp folder
* use public balena api to get informaions about the registry path of the given hostos-version
* use private device open balena api to set get device specific informations
* start modified update-balena-supervisor.sh after upgrading os-system
* use public balena api to get informaions about the correct supervisor version and registry path of the needed supervisor version

2. --no-delta

do not search for delta updates, only install complete image

3. --verbose

do not log into log files, print everything to your unix-device to be able to debug the upgrade process.

## Helpfull informations

After building/compiling the complete OS from the source code, the build-system will generate an docker-image, which includes the "upgrade-image" of the operation system for the specific device-type.

**Beware**:
The naming is quite confusing because, docker use the word image for docker - registry entries and for example for an raspberry pi a image is the operation system file to flash the device.

So this image-file will be uploaded into the public openBalena docker-registry.(`registry2.balena-cloud.com`)
The information which is available for specific device-types is stored in the public balenaAPI (`https://api.balena-cloud.com/v6/release`, complete commando below)


Running start the `upgrade-ssh-2.x.sh` script with the needed hostOs Version will check if the device is online.
If it is only, the script will start the upgrade-2.x.sh script with ssh remote on the device.
This script is running directly on the specific device.

It will make some prerequisites checks and will parse the docker-registry-image-path to the specific hostOS version of the specific devices hardware type (like raspberrypi4-64)

After it have all information it will start the script hostapp-update what comes with the operating system. (/usr/bin/hostapp-update)

This script will download the docker-imager from the given docker registry link and will extract the new raspberry pi "image" to the second partition.

After this magic is done, the `upgrade-2.x.sh` will search for the correct supervisor version in the public balena api.
The new supervisor is also stored in a docker-image available in the public docker-registry.


**Beware**:
The supervisor upgrade script `/usr/bin/update-balena-supervisor` is not able to work with open balena. Due this reason the scp command will copy a customized version to the /tmp folder of the device.

This script will download the new supervisor version from the docker-registry and extract all files.
After the upgrade is done the system will reboot




## Prerequisites

+ You have to be able to connect to your devices with an simple ssh command.

For example `ssh <your_uid>.balena`

to archive these you have to set up and proxy tunnel server

Use this git-repo to build your ssh-proxy-server:
https://github.com/balena-io/balena-cli/blob/96774f4c52b155b7761e6ee70ba505149b318d3c/lib/utils/tunnel.ts#L24

and these settings on your ubuntu/unix environment

````
we need 3 configuration files
~/.ssh/balena.proxytunnel (Proxytunnel-Credentials for your proxy tunnel https://tunnel.<company-url>)
~/.ssh/config.balena-proxy (openssh-parameter to log into sshd of your BalenaOS-Devices)
~/.ssh/config.balena-names (name list of your devices)

install the application proxytunnel on your system
sudo apt install proxytunnel

set -u # print error, if $BALENA_API_KEY is not set (access-token for openbalena):
echo -e "proxy_user = admin\nproxy_passwd = $BALENA_API_KEY" >~/.ssh/balena.proxytunnel
chmod 600 ~/.ssh/balena.proxytunnel # proxytunnel will check that.
cat >"$HOME/.ssh/config.balena-proxy" <<EOH
Host *.balena
User root
Port 22222
RequestTTY yes
ProxyCommand proxytunnel -E -p tunnel.<company-url>:443 -d %h:%p -F $HOME/.ssh/balena.proxytunnel
EOH

# needed if you want to connect via the name of the device to the device
balena devices --json|jq -r \
'.[] | "Host \(.device_name).balena \(.fleet|sub("admin/";"")).balena\n\tHostname \(.uuid).balena\n"' \
>~/.ssh/config.balena-names



nano ~/.ssh/config
add at the end of all lines
Include config.balena-names
Include config.balena-proxy


#if everything is configured correctly then you will be able to use ssh, scp and rsync with your openBalena devices
ssh <your_uid>.balena
````


+ Otherwise change this file and implement your own ssh-proxy command

## Helper commands

* list all available host-os for specific device type:

this huge command will list all available hostos - versions:
````
device=raspberrypi4-64 && curl "https://api.balena-cloud.com/v6/release?\$select=id,semver&\$expand=contains__image/image&\$filter=(belongs_to__application/any(a:a/is_for__device_type/any(dt:dt/slug%20eq%20%27${device}%27)%20and%20is_host%20eq%20true))%20and%20is_final%20eq%20true%20and%20is_invalidated%20eq%20false%20and%20semver%20ne%20%270.0.0%27%20and%20(release_tag/any(rt:(rt/tag_key%20eq%20%27version%27)))%20and%20((release_tag/any(rt:(rt/tag_key%20eq%20%27variant%27)%20and%20(rt/value%20eq%20%27production%27)))%20or%20not(release_tag/any(rt:rt/tag_key%20eq%20%27variant%27)))"| jq -r ".d[].semver"
````

## To Do

Update the update-balena-supervisor in the meta-balenaos repository.
`https://github.com/balena-os/meta-balena/blob/master/meta-balena-common/recipes-containers/balena-supervisor/balena-supervisor/update-balena-supervisor`

## Start upgrading your open balena deevice


## Warning of deprecated informations

All following information seems to be outdated.
For all new devices only to files of the complete git-repo are neeeded.

+ upgrade-ssh-2.x.sh
+ upgrade-2.x.sh

For upgradeing an openBalena device we need also this file:
+ update-balena-supervisor.sh

All other files, scripts, dockerfiles and folders are not needed anymore!

`update-balena-supervisor.sh` is stored in the balenaOS image (/usr/bin/update-balena-supervisor) but at current developement state it is impossible to upgrade the supervisor with it.



Be aware that in the current stage of development **this tool is not meant to be ran by itself but through a** [wrapper](https://github.com/balena-os/meta-balena/blob/master/meta-balena-common/recipes-support/balenahup/balenahup/run-resinhup.sh) developed in [meta-balena](https://github.com/balena-os/meta-balena). This wrapper takes care of all the prerequisites needed for this tool and adds support for balena Supervisor updates as well. In this way, using that wrapper, a device can be updated completely (balenaOS + Supervisor).

The current development stage uses **docker images/containers to deploy and run** this tool. This is because when we first developed this tool the balenaOS was not providing all the python prerequisites needed for it to successfully work. The long term plan would be to bring it completely in the balenaOS including all the prerequisites. This is not completely decided because balenaOS has hard requirements on rootfs size and we try to keep it as small as possible. So this docker container solution is kept for now even though it adds the overhead of downloading an image before being able to run the updater.
Expand Down