balena-mdns-publisher

The MDNS publisher advertises a set of local IP addresses for a local network (<tld>.local) instance of the balena-on-balena (BoB) or OpenBalena (OB) services. The same IP address is used for all services in the BoB or OB instance.

This allows any machine on the same subnet that is not more than one hop from the publisher and BoB/OB instance to automatically be able to resolve the hostnames used for the instance (as long as the machine supports mDNS/DNS-SD, also known as 'ZeroConf' networking).

Prerequisites

The host machine running the publisher service must be running an instance of the Avahi daemon, which this service uses for address publishing.

Additionally, the service requires the ability to use systemd (ie. access to host cgroups or relevant tmpfs mount), and the host DBUS socket.

Installation and Running

This service can be run under a Linux environment, either any standard distribution running docker, or a resinOS device. The two configurations require separate setup, however. A docker-compose service is used here to show how to configure the service, and each specific target.

Docker Setup

Regardless of target, the service requires particular environment variables and access to the host network. The following docker-compose snippet shows the requirements for running the service:

balena-mdns-publisher:
    image: 'balena/balena-mdns-publisher:master'
    network_mode: host
    cap_add:
        - SYS_RESOURCE
        - SYS_ADMIN
    security_opt:
        - 'apparmor:unconfined'
    tmpfs:
        - /run
        - /sys/fs/cgroup
    environment:
        <See 'Environment Variables' section>

Generic Linux Host

Additionally, for a generic Linux host running Avahi and Docker, the following should be included in the service definition to expose the DBUS socket to the correct place inside the service container:

volumes:
    - /run/dbus/system_bus_socket:/host/run/dbus/system_bus_socket

Alternatively you may change the in-container location of the DBUS socket, but you must set DBUS_SESSION_BUS_ADDRESS envvar to the same location value.

balenaOS Device

Should the target be a balenaOS device, then the following section should also be included to ensure that the DBUS socket is mapped and environment variables is set:

 labels:
	io.balena.features.dbus: '1'

Environment Variables

The mDNS publisher requires some additional environment variables be passed to it on execution to allow it to function correctly. These are

• CONFD_BACKEND - This should always be set to ENV
• MDNS_TLD - This is the full Top Level Domain of the host being published
• MDNS_SUBDOMAINS - An array of subdomains to publish host addresses for
• INTERFACE - The name of the host network interface to publish the subdomain addresses too. If this is set, it will override the returned default interface
• DBUS_SESSION_BUS_ADDRESS - This must always be set to unix:path=/host/run/dbus/system_bus_socket' (unless the DBUS target is located elsewhere)
• MDNS_API_TOKEN (optional) - Should Public URL exposure be required, then the shared API token for the Proxy service should be set using this key. The API will be queried every 20 seconds, and any new device with an exposed public URL will have its UUID published as a subdomain. Previously published UUIDs that no longer have a public URL will be deleted
• BALENA_ROOT_CA (optional) - Should the certificate chain used for the BoB/OB instance be via a self-signed CA, this value should be a Base64 encoded version of the CA's PEM certificate

This allows the acquisition of the underlying DBUS socket, as well as the ability to run systemd.

Example docker-compose Service

The following is an example of adding the balena mDNS publisher to a BoB instance running under balenaOS:

balena-mdns-publisher:
    image: 'balena/balena-mdns-publisher:master'
    network_mode: host
    cap_add:
        - SYS_RESOURCE
        - SYS_ADMIN
    security_opt:
        - 'apparmor:unconfined'
    tmpfs:
        - /run
        - /sys/fs/cgroup
    labels:
        io.balena.features.dbus: '1'
    environment:
        CONFD_BACKEND: ENV
        MDNS_TLD: my.bob.local
        MDNS_SUBDOMAINS: >-
            ["admin", "api", ...]
        MDNS_API_TOKEN: 1234567890abcdef
        DBUS_SESSION_BUS_ADDRESS: 'unix:path=/host/run/dbus/system_bus_socket'
        BALENA_ROOT_CA: >-
            1234567890abcdef