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:

Diagram

@startuml

database "OCI-Bundle" as bundle
participant "D-Bus/Thunder\nAPI" as api
participant "Dobby\nDaemon" as dob
participant "Dobby Plugin\nLauncher" as helphost

participant "OCI Runtime\n(crun)" as crun

box "Container Namespace" #LightBlue
participant "containerized\nApp" as app
participant "Dobby Plugin\nLauncher" as helpcont

autonumber
autoactivate on

[o-> dob : system startup
...

== Start Container ==
api -> dob : Start container
note right : fork per-App threads

dob -> bundle : read bundle*
deactivate
dob -> helphost : <color:green>**postInstallation**
deactivate
dob -> helphost : <color:green>**preCreation**
deactivate

dob -> crun : create container
crun -> app ** : Create Container
crun -> helpcont **
crun -> helphost : <color:red>**createRuntime**
deactivate

crun -> helpcont : <color:red>**createContainer**
deactivate
note left : paths in host NS\nexecution in container NS
deactivate
dob -> crun : start container
crun -> helpcont : <color:red>**startContainer**
deactivate
crun -> app : start containerised app

crun -> helphost : <color:red>**postStart**
deactivate
deactivate crun
autoactivate off
app -> app : do stuff
...

app -> dob : SIGTERM
deactivate app

dob -> helphost : <color:green>**postHalt**
activate helphost
deactivate
dob -> crun : delete
activate crun
crun -> app !! : delete container
destroy helpcont

crun -> helphost : <color:red>**postStop**
activate helphost
deactivate helphost
crun --> dob
deactivate
deactivate

note left : Clean up per contianer\nDobby thread(s)

hide footbox

@enduml

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.