Skip to content

wasm-wasmtime: Nginx with WebAssembly powered by wasmtime

Installation

You can install this module in any RHEL-based distribution, including, but not limited to:

  • RedHat Enterprise Linux 7, 8, 9 and 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 and Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm 
dnf -y install nginx-module-wasm-wasmtime

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm 
yum -y install nginx-module-wasm-wasmtime

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_wasmx_module.so;

This document describes nginx-module-wasm-wasmtime v0.5.0 released on Feb 15 2025.

WasmX logo

WasmX/ngx_wasm_module

Nginx + WebAssembly

This module enables the embedding of [WebAssembly] runtimes inside of Nginx and aims at offering several host SDK abstractions for the purpose of extending and/or introspecting the Nginx web-server/proxy runtime.

Currently, the module implements a Proxy-Wasm host ABI, which allows the use of client SDKs written in multiple languages, such as Rust and Go. Proxy-Wasm ("WebAssembly for Proxies") is an emerging standard for Wasm filters, adopted by API Gateways such as Kong and Envoy.

What is WasmX?

WasmX aims at extending Nginx for the modern Web infrastructure. This includes supporting WebAssembly runtimes & SDKs (by way of ngx_wasm_module), and generally increasing the breadth of features relied upon by the API Gateway use-case (i.e. reverse-proxying). See CONTRIBUTING.md for additional background and roadmap information.

Synopsis

## nginx.conf
events {}

## nginx master process gets a default 'main' VM
## a new top-level configuration block receives all configuration for this main VM
wasm {
    #      [name]    [path.{wasm,wat}]
    module my_filter /path/to/filter.wasm;
    module my_module /path/to/module.wasm;
}

## each nginx worker process is able to instantiate wasm modules in its subsystems
http {
    server {
        listen 9000;

        location / {
            # execute a proxy-wasm filter when proxying
            #           [module]
            proxy_wasm  my_filter;

            # execute more WebAssembly during the access phase
            #           [phase] [module]  [function]
            wasm_call   access  my_module check_something;

            proxy_pass  ...;
        }
    }

    # other directives
    wasm_socket_connect_timeout 60s;
    wasm_socket_send_timeout    60s;
    wasm_socket_read_timeout    60s;

    wasm_socket_buffer_size     8k;
    wasm_socket_large_buffers   32 16k;
}

Examples

Several "showcase filters" are provided as examples by authors of this module:

More examples are available for each Proxy-Wasm SDK:

Note that all of the above examples may not yet be compatible with ngx_wasm_module.

Last but not least, the WebAssembly Hub contains many other Proxy-Wasm filters, some of which may not yet be compatible with ngx_wasm_module.

Documentation

Usage

See the user documentation for resources on this module's usage.

Development

See the developer documentation for developer resources on building this module from source and other general development processes.

See a term you are unfamiliar with? Consult the code lexicon.

For a primer on the code's layout and architecture, see the code layout section.

Proxy-Wasm SDK

The Proxy-Wasm SDK is the initial focus of WasmX/ngx_wasm_module development and is still a work in progress. You can browse PROXY_WASM.md for a guide on Proxy-Wasm support in ngx_wasm_module.

For a reliable resource in an evolving ABI specification, you may also wish to consult the SDK source of the language of your choice in the Proxy-Wasm SDKs list.

WebAssembly

WebAssembly Runtimes

GitHub

You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-wasm-wasmtime.