Skip to content

Latest commit

 

History

History
132 lines (91 loc) · 4.47 KB

plugins.md

File metadata and controls

132 lines (91 loc) · 4.47 KB
Raw

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

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

Datastore

Datastore plugins add support for additional datastore backends.

Tracer

(experimental)

Tracer plugins allow injecting an opentracing backend into go-ipfs.

Daemon

Daemon plugins are started when the go-ipfs daemon is started and are given an instance of the CoreAPI. This should make it possible to build an ipfs-based application without IPC and without forking go-ipfs.

Note: We eventually plan to make go-ipfs usable as a library. However, this plugin type is likely the best interim solution.

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.
jaeger Tracing An opentracing 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.