kubo/docs/plugins.md

Plugins

Since 0.4.11 go-ipfs has an experimental plugin system that allows augmenting the daemons functionality without recompiling.

When an IPFS node is started, it will load plugins from the $IPFS_PATH/plugins directory (by default ~/.ipfs/plugins).

Table of Contents

• Plugin Types
  • IPLD
  • Datastore
• Available Plugins
• Installing Plugins
  • External Plugin
    • In-tree
    • Out-of-tree
  • Preloaded Plugins
• Creating A Plugin

Plugin Types

IPLD

IPLD plugins add support for additional formats to ipfs dag and other IPLD related commands.

Datastore

Datastore plugins add support for additional datastore backends.

Available Plugins

Name	Type	Preloaded	Description
git	IPLD	x	An IPLD format for git objects.
badgerds	Datastore	x	A high performance but experimental datastore.
flatfs	Datastore	x	A stable filesystem-based datastore.
levelds	Datastore	x	A stable, flexible datastore backend.

• Preloaded plugins are built into the go-ipfs binary and do not need to be installed separately. At the moment, all in-tree plugins are preloaded.

Installing Plugins

Go-ipfs supports two types of plugins: External and Preloaded.

• External plugins must be installed in $IPFS_PATH/plugins/ (usually ~/.ipfs/plugins/).
• Preloaded plugins are built-into the go-ipfs when it's compiled.

External Plugin

The advantage of an external plugin is that it can be built, packaged, and installed independently of go-ipfs. Unfortunately, this method is only supported on Linux and MacOS at the moment. Users of other operating systems should follow the instructions for preloaded plugins.

In-tree

To build plugins included in plugin/plugins, run:

go-ipfs$ make build_plugins
go-ipfs$ ls plugin/plugins/*.so

To install, copy desired plugins to $IPFS_PATH/plugins. For example:

go-ipfs$ mkdir -p ~/.ipfs/plugins/
go-ipfs$ cp plugin/plugins/git.so ~/.ipfs/plugins/
go-ipfs$ chmod +x ~/.ipfs/plugins/git.so # ensure plugin is executable

Finally, restart daemon if it is running.

Out-of-tree

To build out-of-tree plugins, use the plugin's Makefile if provided. Otherwise, you can manually build the plugin by running:

myplugin$ go build -buildmode=plugin -i -o myplugin.so myplugin.go

Finally, as with in-tree plugins:

1. Install the plugin in $IPFS_PATH/plugins.
2. Mark the plugin as executable (chmod +x $IPFS_PATH/plugins/myplugin.so).
3. Restart your IPFS daemon (if running).

Preloaded Plugins

The advantages of preloaded plugins are:

1. They're bundled with the go-ipfs binary.
2. They work on all platforms.

To preload a go-ipfs plugin:

1. Add the plugin to the preload list: plugin/loader/preload_list
2. Build ipfs

go-ipfs$ make build

Creating A Plugin

To create your own out-of-tree plugin, use the example plugin as a starting point. When you're ready, submit a PR adding it to the list of available plugins.