Cockpit Modules

Layout of Module Files
Module Manifest

Cockpit is separated into various modules, each of which brings specific features and/or code.

Warning

It is not yet possible to implement arbitrary new modules.

In addition, any APIs or behavior not explicitly documented here is an internal API and can be changed at any time.

Layout of Module Files

A module consists of one or more files placed in a directory or its subdirectories. It must have a manifest.json file and follow certain naming conventions.

The name of a module is the name of the directory.

Cockpit uses the data directories from the XDG Base Directory Specification to locate modules. The $XDG_DATA_DIRS represents a colon separate list of system data directories, and $XDG_DATA_HOME is a user specific data directory. If the environment variables are not set, defaults are used, according to the spec.

A cockpit/ subdirectories in any of these data directories is the location where modules are loaded by Cockpit. If Cockpit finds a module with the same name, in multiple data directories, then the first one wins. According to the spec the first data directory is $XDG_DATA_HOME and then $XDG_DATA_DIRS in order.

This means that, by default the following directories are searched for cockpit modules, and in this order:

  • ~/.local/share/cockpit/

  • /usr/local/share/cockpit/

  • /usr/share/cockpit/

Modules placed in $XDG_DATA_HOME are not cached by Cockpit or the web browser. Other modules are cached agressively, and are accessed using a checksum of the files in the module and their names.

To further clarify things, here is an example module called "my-module" and its file layout:

/usr/share/cockpit/
    my-module/
        manifest.json
        file.html
        some.js

Place or symlink modules in your ~/.local/share/cockpit directory (or appropriate $XDG_DATA_HOME location) that you would like to modify and develop. System installed modules should not change while Cockpit is running.

Module Manifest

Each module has a manifest.json file. It is a JSON object. The following fields may be present in the manifest:

version

An informational version number for the module.