summaryrefslogtreecommitdiffstats
path: root/docs/modules/ROOT/pages/meta-updater-usage.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'docs/modules/ROOT/pages/meta-updater-usage.adoc')
-rw-r--r--docs/modules/ROOT/pages/meta-updater-usage.adoc87
1 files changed, 87 insertions, 0 deletions
diff --git a/docs/modules/ROOT/pages/meta-updater-usage.adoc b/docs/modules/ROOT/pages/meta-updater-usage.adoc
new file mode 100644
index 0000000..cc53a9f
--- /dev/null
+++ b/docs/modules/ROOT/pages/meta-updater-usage.adoc
@@ -0,0 +1,87 @@
1= Usage
2:meta-updater-github-url: https://github.com/advancedtelematic/meta-updater/tree/master
3:metadata-expiry-article: xref:dev@ota-client::metadata-expiry.adoc[OTA Connect documentation]
4ifdef::env-github[:metadata-expiry-article: link:https://docs.ota.here.com/ota-client/dev/metadata-expiry.html[OTA Connect documentation]]
5
6//MC: No overlap with any content currently in the developer guide, but probably useful content to clean up and include. eg: use cases.
7
8== OSTree
9
10OSTree used to include a simple HTTP server as part of the ostree binary, but this has been removed in more recent versions. However, OSTree repositories are self-contained directories, and can be trivially served over the network using any HTTP server. For example, you could use Python's SimpleHTTPServer:
11
12....
13cd tmp/deploy/images/qemux86-64/ostree_repo
14python -m SimpleHTTPServer <port> # port defaults to 8000
15....
16
17You can then run ostree from inside your device by adding your repo:
18
19....
20# This behaves like adding a Git remote; you can name it anything
21ostree remote add --no-gpg-verify my-remote http://<your-ip>:<port>
22
23# If OSTREE_BRANCHNAME is set in local.conf, that will be the name of the
24# branch. If not set, it defaults to the value of MACHINE (e.g. qemux86-64).
25ostree pull my-remote <branch>
26
27# poky is the OS name as set in OSTREE_OSNAME
28ostree admin deploy --os=poky my-remote:<branch>
29....
30
31After restarting, you will boot into the newly deployed OS image.
32
33For example, on the raspberry pi you can try this sequence:
34
35....
36# add remote
37ostree remote add --no-gpg-verify agl-snapshot https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi3/deploy/images/raspberrypi3/ostree_repo/ agl-ota
38
39# pull
40ostree pull agl-snapshot agl-ota
41
42# deploy
43ostree admin deploy --os=agl agl-snapshot:agl-ota
44....
45
46== garage-push
47
48The https://github.com/advancedtelematic/aktualizr[aktualizr repo] contains a tool, garage-push, which lets you push the changes in OSTree repository generated by bitbake process. It communicates with an http server capable of querying files with HEAD requests and uploading them with POST requests. In particular, this can be used with https://connect.ota.here.com/[HERE OTA Connect]. garage-push is used as follows:
49
50....
51garage-push --repo=/path/to/ostree-repo --ref=mybranch --credentials=/path/to/credentials.zip
52....
53
54You can set `SOTA_PACKED_CREDENTIALS` in your `local.conf` to automatically synchronize your build results with a remote server. Credentials are stored in an archive as described in the xref:dev@ota-client::provisioning-methods-and-credentialszip.adoc[aktualizr documentation].
55
56== aktualizr configuration
57
58https://github.com/advancedtelematic/aktualizr[Aktualizr] supports a variety of xref:dev@ota-client::aktualizr-config-options.adoc[configuration options via a configuration file and the command line]. There are two primary ways to control aktualizr's configuration from meta-updater.
59
60First, you can set `SOTA_CLIENT_PROV` to control which provisioning recipe is used. Each recipe installs an appropriate `sota.toml` file from aktualizr according to the provisioning needs. See the xref:dev@ota-build::sota-variables.adoc[SOTA-related variables in local.conf] section for more information.
61
62Second, you can write recipes to install additional config files with customized options. A few recipes already exist to address common needs and provide an example:
63
64* link:{meta-updater-github-url}/recipes-sota/config/aktualizr-auto-reboot.bb[aktualizr-auto-reboot.bb] configures aktualizr to automatically reboot after new updates are installed in order to apply the updates immediately. This is only relevant for package managers (such as OSTree) that require a reboot to complete the installation process. If this is not enabled, you will need to reboot the system through other means.
65* link:{meta-updater-github-url}/recipes-sota/config/aktualizr-disable-send-ip.bb[aktualizr-disable-send-ip.bb] disables the reporting of networking information to the server. This is enabled by default and supported by https://connect.ota.here.com/[HERE OTA Connect]. However, if you are using a different server that does not support this feature, you may want to disable it in aktualizr.
66* link:{meta-updater-github-url}/recipes-sota/config/aktualizr-log-debug.bb[aktualizr-log-debug.bb] sets the log level of aktualizr to 0 (trace). The default is 2 (info). This recipe is intended for development and debugging purposes.
67
68To use these recipes, you will need to add them to your image with a line such as `IMAGE_INSTALL_append = " aktualizr-log-debug "` in your `local.conf`.
69
70== aktualizr service resource control
71
72With systemd based images, it is possible to set resource policies for the aktualizr service. The main use case is to provide a safeguard against resource exhaustion during an unforeseen failure scenario.
73
74To enable it, install `aktualizr-resource-control` on the target image and optionally override the default resource limits set in link:{meta-updater-github-url}/recipes-sota/aktualizr/aktualizr_git.bb[aktualizr_git.bb], from your `local.conf`.
75
76For example:
77
78....
79IMAGE_INSTALL_append += " aktualizr-resource-control "
80RESOURCE_CPU_WEIGHT_pn-aktualizr = "50"
81....
82
83=== garage-sign configuration
84
85The https://github.com/advancedtelematic/ota-tuf/tree/master/cli[garage-sign] tool can be configured with variables described in the xref:sota-variables.adoc[SOTA-related variables in local.conf] section.
86
87Of particular importance is controlling the expiration of the Targets metadata signed with garage-sign. This is described in detail in the {metadata-expiry-article}. To set a manual expiration date, you can use either of the variables `GARAGE_TARGET_EXPIRES` or `GARAGE_TARGET_EXPIRE_AFTER`. Both cannot be supplied simultaneously. If neither are provided, a default of one month will be used. \ No newline at end of file