// NGINX Modules Synopsis

NGINX Modules Synopsis

Our packages: NGINX Extended  ·  ANGIE Extended

97 dynamic modules.

Index

http-access-control #

A custom Nginx module for advanced access control based on variables.

Source: upstream source

Directives

access #

syntax: access [allow|deny] variable;  ·  default: -  ·  context: http, server, location

The access directive defines an access control rule based on a variable. The variable is evaluated at runtime, and if it is non-empty and not zero, the rule is considered matched. The allow parameter allows access if the condition is met. The allowed request will no longer match the remaining access control rules.

access_deny_status #

syntax: access_deny_status code;  ·  default: access_deny_status 403;  ·  context: http, server, location

Sets the HTTP status code to return in response when access is denied by a deny rule.

access_inherit #

syntax: access_inherit 1 arg (enum);  ·  context: http, server, location

Pick one of an enumerated set of values.

Example

server {
    listen 80;
    server_name example.com;

    # Allow access if $var2 is non-empty and not zero. The allowed request will no longer match the remaining access control rules.
    access allow $var1;

    # Deny access if $var1 is non-empty and not zero
    access deny $var2;

    location / {
        # Your other configurations
    }

    location /restricted {
        # Override deny status code
        access_deny_status 404;

        # Deny access if $var3 is non-empty and not zero
        access deny $var3;
    }
}

↑ back to index

http-access-plus #

Nginx-Access-Plus is a Nginx module allows limiting access to certain http request methods and client addresses.

Source: upstream source

Directives

allow_method #

syntax: allow_method 2 args;  ·  context: http, server, location, limit_except

deny_method #

syntax: deny_method 2 args;  ·  context: http, server, location, limit_except

Example

location / {
    allow_method all get|head;
    allow_method 192.168.1.0/24 post|delete;
    deny_method  all all;
}

↑ back to index

http-array-var #

array-var-nginx-module – Add support for array-typed variables to nginx config files

Source: upstream source

Directives

array_join #

syntax: array_join 2 args;  ·  context: http, server, location, server-if, location-if

Table of Contents ================= Name Status Synopsis Description Directives array_split array_join array_map array_map_op Installation Building as a dynamic module Compatibility Source Repository Getting involved Author Copyright & License * See Also Status ====== This module is production ready.

Example

location /foo {
    array_split ',' $arg_files to=$array;

    # use the set_quote_sql_str directive in the ngx_set_misc
    # module to map to each element in the array $array:
    array_map_op set_quote_sql_str $array;

    array_map "name = $array_it" $array;

    array_join ' or ' $array to=$sql_condition;

    # well, we could feed it to ngx_drizzle to talk to MySQL, for example ;)
    echo "select * from files where $sql_condition";
}

↑ back to index

http-auth-hmac #

HMAC-signed URL authentication for nginx — verify shared-secret signatures on request paths to grant time-limited access to private resources.

Source: upstream source

Directives

auth_hmac #

syntax: auth_hmac 1 arg (on/off flag);  ·  context: http, server, location

Example in Perl below. #### Variable $data contains secure token, timestamp in ISO 8601 format, and expiration period in seconds A similar function in PHP Using Unix timestamp in Node.js Bash version Embedded Variables ================== * $auth_hmac – If the hash is correct and the link has not expired then $secure_link_hash is "1".

auth_hmac_algorithm #

syntax: auth_hmac_algorithm 1 arg (string);  ·  context: http, server, location

Stores a single string value.

auth_hmac_check_time #

syntax: auth_hmac_check_time 1+ args;  ·  context: http, server, location

auth_hmac_check_token #

syntax: auth_hmac_check_token 1 arg;  ·  context: http, server, location

auth_hmac_message #

syntax: auth_hmac_message 1 arg;  ·  context: http, server, location

auth_hmac_secret #

syntax: auth_hmac_secret 1 arg;  ·  context: http, server, location

Example

location ^~ /files/ {
    # Enables the feature, if disabled, $auth_hmac will always be empty
    auth_hmac on;

    # Set the time value used for checking.
    # You can set the expiration time range, the format of the time value, and the time zone of the time value
    auth_hmac_check_time $arg_ts range_end=$arg_e format=%s;

    # Set the token value used for checking
    # Available formats are hex (default), base64, base64url and bin
    auth_hmac_check_token $arg_st format=hex;

    # Secret key
    auth_hmac_secret "my_secret_key";

    # Message to be verified
    auth_hmac_message "$uri|$arg_ts|$arg_e";

    # Cryptographic hash function to be used
    auth_hmac_algorithm sha256;

    # In production environment, we should not reveal to potential attacker
    # why hmac authentication has failed
    # - If the hash is incorrect then $auth_hmac is a NULL string.
    # - If the hash is correct and the link has not expired then $auth_hmac is "1".
    if ($auth_hmac != "1") {
        return 403;
    }

    rewrite ^/files/(.*)$ /files/$1 break;
}

↑ back to index

http-auth-internal #

This Nginx module provides internal request authentication by validating a custom HTTP header (default is X-Fingerprint) against a set of predefined secrets. The module is highly configurable and allows flexible integration into existing systems for enhanced security.

Source: upstream source

Directives

auth_internal #

syntax: auth_internal on | off;  ·  default: auth_internal off;  ·  context: http, server

Enable or disable the internal authentication.

auth_internal_empty_deny #

syntax: auth_internal_empty_deny on | off;  ·  default: auth_internal_empty_deny off;  ·  context: http, server

Determines whether to deny requests missing the header. If set to on, missing headers result in a deny status.

auth_internal_failure_deny #

syntax: auth_internal_failure_deny on | off;  ·  default: auth_internal_failure_deny on;  ·  context: http, server

Determines whether to deny requests when fingerprint validation fails. If set to `on, invalid fingerprints result in a deny status.

auth_internal_header #

syntax: auth_internal_header 1 arg (string);  ·  context: http, server

Stores a single string value.

auth_internal_proxy_secret #

syntax: auth_internal_proxy_secrets secret;  ·  default: -;  ·  context: http, server

Specifies the secret used to gerenate a new value of fingerprint validation header. The fingerprint value will be appended to the variable $auth_internal_proxy_fingerprint, which can be used to append to upstream request headers to enable auth by upstream server. For example, with the following configuration

auth_internal_request_secrets #

syntax: auth_internal_request_secrets secret1 [secret2 ...];  ·  default: -;  ·  context: http, server

Specifies one or more secrets used to validate the header. A maximum of three secrets are allowed.

auth_internal_timeout #

syntax: auth_internal_timeout 1 arg (duration in seconds);  ·  context: http, server

Duration in seconds; accepts s / m / h / d suffixes.

Example

http {
    auth_internal on;
    auth_internal_request_secret secret1 secret2;
    auth_internal_timeout 600;
    auth_internal_header X-Fingerprint;
    auth_internal_empty_deny off;
    auth_internal_failure_deny on;
    auth_internal_proxy_secret secret1;

    server {
        listen 80;

        location / {
            proxy_set_header X-Fingerprint $auth_internal_proxy_fingerprint;
            proxy_pass http://upstream_server;
        }
    }
}

↑ back to index

http-auth-jwt #

JWT (JSON Web Token) authentication module — validates Bearer / cookie tokens against a key, redirects unauthenticated clients to a login URL, and exposes claims as nginx variables.

Source: upstream source

Directives

auth_jwt_algorithm #

syntax: auth_jwt_algorithm 1 arg (string);  ·  context: http, server, location

The algorithm to use. One of: HS256, HS384, HS512, RS256, RS384, RS512

auth_jwt_enabled #

syntax: auth_jwt_enabled 1 arg;  ·  context: http, server, location

Set to "on" to enable JWT checking.

auth_jwt_extract_request_claims #

syntax: auth_jwt_extract_request_claims 1+ args;  ·  context: http, server, location

Set to a space-delimited list of claims to extract from the JWT and set as request headers. These will be accessible via e.g: $http_jwt_sub

auth_jwt_extract_response_claims #

syntax: auth_jwt_extract_response_claims 1+ args;  ·  context: http, server, location

Set to a space-delimited list of claims to extract from the JWT and set as response headers. These will be accessible via e.g: $sent_http_jwt_sub

auth_jwt_extract_var_claims #

syntax: auth_jwt_extract_var_claims 1+ args;  ·  context: http, server, location

Set to a space-delimited list of claims to extract from the JWT and make available as NGINX variables. These will be accessible via e.g: $jwt_claim_sub

auth_jwt_key #

syntax: auth_jwt_key 1 arg (string);  ·  context: http, server, location

The key to use to decode/verify the JWT, *in binhex format* — see below.

auth_jwt_keyfile_path #

syntax: auth_jwt_keyfile_path 1 arg (string);  ·  context: http, server, location

Set to the path from which the key should be read when auth_jwt_use_keyfile is enabled.

auth_jwt_location #

syntax: auth_jwt_location 1 arg (string);  ·  context: http, server, location

Indicates where the JWT is located in the request — see below.

auth_jwt_loginurl #

syntax: auth_jwt_loginurl 1 arg (string);  ·  context: http, server, location

The URL to redirect to if auth_jwt_redirect is enabled and authentication fails.

auth_jwt_redirect #

syntax: auth_jwt_redirect on | off (on/off flag);  ·  context: http, server, location

Set to "on" to redirect to auth_jwt_loginurl if authentication fails.

auth_jwt_use_keyfile #

syntax: auth_jwt_use_keyfile on | off (on/off flag);  ·  context: http, server, location

Set to "on" to read the key from a file rather than from the auth_jwt_key directive.

auth_jwt_validate_sub #

syntax: auth_jwt_validate_sub on | off (on/off flag);  ·  context: http, server, location

Set to "on" to validate the sub claim (e.g. user id) in the JWT.

Example

error_log /var/log/nginx/debug.log debug;
access_log /var/log/nginx/access.log;

log_format  extract_test  'Log extract test sub: $jwt_claim_sub';

server {
    listen %{PORT};
    listen %{SSL_PORT} ssl;
    server_name localhost;

    ssl_certificate /etc/nginx/test.crt;
    ssl_certificate_key /etc/nginx/test.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    
    auth_jwt_key "00112233445566778899AABBCCDDEEFF00112233445566778899AABBCCDDEEFF";
    auth_jwt_loginurl "https://example.com/login";
    auth_jwt_enabled off;

    location /ping {
        return 200 "pong";
    }

    location / {
        alias /usr/share/nginx/html/;
        try_files index.html =404;
    }

    location /secure/cookie/default {
        auth_jwt_enabled on;
        auth_jwt_redirect on;
        auth_jwt_location COOKIE=jwt;
        
        alias /usr/share/nginx/html/;
        try_files index.html =404;
    }

    location /secure/cookie/default/validate-sub {
        auth_jwt_enabled on;
        auth_jwt_redirect on;
        auth_jwt_validate_sub on;
        auth_jwt_location COOKIE=jwt;
        
        alias /usr/share/nginx/html/;
        try_files index.html =404;
    }
        
    location /secure/cookie/default/no-redirect {
        auth_jwt_enabled on;
        auth_jwt_redirect off;
        auth_jwt_location COOKIE=jwt;

        alias /usr/share/nginx/html/;
        try_files index.html =404;
    }

    location /secure/cookie/hs256 {
        auth_jwt_enabled on;
        auth_jwt_redirect on;
        auth_jwt_location COOKIE=jwt;
        auth_jwt_algorithm HS256;

        alias /usr/share/nginx/html/;
        try_files index.html =404;
    }

    location /secure/cookie/hs384 {
        auth_jwt_enabled on;
        auth_jwt_redirect on;
        auth_jwt_location COOKIE=jwt;
        auth_jwt_algorithm HS384;

        alias /usr/share/nginx/html/;
        try_files index.html =404;
    }

    location /secure/cookie/hs512 {
        auth_jwt_enabled on;
        auth_jwt_redirect on;
        auth_jwt_location COOKIE=jwt;
        auth_jwt_algorithm HS512;

        alias /usr/share/nginx/html/;
        try_files index.html =404;
    }

    location /secure/cookie/es256 {
        auth_jwt_enabled on;
        auth_jwt_redirect on;
        auth_jwt_location COOKIE=jwt;
        auth_jwt_algorithm ES256;
        auth_jwt_key "-----BEGIN PUBLIC KEY-----
…

↑ back to index

http-auth-ldap #

LDAP module for Nginx which supports authentication against multiple LDAP servers.

Source: upstream source

Directives

auth_ldap #

syntax: auth_ldap 1 arg;  ·  context: http, server, location, limit_except

auth_ldap_cache_enabled #

syntax: auth_ldap_cache_enabled 1 arg (on/off flag);  ·  context: http

Boolean directive — set to "on" or "off".

auth_ldap_cache_expiration_time #

syntax: auth_ldap_cache_expiration_time 1 arg (duration in ms);  ·  context: http

Duration in milliseconds; accepts ms / s / m suffixes.

auth_ldap_cache_size #

syntax: auth_ldap_cache_size 1 arg (size (k/m/g));  ·  context: http

Size in bytes; accepts k / m / g suffixes.

auth_ldap_servers #

syntax: auth_ldap_servers any args;  ·  context: http, server, location, limit_except

auth_ldap_servers_size #

syntax: auth_ldap_servers_size 1 arg (integer);  ·  context: http

Integer value.

ldap_server #

syntax: ldap_server 1 arg;  ·  context: http

Example

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    # define ldap server
    ldap_server ad_1 {
      # user search base.
      url "ldap://<YOUR LDAP SERVER>:3268/OU=Offices,DC=company,DC=com?sAMAccountName?sub?(objectClass=person)";
      # bind as
      binddn "CN=Operator,OU=Service Accounts,DC=company,DC=com";
      # bind pw
      binddn_passwd <PUT Operator's PASSWORD HERE>;
      # group attribute name which contains member object
      group_attribute member;
      # search for full DN in member object
      group_attribute_is_dn on;
      # matching algorithm (any / all)
      satisfy any;
      # list of allowed groups
      require group "CN=Admins,OU=My Security Groups,DC=company,DC=com";
      require group "CN=New York Users,OU=My Security Groups,DC=company,DC=com";
      # list of allowed users
      # require 'valid_user' cannot be used together with 'user' as valid user is a superset
      # require valid_user;
      require user "CN=Batman,OU=Users,OU=New York Office,OU=Offices,DC=company,DC=com";
      require user "CN=Robocop,OU=Users,OU=New York Office,OU=Offices,DC=company,DC=com";
    }

}

server {
  listen       8081;
  server_name  localhost;

  location / {
    # adding ldap authentication
    auth_ldap "Closed content";
    auth_ldap_servers ad_1;

    root html;
    index index.html index.htm;
  }

  error_page   500 502 503 504  /50x.html;

  location = /50x.html {
    root html;
  }
}

↑ back to index

http-auth-pam #

Nginx module to use PAM for simple http authentication

Source: upstream source

Directives

auth_pam #

syntax: auth_pam 1 arg (string);  ·  context: http, server, location, limit_except

If you are using a Debian GNU/Linux distribution install the `nginx-full package; the module has been included in the debian package since version 1.1.6-1, so it is available on all stable distributions since the wheezy release. ### Configuration The module only has two directives: – auth_pam`: This is the http authentication realm.

auth_pam_service_name #

syntax: auth_pam_service_name 1 arg (string);  ·  context: http, server, location, limit_except

Stores a single string value.

auth_pam_set_pam_env #

syntax: auth_pam_set_pam_env on | off (on/off flag);  ·  context: http, server, location, limit_except

Boolean directive — set to "on" or "off".

Example

location /private/ {
    auth_pam              "Restricted Area";
    auth_pam_service_name "nginx";
    auth_pam_set_pam_env  REMOTE_ADDR=$remote_addr;
}

↑ back to index

http-auth-spnego #

Nginx module for HTTP SPNEGO auth

Source: upstream source

Directives

auth_gss #

syntax: auth_gss on | off (on/off flag);

on/off, for ease of unsecuring while leaving other options in

auth_gss_allow_basic_fallback #

syntax: auth_gss_allow_basic_fallback on | off (on/off flag);

This is done by setting auth_gss_allow_basic_fallback in the config file. auth_gss_allow_basic_fallback off These options affect the operation of basic authentication: * auth_gss_realm: Kerberos realm name.

auth_gss_authorized_principal #

syntax: auth_gss_authorized_principal on | off (list of strings);

a principal name as a string, e.g. alice@EXAMPLE.COM.

auth_gss_authorized_principal_regex #

syntax: auth_gss_authorized_principal_regex on | off;

a regex to match against, e.g.

auth_gss_constrained_delegation #

syntax: auth_gss_constrained_delegation on | off (on/off flag);

Constrained delegation (S4U2proxy) can also be enabled using the auth_gss_constrained_delegation directive together with the auth_gss_delegate_credentials directive.

auth_gss_delegate_credentials #

syntax: auth_gss_delegate_credentials on | off (on/off flag);

Credential Delegation —————————– User credentials can be delegated to nginx using the auth_gss_delegate_credentials directive.

auth_gss_force_realm #

syntax: auth_gss_force_realm on | off (on/off flag);

Forcibly authenticate using the realm configured in

auth_gss_format_full #

syntax: auth_gss_format_full on | off (on/off flag);

To override this behavior, set auth_gss_format_full to on in your configuration.

auth_gss_keytab #

syntax: auth_gss_keytab on | off (string);

absolute path to the keytab file containing service

auth_gss_map_to_local #

syntax: auth_gss_map_to_local on | off (on/off flag);

If you would like to enable GSS local name rules to rewrite usernames, you can specify the auth_gss_map_to_local option.

auth_gss_realm #

syntax: auth_gss_realm on | off (string);

Kerberos realm name. In most deployments this should not

auth_gss_service_ccache #

syntax: auth_gss_service_ccache on | off (string);

To specify the ccache file name to store the service ticket used for constrained delegation, set the auth_gss_service_ccache directive.

auth_gss_service_name #

syntax: auth_gss_service_name on | off (string);

service principal name to use when acquiring

auth_gss_zone_name #

syntax: auth_gss_zone_name 1 arg (string);  ·  context: http

Stores a single string value.

Example

location /secure/ {
    auth_gss              on;
    auth_gss_realm        EXAMPLE.COM;
    auth_gss_keytab       /etc/krb5.keytab;
    auth_gss_service_name HTTP/nginx.example.com;
    auth_gss_allow_basic_fallback on;
}

↑ back to index

http-auth-totp #

Time-based one-time password (TOTP) authentication for Nginx

Source: upstream source

Directives

auth_totp_cookie #

syntax: auth_totp_cookie <name>  ·  default: totp  ·  context: http, server, location, limit_except

Specifies the name of the HTTP cookie to be used for tracking authenticated clients.

auth_totp_expiry #

syntax: auth_totp_expiry <interval>  ·  default: 0s  ·  context: http, server, location, limit_except

Specifies the expiry time for the HTTP cookie to be used for tracking authenticated clients.

auth_totp_file #

syntax: auth_totp_file <filename>  ·  default: -  ·  context: http, server, location, limit_except

Specifies the file that contains usernames and shared secrets for Time-based One-Time Password (TOTP) authentication. This configuration file has the format:

auth_totp_length #

syntax: auth_totp_length <number>  ·  default: 6  ·  context: http, server, location, limit_except

Specifies the truncation length of the Time-based One-Time Password (TOTP) code. This truncation length may be between 1 and 8 digits inclusively. If the supplied TOTP is of a different length to this value, the authentication request will fail.

auth_totp_realm #

syntax: auth_totp_realm <string>|off  ·  default: off  ·  context: http, server, location, limit_except

Enables validation of user name and Time-based One-Time Password (TOTP) using the "HTTP Basic Authentication" protocol. The specified parameter is used as the realm for this authentication. This parameter value can contain variables. The special value of off cancels the application of any auth_totp_realm directive inherited from a higher configuration level.

auth_totp_reuse #

syntax: auth_totp_reuse <on>|<off>  ·  default: off  ·  context: http, server, location, limit_except

Enables the reuse of a Time-based One-Time Password (TOTP) within a validity window. While this is non-standard behaviour per RFC 6238, it provides a convenient manner to ensure a minimum window of validity for generated TOTP codes, even if the TOTP has already been presented to the validating system.

auth_totp_secret #

syntax: auth_totp_secret <string>  ·  default: -  ·  context: http, server, location, limit_except

A server-side secret used when generating session cookies and then when validating session cookies. If an attacker knows this secret, they will be able to forge session cookies that grant access, so it is vital that it be difficult to guess.

auth_totp_skew #

syntax: auth_totp_skew <number>  ·  default: 1  ·  context: http, server, location, limit_except

Specifies the number of time steps by which the time base between the issuing and validating TOTP systems. It is important to note that larger acceptable delay windows represent a larger window for attacks and a balance must be struck between the security and usability of OTPs.

auth_totp_start #

syntax: auth_totp_start <time>  ·  default: 0  ·  context: http, server, location, limit_except

Specifies the UNIX time from which to start counting time steps as part of Time-based One-Time Password (TOTP) algorithm operations. The default value is 0, the UNIX epoch at 1970/01/01.

auth_totp_step #

syntax: auth_totp_step <interval>  ·  default: 30s  ·  context: http, server, location, limit_except

Specifies the time step as part of Time-based One-Time Password (TOTP) algorithm operations.

Example

server {
    listen 80;

    location /protected {
        auth_totp_realm "Protected";
        auth_totp_secret "Secret";
        auth_totp_file /etc/nginx/totp.conf;
        auth_totp_length 8;
        auth_totp_reuse off;
        auth_totp_skew 1;
        auth_totp_step 1m;
        auth_totp_cookie "totp-session";
        auth_totp_expiry 1d;
    }
}

↑ back to index

http-aws-auth #

This nginx module can proxy requests to authenticated S3 backends using Amazon's V4 authentication API. The first version of this module was written for the V2 authentication protocol and can be found in the AuthV2 branch.

Source: upstream source

Directives

aws_access_key #

syntax: aws_access_key 1 arg (string);  ·  context: http, server, location

Stores a single string value.

aws_endpoint #

syntax: aws_endpoint 1 arg;  ·  context: http, server, location

aws_key_scope #

syntax: aws_key_scope 1 arg (string);  ·  context: http, server, location

Stores a single string value.

aws_s3_bucket #

syntax: aws_s3_bucket 1 arg (string);  ·  context: http, server, location

Stores a single string value.

aws_sign #

syntax: aws_sign no args;  ·  context: http, server, location

aws_signing_key #

syntax: aws_signing_key 1 arg (string);  ·  context: http, server, location

Stores a single string value.

Example

  server {
    listen     8000;

    aws_access_key your_aws_access_key; # Example AKIDEXAMPLE
    aws_key_scope scope_of_generated_signing_key; #Example 20150830/us-east-1/service/aws4_request
    aws_signing_key signing_key_generated_using_script; #Example L4vRLWAO92X5L3Sqk5QydUSdB0nC9+1wfqLMOKLbRp4=
    aws_s3_bucket your_s3_bucket;

    location / {
      aws_sign;
      proxy_pass http://your_s3_bucket.s3.amazonaws.com;
    }

    # This is an example that does not use the server root for the proxy root
    location /myfiles {

      rewrite /myfiles/(.*) /$1 break;
      proxy_pass http://your_s3_bucket.s3.amazonaws.com/$1;

      aws_access_key your_aws_access_key;
      aws_key_scope scope_of_generated_signing_key;
      aws_signing_key signing_key_generated_using_script;
    }

    # This is an example that use specific s3 endpoint, default endpoint is s3.amazonaws.com
    location /s3_beijing {

      rewrite /s3_beijing/(.*) /$1 break;
      proxy_pass http://your_s3_bucket.s3.cn-north-1.amazonaws.com.cn/$1;

      aws_sign;
      aws_endpoint "s3.cn-north-1.amazonaws.com.cn";
      aws_access_key your_aws_access_key;
      aws_key_scope scope_of_generated_signing_key;
      aws_signing_key signing_key_generated_using_script;
    }
  }

↑ back to index

http-bot-verifier #

NGINX module that validates incoming traffic claiming to be search-engine crawlers (Googlebot, Bingbot, …) by reverse-DNS lookup.

Source: upstream source

Directives

bot_verifier #

syntax: bot_verifier 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

bot_verifier_enable_repsheet #

syntax: bot_verifier_enable_repsheet 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

bot_verifier_redis_connection_timeout #

syntax: bot_verifier_redis_connection_timeout 1 arg (integer);  ·  context: http, server, location

This setting is used to connect to the Redis database used for caching lookup results. Back to TOC bot_verifier_redis_connection_timeout ————————————- syntax: bot_verifier_redis_connection_timeout &lt;int&gt; default: 10 context: location phase: access Sets the timeout when connecting to Redis.

bot_verifier_redis_expiry #

syntax: bot_verifier_redis_expiry 1 arg (integer);  ·  context: http, server, location

This setting is used to connect to the Redis database used for caching lookup results. Back to TOC bot_verifier_redis_expiry ————————- syntax: bot_verifier_redis_expiry &lt;seconds&gt; default: 3600 context: location phase: access Sets the timeout when querying Redis.

bot_verifier_redis_host #

syntax: bot_verifier_redis_host 1 arg (string);  ·  context: http, server, location

The module will not act unless it is set to on. Back to TOC bot_verifier_redis_host ———————– syntax: bot_verifier_redis_host &lt;string&gt; default: localhost context: location phase: access Sets the Redis host.

bot_verifier_redis_port #

syntax: bot_verifier_redis_port 1 arg (integer);  ·  context: http, server, location

This setting is used to connect to the Redis database used for caching lookup results. Back to TOC bot_verifier_redis_port ———————– syntax: bot_verifier_redis_port &lt;int&gt; default: 6379 context: location phase: access Sets the Redis port.

bot_verifier_redis_read_timeout #

syntax: bot_verifier_redis_read_timeout 1 arg (integer);  ·  context: http, server, location

This setting is used to connect to the Redis database used for caching lookup results. Back to TOC bot_verifier_redis_read_timeout ————————————- syntax: bot_verifier_redis_read_timeout &lt;int&gt; default: 10 context: location phase: access Sets the timeout when querying Redis.

Example

events {
    worker_connections  1024;
}

http {
    server {
        bot_verifier_redis_host localhost;
        bot_verifier_redis_port 6379;
        bot_verifier_redis_connection_timeout 10;
        bot_verifier_redis_read_timeout 10;
        bot_verifier_redis_expiry 3600;
        bot_verifier_enable_repsheet on;

        listen 8888;

        location / {
            bot_verifier on;
        }
    }
}

↑ back to index

http-brotli #

Brotli is a generic-purpose lossless compression algorithm that compresses data using a combination of a modern variant of the LZ77 algorithm, Huffman coding and 2nd order context modeling, with a compression ratio comparable to the best currently available general-purpose compression methods. It is similar in speed wi

Source: upstream source

Directives

brotli #

syntax: brotli on|off  ·  default: off  ·  context: http, server, location, if

Enables or disables on-the-fly compression of responses.

brotli_buffers #

syntax: brotli_buffers <number> <size>  ·  default: 32 4k|16 8k  ·  context: http, server, location

Deprecated, ignored.

brotli_comp_level #

syntax: brotli_comp_level <level>  ·  default: 6  ·  context: http, server, location

Sets on-the-fly compression Brotli quality (compression) level. Acceptable values are in the range from 0 to 11.

brotli_min_length #

syntax: brotli_min_length <length>  ·  default: 20  ·  context: http, server, location

Sets the minimum length of a response that will be compressed. The length is determined only from the Content-Length response header field.

brotli_static #

syntax: brotli_static on|off|always  ·  default: off  ·  context: http, server, location

Enables or disables checking of the existence of pre-compressed files with.br extension. With the always value, pre-compressed file is used in all cases, without checking if the client supports it.

brotli_types #

syntax: brotli_types <mime_type> [..]  ·  default: text/html  ·  context: http, server, location

Enables on-the-fly compression of responses for the specified MIME types in addition to text/html. The special value * matches any MIME type. Responses with the text/html MIME type are always compressed.

brotli_window #

syntax: brotli_window <size>  ·  default: 512k  ·  context: http, server, location

Sets Brotli window size. Acceptable values are 1k, 2k, 4k, 8k, 16k, 32k, 64k, 128k, 256k, 512k, 1m, 2m, 4m, 8m and 16m.

Example

brotli on;
brotli_comp_level 6;
brotli_static on;
brotli_types application/atom+xml application/javascript application/json application/vnd.api+json application/rss+xml
             application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype
             application/x-font-ttf application/x-javascript application/xhtml+xml application/xml
             font/eot font/opentype font/otf font/truetype image/svg+xml image/vnd.microsoft.icon
             image/x-icon image/x-win-bitmap text/css text/javascript text/plain text/xml;

↑ back to index

http-cache-dechunk-filter #

allows range request for cached response that was recieved from upstream with Transfer-Encoding: chunked.

Source: upstream source

Directives

cache_dechunk #

