TokuMX Plugins

This wiki describes the architecture for plugins in TokuMX.

Interface

A plugin is a shared library that defines a symbol with C linkage getInterface, which is a function of zero arguments returning a pointer to a PluginInterface as defined in plugins.h.

We provide a helper class for defining a PluginInterface that just creates new commands, the CommandLoader.

Loading and unloading

Plugins are managed through the loadPlugin and unloadPlugin commands. These require authentication and admin privileges to run. The typical form is

> db.adminCommand({loadPlugin: 'plugin_name'})
{
        "loaded" : {
                "filename" : "libplugin_name.so",
                "fullpath" : "/path/to/tokumx/lib64/plugins/libexampleplugin.so",
                "name" : "plugin_name",
                "version" : "0.0.1-pre-",
                "commands" : [
                        "pluginName"
                ]
        },
        "ok" : 1
}
> db.adminCommand({unloadPlugin: 'plugin_name'})
{ ok : 1 }

There is an alternate form, mostly for development: {loadPlugin: 1, filename: '/path/to/libplugin_name.so'}.

Auto-loading

There are two designs for this: directory-based and collection-based.

Directory-based

Via a command-line parameter, set the plugin directory (or by discovering a directory near the installed binary), look at every lib*.so file in the plugin directory, and try to load it as a plugin.

Pros

• Plugin installation is as simple as it could be: drop the plugin in the installation directory and restart mongod.

Cons

• This requires that the directory, as well as the mongod config file are only writable by administrators. Ensuring they are not world-writable is probably good enough, but it adds unix filesystem security to the list of concerns.

• Might also need to worry about setuid.

Collection-based

Store loaded plugins in a collection ("local.system.plugins" seems right so it isn't replicated), and load all plugins in that collection on startup.

Pros

• This keeps most of the security within mongo itself, we can grant users the ability to load plugins by giving them access to the plugin collection.

• A simple query over "local.system.plugins" tells you everything you need to know, don't need a listPlugins command.

• We can store more information and be more careful that we're loading what we thought we were trying to load. We could even store a checksum of the file and verify it on autoload.

Cons

• This keeps most of the security within mongo itself. MongoDB 2.2 doesn't have the finest grained of security models. It may be harder to get everything as secure as we want it, without making other things unnecessarily difficult for the user, than if we just did it with filesystem access control. By being a little intrusive in NamespaceDetails we can get the local.system.plugins collection to need "admin db"-level authorization. This probably solves this con.

• Need to keep the collection and the actually loaded plugins in the running binary in sync. This synchronization between in-memory state and collection state has bitten us in the past, esp. with exceptions.

• Longer installation process, need to run a command, can't just "unpack and go" anymore.

• We still do need to worry about filesystem security, unless we verify the plugin's checksum on load.

• Need to make sure the local database is really secure now, users with access to it have a lot more power than they used to.

• If we verify checksums of plugins, it's hard to upgrade them.