NGINX: How to forward requests with query strings

Introduction

NGINX is a popular open-source web server known for its performance and flexibility. One common requirement when working with NGINX is to forward requests—including those with query strings—to other servers or locations. This guide will provide a step-by-step tutorial to set up query string forwarding in NGINX. We’ll cover everything from the basics to more advanced configurations, with real code examples that you can use as a starting point for your setups.

Prerequisites

• Basic understanding of web server concepts.
• Familiarity with NGINX configuration files and syntax.
• Access to an NGINX server to implement examples provided.

Getting Started with Basic Query String Forwarding

Forwarding a request with its query string is a common task when you wish to pass on the entire URL requested by the user to another server. Let’s start with a basic example where we forward all requests to another domain.

server {
  listen 80;
  server_name example.com;

  location / {
    proxy_pass http://another-server.com;
  }
}

With the above configuration, any request to example.com along with its query string will be transparently forwarded to another-server.com. The user won’t be aware of the forwarding and the query string (everything after ? in the URL) will be included automatically.

Handling Specific Query Strings

Sometimes you need to only forward requests if they contain certain query strings. This section will cover a scenario where only requests with a specific query parameter will be forwarded.

map $arg_myparam $target_url {
  default          "";
  "specialValue"  http://special-server.com;
}

server {
  listen 80;
  server_name example.com;

  if ($target_url != "") {
    rewrite ^ $target_url permanent;
  }
}

In this advanced configuration, we’re using the map block to define logic based on the query parameter myparam. If myparam equals “specialValue”, requests to example.com will be rewritten to http://special-server.com.

Preserving Query Strings During Re-Writing

Basic rewrites in NGINX will drop the query string unless you specifically account for it. To preserve it during a rewrite, you need to include the $is_args and $args variables, as illustrated below.

server {
  listen 80;
  server_name example.com;

  location / {
    rewrite ^/oldpage$ /newpage$is_args$args permanent;
  }
}

The rewritten URL will now keep the query string intact and append it to the new location. If the original request URL was example.com/oldpage?name=John, the user would be redirected to example.com/newpage?name=John.

Advanced Forwarding with Query String Modification

There may be scenarios where we need to not only forward requests but also modify parts of the query string. NGINX allows you to break down and modify these components using advanced rewrites and maps.

map $arg_type $newarg_type {
  ~^video  photo;
  default  $arg_type;
}

server {
  listen 80;
  server_name example.com;

  location / {
    if ($arg_type) {
      set $args "type=$newarg_type&$args";
      rewrite ^ http://another-server.com?$args;
    }
  }
}

Here we’re examining the type query parameter. If it matches the pattern ~^video (starts with “video”), we change it to “photo”. After modification, the entire query string is appended to the forwarding URL.

Conclusion

Throughout this tutorial, we explored how query strings can be effectively manipulated and forwarded in NGINX. Understanding these techniques is crucial for building dynamic web applications that rely on query-driven content. With concise examples and clear explanations, you should now possess the skills to customize your NGINX server to handle query strings in various advanced ways to meet your specific use cases.