diff --git a/website/source/api/system/plugins-catalog.html.md b/website/source/api/system/plugins-catalog.html.md new file mode 100644 index 000000000..b95526194 --- /dev/null +++ b/website/source/api/system/plugins-catalog.html.md @@ -0,0 +1,155 @@ +--- +layout: "api" +page_title: "/sys/plugins/catalog - HTTP API" +sidebar_current: "docs-http-system-plugins-catalog" +description: |- + The `/sys/plugins/catalog` endpoint is used to manage plugins. +--- + +# `/sys/plugins/catalog` + +The `/sys/plugins/catalog` endpoint is used to list, register, update, and +remove plugins in Vault's catalog. Plugins must be registered before use, and +once registered backends can use the plugin by querying the catalog. + +## List Plugins + +This endpoint lists the plugins in the catalog. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/sys/plugins/catalog/` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST + https://vault.rocks/v1/sys/plugins/catalog +``` + +### Sample Response + +```javascript +{ + "data": { + "keys": [ + "cassandra-database-plugin", + "mssql-database-plugin", + "mysql-database-plugin", + "postgresql-database-plugin" + ] + } +} +``` + +## Register Plugin + +This endpoint registers a new plugin, or updates an existing one with the +supplied name. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/plugins/catalog/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name for this plugin. The name + is what is used to look up plugins in the catalog. This is part of the request + URL. + +- `sha_256` `(string: )` – This is the SHA256 sum of the plugin's + binary. Before a plugin is run it's SHA will be checked against this value, if + they do not match the plugin can not be run. + +- `command` `(string: )` – Specifies the command used to execute the + plugin. This is relative to the plugin directory. e.g. `"myplugin + --my_flag=1"` + +### Sample Payload + +```json +{ + "sha_256": "d130b9a0fbfddef9709d8ff92e5e6053ccd246b78632fc03b8548457026961e9", + "command": "mysql-database-plugin" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/plugins/catalog/example-plugin +``` + +## Read Plugin + +This endpoint returns the configuration data for the plugin with the given name. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/plugins/catalog/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the plugin to retrieve. + This is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://vault.rocks/v1/sys/plugins/catalog/example-plugin +``` + +### Sample Response + +```javascript +{ + "data": { + "plugin": { + "args": [], + "builtin": false, + "command": "/tmp/vault-plugins/mysql-database-plugin", + "name": "example-plugin", + "sha256": "0TC5oPv93vlwnY/5Ll5gU8zSRreGMvwDuFSEVwJpYek=" + } + } +} +``` +## Remove Plugin from Catalog + +This endpoint removes the plugin with the given name. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/sys/plugins/catalog/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the plugin to delete. + This is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/sys/plugins/catalog/example-plugin +``` diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index ea8e35624..c6e92d026 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -120,6 +120,9 @@ > /sys/mounts + > + /sys/plugins/catalog + > /sys/policy