search
HomeOperation and MaintenanceNginxHow to use the upstream module in Nginx

Upstream module introduction

  • nginx modules are generally divided into three categories: handler, filter and upstream. In the previous chapters, readers have already learned about handlers and filters. Using these two types of modules, nginx can easily complete any stand-alone work.

  • The upstream module will enable nginx to transcend the limitations of a single machine and complete the reception, processing and forwarding of network data.

  • The data forwarding function provides nginx with horizontal processing capabilities across a single machine, freeing nginx from the limitation of only providing a single function for terminal nodes, and enabling it to have network application level disassembly. Divide, encapsulate and integrate functions.

  • Data forwarding is a key component of nginx’s ability to build a network application. Of course, due to development cost issues, key components of a network application are often initially developed using high-level programming languages. But when the system reaches a certain scale and more emphasis is placed on performance, in order to achieve the required performance goals, the components developed in high-level languages ​​must be structurally modified.

At this time, in terms of modification costs, nginx's upstream module shows its advantages because it is inherently fast. As an aside, the hierarchical and loose coupling provided by nginx's configuration system makes the system scalable to a relatively high level.

upstream module interface

Essentially speaking, upstream belongs to the handler, but it does not generate its own content, but obtains the content by requesting the back-end server, so it is called upstream (upstream) . The entire process of requesting and obtaining response content has been encapsulated within nginx, so the upstream module only needs to develop several callback functions to complete specific work such as constructing requests and parsing responses.

The upstream module callback functions are listed as follows:

Function name Description
create_request Generate the request buffer (buffer chain) sent to the back-end server, use it when initializing upstream
reinit_request In the event of an error on a backend server, nginx will try another backend server. After nginx selects a new server, it will first call this function to reinitialize the working status of the upstream module, and then connect the upstream again
process_header Processing backend The information header returned by the server. The so-called header is specified by the protocol for communicating with the upstream server, such as the header part of the HTTP protocol, or the response status part of the memcached protocol
abort_request Abort on the client Called when requested. There is no need to implement the function of closing the back-end server connection in the function. The system will automatically complete the steps of closing the connection, so generally this function will not perform any specific work
finalize_request This function is called after the request with the back-end server is completed normally. It is the same as abort_request and generally does not perform any specific work
input_filter Processes the back-end server The response body returned. The default input_filter of nginx will encapsulate the received content into a buffer chain ngx_chain. This chain is located by the out_bufs pointer field of upstream, so developers can use this pointer to obtain the text data returned by the back-end server outside the module. The memcached module implements its own input_filter. This module will be analyzed in detail later.
input_filter_init Initialize the input filter context. nginx's default input_filter_init directly returns

memcached module analysis

  • memcache is a high-performance distributed cache system that has been widely used. memcache defines a set of private communication protocols so that memcache cannot be accessed through HTTP requests. However, the protocol itself is simple and efficient, and memcache is widely used, so most modern development languages ​​and platforms provide memcache support to facilitate developers to use memcache.

  • nginx provides the ngx_http_memcached module, which provides the function of reading data from memcache, but does not provide the function of writing data to memcache.

The upstream module uses the access method of the handler module.

At the same time, the design of the instruction system of the upstream module also follows the basic rules of the handler module: the module will be executed only after configuring the module.

So, what is so special about the upstream module? That is the processing function of the upstream module. The operations performed by the processing function of the upstream module include a fixed process: (take the memcached module as an example, in the processing function ngx_http_memcached_handler of memcached)

Create the upstream data structure:

ngx_http_upstream_t            *u;
if (ngx_http_upstream_create(r) != NGX_OK) {
    return NGX_HTTP_INTERNAL_SERVER_ERROR;
}
u = r->upstream;

Set the tag and schema of the module. Schema will only be used for logs now, and tags will be used for buf_chain management:

ngx_str_set(&u->schema, "memcached://");
u->output.tag = (ngx_buf_tag_t) &ngx_http_memcached_module;

Set the upstream backend server list data structure:

mlcf = ngx_http_get_module_loc_conf(r, ngx_http_memcached_module);
u->conf = &mlcf->upstream;

Set the upstream callback function:

u->create_request = ngx_http_memcached_create_request;
u->reinit_request = ngx_http_memcached_reinit_request;
u->process_header = ngx_http_memcached_process_header;
u->abort_request = ngx_http_memcached_abort_request;
u->finalize_request = ngx_http_memcached_finalize_request;
   
u->input_filter_init = ngx_http_memcached_filter_init;
u->input_filter = ngx_http_memcached_filter;

Create and set upstream environment data structure:

ctx = ngx_palloc(r->pool, sizeof(ngx_http_memcached_ctx_t));
if (ctx == NULL) {
    return NGX_HTTP_INTERNAL_SERVER_ERROR;
}
ctx->request = r;

ngx_http_set_ctx(r, ctx, ngx_http_memcached_module);

u->input_filter_ctx = ctx;

Complete upstream initialization and finishing work:

