@cryptotaxi247 / kubo
Code Commits Issues Pulls Sessions CI/CD
master
master
md 203 lines 6.75 KB
Rendered Raw
1 # Plugins
2
3 Since 0.4.11 Kubo has an experimental plugin system that allows augmenting
4 the daemons functionality without recompiling.
5
6 When an IPFS node is started, it will load plugins from the `$IPFS_PATH/plugins`
7 directory (by default `~/.ipfs/plugins`).
8
9 **Table of Contents**
10
11 - [Plugin Types](#plugin-types)
12 - [IPLD](#ipld)
13 - [Datastore](#datastore)
14 - [Available Plugins](#available-plugins)
15 - [Installing Plugins](#installing-plugins)
16 - [External Plugin](#external-plugin)
17 - [In-tree](#in-tree)
18 - [Out-of-tree](#out-of-tree)
19 - [Preloaded Plugins](#preloaded-plugins)
20 - [Creating A Plugin](#creating-a-plugin)
21
22 ## Plugin Types
23
24 Plugins can implement one or more plugin types, defined in the
25 [plugin](https://godoc.org/github.com/ipfs/kubo/plugin) package.
26
27 ### IPLD
28
29 IPLD plugins add support for additional formats to `ipfs dag` and other IPLD
30 related commands.
31
32 ### Datastore
33
34 Datastore plugins add support for additional datastore backends.
35
36 ### Tracer
37
38 (experimental)
39
40 Tracer plugins allow injecting an opentracing backend into Kubo.
41
42 ### Daemon
43
44 Daemon plugins are started when the Kubo daemon is started and are given an
45 instance of the CoreAPI. This should make it possible to build an ipfs-based
46 application without IPC and without forking Kubo.
47
48 Note: We eventually plan to make Kubo usable as a library. However, this
49 plugin type is likely the best interim solution.
50
51 ### fx (experimental)
52
53 Fx plugins let you customize the [fx](https://pkg.go.dev/go.uber.org/fx) dependency graph and configuration,
54 by customizing the`fx.Option`s that are passed to `fx` when the Kubo node is initialized.
55
56 For example, you can override an interface such as [exchange.Interface](https://github.com/ipfs/go-ipfs-exchange-interface)
57 or [pin.Pinner](https://github.com/ipfs/go-ipfs-pinner) with a custom implementation by appending an option like
58 `fx.Decorate(func() exchange.Interface { return customExchange })`.
59
60 Fx supports some advanced customization. Simple interface replacements like above are unlikely to break in the future,
61 but the more invasive your changes, the more likely they are to break between releases. Kubo cannot guarantee backwards
62 compatibility for `fx` customizations.
63
64 Fx options are applied across every execution of the `ipfs` binary, including:
65
66 - Repo initialization
67 - Daemon
68 - Applying migrations
69 - etc.
70
71 So if you plug in a blockservice that disallows non-allowlisted CIDs, then this may break migrations
72 that fetch migration code over the IPFS network.
73
74 ### Internal
75
76 (never stable)
77
78 Internal plugins are like daemon plugins _except_ that they can access, replace,
79 and modify all internal state. Use this plugin type to extend Kubo in
80 arbitrary ways. However, be aware that your plugin will likely break every time
81 Kubo updated.
82
83 ## Configuration
84
85 Plugins can be configured in the `Plugins` section of the config file. Here,
86 plugins can be:
87
88 1. Passed an arbitrary config object via the `Config` field.
89 2. Disabled via the `Disabled` field.
90
91 Example:
92
93 ```js
94 {
95 // ...
96 "Plugins": {
97 "Plugins": {
98 // plugin named "plugin-foo"
99 "plugin-foo": {
100 "Config": { /* arbitrary json */ }
101 },
102 // plugin named "plugin-bar"
103 "plugin-bar": {
104 "Disabled": true // "plugin-bar" will not be loaded
105 }
106 }
107 }
108 }
109 ```
110
111 ## Available Plugins
112
113 | Name | Type | Preloaded | Description |
114 |---------------------------------------------------------------------------------|-----------|-----------|------------------------------------------------|
115 | [git](https://github.com/ipfs/kubo/tree/master/plugin/plugins/git) | IPLD | x | An IPLD format for git objects. |
116 | [badgerds](https://github.com/ipfs/kubo/tree/master/plugin/plugins/badgerds) | Datastore | x | A high performance but experimental datastore. |
117 | [flatfs](https://github.com/ipfs/kubo/tree/master/plugin/plugins/flatfs) | Datastore | x | A stable filesystem-based datastore. |
118 | [levelds](https://github.com/ipfs/kubo/tree/master/plugin/plugins/levelds) | Datastore | x | A stable, flexible datastore backend. |
119 | [jaeger](https://github.com/ipfs/go-jaeger-plugin) | Tracing | | An opentracing backend. |
120 | [telemetry](https://github.com/ipfs/kubo/tree/master/plugin/plugins/telemetry) | Telemetry | x | Collects anonymized usage data for Kubo development. |
121
122 * **Preloaded** plugins are built into the Kubo binary and do not need to be
123 installed separately. At the moment, all in-tree plugins are preloaded.
124
125 ## Installing Plugins
126
127 Kubo supports two types of plugins: External and Preloaded.
128
129 * External plugins must be installed in `$IPFS_PATH/plugins/` (usually
130 `~/.ipfs/plugins/`).
131 * Preloaded plugins are built-into the Kubo when it's compiled.
132
133 ### External Plugin
134
135 The advantage of an external plugin is that it can be built, packaged, and
136 installed independently of Kubo. Unfortunately, this method is only supported
137 on Linux and MacOS at the moment. Users of other operating systems should follow
138 the instructions for preloaded plugins.
139
140 #### In-tree
141
142 To build plugins included in
143 [plugin/plugins](https://github.com/ipfs/kubo/tree/master/plugin/plugins),
144 run:
145
146 ```bash
147 kubo$ make build_plugins
148 kubo$ ls plugin/plugins/*.so
149 ```
150
151 To install, copy desired plugins to `$IPFS_PATH/plugins`. For example:
152
153 ```bash
154 kubo$ mkdir -p ~/.ipfs/plugins/
155 kubo$ cp plugin/plugins/git.so ~/.ipfs/plugins/
156 kubo$ chmod +x ~/.ipfs/plugins/git.so # ensure plugin is executable
157 ```
158
159 Finally, restart daemon if it is running.
160
161 #### Out-of-tree
162
163 To build out-of-tree plugins, use the plugin's Makefile if provided. Otherwise,
164 you can manually build the plugin by running:
165
166 ```bash
167 myplugin$ go build -buildmode=plugin -o myplugin.so myplugin.go
168 ```
169
170 Finally, as with in-tree plugins:
171
172 1. Install the plugin in `$IPFS_PATH/plugins`.
173 2. Mark the plugin as executable (`chmod +x $IPFS_PATH/plugins/myplugin.so`).
174 3. Restart your IPFS daemon (if running).
175
176 ### Preloaded Plugins
177
178 The advantages of preloaded plugins are:
179
180 1. They're bundled with the Kubo binary.
181 2. They work on all platforms.
182
183 To preload a Kubo plugin:
184
185 1. Add the plugin to the preload list: `plugin/loader/preload_list`
186 2. Build ipfs
187 ```bash
188 kubo$ make build
189 ```
190
191 You can also preload an in-tree but disabled-by-default plugin by adding it to
192 the IPFS_PLUGINS variable. For example, to enable plugins foo, bar, and baz:
193
194 ```bash
195 kubo$ make build IPFS_PLUGINS="foo bar baz"
196 ```
197
198 ## Creating A Plugin
199
200 To create your own out-of-tree plugin, use the [example
201 plugin](https://github.com/ipfs/go-ipfs-example-plugin/) as a starting point.
202 When you're ready, submit a PR adding it to the list of [available
203 plugins](#available-plugins).