Map directive for variable mapping in Nginx - Commands & Configuration

Introduction

Sometimes you want to change or assign values based on other values in your web server. The map directive in nginx helps you create new variables by matching existing ones to new values. This makes your server smarter and more flexible without complex code.

When you want to set different backend servers based on the requested domain name.

When you need to assign custom headers depending on the user agent of the visitor.

When you want to enable or disable features based on the client IP address.

When you want to rewrite URLs differently depending on the request path.

When you want to simplify complex if-else logic by mapping values in one place.

Config File - nginx.conf

nginx.conf

http {
    map $http_user_agent $is_mobile {
        default 0;
        ~*Mobile 1;
    }

    server {
        listen 80;
        server_name example.com;

        location / {
            if ($is_mobile) {
                return 302 /mobile.html;
            }
            return 200 'Welcome to the desktop site!';
        }
    }
}

The map block creates a new variable $is_mobile based on the $http_user_agent header.

If the user agent contains the word 'Mobile' (case-insensitive), $is_mobile is set to 1, otherwise 0.

Inside the server block, nginx checks $is_mobile to redirect mobile users to a mobile page.

Commands

This command tests the nginx configuration file for syntax errors before applying it.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

This command reloads nginx to apply the new configuration without stopping the server.

Terminal

systemctl reload nginx

Expected Output

No output (command runs silently)

This command sends a request to the server to check the response headers and verify redirection for mobile user agents.

Terminal

curl -I http://example.com/

Expected Output

HTTP/1.1 200 OK

Server: nginx

Content-Type: text/html

Content-Length: 27

Connection: keep-alive

This command simulates a mobile user agent to check if the server redirects to the mobile page.

Terminal

curl -I -A "Mozilla/5.0 (iPhone; CPU iPhone OS 13_2_3 like Mac OS X) Mobile" http://example.com/

Expected Output

HTTP/1.1 302 Found

Server: nginx

Location: /mobile.html

Content-Length: 0

Connection: keep-alive

Key Concept

If you remember nothing else from this pattern, remember: the map directive creates new variables by matching existing values, making nginx configuration simpler and more powerful.

Common Mistakes

Using the map directive inside the server block instead of the http block.

The map directive must be defined in the http context; placing it inside server causes nginx to fail loading the config.

Always place the map directive inside the http block at the top level of the configuration.

Not testing the configuration with 'nginx -t' before reloading.

Reloading with syntax errors causes nginx to fail or revert to the old config, leading to downtime or unexpected behavior.

Run 'nginx -t' to verify syntax before reloading the server.

Using incorrect regex syntax in the map keys, like missing ~* for case-insensitive matching.

Without proper regex flags, the map may not match intended values, causing wrong variable assignments.

Use '~*' before regex patterns for case-insensitive matching in map keys.

Summary

The map directive creates new variables by matching existing ones to values.

Define map blocks inside the http context for proper nginx configuration.

Test your configuration with 'nginx -t' before reloading to avoid errors.

Practice

1. What is the primary purpose of the map directive in nginx configuration?

easy

A. To create new variables based on existing variables

B. To define server blocks for different domains

C. To set up SSL certificates

D. To configure load balancing between servers

Solution

1. Step 1: Understand the role of map in nginx

   The map directive is used to create new variables by mapping values from existing variables.

2. Step 2: Compare with other nginx directives

   Other options like server blocks, SSL, and load balancing serve different purposes unrelated to variable mapping.

3. Final Answer:

   To create new variables based on existing variables -> Option A

4. Quick Check:

   map creates variables [OK]

Hint: Map creates variables from existing ones [OK]

Common Mistakes:

• Confusing map with server block configuration
• Thinking map sets SSL or load balancing
• Assuming map modifies request headers directly

2. Which of the following is the correct syntax to start a map block in nginx?

easy

