To support additional functionality, Dobby allows developers to create C++ plugins that can execute code at various stages of a containers lifecycle such as before creation, during startup or at container shutdown. This could be used to map devices, configure networking/iptables or setup displays. Dobby uses a mixture of custom hook-points and OCI hooks (https://github.com/opencontainers/runtime-spec/blob/master/config.md#posix-platform-hooks) to support this.

Plugins are installed in /usr/lib/plugins/dobby by default, although this can be changed at compile-time as necessary.

By default, Dobby builds the following plugins:

  • Networking - provide advanced networking support to containers, including NAT networking and port forwarding
  • Logging - captures container stdout/err and sends it to a file or journald
  • Storage - allow persistent loopback mounts inside containers
  • IPC - allow dbus access inside containers

To enable/disable plugins, add the -DPLUGIN_XYZ=ON/OFF compile flag when building Dobby.

Hook Points

The following table shows the various hook points that a developer can use in their plugins:

Proposed Container Hooks Required for Plugin Support
Diagram Ref #NameExecution NamespacePath Resolution NamespaceWhenResponsibility
4postInstallationhosthost

After the OCI bundle has been downloaded to the client STB, before the runtime’s create operation is called. Only run once per container - if the container is stopped and restarted this hook does not run again

Can modify the container config file

Dobby
5preCreationhosthost

After postInstallation, but before the create operation is called. Is run every time the container is launched.

Can modify the container config file

Dobby
9createRuntimehosthost

During the create operation, after the runtime environment has been created and before the pivot root or any equivalent operation.

This hook, and subsequent hooks, can not modify the container config

OCI Runtime (crun)
10createContainercontainerhostDuring the create operation, after the runtime environment has been created and before the pivot root or any equivalent operation.OCI Runtime (crun)
12startContainercontainercontainerAfter the start operation is called but before the user-specified program command is executed.OCI Runtime (crun)
14postStarthosthostAfter the user-specified process is executed but before the start operation returns.OCI Runtime (crun)
16postHalthosthostWhen a SIGTERM signal is received from the container. Before the delete operation is calledDobby
20postStophosthostAfter the container is deleted but before the delete operation returns.OCI Runtime (crun)

Diagram

Container NamespaceOCI-BundleD-Bus/ThunderAPIDobbyDaemonDobby PluginLauncherOCI Runtime(crun)1system startupStart Container2Start containerfork per-App threads3read bundle*4postInstallation5preCreation6create container7Create ContainercontainerizedApp8 Dobby PluginLauncher9createRuntime10createContainerpaths in host NSexecution in container NS11start container12startContainer13start containerised app14postStart15do stuff16SIGTERM17postHalt18delete19delete container20postStop21 Clean up per contianerDobby thread(s)

DobbyPluginLauncher

To allow Dobby plugins to be run by the OCI hooks, the DobbyPluginLauncher executable is used. This loads the plugins from the plugin directory and runs the specified hook point. This is all configured and run automatically and should not need to be modified.

Writing Plugins

Dobby plugins are written in C++ and authored against the IDobbyRDKPlugin interface: https://github.com/rdkcentral/Dobby/blob/master/pluginLauncher/lib/include/IDobbyRdkPlugin.h. A plugin should declare which hook points it uses by setting the relevant flags, and then override the relevant methods in the interface for those hook points. It only needs to implement methods that it requires - any methods not implemented are skipped.

Every plugin has full read access to the containers config, and the postInstallation and preCreation hooks may also make modifications to the container configuration. After those two hooks, the container config is persisted to disk and can no longer be modified.

A sample plugin - TestRDKPlugin - is available which executes a print statement at each hook point and can be used as an example for further development. All plugins also include a README file which documents their usage.

  • No labels

DISCLAIMER: Please note that the use of the RDK Wiki is subject to its Privacy Policy & Terms of Use. In addition, this Wiki may be accessed by all RDK licensees and their contractors.