Introduction to Map command

The Map directive is a directive in the NGINX configuration file. It is used to create custom variables during request processing and map values according to the specified key-value mapping relationship. The Map directive is provided by the ngx_http_map_module module, which is installed by default when installing NGINX. The Map directive can be used in many scenarios, such as generating rewrite rules based on the request path, determining whether to enable caching based on the request header, configuring different backend services based on query parameters, etc.

Three parameters of the Map directive:

1. default: Specify the default value that will be used when the source variable cannot match any expression. When default is not set, an empty string will be used as the default result;

2. hostnames: allows the domain name to be specified as the source variable value using a prefix or suffix mask. This parameter must be written at the front of the value mapping list;

3. include: include one or more files containing mapping values;

The syntax of the Map directive is as follows:

map $variable $new_variable {
    key value;
    key value;
    # 可以添加更多的键值对
    default value;
}

in:

$variable is the name of the input variable to be mapped.
$new_variable is the name of the new variable that maps the result.
key are the possible values of the input variable.
value is the mapped value associated with each key.
default Is the default value when the input variable does not match any key.

This directive allows you to set new variable values based on different values of input variables. This is useful when configuring NGINX to tailor the server's behavior to different situations.

Classic usage scenarios

Path rewriting: You can use the Map module to rewrite URLs based on the requested URI, such as mapping an old URL to a new URL.

map $uri $new_uri {
  /old-path /new-path;
  /another-old-path /another-new-path;
}

server {
  location / {
    rewrite ^ $new_uri permanent;
  }
}

Request distribution: You can use the map module to distribute requests to different backend servers, selected based on certain conditions.

map $arg_backend $backend {
  default backend1;
  server1 backend2;
  server2 backend3;
}

upstream backend1 {
  server backend1.example.com;
}

upstream backend2 {
  server backend2.example.com;
}

upstream backend3 {
  server backend3.example.com;
}

server {
  location / {
    proxy_pass http://$backend;
  }

Permission control: You can use the map module to control access permissions based on client IP address or other conditions.

map $remote_addr $allowed {
  192.168.1.0/24 1;
  default 0;
}

server {
  location /private {
    if ($allowed = 0) {
      return 403;
    }
    # 允许访问私有内容
  }
}

These are some common usage scenarios of the NGINX map module. You can customize the mapping rules according to specific needs to meet your needs.

How to use OpenNJet to implement dynamic configuration of Map instructions?

The NGINX Map directive supports static configuration but does not support dynamic configuration. It is mainly used to create a map of key-value pairs during request processing to find the corresponding value based on the input value. This mapping is defined in the NGINX configuration file and loaded when the server starts. So, today I will share with you how to make good use of OpenNJet to dynamically modify the mapping relationship of key values in the Map instruction without reloading or restarting the OpenNJet instance.

OpenNJet portal: https://njet.org.cn/

What are the benefits of doing this?

Flexibility: Dynamic map configuration allows you to update mapping rules in real time without restarting. This means you can change the mapping as needed without disrupting service.
Performance optimization: Dynamically configuring maps can improve performance because it allows the map to be maintained in memory instead of reloading the configuration file on every request.
Simplified management: Using dynamic configuration maps, you can store configuration information in one place instead of being scattered in multiple configuration files. This makes management and maintenance easier.
Real-time updates: You can update mappings in real time through API or other methods to respond to changing requirements in different scenarios without manually editing configuration files.

Configuration instructions

Basic configuration:

njet.conf

worker_processes auto;
cluster_name njet;
node_name node1;
error_log logs/error.log error;

helper ctrl modules/njt_helper_ctrl_module.so conf/njet_ctrl.conf;
helper broker modules/njt_helper_broker_module.so;

load_module modules/njt_http_location_module.so;
load_module modules/njt_http_vtsc_module.so;
load_module modules/njt_http_dyn_map_module.so;

events {
    worker_connections  1024;
}

http {
    map $arg_service $backend_svr {
       default "127.0.0.1:18081";
    }

    include mime.types;
    server {
        listen       8080;
        location / {
           proxy_pass http://$backend_svr;
        }
    }

    server {
        listen 18081;
        return 200 "default service 18081\n";
    }
}

ctrl.conf

load_module modules/njt_http_sendmsg_module.so;
load_module modules/njt_ctrl_config_api_module.so; 
load_module modules/njt_helper_health_check_module.so;
load_module modules/njt_http_upstream_api_module.so; 
load_module modules/njt_http_location_api_module.so;
load_module modules/njt_doc_module.so;
load_module modules/njt_http_vtsd_module.so;

error_log logs/error_ctrl.log error;

events {
    worker_connections  1024;
}

http {
    include mime.types;
    access_log off;
    server {
        listen       8081;
        keepalive_timeout 0;

        location / {
            return 200 "njet control panel\n";
        }
        location /hc {
            health_check_api;
        }
        
        location /api {
             api write=on;
        }
        
        location /kv {
            dyn_sendmsg_kv;
        }
        
        location /config {
            config_api;
        }
        
        location /doc {
            doc_api;
        }
        location /dyn_loc {
           dyn_location_api;
        }
  
        location /metrics {
            vhost_traffic_status_display;
            vhost_traffic_status_display_format html;
        }
    }
}

For more verification, click OpenNJet to view the execution effect.

OpenNJet dynamic configuration map provides the advantages of more flexibility, high performance, simplified management and real-time updates, allowing you to better manage and optimize your server configuration.

OpenNJet was first based on the basic fork of NGINX1.19 and evolved independently. OpenNJet has the characteristics of high performance, stability, and easy expansion. It also solves the long-standing problems of NGINX such as difficulty in dynamic configuration and management functions affecting business. As the underlying engine, OpenNJet uses the dynamic loading mechanism to implement different product forms, such as API gateway, message proxy, inbound and outbound proxy, load balancing, WAF, etc. In the cloud-native architecture, OpenNJet not only provides north-south communication gateway functions, but also provides new features such as east-west communication in the service grid, transparent traffic hijacking, circuit breaker, telemetry and fault injection.

Gitee mailing group
invites you to open source and build together: https://njet.org.cn/

[Practical experience] How to dynamically configure NGINX Map?

Introduction to Map command

Classic usage scenarios

How to use OpenNJet to implement dynamic configuration of Map instructions?

Guess you like