https://github.com/redhatinsights/yggdrasil
https://github.com/redhatinsights/yggdrasil
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/redhatinsights/yggdrasil
- Owner: RedHatInsights
- License: gpl-3.0
- Created: 2020-08-31T18:33:03.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-24T09:11:01.000Z (2 months ago)
- Last Synced: 2025-03-29T19:07:19.310Z (2 months ago)
- Language: Go
- Size: 813 KB
- Stars: 22
- Watchers: 24
- Forks: 37
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://godocs.io/github.com/redhatinsights/yggdrasil)
# yggdrasil
_yggdrasil_ is a system daemon that subscribes to topics on an MQTT broker and
routes any data received on the topics to an appropriate child "worker" process,
exchanging data with its worker processes through a D-Bus message broker.
## Installation
The easiest way to compile and install yggdrasil is using `meson`. Because
yggdrasil runs as a privileged system daemon, systemd unit files and D-Bus
policy files must be installed in specific directories in order for the service
to start.
Generally, it is recommended to follow your distribution's packaging guidelines
for compiling Go programs and installing projects using `meson`. What follows is
a generally acceptable set of steps to setup, compile and install yggdrasil
using `meson`.
```bash
# Set up the project according to distribution-specific directory locations
meson setup --prefix /usr/local --sysconfdir /etc --localstatedir /var builddir
# Compile
meson compile -C builddir
# Install
meson install -C builddir
```
`meson` includes an optional `--destdir` to its `install` subcommand to aid in
packaging.
## Configuration
Configuration of `yggd` can be done by specifying values in a configuration file
or via command line arguments. Command-line arguments take precedence over
configuration file values. The configuration file is [TOML](https://toml.io).
The default location searched for the system-wide configuration file is at
`/etc/yggdrasil/config.toml` (assuming SYSCONFDIR=/etc, as the example above).
The default location of the file may be overridden by passing the `--config`
command-line argument to `yggd`.
### (Optional) Authentication
In order to run `yggd` under certain conditions (such as connecting to a broker
that requires mTLS authentication), a valid certificate must first be created
and written to the filesystem.
#### Red Hat Subscription Manager
One way of generating a valid certificate is to first register the system with
an RHSM provider. The simplest way to do this is to create a free [Red Hat
Developer account](https://developers.redhat.com/register). On a Red Hat
Enterprise Linux system, run `subscription-manager register`, using the
developer account username and password.
```
sudo subscription-manager register --username [email protected] --password sw0rdf1sh
```
Once the system is successfully registered with RHSM, `yggd` can be launched,
using the certificate key pair:
```
sudo /usr/sbin/yggd --cert-file /etc/pki/consumer/cert.pem --key-file /etc/pki/consumer/key.pem
```
### Tags
A set of tags may be defined to associate additional key/value data with a host
when connecting to the broker. To do this, create the file
`/etc/yggdrasil/tags.toml` (assuming `SYSCONFDIR=/etc`, as the example above).
The contents of the file may be any number of TOML key/value pairs. However, a
limited number of TOML values are accepted as tag values (strings, integers,
booleans, floats, Local Date, Local Time, Offset Date-Time and Local Date-Time).
An example the tags.toml file can be found at at
/usr/share/doc/yggdrasil/tags.toml
## Running
yggdrasil uses D-Bus as an IPC framework to enable communication between workers
and the dispatcher, as well as exporting an API enabling other services to
interact with it. `yggd` follows the normal logic for determining which bus to
connect to. It will attempt to connect to the session bus if
`DBUS_SESSION_BUS_ADDRESS` is defined. Otherwise, it will attempt to connect to
the system bus. On the system bus, if the process is not running as root, the
installed D-Bus security policy will deny the process from claiming the
`com.redhat.Yggdrasil1` and `com.redhat.Yggdrasil1.Dispatcher1` names, and the
process will exit.
The systemd unit `yggrasil.service` starts `yggd`, using the logic described
above.
```
systemctl enable --now yggdrasil
```
Multiple instances of `yggd` can be run by using the templated systemd units.
Each instance requires a private D-Bus session. The socket and broker are
started with `[email protected]` and `[email protected]`, respectively.
A templated yggdrasil unit is available to automatically connect yggd to the
D-Bus broker started by `[email protected]`.
```
systemctl enable --now [email protected]
systemctl enable --now [email protected]
systemctl enable --now [email protected]
```
This will define and create an abstract UNIX domain socket named `yggd_bunnies`.
It will start a `dbus-broker` process running in the "user" scope, connecting to
the `yggd_bunnies` socket defined previously. Finally, `yggd` is launched with a
specific configuration file as the value of the `--config` argument:
`/etc/yggdrasil/yggdrasil-bunnies.toml`.
## Workers
A functional worker program must connect to the message bus as determined by the
`DBUS_SESSION_BUS_ADDRESS` environment variable, connecting to a session bus if
the value is defined, otherwise connecting to the system bus. Once connected to
the bus:
* The program must export an object on the bus that implements the
`com.redhat.Yggdrasil1.Worker1` interface.
* The object must be exported at a path under `/com/redhat/Yggdrasil1/Worker1`
that includes the directive name (i.e. `/com/redhat/Yggdrasil1/Worker1/echo`).
* The worker must claim a well-known name that begins with
`com.redhat.Yggdrasil1.Worker1` and includes its directive as the final segment
in reverse-domain-name notation (i.e. `com.redhat.Yggdrasil1.Worker1.echo`).
A worker can transmit data back to a destination by calling the
`com.redhat.Yggdrasil1.Dispatcher1.Transmit` method.
Package `worker` implements the above requirements implicitly, enabling workers
to be written without needing to worry about much of the D-Bus requirements
outlined above.
See `worker/echo` for a reference implementation of a worker program.