description: Learn how to configure the wasm Envoy extension, which is a builtin Consul extension that allows you to run WebAssembly plugins in Envoy proxies.
---
# WebAssembly extension configuration reference
This topic describes how to configure the `wasm` extension, which directs Consul to run WebAssembly (Wasm) plugins in Envoy proxies. Refer to [Run WebAssembly plug-ins in Envoy proxy](/consul/docs/connect/proxies/envoy-extensions/usage/wasm) for usage information.
## Configuration model
The following list outlines the field hierarchy, data types, and requirements for the `wasm` configuration. Place the configuration inside the `EnvoyExtension.Arguments` field in the proxy defaults or service defaults configuration entry. Refer the following documentation for additional information:
- [`EnvoyExtensions` in proxy defaults](/consul/docs/connect/config-entries/proxy-defaults#envoyextensions)
- [`EnvoyExtensions` in service defaults](/consul/docs/connect/config-entries/service-defaults#envoyextensions)
Click on a property name to view additional details, including default values.
Specifies the type of Wasm filter to apply. You can set either `tcp` or `http`. Set the `Protocol` to the protocol that the Wasm plugin implements when loaded by the filter. For Consul to apply the filter, the protocol must match the service's protocol.
- Data type is one of the following string values:
- `tcp`
- `http`
### `ListenerType`
Specifies the type of listener the extension applies to. The listener type is either `inbound` or `outbound`. If the listener type is set to `inbound`, Consul applies the extension so the Wasm plugin is run when other services in the mesh send messages to the service attached to the proxy. If the listener type is set to `outbound`, Consul applies the extension so the Wasm plugin is run when the attached proxy sends messages to other services in the mesh.
#### Values
- Default: None
- This field is required.
- Data type is one of the following string values:
- `inbound`
- `outbound`
### `ProxyType`
Specifies the type of Envoy proxy that the extension applies to. The only supported value is `connect-proxy`.
#### Values
- Default: `connect-proxy`
- This field is required.
- Data type: String
### `PluginConfig{}`
Map containing the following configuration parameters for your Wasm plugin:
Specifies a unique name for a filter in a VM. Envoy uses the name to identify specific filters if multiple filters are processed on a VM with the same `VmID` and `RootID`. The name also appears in logs for debugging purposes.
#### Values
- Default: None
- Data type: String
### `PluginConfig{}.RootID`
Specifies a unique ID for a set of filters in a VM that share a `RootContext` and `Contexts`, such as a Wasm `HttpFilter` and a Wasm `AccessLog`, if applicable. All filters with the same `RootID` and `VmID` share `Context`s.
#### Values
- Default: None
- Data type: String
### `PluginConfig{}.VmConfig{}`
Map containing the following configuration parameters for the VM that runs your Wasm plugin:
Specifies an ID that Envoy uses with a hash of the Wasm code to determine which VM runs the plugin. All plugins with the same `VmID` and `Code` use the same VM. If unspecified, all plugins with the same code run in the same VM. Sharing a VM between plugins may have security implications, but can reduce memory utilization and can make data sharing easier.
#### Values
- Default: None
- Data type: String
### `PluginConfig{}.VmConfig{}.Runtime`
Specifies the type of Wasm runtime.
#### Values
- Default: `v8`
- Data type is one of the following string values:
- `v8`
- `wastime`
- `wamr`
- `wavm`
### `PluginConfig{}.VmConfig{}.Code{}`
Map containing one of the following configuration parameters:
- [`Local`](#pluginconfig-vmconfig-code-local)
- [`Remote`](#pluginconfig-vmconfig-code-local)
You can configure either `Local` or `Remote`, but not both. The `Code` block instructs Consul how to find the Wasm plugin code for Envoy to execute.
#### Values
- Default: None
- This field is required.
- Data type is a map containing one of the following configurations:
- [`Local`](#pluginconfig-vmconfig-code-local)
- [`Remote`](#pluginconfig-vmconfig-code-local)
### `PluginConfig{}.VmConfig{}.Code{}.Local{}`
Instructs Envoy to load the plugin code from a local volume. Do not configure the `Local` parameter if the plugin code is on a remote server.
The `Local` field is a map that contains a `Filename` parameter. The `Filename` parameter takes a string value that specifies the path to the plugin on the local file system.
Local plug-ins are not supported in Kubernetes-orchestrated environments.
#### Values
- Default: None
- Data type is a map containing the `Filename` parameter. The `Filename` parameter takes a string value that specifies the path to the plugin on the local file system.
### `PluginConfig{}.VmConfig{}.Code{}.Remote{}`
Instructs Envoy to load the plugin code from a remote server. Do not configure the `Remote` parameter if the plugin code is on the local VM.
The `Remote` field is a map containing the following parameters:
Specifies the URI Envoy uses to fetch the plugin file from the upstream. This field is required for Envoy to retrieve plugin code from a remote location. You must specify the fully-qualified domain name (FDQN) of the remote URI, which includes the protocol, host, and path.
Defines a policy for retrying requests to the upstream service when fetching the plugin data. The `RetryPolicy` field is a map containing the following parameters:
Specifies parameters that control retry backoff strategy.
#### Values
- Default: None
- Data type: Map
The following table describes the fields you can specify in the `RetryBackOff` map:
| Parameter | Description | Data type | Default |
| --- | --- | --- | --- |
| `BaseInterval` | Specifies the base interval for determining the next backoff computation. Set a value greater than `0` and less than or equal to the `MaxInterval` value. | String | `1s` |
| `MaxInterval` | Specifies the maximum interval between retries. Set the value greater than or equal to the `BaseInterval` value. | String | `10s` |
Specifies the configuration Envoy encodes as bytes and passes to the plugin during VM startup. Refer to [`proxy_on_vm_start` in the Proxy Wasm ABI documentation](https://github.com/proxy-wasm/spec/tree/cefc2cbab70eaba2c187523dff0b38fce2f90771/abi-versions/vNEXT#proxy_on_vm_start) for additional information.
Specifies environment variables for Enovy to inject into this VM so that they are available through WASI's `environ_get` and `environ_get_sizes` system calls.
In most cases, WASI calls the functions implicitly in your language's standard library. As a result, you do not need to call them directly. You can also access environment variables as you would on native platforms.
| `HostEnvKeys` | Specifies a list of Envoy environment variable keys to expose to the VM. If a key exists in Envoy's environment variables, then the key-value pair is injected. Envoy ignores `HostEnvKeys` that do not exist in its environment variables. | List | None |
Specifies the configuration Consul encodes as bytes and passes to the plugin during plugin startup. Refer to [`proxy_on_configure` in the Envoy documentation](https://github.com/proxy-wasm/spec/tree/cefc2cbab70eaba2c187523dff0b38fce2f90771/abi-versions/vNEXT#proxy_on_configure) for additional information.
Specifies a configuration for restricting the proxy-Wasm capabilities that are available to the module.
The `CapabilityRestrictionConfiguration` field is a map that contains a `AllowedCapabilities` parameter. The `AllowedCapabilities` parameter takes a map of string values that correspond to Envoy capability names. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/wasm/v3/wasm.proto#extensions-wasm-v3-capabilityrestrictionconfig) for additional information.
!> **Security warning**: Consul ignores the value that each capability maps to. You can leave the `AllowedCapabilities` empty to allow all capabilities, but doing so gives the configured plugin full unrestricted access to the runtime API provided by the Wasm VM. You must set this to a non-empty map if you want to restrict access to specific capabilities provided by the Wasm runtime API.
#### Values
- Default: `""`
- Data type is a map containing the `AllowedCapabilities` parameter. The `AllowedCapabilities` parameter takes a map of string values that correspond to Envoy capability names. Refer to the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/wasm/v3/wasm.proto#extensions-wasm-v3-capabilityrestrictionconfig) for additional information.
## Examples
The following examples demonstrate patterns that you may be able to model your configurations on.
### Run a Wasm plugin from a local file
In the following example, Consul figures the Envoy proxy for the `db` service with an inbound TCP Wasm filter that uses the plugin code from the local `/consul/extensions/sqli.wasm` file.
```hcl
Kind = "service-defaults"
Name = "db"
Protocol = "tcp"
EnvoyExtensions = [
{
Name = "builtin/wasm"
Required = true
Arguments = {
Protocol = "tcp"
ListenerType = “inbound”
PluginConfig = {
VmConfig = {
Code = {
Local = {
Filename = "file:///consul/extensions/sqli.wasm"
}
}
}
Configuration = <<EOF
{
"key": "value"
}
EOF
}
}
}
]
```
### Run a Wasm plugin from a remote file
In the following example, Consul configures the Envoy proxy for all HTTP services with an HTTP Wasm filter. The filter uses the plugin code from a remote `https://extension-server/waf.wasm` file. The Envoy proxy for each service fetches the remote file and verify the SHA256 checksum. The proxy times if Consul cannot fetch the remote plugin after three seconds.