syntax: cache_dechunk 1 arg (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

Example

load_module "/usr/lib64/nginx/modules/ngx_http_cache_dechunk_filter_module.so";

http {
    proxy_cache_path /var/lib/nginx/tmp/cache keys_zone=sample:10m max_size=10g;

    server {
        proxy_cache         sample;
        proxy_cache_valid   200 1h;
        proxy_http_version  1.1;

        cache_dechunk on;

        location / {
            proxy_pass http://upstream;
        }
    }
}

↑ back to index

http-cache-purge #

An nginx module that adds cache purge support for FastCGI, proxy, SCGI, and uWSGI caches. A purge operation removes the cached entry whose key matches the purge request.

Source: upstream source

Directives

cache_purge_background_queue #

syntax: cache_purge_background_queue 1 arg;  ·  context: http

When enabled, wildcard and purge_all purge requests are enqueued and return 202 Accepted immediately; a per-worker background timer drains the queue in batches. Has no effect on exact-key purges, which are always synchronous. When disabled, all purges are processed synchronously in the request handler.

cache_purge_batch_size #

syntax: cache_purge_batch_size 1 arg (integer);  ·  context: http

Number of queue entries processed per background timer tick. Values above 64 are clamped to 64 at startup (a warning is logged). Reduce this value if purge operations cause iowait spikes; increase it for faster queue drain on fast storage. Only meaningful when cache_purge_background_queue on.

cache_purge_legacy_status #

syntax: cache_purge_legacy_status 1 arg;  ·  context: http

Controls the HTTP status code returned when a purge request targets an entry that is not in the cache: Default is on (412) for backwards compatibility with earlier releases. Set to off to return 404 Not Found, the correct HTTP status for a resource that does not exist (RFC 9110 §15.5.5).

cache_purge_queue_size #

syntax: cache_purge_queue_size 1 arg (integer);  ·  context: http

Maximum number of entries the background queue can hold. Each slot occupies roughly 1–2 KB of shared memory (2048 slots ≈ 3 MB). When the queue is full, new wildcard / purge_all purge requests fall back to synchronous processing. Only meaningful when cache_purge_background_queue on.

cache_purge_response_type #

syntax: cache_purge_response_type 1 arg;  ·  context: http, server, location

Sets the Content-Type and body format of purge responses. Has no effect on cache-miss responses (412 / 404), which are generated by nginx's built-in error-page renderer.

cache_purge_throttle_ms #

syntax: cache_purge_throttle_ms 1 arg (duration in ms);  ·  context: http

Interval between background processing ticks. Accepts any nginx time value: 10ms, 500ms, 1s, 2s 500ms. Only meaningful when cache_purge_background_queue on. Increase on constrained or spinning-disk storage; decrease on NVMe. Time-unit note: a bare integer with no suffix (e.g. 10) is interpreted

cache_purge_vary_aware #

syntax: cache_purge_vary_aware 1 arg;  ·  context: http

When on, an exact-key purge walks the cache directory after deleting the primary file and removes any remaining files that carry the same KEY: string. This covers all Vary and gzip_vary variants of a cached response, which are stored at different filesystem paths but share one logical key. The byte variant regardless. —

fastcgi_cache_purge #

syntax: fastcgi_cache_purge 1+ args;  ·  context: http, server, location

Equivalent to proxy_cache_purge but for FastCGI cache zones configured with fastcgi_cache / fastcgi_cache_path.

proxy_cache_purge #

syntax: proxy_cache_purge 1+ args;  ·  context: http, server, location

Inline form (from …) — intercepts the named HTTP method on a proxy location and purges the matching cache entry. on is a shorthand for method PURGE; off disables purging. Optionally restrict to a list of CIDR ranges or use from all to allow from any address. Adding purge_all before from empties the entire cache zone regardless of the request URI.

scgi_cache_purge #

syntax: scgi_cache_purge 1+ args;  ·  context: http, server, location

Equivalent to proxy_cache_purge but for SCGI cache zones configured with scgi_cache / scgi_cache_path.

uwsgi_cache_purge #

syntax: uwsgi_cache_purge 1+ args;  ·  context: http, server, location

Equivalent to proxy_cache_purge but for uWSGI cache zones configured with uwsgi_cache / uwsgi_cache_path.

Example

http {
    proxy_cache_path /var/cache/nginx keys_zone=main:10m;

    cache_purge_background_queue on;
    cache_purge_queue_size        2048;
    cache_purge_batch_size        20;
    cache_purge_throttle_ms       10ms;

    server {
        location / {
            proxy_pass        http://backend;
            proxy_cache       main;
            proxy_cache_key   "$host$uri$is_args$args";
            proxy_cache_purge PURGE from 127.0.0.1;
        }
    }
}

↑ back to index

http-captcha #

Server-rendered CAPTCHA image generator — emits a PNG challenge tied to a cookie; pair with a CSRF token and an MD5 check to gate POST endpoints (login, signup, comment forms) against simple bot traffic.

Source: upstream source

Directives

captcha #

syntax: captcha;  ·  default: ——  ·  context: location

Enables generation of captcha image.

captcha_case #

syntax: captcha_case on | off;  ·  default: off  ·  context: http, server, location

Enables/disables ignoring captcha case.

captcha_charset #

syntax: captcha_charset string;  ·  default: abcdefghkmnprstuvwxyzABCDEFGHKMNPRSTUVWXYZ23456789  ·  context: http, server, location

Sets characters used in captcha text.

captcha_csrf #

syntax: captcha_csrf string;  ·  default: csrf  ·  context: http, server, location

Sets name of csrf var of captcha.

captcha_expire #

syntax: captcha_expire seconds;  ·  default: 3600  ·  context: http, server, location

Sets seconds before expiring captcha.

captcha_font #

syntax: captcha_font string;  ·  default: /usr/share/fonts/ttf-liberation/LiberationSans-Regular.ttf  ·  context: http, server, location

Sets font of captcha text.

captcha_height #

syntax: captcha_height pixels;  ·  default: 30  ·  context: http, server, location

Sets height of captcha image.

captcha_length #

syntax: captcha_length characters;  ·  default: 4  ·  context: http, server, location

Sets length of captcha text.

captcha_level #

syntax: captcha_level 1 arg (integer);  ·  context: http, server, location

Integer value.

captcha_line #

syntax: captcha_line 1 arg (integer);  ·  context: http, server, location

Integer value.

captcha_name #

syntax: captcha_name string;  ·  default: Captcha  ·  context: http, server, location

Sets name of captcha cookie.

captcha_secret #

syntax: captcha_secret string;  ·  default: secret  ·  context: http, server, location

Sets secret of captcha.

captcha_size #

syntax: captcha_size pixels;  ·  default: 20  ·  context: http, server, location

Sets size of captcha font.

captcha_star #

syntax: captcha_star 1 arg (integer);  ·  context: http, server, location

Integer value.

captcha_width #

syntax: captcha_width pixels;  ·  default: 130  ·  context: http, server, location

Sets width of captcha image.

Example

location =/captcha {
    captcha;
}
location =/login {
    set_form_input $csrf_form csrf;
    set_unescape_uri $csrf_unescape $csrf_form;
    set_form_input $captcha_form captcha;
    set_unescape_uri $captcha_unescape $captcha_form;
    set_md5 $captcha_md5 "secret${captcha_unescape}${csrf_unescape}";
    if ($captcha_md5 != $cookie_captcha) {
        # captcha invalid code
    }
}

↑ back to index

http-cgi #

Brings CGI support to Nginx and Angie webserver.

Source: upstream source

Directives

cgi #

syntax: cgi 1+ args;  ·  context: server, location

If: You are also a fun of CGI If you have any problem with nginx-cgi If you want to get update of nginx-cgi If you want to know more friends Please join us: <https://discord.gg/EJSfqHHmaR>. ## Benchmark CGI is not as slow as people normally think.

cgi_body_only #

syntax: cgi_body_only on | off (on/off flag);  ·  context: server, location

Default: empty #### cgi_body_only <on|off> A standard CGI script should output two parts: header and body.

cgi_interpreter #

syntax: cgi_interpreter any args;  ·  context: server, location

If you clearly set cgi_interpreter, it's okay to remove this line, otherwise missing of shebang will causes a 500 error.

cgi_pass #

syntax: cgi_pass 1+ args;  ·  context: server, location

Default: off #### cgi_pass <script_path> Alias of cgi pass <script_path>. #### cgi_interpreter [interpreter] [args…] Set interpreter and interpreter args for cgi script.

cgi_path #

syntax: cgi_path 1 arg (string);  ·  context: server, location

Default: off #### cgi_path <PATH> Change cgi script PATH environment variable.

cgi_rdns #

syntax: cgi_rdns 1 arg;  ·  context: server, location

If you mind this matter, you should avoid this. stderr: redirect CGI stderr to nginx process's stderr file <path_to_file>: redirect CGI stderr to a file #### cgi_rdns <on|off|double> [required] Enable or disable reverse dns.

cgi_set_var #

syntax: cgi_set_var 2 args;  ·  context: server, location

Default: on #### cgi_set_var <name> <value> Add and pass extra environment variables to CGI script.

cgi_stderr #

syntax: cgi_stderr 1 arg;  ·  context: server, location

But it's not recommanded, it may introduce confusing issues to your system. #### cgi_stderr <off|info|warn|error|crit|alert|emerg|stderr> #### cgi_stderr file <path_to_file> By default, nginx-cgi grab cgi script's stderr output and dump it to nginx log with warn level.

cgi_strict #

syntax: cgi_strict on | off (on/off flag);  ·  context: server, location

If cgi_strict is on, nginx-cgi will check all cgi output headers, and 500 error will be responsed if invalid header found.

cgi_timeout #

syntax: cgi_timeout 1 arg;  ·  context: server, location

cgi_working_dir #

syntax: cgi_working_dir 1 arg;  ·  context: server, location

Default: empty #### cgi_working_dir <dir> Set the working directory of CGI script.

Example

daemon off;
master_process off;
error_log /dev/stderr debug;

load_module ../../nginx/objs/ngx_http_cgi_module.so;

events {
    # Mac OS has a limitation of 255 file descriptors by default
    worker_connections 128;
}

http {
    server {
        listen 8000;
        root html;
        # http2 on;

        location /cgi-bin {
            cgi on;
            # cgi_timeout 10 5;
        }

        location /cgi {
            rewrite ^/cgi/(.*)$ /cgi-bin/$1 last;
        }
    }
}

↑ back to index

http-combined-upstreams #

Nginx Combined Upstreams module

Source: upstream source

Directives

add_upstream #

syntax: add_upstream 1 arg;  ·  context: upstream

A comprehensive article discovering details of implementation of directive add_upstream which can also be regarded as a small tutorial for Nginx modules development. 2. nginx upstrand to configure super-layers of upstreams.

combine_server_singlets #

syntax: combine_server_singlets no args;  ·  context: upstream

Directive combine_server_singlets in upstream u1 generates two singlet upstreams u1_single_1 and u1_single_2 to inhabit upstrand us1.

dynamic_upstrand #

syntax: dynamic_upstrand 2+ args;  ·  context: server, location, location-if

Additionally, directive dynamic_upstrand is introduced for choosing upstrands in run-time.

extend_single_peers #

syntax: extend_single_peers no args;  ·  context: upstream

Directive extend_single_peers —————————– Peers in upstreams fail according to the rules listed in directive proxy_next_upstream.

upstrand #

syntax: upstrand 1 arg;  ·  context: http

Block upstrand ————– Is aimed to configure a super-layer of upstreams that do not lose their identities.

Example

# this nginx configuration file is for demonstration purpose only

user                    nobody;
worker_processes        1;

events {
    worker_connections  1024;
}

http {
    default_type        application/octet-stream;
    sendfile            on;

    log_format          fmt '$remote_addr [$time_local]\n'
                            '>>> [path]          $upstrand_path\n'
                            '>>> [addr]          $upstrand_addr\n'
                            '>>> [response time] $upstrand_response_time\n'
                            '>>> [status]        $upstrand_status';

    upstream u1 {
        server localhost:8020;
    }
    upstream u2 {
        server localhost:8030;
    }
    upstream ucombined {
        server localhost:8030;
        add_upstream u1;
        add_upstream u2 backup;
    }
    upstream u3 {
        server localhost:8020;
        server localhost:8030;
        combine_server_singlets;
        combine_server_singlets byname;
        combine_server_singlets _tmp_ 2;
    }
    upstream u4 {
        server localhost:8020;
        server localhost:8030;
        combine_server_singlets _single_ nobackup;
    }

    upstream u01 {
        # to test next_upstream_statuses error set port 8140
        server localhost:8040;
    }
    upstream u02 {
        # to test next_upstream_statuses error set port 8150
        server localhost:8050;
    }
    upstream b01 {
        server localhost:8060;
    }
    upstream b02 {
        server localhost:8070;
    }

    upstrand us1 {
        upstream ~^u0 blacklist_interval=60s;
        upstream b01 backup;
        order start_random;
        next_upstream_statuses error timeout non_idempotent 204 5xx;
        next_upstream_timeout 60s;
        #next_upstream_statuses 200 204 5xx;
        #next_upstream_statuses error timeout;
    }
    upstrand us2 {
        upstream ~^u0;
        upstream b02 backup;
        order start_random;
        next_upstream_statuses 5xx;
        intercept_statuses 5xx /Internal/failover;
    }
    upstrand us4 {
        upstream ~^u4_single_ blacklist_interval=60s;
        order per_request;
        next_upstream_statuses error timeout non_idempotent 5xx;
        intercept_statuses 5xx /Internal/failover;
    }

    proxy_read_timeout 5s;
    proxy_intercept_errors on;
    #proxy_next_upstream_tries 1;

    server {
        listen       8010;
        server_name
…

↑ back to index

http-compression-normalize #

ngx_http_compression_normalize_module is an Nginx module designed to parse, normalize, and manage the Accept-Encoding headers from client requests. It ensures consistent handling of compression algorithms by standardizing the Accept-Encoding values, facilitating better compression management and improved vary cache per

Source: upstream source

Directives

compression_normalize_accept_encoding #

syntax: compression_normalize_accept_encoding combinations1 [combinations2 ..] | off;  ·  default: compression_normalize_accept_encoding off;  ·  context: http, server, location

Enables the normalization of the Accept-Encoding header by specifying preferred combinations of compression algorithms. This directive accepts a list of compression methods, allowing to define the order and priority of encoding types that the server should prefer when responding to client requests. For example, with the following configuration

Example

http {
    compression_normalize_accept_encoding gzip,br,zstd gzip,br zstd br gzip;

    server {
        listen 80;
        server_name example.com;

        location / {
            # Your configurations
        }
    }
}

↑ back to index

http-compression-vary #

ngx_http_compression_vary_filter_module is a header filter module used instead of the 'gzip_vary' directive.

Source: upstream source

Directives

compression_vary #

syntax: compression_vary on | off;  ·  default: compression_vary off;  ·  context: http, server, location

Enables or disables inserting the Vary: Accept-Encoding response header field if the directives gzip, gzip_static, or gunzip are active. This module is also effective when the directives from third-party compression modules such as brotli, brotli_static, unbrotli, zstd, zstd_static, and unzstd are activated.

Example

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location / {
        gzip on;
        compression_vary on;

        proxy_pass http://foo.com;
    }
}

↑ back to index

http-concat #

This is a module that is distributed with tengine which is a distribution of Nginx that is used by the e-commerce/auction site Taobao.com. This distribution contains some modules that are new on the Nginx scene. The ngx_http_concat module is one of them.

Source: upstream source

Directives

concat #

syntax: concat on | off (on/off flag);  ·  context: http, server, location

This applies to any other type of files that you decide to concatenate by adding the respective MIME type via concat_types, <br/> <br/> concat\_max\_files numberp default: concat_max_files 10 context: http, server, location Defines the maximum number of files that can be concatenated in a given context.

concat_delimiter #

syntax: concat_delimiter 1 arg (string);  ·  context: http, server, location

Set it to the value you need. <br/> <br/> concat_delimiter: string default: NONE context: http, server, locatione Defines the delimiter between two files.

concat_ignore_file_error #

syntax: concat_ignore_file_error on | off (on/off flag);  ·  context: http, server, location

on | off

concat_max_files #

syntax: concat_max_files 1 arg (integer);  ·  context: http, server, location

This applies to any other type of files that you decide to concatenate by adding the respective MIME type via concat_types, <br/> <br/> concat\_max\_files numberp default: concat_max_files 10 context: http, server, location Defines the maximum number of files that can be concatenated in a given context.

concat_types #

syntax: concat_types 1+ args;  ·  context: http, server, location

This applies to any other type of files that you decide to concatenate by adding the respective MIME type via concat_types, <br/> <br/> concat\_max\_files numberp default: concat_max_files 10 context: http, server, location Defines the maximum number of files that can be concatenated in a given context.

concat_unique #

syntax: concat_unique on | off (on/off flag);  ·  context: http, server, location

So if you have CSS and JS you cannot do something like this: http://example.com/static/??foo.css,bar/foobaz.js In order to do that you must set concat_unique off.

Example

location /static/ {
    concat            on;
    concat_max_files  20;
    concat_types      text/css application/javascript;
    concat_unique     off;
}
# Then request: /static/??reset.css,layout.css,theme.css

↑ back to index

The Nginx module for adding cookie flag

Source: upstream source

Directives

set_cookie_flag #

syntax: set_cookie_flag 1+ args;  ·  context: server, location

-| – — | — Syntax | set_cookie_flag \<cookie_name\|*\> [HttpOnly] [secure] [SameSite\|SameSite=[Lax\|Strict]]; Default | – Context | server, location Description: Add flag to desired cookie.

Example

location / {
    set_cookie_flag Secret HttpOnly secure SameSite;
    set_cookie_flag * HttpOnly;
    set_cookie_flag SessionID SameSite=Lax secure;
    set_cookie_flag SiteToken SameSite=Strict;
}

↑ back to index

http-cookies-filter #

A NGINX module for fine-grained request cookies control.

Source: upstream source

Directives

add_request_cookie #

syntax: add_request_cookie cookie_name value [if=condition];  ·  default: —  ·  context: http, server, location

Adds a new cookie. If the cookie already exists, the operation is ignored.

clear_request_cookie #

syntax: clear_request_cookie cookie_name [if=condition];  ·  default: —  ·  context: http, server, location

Removes a cookie from the request headers.

rewrite_request_cookie #

syntax: rewrite_request_cookie 2 args;  ·  context: http, server, location

set_request_cookie #

syntax: set_request_cookie cookie_name value [if=condition];  ·  default: —  ·  context: http, server, location

Sets the value of a cookie. If the cookie already exists, it will be modified. Cookie names are case-sensitive, the same below.

Example

http {
    server {
        listen 80;
        server_name example.com;

        location / {
            # If a cookie named "a" exists, set it to 1. Otherwise, add a cookie named "a" with value 1.
            set_request_cookie a 1;

            # If a cookie named "b" exists, do nothing. Otherwise, add a cookie named "a" with value 1.
            add_request_cookie b 2;

            # If a cookie named "c" exists, set it to 3. Otherwise, do nothing.
            modify_request_cookie c 3;
    
            # If a cookie named "d" exists, delete it. Otherwise, do nothing.
            clear_request_cookie d;

            # Conditional filtering. Only effected if varialbe $http_a is not empty or '0'.
            set_request_cookie e 4 if=$http_a;

            # Send the filtered cookies to upstream.
            proxy_set_header Cookie $filtered_request_cookies;

            proxy_pass http://127.0.0.1:8080;
        }
    }
}

↑ back to index

http-cors #

Support Cross-Origin Resource Sharing (CORS) in Nginx.

Source: upstream source

Directives

cors #

syntax: cors on | off;  ·  default: cors off;  ·  context: http, server, location

Master switch to enable CORS processing. When enabled, the module intercepts OPTIONS requests (preflight) and adds CORS headers to all responses that match the configured policies. —

cors_allow_credentials #

syntax: cors_allow_credentials on | off;  ·  default: cors_allow_credentials off;  ·  context: http, server, location

Enables Access-Control-Allow-Credentials: true, allowing requests to include credentials (cookies, HTTP authentication, client certificates). —

cors_allow_headers #

syntax: cors_allow_headers \* | \*\* | header ...;  ·  default: \*;  ·  context: http, server, location

Specifies which request headers are allowed for cross-origin requests. Supports three modes: The following safelisted headers are always allowed and will be silently skipped if you include them in the configuration: Accept, Accept-Language, Content-Language, Content-Type, Range. —

cors_allow_methods #

syntax: cors_allow_methods \* | \*\* | method ...;  ·  default: \*;  ·  context: http, server, location

Specifies which HTTP methods are allowed for cross-origin requests. Supports three modes: Method names are case-sensitive and must be uppercase (GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, etc.). —

cors_allow_origins #

syntax: cors_allow_origins \* | \*\* | origin ...;  ·  default: cors_allow_origins \*;  ·  context: http, server, location

Specifies which origins are allowed to access the resource. Supports three modes: Origins can be specified as exact strings or, if PCRE support is compiled into Nginx, as regex patterns prefixed with ~: —

cors_bypass #

syntax: cors_bypass variable ...;  ·  default: —  ·  context: http, server, location

Defines conditions under which CORS processing is skipped. Accepts one or more Nginx variables. If any variable evaluates to a non-empty, non-zero value (i.e., not "" and not "0"), CORS header injection and preflight handling are bypassed for that request. Examples: When omitted, CORS headers are applied to all requests. —

cors_expose_headers #

syntax: cors_expose_headers header ...;  ·  default: —  ·  context: http, server, location

Specifies which response headers are safe to expose to the browser via Access-Control-Expose-Headers. By default, browsers only expose a limited set of response headers (the safelisted response headers: Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified, Pragma). Use this directive to expose additional headers. —

cors_max_age #

syntax: cors_max_age time;  ·  default: —  ·  context: http, server, location

Specifies how long (in seconds) the browser is allowed to cache the preflight response via Access-Control-Max-Age. Common values: 3600 (1 hour), 86400 (1 day). When set to 0 or not configured, the header is omitted. —

cors_preflight_status #

syntax: cors_preflight_status 200 | 204;  ·  default: cors_preflight_status 200;  ·  context: http, server, location

Specifies the HTTP status code returned for preflight (OPTIONS) requests. Only 200 and 204 are valid values.

Example

http {
    cors on;
    cors_max_age           3600;
    cors_allow_origins     **;
    cors_allow_methods     GET HEAD PUT POST;
    cors_allow_headers     **;

    server {
        listen       80;
        server_name  localhost;

        location / {
            root   html;
            index  index.html index.htm;
        }
    }
}

↑ back to index

http-dav-ext #

Extends the bundled WebDAV module with PROPFIND, OPTIONS, LOCK and UNLOCK methods plus per-zone lock storage — required for real WebDAV clients (Finder, Windows Explorer, davfs2).

Source: upstream source

Directives

dav_ext_lock #

syntax: dav_ext_lock 1 arg;  ·  context: http, server, location

dav_ext_lock_zone #

syntax: dav_ext_lock_zone 1 arg;  ·  context: http

dav_ext_methods #

syntax: dav_ext_methods 1+ args (bitmask);  ·  context: http, server, location

Bitmask — combine several keywords.

Example

location /webdav/ {
    root /var/www;
    dav_methods         PUT DELETE MKCOL COPY MOVE;
    dav_ext_methods     PROPFIND OPTIONS LOCK UNLOCK;
    dav_ext_lock        zone=davlock;
    create_full_put_path on;
}
# Define the lock zone at http {} level:
# dav_ext_lock_zone zone=davlock:10m;

↑ back to index

http-doh #

Simple Nginx module for serving DNS-over-HTTPS (DOH) requests.

Source: upstream source

Directives

doh #

syntax: doh no args;  ·  context: location

doh_address #

syntax: doh_address 1 arg (string);  ·  context: location

Stores a single string value.

doh_port #

syntax: doh_port 1 arg (size (k/m/g));  ·  context: location

Size in bytes; accepts k / m / g suffixes.

doh_timeout #

syntax: doh_timeout 1 arg (duration in ms);  ·  context: location

Duration in milliseconds; accepts ms / s / m suffixes.

Example

location /dns-query { 
	doh;
	doh_address 127.0.2.1;
	doh_port 5353;
	doh_timeout 2;
}

↑ back to index

http-dynamic-etag #

This NGINX module empowers your dynamic content with automatic ETag header. It allows client browsers to issue conditional GET requests to dynamic pages. And thus saves bandwidth and ensures better performance!

Source: upstream source

Directives

dynamic_etag_types #

syntax: dynamic_etag_types <mime_type> [..]  ·  default: text/html  ·  context: http, server, location

Enables applying ETag automatically for the specified MIME types in addition to text/html. The special value * matches any MIME type. Responses with the text/html MIME type are always included.

Example

    location = /hello {
        return 200 "hello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earthhello earth2\n";
    }
    location = /hello-proxy {
        dynamic_etag on;
        dynamic_etag_types text/plain;
        proxy_buffering off;
        proxy_pass http://127.0.0.1:$TEST_NGINX_SERVER_PORT/hello;
    }

↑ back to index

http-dynamic-limit-req #

The ngx_dynamic_limit_req_module module is used to dynamically lock IP and release it periodically.

Source: upstream source

Directives

dynamic_limit_req #

syntax: dynamic_limit_req zone=name [burst=number] [nodelay | delay=number];  ·  default: —  ·  context: http, server, location, if

dynamic_limit_req_log_level #

syntax: dynamic_limit_req_log_level info | notice | warn | error;  ·  default: dynamic_limit_req_log_level error;  ·  context: http, server, location

By default, the maximum burst size is equal to zero. ## dynamic_limit_req_log_level Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing.

dynamic_limit_req_redis #

syntax: dynamic_limit_req_redis unix_socket | port=[number] requirepass=[password];  ·  default: port 6379  ·  context: http

Requests with an empty key value are not accounted. ## dynamic_limit_req_redis Sets optional parameters, unix_socket, port, requirepass.

dynamic_limit_req_status #

syntax: dynamic_limit_req_status code;  ·  default: dynamic_limit_req_status 503;  ·  context: http, server, location, if

Integer value.

dynamic_limit_req_zone #

syntax: dynamic_limit_req_zone key zone=name:size rate=rate [sync] redis=127.0.0.1 block_second=time;  ·  default: —  ·  context: http

Example


    worker_processes  2;
    events {
        worker_connections  1024;
    }
    http {
        include       mime.types;
        default_type  application/octet-stream;
        sendfile        on;
        keepalive_timeout  65;

   dynamic_limit_req_zone $binary_remote_addr zone=one:10m rate=100r/s redis=127.0.0.1 block_second=300;
   dynamic_limit_req_zone $binary_remote_addr zone=two:10m rate=50r/s redis=127.0.0.1 block_second=600;
   dynamic_limit_req_zone $binary_remote_addr zone=sms:5m rate=5r/m redis=127.0.0.1 block_second=1800;


        server {
            listen       80;
            server_name  localhost;
            location / {

                if ($http_x_forwarded_for) {
                 return 400;
                }
                root   html;
                index  index.html index.htm;
                dynamic_limit_req zone=one burst=100 nodelay;
                dynamic_limit_req_status 403;
            }
            error_page   403 500 502 503 504  /50x.html;
            location = /50x.html {
                root   html;
            }
        }
        server {
            listen       80;
            server_name  localhost2;
            location / {
                root   html;
                index  index.html index.htm;

                    set $flag 0;
                   if ($document_uri ~* "regist"){
                      set $flag "${flag}1";
                        }
                  if ($request_method = POST ) {
                        set $flag "${flag}2";
                          }
                      if ($flag = "012"){
                      dynamic_limit_req zone=sms burst=3 nodelay;
                      dynamic_limit_req_status 403;
                      }


                      if ($document_uri ~* "getSmsVerifyCode.do"){
                      dynamic_limit_req zone=sms burst=5 nodelay;
                      dynamic_limit_req_status 444;
                }

                dynamic_limit_req zone=two burst=50 nodelay;
                dynamic_limit_req_status 403;
            }
            error_page   403 502 503 504  /50x.html;
            location = /50x.html {
                root   html;
            }
        }
    }

↑ back to index

http-dynamic-upstream #

ngx_dynamic_upstream is the module for operating upstreams dynamically with HTTP APIs such as ngx_http_upstream_conf.

Source: upstream source

Directives

dynamic_upstream #

syntax: dynamic_upstream no args;  ·  context: location

Now ngx_dynamic_upstream supports dynamic upstream under only http context.

Example

upstream backends {
    zone zone_for_backends 1m;
    server 127.0.0.1:6001;
    server 127.0.0.1:6002;
    server 127.0.0.1:6003;
}

server {
    listen 6000;

    location /dynamic {
		allow 127.0.0.1;
	    deny all;
        dynamic_upstream;
    }

    location / {
	    proxy_pass http://backends;
    }
}

↑ back to index

http-early-hints #

This is an experimental nginx module that sending 103 early hints before sending content(NGX_HTTP_ACCESS_PHASE).

Source: upstream source

Directives

add_early_header #

syntax: add_early_header 2 args;  ·  context: location, location-if

Example

    location /103 {
        add_early_header "Link" "</main.css>;rel=preload";
        add_early_header "Link" "</main.js>;rel=preload";
        if ($early_hints = 1) {
           return 200;
        }
    }

↑ back to index

http-echo #

Brings "echo", "sleep", "time", "exec" and other shell-style helpers into the nginx config language — handy for quick endpoints, test rigs and concatenating subrequests.

Source: upstream source

Directives

echo #

syntax: echo any args;  ·  context: location, location-if

echo_abort_parent #

syntax: echo_abort_parent no args;  ·  context: location, location-if

echo_after_body #

syntax: echo_after_body any args;  ·  context: location, location-if

echo_before_body #

syntax: echo_before_body any args;  ·  context: location, location-if

echo_blocking_sleep #

syntax: echo_blocking_sleep 1 arg;  ·  context: location, location-if

echo_duplicate #

syntax: echo_duplicate 2+ args;  ·  context: location, location-if

echo_end #

syntax: echo_end no args;  ·  context: location, location-if

echo_exec #

syntax: echo_exec 1 arg;  ·  context: location, location-if

echo_flush #

syntax: echo_flush no args;  ·  context: location, location-if

echo_foreach_split #

syntax: echo_foreach_split 2+ args;  ·  context: location, location-if

echo_location #

syntax: echo_location 1 arg;  ·  context: location, location-if

echo_location_async #

syntax: echo_location_async 1 arg;  ·  context: location, location-if

echo_read_request_body #

syntax: echo_read_request_body no args;  ·  context: location, location-if

echo_request_body #

syntax: echo_request_body no args;  ·  context: location, location-if

echo_reset_timer #

syntax: echo_reset_timer no args;  ·  context: location, location-if

echo_sleep #

syntax: echo_sleep 1 arg;  ·  context: location, location-if

echo_status #

syntax: echo_status 1 arg (integer);  ·  context: location, location-if

Integer value.

echo_subrequest #

syntax: echo_subrequest 2+ args;  ·  context: location, location-if

echo_subrequest_async #

syntax: echo_subrequest_async 2+ args;  ·  context: location, location-if

Example

    location /abort {
        echo hello;
        echo_flush;
        echo_location_async '/foo';
        echo_location_async '/bar';
        echo_location_async '/baz';
        echo world;
        echo_flush;
    }

    location /proxy {
        proxy_pass "http://127.0.0.1:$server_port/sleep?$query_string";
    }

    location /sleep {
        echo_sleep $arg_sleep;
        echo $arg_echo;
        echo_flush;
    }

    location /foo {
        echo_location '/proxy?sleep=1&echo=foo';
        #echo_flush;
        echo_abort_parent;
    }

    location /bar {
        proxy_pass 'http://127.0.0.1:$server_port/sleep_bar';
    }

    location /baz {
        proxy_pass 'http://127.0.0.1:$server_port/sleep_baz';
    }

    location /sleep_bar {
        echo_sleep 2;
        echo bar;
    }

    location /sleep_baz {
        echo_sleep 3;
        echo baz;
    }

↑ back to index

http-encrypted-session #

encrypted-session-nginx-module – encrypt and decrypt nginx variable values

Source: upstream source

Directives

encrypted_session_expires #

syntax: encrypted_session_expires 1 arg;  ·  context: http, server, location, server-if, location-if

For example, Back to TOC encrypted_session_expires ————————- syntax: encrypted_session_expires &lt;time&gt; default: encrypted_session_expires 1d; context: http, server, server if, location, location if Sets expiration time difference (in seconds by default).

encrypted_session_iv #

syntax: encrypted_session_iv 1 arg;  ·  context: http, server, location, server-if, location-if

For example, Back to TOC encrypted_session_iv ——————– syntax: encrypted_session_iv &lt;iv&gt; default: encrypted_session_iv "deadbeefdeadbeef"; context: http, server, server if, location, location if Sets the initial vector used for the cipher (must be no longer than 16 bytes).

encrypted_session_key #

syntax: encrypted_session_key 1 arg;  ·  context: http, server, location, server-if, location-if

set_decrypt_session #

syntax: set_decrypt_session 1 arg;  ·  context: http, server, location, server-if, location-if

set_encrypt_session #

syntax: set_encrypt_session 1 arg;  ·  context: http, server, location, server-if, location-if

Example

# key must be of 32 bytes long
encrypted_session_key "abcdefghijklmnopqrstuvwxyz123456";

# iv must not be longer than 16 bytes
#   default: "deadbeefdeadbeef" (w/o quotes)
encrypted_session_iv "1234567812345678";

# default: 1d (1 day)
encrypted_session_expires 3600; # in sec

location /encrypt {
    set $raw 'text to encrypted'; # from the ngx_rewrite module
    set_encrypt_session $session $raw;
    set_encode_base32 $session; # from the ngx_set_misc module

    add_header Set-Cookie 'my_login=$session';  # from the ngx_headers module

    # your content handler goes here...
}

location /decrypt {
    set_decode_base32 $session $cookie_my_login; # from the ngx_set_misc module
    set_decrypt_session $raw $session;

    if ($raw = '') {
        # bad session
    }

    # your content handler goes here...
}

↑ back to index

http-enhanced-memc #

Drop-in replacement for the standard memcached module with custom HTTP header pass-through (Content-Type, Last-Modified) and flush/stats endpoints.

Source: upstream source

Directives

enhanced_memcached_allow_delete #

syntax: enhanced_memcached_allow_delete on | off (on/off flag);  ·  context: location

Boolean directive — set to "on" or "off".

enhanced_memcached_allow_put #

syntax: enhanced_memcached_allow_put on | off (on/off flag);  ·  context: location

Boolean directive — set to "on" or "off".

enhanced_memcached_bind #

syntax: enhanced_memcached_bind 1 arg;  ·  context: http, server, location

enhanced_memcached_buffer_size #

syntax: enhanced_memcached_buffer_size 1 arg (size (k/m/g));  ·  context: http, server, location

Size in bytes; accepts k / m / g suffixes.

enhanced_memcached_connect_timeout #

syntax: enhanced_memcached_connect_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

enhanced_memcached_flush #

syntax: enhanced_memcached_flush on | off (on/off flag);  ·  context: location

Boolean directive — set to "on" or "off".

enhanced_memcached_flush_namespace #

syntax: enhanced_memcached_flush_namespace on | off (on/off flag);  ·  context: location

Boolean directive — set to "on" or "off".

enhanced_memcached_hash_keys_with_md5 #

syntax: enhanced_memcached_hash_keys_with_md5 on | off (on/off flag);  ·  context: location

Boolean directive — set to "on" or "off".

enhanced_memcached_pass #

syntax: enhanced_memcached_pass 1 arg;  ·  context: location, location-if

enhanced_memcached_read_timeout #

syntax: enhanced_memcached_read_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

enhanced_memcached_send_timeout #

syntax: enhanced_memcached_send_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

enhanced_memcached_stats #

syntax: enhanced_memcached_stats on | off (on/off flag);  ·  context: location

Boolean directive — set to "on" or "off".

Example

worker_processes 1;
worker_rlimit_nofile 1000;

events {
  worker_connections 1000;
}

pid nginx.pid;

error_log logs/error.log debug;

http {

	default_type application/octet-stream;

	upstream memcached_upstream {
	  server 127.0.0.1:11211;
	  keepalive 20;
	}

	server {
		listen 127.0.0.1:8086;

		server_name ~^(?<real_host>.*).put$;

		location / {
		  set $enhanced_memcached_key "$request_uri";
		  set $enhanced_memcached_expire $http_memcached_expire;
		  set $enhanced_memcached_use_add $http_memcached_use_add;
		  set $enhanced_memcached_key_namespace "$real_host";
		  enhanced_memcached_hash_keys_with_md5 on;
		  enhanced_memcached_allow_put on;
		  enhanced_memcached_allow_delete on;
		  enhanced_memcached_pass memcached_upstream;
		}

		location /stats {
		  enhanced_memcached_stats on;
		  enhanced_memcached_pass memcached_upstream;
		  access_log off;
		}

		location /flushns {
		  set $enhanced_memcached_key "$request_uri";
		  set $enhanced_memcached_key_namespace "$real_host";
		  enhanced_memcached_flush_namespace on;
		  enhanced_memcached_pass memcached_upstream;
		}

		location /flush {
		  enhanced_memcached_flush on;
		  enhanced_memcached_pass memcached_upstream;
		}

	}

	server {
		listen 127.0.0.1:8086;

		server_name ~^(?<real_host>.*)$;

		gzip              on;
	  gzip_proxied      any;
	  gzip_http_version 1.0;
	  gzip_comp_level   5;
	  gzip_types        text/plain text/css application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript application/atom+xml application/vnd.ms-fontobject application/x-font-ttf font/opentype;
	  gzip_vary        on;

    if ($request_method != GET) {
       return 404;
    }

    if ($http_pragma ~* "no-cache") {
       return 404;
    }

    if ($http_cache_control ~* "no-cache") {
       return 404;
    }

	 	location / {
	    set $enhanced_memcached_key "$request_uri";
	    set $enhanced_memcached_key_namespace "$real_host";
	    enhanced_memcached_hash_keys_with_md5 on;
	    enhanced_memcached_pass memcached_upstream;
	  }
	}

	server {

		listen 127.0.0.1:8087;

		server_name ~^(?<real_host>.*).put$;

		location / {
		  set $enhanced_memcached_key "$request_uri";
		  set $enhanced_memcached_expire $http_memcached_expire;
		  set $enhanced_memcached_use_add $http_memcached_use_add;
		  enhanced_memcached_hash_keys_with_md5 on;
		  enhanced_memcached_
…

↑ back to index

http-error-log-write #

ngx_http_error_log_write_module allows writing error log entries based on conditional expressions in nginx configuration files..

Source: upstream source

Directives

error_log_write #

syntax: error_log_write [level=log_level] message=text [if=condition];  ·  default: -  ·  context: http, server, location

Writing a new error log. All error log entries are inherited unconditionally from the previous configuration level.

Example

error_log_write level=info message="main test log";

server {
    listen 127.0.0.1:80;
    server_name localhost;

    error_log_write  message="server test log" if=$arg_test; 

    location / {
        error_log_write level=warn message="auth required" if!=$http_authorization;
        auth_baisc "auth required";
        auth_basic_user_file conf/htpasswd;
        proxy_pass http://example.upstream.com;
    }
}

↑ back to index

http-eval #

ngx_eval – Capturing subrequest response bodies into NGINX variables

Source: upstream source

Directives

eval #

syntax: eval 1+ args;  ·  context: location

eval_buffer_size #

syntax: eval_buffer_size 1 arg (size (k/m/g));  ·  context: http, server, location

Size in bytes; accepts k / m / g suffixes.

eval_escalate #

syntax: eval_escalate 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

eval_override_content_type #

syntax: eval_override_content_type 1 arg (string);  ·  context: http, server, location

Stores a single string value.

eval_subrequest_in_memory #

syntax: eval_subrequest_in_memory on | off;  ·  context: http, server, location

Example

# an example for working with the ngx_drizzle + ngx_rds_json
# modules, but you must put ngx_rds_json *after*
# ngx_eval during nginx configure, for example:
#     ./configure --add-module=/path/to/nginx-eval-module \
#           --add-module=/path/to/rds-json-nginx-module \
#           --add-module=/path/to/drizzle-nginx-module
location = /mysql {
    eval_subrequest_in_memory off;
    eval_override_content_type text/plain;
    eval_buffer_size 4k; # default 4k, truncated if overflown
    eval $res {
        drizzle_query "select * from cats";
        drizzle_pass my_mysql_backend;
        rds_json on;
    }
    # now $res holds the JSON formatted result set
    if ($res ~ '"Tom"') {
        echo "Found the Tom cat!";
        break;
    }
    echo "The Tom cat is missing!";
}

# an example for working with the ngx_postgres module
location = /login {
   eval_subrequest_in_memory off;
   eval_override_content_type text/plain;
   eval_buffer_size 1k;
   eval $uid {
       postgres_query "select id
           from users
           where name=$arg_name and pass=$arg_pass";
       postgres_pass pg_backend;
       postgres_output value 0 0;
   }
   if ($uid !~ '^\d+$') {
       rewrite ^ /relogin redirect; break;
   }
   # your content handler settings...
}

↑ back to index

http-extra-variables #

A collection of extra variables for NGINX. Used to meet logging or other needs.

Source: upstream source

No nginx directives detected.

↑ back to index

http-fancyindex #

Replaces the built-in autoindex with a richer, themeable directory listing — supports CSS, custom header/footer, sorting, human-readable sizes and localised timestamps.

Source: upstream source

Directives

fancyindex #

syntax: fancyindex on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

fancyindex_case_sensitive #

syntax: fancyindex_case_sensitive on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

fancyindex_css_href #

syntax: fancyindex_css_href on | off (string);  ·  context: http, server, location

Stores a single string value.

fancyindex_default_sort #

syntax: fancyindex_default_sort 1 arg (enum);  ·  context: http, server, location

Pick one of an enumerated set of values.

fancyindex_directories_first #

syntax: fancyindex_directories_first on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

fancyindex_exact_size #

syntax: fancyindex_exact_size on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

fancyindex_footer #

syntax: fancyindex_footer 1 arg;  ·  context: http, server, location

fancyindex_header #

syntax: fancyindex_header 1 arg;  ·  context: http, server, location

fancyindex_hide_parent_dir #

syntax: fancyindex_hide_parent_dir on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

fancyindex_hide_symlinks #

syntax: fancyindex_hide_symlinks on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

fancyindex_ignore #

syntax: fancyindex_ignore 1+ args;  ·  context: http, server, location

fancyindex_localtime #

syntax: fancyindex_localtime on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

fancyindex_show_dotfiles #

syntax: fancyindex_show_dotfiles on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

fancyindex_show_path #

syntax: fancyindex_show_path on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

fancyindex_time_format #

syntax: fancyindex_time_format on | off (string);  ·  context: http, server, location

Stores a single string value.

Example

location / {
    fancyindex                on;
    fancyindex_exact_size     off;
    fancyindex_name_length    64;
    fancyindex_default_sort   name;
    fancyindex_directories_first on;
    fancyindex_localtime      on;
    fancyindex_header         "/.fancyindex/header.html";
    fancyindex_footer         "/.fancyindex/footer.html";
}

↑ back to index

http-flv-live #

A media streaming server based on nginx-rtmp-module.

Source: upstream source

Directives

access_log #

syntax: access_log 1 arg;

ack_window #

syntax: ack_window 1 arg (integer);

Integer value.

allow #

syntax: allow 1 arg;

application #

syntax: application 1 arg;

The appname is used to match an application block in rtmp block (see below for details).

buffer #

syntax: buffer 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

buflen #

syntax: buflen 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

busy #

syntax: busy 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

chunk_size #

syntax: chunk_size 1 arg (integer);

Integer value.

connection_pool_size #

syntax: connection_pool_size 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

dash #

syntax: dash 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

dash_cleanup #

syntax: dash_cleanup 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

dash_fragment #

syntax: dash_fragment 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

dash_nested #

syntax: dash_nested 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

dash_path #

syntax: dash_path 1 arg (string);

Stores a single string value.

dash_playlist_length #

syntax: dash_playlist_length 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

deny #

syntax: deny 1 arg;

drop_idle_publisher #

syntax: drop_idle_publisher 1 arg;

exec #

syntax: exec 1+ args;

{ ngx_string("exec_block"), NGX_RTMP_APP_CONF|NGX_CONF_BLOCK|NGX_CONF_NOARGS|NGX_CONF_TAKE1, ngx_rtmp_exec_block, NGX_RTMP_APP_CONF_OFFSET, 0, NULL },

exec_kill_signal #

syntax: exec_kill_signal 1 arg;

exec_options #

syntax: exec_options 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

exec_play #

syntax: exec_play 1+ args;

exec_play_done #

syntax: exec_play_done 1+ args;

exec_publish #

syntax: exec_publish 1+ args;

exec_publish_done #

syntax: exec_publish_done 1+ args;

exec_pull #

syntax: exec_pull 1+ args;

exec_push #

syntax: exec_push 1+ args;

exec_record_done #

syntax: exec_record_done 1+ args;

exec_static #

syntax: exec_static 1+ args;

flv_live #

syntax: flv_live 1 arg (on/off flag);  ·  context: location

Boolean directive — set to "on" or "off".

gop_cache #

syntax: gop_cache 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

gop_max_audio_count #

syntax: gop_max_audio_count 1 arg (integer);

Integer value.

gop_max_frame_count #

syntax: gop_max_frame_count 1 arg (integer);

Integer value.

gop_max_video_count #

syntax: gop_max_video_count 1 arg (integer);

Integer value.

hls #

syntax: hls 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

hls_audio_buffer_size #

syntax: hls_audio_buffer_size 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

hls_base_url #

syntax: hls_base_url 1 arg (string);

Stores a single string value.

hls_cleanup #

syntax: hls_cleanup 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

hls_continuous #

syntax: hls_continuous 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

hls_dir_access #

syntax: hls_dir_access 1 arg;

hls_fragment #

syntax: hls_fragment 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_fragment_naming #

syntax: hls_fragment_naming 1 arg (enum);

Pick one of an enumerated set of values.

hls_fragment_naming_granularity #

syntax: hls_fragment_naming_granularity 1 arg (integer);

Integer value.

hls_fragment_slicing #

syntax: hls_fragment_slicing 1 arg (enum);

Pick one of an enumerated set of values.

hls_fragments_per_key #

syntax: hls_fragments_per_key 1 arg (integer);

Integer value.

hls_key_path #

syntax: hls_key_path 1 arg (string);

Stores a single string value.

hls_key_url #

syntax: hls_key_url 1 arg (string);

Stores a single string value.

hls_keys #

syntax: hls_keys 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

hls_max_audio_delay #

syntax: hls_max_audio_delay 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_max_fragment #

syntax: hls_max_fragment 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_muxdelay #

syntax: hls_muxdelay 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_nested #

syntax: hls_nested 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

hls_nested_index_filename #

syntax: hls_nested_index_filename 1 arg (string);

Stores a single string value.

hls_path #

syntax: hls_path 1 arg (string);

Stores a single string value.

hls_playlist_length #

syntax: hls_playlist_length 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_sync #

syntax: hls_sync 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_type #

syntax: hls_type 1 arg (enum);

Pick one of an enumerated set of values.

hls_variant #

syntax: hls_variant 1+ args;

idle_streams #

syntax: idle_streams 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

interleave #

syntax: interleave 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

listen #

syntax: listen 1+ args;

live #

syntax: live 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

log_format #

syntax: log_format 2+ args;

log_interval #

syntax: log_interval 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

log_size #

syntax: log_size 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

max_connections #

syntax: max_connections 1 arg (integer);

Integer value.

max_message #

syntax: max_message 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

max_streams #

syntax: max_streams 1 arg (integer);

Integer value.

merge_slashes #

syntax: merge_slashes on | off (on/off flag);

Boolean directive — set to "on" or "off".

meta #

syntax: meta 1 arg (enum);

Pick one of an enumerated set of values.

netcall_buffer #

syntax: netcall_buffer 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

netcall_timeout #

syntax: netcall_timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

notify_method #

syntax: notify_method 1 arg;

notify_no_resolve #

syntax: notify_no_resolve 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

notify_relay_redirect #

syntax: notify_relay_redirect 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

notify_update_strict #

syntax: notify_update_strict 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

notify_update_timeout #

syntax: notify_update_timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

on_connect #

syntax: on_connect 1 arg;

on_disconnect #

syntax: on_disconnect 1 arg;

on_done #

syntax: on_done 1 arg;

on_play #

syntax: on_play 1 arg;

on_play_done #

syntax: on_play_done 1 arg;

on_publish #

syntax: on_publish 1 arg;

on_publish_done #

syntax: on_publish_done 1 arg;

on_record_done #

syntax: on_record_done 1 arg;

on_update #

syntax: on_update 1 arg;

out_cork #

syntax: out_cork 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

out_queue #

syntax: out_queue 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

ping #

syntax: ping 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

ping_timeout #

syntax: ping_timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

play #

syntax: play 1+ args;

play_local_path #

syntax: play_local_path 1 arg (string);

Stores a single string value.

play_restart #

syntax: play_restart 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

play_temp_path #

syntax: play_temp_path 1 arg (string);

Stores a single string value.

play_time_fix #

syntax: play_time_fix 1 arg (on/off flag);

time fixes are needed for flash clients

publish_notify #

syntax: publish_notify 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

publish_time_fix #

syntax: publish_time_fix 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

pull #

syntax: pull 1+ args;

pull_reconnect #

syntax: pull_reconnect 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

push #

syntax: push 1+ args;

push_reconnect #

syntax: push_reconnect 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

record #

syntax: record 1+ args (bitmask);

Bitmask — combine several keywords.

record_append #

syntax: record_append 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

record_interval #

syntax: record_interval 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

record_lock #

syntax: record_lock 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

record_max_frames #

syntax: record_max_frames 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

record_max_size #

syntax: record_max_size 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

record_notify #

syntax: record_notify 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

record_path #

syntax: record_path 1 arg (string);

Stores a single string value.

record_suffix #

syntax: record_suffix 1 arg (string);

Stores a single string value.

record_unique #

syntax: record_unique 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

recorder #

syntax: recorder 1 arg;

relay_buffer #

syntax: relay_buffer 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

resolver #

syntax: resolver 1+ args;

resolver_timeout #

syntax: resolver_timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

respawn #

syntax: respawn 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

respawn_timeout #

syntax: respawn_timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

rtmp #

syntax: rtmp no args;  ·  context: main

The appname is used to match an application block in rtmp block (see below for details).

rtmp_auto_push #

syntax: rtmp_auto_push 1 arg (on/off flag);  ·  context: main

Boolean directive — set to "on" or "off".

rtmp_auto_push_reconnect #

syntax: rtmp_auto_push_reconnect 1 arg (duration in ms);  ·  context: main

Duration in milliseconds; accepts ms / s / m suffixes.

rtmp_control #

syntax: rtmp_control 1+ args;  ·  context: http, server, location

rtmp_socket_dir #

syntax: rtmp_socket_dir 1 arg (string);  ·  context: main

Stores a single string value.

rtmp_stat #

syntax: rtmp_stat 1+ args;  ·  context: http, server, location

rtmp_stat_format #

syntax: rtmp_stat_format 1 arg;  ·  context: http, server, location

rtmp_stat_stylesheet #

syntax: rtmp_stat_stylesheet 1 arg (string);  ·  context: http, server, location

Stores a single string value.

send_lowat #

syntax: send_lowat 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

send_timeout #

syntax: send_timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

server #

syntax: server no args;

The value of app (appname) is used to match an application block, but if the requested app appears in several server blocks and those blocks have the same address and port configuration, host name matches server_name directive will be additionally used to identify the requested application block, otherwise the first one is matched.

server_name #

syntax: server_name 1+ args;

The value of app (appname) is used to match an application block, but if the requested app appears in several server blocks and those blocks have the same address and port configuration, host name matches server_name directive will be additionally used to identify the requested application block, otherwise the first one is matched.

session_relay #

syntax: session_relay 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

so_keepalive #

syntax: so_keepalive on | off (on/off flag);

Boolean directive — set to "on" or "off".

stream_buckets #

syntax: stream_buckets 1 arg (integer);

Integer value.

sync #

syntax: sync 1 arg;

tcp_nodelay #

syntax: tcp_nodelay on | off (on/off flag);

Boolean directive — set to "on" or "off".

tcp_nopush #

syntax: tcp_nopush on | off (on/off flag);

Boolean directive — set to "on" or "off".

timeout #

syntax: timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

wait_key #

syntax: wait_key 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

wait_video #

syntax: wait_video 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

Example

worker_processes  1;

error_log  logs/error.log debug;

events {
    worker_connections  1024;
}

rtmp {
    server {
        listen 1935;

        application myapp {
            live on;

            #record keyframes;
            #record_path /tmp;
            #record_max_size 128K;
            #record_interval 30s;
            #record_suffix .this.is.flv;

            #on_publish http://localhost:8080/publish;
            #on_play http://localhost:8080/play;
            #on_record_done http://localhost:8080/record_done;
        }
    }
}

http {
    server {
        listen      8080;

        location /stat {
            rtmp_stat all;
            rtmp_stat_stylesheet stat.xsl;
        }

        location /stat.xsl {
            root /path/to/nginx-rtmp-module/;
        }

        location /control {
            rtmp_control all;
        }

        #location /publish {
        #    return 201;
        #}

        #location /play {
        #    return 202;
        #}

        #location /record_done {
        #    return 203;
        #}

        location /rtmp-publisher {
            root /path/to/nginx-rtmp-module/test;
        }

        location / {
            root /path/to/nginx-rtmp-module/test/www;
        }
    }
}

↑ back to index

This is a module that is distributed with tengine which is a distribution of Nginx that is used by the e-commerce/auction site Taobao.com. This distribution contains some modules that are new on the Nginx scene. The ngx_http_footer_filter module is one of them.

Source: upstream source

Directives

footer #

syntax: footer 1 arg;  ·  context: http, server, location

This module implements a body filter that adds a given string to the page footer.

footer_types #

syntax: footer_types 1+ args;  ·  context: http, server, location

This string can have variables embedded. <br/> <br/> footer_types MIME types default: footer_types: text/html context: http, server, location Defines the MIME types of the files where the footer will be included. ## Installation 1.

Example

location / {
    footer        "<hr><p>Served by nginx — $hostname</p>";
    footer_types  text/html;
}

↑ back to index

http-form-input #

form-input-nginx-module – NGINX module that reads HTTP POST and PUT request body encoded in "application/x-www-form-urlencoded" and parses the arguments into nginx variables.

Source: upstream source

Directives

set_form_input #

syntax: set_form_input 1 arg;  ·  context: http, server, location

set_form_input_multi #

syntax: set_form_input_multi 1 arg;  ·  context: http, server, location

Example

#nginx.conf

location /foo {
    # ensure client_max_body_size == client_body_buffer_size
    client_max_body_size 100k;
    client_body_buffer_size 100k;

    set_form_input $data;    # read "data" field into $data
    set_form_input $foo foo; # read "foo" field into $foo
}

location /bar {
    # ensure client_max_body_size == client_body_buffer_size
    client_max_body_size 1m;
    client_body_buffer_size 1m;

    set_form_input_multi $data; # read all "data" field into $data
    set_form_input_multi $foo data; # read all "data" field into $foo

    array_join ' ' $data; # now $data is an string
    array_join ' ' $foo;  # now $foo is an string
}

↑ back to index

http-geoip2 #

ngx_http_geoip2_module – creates variables with values from the maxmind geoip2 databases based on the client IP (default) or from a specific variable (supports both IPv4 and IPv6)

Source: upstream source

Directives

geoip2 #

syntax: geoip2 1 arg;  ·  context: http

geoip2_proxy #

syntax: geoip2_proxy 1 arg;  ·  context: http

geoip2_proxy_recursive #

syntax: geoip2_proxy_recursive on | off (on/off flag);  ·  context: http

Boolean directive — set to "on" or "off".

Example

http {
    ...
    geoip2 /etc/maxmind-country.mmdb {
        auto_reload 5m;
        $geoip2_metadata_country_build metadata build_epoch;
        $geoip2_data_country_code default=US source=$variable_with_ip country iso_code;
        $geoip2_data_country_name country names en;
    }

    geoip2 /etc/maxmind-city.mmdb {
        $geoip2_data_city_name default=London city names en;
    }
    ....

    fastcgi_param COUNTRY_CODE $geoip2_data_country_code;
    fastcgi_param COUNTRY_NAME $geoip2_data_country_name;
    fastcgi_param CITY_NAME    $geoip2_data_city_name;
    ....
}

stream {
    ...
    geoip2 /etc/maxmind-country.mmdb {
        $geoip2_data_country_code default=US source=$remote_addr country iso_code;
    }
    ...
}

↑ back to index

http-headers-more-filter #

Adds full control over response and request headers — set, append, remove or rewrite headers per response status code, far beyond what add_header / proxy_set_header can express.

Source: upstream source

Directives

more_clear_headers #

syntax: more_clear_headers 1+ args;  ·  context: http, server, location, location-if

more_clear_input_headers #

syntax: more_clear_input_headers 1+ args;  ·  context: http, server, location, location-if

more_set_headers #

syntax: more_set_headers 1+ args;  ·  context: http, server, location, location-if

more_set_input_headers #

syntax: more_set_input_headers 1+ args;  ·  context: http, server, location, location-if

Example

    location /index.html {
        more_clear_input_headers "Range*" ;
        more_clear_input_headers "Content-Range*" ;

        more_set_input_headers 'Range: bytes=1-5';
        more_set_headers  'Content-Range: bytes 1-5/1000';
    }

↑ back to index

Nginx HMAC Secure Link Module

Source: upstream source

Directives

secure_link_hmac #

syntax: secure_link_hmac 1 arg;  ·  context: http, server, location

Specifies the variable expression whose evaluated value must follow the format <token>,<timestamp>[,<expires>]. **The field separator is always a comma and is required between each field.** The comma is hardcoded in the module parser; no other separator is supported here.

secure_link_hmac_algorithm #

syntax: secure_link_hmac_algorithm 1 arg (string);  ·  default: sha256  ·  context: http, server, location

The OpenSSL digest name used for the HMAC. Embedded Variables ——————

secure_link_hmac_message #

syntax: secure_link_hmac_message 1 arg;  ·  context: http, server, location

The message whose HMAC is to be verified. Must match exactly what the client used when computing the token. Typically includes the URI and the timestamp so that tokens are URL-specific and time-bound. **The separator between fields in the message is freely chosen by the operator and may be any byte or sequence of bytes** — pipe (|), colon

secure_link_hmac_secret #

syntax: secure_link_hmac_secret 1 arg;  ·  context: http, server, location

The HMAC secret key. Keep this out of version control.

Example

location ^~ /files/ {
    # The three comma-separated fields: token, timestamp, expires (seconds)
    secure_link_hmac "$arg_st,$arg_ts,$arg_e";

    # HMAC secret key
    secure_link_hmac_secret "my_secret_key";

    # The message that was signed: URI + timestamp + expiry
    secure_link_hmac_message "$uri|$arg_ts|$arg_e";

    # Hash algorithm
    secure_link_hmac_algorithm sha256;

    # In production, do not reveal whether the token was wrong or expired.
    # $secure_link_hmac == "1" → valid and not expired
    # $secure_link_hmac == "0" → valid but expired
    # $secure_link_hmac unset  → invalid / malformed
    if ($secure_link_hmac != "1") {
        return 403;
    }

    rewrite ^/files/(.*)$ /files/$1 break;
}

↑ back to index

http-iconv #

Character-set conversion filter — re-encode response bodies between arbitrary charsets (e.g. GBK ↔ UTF-8) via libiconv at the filter stage.

Source: upstream source

Directives

iconv_buffer_size #

syntax: iconv_buffer_size 1 arg (size (k/m/g));  ·  context: location

Size in bytes; accepts k / m / g suffixes.

iconv_filter #

syntax: iconv_filter 2 args;  ·  context: location

set_iconv #

syntax: set_iconv 4 args;  ·  context: location

Example

    location /foo {
        iconv_filter from=utf-8 to=gbk;
        iconv_buffer_size 10;
        echo '106,纪梵希 蜜粉,8,4.5,62.5%
107,时空胶囊,8,3.2857142857143,42.86%
108,雅顿 vc 美白 胶囊,8,7,14.29%
109,水磁场,8,5,14.29%
110,GEL,8,1,100%
111,雅顿 润唇膏 正品,8,8,20%
112,玫瑰面膜,8,1.5,87.5%
113,露得清 祛痘,8,5.1428571428571,42.86%
114,美白水,8,4.75,50%
115,ë,8,1.875,87.5%
116,大米粉,8,1.25,75%
350,薇姿油脂调护洁面啫喱,2,1,100%
475,啫喱 屈臣氏,1,1,100%
569,洗面奶啫喱,1,1,100%';
    }

↑ back to index

http-internal-redirect #

ngx_http_internal_redirect_module allows making an internal redirect. In contrast to rewriting URIs, the redirection is made after rewrite phase. Currently supported request phases are preaccess, access, precontent and content, allowing it to be used with many nginx official or third-party modules.

Source: upstream source

Directives

internal_redirect #

syntax: internal_redirect [-i] pattern replacement [phase=<phase>] [flag=<flag>] [if=<condition> | if!=<condition>]  ·  default: -  ·  context: http, server, location

The optional -i parameter specifies that a case-insensitive regular expression match should be performed. The optional flag= parameter is used for additional actions after evaluating the rule. The value of this parameter can be one of: stops processing the current set of rules at this phase, and immediately executes an internal redirection;

Example

server {
    listen 127.0.0.1:80;
    server_name localhost;

    location /old {
        internal_redirect -i ^/old(.+) /new$1 phase=preaccess;
    }

    location /new {
        return 200 'current uri is: $uri';
    }
}

↑ back to index

http-js-challenge #

Simple javascript proof-of-work based access for Nginx with virtually no overhead.

Source: upstream source

Directives

js_challenge #

syntax: js_challenge on | off (on/off flag);  ·  context: server, location, server-if, location-if

Boolean directive — set to "on" or "off".

js_challenge_bucket_duration #

syntax: js_challenge_bucket_duration 1 arg (integer);  ·  context: server, location

DEFAULT: "Verifying your browser…" * js_challenge_bucket_duration time Interval to prompt js challenge, in seconds.

js_challenge_html #

syntax: js_challenge_html 1 arg (string);  ·  context: server, location

DEFAULT: "changeme" js_challenge_html "/path/to/file.html" Path to html file to be inserted in the <body> tag of the interstitial page js_challenge_title "title" Will be inserted in the <title> tag of the interstitial page.

js_challenge_secret #

syntax: js_challenge_secret 1 arg (string);  ·  context: server, location

Stores a single string value.

js_challenge_title #

syntax: js_challenge_title 1 arg (string);  ·  context: server, location

DEFAULT: "changeme" js_challenge_html "/path/to/file.html" Path to html file to be inserted in the <body> tag of the interstitial page js_challenge_title "title" Will be inserted in the <title> tag of the interstitial page.

Example

server {
    js_challenge on;
    js_challenge_secret "change me!";
    js_challenge_html /path/to/body.html;
    js_challenge_bucket_duration 3600;
    js_challenge_title "Verifying your browser...";

    location /static {
        js_challenge off;
        alias /static_files/;
    }

    location /sensitive {
        js_challenge_bucket_duration 600;
        #...
    }

    #...
}

↑ back to index

http-keyval #

nginx-keyval is a key-value store dynamic module for nginx. It was developed inspired by the commercial version of nginx's ngx_http_keyval_module.

Source: upstream source

Directives

keyval #

syntax: keyval 3 args;  ·  context: http

Define a variable from key-value pairs

keyval_zone #

syntax: keyval_zone 1+ args;  ·  context: http

Define a shared memory zone

keyval_zone_redis #

syntax: keyval_zone_redis 1+ args;  ·  context: http

Define a Redis zone

Example

# OpenID Connect configuration
#
# Each map block allows multiple values so that multiple IdPs can be supported,
# the $host variable is used as the default input parameter but can be changed.
#
map $host $oidc_authz_endpoint {
    default https://accounts.google.com/o/oauth2/v2/auth;
}

map $host $oidc_authz_extra_args {
    # Extra arguments to include in the request to the IdP's authorization
    # endpoint.
    # Some IdPs provide extended capabilities controlled by extra arguments,
    # for example Keycloak can select an IdP to delegate to via the
    # "kc_idp_hint" argument.
    # Arguments must be expressed as query string parameters and URL-encoded
    # if required.
    default "";
    #www.example.com "kc_idp_hint=another_provider"
}

map $host $oidc_token_endpoint {
    default https://oauth2.googleapis.com/token;
}

map $host $oidc_jwt_keyfile {
    default https://www.googleapis.com/oauth2/v3/certs;
}

map $host $oidc_client {
    default "CLIENT_ID";
}

map $host $oidc_pkce_enable {
    default 0;
}

map $host $oidc_client_secret {
    default "CLIENT_SECRET";
}

map $host $oidc_scopes {
    default "openid+email";
}

map $host $oidc_logout_redirect {
    # Where to send browser after requesting /logout location. This can be
    # replaced with a custom logout page, or complete URL.
    default "/_logout"; # Built-in, simple logout page
}

map $host $oidc_hmac_key {
    # This should be unique for every NGINX instance/cluster
    default dtrqidtoA9HdV3Odq2wxIhYy;
}

map $host $zone_sync_leeway {
    # Specifies the maximum timeout for synchronizing ID tokens between cluster
    # nodes when you use shared memory zone content sync. This option is only
    # recommended for scenarios where cluster nodes can randomly process
    # requests from user agents and there may be a situation where node "A"
    # successfully received a token, and node "B" receives the next request in
    # less than zone_sync_interval.
    default 0; # Time in milliseconds, e.g. (zone_sync_interval * 2 * 1000)
}

map $proto $oidc_cookie_flags {
    http  "Path=/; SameSite=lax;"; # For HTTP/plaintext testing
    https "Path=/; SameSite=lax; HttpOnly; Secure;"; # Production recommendation
}

map $http_x_forwarded_port $redirect_base {
    ""      $proto://$host:$server_port;
    default $proto://$host:$http_x_forwarded_port;
}

map $http_x_forwarded_proto $proto {
    ""
…

↑ back to index

http-length-hiding-filter #

1. Disabling HTTP compression 2. Separating secrets from user input 3. Randomizing secrets per request 4. Masking secrets (effectively randomizing by XORing with a random secret per request) 5. Protecting vulnerable pages with CSRF 6. Length hiding (by adding random number of bytes to the responses) 7. Rate-limiting th

Source: upstream source

Directives

length_hiding #

syntax: length_hiding on | off  ·  default: off  ·  context: http, server, location, if in location

Enables or disables adding random generated HTML comment.

length_hiding_max #

syntax: length_hiding_max size  ·  default: 2048  ·  context: http, server, location

Sets maximum length of random generated string used in HTML comment. The size should be within a range from 256 and 2048.

length_hiding_types #

syntax: length_hiding_types <mime_type> [..]  ·  default: text/html  ·  context: http, server, location, if in location

Enables adding random generated HTML comment to responses of the specified MIME types in addition to text/html. The special value * matches any MIME type.

Example

server {
    listen       443 default_server deferred ssl http2;
    server_name  example.com;
    length_hiding_max 1024;

    location /hiding {
        length_hiding on;
    }
}

↑ back to index

http-let #

Adds support for arithmetic operations to NGINX config.

Source: upstream source

Directives

let #

syntax: let 1+ args;  ·  context: location

—————- NGINX let module —————- Adds support for arithmetic operations to NGINX config.

Example


#user  nobody;
worker_processes  1;

error_log  logs/error.log debug_http;
#error_log  logs/error.log;
#error_log  logs/error.log  notice;
#error_log  logs/error.log  info;

#pid        logs/nginx.pid;


events {
    worker_connections  1024;
}


http {
    include       mime.types;
    default_type  application/octet-stream;

    #log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
    #                  '$status $body_bytes_sent "$http_referer" '
    #                  '"$http_user_agent" "$http_x_forwarded_for"';

    #access_log  logs/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    #keepalive_timeout  0;
    keepalive_timeout  65;

    #gzip  on;

    server {
        listen       8181;
        server_name  localhost;

        #charset koi8-r;

        #access_log  logs/host.access.log  main;

        location / {
            root   html;
            index  index.html index.htm;
        }

        location ~ /let/(?P<uid>.*) {
            let $letresult 1 + 2 * $uid;
            rewrite ^/let/.*$ /let-result/$letresult redirect;
        }


# proxy the PHP scripts to Apache listening on 127.0.0.1:80
#
#location ~ \.php$ {
#    proxy_pass   http://127.0.0.1;
#}

# pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
#
#location ~ \.php$ {
#    root           html;
#    fastcgi_pass   127.0.0.1:9000;
#    fastcgi_index  index.php;
#    fastcgi_param  SCRIPT_FILENAME  /scripts$fastcgi_script_name;
#    include        fastcgi_params;
#}

# deny access to .htaccess files, if Apache's document root
# concurs with nginx's one
#
#location ~ /\.ht {
#    deny  all;
#}
		}


    # another virtual host using mix of IP-, name-, and port-based configuration
    #
    #server {
    #    listen       8000;
    #    listen       somename:8080;
    #    server_name  somename  alias  another.alias;

    #    location / {
    #        root   html;
    #        index  index.html index.htm;
    #    }
    #}


    # HTTPS server
    #
    #server {
    #    listen       443;
    #    server_name  localhost;

    #    ssl                  on;
    #    ssl_certificate      cert.pem;
    #    ssl_certificate_key  cert.key;

    #    ssl_session_timeout  5m;

    #    ssl_protocols  SSLv2 SSLv3 TLSv1;
    #    ssl_ciphers  HIGH:!aNULL:!MD5;
    #    ssl_prefer_server_ciphers   on;

    #    location / {
    #        ro
…

↑ back to index

http-limit-traffic-rate #

Nginx directive limit_rate could limit connection's speed, and limit_conn could limit connection number by given variable. If the client is a browser, it only open one connection to the server. The speed will be limited to limit_rate, unless the client is a multi-thread download tool.

Source: upstream source

Directives

limit_traffic_rate #

syntax: limit_traffic_rate 2 args;  ·  context: http, server, location

limit_traffic_rate module ========================= Notes —– Nginx directive limit_rate could limit connection's speed, and limit_conn could limit connection number by given variable.

limit_traffic_rate_zone #

syntax: limit_traffic_rate_zone 3 args;  ·  context: http

Example

http {
    #limit_traffic_rate_zone   rate $request_uri 32m;
    limit_traffic_rate_zone   rate $remote_addr 32m;

    server {
        location /download/ {
            limit_traffic_rate  rate 20k;
        }
    }
}

↑ back to index

http-log-var-set #

ngx_http_log_var_set_module allows setting the variable to the given value before access log writing.

Source: upstream source

Directives

log_var_set #

syntax: log_var_set $variable value [if=condition];  ·  default: -  ·  context: http, server, location

Sets the request variable to the given value before access log writing. The value may contain variables from request or response, such as $upstream_http_*. These directives are inherited from the previous configuration level only when there is no directive for the same variable defined at the current level.

Example

log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    '"$log_field1" "$log_field2"';
access_log /spool/logs/nginx-access.log;

server {
    listen 127.0.0.1:80;
    server_name localhost;

    location / {
        log_var_set $log_field1 $upstream_http_custom_header1;
        log_var_set $log_field2 $upstream_http_custom_header2;
        proxy_pass http://example.upstream.com;
    }
}

↑ back to index

http-loop-detect #

ngx_http_loop_detect_module allows NGINX to use the CDN-Loop header to prevent request loops.

Source: upstream source

Directives

loop_detect #

syntax: loop_detect on | off;  ·  default: loop_detect off;  ·  context: http, server, location

Enables or disables the loop detection for the current scope. When enabled, the module checks the CDN-Loop header to track the number of hops and blocks requests exceeding the allowed limit.

loop_detect_cdn_id #

syntax: loop_detect_cdn_id string;  ·  default: loop_detect_cdn_id openresty;  ·  context: http, server, location

Sets the unique identifier for your clusters. This identifier is used to parse and track loops in the CDN-Loop header.

loop_detect_max_allow_loops #

syntax: loop_detect_max_allow_loops number;  ·  default: loop_detect_max_allow_loops 10;  ·  context: http, server, location

Sets the maximum number of allowed loops before blocking the request. The number must be greater than 0.

loop_detect_status #

syntax: loop_detect_status code;  ·  default: loop_detect_status 508;  ·  context: http, server, location

Sets the HTTP status code returned when a request exceeds the allowed loop limit. The code must be between 400 and 599 (client or server errors).

Example

http {
    # Enable the module in a location block
    loop_detect on;
    loop_detect_cdn_id my_cdn_id;
    loop_detect_status 508;
    loop_detect_max_allow_loops 10;

    server {
        listen 80;
        server_name example.com;
        location / {
            proxy_set_header CDN-Loop $loop_detect_proxy_add_cdn_loop;
            proxy_pass http://example.upstream.com;
        }
    }
}

↑ back to index

http-lua #

OpenResty Lua module — embed full Lua/LuaJIT scripting into nginx for request handling, access control, traffic shaping, dynamic routing and almost anything else you can imagine.

Source: upstream source

Directives

access_by_lua #

syntax: access_by_lua 1 arg;  ·  context: http, server, location, location-if

access_by_lua "<inline script>"

access_by_lua_block #

syntax: access_by_lua_block no args;  ·  context: http, server, location, location-if

access_by_lua_block { <inline script> }

access_by_lua_file #

syntax: access_by_lua_file 1 arg;  ·  context: http, server, location, location-if

access_by_lua_no_postpone #

syntax: access_by_lua_no_postpone on | off (on/off flag);  ·  context: http

Boolean directive — set to "on" or "off".

balancer_by_lua_block #

syntax: balancer_by_lua_block no args;  ·  context: upstream

balancer_by_lua_file #

syntax: balancer_by_lua_file 1 arg;  ·  context: upstream

balancer_keepalive #

syntax: balancer_keepalive 1 arg;  ·  context: upstream

body_filter_by_lua #

syntax: body_filter_by_lua 1 arg;  ·  context: http, server, location, location-if

body_filter_by_lua_block #

syntax: body_filter_by_lua_block no args;  ·  context: http, server, location, location-if

body_filter_by_lua_block { <inline script> }

body_filter_by_lua_file #

syntax: body_filter_by_lua_file 1 arg;  ·  context: http, server, location, location-if

content_by_lua #

syntax: content_by_lua 1 arg;  ·  context: location, location-if

content_by_lua "<inline script>"

content_by_lua_block #

syntax: content_by_lua_block no args;  ·  context: location, location-if

content_by_lua_block { <inline script> }

content_by_lua_file #

syntax: content_by_lua_file 1 arg;  ·  context: location, location-if

content_by_lua_file rel/or/abs/path/to/script

exit_worker_by_lua_block #

syntax: exit_worker_by_lua_block no args;  ·  context: http

exit_worker_by_lua_file #

syntax: exit_worker_by_lua_file 1 arg;  ·  context: http

header_filter_by_lua #

syntax: header_filter_by_lua 1 arg;  ·  context: http, server, location, location-if

header_filter_by_lua <inline script>

header_filter_by_lua_block #

syntax: header_filter_by_lua_block no args;  ·  context: http, server, location, location-if

header_filter_by_lua_block { <inline script> }

header_filter_by_lua_file #

syntax: header_filter_by_lua_file 1 arg;  ·  context: http, server, location, location-if

init_by_lua #

syntax: init_by_lua 1 arg;  ·  context: http

init_by_lua_block #

syntax: init_by_lua_block no args;  ·  context: http

init_by_lua_file #

syntax: init_by_lua_file 1 arg;  ·  context: http

init_worker_by_lua #

syntax: init_worker_by_lua 1 arg;  ·  context: http

init_worker_by_lua_block #

syntax: init_worker_by_lua_block no args;  ·  context: http

init_worker_by_lua_file #

syntax: init_worker_by_lua_file 1 arg;  ·  context: http

log_by_lua #

syntax: log_by_lua 1 arg;  ·  context: http, server, location, location-if

log_by_lua <inline script>

log_by_lua_block #

syntax: log_by_lua_block no args;  ·  context: http, server, location, location-if

log_by_lua_block { <inline script> }

log_by_lua_file #

syntax: log_by_lua_file 1 arg;  ·  context: http, server, location, location-if

lua_capture_error_log #

syntax: lua_capture_error_log 1 arg;  ·  context: http

lua_check_client_abort #

syntax: lua_check_client_abort on | off (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

lua_code_cache #

syntax: lua_code_cache on | off;  ·  context: http, server, location, location-if

lua_fake_shm #

syntax: lua_fake_shm 2 args;  ·  context: http

lua_http10_buffering #

syntax: lua_http10_buffering on | off (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

lua_load_resty_core #

syntax: lua_load_resty_core on | off;  ·  context: http

lua_malloc_trim #

syntax: lua_malloc_trim 1 arg;  ·  context: http

NGX_HTTP_SSL

lua_max_pending_timers #

syntax: lua_max_pending_timers 1 arg (integer);  ·  context: http

Integer value.

lua_max_running_timers #

syntax: lua_max_running_timers 1 arg (integer);  ·  context: http

Integer value.

lua_need_request_body #

syntax: lua_need_request_body on | off (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

lua_package_cpath #

syntax: lua_package_cpath 1 arg;  ·  context: http

lua_package_path #

syntax: lua_package_path 1 arg;  ·  context: http

lua_regex_cache_max_entries #

syntax: lua_regex_cache_max_entries 1 arg;  ·  context: http

lua_regex_match_limit #

syntax: lua_regex_match_limit 1 arg;  ·  context: http

lua_sa_restart #

syntax: lua_sa_restart on | off (on/off flag);  ·  context: http

Boolean directive — set to "on" or "off".

lua_shared_dict #

syntax: lua_shared_dict 2 args;  ·  context: http

lua_socket_buffer_size #

syntax: lua_socket_buffer_size 1 arg (size (k/m/g));  ·  context: http, server, location, location-if

Size in bytes; accepts k / m / g suffixes.

lua_socket_connect_timeout #

syntax: lua_socket_connect_timeout 1 arg (duration in ms);  ·  context: http, server, location, location-if

Duration in milliseconds; accepts ms / s / m suffixes.

lua_socket_keepalive_timeout #

syntax: lua_socket_keepalive_timeout 1 arg (duration in ms);  ·  context: http, server, location, location-if

Duration in milliseconds; accepts ms / s / m suffixes.

lua_socket_log_errors #

syntax: lua_socket_log_errors on | off (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

lua_socket_pool_size #

syntax: lua_socket_pool_size 1 arg (integer);  ·  context: http, server, location, location-if

Integer value.

lua_socket_read_timeout #

syntax: lua_socket_read_timeout 1 arg (duration in ms);  ·  context: http, server, location, location-if

Duration in milliseconds; accepts ms / s / m suffixes.

lua_socket_send_lowat #

syntax: lua_socket_send_lowat 1 arg (size (k/m/g));  ·  context: http, server, location, location-if

Size in bytes; accepts k / m / g suffixes.

lua_socket_send_timeout #

syntax: lua_socket_send_timeout 1 arg (duration in ms);  ·  context: http, server, location, location-if

Duration in milliseconds; accepts ms / s / m suffixes.

lua_ssl_certificate #

syntax: lua_ssl_certificate 1 arg (list of strings);  ·  context: http, server, location

Appends a string to a list; may be specified multiple times.

lua_ssl_certificate_key #

syntax: lua_ssl_certificate_key 1 arg (list of strings);  ·  context: http, server, location

Appends a string to a list; may be specified multiple times.

lua_ssl_ciphers #

syntax: lua_ssl_ciphers 1 arg (string);  ·  context: http, server, location

Stores a single string value.

lua_ssl_conf_command #

syntax: lua_ssl_conf_command 2 args (key value pair);  ·  context: http, server, location

Stores a key/value pair.

lua_ssl_crl #

syntax: lua_ssl_crl 1 arg (string);  ·  context: http, server, location

Stores a single string value.

lua_ssl_key_log #

syntax: lua_ssl_key_log 1 arg (string);  ·  context: http, server, location

Stores a single string value.

lua_ssl_protocols #

syntax: lua_ssl_protocols 1+ args (bitmask);  ·  context: http, server, location

Bitmask — combine several keywords.

lua_ssl_trusted_certificate #

syntax: lua_ssl_trusted_certificate 1 arg (string);  ·  context: http, server, location

Stores a single string value.

lua_ssl_verify_depth #

syntax: lua_ssl_verify_depth 1 arg (integer);  ·  context: http, server, location

Integer value.

lua_thread_cache_max_entries #

syntax: lua_thread_cache_max_entries 1 arg (integer);  ·  context: http

Integer value.

lua_transform_underscores_in_response_headers #

syntax: lua_transform_underscores_in_response_headers on | off (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

lua_upstream_skip_openssl_default_verify #

syntax: lua_upstream_skip_openssl_default_verify on | off (on/off flag);  ·  context: location, location-if

Boolean directive — set to "on" or "off".

lua_use_default_type #

syntax: lua_use_default_type on | off (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

lua_worker_thread_vm_pool_size #

syntax: lua_worker_thread_vm_pool_size 1 arg (integer);  ·  context: http

Integer value.

precontent_by_lua_block #

syntax: precontent_by_lua_block no args;  ·  context: http, server, location, location-if

precontent_by_lua_block { <inline script> }

precontent_by_lua_file #

syntax: precontent_by_lua_file 1 arg;  ·  context: http, server, location, location-if

precontent_by_file filename;

precontent_by_lua_no_postpone #

syntax: precontent_by_lua_no_postpone on | off (on/off flag);  ·  context: http

Boolean directive — set to "on" or "off".

proxy_ssl_certificate_by_lua_block #

syntax: proxy_ssl_certificate_by_lua_block no args;  ·  context: location, location-if

same context as proxy_pass directive

proxy_ssl_certificate_by_lua_file #

syntax: proxy_ssl_certificate_by_lua_file 1 arg;  ·  context: location, location-if

proxy_ssl_verify_by_lua_block #

syntax: proxy_ssl_verify_by_lua_block no args;  ·  context: location, location-if

same context as proxy_pass directive

proxy_ssl_verify_by_lua_file #

syntax: proxy_ssl_verify_by_lua_file 1 arg;  ·  context: location, location-if

rewrite_by_lua #

syntax: rewrite_by_lua 1 arg;  ·  context: http, server, location, location-if

rewrite_by_lua "<inline script>"

rewrite_by_lua_block #

syntax: rewrite_by_lua_block no args;  ·  context: http, server, location, location-if

rewrite_by_lua_block { <inline script> }

rewrite_by_lua_file #

syntax: rewrite_by_lua_file 1 arg;  ·  context: http, server, location, location-if

rewrite_by_lua_no_postpone #

syntax: rewrite_by_lua_no_postpone on | off (on/off flag);  ·  context: http

Boolean directive — set to "on" or "off".

server_rewrite_by_lua_block #

syntax: server_rewrite_by_lua_block no args;  ·  context: http, server

server_rewrite_by_lua_block { <inline script> }

server_rewrite_by_lua_file #

syntax: server_rewrite_by_lua_file 1 arg;  ·  context: http, server

server_rewrite_by_lua_file filename;

set_by_lua #

syntax: set_by_lua 2+ args;  ·  context: server, location, server-if, location-if

set_by_lua $res <inline script> [$arg1 [$arg2 […]]]

set_by_lua_block #

syntax: set_by_lua_block 1 arg;  ·  context: server, location, server-if, location-if

set_by_lua_block $res { inline Lua code }

set_by_lua_file #

syntax: set_by_lua_file 2+ args;  ·  context: server, location, server-if, location-if

set_by_lua_file $res rel/or/abs/path/to/script [$arg1 [$arg2 [..]]]

ssl_certificate_by_lua_block #

syntax: ssl_certificate_by_lua_block no args;  ·  context: http, server

ssl_certificate_by_lua_file #

syntax: ssl_certificate_by_lua_file 1 arg;  ·  context: http, server

ssl_client_hello_by_lua_block #

syntax: ssl_client_hello_by_lua_block no args;  ·  context: http, server

ssl_client_hello_by_lua_file #

syntax: ssl_client_hello_by_lua_file 1 arg;  ·  context: http, server

ssl_session_fetch_by_lua_block #

syntax: ssl_session_fetch_by_lua_block no args;  ·  context: http

ssl_session_fetch_by_lua_file #

syntax: ssl_session_fetch_by_lua_file 1 arg;  ·  context: http

ssl_session_store_by_lua_block #

syntax: ssl_session_store_by_lua_block no args;  ·  context: http

ssl_session_store_by_lua_file #

syntax: ssl_session_store_by_lua_file 1 arg;  ·  context: http

Example

    location = /t {
        set $a '';
        rewrite_by_lua_block {
            local s = ngx.var.a
            s = s .. "}rewrite{\n"
            ngx.var.a = s
        }
        access_by_lua_block {
            local s = ngx.var.a
            s = s .. '}access{\n'
            ngx.var.a = s
        }
        content_by_lua_block {
            local s = ngx.var.a
            s = s .. [[}content{]]
            ngx.say(s)
            ngx.say("glob: ", glob)
        }
        log_by_lua_block {
            print("log by lua running \"}{!\"")
        }
        header_filter_by_lua_block {
            ngx.header["Foo"] = "\"Hello, world\""
            ngx.header["Content-Length"] = nil
        }
        body_filter_by_lua_block {
            local data, eof = ngx.arg[1], ngx.arg[2]
            print("eof = ", eof)
            if eof then
                if not data then
                    data = ""
                end
                data = data .. "}body filter{\n"
                print("data: ", data)
                ngx.arg[1] = data
            end
        }
    }

↑ back to index

http-lua-upstream #

ngx_http_lua_upstream – Nginx C module to expose Lua API to ngx_lua for Nginx upstreams

Source: upstream source

No nginx directives detected.

↑ back to index

http-memc #

Extended memcached client — adds the missing memcached verbs (add, set, replace, append, prepend, delete, flush_all, stats, version) that the bundled memcached_pass module is missing.

Source: upstream source

Directives

memc_buffer_size #

syntax: memc_buffer_size 1 arg (size (k/m/g));  ·  context: http, server, location

Size in bytes; accepts k / m / g suffixes.

memc_cmds_allowed #

syntax: memc_cmds_allowed 1+ args;  ·  context: http, server, location, location-if

memc_connect_timeout #

syntax: memc_connect_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

memc_flags_to_last_modified #

syntax: memc_flags_to_last_modified on | off (on/off flag);  ·  context: location, location-if

Boolean directive — set to "on" or "off".

memc_ignore_client_abort #

syntax: memc_ignore_client_abort on | off (on/off flag);  ·  context: location, location-if

Boolean directive — set to "on" or "off".

memc_next_upstream #

syntax: memc_next_upstream 1+ args (bitmask);  ·  context: http, server, location

Bitmask — combine several keywords.

memc_pass #

syntax: memc_pass 1 arg;  ·  context: location, location-if

memc_read_timeout #

syntax: memc_read_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

memc_send_timeout #

syntax: memc_send_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

memc_upstream_fail_timeout #

syntax: memc_upstream_fail_timeout 1 arg;  ·  context: http, server, location

memc_upstream_max_fails #

syntax: memc_upstream_max_fails 1 arg;  ·  context: http, server, location

Example

    memc_connect_timeout 10ms;
    memc_send_timeout 10ms;
    location /stats {
        set $memc_cmd stats;
        memc_pass 127.0.0.2:12345;
    }

↑ back to index

http-modsecurity #

The ModSecurity-nginx connector — bridges nginx to libmodsecurity v3 so OWASP CRS and custom WAF rules run as a dynamic module.

Source: upstream source

Directives

modsecurity #

syntax: modsecurity on | off (on/off flag);  ·  context: http, server, location

It adds four new directives and they are: modsecurity ———– syntax: modsecurity on | off context: http, server, location default: off Turns on or off ModSecurity functionality.

modsecurity_rules #

syntax: modsecurity_rules 1 arg;  ·  context: http, server, location

It also specifies the key that will be used to authenticate to that server: modsecurity_rules —————– syntax: modsecurity_rules &lt;modsecurity rule&gt; context: http, server, location default: no Allows for the direct inclusion of a ModSecurity rule into the nginx configuration.

modsecurity_rules_file #

syntax: modsecurity_rules_file 1 arg;  ·  context: http, server, location

modsecurity_rules_remote #

syntax: modsecurity_rules_remote 2 args;  ·  context: http, server, location

modsecurity_transaction_id #

syntax: modsecurity_transaction_id 1+ args;  ·  context: http, server, location

The following example is loading rules from a file and injecting specific configurations per directory/alias: modsecurity_transaction_id ————————– syntax: modsecurity_transaction_id string context: http, server, location default: no Allows to pass transaction ID from nginx instead of generating it in the library.

modsecurity_use_error_log #

syntax: modsecurity_use_error_log on | off (on/off flag);  ·  context: http, server, location

String can contain variables. modsecurity_use_error_log ———– syntax: modsecurity_use_error_log on | off context: http, server, location default: on Turns on or off ModSecurity error log functionality. # Contributing As an open source project we invite (and encourage) anyone from the community to contribute to our project.

Example

server {
    modsecurity on;
    location / {
        root /var/www/html;
        modsecurity_rules_file /etc/my_modsecurity_rules.conf;
    }
    location /ops {
        root /var/www/html/opts;
        modsecurity_rules '
          SecRuleEngine On
          SecDebugLog /tmp/modsec_debug.log
          SecDebugLogLevel 9
          SecRuleRemoveById 10
        ';
    }
}

↑ back to index

http-naxsi #

NAXSI is an open-source, low-rules-maintenance web application firewall for nginx — blocks SQL/XSS injections by default-deny pattern matching.

Source: upstream source

No nginx directives detected.

↑ back to index

http-ndk #

Nginx Development Kit (NDK)

Source: upstream source

No nginx directives detected.

↑ back to index

http-pagespeed #

To see ngx_pagespeed in action, with example pages for each of the optimizations, see our <a href="http://ngxpagespeed.com">demonstration site</a>.

Source: upstream source

Directives

pagespeed #

syntax: pagespeed 1 arg;  ·  context: http

!ngx_pagespeed ![Build Status](https://travis-ci.org/apache/incubator-pagespeed-ngx) ngx_pagespeed speeds up your site and reduces page load time by automatically applying web performance best practices to pages and associated assets (CSS, JavaScript, images) without requiring you to modify your existing content or workflow.

Example

pagespeed on;
pagespeed FileCachePath        /var/cache/ngx_pagespeed;
pagespeed RewriteLevel         CoreFilters;
pagespeed EnableFilters         collapse_whitespace,remove_comments;
pagespeed EnableFilters         rewrite_images,recompress_images;

location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+" {
    add_header "" "";
}

↑ back to index

http-postgres #

ngx_postgres is an upstream module that allows nginx to communicate directly with PostgreSQL database.

Source: upstream source

Directives

postgres_connect_timeout #

syntax: postgres_connect_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

postgres_escape #

syntax: postgres_escape 1 arg;  ·  context: http, server, location

This directive can be used more than once within same context. postgres_escape ————— syntax: postgres_escape $escaped [[=]$unescaped] default: none * context: http, server, location Escape and quote $unescaped string.

postgres_keepalive #

syntax: postgres_keepalive 1+ args;  ·  context: upstream

postgres_output #

syntax: postgres_output 1 arg;  ·  context: http, server, location, location-if

postgres_pass #

syntax: postgres_pass 1 arg;  ·  context: location, location-if

Sample configuration #6 ———————– Use GET parameter in SQL query. location /quotes { set_unescape_uri $txt $arg_txt; postgres_escape $txt; postgres_pass database; postgres_query "SELECT * FROM quotes WHERE quote=$txt"; } Required modules (other than ngx_postgres): – ngx_set_misc.

postgres_query #

syntax: postgres_query 1+ args;  ·  context: http, server, location, location-if

Sample configuration #6 ———————– Use GET parameter in SQL query. location /quotes { set_unescape_uri $txt $arg_txt; postgres_escape $txt; postgres_pass database; postgres_query "SELECT * FROM quotes WHERE quote=$txt"; } Required modules (other than ngx_postgres): – ngx_set_misc.

postgres_result_timeout #

syntax: postgres_result_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

postgres_rewrite #

syntax: postgres_rewrite 2+ args;  ·  context: http, server, location, location-if

postgres_server #

syntax: postgres_server 1+ args;  ·  context: upstream

Configuration directives ======================== postgres_server ————— syntax: postgres_server {ip[:portnum]|unix:/socket/dir} [port=portnum] [dbname=dbname] [user=user] [password=pass] default: none * context: upstream Set details about the database server.

postgres_set #

syntax: postgres_set 3 args;  ·  context: http, server, location

Example

    location = /auth {
        internal;
        postgres_escape     $user $remote_user;
        postgres_escape     $pass $remote_passwd;
        postgres_pass       database;
        postgres_query      "select login from users where login=$user and pass=$pass";
        postgres_rewrite    no_rows 403;
        postgres_set        $login 0 0 required;
        postgres_output     none;
    }

    location /test {
        auth_request        /auth;
        auth_request_set    $auth_user $login;
        echo -n             "hi, $auth_user!";
    }

↑ back to index

http-proxy-var-set #

ngx_http_proxy_var_set_module allows setting the variable to the given value during processing of proxy response.

Source: upstream source

Directives

grpc_var_set #

syntax: grpc_var_set 2 args;  ·  context: http, server, location

proxy_var_set #

syntax: proxy_var_set $variable value [if=condition];  ·  default: -  ·  context: http, server, location

Sets the request variable to the given value during processing of proxy response. The value may contain variables from request or response, such as $upstream_http_*. These directives are inherited from the previous configuration level only when there is no directive for the same variable defined at the current level.

Example

server {
    listen 127.0.0.1:80;
    server_name localhost;

    location / {
        set $no_cache "";
        proxy_var_set $no_cache $upstream_http_custom_header1;
        proxy_no_cache $no_cache;
        proxy_pass http://example.upstream.com;
    }
}

↑ back to index

http-push-stream #

Long-polling / EventSource / WebSocket Pub-Sub server — turns nginx into a real-time message broker with channels, statistics and subscriber management.

Source: upstream source

Directives

push_stream_allow_connections_to_events_channel #

syntax: push_stream_allow_connections_to_events_channel 1 arg (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

push_stream_allowed_origins #

syntax: push_stream_allowed_origins 1 arg;  ·  context: http, server, location

push_stream_authorized_channels_only #

syntax: push_stream_authorized_channels_only 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

push_stream_channel_deleted_message_text #

syntax: push_stream_channel_deleted_message_text 1 arg (string);  ·  context: http

Stores a single string value.

push_stream_channel_inactivity_time #

syntax: push_stream_channel_inactivity_time 1 arg (duration in seconds);  ·  context: http

Duration in seconds; accepts s / m / h / d suffixes.

push_stream_channel_info_on_publish #

syntax: push_stream_channel_info_on_publish 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

push_stream_channels_path #

syntax: push_stream_channels_path 1 arg;  ·  context: http, server, location, location-if

Location directives

push_stream_channels_statistics #

syntax: push_stream_channels_statistics no args;  ·  context: location

push_stream_events_channel_id #

syntax: push_stream_events_channel_id 1 arg (string);  ·  context: http

Stores a single string value.

push_stream_footer_template #

syntax: push_stream_footer_template 1 arg (string);  ·  context: http, server, location

Stores a single string value.

push_stream_header_template #

syntax: push_stream_header_template 1 arg (string);  ·  context: http, server, location

Stores a single string value.

push_stream_header_template_file #

syntax: push_stream_header_template_file 1 arg;  ·  context: http, server, location

push_stream_last_event_id #

syntax: push_stream_last_event_id 1 arg;  ·  context: http, server, location, location-if

push_stream_last_received_message_tag #

syntax: push_stream_last_received_message_tag 1 arg;  ·  context: http, server, location, location-if

push_stream_last_received_message_time #

syntax: push_stream_last_received_message_time 1 arg;  ·  context: http, server, location, location-if

push_stream_longpolling_connection_ttl #

syntax: push_stream_longpolling_connection_ttl 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

push_stream_max_channel_id_length #

syntax: push_stream_max_channel_id_length 1 arg (integer);  ·  context: http

Integer value.

push_stream_max_messages_stored_per_channel #

syntax: push_stream_max_messages_stored_per_channel 1 arg (integer);  ·  context: http

Integer value.

push_stream_max_number_of_channels #

syntax: push_stream_max_number_of_channels 1 arg (integer);  ·  context: http

Integer value.

push_stream_max_number_of_wildcard_channels #

syntax: push_stream_max_number_of_wildcard_channels 1 arg (integer);  ·  context: http

Integer value.

push_stream_max_subscribers_per_channel #

syntax: push_stream_max_subscribers_per_channel 1 arg (integer);  ·  context: http

Integer value.

push_stream_message_template #

syntax: push_stream_message_template 1 arg (string);  ·  context: http, server, location

Stores a single string value.

push_stream_message_ttl #

syntax: push_stream_message_ttl 1 arg (duration in seconds);  ·  context: http

Duration in seconds; accepts s / m / h / d suffixes.

push_stream_padding_by_user_agent #

syntax: push_stream_padding_by_user_agent 1 arg (string);  ·  context: http, server, location

Stores a single string value.

push_stream_ping_message_interval #

syntax: push_stream_ping_message_interval 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

push_stream_ping_message_text #

syntax: push_stream_ping_message_text 1 arg (string);  ·  context: http

Stores a single string value.

push_stream_publisher #

syntax: push_stream_publisher no args;  ·  context: location

push_stream_shared_memory_size #

syntax: push_stream_shared_memory_size 1 arg;  ·  context: http

Main directives

push_stream_store_messages #

syntax: push_stream_store_messages 1 arg (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

push_stream_subscriber #

syntax: push_stream_subscriber no args;  ·  context: location

push_stream_subscriber_connection_ttl #

syntax: push_stream_subscriber_connection_ttl 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

push_stream_timeout_with_body #

syntax: push_stream_timeout_with_body 1 arg (on/off flag);  ·  context: http

Boolean directive — set to "on" or "off".

push_stream_user_agent #

syntax: push_stream_user_agent 1 arg;  ·  context: http, server, location

push_stream_websocket_allow_publish #

syntax: push_stream_websocket_allow_publish 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

push_stream_wildcard_channel_max_qtd #

syntax: push_stream_wildcard_channel_max_qtd 1 arg (integer);  ·  context: http, server, location

Integer value.

push_stream_wildcard_channel_prefix #

syntax: push_stream_wildcard_channel_prefix 1 arg (string);  ·  context: http

Stores a single string value.

Example

http {
    push_stream_shared_memory_size  32M;

    server {
        location /pub {
            push_stream_publisher        admin;
            push_stream_channels_path    $arg_id;
        }
        location ~ /sub/(.+) {
            push_stream_subscriber          long-polling;
            push_stream_channels_path       $1;
            push_stream_message_template    "<script>parent.s({~text~});</script>";
        }
    }
}

↑ back to index

http-redis2 #

Streaming non-blocking upstream module for Redis — proxy raw Redis protocol traffic from nginx with full pipelining support, complementing the Lua resty.redis client.

Source: upstream source

Directives

redis2_bind #

syntax: redis2_bind 1 arg;  ·  context: http, server, location

redis2_buffer_size #

syntax: redis2_buffer_size 1 arg (size (k/m/g));  ·  context: http, server, location

Size in bytes; accepts k / m / g suffixes.

redis2_connect_timeout #

syntax: redis2_connect_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

redis2_literal_raw_query #

syntax: redis2_literal_raw_query 1 arg (string);  ·  context: location, location-if

Stores a single string value.

redis2_next_upstream #

syntax: redis2_next_upstream 1+ args (bitmask);  ·  context: http, server, location

Bitmask — combine several keywords.

redis2_pass #

syntax: redis2_pass 1 arg;  ·  context: location, location-if

redis2_query #

syntax: redis2_query 1+ args;  ·  context: location, location-if

redis2_raw_queries #

syntax: redis2_raw_queries 2 args;  ·  context: location, location-if

redis2_raw_query #

syntax: redis2_raw_query 1 arg;  ·  context: location, location-if

redis2_read_timeout #

syntax: redis2_read_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

redis2_send_timeout #

syntax: redis2_send_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

Example

    location /set {
        redis2_query set 'counters::stats::list' '[["mafiaclans.eu", 12], ["picfu.net", 5], ["www.test.com", 0], ["www.ayom.com", 0], ["www.21dezember2012.org", 0], ["the-indie.ch", 0], ["spiele-check.de", 0], ["online-right-now.net", 0], ["google.com", 0]]';

        redis2_pass 127.0.0.1:$TEST_NGINX_REDIS_PORT;
    }

    location /get {
        redis2_raw_query 'get counters::stats::list\r\n';
        redis2_pass 127.0.0.1:$TEST_NGINX_REDIS_PORT;
    }

    location /main2 {
        content_by_lua '
            local res = ngx.location.capture("/set");
            ngx.print(res.body)
            res = ngx.location.capture("/get");
            ngx.print(res.body)
        ';
    }
    location /main {
        # echo_location is buggy...sigh.
        echo_location /set;
        echo_location /get;
    }

↑ back to index

http-rewrite-status-filter #

ngx_http_rewrite_status_filter_module is a filter module used to rewrite response status code.

Source: upstream source

Directives

rewrite_status #

syntax: rewrite_status status [if=condition];  ·  default: -  ·  context: http, server, location

Rewrite response status code.

Example

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location / {
        rewrite_status 404 if=$http_rsp_404_status;
        proxy_pass http://foo.com;
    }
}

↑ back to index

http-security-headers #

This NGINX module adds security headers and removes insecure headers, the right way (c).

Source: upstream source

Directives

security_headers_coep #

syntax: security_headers_coep require-corp | credentialless | unsafe-none | omit  ·  default: omit  ·  context: http, server, location

Controls inclusion and value of Cross-Origin-Embedder-Policy header. This header controls embedding of cross-origin resources. Special omit value will disable sending the header by the module. The default is omit because enabling this header can break sites that load third-party resources (analytics, CDN assets, ads) without proper CORS headers.

security_headers_coop #

syntax: security_headers_coop same-origin | same-origin-allow-popups | unsafe-none | omit  ·  default: omit  ·  context: http, server, location

Controls inclusion and value of Cross-Origin-Opener-Policy header. This header controls window opener relationships across origins. Special omit value will disable sending the header by the module. The default is omit because enabling this header can break popup/window.opener communication patterns. Enable explicitly only if you understand the implications.

security_headers_corp #

syntax: security_headers_corp same-site | same-origin | cross-origin | omit  ·  default: same-site  ·  context: http, server, location

Controls inclusion and value of Cross-Origin-Resource-Policy header. This header controls how your resources can be embedded by other origins. Special omit value will disable sending the header by the module. The default same-site is a safe choice that prevents cross-site embedding while allowing same-site requests.

security_headers_frame #

syntax: security_headers_frame sameorigin | deny | omit  ·  default: sameorigin  ·  context: http, server, location

Controls inclusion and value of X-Frame-Options header. Special omit value will disable sending the header by the module.

security_headers_referrer_policy #

syntax: security_headers_referrer_policy no-referrer | no-referrer-when-downgrade | same-origin | origin  ·  default: strict-origin-when-cross-origin  ·  context: http, server, location

Controls inclusion and value of Referrer-Policy header. Special omit value will disable sending the header by the module.

security_headers_text_types #

syntax: security_headers_text_types 1+ args;  ·  context: http, server, location

security_headers_xss #

syntax: security_headers_xss off | on | block | omit | unset  ·  default: unset  ·  context: http, server, location

Controls X-XSS-Protection header.

Example

    security_headers on;
    security_headers_corp same-origin;
    security_headers_coop same-origin;
    security_headers_coep require-corp;
    location = /hello {
        return 200 "hello world\n";
    }

↑ back to index

http-server-redirect #

The ngx_http_server_redirect_module is a custom nginx module designed to facilitate dynamic server redirection based on configurable rules. It allows users to redirect incoming requests to different servers conditionally.

Source: upstream source

Directives

schedule_redirect #

syntax: schedule_redirect on | off (on/off flag);  ·  context: server

Here is an example: This example redirects requests to newserver.com if the Server-Redirect header has value and value is not 0. ### Directive: schedule_redirect Syntax: schedule_redirect on | off Default: schedule_redirect off Context: server Redirect the current request to another server from the first request path.

server_redirect #

syntax: server_redirect 1 arg;  ·  context: server

This process is internal and no 302 redirection will occur. ## Configuration ### Directive: server_redirect Syntax: server_redirect target_host [if=condition] Default: – Context: server Redirect the current request to another server.

Example

http {
    server {
        listen 80;
        server_name example.com;

        # Redirect if request has 'X-Redirect' header and value is not 0 or empty.
        server_redirect newserver.com if=$http_x_redirect;

        # You can use ngx_http_var_module to generate judgment variables based on conditions.
        # https://git.hanada.info/hanada/ngx_http_var_module
        # var $is_ipv6 if_find $remote_addr :;
        # server_redirect newserver.com if=$is_ipv6;

        # This module takes effect after the real_ip module,
        # Therefore, the real_ip module's directives will take effect on the server before server redirect.
        # real_ip_header x-client-ip;

        location / {
            proxy_pass http://newserver.com;
        }
    }

    server {
        listen 80;
        server_name newserver.com;

        # You can get original host from this variable.
        add_header x-original-host $server_redirect_original_host;

        location / {
            proxy_pass http://upstream.com;
        }
    }
}

↑ back to index

http-set-misc #

Adds string, URL, hash, hex, base32, base64 and time utility set_* directives to nginx variables — the rewrite-by-config Swiss-army knife OpenResty relies on.

Source: upstream source

Directives

set_base32_alphabet #

syntax: set_base32_alphabet 1 arg;  ·  context: http, server, location, server-if, location-if

set_base32_padding #

syntax: set_base32_padding on | off (on/off flag);  ·  context: http, server, location, server-if, location-if

Boolean directive — set to "on" or "off".

set_decode_base32 #

syntax: set_decode_base32 1 arg;  ·  context: http, server, location, server-if, location-if

set_encode_base32 #

syntax: set_encode_base32 1 arg;  ·  context: http, server, location, server-if, location-if

set_formatted_gmt_time #

syntax: set_formatted_gmt_time 2 args;  ·  context: http, server, location, server-if, location-if

set_formatted_local_time #

syntax: set_formatted_local_time 2 args;  ·  context: http, server, location, server-if, location-if

set_hashed_upstream #

syntax: set_hashed_upstream 3 args;  ·  context: http, server, location, server-if, location-if

set_local_today #

syntax: set_local_today 1 arg;  ·  context: http, server, location, server-if, location-if

set_misc_base32_padding #

syntax: set_misc_base32_padding on | off (on/off flag);  ·  context: http, server, location, server-if, location-if

Boolean directive — set to "on" or "off".

Example

    set_base32_padding off;
    set_base32_alphabet "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
    location /bar {
        set $a '"hello, world!\nhiya"';
        set_encode_base32 $a;
        set $b $a;
        set_decode_base32 $b;

        echo $a;
        echo $b;
    }

↑ back to index

http-slowfs-cache #

WARNING! There is no point in using this module when cache is placed on the same speed disk(s) as origin.

Source: upstream source

Directives

slowfs_big_file_size #

syntax: slowfs_big_file_size 1 arg (size (k/m/g));  ·  context: http, server, location

Size in bytes; accepts k / m / g suffixes.

slowfs_cache #

syntax: slowfs_cache on | off;  ·  context: http, server, location

slowfs_cache_key #

syntax: slowfs_cache_key on | off;  ·  context: http, server, location

slowfs_cache_min_uses #

syntax: slowfs_cache_min_uses 1 arg (integer);  ·  context: http, server, location

Integer value.

slowfs_cache_path #

syntax: slowfs_cache_path 2+ args;  ·  context: http

Configuration notes =================== slowfs_cache_path and slowfs_temp_path values should point to the same filesystem, otherwise files will be copied twice.

slowfs_cache_purge #

syntax: slowfs_cache_purge 2 args;  ·  context: location

slowfs_cache_valid #

syntax: slowfs_cache_valid 1+ args;  ·  context: http, server, location

slowfs_temp_path #

syntax: slowfs_temp_path 1 arg (filesystem path);  ·  context: http, server, location

Configuration notes =================== slowfs_cache_path and slowfs_temp_path values should point to the same filesystem, otherwise files will be copied twice.

Example

slowfs_cache_path /var/cache/slowfs levels=1:2 keys_zone=slowfs:10m
                  inactive=1h max_size=2g;

location /slow/ {
    root              /mnt/slow-disk;
    slowfs_cache      slowfs;
    slowfs_cache_key  $uri;
    slowfs_cache_valid 200 1h;
    slowfs_big_file_size 100m;
}

↑ back to index

http-sorted-querystring #

Nginx Sorted Querystring Module

Source: upstream source

Directives

sorted_querysting_filter_parameter #

syntax: sorted_querysting_filter_parameter 1+ args;  ·  context: http, server, location, location-if

It is also possible to remove one or more undesired query parameters by defining their name with the sorted_querysting_filter_parameter directive, like sorted_querystring_filter_parameter <parameter_name> [<parameter_name> <parameter_name> …];. _This module is not distributed with the Nginx source.

Example

pid         logs/nginx.pid;
error_log   logs/nginx-main_error.log debug;

# Development Mode
master_process      off;
daemon              off;
worker_processes    2;

events {
  worker_connections  1024;
  #use                 kqueue; # MacOS
  use                 epoll; # Linux
}

http {
  default_type    text/plain;

  types {
      text/html   html;
  }

  log_format main  '[$time_local] $host "$request" $request_time s '
                   '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
                   'cache_status: "$upstream_cache_status" args: "$args '
                   'sorted_args: "$sorted_querystring_args" ';

  access_log       logs/nginx-http_access.log;

  proxy_cache_path /tmp/cache levels=1:2 keys_zone=zone:10m inactive=10d max_size=100m;

  server {
    listen          8080;
    server_name     localhost;

    access_log       logs/nginx-http_access.log main;

    location /filtered {
      sorted_querysting_filter_parameter v _ v time b;

      proxy_set_header Host "static_files_server";
      proxy_pass http://localhost:8081;

      proxy_cache zone;
      proxy_cache_key "$sorted_querystring_args";
      proxy_cache_valid 200 1m;
    }

    location / {
      proxy_pass http://localhost:8081;

      proxy_cache zone;
      proxy_cache_key "$sorted_querystring_args";
      proxy_cache_valid 200 10m;
    }
  }

  server {
    listen          8081;

    location / {
      return 200 "$args\n";
    }
  }
}

↑ back to index

http-srcache-filter #

Transparent subrequest-based response caching — store and serve cached output via any backend nginx can talk to (memcached, redis), bypassing the built-in proxy/fastcgi cache.

Source: upstream source

Directives

srcache_buffer #

syntax: srcache_buffer 1 arg (size (k/m/g));  ·  context: http, server, location, location-if

Size in bytes; accepts k / m / g suffixes.

srcache_default_expire #

syntax: srcache_default_expire 1 arg (duration in seconds);  ·  context: http, server, location, location-if

Duration in seconds; accepts s / m / h / d suffixes.

srcache_fetch #

syntax: srcache_fetch 2 args;  ·  context: http, server, location, location-if

srcache_fetch_skip #

syntax: srcache_fetch_skip 1 arg;  ·  context: http, server, location, location-if

srcache_header_buffer_size #

syntax: srcache_header_buffer_size 1 arg (size (k/m/g));  ·  context: http, server, location, location-if

Size in bytes; accepts k / m / g suffixes.

srcache_ignore_content_encoding #

syntax: srcache_ignore_content_encoding on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

srcache_max_expire #

syntax: srcache_max_expire 1 arg (duration in seconds);  ·  context: http, server, location, location-if

Duration in seconds; accepts s / m / h / d suffixes.

srcache_methods #

syntax: srcache_methods 1+ args (bitmask);  ·  context: http, server, location

Bitmask — combine several keywords.

srcache_request_cache_control #

syntax: srcache_request_cache_control on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

srcache_response_cache_control #

syntax: srcache_response_cache_control on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

srcache_store #

syntax: srcache_store 2 args;  ·  context: http, server, location, location-if

srcache_store_hide_header #

syntax: srcache_store_hide_header 1 arg (list of strings);  ·  context: http, server, location

Appends a string to a list; may be specified multiple times.

srcache_store_max_size #

syntax: srcache_store_max_size 1 arg (size (k/m/g));  ·  context: http, server, location, location-if

Size in bytes; accepts k / m / g suffixes.

srcache_store_no_cache #

syntax: srcache_store_no_cache on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

srcache_store_no_store #

syntax: srcache_store_no_store on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

srcache_store_pass_header #

syntax: srcache_store_pass_header 1 arg (list of strings);  ·  context: http, server, location

Appends a string to a list; may be specified multiple times.

srcache_store_private #

syntax: srcache_store_private on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

srcache_store_ranges #

syntax: srcache_store_ranges on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

srcache_store_skip #

syntax: srcache_store_skip 1 arg;  ·  context: http, server, location, location-if

srcache_store_statuses #

syntax: srcache_store_statuses 1+ args;  ·  context: http, server, location, location-if

Example

    location /foo {
        default_type text/css;
        srcache_fetch GET /memc $uri;
        srcache_store PUT /memc $uri;
        srcache_store_no_cache on;
        srcache_store_no_store off;
        srcache_store_private off;

        content_by_lua '
            ngx.header.cache_control = "no-cache"
            ngx.say("hello")
        ';
    }

    location /memc {
        internal;

        set $memc_key $query_string;
        set $memc_exptime 300;
        memc_pass 127.0.0.1:$TEST_NGINX_MEMCACHED_PORT;
    }

↑ back to index

http-statsd #

Emits per-request StatsD metrics (counts, timings) from inside nginx — good for dashboards when full Prometheus instrumentation is overkill.

Source: upstream source

Directives

statsd_count #

syntax: statsd_count 2 args;  ·  context: server, location, server-if, location-if

statsd_sample_rate #

syntax: statsd_sample_rate 1 arg (integer);  ·  context: http, server, location

Integer value.

statsd_server #

syntax: statsd_server 1 arg;  ·  context: http, server, location

statsd_timing #

syntax: statsd_timing 2 args;  ·  context: server, location, server-if, location-if

Example

http {
    statsd_server  127.0.0.1:8125;
    statsd_sample_rate 100;

    server {
        location / {
            statsd_count  "nginx.requests.${status}" 1;
            statsd_timing "nginx.request_time" $request_time;
            proxy_pass http://backend;
        }
    }
}

↑ back to index

http-subs-filter #

Streaming response substitution — search-and-replace text or regex patterns inside response bodies on the fly, without buffering the whole document.

Source: upstream source

Directives

subs_buffers #

syntax: subs_buffers 2 args (number and size of buffers);  ·  context: http, server, location

Number and size of buffers, e.g. "32 4k".

subs_filter #

syntax: subs_filter 2+ args;  ·  context: http, server, location

You can disable the compressed response like this: proxy_set_header Accept-Encoding ""; subs_filter syntax: subs_filter source_str destination_str [gior] default: none context: http, server, location subs_filter allows replacing source string(regular expression or fixed) in the nginx response with destination string.

subs_filter_bypass #

syntax: subs_filter_bypass 1+ args;  ·  context: http, server, location

subs_filter_types #

syntax: subs_filter_types 1+ args;  ·  context: http, server, location

subs_line_buffer_size #

syntax: subs_line_buffer_size 2 args (size (k/m/g));  ·  context: http, server, location

Size in bytes; accepts k / m / g suffixes.

Example

    set $foo "0";
    set $bypass "1";
    location / {
        subs_filter 'taobao.com' 'yaoweibin' ir;
        subs_filter_bypass $foo $bypass;
        proxy_pass http://yaoweibin.net:8080/test/subs/taobao.htm;
    }

↑ back to index

http-sysguard #

Earlier versions is not tested.

Source: upstream source

Directives

sysguard #

syntax: sysguard on | off (on/off flag);  ·  context: http, server, location

Description: Enables or disables the module working.

sysguard_interval #

syntax: sysguard_interval 1 arg (duration in seconds);  ·  context: http, server, location

Description: Specify the time interval to update your system information. The default value is one second, which means sysguard updates the server status once a second.

sysguard_load #

syntax: sysguard_load 1 arg;  ·  context: http, server, location

It also requires the /proc file system to get memory information. ## Embedded Variables The following embedded variables are provided: $sysguard_load The load of system.

sysguard_log_level #

syntax: sysguard_log_level 1 arg (enum);  ·  context: http, server, location

Description: Specify the log level of sysguard.

sysguard_mem #

syntax: sysguard_mem 1 arg;  ·  context: http, server, location

sysguard_mode #

syntax: sysguard_mode on | off (enum);  ·  context: http, server, location

Description: If there are more than one type of monitor, this directive is used to specified the relations among all the monitors which are: 'and' for all matching and 'or' for any matching.

sysguard_rt #

syntax: sysguard_rt 1 arg;  ·  context: http, server, location

Description: Specify the response time threshold. Parameter rt is used to set a threshold of the average response time, in second. Parameter period is used to specify the period of the statistics cycle. If the average response time of the system exceeds the threshold specified by the user, The default method is set to be method=AMM:period.

Example

http {

    ...

    server {

        ...

        sysguard on;
        sysguard_mode or;

        sysguard_load load=10.5 action=/loadlimit;
        sysguard_mem swapratio=20% action=/swaplimit;
        sysguard_mem free=100M action=/freelimit;
        sysguard_rt rt=0.01 period=5s method=AMM:10 action=/rtlimit;

        location /loadlimit {
            return 503;
        }

        location /swaplimit {
            return 503;
        }

        location /freelimit {
            return 503;
        }

        location /rtlimit {
            return 503;
        }
    }

    ...

    server {

        ...

        location /api {
            sysguard on;
            sysguard_mode or;
            sysguard_load load=20 action=/limit;
            sysguard_mem swapratio=10% action=/limit;
            sysguard_rt rt=2.01 period=5s method=WMA:10 action=/limit;

            ... 

        }

        location /images {
            sysguard on;
            sysguard_mode and;
            sysguard_load load=20 action=/limit;
            sysguard_mem swapratio=10% action=/limit;
            sysguard_rt rt=2.01 period=5s method=WMA:10 action=/limit;

            ...

        }

        location /limit {
            return 503;
        }
    }

}

↑ back to index

http-testcookie-access #

Cookie-based bot mitigation — sets a JavaScript-required test cookie before allowing access, weeding out simple non-browser scrapers and low-effort DDoS traffic.

Source: upstream source

Directives

testcookie #

syntax: testcookie 1 arg (enum);  ·  context: http, server, location, server-if, location-if

DESCRIPTION testcookie-nginx-module is a simple robot mitigation module using cookie based challenge/response.

testcookie_arg #

syntax: testcookie_arg 1 arg (string);  ·  context: http, server, location

Stores a single string value.

testcookie_deny_keepalive #

syntax: testcookie_deny_keepalive 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

testcookie_domain #

syntax: testcookie_domain 1 arg (string);  ·  context: http, server, location

Stores a single string value.

testcookie_expires #

syntax: testcookie_expires 1 arg;  ·  context: http, server, location

testcookie_fallback #

syntax: testcookie_fallback 1 arg;  ·  context: http, server, location

testcookie_get_only #

syntax: testcookie_get_only 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

testcookie_httponly_flag #

syntax: testcookie_httponly_flag 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

testcookie_https_location #

syntax: testcookie_https_location 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

testcookie_internal #

syntax: testcookie_internal 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

testcookie_max_attempts #

syntax: testcookie_max_attempts 1 arg;  ·  context: http, server, location

testcookie_name #

syntax: testcookie_name 1 arg (string);  ·  context: http, server, location

Stores a single string value.

testcookie_p3p #

syntax: testcookie_p3p 1 arg (string);  ·  context: http, server, location

Stores a single string value.

testcookie_pass #

syntax: testcookie_pass 1 arg;  ·  context: http, server, location

testcookie_path #

syntax: testcookie_path 1 arg (string);  ·  context: http, server, location

Stores a single string value.

testcookie_port_in_redirect #

syntax: testcookie_port_in_redirect 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

testcookie_redirect_via_refresh #

syntax: testcookie_redirect_via_refresh 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

testcookie_refresh_encrypt_cookie #

syntax: testcookie_refresh_encrypt_cookie 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

testcookie_refresh_encrypt_cookie_iv #

syntax: testcookie_refresh_encrypt_cookie_iv 1 arg;  ·  context: http, server, location

testcookie_refresh_encrypt_cookie_key #

syntax: testcookie_refresh_encrypt_cookie_key 1 arg;  ·  context: http, server, location

testcookie_refresh_status #

syntax: testcookie_refresh_status 1 arg;  ·  context: http, server, location

testcookie_refresh_template #

syntax: testcookie_refresh_template 1 arg;  ·  context: http, server, location

testcookie_samesite #

syntax: testcookie_samesite 1 arg (string);  ·  context: http, server, location

Stores a single string value.

testcookie_secret #

syntax: testcookie_secret 1 arg (string);  ·  context: http, server, location

Stores a single string value.

testcookie_secure_flag #

syntax: testcookie_secure_flag 1 arg;  ·  context: http, server, location

testcookie_session #

syntax: testcookie_session 1 arg;  ·  context: http, server, location

testcookie_whitelist #

syntax: testcookie_whitelist no args;  ·  context: http, server

Example

        location / {
            if ($http_user_agent = "test") {
                testcookie on;
            }
        }

↑ back to index

http-trim-filter #

Whitespace and comment stripper for HTML / JS / CSS response bodies — shrinks payloads on the fly without requiring a build-time minifier.

Source: our fork on GitHub

Directives

trim #

syntax: trim 1 arg;  ·  context: http, server, location

trim_css #

syntax: trim_css 1 arg;  ·  context: http, server, location

trim_js #

syntax: trim_js 1 arg;  ·  context: http, server, location

trim_types #

syntax: trim_types 1+ args;  ·  context: http, server, location

Example

location / {
    trim        on;
    trim_js     on;
    trim_css    on;
    trim_types  text/html text/css application/javascript;
}

↑ back to index

http-ts #

MPEG-TS streaming module — packages an upstream video source into on-the-fly HLS and DASH segments served directly from nginx.

Source: upstream source

Directives

ts #

syntax: ts no args;  ·  context: location

ts_dash #

syntax: ts_dash 1+ args;  ·  context: location

ts_hls #

syntax: ts_hls 1+ args;  ·  context: location

Example

location /stream/ {
    ts;
    ts_hls   path=/var/ts/hls  segment=4s  segments=10;
    ts_dash  path=/var/ts/dash segment=4s  segments=10;
}

↑ back to index

http-unbrotli #

ngx_http_unbrotli_filter_module is a filter that decompresses responses with “Content-Encoding: brotli” for clients that do not support “brotli” encoding method. The module will be useful when it is desirable to store data compressed to save space and reduce I/O costs.

Source: upstream source

Directives

unbrotli #

syntax: unbrotli on | off;  ·  default: unbrotli off;  ·  context: http, server, location

Enables or disables decompression of brotli compressed responses for clients that lack brotli support.

unbrotli_buffers #

syntax: unbrotli_buffers number size;  ·  default: unbrotli_buffers 32 4k | 16 8k;  ·  context: http, server, location

Sets the number and size of buffers used to decompress a response. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.

unbrotli_force #

syntax: unbrotli_force string ...;  ·  default: -  ·  context: http, server, location

Defines the conditions for forced brotli decompression. If at least one value in the string parameter is not empty and not equal to "0", forced brotli decompression is performed. But it will not try to decompress responses that do not contain the response header Content-Encoding: br

Example

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location / {
        # enable brotli decompression for clients that do not support brotli compression
        unbrotli on;

        proxy_pass http://foo.com;
    }
}

↑ back to index

http-unzstd #

ngx_http_unzstd_filter_module is a filter that decompresses responses with “Content-Encoding: zstd” for clients that do not support “zstd” (Zstandard compression) encoding method. The module will be useful when it is desirable to store data compressed to save space and reduce I/O costs.

Source: upstream source

Directives

unzstd #

syntax: unzstd on | off;  ·  default: unzstd off;  ·  context: http, server, location

Enables or disables decompression of zstd compressed responses for clients that lack zstd support.

unzstd_buffers #

syntax: unzstd_buffers number size;  ·  default: unzstd_buffers 32 4k | 16 8k;  ·  context: http, server, location

Sets the number and size of buffers used to decompress a response. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.

unzstd_dict_file #

syntax: unzstd_dict_file 1 arg (string);  ·  context: http

Stores a single string value.

unzstd_force #

syntax: unzstd_force string ...;  ·  default: -  ·  context: http, server, location

Defines the conditions for forced brotli decompression. If at least one value in the string parameter is not empty and not equal to "0", forced zstd decompression is performed. But it will not try to decompress responses that do not contain the response header Content-Encoding: zstd.

Example

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location / {
        # enable zstd decompression for clients that do not support zstd compression
        unzstd on;

        proxy_pass http://foo.com;
    }
}

↑ back to index

http-upload #

A module for nginx for handling file uploads using multipart/form-data encoding (RFC 1867) and resumable uploads according to this protocol.

Source: upstream source

Directives

upload_add_header #

syntax: upload_add_header 2 args;  ·  context: http, server, location, location-if, limit_except

Specifies the name and content of the header that will be added to the response

upload_aggregate_form_field #

syntax: <code><b>upload_aggregate_form_field</b> <i>name</i> <i>value</i></code><br>  ·  default: —<br>  ·  context: server,location

Specifies a form field(s) containing aggregate attributes to generate for each uploaded file in request body passed to backend. Both name and value could contain standard nginx variables, variables from following additional special variables: The value of a field specified by this directive is evaluated after resources to calculate MD5 and SHA1 checksums.

upload_buffer_size #

syntax: <code><b>upload_buffer_size</b> <i>size</i></code><br>  ·  default: size of memory page in bytes<br>  ·  context: server,location

Size in bytes of write buffer which will be used to accumulate file data and write it to disk. This directive is intended to be used to compromise memory usage vs. syscall rate.

upload_cleanup #

syntax: <code><b>upload_cleanup</b> <i>status/range</i> ...</code><br>  ·  default: —<br>  ·  context: server,location

Specifies HTTP statuses after generation of which all file successfuly uploaded in current request will be removed. Used for cleanup after backend or server failure. Backend may also explicitly signal errornous status if it doesn't need uploaded files for some reason. HTTP status must be a numerical value in range 400-599, no leading zeroes are

upload_empty_fiels_names #

syntax: upload_empty_fiels_names on | off (on/off flag);  ·  context: http, server, location, location-if, limit_except

Specifies whether empty field names are allowed

upload_limit_rate #

syntax: <code><b>upload_limit_rate</b> <i>rate</i></code><br>  ·  default: 0<br>  ·  context: main,server,location

Specifies upload rate limit in bytes per second. Zero means rate is unlimited.

upload_max_file_size #

syntax: <code><b>upload_max_file_size</b> <i>size</i></code><br>  ·  default: 0<br>  ·  context: main,server,location

Specifies maximal size of the file. Files longer than the value of this directive will be omitted. This directive specifies "soft" limit, in the sense, that after encountering file longer than specified limit, nginx will continue to process request body, trying to receive remaining files. For "hard" limit client_max_body_size directive must be

upload_max_output_body_len #

syntax: <code><b>upload_max_output_body_len</b> <i>size</i></code><br>  ·  default: 100k<br>  ·  context: main,server,location

Specifies maximal length of the output body. This prevents piling up of non-file form fields in memory. Whenever output body overcomes specified limit error 413 (Request entity too large) will be generated. The value of zero for this directive specifies that no restrictions on output body length should be applied.

upload_max_part_header_len #

syntax: <code><b>upload_max_part_header_len</b> <i>size</i></code><br>  ·  default: 512<br>  ·  context: server,location

Specifies maximal length of part header in bytes. Determines the size of the buffer which will be used to accumulate part headers.

upload_merge_buffer_size #

syntax: upload_merge_buffer_size 1 arg (size (k/m/g));  ·  context: http, server, location

Specifies the size of buffer, which will be used for merging ranges into state file

upload_pass #

syntax: <code><b>upload_pass</b> <i>location</i></code><br>  ·  default: —<br>  ·  context: server,location

Specifies location to pass request body to. File fields will be stripped and replaced by fields, containing necessary information to handle uploaded files.

upload_pass_args #

syntax: <code><b>upload_pass_args</b> on | off</code><br>  ·  default: off<br>  ·  context: main,server,location

Enables forwarding of query arguments to location, specified by In this example backend gets request URI "/upload?id=5". In case of upload_pass_args off backend gets "/upload".

upload_pass_form_field #

syntax: <code><b>upload_pass_form_field</b> <i>regex</i></code><br>  ·  default: —<br>  ·  context: server,location

Specifies a regex pattern for names of fields which will be passed to backend from original request body. This directive could be specified multiple times per location. Field will be passed to backend as soon as first pattern matches. For PCRE-unaware enviroments this directive specifies exact name of a field to pass to backend. If directive is

upload_range_header_buffer_size #

syntax: upload_range_header_buffer_size 1 arg (size (k/m/g));  ·  context: http, server, location

Specifies the size of buffer, which will be used for returning range header

upload_resumable #

syntax: <code><b>upload_resumable</b> on | off</code><br>  ·  default: upload_resumable off<br>  ·  context: main,server,location

Enables resumable uploads.

upload_set_form_field #

syntax: <code><b>upload_set_form_field</b> <i>name</i> <i>value</i></code><br>  ·  default: —<br>  ·  context: server,location

Specifies a form field(s) to generate for each uploaded file in request body passed to backend. Both name and value could contain following special variables: with leading path elements in DOS and UNIX notation stripped. I.e. "D:\\Documents And Settings\\My Dcouments\\My Pictures\\Picture.jpg" will be converted to "Picture.jpg" and "/etc/passwd" will be

upload_state_store #

syntax: <code><b>upload_state_store</b> <i>directory</i> [<i>level1</i> [<i>level2</i>]] ...</code><br>  ·  default: —<br>  ·  context: server,location

Specifies a directory that will contain state files for resumable uploads. The directory could be hashed. In this case all subdirectories should exist before starting nginx.

upload_store #

syntax: <code><b>upload_store</b> <i>directory</i> [<i>level1</i> [<i>level2</i>]] ...</code><br>  ·  default: —<br>  ·  context: server,location

Specifies a directory to which output files will be saved to. The directory could be hashed. In this case all subdirectories should exist before starting nginx.

upload_store_access #

syntax: <code><b>upload_store_access</b> <i>mode</i></code><br>  ·  default: upload_store_access user:rw<br>  ·  context: server,location

Specifies access mode which will be used to create output files.

upload_tame_arrays #

syntax: <code><b>upload_tame_arrays</b> on | off</code><br>  ·  default: off<br>  ·  context: main,server,location

Specifies whether square brackets in file field names must be dropped (required for PHP arrays).

Example

server {
    client_max_body_size 100m;
    listen 80;

    # Upload form should be submitted to this location
    location /upload/ {
        # Pass altered request body to this location
        upload_pass @test;

        # Store files to this directory
        # The directory is hashed, subdirectories 0 1 2 3 4 5 6 7 8 9 should exist
        upload_store /tmp 1;

        # Allow uploaded files to be read only by user
        upload_store_access user:r;

        # Set specified fields in request body
        upload_set_form_field $upload_field_name.name "$upload_file_name";
        upload_set_form_field $upload_field_name.content_type "$upload_content_type";
        upload_set_form_field $upload_field_name.path "$upload_tmp_path";

        # Inform backend about hash and size of a file
        upload_aggregate_form_field "$upload_field_name.md5" "$upload_file_md5";
        upload_aggregate_form_field "$upload_field_name.size" "$upload_file_size";

        upload_pass_form_field "^submit$|^description$";

        upload_cleanup 400 404 499 500-505;
    }

    # Pass altered request body to a backend
    location @test {
        proxy_pass http://localhost:8080;
    }
}

↑ back to index

http-uploadprogress #

Nginx Upload Progress Module

Source: upstream source

Directives

report_uploads #

syntax: report_uploads 1 arg;  ·  context: http, server, location

It must be in a proxy_pass or fastcgi_pass location. report_uploads ++++++++++++++ :Syntax: report_uploads <zone_name> :Default: none :Context: location :Description: This directive allows a location to report the upload progress that is tracked by track_uploads for <zone_name>.

track_uploads #

syntax: track_uploads 2 args;  ·  context: http, server, location

It must be in a proxy_pass or fastcgi_pass location. report_uploads ++++++++++++++ :Syntax: report_uploads <zone_name> :Default: none :Context: location :Description: This directive allows a location to report the upload progress that is tracked by track_uploads for <zone_name>.

upload_progress #

syntax: upload_progress 2 args;  ·  context: http

upload_progress_content_type #

syntax: upload_progress_content_type 1 arg (string);  ·  context: http, server, location

Stores a single string value.

upload_progress_header #

syntax: upload_progress_header 1 arg (string);  ·  context: http, server, location

Stores a single string value.

upload_progress_java_output #

syntax: upload_progress_java_output no args;  ·  context: http, server, location

If you rely on this module serving the deprecated java output use: upload_progress_java_output in the progress probe location.

upload_progress_json_output #

syntax: upload_progress_json_output no args;  ·  context: http, server, location

upload_progress_jsonp_output #

syntax: upload_progress_jsonp_output no args;  ·  context: http, server, location

upload_progress_jsonp_parameter #

syntax: upload_progress_jsonp_parameter 1 arg (string);  ·  context: http, server, location

Stores a single string value.

upload_progress_template #

syntax: upload_progress_template 2 args;  ·  context: http, server, location

Example

http {
    upload_progress  uploads  1m;

    server {
        location /upload {
            track_uploads     uploads 30s;
            proxy_pass        http://backend;
        }
        location ^~ /progress {
            report_uploads             uploads;
            upload_progress_json_output;
        }
    }
}

↑ back to index

http-upstream-cache-vars #

ngx_http_upstream_cache_vars_module is a nginx module to provide a collection of upstream cache metadata variables.

Source: upstream source

No nginx directives detected.

↑ back to index

http-upstream-log #

The ngx_http_upstream_log_module module writes upstream request logs in the specified format, like ngx_http_log_module. Most of the work of this module originates from ngx_http_log_module.

Source: upstream source

Directives

upstream_log #

syntax: upstream_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]]; upstream_log off;  ·  default: -;  ·  context: http, server, location, if in location, limit_except

If either the buffer or gzip parameter is used, writes to log will be buffered. When buffering is enabled, the data will be written to the file: Example: The file path can contain variables, but such logs have some constraints:

Example

    http {

        log_format access '$remote_addr - $remote_user [$time_local] "$request" '
                        '$status $body_bytes_sent "$http_referer" '
                        '"$http_user_agent" "$http_x_forwarded_for"';

        log_format upstream '$remote_addr $upstream_last_addr [$time_local] "$upstream_method $upstream_uri" '
                                 '$upstream_last_status $upstream_last_response_length $upstream_last_bytes_sent $upstream_last_bytes_received '
                                 '$upstream_last_connect_time $upstream_last_header_time $upstream_last_response_time';

        upstream cluster {
            server 192.168.0.1:80;
            server 192.168.0.2:80;
        }

        server {
            listen 80;

            access_log logs/access.log access;
            upstream_log logs/upstream.log upstream;

            location / {
                proxy_pass http://cluster;
            }
        }

    }

↑ back to index

http-user-agent #

if ($variable == value) {

Source: upstream source

Directives

user_agent #

syntax: user_agent 1 arg;  ·  context: http

E.g 1. "Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.1; WOW64; Trident/6.0)", this string is MSIE's user_agent string, we will return when we find the keyword "MSIE".

Example

map $http_user_agent $is_mobile {
    default 0;
    "~*(?:Android|iPhone|iPad|Mobile)" 1;
}

location / {
    if ($is_mobile) {
        rewrite ^ /m$uri last;
    }
}

↑ back to index

http-var #

ngx_http_var_module is a nginx module that dynamically assigns new variables through predefined functions.

Source: upstream source

Directives

var #

syntax: var $new_variable function [-i] args... [if\=condition]  ·  default: -  ·  context: http, server, location

Define a new variable whose value is the result of function calculation. The variable value cannot be cached and is recalculated each time it is used. If the current level does not define a variable with the same variable name, it can be inherited from the previous level. The -i parameter is used to ignore case (Available only in some functions).

Example

#### Conditional Judgement ####
# Returns 1 if the input parameter is empty or 0, otherwise returns 0
var $bool_var not str;

# Returns 1 if all input parameters are non-empty and not 0, otherwise returns 0
var $bool_var and str1 str2...; 

# Returns 1 if any input parameter is non-empty and not 0, otherwise returns 0
var $bool_var or str1 str2...; 


#### String Judgement ####
# Checks if the string is empty, returns 1 or 0
var $bool_var is_empty str;

# Checks if the string is non-empty, returns 1 or 0
var $bool_var is_not_empty str;

# Checks if the string is a number, returns 1 or 0. Only decimal numbers are allowed. negative numbers and fractions are supported.
var $bool_var is_num str;

# Checks if the strings are equal, returns 1 or 0
var $bool_var str_eq [-i] str1 str2;

# Checks if the strings are not equal, returns 1 or 0
var $bool_var str_ne [-i] str1 str2;

# Checks if the string has the specified prefix, returns 1 or 0
var $bool_var starts_with [-i] str prefix;

# Checks if the string has the specified suffix, returns 1 or 0
var $bool_var ends_with [-i] str suffix;

# Checks if the substring is present, returns 1 or 0
var $bool_var contains [-i] str sub_str;

# Checks if the str1 is one of str2 .. strn, returns 1 or 0
var $bool_var str_in [-i] str1 str2 str3 .. strn;

#### General String Operations ####
# Set the value directly of the variable
var $new_var set src_str;

# Length of the string
var $new_var len src_str;

# Convert to uppercase
var $new_var upper src_str;

# Convert to lowercase
var $new_var lower src_str;

# Capitalize the first letter of each word (words are separated by non-alphanumeric characters)
var $new_var initcap src_str;

# Trim leading and trailing whitespace characters or other characters
var $new_var trim src_str [char];

# Trim leading whitespace characters or other characters
var $new_var ltrim src_str [char];

# Trim trailing whitespace characters or other characters
var $new_var rtrim src_str [char];

# Reverse the string
var $new_var reverse src_str;

# Get starting position of substring
var $new_var position [-i] src_str sub_str;

# Repeat the string a given number of times
var $new_var repeat src_str times;

# Extract substring
var $new_var substr src_str start [len];

# Replace keyword
var $new_var replace [-i] src_str src dst;

# Extract parameters
# Extract a value from a list of parameters. A use case for th
…

↑ back to index

http-vhost-traffic-status #

Nginx virtual host traffic status module

Source: upstream source

Directives

vhost_traffic_status #

syntax: vhost_traffic_status on | off (on/off flag);  ·  context: http, server, location

Description: Enables or disables the module working. If you set vhost_traffic_status_zone directive, is automatically enabled.

vhost_traffic_status_average_method #

syntax: vhost_traffic_status_average_method 1 arg;  ·  context: http, server, location

Description: Sets the method which is a formula that calculate the average of response processing times. The period is an effective time of the values used for the average calculation.(Default: 60s) If period set to 0, effective time is ignored. In this case, the last average value is displayed even if there is no requests and after the elapse of time.

vhost_traffic_status_bypass_limit #

syntax: vhost_traffic_status_bypass_limit on | off (on/off flag);  ·  context: http, server, location

Description: Enables or disables to bypass vhost_traffic_status_limit directives. The limit features is bypassed if this option is enabled. This is mostly useful if you want to connect the status web page like /status regardless of vhost_traffic_status_limit directives as follows:

vhost_traffic_status_bypass_stats #

syntax: vhost_traffic_status_bypass_stats on | off (on/off flag);  ·  context: http, server, location

Description: Enables or disables to bypass vhost_traffic_status. The traffic status stats features is bypassed if this option is enabled. In other words, it is excluded from the traffic status stats. This is mostly useful if you want to ignore your request in status web page like /status as follows:

vhost_traffic_status_display #

syntax: vhost_traffic_status_display no args;  ·  context: server, location

Description: Enables or disables the module display handler.

vhost_traffic_status_display_format #

syntax: vhost_traffic_status_display_format 1 arg (enum);  ·  context: server, location

Description: Sets the display handler's output format. If you set json, will respond with a JSON document. If you set html, will respond with the built-in live dashboard in HTML. If you set jsonp, will respond with a JSONP callback function(default: ngx_http_vhost_traffic_status_jsonp_callback). If you set prometheus, will respond with a prometheus document.

vhost_traffic_status_display_jsonp #

syntax: vhost_traffic_status_display_jsonp 1 arg (string);  ·  context: server, location

Description: Sets the callback name for the JSONP.

vhost_traffic_status_display_sum_key #

syntax: vhost_traffic_status_display_sum_key 1 arg (string);  ·  context: server, location

Description: Sets the sum key string in serverZones field's JSON. The default sum key string is the "*".

vhost_traffic_status_dump #

syntax: vhost_traffic_status_dump 1 arg;  ·  context: http

Description: Enables the statistics data dump and restore. The path is a location to dump the statistics data.(e.g. /var/log/nginx/vts.db) The period is a backup cycle time.(Default: 60s) It is backed up immediately regardless of the backup cycle if nginx is exited by signal(SIGKILL).

vhost_traffic_status_filter #

syntax: vhost_traffic_status_filter on | off (on/off flag);  ·  context: http, server, location

Description: Enables or disables the filter features.

vhost_traffic_status_filter_by_host #

syntax: vhost_traffic_status_filter_by_host on | off (on/off flag);  ·  context: http, server, location

Description: Enables or disables the keys by Host header field. If you set on and nginx's server_name directive set several or wildcard name starting with an asterisk, e.g. “*.example.org” and requested to server with hostname such as (a|b|c).example.org or *.example.org then json serverZones is printed as follows:

vhost_traffic_status_filter_by_set_key #

syntax: vhost_traffic_status_filter_by_set_key 1 arg;  ·  context: http, server, location

Description: Enables the keys by user defined variable. The key is a key string to calculate traffic. The name is a group string to calculate traffic. The key and name can contain variables such as $host, $server_name. The name's group belongs to filterZones if specified. The key's group belongs to serverZones if not specified second argument name.

vhost_traffic_status_filter_check_duplicate #

syntax: vhost_traffic_status_filter_check_duplicate on | off (on/off flag);  ·  context: http, server, location

Description: Enables or disables the deduplication of vhost_traffic_status_filter_by_set_key. It is processed only one of duplicate values(key + name) in each directives(http, server, location) if this option is enabled.

vhost_traffic_status_filter_max_node #

syntax: vhost_traffic_status_filter_max_node 1+ args;  ·  context: http

Description: Enables the limit of filter size using the specified number and string values. If the number is exceeded, the existing nodes are deleted by the LRU algorithm. The number argument is the size of the node that will be limited. The default value 0 does not limit filters. The one node is an object in filterZones in JSON document. For examples:

vhost_traffic_status_histogram_buckets #

syntax: vhost_traffic_status_histogram_buckets 1+ args;  ·  context: http, server, location

Description: Sets the observe buckets to be used in the histograms. By default, if you do not set this directive, it will not work. The second can be expressed in decimal places with a minimum value of 0.001(1ms). The maximum size of the buckets is 32. If this value is insufficient for you, For examples: by vhost_traffic_status_histogram_buckets directive.

vhost_traffic_status_ignore_status #

syntax: vhost_traffic_status_ignore_status 1+ args (bitmask);  ·  context: http, server, location

Bitmask — combine several keywords.

vhost_traffic_status_limit #

syntax: vhost_traffic_status_limit on | off (on/off flag);  ·  context: http, server, location

Description: Enables or disables the limit features.

vhost_traffic_status_limit_check_duplicate #

syntax: vhost_traffic_status_limit_check_duplicate on | off (on/off flag);  ·  context: http, server, location

Description: Enables or disables the deduplication of vhost_traffic_status_limit_by_set_key. It is processed only one of duplicate values(member | key + member) in each directives(http, server, location) if this option is enabled.

vhost_traffic_status_limit_traffic #

syntax: vhost_traffic_status_limit_traffic 1 arg;  ·  context: http, server, location

Description: Enables the traffic limit for specified member. The member is a member string to limit traffic. The size is a size(k/m/g) to limit traffic. The code is a code to return in response to rejected requests.(Default: 503) The available member strings are as follows:

vhost_traffic_status_limit_traffic_by_set_key #

syntax: vhost_traffic_status_limit_traffic_by_set_key 2 args;  ·  context: http, server, location

Description: Enables the traffic limit for specified key and member. The key is a key string to limit traffic. The member is a member string to limit traffic. The size is a size(k/m/g) to limit traffic. The code is a code to return in response to rejected requests.(Default: 503) The key syntax is as follows: The available group strings are as follows:

vhost_traffic_status_measure_status_codes #

syntax: vhost_traffic_status_measure_status_codes no args;  ·  context: http

Allows tracking of specific HTTP status codes or all status codes in the Vhost Traffic Status module.

vhost_traffic_status_set_by_filter #

syntax: vhost_traffic_status_set_by_filter 2 args;  ·  context: http, server, location, location-if

Description: Get the specified status value stored in shared memory. It can acquire almost all status values and the obtained value is stored in $variable which is first argument. Caveats: The name is case sensitive. All return values take the integer type. For examples:

vhost_traffic_status_stats_by_upstream #

syntax: vhost_traffic_status_stats_by_upstream on | off (on/off flag);  ·  context: http

Description: Enables or disables to stats upstreamZone. The upstreamZone in the traffic status stats features is bypassed if this option is disabled. In other words, it is excluded from the traffic status stats. This is mostly useful if you want to be disable statistics collection for upstream servers to reduce CPU load.

vhost_traffic_status_zone #

syntax: vhost_traffic_status_zone no args;  ·  context: http

Description: Sets parameters for a shared memory zone that will keep states for various keys. The cache is shared between all worker processes. In most cases, the shared memory size used by nginx-module-vts does not increase much. The shared memory size is increased pretty when using vhost_traffic_status_filter_by_set_key it does not continuously increase.

Example

http {
    vhost_traffic_status_zone;

    ...

    server {

        ...

        location /status {
            vhost_traffic_status_bypass_limit on;
            vhost_traffic_status_bypass_stats on;
            vhost_traffic_status_display;
            vhost_traffic_status_display_format html;
        }
    }
}

↑ back to index

http-vod #

Join the list of organizations using this video packager project.

Source: upstream source

Directives

vod #

syntax: vod segmenter  ·  default: n/a  ·  context: location

Enables the nginx-vod module on the enclosing location. The allowed values for segmenter are: 1. none – serves the MP4 files as is / clipped 2. dash – Dynamic Adaptive Streaming over HTTP packager 3. hds – Adobe HTTP Dynamic Streaming packager 4. hls – Apple HTTP Live Streaming packager 5. mss – Microsoft Smooth Streaming packager

vod_align_segments_to_key_frames #

syntax: vod_align_segments_to_key_frames on/off  ·  default: off  ·  context: http, server, location

When enabled, the module forces all segments to start with a key frame. Enabling this setting can lead to differences between the actual segment durations and the durations reported in the manifest (unless vod_manifest_segment_durations_mode is set to accurate).

vod_apply_dynamic_mapping #

syntax: vod_apply_dynamic_mapping mapping  ·  default: none  ·  context: http, server, location

Maps dynamic clips to concat clips using the given expression, previously generated by $vod_dynamic_mapping. The parameter value can contain variables.

vod_base_url #

syntax: vod_base_url url  ·  default: see below  ·  context: http, server, location

Sets the base URL (scheme + domain) that should be returned in manifest responses. The parameter value can contain variables, if the parameter evaluates to an empty string, relative URLs will be used. If the parameter evaluates to a string ending with /, it is assumed to be a full URL – the module only appends the file name to it, instead of a full URI.

vod_bootstrap_segment_durations #

syntax: vod_bootstrap_segment_durations duration  ·  default: none  ·  context: http, server, location

Adds a bootstrap segment duration in milliseconds. This setting can be used to make the first few segments shorter than the default segment duration, thus making the adaptive bitrate selection kick-in earlier without the overhead of short segments throughout the video.

vod_cache_buffer_size #

syntax: vod_cache_buffer_size size  ·  default: 256K  ·  context: http, server, location

Sets the size of the cache buffers used when reading MP4 frames.

vod_clip_from_param_name #

syntax: vod_clip_from_param_name name  ·  default: clipFrom  ·  context: http, server, location

The name of the clip from request parameter.

vod_clip_to_param_name #

syntax: vod_clip_to_param_name name  ·  default: clipTo  ·  context: http, server, location

The name of the clip to request parameter.

vod_drm_clear_lead_segment_count #

syntax: vod_drm_clear_lead_segment_count count  ·  default: 1  ·  context: http, server, location

Sets the number of clear (unencrypted) segments in the beginning of the stream. A clear lead enables the player to start playing without having to wait for the license response.

vod_drm_enabled #

syntax: vod_drm_enabled on/off  ·  default: off  ·  context: http, server, location

When enabled, the module encrypts the media segments according to the response it gets from the drm upstream. Currently supported only for dash and mss (play ready).

vod_drm_info_cache #

syntax: vod_drm_info_cache zone_name zone_size [expiration]  ·  default: off  ·  context: http, server, location

Configures the size and shared memory object name of the drm info cache.

vod_drm_max_info_length #

syntax: vod_drm_max_info_length length  ·  default: 4K  ·  context: http, server, location

Sets the maximum length of a drm info returned from upstream.

vod_drm_request_uri #

syntax: vod_drm_request_uri uri  ·  default: $vod_suburi  ·  context: http, server, location

Sets the uri of drm info requests, the parameter value can contain variables. In case of multi url, $vod_suburi will be the current sub uri (a separate drm info request is issued per sub URL)

vod_drm_single_key #

syntax: vod_drm_single_key on/off  ·  default: off  ·  context: http, server, location

When enabled, the module requests the drm info only for the first sequence and applies it to all sequences. When disabled, the drm info is requested for each sequence separately. In addition, in DASH, enabling this setting makes the module place the ContentProtection tag under AdaptationSet, otherwise, it is placed under Representation.

vod_drm_upstream_location #

syntax: vod_drm_upstream_location location  ·  default: none  ·  context: http, server, location

Sets the nginx location that should be used for getting the DRM info for the file.

vod_dynamic_clip_map_uri #

syntax: vod_dynamic_clip_map_uri uri  ·  default: none  ·  context: http, server, location

Sets the uri that should be used to map dynamic clips. The parameter value can contain variables, specifically, $vod_clip_id contains the id of the clip that should be mapped. The expected response from this uri is a JSON containing a concat clip object.

vod_dynamic_mapping_cache #

syntax: vod_dynamic_mapping_cache zone_name zone_size [expiration]  ·  default: off  ·  context: http, server, location

Configures the size and shared memory object name of the cache that stores the mapping of dynamic clips.

vod_encryption_iv_seed #

syntax: vod_encryption_iv_seed string  ·  default: empty  ·  context: http, server, location

Sets the seed that is used to generate the encryption IV, currently applies only to HLS/fMP4 with AES-128 encryption. The parameter value can contain variables.

vod_expires #

syntax: vod_expires time  ·  default: none  ·  context: http, server, location

Sets the value of the "Expires" and "Cache-Control" response headers for successful requests. This directive is similar to nginx's built-in expires directive, except that it only supports the expiration interval scenario (epoch, max, off, day time are not supported)

vod_expires_live #

syntax: vod_expires_live time  ·  default: none  ·  context: http, server, location

Same as vod_expires (above) for live requests that are not time dependent and not segments (e.g. HLS – master.m3u8, HDS – manifest.f4m).

vod_expires_live_time_dependent #

syntax: vod_expires_live_time_dependent time  ·  default: none  ·  context: http, server, location

Same as vod_expires (above) for live requests that are time dependent (HLS – index.m3u8, HDS – bootstrap.abst, MSS – manifest, DASH – manifest.mpd).

vod_fallback_upstream_location #

syntax: vod_fallback_upstream_location location  ·  default: none  ·  context: http, server, location

Sets an nginx location to which the request is forwarded after encountering a file not found error (local/mapped modes only).

vod_force_continuous_timestamps #

syntax: vod_force_continuous_timestamps on/off  ·  default: off  ·  context: http, server, location

Generate continuous timestamps even when the media set has gaps (gaps can created by the use of clipTimes) If ID3 timestamps are enabled (vod_hls_mpegts_output_id3_timestamps), they contain the original timestamps that were set in clipTimes.

vod_force_playlist_type_vod #

syntax: vod_force_playlist_type_vod on/off  ·  default: off  ·  context: http, server, location

Generate a vod stream even when the media set has playlistType=live. Enabling this setting has the following effects: 1. Frame timestamps will be continuous and start from zero 2. Segment indexes will start from one 3. In case of HLS, the returned manifest will have both #EXT-X-PLAYLIST-TYPE:VOD and #EXT-X-ENDLIST

vod_force_sequence_index #

syntax: vod_force_sequence_index on/off  ·  default: off  ·  context: http, server, location

Use sequence index in segment uris even if there is only one sequence

vod_gop_look_ahead #

syntax: vod_gop_look_ahead millis  ·  default: 1000  ·  context: http, server, location

Sets the interval (in milliseconds) after the thumbnail offset that should be loaded.

vod_gop_look_behind #

syntax: vod_gop_look_behind millis  ·  default: 10000  ·  context: http, server, location

Sets the interval (in milliseconds) before the thumbnail offset that should be loaded. This setting should be set to the maximum GOP size, setting it to a lower value may result in capture failure. Note that the metadata of all frames between offset – vod_gop_look_behind and offset + vod_gop_look_ahead

vod_ignore_edit_list #

syntax: vod_ignore_edit_list on/off  ·  default: off  ·  context: http, server, location

When enabled, the module ignores any edit lists (elst) in the MP4 file.

vod_initial_read_size #

syntax: vod_initial_read_size size  ·  default: 4K  ·  context: http, server, location

Sets the size of the initial read operation of the MP4 file.

vod_lang_param_name #

syntax: vod_lang_param_name name  ·  default: lang  ·  context: http, server, location

The name of the language request parameter.

vod_last_modified #

syntax: vod_last_modified time  ·  default: none  ·  context: http, server, location

Sets the value of the Last-Modified header returned on the response, by default the module does not return a Last-Modified header. The reason for having this parameter here is in order to support If-Modified-Since / If-Unmodified-Since. This makes nginx always reply as if the content changed (412 for If-Unmodified-Since / 200 for If-Modified-Since)

vod_last_modified_types #

syntax: vod_last_modified_types mime-type1 mime-type2 ...  ·  default: none  ·  context: http, server, location

Sets the MIME types for which the Last-Modified header should be set. The special value "*" matches any MIME type.

vod_live_mapping_cache #

syntax: vod_live_mapping_cache zone_name zone_size [expiration]  ·  default: off  ·  context: http, server, location

Configures the size and shared memory object name of the mapping cache for live (mapped mode only).

vod_live_response_cache #

syntax: vod_live_response_cache zone_name zone_size [expiration]  ·  default: off  ·  context: http, server, location

Configures the size and shared memory object name of the response cache for time changing live responses. This cache holds the following types of responses for live: DASH MPD, HLS index M3U8, HDS bootstrap, MSS manifest.

vod_live_window_duration #

syntax: vod_live_window_duration duration  ·  default: 30000  ·  context: http, server, location

Sets the total duration in milliseconds of the segments that should be returned in a live manifest. If the value is positive, nginx vod returns a range of maximum vod_live_window_duration milliseconds, ending at the current server time.

vod_manifest_duration_policy #

syntax: vod_manifest_duration_policy min/max  ·  default: max  ·  context: http, server, location

Configures the policy for calculating the duration of a manifest containing multiple streams:

vod_manifest_segment_durations_mode #

syntax: vod_manifest_segment_durations_mode estimate/accurate  ·  default: estimate  ·  context: http, server, location

Configures the calculation mode of segment durations within manifest requests: an HLS manifest will contain #EXTINF:10 frame rate of 29.97 and 10 second segments it will report the first segment as 10.01. accurate mode also takes into account the key frame alignment, in case vod_align_segments_to_key_frames is on

vod_mapping_cache #

syntax: vod_mapping_cache zone_name zone_size [expiration]  ·  default: off  ·  context: http, server, location

Configures the size and shared memory object name of the mapping cache for vod (mapped mode only).

vod_max_frame_count #

syntax: vod_max_frame_count count  ·  default: 1048576  ·  context: http, server, location

Sets the limit on the total count of the frames read to serve non segment (e.g. playlist) request.

vod_max_frames_size #

syntax: vod_max_frames_size size  ·  default: 16MB  ·  context: http, server, location

Sets the limit on the total size of the frames of a single segment

vod_max_mapping_response_size #

syntax: vod_max_mapping_response_size length  ·  default: 1K  ·  context: http, server, location

Sets the maximum length of a path returned from upstream (mapped mode only).

vod_max_metadata_size #

syntax: vod_max_metadata_size size  ·  default: 128MB  ·  context: http, server, location

Sets the maximum supported video metadata size (for MP4 – moov atom size)

vod_max_upstream_headers_size #

syntax: vod_max_upstream_headers_size size  ·  default: 4k  ·  context: http, server, location

Sets the size that is allocated for holding the response headers when issuing upstream requests (to vod_xxx_upstream_location).

vod_media_set_map_uri #

syntax: vod_media_set_map_uri uri  ·  default: $vod_suburi  ·  context: http, server, location

Sets the uri of media set mapping requests, the parameter value can contain variables. In case of multi url, $vod_suburi will be the current sub uri (a separate request is issued per sub URL)

vod_media_set_override_json #

syntax: vod_media_set_override_json json  ·  default: {}  ·  context: http, server, location

This parameter provides a way to override portions of the media set JSON (mapped mode only). For example, vod_media_set_override_json '{"clipTo":20000}' clips the media set to 20 sec. The parameter value can contain variables.

vod_metadata_cache #

syntax: vod_metadata_cache zone_name zone_size [expiration]  ·  default: off  ·  context: http, server, location

Configures the size and shared memory object name of the video metadata cache. For MP4 files, this cache holds the moov atom.

vod_min_single_nalu_per_frame_segment #

syntax: vod_min_single_nalu_per_frame_segment index  ·  default: 0  ·  context: http, server, location

Sets the minimum segment index (1-based) that should be assumed to have a single h264 nalu per frame. If the value is 0, no assumption is being made on the number of nal units per frame. This setting only affects DASH and MSS configurations that have DRM enabled. calculated in advance, allowing the module to:

vod_mode #

syntax: vod_mode mode  ·  default: local  ·  context: http, server, location

Sets the file access mode – local, remote or mapped (see the features section above for more details)

vod_multi_uri_suffix #

syntax: vod_multi_uri_suffix suffix  ·  default: .urlset  ·  context: http, server, location

A URL suffix that is used to identify multi URLs. A multi URL is a way to encode several different URLs that should be played together as an adaptive streaming set, under a single URL. When the default suffix is used, an HLS set URL may look like: http://host/hls/common-prefix,bitrate1,bitrate2,common-suffix.urlset/master.m3u8

vod_notification_uri #

syntax: vod_notification_uri uri  ·  default: none  ·  context: http, server, location

Sets the uri that should be used to issue notifications. The parameter value can contain variables, specifically, $vod_notification_id contains the id of the notification that is being fired. The response from this uri is ignored.

vod_open_file_thread_pool #

syntax: vod_open_file_thread_pool pool_name  ·  default: off  ·  context: http, server, location

Enables the use of asynchronous file open via thread pool. The thread pool must be defined with a thread_pool directive, if no pool name is specified the default pool is used. This directive is supported only on nginx 1.7.11 or newer when compiling with –add-threads.

vod_output_buffer_pool #

syntax: vod_output_buffer_pool size count  ·  default: off  ·  context: http, server, location

Pre-allocates buffers for generating response data, saving the need allocate/free the buffers on every request.

vod_parse_hdlr_name #

syntax: vod_parse_hdlr_name on/off  ·  default: off  ·  context: http, server, location

When enabled, the module parses the name field of the hdlr MP4 atom, and uses it as the stream label.

vod_parse_udta_name #

syntax: vod_parse_udta_name on/off  ·  default: off  ·  context: http, server, location

When enabled, the module parses the name atom child of the udta MP4 atom, and uses it as the stream label.

vod_path_response_postfix #

syntax: vod_path_response_postfix postfix  ·  default: "}]}]}  ·  context: http, server, location

Sets the postfix that is expected in URI mapping responses (mapped mode only).

vod_path_response_prefix #

syntax: vod_path_response_prefix prefix  ·  default: {"sequences":[{"clips":[{"type":"source","path":"  ·  context: http, server, location

Sets the prefix that is expected in URI mapping responses (mapped mode only).

vod_performance_counters #

syntax: vod_performance_counters zone_name  ·  default: off  ·  context: http, server, location

Configures the shared memory object name of the performance counters

vod_proxy_header_name #

syntax: vod_proxy_header_name name  ·  default: X-Kaltura-Proxy  ·  context: http, server, location

Sets the name of an HTTP header that is used to prevent fallback proxy loops (local/mapped modes only).

vod_proxy_header_value #

syntax: vod_proxy_header_value name  ·  default: dumpApiRequest  ·  context: http, server, location

Sets the value of an HTTP header that is used to prevent fallback proxy loops (local/mapped modes only).

vod_redirect_segments_url #

syntax: vod_redirect_segments_url url  ·  default: none  ·  context: http, server, location

Sets a url to which requests for segments should be redirected. The parameter value can contain variables, specifically, $vod_dynamic_mapping contains a serialized representation of the mapping of dynamic clips.

vod_remote_upstream_location #

syntax: vod_remote_upstream_location location  ·  default: none  ·  context: http, server, location

Sets an nginx location that is used to read the MP4 file on remote or mapped mode. If this directive is set on mapped mode, the module reads the MP4 files over HTTP, treating the paths in the mapping JSON as URIs (the default behavior is to read from local files)

vod_response_cache #

syntax: vod_response_cache zone_name zone_size [expiration]  ·  default: off  ·  context: http, server, location

Configures the size and shared memory object name of the response cache. The response cache holds manifests and other non-video content (like DASH init segment, HLS encryption key etc.). Video segments are not cached.

vod_secret_key #

syntax: vod_secret_key string  ·  default: empty  ·  context: http, server, location

Sets the seed that is used to generate the TS encryption key and DASH/MSS encryption IVs. The parameter value can contain variables, and will usually have the structure "secret-$vod_filepath". See the list of nginx variables added by this module below.

vod_segment_count_policy #

syntax: vod_segment_count_policy last_short/last_long/last_rounded  ·  default: last_short  ·  context: http, server, location

Configures the policy for calculating the segment count, for segment_duration = 10 seconds:

vod_segment_duration #

syntax: vod_segment_duration duration  ·  default: 10s  ·  context: http, server, location

Sets the segment duration in milliseconds. It is highly recommended to use a segment duration that is a multiple of the GOP duration. If the segment duration is not a multiple of GOP duration, and vod_align_segments_to_key_frames is enabled, there could be significant the appearance of empty segments within the stream.

vod_segment_max_frame_count #

syntax: vod_segment_max_frame_count count  ·  default: 65536  ·  context: http, server, location

Sets the limit on the total count of the frames read to serve segment request.

vod_segments_base_url #

syntax: vod_segments_base_url url  ·  default: see below  ·  context: http, server, location

Sets the base URL (scheme + domain) that should be used for delivering video segments. The parameter value can contain variables, if the parameter evaluates to an empty string, relative URLs will be used. If not set, vod_base_url will be used. The setting currently affects only HLS.

vod_source_clip_map_uri #

syntax: vod_source_clip_map_uri uri  ·  default: none  ·  context: http, server, location

Sets the uri that should be used to map source clips defined using the clipIds property of concat. The parameter value can contain variables, specifically, $vod_clip_id contains the id of the clip that should be mapped. The expected response from this uri is a JSON containing a source clip object.

vod_speed_param_name #

syntax: vod_speed_param_name name  ·  default: speed  ·  context: http, server, location

The name of the speed request parameter.

vod_status #

syntax: vod_status  ·  default: n/a  ·  context: location

Enables the nginx-vod status page on the enclosing location. The following query params are supported:

vod_time_shift_param_name #

syntax: vod_time_shift_param_name name  ·  default: shift  ·  context: http, server, location

The name of the shift request parameter.

vod_tracks_param_name #

syntax: vod_tracks_param_name name  ·  default: tracks  ·  context: http, server, location

The name of the tracks request parameter.

vod_upstream_extra_args #

syntax: vod_upstream_extra_args "arg1=value1&arg2=value2&..."  ·  default: empty  ·  context: http, server, location

Extra query string arguments that should be added to the upstream request (remote/mapped modes only). The parameter value can contain variables.

vod_upstream_location #

syntax: vod_upstream_location location  ·  default: none  ·  context: http, server, location

Sets an nginx location that is used to read the MP4 file (remote mode) or mapping the request URI (mapped mode).

Example


worker_processes  1;

error_log  /var/log/nginx/error.log debug;

pid		/var/run/nginx.pid;

events {
	worker_connections  1024;
	multi_accept on;
	use epoll;
}

http {
	include	   mime.types;
	default_type  application/octet-stream;

	log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
		'$status $bytes_sent $request_time "$http_referer" '
		'"$http_user_agent" "$http_x_kaltura_f5_https" $http_x_kaltura_f5_remote_addr '
		'"$sent_http_x_kaltura" "$http_host" $pid $sent_http_x_kaltura_session - '
		'$request_length "$sent_http_content_range" "$http_x_forwarded_for" '
		'"$http_x_forwarded_server" "$http_x_forwarded_host" "$sent_http_cache_control" '
		'$connection ';

	access_log /var/log/nginx/access.log main;

	sendfile on;
	tcp_nopush on;
	tcp_nodelay on;

	keepalive_timeout 60;
	keepalive_requests 1000;
	client_header_timeout 20;
	client_body_timeout 20;
	reset_timedout_connection on;
	send_timeout 20;

	add_header X-Me $hostname;

	gzip  on;
	gzip_types application/vnd.apple.mpegurl;
		
	# common vod settings
	vod_metadata_cache metadata_cache 512m;
	vod_mapping_cache mapping_cache 5m;
	vod_response_cache response_cache 128m;
	vod_drm_info_cache drm_cache 64m;

	# common proxy settings
	proxy_connect_timeout 5;
	proxy_send_timeout 5;
	proxy_read_timeout 5;
	
	# common file caching / aio
	open_file_cache max=100 inactive=5m;
	open_file_cache_valid 2m;
	open_file_cache_min_uses 1;
	open_file_cache_errors on;
	aio on;
	
	upstream kalapi {
		server localhost:80 max_fails=0;
	}
	
	upstream self {
		server localhost:8001 max_fails=0;
		keepalive 32;
	}	

	upstream testapi {
		server localhost:8002 max_fails=0;
	}

	upstream fallback {
		server localhost:8003 max_fails=0;
	}

	upstream drmservice {
		server localhost:8004 max_fails=0;
	}
	
	server {
		listen	   8001 backlog=1024;
		server_name  localhost;

		# location for testing keep-alive - any requests to /self/xxx get proxied to xxx with keepalive
		# the tested module "sees" keepalive connections even though the test code is not using keepalive
		location /self/ {
			proxy_pass http://self/;
			proxy_http_version 1.1;
			proxy_set_header Connection "";
			proxy_set_header Host $http_host;
		}
		
		# internal location for vod subrequests
		location /kalapi_proxy/ {
			internal;
			proxy_pass http://kalapi/;
			proxy_set_header Host $http_host;
		}

		location /testapi_proxy/ {
			int
…

↑ back to index

http-waf #

Handy, High performance Nginx firewall module.

Source: upstream source

Directives

waf #

syntax: waf on | off;  ·  context: http, server, location

waf_action #

syntax: waf_action 1 arg;  ·  context: http, server, location

waf_block_page #

syntax: waf_block_page 1 arg;  ·  context: http, server, location

waf_cache #

syntax: waf_cache 1 arg;  ·  context: server, location

waf_captcha #

syntax: waf_captcha 1 arg;  ·  context: http, server, location

waf_cc_deny #

syntax: waf_cc_deny 1 arg;  ·  context: server, location

waf_mode #

syntax: waf_mode 1+ args;  ·  context: http, server, location

waf_modsecurity #

syntax: waf_modsecurity 1 arg;  ·  context: http, server, location

waf_modsecurity_transaction_id #

syntax: waf_modsecurity_transaction_id 1 arg;  ·  context: http, server, location

waf_priority #

syntax: waf_priority 1 arg;  ·  context: http, server, location

waf_rule_path #

syntax: waf_rule_path 1 arg;  ·  context: http, server, location

waf_under_attack #

syntax: waf_under_attack 1 arg;  ·  context: http, server, location

waf_verify_bot #

syntax: waf_verify_bot 1 arg;  ·  context: http, server, location

waf_zone #

syntax: waf_zone 2 args;  ·  context: http

Example

waf on;
waf_mode FULL;
waf_rule_path ${base_dir}/waf/rules/;
waf_cc_deny off rate=100r/m;
waf_cache off capacity=50;
waf_modsecurity on file=${base_dir}/waf/modsec/modsecurity.conf;
waf_modsecurity_transaction_id modsecurity_transaction_id;

location /t {

}

↑ back to index

http-xss-filter #

xss-nginx-module – Native cross-site scripting support in nginx

Source: upstream source

Directives

xss_callback_arg #

syntax: xss_callback_arg 1 arg (string);  ·  context: http, server, location, location-if

Stores a single string value.

xss_check_status #

syntax: xss_check_status on | off (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

xss_get #

syntax: xss_get on | off;  ·  context: http, server, location, location-if

xss_input_types #

syntax: xss_input_types 1+ args;  ·  context: http, server, location, location-if

xss_output_type #

syntax: xss_output_type 1+ args (string);  ·  context: http, server, location, location-if

Stores a single string value.

xss_override_status #

syntax: xss_override_status on | off (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

Example

# accessing /foo?callback=process gives the response
# body "process(...);" (without quotes) where "..."
# is the original response body of the /foo location.
server {
    location /foo {
        # your content handler goes here...

        xss_get on;
        xss_callback_arg 'callback';
        xss_input_types 'application/json'; # default
        xss_output_type 'application/x-javascript'; # default
    }
    ...
}

↑ back to index

http-zip #

Streams a ZIP archive on demand from a manifest of upstream files — no temporary file, no full-archive buffering, supports range requests.

Source: upstream source

No nginx directives detected.

↑ back to index

http-zstd #

Our hardened fork of tokers/zstd-nginx-module — Zstandard compression filter for nginx and Angie. Typically beats gzip at comparable or faster speeds. Continuously fuzzed and run under ASAN/UBSAN; see our deep-dive what it does, bugs fixed and the zstd vs brotli vs zlib-ng comparison.

Source: our fork on GitHub

Directives

zstd #

syntax: zstd on | off;  ·  default: zstd off;  ·  context: http, server, location, if in location

Enables or disables on-the-fly zstd compression for responses. Example: —

zstd_buffers #

syntax: zstd_buffers number size;  ·  default: zstd_buffers 2 <ZSTD_CStreamOutSize()>; (the size is libzstd's recommended streaming output unit, ~128 KB)  ·  context: http, server, location

Configures the number and size of output buffers used during compression. The total buffer space is number × size. Increasing these values allows larger chunks to be accumulated before writing, potentially improving throughput at the cost of higher per-request memory usage. Example: —

zstd_bypass #

syntax: zstd_bypass string ...;  ·  default: —  ·  context: http, server, location

Disables on-the-fly compression for the current request when at least one of the given string parameters evaluates to a non-empty value that is not "0". Each parameter is typically a variable (often driven by a map), so the decision is made per request rather than statically. > > > —

zstd_comp_level #

syntax: zstd_comp_level level;  ·  default: zstd_comp_level 3;  ·  context: http, server, location

Sets the zstd compression level. Accepted values depend on the installed zstd library version: Choosing a level: For most web-serving workloads, levels 1–3 are recommended. Avoid high levels (> 9) in production unless responses are generated infrequently and cached. Example: —

zstd_dict_file #

syntax: zstd_dict_file /path/to/dict;  ·  default: —  ·  context: http

Loads a pre-trained zstd dictionary for use during compression. Dictionaries can significantly improve compression ratios for small, structurally similar responses (e.g. JSON API responses). Example: —

zstd_long #

syntax: zstd_long on | off;  ·  default: zstd_long off;  ·  context: http, server, location

Enables zstd long-distance matching (ZSTD_c_enableLongDistanceMatching). zstd keeps a secondary long-range hash table that finds repeated sequences far beyond the regular match window, which can meaningfully improve the compression ratio on large, internally repetitive bodies — concatenated JSON, HTML with repeated boilerplate, log dumps, sitemaps. Example:

zstd_max_cctx_memory #

syntax: zstd_max_cctx_memory size;  ·  default: — (disabled, no budget enforced)  ·  context: http, server, location

Requires: module built with -DZSTD_STATIC_LINKING_ONLY against libzstd ≥ 1.4.0 (the project's production and CI builds do; see Compatibility). Asserts at config load that the combined zstd parameters configured for the location (zstd_comp_level, zstd_window_log, zstd_long, zstd_target_cblock_size) do not need more than size bytes of parameters to lower. —

zstd_max_length #

syntax: zstd_max_length length;  ·  default: — (no limit)  ·  context: http, server, location

Sets the maximum response size that will be compressed. The limit is enforced in two places: By default there is no upper limit. You may want to set one if very large responses (e.g. multi-megabyte file downloads) should bypass compression to avoid holding the worker process busy. Example: —

zstd_min_length #

syntax: zstd_min_length length;  ·  default: zstd_min_length 20;  ·  context: http, server, location

Sets the minimum response size (in bytes) required for compression to apply. The size is taken from the Content-Length response header; responses without Content-Length are always eligible. Example: —

zstd_static #

syntax: zstd_static on | off | always;  ·  default: zstd_static off;  ·  context: http, server, location

Controls how pre-compressed .zst files are served. When set to on, the module sets r->gzip_vary = 1, which causes nginx to add a Vary: Accept-Encoding response header (controlled by gzip_vary). Enable gzip_vary on; alongside zstd_static on; to ensure correct caching by proxies and CDNs. Example: Pre-compress files with a matching level to your workload: —

zstd_target_cblock_size #

syntax: zstd_target_cblock_size size;  ·  default: — (disabled, uses ZSTD library defaults)  ·  context: http, server, location

Requires: libzstd ≥ v1.5.6 Sets the target compressed block size for zstd frames. Controlling block size improves incremental response parsing, particularly in browsers where CSS/JavaScript in the response head must be available as soon as possible. Example: —

zstd_types #

syntax: zstd_types mime-type ...;  ·  default: zstd_types text/html;  ·  context: http, server, location

Compresses responses with the listed MIME types in addition to text/html. Use * to match all MIME types. Example for a typical web application: —

zstd_window_log #

syntax: zstd_window_log exponent;  ·  default: — (disabled; zstd uses its level-derived default)  ·  context: http, server, location

Caps the zstd compression window at 2^exponent bytes. zstd's per-request working memory is dominated by the window size (roughly the window plus match-table overhead), so without a cap a high compression level on large response bodies lets each concurrent request inflate the worker's resident memory unpredictably. Bounding window_log gives a Example: —

Example

http {
    # Compress text responses for clients that support zstd.
    # Only responses >= 1000 bytes are compressed (smaller ones see no benefit).
    zstd             on;
    zstd_comp_level  3;
    zstd_min_length  1000;
    zstd_types       text/plain text/css application/json
                     application/javascript text/xml application/xml
                     application/xml+rss text/javascript image/svg+xml;

    # Required: emit Vary: Accept-Encoding so proxies/CDNs cache correctly.
    gzip_vary        on;

    server {
        listen 80;
        server_name example.com;

        # Dynamic compression via filter module
        location /api/ {
            proxy_pass http://backend;
        }

        # Serve pre-compressed .zst files for static assets
        location /static/ {
            zstd_static on;
            root /var/www;
        }
    }
}

↑ back to index

ipscrub #

ipscrub is an IP address anonymizer for nginx log files. It's an nginx module that generates an IP-based hash. You can use this hash to link requests from the same source, without identifying your users by IP address.

Source: upstream source

Directives

ipscrub_period_seconds #

syntax: ipscrub_period_seconds 1 arg (integer);  ·  context: http

Set ipscrub_period_seconds <NUM SECONDS PER PERIOD>; (optional). 1.

Example

# Anonymise client IPs in access logs by rotating the salt every hour.
ipscrub_period_seconds 3600;

log_format scrubbed '$remote_addr_ipscrub - [$time_local] "$request" $status';
access_log /var/log/nginx/access.log scrubbed;

↑ back to index

nchan #

<img class="logo" alt="NCHAN" src="https://nchan.io/github-logo.png" />

Source: upstream source

Directives

nchan_access_control_allow_credentials #

syntax: nchan_access_control_allow_credentials 1 arg (on/off flag);  ·  context: http, server, location, location-if

Boolean directive — set to "on" or "off".

nchan_access_control_allow_origin #

syntax: nchan_access_control_allow_origin 1 arg;  ·  context: http, server, location, location-if

nchan_authorize_request #

syntax: nchan_authorize_request 1 arg;  ·  context: server, location, location-if

If a publisher or subscriber request exceeds a group limit, Nchan will respond to it with a 403 Forbidden response. <!– tag:group –> ## Hooks and Callbacks <!– tag:hook –> ### Request Authorization This feature, configured with nchan_authorize_request, behaves just like the Nginx http_auth_request module.

nchan_benchmark #

syntax: nchan_benchmark no args;  ·  context: location

nchan_benchmark_channels #

syntax: nchan_benchmark_channels 1 arg (integer);  ·  context: location

Integer value.

nchan_benchmark_message_padding_bytes #

syntax: nchan_benchmark_message_padding_bytes 1 arg (integer);  ·  context: location

Integer value.

nchan_benchmark_messages_per_channel_per_minute #

syntax: nchan_benchmark_messages_per_channel_per_minute 1 arg (integer);  ·  context: location

Integer value.

nchan_benchmark_publisher_distribution #

syntax: nchan_benchmark_publisher_distribution 1 arg;  ·  context: location

nchan_benchmark_subscriber_distribution #

syntax: nchan_benchmark_subscriber_distribution 1 arg;  ·  context: location

nchan_benchmark_subscribers_per_channel #

syntax: nchan_benchmark_subscribers_per_channel 1 arg (integer);  ·  context: location

Integer value.

nchan_benchmark_time #

syntax: nchan_benchmark_time 1 arg (duration in seconds);  ·  context: location

Duration in seconds; accepts s / m / h / d suffixes.

nchan_channel_event_string #

syntax: nchan_channel_event_string 1 arg;  ·  context: server, location, location-if

Let's see what this channel events subscriber receives when I publish messages to Subscribing to /pubsub/foo produces the channel event Publishing a message to /pubsub/foo: Unsubscribing from /pubsub/foo: Deleting /pubsub/foo (with HTTP DELETE /pubsub/foo): The event string itself is configirable with nchan_channel_event_string.

nchan_channel_events_channel_id #

syntax: nchan_channel_events_channel_id 1 arg;  ·  context: server, location, location-if

nchan_channel_group #

syntax: nchan_channel_group 1 arg;  ·  context: server, location, location-if

(This can be ensured, as above, by setting separate nchan_channel_groups.).

nchan_channel_group_accounting #

syntax: nchan_channel_group_accounting 1 arg (on/off flag);  ·  context: server, location

Can be set with nginx variables. – nchan_channel_group_accounting arguments: 1 default: off context: server, location > Enable tracking channel, subscriber, and message information on a per-channel-group basis.

nchan_channel_id #

syntax: nchan_channel_id 1 arg;  ·  context: server, location, location-if

By default, it is set to $nchan_channel_event $nchan_channel_id.

nchan_channel_id_split_delimiter #

syntax: nchan_channel_id_split_delimiter 1 arg (string);  ·  context: server, location, location-if

Stores a single string value.

nchan_channel_timeout #

syntax: nchan_channel_timeout 1 arg (duration in seconds);  ·  context: http, server, location

This data does not account for information from other Nchan instances, and monitors only local connections, published messages, etc. more details – nchan_channel_timeout arguments: 1 context: http, server, location legacy name: push_channel_timeout > Amount of time an empty channel hangs around.

nchan_deflate_message_for_websocket #

syntax: nchan_deflate_message_for_websocket 1 arg;  ·  context: server, location

Message deflation is enabled by setting the nchan_deflate_message_for_websocket on; directive in a publisher location. <br /> The deflated data is stored alongside the original message in memory, or, if large enough, on disk.

nchan_eventsource_event #

syntax: nchan_eventsource_event 1 arg (string);  ·  context: server, location, location-if

Stores a single string value.

nchan_eventsource_ping_comment #

syntax: nchan_eventsource_ping_comment 1 arg;  ·  context: server, location, location-if

When used in a subscriber location, overrides all messages' associated event: string with the given value. – nchan_eventsource_ping_comment arguments: 1 default: (empty) context: server, location, if > Set the EventSource comment : … line for periodic pings from server to client.

nchan_eventsource_ping_data #

syntax: nchan_eventsource_ping_data 1 arg;  ·  context: server, location, location-if

If empty, no comment is sent with the ping. – nchan_eventsource_ping_data arguments: 1 default: (empty) context: server, location, if > Set the EventSource data: line for periodic pings from server to client.

nchan_eventsource_ping_event #

syntax: nchan_eventsource_ping_event 1 arg;  ·  context: server, location, location-if

If empty, no data is sent with the ping. – nchan_eventsource_ping_event arguments: 1 default: ping context: server, location, if > Set the EventSource event: line for periodic pings from server to client.

nchan_eventsource_ping_interval #

syntax: nchan_eventsource_ping_interval 1 arg (duration in seconds);  ·  context: server, location, location-if

If empty, no event type is sent with the ping. – nchan_eventsource_ping_interval <number> (seconds) arguments: 1 default: 0 (none) context: server, location, if > Interval for sending ping messages to EventSource subscribers.

nchan_group_location #

syntax: nchan_group_location no args;  ·  context: location

To get group data, send a GET request to a nchan_group_location: By default, the data is returned in human-readable plaintext, but can also be formatted as JSON, XML, or YAML: The data in the response are for the single Nchan instance only, regardless of whether Redis is used.

nchan_group_max_channels #

syntax: nchan_group_max_channels 1 arg;  ·  context: location

nchan_group_max_messages #

syntax: nchan_group_max_messages 1 arg;  ·  context: location

nchan_group_max_messages_disk #

syntax: nchan_group_max_messages_disk 1 arg;  ·  context: location

nchan_group_max_messages_memory #

syntax: nchan_group_max_messages_memory 1 arg;  ·  context: location

nchan_group_max_subscribers #

syntax: nchan_group_max_subscribers 1 arg;  ·  context: location

nchan_longpoll_multipart_response #

syntax: nchan_longpoll_multipart_response 1 arg;  ·  context: server, location, location-if

Disabled by default. – nchan_longpoll_multipart_response [ off | on | raw ] arguments: 1 default: off context: server, location, if > when set to 'on', enable sending multiple messages in a single longpoll response, separated using the multipart/mixed content-type scheme.

nchan_max_channel_id_length #

syntax: nchan_max_channel_id_length 1 arg (integer);  ·  context: http, server, location

Integer value.

nchan_max_channel_subscribers #

syntax: nchan_max_channel_subscribers 1 arg (integer);  ·  context: http, server, location

Integer value.

nchan_message_buffer_length #

syntax: nchan_message_buffer_length 1 arg;  ·  context: http, server, location

Used for channel statistics, message storage, and interprocess communication. more details – nchan_store_messages [ on | off ] arguments: 1 default: on context: http, server, location, if legacy name: push_store_messages > Publisher configuration. "off" is equivalent to setting nchan_message_buffer_length 0, which disables the buffering of old messages.

nchan_message_temp_path #

syntax: nchan_message_temp_path 1 arg (filesystem path);  ·  context: http

An Nginx variable can also be used to set the buffer length dynamically. – nchan_message_temp_path <path> arguments: 1 default: <client_body_temp_path> context: http > Large messages are stored in temporary files in the client_body_temp_path or the nchan_message_temp_path if the former is unavailable.

nchan_message_timeout #

syntax: nchan_message_timeout 1 arg;  ·  context: http, server, location

Default is the built-in default client_body_temp_path – nchan_message_timeout [ <time> | <variable> ] arguments: 1 default: 1h context: http, server, location legacy name: push_message_timeout > Publisher configuration setting the length of time a message may be queued before it is considered expired.

nchan_permessage_deflate_compression_level #

syntax: nchan_permessage_deflate_compression_level 1 arg;  ·  context: http

nchan_permessage_deflate_compression_memlevel #

syntax: nchan_permessage_deflate_compression_memlevel 1 arg;  ·  context: http

nchan_permessage_deflate_compression_strategy #

syntax: nchan_permessage_deflate_compression_strategy 1 arg;  ·  context: http

nchan_permessage_deflate_compression_window #

syntax: nchan_permessage_deflate_compression_window 1 arg;  ·  context: http

Use 'default' for normal data, For details see zlib's section on copression strategies – nchan_permessage_deflate_compression_window [ 9-15 ] arguments: 1 default: 10 context: http > Compression window for the deflate algorithm used in websocket's permessage-deflate extension.

nchan_publisher #

syntax: nchan_publisher no args;  ·  context: server, location, location-if

The bigger the window, the better the compression, but the more memory used by the compressor. – nchan_publisher [ http | websocket ] arguments: 0 – 2 default: http websocket context: server, location, if legacy name: push_publisher > Defines a server or location as a publisher endpoint.

nchan_publisher_channel_id #

syntax: nchan_publisher_channel_id 1 arg;  ·  context: server, location, location-if

nchan_publisher_upstream_request #

syntax: nchan_publisher_upstream_request 1 arg;  ·  context: server, location, location-if

Messages received with this subprotocol are of the form <pre> id: message_id content-type: message_content_type \n message_data </pre> The content-type: line may be omitted. <br /> #### Websocket Publisher Messages published through a websocket connection can be forwarded to an upstream application with the nchan_publisher_upstream_request config directive.

nchan_pubsub #

syntax: nchan_pubsub no args;  ·  context: server, location, location-if

Unlike the other subscriber types, the chunked subscriber cannot be used with http/2 because it disallows chunked encoding. <!– tag:subscriber-chunked –> ## PubSub Endpoint PubSub endpoints are Nginx config locations with the nchan_pubsub directive.

nchan_redis_accurate_subscriber_count #

syntax: nchan_redis_accurate_subscriber_count 1 arg (on/off flag);  ·  context: upstream

An Nginx variable can also be used to set the timeout dynamically. – nchan_redis_accurate_subscriber_count arguments: 1 default: off context: upstream > When disabled, use fast but potentially inaccurate subscriber counts.

nchan_redis_cluster_check_interval_backoff #

syntax: nchan_redis_cluster_check_interval_backoff 1 arg;  ·  context: upstream

Defaults to 'off' for legacy reasons, but will be enabled by default in the future. – nchan_redis_cluster_check_interval_backoff <floating point> >= 0, ratio of current delay arguments: 1 default: 2 (increase delay by 200% each try) context: upstream > Add an exponentially increasing delay to the Redis cluster check interval.

nchan_redis_cluster_check_interval_jitter #

syntax: nchan_redis_cluster_check_interval_jitter 1 arg;  ·  context: upstream

nchan_redis_cluster_check_interval_max #

syntax: nchan_redis_cluster_check_interval_max 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_cluster_check_interval_min #

syntax: nchan_redis_cluster_check_interval_min 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_cluster_connect_timeout #

syntax: nchan_redis_cluster_connect_timeout 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_cluster_max_failing_time #

syntax: nchan_redis_cluster_max_failing_time 1 arg (duration in ms);  ·  context: upstream

It will attempt to do this until nchan_redis_cluster_max_failing_time is exceeded.

nchan_redis_cluster_recovery_delay #

syntax: nchan_redis_cluster_recovery_delay 1 arg (duration in ms);  ·  context: upstream

Additionally, recovery attempt delays have configurable jitter, exponential backoff, and maximum values. #### Using Redis securely Redis servers can be connected to via TLS by using the nchan_redis_ssl config setting in an upstream block, or by using the rediss:// schema for the server URLs.

nchan_redis_cluster_recovery_delay_backoff #

syntax: nchan_redis_cluster_recovery_delay_backoff 1 arg;  ·  context: upstream

Additionally, recovery attempt delays have configurable jitter, exponential backoff, and maximum values. #### Using Redis securely Redis servers can be connected to via TLS by using the nchan_redis_ssl config setting in an upstream block, or by using the rediss:// schema for the server URLs.

nchan_redis_cluster_recovery_delay_jitter #

syntax: nchan_redis_cluster_recovery_delay_jitter 1 arg;  ·  context: upstream

Additionally, recovery attempt delays have configurable jitter, exponential backoff, and maximum values. #### Using Redis securely Redis servers can be connected to via TLS by using the nchan_redis_ssl config setting in an upstream block, or by using the rediss:// schema for the server URLs.

nchan_redis_cluster_recovery_delay_max #

syntax: nchan_redis_cluster_recovery_delay_max 1 arg (duration in ms);  ·  context: upstream

Additionally, recovery attempt delays have configurable jitter, exponential backoff, and maximum values. #### Using Redis securely Redis servers can be connected to via TLS by using the nchan_redis_ssl config setting in an upstream block, or by using the rediss:// schema for the server URLs.

nchan_redis_command_timeout #

syntax: nchan_redis_command_timeout 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_connect_timeout #

syntax: nchan_redis_connect_timeout 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_discovered_ip_range_blacklist #

syntax: nchan_redis_discovered_ip_range_blacklist 1 arg;  ·  context: upstream

nchan_redis_fakesub_timer_interval #

syntax: nchan_redis_fakesub_timer_interval 1 arg (duration in ms);  ·  context: http

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_idle_channel_cache_timeout #

syntax: nchan_redis_idle_channel_cache_timeout 1 arg (duration in seconds);  ·  context: http, server, location

Duration in seconds; accepts s / m / h / d suffixes.

nchan_redis_idle_channel_keepalive_backoff #

syntax: nchan_redis_idle_channel_keepalive_backoff 1 arg;  ·  context: upstream

nchan_redis_idle_channel_keepalive_jitter #

syntax: nchan_redis_idle_channel_keepalive_jitter 1 arg;  ·  context: upstream

nchan_redis_idle_channel_keepalive_max #

syntax: nchan_redis_idle_channel_keepalive_max 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_idle_channel_keepalive_min #

syntax: nchan_redis_idle_channel_keepalive_min 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_idle_channel_keepalive_safety_margin #

syntax: nchan_redis_idle_channel_keepalive_safety_margin 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_load_scripts_unconditionally #

syntax: nchan_redis_load_scripts_unconditionally 1 arg (on/off flag);  ·  context: upstream

Boolean directive — set to "on" or "off".

nchan_redis_namespace #

syntax: nchan_redis_namespace 1 arg (string);  ·  context: http, server, location, upstream

All Nchan-related keys in redis will be of the form "nchan_redis_namespace:*" .

nchan_redis_nostore_fastpublish #

syntax: nchan_redis_nostore_fastpublish 1 arg (on/off flag);  ·  context: http, server, upstream

Boolean directive — set to "on" or "off".

nchan_redis_optimize_target #

syntax: nchan_redis_optimize_target 1 arg;  ·  context: upstream

Also from 1.2.0 onward, nchan_redis_optimize_target can be used to prefer optimizing Redis slaves for CPU or bandwidth.

nchan_redis_pass #

syntax: nchan_redis_pass 1 arg;  ·  context: http, server, location

It can also auto-discover and use Redis slaves to balance PUBSUB traffic. <!– commands: nchan_redis_server nchan_redis_pass –> #### Redis Cluster Nchan also supports using Redis Cluster, which adds scalability via sharding channels among cluster nodes.

nchan_redis_pass_inheritable #

syntax: nchan_redis_pass_inheritable 1 arg (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

nchan_redis_password #

syntax: nchan_redis_password 1 arg (string);  ·  context: upstream

A password and optional username for the AUTH command can be set by the nchan_redis_username and nchan_redis_password config settings in an upstream block, or by using the redis://<username>:<password>@hostname server URL schema.

nchan_redis_ping_interval #

syntax: nchan_redis_ping_interval 1 arg (duration in seconds);  ·  context: http, server, location, upstream

All servers in the upstream block will use this password _unless_ a different password is specified by a server URL. – nchan_redis_ping_interval arguments: 1 default: 4m context: http, server, upstream, location > Send a keepalive command to redis to keep the Nchan redis clients from disconnecting.

nchan_redis_publish_msgpacked_max_size #

syntax: nchan_redis_publish_msgpacked_max_size 1 arg (size (k/m/g));  ·  context: http

Size in bytes; accepts k / m / g suffixes.

nchan_redis_reconnect_delay #

syntax: nchan_redis_reconnect_delay 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_reconnect_delay_backoff #

syntax: nchan_redis_reconnect_delay_backoff 1 arg;  ·  context: upstream

nchan_redis_reconnect_delay_jitter #

syntax: nchan_redis_reconnect_delay_jitter 1 arg;  ·  context: upstream

nchan_redis_reconnect_delay_max #

syntax: nchan_redis_reconnect_delay_max 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_retry_commands #

syntax: nchan_redis_retry_commands 1 arg (on/off flag);  ·  context: upstream

Boolean directive — set to "on" or "off".

nchan_redis_retry_commands_max_wait #

syntax: nchan_redis_retry_commands_max_wait 1 arg (duration in ms);  ·  context: upstream

Duration in milliseconds; accepts ms / s / m suffixes.

nchan_redis_server #

syntax: nchan_redis_server 1 arg;  ·  context: upstream

It can also auto-discover and use Redis slaves to balance PUBSUB traffic. <!– commands: nchan_redis_server nchan_redis_pass –> #### Redis Cluster Nchan also supports using Redis Cluster, which adds scalability via sharding channels among cluster nodes.

nchan_redis_ssl #

syntax: nchan_redis_ssl 1 arg (on/off flag);  ·  context: upstream

Additionally, recovery attempt delays have configurable jitter, exponential backoff, and maximum values. #### Using Redis securely Redis servers can be connected to via TLS by using the nchan_redis_ssl config setting in an upstream block, or by using the rediss:// schema for the server URLs.

nchan_redis_ssl_ciphers #

syntax: nchan_redis_ssl_ciphers 1 arg (string);  ·  context: upstream

Stores a single string value.

nchan_redis_ssl_client_certificate #

syntax: nchan_redis_ssl_client_certificate 1 arg (string);  ·  context: upstream

Stores a single string value.

nchan_redis_ssl_client_certificate_key #

syntax: nchan_redis_ssl_client_certificate_key 1 arg (string);  ·  context: upstream

Stores a single string value.

nchan_redis_ssl_server_name #

syntax: nchan_redis_ssl_server_name 1 arg (string);  ·  context: upstream

Stores a single string value.

nchan_redis_ssl_trusted_certificate #

syntax: nchan_redis_ssl_trusted_certificate 1 arg (string);  ·  context: upstream

Defaults to the system's SSL cert path unless nchan_redis_ssl_trusted_certificate is set – nchan_redis_ssl_verify_certificate [ on | off ] arguments: 1 default: on context: upstream > Should the server certificate be verified when using TLS for Redis connections?

nchan_redis_ssl_trusted_certificate_path #

syntax: nchan_redis_ssl_trusted_certificate_path 1 arg (string);  ·  context: upstream

Stores a single string value.

nchan_redis_ssl_verify_certificate #

syntax: nchan_redis_ssl_verify_certificate 1 arg (on/off flag);  ·  context: upstream

Defaults to the system's SSL cert path unless nchan_redis_ssl_trusted_certificate is set – nchan_redis_ssl_verify_certificate [ on | off ] arguments: 1 default: on context: upstream > Should the server certificate be verified when using TLS for Redis connections?

nchan_redis_storage_mode #

syntax: nchan_redis_storage_mode 1 arg;  ·  context: http, server, location, upstream

Useful to disable when testing with a self-signed server certificate. – nchan_redis_storage_mode [ distributed | backup | nostore ] arguments: 1 default: distributed context: http, server, upstream, location > The mode of operation of the Redis server.

nchan_redis_subscribe_weights #

syntax: nchan_redis_subscribe_weights 1 arg;  ·  context: upstream

The nchan_redis_subscribe_weights setting is available to fine-tune this load-balancing.

nchan_redis_upstream_stats #

syntax: nchan_redis_upstream_stats 1 arg;  ·  context: server, location

The response is JSON of the form: For brevity, the entire command_totals hash is omitted in this documentation. <!– commands: nchan_redis_upstream_stats nchan_redis_upstream_stats_disconnected_timeout nchan_redis_upstream_stats_enabled –> ## Introspection There are several ways to see what's happening inside Nchan.

nchan_redis_upstream_stats_disconnected_timeout #

syntax: nchan_redis_upstream_stats_disconnected_timeout 1 arg (on/off flag);  ·  context: upstream

The response is JSON of the form: For brevity, the entire command_totals hash is omitted in this documentation. <!– commands: nchan_redis_upstream_stats nchan_redis_upstream_stats_disconnected_timeout nchan_redis_upstream_stats_enabled –> ## Introspection There are several ways to see what's happening inside Nchan.

nchan_redis_upstream_stats_enabled #

syntax: nchan_redis_upstream_stats_enabled 1 arg (on/off flag);  ·  context: upstream

The response is JSON of the form: For brevity, the entire command_totals hash is omitted in this documentation. <!– commands: nchan_redis_upstream_stats nchan_redis_upstream_stats_disconnected_timeout nchan_redis_upstream_stats_enabled –> ## Introspection There are several ways to see what's happening inside Nchan.

nchan_redis_url #

syntax: nchan_redis_url 1 arg;  ·  context: http, server, location

nchan_redis_username #

syntax: nchan_redis_username 1 arg (string);  ·  context: upstream

A password and optional username for the AUTH command can be set by the nchan_redis_username and nchan_redis_password config settings in an upstream block, or by using the redis://<username>:<password>@hostname server URL schema.

nchan_redis_wait_after_connecting #

syntax: nchan_redis_wait_after_connecting 1 arg;  ·  context: http, server, location

nchan_shared_memory_size #

syntax: nchan_shared_memory_size 1 arg;  ·  context: http

The size of the memory segment is configured with nchan_shared_memory_size.

nchan_storage_engine #

syntax: nchan_storage_engine 1 arg;  ·  context: http, server, location

Don't mess with this setting unless you know what you are doing! – nchan_storage_engine [ memory | redis ] arguments: 1 default: memory context: http, server, location > Development directive to completely replace default storage engine.

nchan_store_messages #

syntax: nchan_store_messages 1 arg;  ·  context: http, server, location, location-if

Used for channel statistics, message storage, and interprocess communication. more details – nchan_store_messages [ on | off ] arguments: 1 default: on context: http, server, location, if legacy name: push_store_messages > Publisher configuration. "off" is equivalent to setting nchan_message_buffer_length 0, which disables the buffering of old messages.

nchan_stub_status #

syntax: nchan_stub_status no args;  ·  context: location

This string can use any Nginx and Nchan variables. ### nchan_stub_status Stats Like Nginx's stub_status, nchan_stub_status is used to get performance metrics.

nchan_subscribe_existing_channels_only #

syntax: nchan_subscribe_existing_channels_only 1 arg (on/off flag);  ·  context: http, server, location

Does not include subscribers on other Nchan instances when using a shared Redis server. – nchan_subscribe_existing_channels_only [ on | off ] arguments: 1 default: off context: http, server, location legacy name: push_authorized_channels_only > Whether or not a subscriber may create a channel by sending a request to a subscriber location.

nchan_subscribe_request #

syntax: nchan_subscribe_request 1 arg;  ·  context: server, location, location-if

Without additional configuration, this turns a location into an echo server. more details – nchan_subscribe_request <url> arguments: 1 context: server, location, if > Send GET request to internal location (which may proxy to an upstream server) after subscribing.

nchan_subscriber #

syntax: nchan_subscriber no args;  ·  context: server, location, location-if

This can be used to erase messages or to scale an existing channel's message buffer as desired. ## Subscriber Endpoints Subscriber endpoints are Nginx config locations with the nchan_subscriber directive.

nchan_subscriber_channel_id #

syntax: nchan_subscriber_channel_id 1 arg;  ·  context: server, location, location-if

The queue is traversed automatically, starting at the position defined by the nchan_subscriber_first_message setting. > The value is a list of permitted subscriber types. more details – nchan_subscriber_channel_id arguments: 1 – 7 default: (none) context: server, location, if > Channel id for subscriber location.

nchan_subscriber_compound_etag_message_id #

syntax: nchan_subscriber_compound_etag_message_id 1 arg (on/off flag);  ·  context: server, location, location-if

Boolean directive — set to "on" or "off".

nchan_subscriber_first_message #

syntax: nchan_subscriber_first_message 1 arg;  ·  context: server, location, location-if

Sending a request without a "If-Modified-Since" or "If-None-Match" headers returns the oldest message in a channel's message queue, or waits until the next published message, depending on the value of the nchan_subscriber_first_message config directive.

nchan_subscriber_http_raw_stream_separator #

syntax: nchan_subscriber_http_raw_stream_separator 1 arg;  ·  context: server, location, location-if

Messages are appended to the response body, separated by a newline or configurable by nchan_subscriber_http_raw_stream_separator. <!– tag:subscriber-rawstream –> – ### HTTP Chunked Transfer This subscription method uses the chunked Transfer-Encoding to receive messages.

nchan_subscriber_info #

syntax: nchan_subscriber_info no args;  ·  context: location

Automatically terminated with a newline character if not explicitly set to an empty string. – nchan_subscriber_info arguments: 0 context: location > A subscriber location for debugging the state of subscribers on a given channel.

nchan_subscriber_info_string #

syntax: nchan_subscriber_info_string 1 arg;  ·  context: server, location

The subscribers of the channel specified by nchan_channel_id evaluate nchan_subscriber_info_string and send it back to the requested on this location.

nchan_subscriber_last_message_id #

syntax: nchan_subscriber_last_message_id 1 arg;  ·  context: server, location, location-if

This behavior can be configured via the nchan_subscriber_last_message_id config.

nchan_subscriber_message_id_custom_etag_header #

syntax: nchan_subscriber_message_id_custom_etag_header 1 arg (string);  ·  context: server, location, location-if

Used primarily as a workaround for the inability to set the first Last-Message-Id of a web browser's EventSource object. – nchan_subscriber_message_id_custom_etag_header arguments: 1 default: (none) context: server, location, if > Use a custom header instead of the Etag header for message ID in subscriber responses.

nchan_subscriber_timeout #

syntax: nchan_subscriber_timeout 1 arg (duration in seconds);  ·  context: http, server, location, location-if

Duration in seconds; accepts s / m / h / d suffixes.

nchan_unsubscribe_request #

syntax: nchan_unsubscribe_request 1 arg;  ·  context: server, location, location-if

These should point to Nginx locations configured to forward requests to an upstream proxy (your application): In order for nchan_unsubscribe_request to work correctly, the location it points to must have proxy_ignore_client_abort on;.

nchan_use_redis #

syntax: nchan_use_redis 1 arg;  ·  context: http, server, location

Nchan can also be scaled out to multiple Nginx instances using the Redis storage engine, and that too can be scaled up beyond a single-point-of-failure by using Redis Cluster. ## Install #### Download Packages – Arch Linux: nginx-mod-nchan and nginx-mainline-mod-nchan are available in the Arch User Repository. – Mac OS X: a homebrew package is available.

nchan_websocket_client_heartbeat #

syntax: nchan_websocket_client_heartbeat 2 args;  ·  context: server, location, location-if

Disabled for longpoll and interval-polling subscribers. more details – nchan_websocket_client_heartbeat <heartbeat_in> <heartbeat_out> arguments: 2 default: none (disabled) context: server, location, if > Most browser Websocket clients do not allow manually sending PINGs to the server.

nchan_websocket_ping_interval #

syntax: nchan_websocket_ping_interval 1 arg (duration in seconds);  ·  context: server, location, location-if

Server-initiated keep-alive pings can be configured with the nchan_websocket_ping_interval config directive.

push_min_message_buffer_length #

syntax: push_min_message_buffer_length 1 arg;  ·  context: server, location, location-if

push_subscriber_concurrency #

syntax: push_subscriber_concurrency 1 arg;  ·  context: server, location, location-if

Example

  #enable group accounting
  nchan_channel_group_accounting on;
  
  location ~ /pubsub/(\w+)$ {
    nchan_pubsub;
    nchan_channel_group "limited";
    nchan_channel_id $1;
  }
  
  location ~ /prelimited_pubsub/(\w+)$ {
    nchan_pubsub;
    nchan_channel_group "limited";
    nchan_channel_id $1;
    nchan_group_max_subscribers 100;
    nchan_group_max_messages_memory 50M;
  }
  
  location /group {
    nchan_channel_group limited;
    nchan_group_location;
    nchan_group_max_channels $arg_max_channels;
    nchan_group_max_messages $arg_max_messages;
    nchan_group_max_messages_memory $arg_max_messages_mem;
    nchan_group_max_messages_disk $arg_max_messages_disk;
    nchan_group_max_subscribers $arg_max_subs;
  }

↑ back to index

njs #

NGINX JavaScript — embed real JavaScript into request handling (<code>js_set</code>, <code>js_content</code>, <code>js_body_filter</code>, <code>js_periodic</code>, …) for routing, header rewriting, dynamic auth and response transformation. <strong>Built against QuickJS-NG</strong> instead of njs&rsquo;s native interpreter, so the language surface is full ES2023: real <code>async</code>/<code>await</code>, <code>BigInt</code>, <code>Proxy</code>, ES modules with dynamic <code>import()</code>, modern regex (lookbehind, <code>\p{…}</code>) and a working <code>Intl</code>. You stop hitting &ldquo;njs doesn&rsquo;t have that&rdquo; walls when porting code from Node or MDN.

Source: upstream source

Directives

js_access #

syntax: js_access 1 arg;  ·  context: location, location-if, limit_except

js_body_filter #

syntax: js_body_filter 1 arg;  ·  context: location, location-if, limit_except

js_content #

syntax: js_content 1 arg;  ·  context: location, location-if, limit_except

js_context_reuse #

syntax: js_context_reuse 1 arg (size (k/m/g));  ·  context: http, server, location

Size in bytes; accepts k / m / g suffixes.

js_context_reuse_max_size #

syntax: js_context_reuse_max_size 1 arg (size (k/m/g));  ·  context: http, server, location

Size in bytes; accepts k / m / g suffixes.

js_engine #

syntax: js_engine 1 arg;  ·  context: http, server, location

js_fetch_buffer_size #

syntax: js_fetch_buffer_size 1 arg (size (k/m/g));  ·  context: http, server, location

Size in bytes; accepts k / m / g suffixes.

js_fetch_ciphers #

syntax: js_fetch_ciphers 1 arg (string);  ·  context: http, server, location

Stores a single string value.

js_fetch_keepalive #

syntax: js_fetch_keepalive 1 arg (integer);  ·  context: http, server, location

Integer value.

js_fetch_keepalive_requests #

syntax: js_fetch_keepalive_requests 1 arg (integer);  ·  context: http, server, location

Integer value.

js_fetch_keepalive_time #

syntax: js_fetch_keepalive_time 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

js_fetch_keepalive_timeout #

syntax: js_fetch_keepalive_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

js_fetch_max_response_buffer_size #

syntax: js_fetch_max_response_buffer_size 1 arg (size (k/m/g));  ·  context: http, server, location

Size in bytes; accepts k / m / g suffixes.

js_fetch_protocols #

syntax: js_fetch_protocols 1+ args (bitmask);  ·  context: http, server, location

Bitmask — combine several keywords.

js_fetch_proxy #

syntax: js_fetch_proxy 1 arg;  ·  context: http, server, location

js_fetch_timeout #

syntax: js_fetch_timeout 1 arg (duration in ms);  ·  context: http, server, location

Duration in milliseconds; accepts ms / s / m suffixes.

js_fetch_trusted_certificate #

syntax: js_fetch_trusted_certificate 1 arg (string);  ·  context: http, server, location

Stores a single string value.

js_fetch_verify #

syntax: js_fetch_verify on | off (on/off flag);  ·  context: http, server, location

Boolean directive — set to "on" or "off".

js_fetch_verify_depth #

syntax: js_fetch_verify_depth 1 arg (integer);  ·  context: http, server, location

Integer value.

js_filter #

syntax: js_filter 1 arg (string);  ·  context: stream, stream/server

Stores a single string value.

js_header_filter #

syntax: js_header_filter 1 arg (string);  ·  context: location, location-if, limit_except

Stores a single string value.

js_import #

syntax: js_import 1 arg;  ·  context: http, server, location

js_load_http_native_module #

syntax: js_load_http_native_module 1 arg;  ·  context: main

js_load_stream_native_module #

syntax: js_load_stream_native_module 1 arg;  ·  context: main

js_path #

syntax: js_path 1 arg (list of strings);  ·  context: http, server, location

Appends a string to a list; may be specified multiple times.

js_periodic #

syntax: js_periodic any args;  ·  context: location

js_preload_object #

syntax: js_preload_object 1 arg;  ·  context: http, server, location

js_preread #

syntax: js_preread 1 arg (string);  ·  context: stream, stream/server

Stores a single string value.

js_set #

syntax: js_set 2 args;  ·  context: http, server, location

js_shared_dict_zone #

syntax: js_shared_dict_zone 1+ args;  ·  context: http

js_var #

syntax: js_var 1 arg;  ·  context: http, server, location

Example

# Load the ngx_http_js_module module
load_module modules/ngx_http_js_module.so;

events {}

http {
  # Set the path to our njs JavaScript files
  js_path "/etc/nginx/njs/";

  # Import our JavaScript file into the variable "main"
  js_import main from http/hello.js;

  server {
    listen 80;

    location / {
      # Execute the "hello" function defined in our JavaScript file on all HTTP requests
      # and respond with the contents of our function.
      js_content main.hello;
    }
  }
}

↑ back to index

rtmp #

playing from local filesystem or HTTP

Source: upstream source

Directives

access_log #

syntax: access_log 1 arg;

ack_window #

syntax: ack_window 1 arg (integer);

Integer value.

allow #

syntax: allow 1 arg;

application #

syntax: application 1 arg;

These features are not supported execs static pulls * auto_push ### RTMP URL format rtmp://rtmp.example.com/app[/name] app – should match one of application {} blocks in config name – interpreted by each application can be empty ### Multi-worker live streaming Module supports multi-worker live streaming through automatic stream pushing to nginx workers.

buffer #

syntax: buffer 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

buflen #

syntax: buflen 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

busy #

syntax: busy 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

chunk_size #

syntax: chunk_size 1 arg (integer);

Integer value.

dash #

syntax: dash 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

dash_cleanup #

syntax: dash_cleanup 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

dash_fragment #

syntax: dash_fragment 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

dash_nested #

syntax: dash_nested 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

dash_path #

syntax: dash_path 1 arg (string);

Stores a single string value.

dash_playlist_length #

syntax: dash_playlist_length 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

deny #

syntax: deny 1 arg;

drop_idle_publisher #

syntax: drop_idle_publisher 1 arg;

exec #

syntax: exec 1+ args;

{ ngx_string("exec_block"), NGX_RTMP_APP_CONF|NGX_CONF_BLOCK|NGX_CONF_NOARGS|NGX_CONF_TAKE1, ngx_rtmp_exec_block, NGX_RTMP_APP_CONF_OFFSET, 0, NULL },

exec_kill_signal #

syntax: exec_kill_signal 1 arg;

exec_options #

syntax: exec_options 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

exec_play #

syntax: exec_play 1+ args;

exec_play_done #

syntax: exec_play_done 1+ args;

exec_publish #

syntax: exec_publish 1+ args;

exec_publish_done #

syntax: exec_publish_done 1+ args;

exec_pull #

syntax: exec_pull 1+ args;

exec_push #

syntax: exec_push 1+ args;

exec_record_done #

syntax: exec_record_done 1+ args;

exec_static #

syntax: exec_static 1+ args;

hls #

syntax: hls 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

hls_audio_buffer_size #

syntax: hls_audio_buffer_size 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

hls_base_url #

syntax: hls_base_url 1 arg (string);

Stores a single string value.

hls_cleanup #

syntax: hls_cleanup 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

hls_continuous #

syntax: hls_continuous 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

hls_fragment #

syntax: hls_fragment 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_fragment_naming #

syntax: hls_fragment_naming 1 arg (enum);

Pick one of an enumerated set of values.

hls_fragment_naming_granularity #

syntax: hls_fragment_naming_granularity 1 arg (integer);

Integer value.

hls_fragment_slicing #

syntax: hls_fragment_slicing 1 arg (enum);

Pick one of an enumerated set of values.

hls_fragments_per_key #

syntax: hls_fragments_per_key 1 arg (integer);

Integer value.

hls_key_path #

syntax: hls_key_path 1 arg (string);

Stores a single string value.

hls_key_url #

syntax: hls_key_url 1 arg (string);

Stores a single string value.

hls_keys #

syntax: hls_keys 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

hls_max_audio_delay #

syntax: hls_max_audio_delay 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_max_fragment #

syntax: hls_max_fragment 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_muxdelay #

syntax: hls_muxdelay 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_nested #

syntax: hls_nested 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

hls_path #

syntax: hls_path 1 arg (string);

Stores a single string value.

hls_playlist_length #

syntax: hls_playlist_length 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_sync #

syntax: hls_sync 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

hls_type #

syntax: hls_type 1 arg (enum);

Pick one of an enumerated set of values.

hls_variant #

syntax: hls_variant 1+ args;

idle_streams #

syntax: idle_streams 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

interleave #

syntax: interleave 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

listen #

syntax: listen 1 arg;

live #

syntax: live 1 arg (on/off flag);

These features are not supported execs static pulls * auto_push ### RTMP URL format rtmp://rtmp.example.com/app[/name] app – should match one of application {} blocks in config name – interpreted by each application can be empty ### Multi-worker live streaming Module supports multi-worker live streaming through automatic stream pushing to nginx workers.

log_format #

syntax: log_format 2+ args;

max_connections #

syntax: max_connections 1 arg (integer);

Integer value.

max_message #

syntax: max_message 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

max_streams #

syntax: max_streams 1 arg (integer);

Integer value.

meta #

syntax: meta 1 arg (enum);

Pick one of an enumerated set of values.

netcall_buffer #

syntax: netcall_buffer 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

netcall_timeout #

syntax: netcall_timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

notify_method #

syntax: notify_method 1 arg;

notify_relay_redirect #

syntax: notify_relay_redirect 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

notify_update_strict #

syntax: notify_update_strict 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

notify_update_timeout #

syntax: notify_update_timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

on_connect #

syntax: on_connect 1 arg;

on_disconnect #

syntax: on_disconnect 1 arg;

on_done #

syntax: on_done 1 arg;

on_play #

syntax: on_play 1 arg;

on_play_done #

syntax: on_play_done 1 arg;

on_publish #

syntax: on_publish 1 arg;

on_publish_done #

syntax: on_publish_done 1 arg;

on_record_done #

syntax: on_record_done 1 arg;

on_update #

syntax: on_update 1 arg;

out_cork #

syntax: out_cork 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

out_queue #

syntax: out_queue 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

ping #

syntax: ping 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

ping_timeout #

syntax: ping_timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

play #

syntax: play 1+ args;

play_local_path #

syntax: play_local_path 1 arg (string);

Stores a single string value.

play_restart #

syntax: play_restart 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

play_temp_path #

syntax: play_temp_path 1 arg (string);

Stores a single string value.

play_time_fix #

syntax: play_time_fix 1 arg (on/off flag);

time fixes are needed for flash clients

publish_notify #

syntax: publish_notify 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

publish_time_fix #

syntax: publish_time_fix 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

pull #

syntax: pull 1+ args;

pull_reconnect #

syntax: pull_reconnect 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

push #

syntax: push 1+ args;

push_reconnect #

syntax: push_reconnect 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

record #

syntax: record 1+ args (bitmask);

Bitmask — combine several keywords.

record_append #

syntax: record_append 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

record_interval #

syntax: record_interval 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

record_lock #

syntax: record_lock 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

record_max_frames #

syntax: record_max_frames 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

record_max_size #

syntax: record_max_size 1 arg (size (k/m/g));

Size in bytes; accepts k / m / g suffixes.

record_notify #

syntax: record_notify 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

record_path #

syntax: record_path 1 arg (string);

Stores a single string value.

record_suffix #

syntax: record_suffix 1 arg (string);

Stores a single string value.

record_unique #

syntax: record_unique 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

recorder #

syntax: recorder 1 arg;

relay_buffer #

syntax: relay_buffer 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

respawn #

syntax: respawn 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

respawn_timeout #

syntax: respawn_timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

rtmp #

syntax: rtmp no args;  ·  context: main

These features are not supported execs static pulls * auto_push ### RTMP URL format rtmp://rtmp.example.com/app[/name] app – should match one of application {} blocks in config name – interpreted by each application can be empty ### Multi-worker live streaming Module supports multi-worker live streaming through automatic stream pushing to nginx workers.

rtmp_auto_push #

syntax: rtmp_auto_push 1 arg (on/off flag);  ·  context: main

Boolean directive — set to "on" or "off".

rtmp_auto_push_reconnect #

syntax: rtmp_auto_push_reconnect 1 arg (duration in ms);  ·  context: main

Duration in milliseconds; accepts ms / s / m suffixes.

rtmp_control #

syntax: rtmp_control 1+ args;  ·  context: http, server, location

rtmp_socket_dir #

syntax: rtmp_socket_dir 1 arg (string);  ·  context: main

Stores a single string value.

rtmp_stat #

syntax: rtmp_stat 1+ args;  ·  context: http, server, location

rtmp_stat_stylesheet #

syntax: rtmp_stat_stylesheet 1 arg (string);  ·  context: http, server, location

Stores a single string value.

server #

syntax: server no args;

session_relay #

syntax: session_relay 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

so_keepalive #

syntax: so_keepalive on | off (on/off flag);

Boolean directive — set to "on" or "off".

stream_buckets #

syntax: stream_buckets 1 arg (string);

Stores a single string value.

sync #

syntax: sync 1 arg;

timeout #

syntax: timeout 1 arg (duration in ms);

Duration in milliseconds; accepts ms / s / m suffixes.

wait_key #

syntax: wait_key 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

wait_video #

syntax: wait_video 1 arg (on/off flag);

Boolean directive — set to "on" or "off".

Example

worker_processes  1;

error_log  logs/error.log debug;

events {
    worker_connections  1024;
}

rtmp {
    server {
        listen 1935;

        application myapp {
            live on;

            #record keyframes;
            #record_path /tmp;
            #record_max_size 128K;
            #record_interval 30s;
            #record_suffix .this.is.flv;

            #on_publish http://localhost:8080/publish;
            #on_play http://localhost:8080/play;
            #on_record_done http://localhost:8080/record_done;
        }
    }
}

http {
    server {
        listen      8080;

        location /stat {
            rtmp_stat all;
            rtmp_stat_stylesheet stat.xsl;
        }

        location /stat.xsl {
            root /path/to/nginx-rtmp-module/;
        }

        location /control {
            rtmp_control all;
        }

        #location /publish {
        #    return 201;
        #}

        #location /play {
        #    return 202;
        #}

        #location /record_done {
        #    return 203;
        #}

        location /rtmp-publisher {
            root /path/to/nginx-rtmp-module/test;
        }

        location / {
            root /path/to/nginx-rtmp-module/test/www;
        }
    }
}

↑ back to index

ssl-ct #

Certificate Transparency module — attaches SCTs (Signed Certificate Timestamps) to the TLS handshake so browsers can verify the cert was logged with public CT logs.

Source: upstream source

No nginx directives detected.

↑ back to index

stream-lua #

ngx_stream_lua_module – Embed the power of Lua into Nginx stream/TCP Servers.

Source: upstream source

Directives

balancer_by_lua_block #

syntax: balancer_by_lua_block no args;  ·  context: stream/upstream

balancer_by_lua_file #

syntax: balancer_by_lua_file 1 arg;  ·  context: stream/upstream

content_by_lua #

syntax: content_by_lua 1 arg;  ·  context: stream/server

content_by_lua "<inline script>"

content_by_lua_block #

syntax: content_by_lua_block no args;  ·  context: stream/server

content_by_lua_block { <inline script> }

content_by_lua_file #

syntax: content_by_lua_file 1 arg;  ·  context: stream/server

content_by_lua_file rel/or/abs/path/to/script

init_by_lua #

syntax: init_by_lua 1 arg;  ·  context: stream

init_by_lua_block #

syntax: init_by_lua_block no args;  ·  context: stream

init_by_lua_file #

syntax: init_by_lua_file 1 arg;  ·  context: stream

init_worker_by_lua #

syntax: init_worker_by_lua 1 arg;  ·  context: stream

init_worker_by_lua_block #

syntax: init_worker_by_lua_block no args;  ·  context: stream

init_worker_by_lua_file #

syntax: init_worker_by_lua_file 1 arg;  ·  context: stream

log_by_lua_block #

syntax: log_by_lua_block no args;  ·  context: stream, stream/server

This directive was first introduced in the v0.0.3 release. Back to TOC log_by_lua_block —————- syntax: log_by_lua_block { lua-script } context: stream, server phase: log Runs the Lua source code specified as <lua-script> during the log request processing phase.

log_by_lua_file #

syntax: log_by_lua_file 1 arg;  ·  context: stream, stream/server

This directive was first introduced in the v0.0.3 release. Back to TOC log_by_lua_file ————— syntax: log_by_lua_file &lt;path-to-lua-script-file&gt; context: stream, server phase: log Equivalent to log_by_lua_block, except that the file specified by <path-to-lua-script-file> contains the Lua code or LuaJIT bytecode to be executed.

lua_add_variable #

syntax: lua_add_variable 1 arg;  ·  context: stream

This directive was first introduced in the v0.0.3 release. Back to TOC lua_add_variable —————- syntax: lua_add_variable $var context: stream Add the variable $var to the "stream" subsystem and makes it changeable.

lua_capture_error_log #

syntax: lua_capture_error_log 1 arg;  ·  context: stream

lua_check_client_abort #

syntax: lua_check_client_abort on | off (on/off flag);  ·  context: stream, stream/server

Boolean directive — set to "on" or "off".

lua_code_cache #

syntax: lua_code_cache on | off;  ·  context: stream, stream/server

The Lua code cache can be temporarily disabled during development by switching lua_code_cache off in nginx.conf to avoid having to reload Nginx.

lua_load_resty_core #

syntax: lua_load_resty_core on | off;  ·  context: stream

lua_malloc_trim #

syntax: lua_malloc_trim 1 arg;  ·  context: stream

NGX_STREAM_SSL

lua_max_pending_timers #

syntax: lua_max_pending_timers 1 arg (integer);  ·  context: stream

Integer value.

lua_max_running_timers #

syntax: lua_max_running_timers 1 arg (integer);  ·  context: stream

Integer value.

lua_package_cpath #

syntax: lua_package_cpath 1 arg;  ·  context: stream

lua_package_path #

syntax: lua_package_path 1 arg;  ·  context: stream

lua_regex_cache_max_entries #

syntax: lua_regex_cache_max_entries 1 arg (integer);  ·  context: stream

Integer value.

lua_regex_match_limit #

syntax: lua_regex_match_limit 1 arg (integer);  ·  context: stream

Integer value.

lua_sa_restart #

syntax: lua_sa_restart on | off (on/off flag);  ·  context: stream

Boolean directive — set to "on" or "off".

lua_shared_dict #

syntax: lua_shared_dict 2 args;  ·  context: stream

lua_socket_buffer_size #

syntax: lua_socket_buffer_size 1 arg (size (k/m/g));  ·  context: stream, stream/server

Size in bytes; accepts k / m / g suffixes.

lua_socket_connect_timeout #

syntax: lua_socket_connect_timeout 1 arg (duration in ms);  ·  context: stream, stream/server

Duration in milliseconds; accepts ms / s / m suffixes.

lua_socket_keepalive_timeout #

syntax: lua_socket_keepalive_timeout 1 arg (duration in ms);  ·  context: stream, stream/server

Duration in milliseconds; accepts ms / s / m suffixes.

lua_socket_log_errors #

syntax: lua_socket_log_errors on | off (on/off flag);  ·  context: stream, stream/server

Boolean directive — set to "on" or "off".

lua_socket_pool_size #

syntax: lua_socket_pool_size 1 arg (integer);  ·  context: stream, stream/server

Integer value.

lua_socket_read_timeout #

syntax: lua_socket_read_timeout 1 arg (duration in ms);  ·  context: stream, stream/server

Duration in milliseconds; accepts ms / s / m suffixes.

lua_socket_send_lowat #

syntax: lua_socket_send_lowat 1 arg (size (k/m/g));  ·  context: stream, stream/server

Size in bytes; accepts k / m / g suffixes.

lua_socket_send_timeout #

syntax: lua_socket_send_timeout 1 arg (duration in ms);  ·  context: stream, stream/server

Duration in milliseconds; accepts ms / s / m suffixes.

lua_ssl_certificate #

syntax: lua_ssl_certificate 1 arg (list of strings);  ·  context: stream, stream/server

Appends a string to a list; may be specified multiple times.

lua_ssl_certificate_key #

syntax: lua_ssl_certificate_key 1 arg (list of strings);  ·  context: stream, stream/server

Appends a string to a list; may be specified multiple times.

lua_ssl_ciphers #

syntax: lua_ssl_ciphers 1 arg (string);  ·  context: stream, stream/server

Stores a single string value.

lua_ssl_conf_command #

syntax: lua_ssl_conf_command 2 args (key value pair);  ·  context: stream, stream/server

Stores a key/value pair.

lua_ssl_crl #

syntax: lua_ssl_crl 1 arg (string);  ·  context: stream, stream/server

Stores a single string value.

lua_ssl_key_log #

syntax: lua_ssl_key_log 1 arg (string);  ·  context: stream, stream/server

Stores a single string value.

lua_ssl_protocols #

syntax: lua_ssl_protocols 1+ args (bitmask);  ·  context: stream, stream/server

Bitmask — combine several keywords.

lua_ssl_trusted_certificate #

syntax: lua_ssl_trusted_certificate 1 arg (string);  ·  context: stream, stream/server

Stores a single string value.

lua_ssl_verify_depth #

syntax: lua_ssl_verify_depth 1 arg (integer);  ·  context: stream, stream/server

Integer value.

lua_upstream_skip_openssl_default_verify #

syntax: lua_upstream_skip_openssl_default_verify on | off (on/off flag);  ·  context: stream/server

Boolean directive — set to "on" or "off".

preread_by_lua_block #

syntax: preread_by_lua_block no args;  ·  context: stream, stream/server

The preread_by_lua_block code will always run at the end of the preread processing phase unless preread\_by\_lua\_no\_postpone is turned on.

preread_by_lua_file #

syntax: preread_by_lua_file 1 arg;  ·  context: stream, stream/server

preread_by_lua_file rel/or/abs/path/to/script

preread_by_lua_no_postpone #

syntax: preread_by_lua_no_postpone on | off (on/off flag);  ·  context: stream

The preread_by_lua_block code will always run at the end of the preread processing phase unless preread\_by\_lua\_no\_postpone is turned on.

proxy_ssl_certificate_by_lua_block #

syntax: proxy_ssl_certificate_by_lua_block no args;  ·  context: stream/server

same context as proxy_pass directive

proxy_ssl_certificate_by_lua_file #

syntax: proxy_ssl_certificate_by_lua_file 1 arg;  ·  context: stream/server

proxy_ssl_verify_by_lua_block #

syntax: proxy_ssl_verify_by_lua_block no args;  ·  context: stream/server

proxy_ssl_verify_by_lua_file #

syntax: proxy_ssl_verify_by_lua_file 1 arg;  ·  context: stream/server

ssl_certificate_by_lua_block #

syntax: ssl_certificate_by_lua_block no args;  ·  context: stream, stream/server

ssl_certificate_by_lua_file #

syntax: ssl_certificate_by_lua_file 1 arg;  ·  context: stream, stream/server

ssl_client_hello_by_lua_block #

syntax: ssl_client_hello_by_lua_block no args;  ·  context: stream, stream/server

ssl_client_hello_by_lua_file #

syntax: ssl_client_hello_by_lua_file 1 arg;  ·  context: stream, stream/server

Example

    location = /back {
        lua_socket_log_errors on;
        content_by_lua_block {
            ngx.send_headers()
            ngx.flush(true)

            local sock, err = ngx.req.socket()

            if not sock then
               ngx.say("failed to get socket: ", err)
               return nil
            end

            sock:settimeout(100);

            local reader = sock:receiveuntil("no-such-terminator")
            local data, err, partial = reader()
            if not data then
               ngx.say("err: ", err, ", partial: ", partial)
            else
                ngx.say("received: ", data)
            end

            ngx.sleep(0.1)

            local data, err, partial = sock:receive()
            if err then
               ngx.say("err: ", err, ", partial: ", partial)
            else
                ngx.say("received: ", data)
            end
        }
    }

↑ back to index

stream-sts #

Nginx stream server traffic status module

Source: upstream source

Directives

stream_server_traffic_status #

syntax: stream_server_traffic_status on | off (on/off flag);  ·  context: http, server, location

Description: Enables or disables the module working. If you set stream_server_traffic_status_zone directive, is automatically enabled.

stream_server_traffic_status_average_method #

syntax: stream_server_traffic_status_average_method 1 arg;  ·  context: http, server, location

Description: Sets the method which is a formula that calculate the average of response processing times. The period is an effective time of the values used for the average calculation.(Default: 60s) If period set to 0, effective time is ignored. In this case, the last average value is displayed even if there is no requests and after the elapse of time.

stream_server_traffic_status_display #

syntax: stream_server_traffic_status_display no args;  ·  context: server, location

Description: Enables or disables the module display handler.

stream_server_traffic_status_display_format #

syntax: stream_server_traffic_status_display_format 1 arg (enum);  ·  context: server, location

Description: Sets the display handler's output format. If you set json, will respond with a JSON document. If you set html, will respond with the built-in live dashboard in HTML. If you set jsonp, will respond with a JSONP callback function(default: ngx_http_stream_server_traffic_status_jsonp_callback).

stream_server_traffic_status_display_jsonp #

syntax: stream_server_traffic_status_display_jsonp 1 arg (string);  ·  context: server, location

Description: Sets the callback name for the JSONP.

stream_server_traffic_status_zone #

syntax: stream_server_traffic_status_zone no args;  ·  context: http

Description: Sets parameters for a shared memory zone specified by server_traffic_status_zone directive in stream block. Caveats: The name must be same as specified by server_traffic_status_zone.

Example

http {

    stream_server_traffic_status_zone;

    ...

    server {

        server_name example.org;

        ...


        location /status {
            stream_server_traffic_status_display;
            stream_server_traffic_status_display_format html;
        }
    }                                                                                                                                                                                           }
}

stream {
    geoip_country    /usr/share/GeoIP/GeoIP.dat;

    server_traffic_status_zone;

    server_traffic_status_filter_by_set_key $geoip_country_code country::*;

    server {

        ...

    }

    ...

}

↑ back to index