r->main->count++;
ngx_http_upstream_init(r);
return NGX_DONE;

This is true for any upstream module, as simple as memcached, as complex as proxy and fastcgi.
The biggest difference between different upstream modules in these 6 steps will appear in steps 2, 3, 4, and 5.

Steps 2 and 4 are easy to understand. The flags set by different modules and the callback functions used are definitely different. Step 5 is not difficult to understand either.

Only step 3 is a bit confusing. Different modules have very different strategies when obtaining the backend server list. Some are as simple and clear as memcached, and some are as logically complex as proxy.

Step 6 is usually consistent between different modules. Increase count by 1 and return NGX_DONE.
When nginx encounters this situation, although it will consider that the processing of the current request has ended, it will not release the memory resources used by the request, nor will it close the connection with the client.
The reason why this is needed is because nginx has established a one-to-one relationship between upstream requests and client requests. When subsequently using ngx_event_pipe to send the upstream response back to the client, these stored client information will also be used. data structure.
Bind upstream requests and client requests one-to-one. This design has advantages and disadvantages. The advantage is that it simplifies module development and allows you to focus on module logic. However, the disadvantages are equally obvious. One-to-one design often cannot meet the needs of complex logic.

Callback function: (still taking the processing function of the memcached module as an example)

  • ngx_http_memcached_create_request: It is very simple to generate one according to the set content key, then generate a "get $key" request and place it in r->upstream->request_bufs.

  • ngx_http_memcached_reinit_request: No initialization required.

  • ngx_http_memcached_abort_request: No additional action required.

  • ngx_http_memcached_finalize_request: No additional action required.

  • ngx_http_memcached_process_header: The business focus function of the module. The header information of the memcache protocol is defined as the first line of text, and the code is as follows:

#define LF     (u_char) '\n'
for (p = u->buffer.pos; p < u->buffer.last; p++) {
    if (*p == LF) {
        goto found;
    }
}

If the LF (‘\n’) character is not found in the data that has been read into the buffer , the function returns NGX_AGAIN, indicating that the header has not been completely read and the data needs to continue to be read. nginx will call this function again after receiving new data.

nginx will only use one cache when processing the response header of the back-end server. All data is in this cache, so when parsing the header information, there is no need to consider the fact that the header information spans multiple caches. If the header is too large and cannot be saved in this cache, nginx will return an error message to the client and record an error log, indicating that the cache is not large enough.

The important responsibility of ngx_http_memcached_process_header is to translate the status returned by the back-end server into the status returned to the client. For example:

u->headers_in.content_length_n = ngx_atoof(start, p - start);
···
u->headers_in.status_n = 200;
u->state->status = 200;
···
u->headers_in.status_n = 404;
u->state->status = 404;

u->state is used to calculate upstream related variables. For example, u->state->status will be used to calculate the value of the variable "upstream_status". u->headers_in will be returned as a status code in the response to the client. And u->headers_in.content_length_n sets the length of the response returned to the client.

In this function, you must move the read pointer pos backward after processing the header information, otherwise this data will also be copied to the body of the response returned to the client, resulting in the content of the body being inconsistent. correct.

ngx_http_memcached_process_header function completes the correct processing of the response header and should return NGX_OK. If NGX_AGAIN is returned, it means that the complete data has not been read and the data needs to be continued to be read from the backend server. Returning NGX_DECLINED is meaningless. Any other return value is considered an error status, and nginx will end the upstream request and return an error message.

ngx_http_memcached_filter_init: Fix content length received from backend server. Because this part of the length is not added when processing the header.

ngx_http_memcached_filter:
The memcached module is a rare module with a callback function for processing text.
Because the memcached module needs to filter the CRLF "END" CRLF at the end of the text, it implements its own filter callback function.

The actual meaning of processing the text is to encapsulate the valid content of the text received from the back-end server into ngx_chain_t and add it to the end of u->out_bufs.

nginx does not copy data, but establishes the ngx_buf_t data structure to point to these data memory areas, and then organizes these bufs by ngx_chain_t. This implementation avoids large-scale memory relocation and is one of the reasons why nginx is efficient.

The above is the detailed content of How to use the upstream module in Nginx. For more information, please follow other related articles on the PHP Chinese website!

Statement
This article is reproduced at:亿速云. If there is any infringement, please contact admin@php.cn delete
NGINX in Action: Examples and Real-World ApplicationsNGINX in Action: Examples and Real-World ApplicationsApr 17, 2025 am 12:18 AM

NGINX can be used to improve website performance, security, and scalability. 1) As a reverse proxy and load balancer, NGINX can optimize back-end services and share traffic. 2) Through event-driven and asynchronous architecture, NGINX efficiently handles high concurrent connections. 3) Configuration files allow flexible definition of rules, such as static file service and load balancing. 4) Optimization suggestions include enabling Gzip compression, using cache and tuning the worker process.

NGINX Unit: Supporting Different Programming LanguagesNGINX Unit: Supporting Different Programming LanguagesApr 16, 2025 am 12:15 AM