A. map ($variable, $new_variable) {

B. map $new_variable $variable {

C. map { $variable $new_variable }

D. map $variable $new_variable {

Solution

1. Step 1: Recall the syntax of the map directive

   The correct syntax is map $variable $new_variable { where the first variable is the source and the second is the target.

2. Step 2: Eliminate incorrect syntax

   The incorrect options use wrong order or invalid punctuation for nginx configuration.

3. Final Answer:

   map $variable $new_variable { -> Option D

4. Quick Check:

   map syntax = map $source $target { [OK]

Hint: Map syntax: map $source $target { [OK]

Common Mistakes:

• Swapping source and target variables
• Using parentheses or braces incorrectly
• Missing the $ sign before variables

3. Given this nginx map configuration:

map $http_user_agent $is_mobile {
    default 0;
    ~*Mobile 1;
}

What will be the value of $is_mobile if the user agent is Mozilla/5.0 (Linux; Mobile)?

medium

A. Mobile

B. 0

C. 1

D. default

Solution

1. Step 1: Understand the map pattern matching

   The map uses a case-insensitive regex ~*Mobile to match user agents containing 'Mobile'.

2. Step 2: Check the user agent string

   The user agent contains 'Mobile', so the regex matches and sets $is_mobile to 1.

3. Final Answer:

   1 -> Option C

4. Quick Check:

   Regex match 'Mobile' sets value to 1 [OK]

Hint: Regex ~*Mobile matches user agent containing 'Mobile' [OK]

Common Mistakes:

• Ignoring case-insensitive regex (~*)
• Assuming default value applies despite match
• Confusing variable names

4. Identify the error in this nginx map configuration:

map $request_method $allow_method {
    GET yes;
    POST yes;
    DELETE no
}

medium

A. Missing semicolon after DELETE no

B. Incorrect variable names

C. map directive cannot map request methods

D. Using yes/no instead of 1/0 is invalid

Solution

1. Step 1: Check syntax for each mapping line

   Each line inside map must end with a semicolon. The line DELETE no is missing a semicolon.

2. Step 2: Validate other options

   Variable names are valid, mapping request methods is allowed, and yes/no strings are acceptable values.

3. Final Answer:

   Missing semicolon after DELETE no -> Option A

4. Quick Check:

   Each map line ends with ; [OK]

Hint: Every map entry line ends with a semicolon [OK]

Common Mistakes:

• Omitting semicolons at line ends
• Thinking yes/no are invalid values
• Assuming map can't use request methods

5. You want to create a variable $cache_key that is mobile if the user agent contains 'Mobile', otherwise desktop. Which map configuration correctly achieves this?

hard

A. map $cache_key $http_user_agent {
mobile ~*Mobile;
desktop default;
}

B. map $http_user_agent $cache_key {
~*Mobile mobile;
default desktop;
}

C. map $http_user_agent $cache_key {
default desktop
~*Mobile mobile
}

D. map $http_user_agent $cache_key {
Mobile mobile;
default desktop;
}

Solution

1. Step 1: Confirm correct map syntax and order

   The map directive must have source variable first, target variable second, and each line ends with semicolon.

2. Step 2: Check pattern matching and default

   map $http_user_agent $cache_key { ~*Mobile mobile; default desktop; } uses case-insensitive regex ~*Mobile to match user agents containing 'Mobile' and sets mobile, else desktop.

3. Step 3: Eliminate incorrect options

   map $cache_key $http_user_agent { mobile ~*Mobile; desktop default; } reverses variables, one misses semicolons, another uses exact 'Mobile' without regex and may miss case-insensitive matches.

4. Final Answer:

   map $http_user_agent $cache_key { ~*Mobile mobile; default desktop; } -> Option B

5. Quick Check:

   Correct map syntax with regex and default [OK]

Hint: Use map $source $target with regex and default [OK]

Common Mistakes:

• Swapping source and target variables
• Missing semicolons after lines
• Not using case-insensitive regex for matching