Update docs to match running builtins as plugins

website/source/api/system/auth.html.md

@@ -84,9 +84,6 @@ For example, enable the "foo" auth method will make it accessible at
   - `max_lease_ttl` `(string: "")` - The maximum lease duration, specified as a
      string duration like "5s" or "30m".
 
-  - `plugin_name` `(string: "")` - The name of the plugin in the plugin catalog
-     to use.
-
   - `audit_non_hmac_request_keys` `(array: [])` - Comma-separated list of keys
      that will not be HMAC'd by audit devices in the request data object.
 
@@ -99,13 +96,6 @@ For example, enable the "foo" auth method will make it accessible at
   - `passthrough_request_headers` `(array: [])` - Comma-separated list of headers
      to whitelist and pass from the request to the backend.
 
-    The plugin_name can be provided in the config map or as a top-level option,
-    with the former taking precedence.
-
-- `plugin_name` `(string: "")` – Specifies the name of the auth plugin to
-  use based from the name in the plugin catalog. Applies only to plugin
-  methods.
-
 Additionally, the following options are allowed in Vault open-source, but
 relevant functionality is only supported in Vault Enterprise:
 

website/source/api/system/mounts.html.md

@@ -38,7 +38,6 @@ $ curl \
       "default_lease_ttl": 0,
       "max_lease_ttl": 0,
       "force_no_cache": false,
-      "plugin_name": "",
       "seal_wrap": false
     }
   },
@@ -49,7 +48,6 @@ $ curl \
       "default_lease_ttl": 0,
       "max_lease_ttl": 0,
       "force_no_cache": false,
-      "plugin_name": "",
       "seal_wrap": false
     }
   }
@@ -89,9 +87,6 @@ This endpoint enables a new secrets engine at the given path.
 
   - `force_no_cache` `(bool: false)` - Disable caching.
 
-  - `plugin_name` `(string: "")` - The name of the plugin in the plugin catalog
-     to use.
-
   - `audit_non_hmac_request_keys` `(array: [])` - Comma-separated list of keys
      that will not be HMAC'd by audit devices in the request data object.
 
@@ -108,8 +103,7 @@ This endpoint enables a new secrets engine at the given path.
     These control the default and maximum lease time-to-live, force
     disabling backend caching, and option plugin name for plugin backends
     respectively. The first three options override the global defaults if
-    set on a specific mount. The plugin_name can be provided in the config
-    map or as a top-level option, with the former taking precedence.
+    set on a specific mount.
 
     When used with supported seals (`pkcs11`, `awskms`, etc.), `seal_wrap`
     causes key material for supporting mounts to be wrapped by the seal's
@@ -123,10 +117,6 @@ This endpoint enables a new secrets engine at the given path.
     - `version` `(string: "1")` - The version of the KV to mount. Set to "2" for mount
       KV v2.
 
-- `plugin_name` `(string: "")` – Specifies the name of the plugin to
-  use based from the name in the plugin catalog. Applies only to plugin
-  backends.
-
 Additionally, the following options are allowed in Vault open-source, but
 relevant functionality is only supported in Vault Enterprise:
 

website/source/api/system/plugins-catalog.html.md

@@ -9,17 +9,17 @@ description: |-
 
 # `/sys/plugins/catalog`
 
-The `/sys/plugins/catalog` endpoint is used to list, register, update, and
+The `/sys/plugins/catalog` endpoint is used to read, 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
+## Read Plugins
 
-This endpoint lists the plugins in the catalog.
+This endpoint lists the plugins in the catalog by type.
 
 | Method   | Path                         | Produces               |
 | :------- | :--------------------------- | :--------------------- |
-| `LIST`   | `/sys/plugins/catalog`      | `200 application/json`  |
+| `GET`    | `/sys/plugins/catalog`       | `200 application/json` |
 
 ### Sample Request
 
@@ -35,11 +35,25 @@ $ curl \
 ```javascript
 {
     "data": {
-        "keys": [
+        "auth": [
+            "aws",
+            "azure",
+            "custom-auth-plugin",
+            "gcp",
+            "ldap"
+        ],
+        "database": [
             "cassandra-database-plugin",
             "mssql-database-plugin",
             "mysql-database-plugin",
             "postgresql-database-plugin"
+        ],
+        "secret": [
+            "ad",
+            "aws",
+            "azure",
+            "gcp",
+            "transit"
         ]
     }
 }
@@ -53,15 +67,18 @@ 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)`     |
+| Method   | Path                               | Produces               |
+| :------- | :--------------------------------- | :--------------------- |
+| `PUT`    | `/sys/plugins/catalog/:type/:name` | `204 (empty body)`     |
 
 ### Parameters
 
 - `name` `(string: <required>)` – 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.
+
+- `type` `(string: <required>)` – Specifies the type of this plugin. May be 
+  "auth", "database", or "secret".
 
 - `sha256` `(string: <required>)` – 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
