echo

Shell-style echo, sleep, and subrequests in config

dynamic moduleBSD-2-Clausesource

Overview

echo-nginx-module brings shell-style directives such as echo, sleep, and time into the nginx config. It generates response bodies directly from configuration, with full nginx variable interpolation.

Operators use it to build health-check and debug endpoints, mock upstream responses, test rewrite and variable behavior, and stitch together subrequests without writing an application. All blocking-looking directives, such as echo_sleep, are implemented in a non-blocking way.

The module is written and maintained by Yichun Zhang (agentzh) of OpenResty Inc. and is one of the earliest OpenResty components.

Key directives

echoWrites text plus a trailing newline into the response body, interpolating nginx variables such as $remote_addr.

echo_sleepPauses the current request for a given number of seconds without blocking the worker process.

echo_location / echo_location_asyncIssues subrequests to other locations and includes their output, serially or in parallel.

echo_before_body / echo_after_bodyPrepends or appends text around the output of the location's regular content handler.

echo_read_request_bodyReads the client request body so it can be inspected through the $request_body variable.

Example

nginx.conf

load_module modules/ngx_http_echo_module.so; server { listen 80; location /healthz { echo "ok $remote_addr $time_iso8601"; } location /both { echo_location_async /a; echo_location_async /b; } }

Availability

Ships as a dynamic module in libnginx-mod-http-echo, installed automatically with nginx-extras. The package drops a load_module config into /etc/nginx/modules-enabled/, so it loads on start.