Posix Secondaries: bitbaking and usage of Primary and Secondary images
The goal of this doc is to guide a reader on bitbaking of two type of images primary
and secondary
that are targeted for QEMU or RPi
and running of which on the target makes it act as Primary
and Secondary
ECU of a single device.
Refer to the Uptane standard in order to grok the meaning of the Primary
and Secondary
terms in the given context from a theoretical standpoint.
Check out this doc to understand these terms from a practical standpoint and to learn how Primary
and Secondary
can be emulated locally on an user’s host.
It is highly advisable to follow the doc instructions and play with emulated Primary
and Secondary
prior to running steps described further in this doc.
Bitbaking
It is assumed that a reader is familiar with Yocto and bitbaking in general as well as bitbaking of Aktualizr images in particular, details of which are out of scope of this doc and can be found in the following guides:
Primary
To bitbake an image for Primary
run the following:
bitbake primary-image
Name | Default | Description |
---|---|---|
|
|
An IP address to assign to one of the Primary’s NIC for communication with Secondaries |
|
|
A TCP port that Primary aktualizr listens on for connections from Secondaries |
|
|
Time (seconds) to wait for connections from Secondaries. Note that, while a Primary can still function if some Secondaries failed to connect, it will only provision if all its Secondaries have connected before this delay. |
|
|
A space separated list of TCP/IP addresses of the Secondaries to be included into the list of ECUs served by the given Primary |
Note that PRIMARY_SECONDARIES can be a list of TCP/IP addresses in order to fulfill multiple secondaries use case.
For example, PRIMARY_SECONDARIES = "10.0.3.2:9050 10.0.3.3:9050 10.0.3.4:9050"
.
Secondary
To bitbake an image for Secondary
run the following:
bitbake secondary-image
Name | Default | Description |
---|---|---|
|
|
An IP address to assign to A Secondary NIC for communication with Primary |
|
|
A TCP port that Secondary listen on for connections from Primary |
Multiple secondaries use case
In order to support multiple secondaries use case an user should:
-
repeat the secondary bitbaking procedure corresponding number of times, each time
-
specifying unique TCP/IP address by means of
SECONDARY_IP
andSECONDARY_PORT
configuration variables -
copying and naming uniquely the resultant image file (e.g.
cp tmp/deploy/images/qemux86-64/secondary-image-qemux86-64.ota-ext4 secondary-images/secondary-image-qemux86-64.ota-ext4-001
)
-
-
bitbake the primary image with
PRIMARY_SECONDARIES
listing the corresponding secondaries TCP/IP addresses -
run the primary by following the guide in Running
-
run the secondaries by running the command specified in Running with a parameter pointing to corresponding secondary image. For example,
../meta-updater/scripts/run-qemu-ota --no-gui --secondary-network secondary-images/secondary-image-qemux86-64.ota-ext4-001
../meta-updater/scripts/run-qemu-ota --no-gui --secondary-network secondary-images/secondary-image-qemux86-64.ota-ext4-002
Specifics of bitbaking for Raspberry Pi
It is assumed that a reader is a familiar with bitbaking for Raspberry Pi in general, see Build a Raspberry Pi image.
The aforementioned/above guide is relevant and applicable to building a Raspberry images of Primay and Secondary. The following is specifics of building such images targeting RPi.
-
run
source meta-updater/scripts/envsetup.sh raspberrypi3
to get the build environment set up from a root of the yocto project (updater-repo) -
specify type of NIC to use for Primary for connection to Internet/backend. There are two options, ethernet NIC or Wifi. By default ethernet NIC is used which implies that Raspberry Pi is connected to LAN with an access to Internet. To use WiFi NIC the following configuration variables should be defined in your local configuration (local.conf):
Name | Default | Description |
---|---|---|
|
|
A flag to enable/disable (default) WiFi on RPi board. |
|
|
SSID of a WiFi network to connect to. The SSID is case sensitive. |
|
|
Password to connect to the WiFi network router. |
RPi networking details in a context of Posix secondaries support
IP/Posix secondaries support implies that a single primary ECU connected to two IP networks:
-
an IP network with an access to Internet for communication with the OTA backend;
-
an IP network that does not have access to Internet for communication with secondary ECU(s). The secondaries should be connected to this internal network.
Taking into account that RPi has two NICs, ethernet and wifi the aforementioned requirements to networking can be fulfilled by applying the following approaches.
Primary uses multihomed ethernet interface, Secondary uses ethernet interface
Both primary and secondary ECUs has wifi turned off and are connected to the same LAN (via switch or router) that has an access to Internet. Primary only network interface is configured in such way that it has two IP addresses assigned to it.
The first one (10.0.3.1 by default) is statically defined (can be configured via PRIMARY_IP
configuration variable)
and connects the primary to an internal IP network (10.0.3.0/8) that is aimed for communication with secondary ECU(s).
Secondary(ies) are connected to the same internal network (10.0.3.0/8) by assigning to their
ethernet interface corresponding IP addresses (10.0.3.x, 10.0.3.2 for the default only secondary, SECONDARY_IP
configuration variable).
The second IP address assigned to the primary ethernet NIC should be obtained from a DHCP server running on one of the devices (usually a router) that is connected to the given LAN, has an access to Internet and provides each host connected to the given IP network with access to Internet (via NATing IP packets, DHCP and NAT server can be hosted/running on different devices).
The given networking option is enabled by default.
Primary uses both wifi and ethernet interfaces, Secondary uses ethernet interface
Primary has wifi on, and its wifi NIC is connected to a LAN with an access to Internet. Also, Primary ethernet NIC
is assigned with an only IP address (10.0.3.1 by default) to connect to the internal network for communication
with secondary ECUs.
Secondary(ies) are connected to the same internal network (10.0.3.0/8) by assigning to their
ethernet interface corresponding IP addresses (10.0.3.x, 10.0.3.2 for the default only secondary, SECONDARY_IP
configuration variable).
Primary and Secondary uses wifi, only Primary uses ethernet NIC
In this case, both Primary and Secondary(ies) uses wifi NIC to connect to the internal network (wifi router should not have an Internet access). Secondary doesn’t use ethernet NIC. Primary connects to Internet via ethernet NIC that should be connected to LAN with an access to Internet. (This approach is not supported by meta-updater but can be applied by an advanced user.)
Running
It is assumed that a reader is familiar with details on running of bitbaked images targeted for QEMU, such information can be found in the following docs:
Usage
Once both Primary and Secondary VMs are running you should see that a new device has been registered at the server and you can start testing it. The following are Tips & Tricks for using & troubleshooting of the Primary and Secondary VMs.
-
run
journalctl -f -u aktualizr
to see logs that are being output by aktualizr running onPrimary
VM; -
run
journalctl -f -u aktualizr-secondary
to see logs that are being output by aktualizr-secondary (posix/IP secondary) running onSecondary
VM; -
By default, both aktualizr and aktualizr-secondary are running as systemd services. Use
systemctl stop|start|restart <aktualizr|aktualizr-secondary>
to control aktualizr and aktualizr-secondary daemons/services managed by systemd; -
To control aktualizr|aktualizr-secondary manually stop corresponding systemd service (see above) and run it from command line: just type
aktualizr' | `aktualizr-secondary
; -
By default, both executables output logs of level 1 (INFO), specify log level 0 in their config to see debug logs. In case of running from command line add corresponding parameter
<aktualizr|aktualizr-secondary> --loglevel 0
. In case of running as a systemd service add corresponding configuration fragment into /etc/sota/conf.d/ folder, e.g.echo -e "[logger]\nloglevel = 0" > /etc/sota/conf.d/50-debug-logs.toml
and restart the service; -
In order to trigger a device re-provisioning, please, remove the DB file on Primary, i.e.
rm /var/sota/sql.db
-
If the DB file is removed on Secondary then the device should be re-provisioned (see above), otherwise Primary/aktualizr will refuse to work with a 'new' secondary as it will have a "new" autogenerated ECU serial that doesn’t the one already been registered on Primary.
-
OTA Connect does not support adding/removing secondary ECUs to a device that has been already registered. Thus adding a new ECU to the list of secondaries on Primary won’t take much effect, the new ECU won’t appear on the UI and it will be listed as not registered by aktualizr-info.