@@ -94,7 +111,7 @@ $ curl \
     --header "X-Vault-Token: ..." \
     --request PUT \
     --data @payload.json \
-    http://127.0.0.1:8200/v1/sys/plugins/catalog/example-plugin
+    http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin
 ```
 
 ## Read Plugin
@@ -104,22 +121,25 @@ 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` |
+| Method   | Path                               | Produces               |
+| :------- | :--------------------------------- | :--------------------- |
+| `GET`    | `/sys/plugins/catalog/:type/:name` | `200 application/json` |
 
 ### Parameters
 
 - `name` `(string: <required>)` – Specifies the name of the plugin to retrieve.
   This is part of the request URL.
+
+- `type` `(string: <required>)` – Specifies the type of this plugin. May be 
+  "auth", "database", or "secret".
 
 ### Sample Request
 
 ```
 $ curl \
     --header "X-Vault-Token: ..." \
     --request GET \
-    http://127.0.0.1:8200/v1/sys/plugins/catalog/example-plugin
+    http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin
 ```
 
 ### Sample Response
@@ -144,18 +164,21 @@ This endpoint removes the plugin with the given name.
 
 | Method   | Path                         | Produces               |
 | :------- | :--------------------------- | :--------------------- |
-| `DELETE` | `/sys/plugins/catalog/:name` | `204 (empty body)`     |
+| `DELETE` | `/sys/plugins/catalog/:type/:name` | `204 (empty body)`     |
 
 ### Parameters
 
 - `name` `(string: <required>)` – Specifies the name of the plugin to delete.
   This is part of the request URL.
+
+- `type` `(string: <required>)` – Specifies the type of this plugin. May be 
+  "auth", "database", or "secret".
 
 ### Sample Request
 
 ```
 $ curl \
     --header "X-Vault-Token: ..." \
     --request DELETE \
-    http://127.0.0.1:8200/v1/sys/plugins/catalog/example-plugin
+    http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin
 ```

website/source/docs/auth/azure.html.md

@@ -177,15 +177,15 @@ for your server at `path/to/plugins`:
 1. Enable the plugin in the catalog:
 
     ```text
-    $ vault write sys/plugins/catalog/azure-auth \
+    $ vault write sys/plugins/catalog/auth/azure-auth \
         command="vault-plugin-auth-azure" \
         sha256="..."
     ```
 
 1. Enable the azure auth method as a plugin:
 
     ```text
-    $ vault auth enable -path=azure -plugin-name=azure-auth plugin
+    $ vault auth enable -path=azure azure-auth
     ```
 
 ## API

website/source/docs/commands/auth/enable.html.md

@@ -54,6 +54,3 @@ flags](/docs/commands/index.html) included on all commands.
 - `-path` `(string: "")` - Place where the auth method will be accessible. This
   must be unique across all auth methods. This defaults to the "type" of the
   auth method. The auth method will be accessible at `/auth/<path>`.
-
-- `-plugin-name` `(string: "")` - Name of the auth method plugin. This plugin
-  name must already exist in the Vault server's plugin catalog.

website/source/docs/commands/plugin/deregister.html.md

@@ -11,14 +11,15 @@ description: |-
 # plugin deregister
 
 The `plugin deregister` command deregisters an existing plugin from Vault's
-plugin catalog. If the plugin does not exist, no error is returned.
+plugin catalog. If the plugin does not exist, no error is returned. The plugin's
+type of "auth", "database", or "secret" must be included.
 
 ## Examples
 
 Deregister a plugin:
 
 ```text
-$ vault plugin deregister my-custom-plugin
+$ vault plugin deregister auth my-custom-plugin
 Success! Deregistered plugin (if it was registered): my-custom-plugin
 ```
 

website/source/docs/commands/plugin/info.html.md

@@ -10,13 +10,14 @@ description: |-
 # plugin info
 
 The `plugin info` displays information about a plugin in the catalog.
+The plugin's type of "auth", "database", or "secret" must be included.
 
 ## Examples
 
 Display information about a plugin
 
 ```text
-$ vault plugin info my-custom-plugin
+$ vault plugin info auth my-custom-plugin
 
 Key        Value
 ---        -----

website/source/docs/commands/plugin/list.html.md

@@ -10,6 +10,7 @@ description: |-
 # plugin list
 
 The `plugin list` command lists all available plugins in the plugin catalog.
+It can be used alone or with a type such as "auth", "database", or "secret".
 
 ## Examples
 
@@ -22,6 +23,12 @@ Plugins
 -------
 my-custom-plugin
 # ...
+
+$ vault plugin list database
+Plugins
+-------
+cassandra-database-plugin
+# ...
 ```
 
 ## Usage

website/source/docs/commands/plugin/register.html.md

@@ -11,6 +11,7 @@ description: |-
 # plugin register
 
 The `plugin register` command registers a new plugin in Vault's plugin catalog.