NGINXUnit supports multiple programming languages ​​and is implemented through modular design. 1. Loading language module: Load the corresponding module according to the configuration file. 2. Application startup: Execute application code when the calling language runs. 3. Request processing: forward the request to the application instance. 4. Response return: Return the processed response to the client.

Choosing Between NGINX and Apache: The Right Fit for Your NeedsChoosing Between NGINX and Apache: The Right Fit for Your NeedsApr 15, 2025 am 12:04 AM

NGINX and Apache have their own advantages and disadvantages and are suitable for different scenarios. 1.NGINX is suitable for high concurrency and low resource consumption scenarios. 2. Apache is suitable for scenarios where complex configurations and rich modules are required. By comparing their core features, performance differences, and best practices, you can help you choose the server software that best suits your needs.

How to start nginxHow to start nginxApr 14, 2025 pm 01:06 PM

Question: How to start Nginx? Answer: Install Nginx Startup Nginx Verification Nginx Is Nginx Started Explore other startup options Automatically start Nginx

How to check whether nginx is startedHow to check whether nginx is startedApr 14, 2025 pm 01:03 PM

How to confirm whether Nginx is started: 1. Use the command line: systemctl status nginx (Linux/Unix), netstat -ano | findstr 80 (Windows); 2. Check whether port 80 is open; 3. Check the Nginx startup message in the system log; 4. Use third-party tools, such as Nagios, Zabbix, and Icinga.

How to close nginxHow to close nginxApr 14, 2025 pm 01:00 PM

To shut down the Nginx service, follow these steps: Determine the installation type: Red Hat/CentOS (systemctl status nginx) or Debian/Ubuntu (service nginx status) Stop the service: Red Hat/CentOS (systemctl stop nginx) or Debian/Ubuntu (service nginx stop) Disable automatic startup (optional): Red Hat/CentOS (systemctl disabled nginx) or Debian/Ubuntu (syst

How to configure nginx in WindowsHow to configure nginx in WindowsApr 14, 2025 pm 12:57 PM

How to configure Nginx in Windows? Install Nginx and create a virtual host configuration. Modify the main configuration file and include the virtual host configuration. Start or reload Nginx. Test the configuration and view the website. Selectively enable SSL and configure SSL certificates. Selectively set the firewall to allow port 80 and 443 traffic.

How to solve nginx403 errorHow to solve nginx403 errorApr 14, 2025 pm 12:54 PM

The server does not have permission to access the requested resource, resulting in a nginx 403 error. Solutions include: Check file permissions. Check the .htaccess configuration. Check nginx configuration. Configure SELinux permissions. Check the firewall rules. Troubleshoot other causes such as browser problems, server failures, or other possible errors.

See all articles

Hot AI Tools

Undresser.AI Undress

Undresser.AI Undress

AI-powered app for creating realistic nude photos

AI Clothes Remover

AI Clothes Remover

Online AI tool for removing clothes from photos.

Undress AI Tool

Undress AI Tool

Undress images for free

Clothoff.io

Clothoff.io

AI clothes remover

AI Hentai Generator

AI Hentai Generator

Generate AI Hentai for free.

Hot Article

R.E.P.O. Energy Crystals Explained and What They Do (Yellow Crystal)
1 months agoBy尊渡假赌尊渡假赌尊渡假赌
R.E.P.O. Best Graphic Settings
1 months agoBy尊渡假赌尊渡假赌尊渡假赌
R.E.P.O. How to Fix Audio if You Can't Hear Anyone
1 months agoBy尊渡假赌尊渡假赌尊渡假赌
R.E.P.O. Chat Commands and How to Use Them
1 months agoBy尊渡假赌尊渡假赌尊渡假赌

Hot Tools

Safe Exam Browser

Safe Exam Browser

Safe Exam Browser is a secure browser environment for taking online exams securely. This software turns any computer into a secure workstation. It controls access to any utility and prevents students from using unauthorized resources.

Notepad++7.3.1

Notepad++7.3.1

Easy-to-use and free code editor

MinGW - Minimalist GNU for Windows

MinGW - Minimalist GNU for Windows

This project is in the process of being migrated to osdn.net/projects/mingw, you can continue to follow us there. MinGW: A native Windows port of the GNU Compiler Collection (GCC), freely distributable import libraries and header files for building native Windows applications; includes extensions to the MSVC runtime to support C99 functionality. All MinGW software can run on 64-bit Windows platforms.

DVWA

DVWA

Damn Vulnerable Web App (DVWA) is a PHP/MySQL web application that is very vulnerable. Its main goals are to be an aid for security professionals to test their skills and tools in a legal environment, to help web developers better understand the process of securing web applications, and to help teachers/students teach/learn in a classroom environment Web application security. The goal of DVWA is to practice some of the most common web vulnerabilities through a simple and straightforward interface, with varying degrees of difficulty. Please note that this software

PhpStorm Mac version

PhpStorm Mac version

The latest (2018.2.1) professional PHP integrated development tool