Branding & Releases =================== This document is for projects using Infix as a br2-external, i.e., OEMs. Branding -------- Branding is done in menuconfig, there are several settings affecting it, most are in the Infix external subsection called "Branding", but there is also `BR2_TARGET_GENERIC_HOSTNAME`, which deserves a special mention. The hostname is used for the system default `/etc/hostname`, which is the base name for the "unique:ified" hostname + the last three octets of the base MAC[^1] address, e.g., `infix-c0-ff-ee`. This in turn is the hostname that is set at first boot and also advertised by device discovery protocols like mDNS-SD and LLDP. See the help texts for the *Infix Branding* settings to understand which ones are mandatory and which are optional, menuconfig does not check this for you and you may end up with odd results. Verify the result after a build by inspecting: - `output/images/*`: names, missing prefix, etc. - `output/target/etc/os-release`: this file is sourced by other build scripts, e.g., `mkgns3a.sh`. For reference, see https://www.freedesktop.org/software/systemd/man/os-release.html > **Note:** to get proper GIT revision (hash) from your composed OS, > remember in menuconfig to set `INFIX_OEM_PATH`. When unset the > Infix `post-build.sh` script defaults to the Infix base path. The > revision is stored in the file `/etc/os-release` as BUILD_ID and > is also in the file `/etc/version`. See below for more info. [^1]: The base MAC address is defined in the device's Vital Product Data (VPD) EEPROM, or similar, which is used by the kernel to create the system interfaces. This MAC address is usually also printed on a label on the device. Factory Defaults ---------------- The Infix default configuration, factory-config, is part static files and part per-device generated files, e.g., SSH hostkey and hostname. The latter is constructed from the file `/etc/hostname`, appended with the last three octets of the system's base MAC address. To override the base hostname, set `BR2_TARGET_GENERIC_HOSTNAME` in your defconfig. The static files are installed by Infix `confd` in `/usr/share/confd/` at build time. It contains two subdirectories: /usr/share/confd/ |- factory.d/ | |- 10-foo.json | |- 10-bar.json | `- 10-qux.json `- failure.d/ |- 10-xyzzy.json `- 10-garply.json To override, or extend, these files in you br2-external, set up a rootfs overlay and add it last in `BR2_ROOTFS_OVERLAY`. Your overlay can look something like this: ./board/common/rootfs/ |- etc/ | |- confdrc # See below | `- confdrc.local `- usr/ `- share/ `- confd/ |- 10-foo.json # Override Infix foo |- 30-bar.json # Extend, probably 10-bar.json `- 30-fred.json # Extend, your own defaults Using the same filename in your overlay, here `10-foo.json`, completely replaces the contents of the same file provided by Infix. If you just want to extend, or replace parts of an Infix default, use `30-....json`. Here the file `30-bar.json` is just a helpful hit to maintainers of your br2-external that it probably extends Infix' `10-bar.json`. The reason for the jump in numbers is that 20 is reserved for files generated by Infix' `gen-function` scripts. Your br2-external can provide a few custom ones that the `bootstrap` knows about, e.g., `gen-ifs-custom` that overrides `20-interfaces.json`. See the bootstrap script for more help, and up-to-date information. > **Note:** you may not need to provide your own `/etc/confdrc`. The > one installed by `confd` is usually enough. However, if you want to > adjust the behavior of `bootstrap` you may want to override it. There > is also `confdrc.local`, which usually is enough to change arguments > to scripts like `gen-interfaces`, e.g., to create a bridge by default, > you may want to look into `GEN_IFACE_OPTS`. Integration ----------- When integrating your software stack with Infix there may be protocols that want to change system settings like hostname and dynamically set IP address and default gateway, e.g. PROFINET. This section detail a few recommendations for maintaining co-existence in this scenario of the multiple producers problem. First, there's a clear difference between "singleton" like hostsname and an interface IP address. Consider the case of a static IP and a DHCP assigned IP, these can co-exist because of the `proto NUM` field available in iproute2. This is used in Infix so that static addresses can be flushed independently of DHCP addresses. The same can be done by other "address providers", e.g., PROFINET. Changing properties like hostname should be done by injecting a change into Infix, by for example calling `sysrepocfg -Ediff.xml`. Here is an example of how to get the current hostname and apply an XML diff: ``` root@infix-00-00-00:~# sysrepocfg -X -x "/system/hostname" > hostnm.xml root@infix-00-00-00:~# cat hostnm.xml infix-00-00-00 root@infix-00-00-00:~# edit hostnm.xml root@infix-00-00-00:~# sysrepocfg -Ehostnm.xml root@example:~# ``` Second, perform all changes on `running-config`, the running datastore. That way you have a clear state to return to if your application needs to do a factory reset. E.g., in PROFINET a type 1/2 factory reset will reset only the PROFINET specific settings. That way you can actually have your system `startup-config` disable all physical ports and the PROFINET application enables only ports that are not deactivated. (On factory reset it will not know of any ports to deactivate so it will activate all.) You can consider the system composed of two entities: - NETCONF starts up the system using `startup-config`, then - Hands over control to your application at runtime Infix is prepared for this by already having two "runlevels" for these two states. The `startup-config` is applied in runlevel S (bootstrap) and the system then enters runlevel 2 for normal operation. This allow you to keep a set of functionality that is provided by the underlying system, and another managed by your application. You can of course in your br2-external provide a sysrepo plugin that block operations on certain datastores when your application is enabled. E.g., to prevent changes to startup after initial deployment. In that case a proper factory reset would be needed to get back to a "pre-deployment" state where you can reconfigure your baseline. Releases -------- A release build requires the global variable `INFIX_RELEASE` to be set. It can be derived from GIT, if the source tree is kept in GIT VCS. First, let us talk about versioning in general. ### Versioning Two popular scheme for versioning a product derived from Infix: 1. Track Infix major.minor, e.g. *Foobar v23.08.z*, where `z` is your patch level. I.e., Foobar v23.08.0 could be based on Infix v23.08.0, or v23.08.12, it is up to you. Maybe you based it on v23.08.12 and then back ported changes from v23.10.0, but it was the first release you made to your customer(s). 2. Start from v1.0.0 and step the major number every time you sync with a new Infix release, or every time Infix bumps to the next Buildroot LTS. The important thing is to be consistent, not only for your own sake, but also for your end customers. The *major.minor.patch* style is the most common and often recommended style, which usually maps well to other systems, e.g. PROFINET GSDML files require this (*VX.Y.Z*). But you can of course use only two numbers, *major.minor*, as well. > What could be confusing, however, is if you use the name *Infix* > with your own versioning scheme. ### `INFIX_RELEASE` This global variable **must be** a lower-case string (no spaces or other characters outside of 0–9, a–z, '.', '_' and '-') identifying the operating system version, excluding any OS name information or release code name, and suitable for processing by scripts or usage in generated filenames. Used for `VERSION` and `VERSION_ID` in `/etc/os-release` and generated file names like disk images, etc. **Default:** generated using `git describe --always --dirty --tags`, with an additional `-C $infix_path`. This variable defaults to the Infix tree and can be changed by setting the menuconfig branding variable `INFIX_OEM_PATH` to that of the br2-external. It is also possible to set the `GIT_VERSION` variable in your `post-build.sh` script to change how the VCS version is extracted.