+The plugin's type of "auth", "database", or "secret" must be included.
 
 ## Examples
 
@@ -19,7 +20,7 @@ Register a plugin:
 ```text
 $ vault plugin register \
     -sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
-    my-custom-plugin
+    auth my-custom-plugin
 Success! Registered plugin: my-custom-plugin
 ```
 
@@ -29,7 +30,7 @@ Register a plugin with custom args:
 $ vault plugin register \
     -sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
     -args=--with-glibc,--with-curl-bindings \
-    my-custom-plugin
+    auth my-custom-plugin
 ```
 
 ## Usage

website/source/docs/commands/secrets/enable.html.md

@@ -51,7 +51,7 @@ $ vault secrets enable -max-lease-ttl=30m database
 Enable a custom plugin (after it is registered in the plugin registry):
 
 ```text
-$ vault secrets enable -path=my-secrets -plugin-name=my-plugin plugin
+$ vault secrets enable -path=my-secrets my-plugin
 ```
 
 For more information on the specific configuration options and paths, please see
@@ -84,6 +84,3 @@ flags](/docs/commands/index.html) included on all commands.
 - `-path` `(string: "")` Place where the secrets engine will be accessible. This
   must be unique cross all secrets engines. This defaults to the "type" of the
   secrets engine.
-
-- `-plugin-name` `(string: "")` - Name of the secrets engine plugin. This plugin
-  name must already exist in Vault's plugin catalog.

website/source/docs/internals/plugins.html.md

@@ -8,15 +8,23 @@ description: |-
 ---
 
 # Plugin System
-Certain Vault backends utilize plugins to extend their functionality outside of
-what is available in the core Vault code. Often times these backends will
-provide both builtin plugins and a mechanism for executing external plugins.
-Builtin plugins are shipped with Vault, often for commonly used implementations,
-and require no additional operator intervention to run. Builtin plugins are
-just like any other backend code inside Vault. External plugins, on the other
-hand, are not shipped with the Vault binary and must be registered to Vault by
-a privileged Vault user. This section of the documentation will describe the
-architecture and security of external plugins.
+All Vault auth and secret backends are considered plugins. This simple concept
+allows both built-in and external plugins to be treated like Legos. Any plugin
+can exist at multiple different locations. Different versions of a plugin may
+be at each one, with each version differing from Vault's version.
+
+## Built-In Plugins
+Built-in plugins are shipped with Vault, often for commonly used implementations,
+and require no additional operator intervention to run. Built-in plugins are
+just like any other backend code inside Vault.
+
+To use a different or edited version of a built-in plugin, you would first edit
+the plugin's code or navigate to the Vault version holding the version of the
+plugin you desire. Then, you'd `$ cd` into the `cmd/:plugin-name` directory
+contained alongside that plugin's code. For instance, for AppRole, you would:
+`$ cd vault/builtin/credential/approle/cmd/approle`. Once in that directory,
+you would run `$ go build` to obtain a new binary for the AppRole plugin. Then
+you would add it to the plugin catalog as per normal, and enable it.
 
 # Plugin Architecture
 Vault's plugins are completely separate, standalone applications that Vault
@@ -25,6 +33,10 @@ share the same memory space as Vault and therefore can only access the
 interfaces and arguments given to it. This also means a crash in a plugin can not
 crash the entirety of Vault.
 
+It is possible to enable a custom plugin with a name that's identical to a 
+built-in plugin. In such a situation, Vault will always choose the custom plugin
+when enabling it. 
+
 ## Plugin Communication
 Vault creates a mutually authenticated TLS connection for communication with the
 plugin's RPC server. While invoking the plugin process, Vault passes a [wrapping
@@ -73,10 +85,10 @@ docs](/api/system/plugins-catalog.html).
 An example plugin submission looks like:
 
 ```
-$ vault write sys/plugins/catalog/myplugin-database-plugin \
+$ vault write sys/plugins/catalog/database/myplugin-database-plugin \
     sha256=<expected SHA256 Hex value of the plugin binary> \
     command="myplugin"
-Success! Data written to: sys/plugins/catalog/myplugin-database-plugin
+Success! Data written to: sys/plugins/catalog/database/myplugin-database-plugin
 ```
 
 ### Plugin Execution

website/source/docs/plugin/index.html.md

@@ -27,8 +27,8 @@ Before a plugin backend can be mounted, it needs to be registered via the
 the plugin is registered, it can be mounted by specifying the registered plugin name:
 
 ```text
-$ vault secrets enable -path=my-secrets -plugin-name=passthrough-plugin plugin
-Successfully mounted plugin 'passthrough-plugin' at 'my-secrets'!
+$ vault secrets enable -path=my-secrets passthrough-plugin
+Success! Enabled the passthrough-plugin secrets engine at: my-secrets/
 ```
 
 Listing secrets engines will display secrets engines that are mounted as