Nginx FastCGI proxying sends a request to a FastCGI application server such as PHP-FPM instead of serving the request as a static file or forwarding it to an HTTP server. The fastcgi_pass directive selects the FastCGI listener, while fastcgi_param builds the parameter environment that tells the backend which script to execute and how to interpret the request.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
A working configuration therefore has three essentials: a location that matches the intended dynamic requests, a fastcgi_pass endpoint that actually exists, and a correct SCRIPT_FILENAME. The endpoint may be a Unix socket, a TCP address, or an upstream group. The example below is a starting point, not a universal socket path:
As an Amazon Associate I earn from qualifying purchases.
What FastCGI proxying does in Nginx
FastCGI is a backend protocol integration. Nginx accepts the client’s HTTP request, selects a location, converts request details into FastCGI parameters, and sends them to a FastCGI server. The FastCGI server runs the application code and returns a response. Nginx then sends that response back to the client, applying its normal response handling, buffering, header filtering, and error processing.
With PHP, the FastCGI server is commonly PHP-FPM. PHP-FPM listens on a Unix-domain socket or a TCP port; Nginx does not need to speak HTTP to it. That is why a PHP location uses fastcgi_pass, not the HTTP-oriented proxy_pass directive.
#1 Best Overall
- [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
- [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
- [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
- [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
- [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.
The request path from browser to script
- A client requests a URI such as
/index.php. - Nginx chooses the matching
locationblock. The directives in that block determine whether the request is treated as static content, FastCGI, or another type of upstream request. - Nginx evaluates variables such as
$document_rootand$fastcgi_script_name. - The
fastcgi_paramdirectives create the parameter environment. For PHP,SCRIPT_FILENAMEidentifies the filesystem path to execute andQUERY_STRINGcarries URL parameters. fastcgi_passopens a connection to the configured listener and sends the request parameters and body.- The FastCGI server executes the selected script and returns status, headers, and body data.
- Nginx applies its FastCGI response settings, then returns the result to the client.
fastcgi_pass versus proxy_pass
The two directives both connect Nginx to an upstream service, but they use different backend protocols and request representations.
| Directive | Backend protocol | Typical use | What Nginx sends |
|---|---|---|---|
fastcgi_pass |
FastCGI | PHP-FPM and other FastCGI application servers | FastCGI parameters, request metadata, and the request body |
proxy_pass |
HTTP or HTTPS | HTTP application servers and APIs | An HTTP request with method, URI, headers, and body |
Using proxy_pass for a PHP-FPM socket will not turn PHP-FPM into an HTTP service. Conversely, using fastcgi_pass for an ordinary HTTP application is the wrong protocol. Select the directive that matches the listener’s protocol.
Prerequisites before writing the location block
You need an Nginx server block, a document root containing the application, and a FastCGI server that is already listening. Determine the listener from the FastCGI runtime’s configuration rather than copying a path from another machine.
- Unix socket: a filesystem path such as
/run/php/php-fpm.sock. The file must exist and be accessible to the Nginx worker. - TCP listener: a hostname or IP address plus port, such as
127.0.0.1:9000. The address and port must match the FastCGI server’s listening configuration. - Upstream group: a named group of FastCGI servers used when requests are distributed among multiple backends.
A socket path in an example is deployment-specific. Distribution packages, PHP versions, containers, and custom builds frequently expose different names. A wrong path or port normally appears as a connection failure in the Nginx error log.
A minimal PHP-style FastCGI configuration
This location handles URIs ending in .php and passes them to a Unix socket. Replace the socket with the listener exposed by your FastCGI server.
Rank #2
- 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
- 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
- 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
- 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
- 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.
location ~ .php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}The same pattern can use a TCP listener:
location ~ .php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}The critical relationship is between the request URI and SCRIPT_FILENAME. If the document root is /data/www and the request is /index.php, the expression $document_root$fastcgi_script_name produces /data/www/index.php. The FastCGI server uses that value as the script path.
Using an upstream group
For more than one FastCGI backend, define an upstream group and point fastcgi_pass at its name:
upstream php_backends {
server 127.0.0.1:9000;
server 127.0.0.1:9001;
}
server {
root /data/www;
location ~ .php$ {
fastcgi_pass php_backends;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
}An upstream group distributes connections, but it does not automatically solve application-state problems. Review backend health, session storage, uploaded files, caches, and any other state that must be shared before adding servers.
How fastcgi_param builds the application environment
FastCGI does not receive a normal HTTP request line and header block in the same form as an HTTP proxy. Nginx creates named parameters instead. The include fastcgi_params; line supplies a standard set for the request, while explicit directives add or override values needed by the application.
The module reference identifies SCRIPT_FILENAME and QUERY_STRING as the minimum PHP-oriented settings. PHP uses SCRIPT_FILENAME to determine which file to execute, and QUERY_STRING carries parameters after the question mark in the URI.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #3
- [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
- [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
- [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
- [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
- [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by
For scripts that process POST requests, make sure the environment includes:
REQUEST_METHOD, such asGETorPOST.CONTENT_TYPE, which describes the request body format.CONTENT_LENGTH, which identifies the body size.
The exact set supplied by an included parameter file can vary by installation. Inspect the included file and confirm that your application receives the values it needs instead of assuming that every package ships an identical file.
URI-to-script mapping: fastcgi_index, paths, and PATH_INFO
Requests for a directory URI
$fastcgi_script_name is based on the request URI. When the URI ends with a slash and fastcgi_index is configured, Nginx appends the index filename. With fastcgi_index index.php, a request for / can resolve to /index.php under the configured document root.
This behavior is why a directory request and an explicit script request can produce different script names. Test both forms when diagnosing an unexpected file path.
Free tools Windows power users keep installed
One-click scans. No signup required.
Applications that use PATH_INFO
Some applications put additional route information after the script name, for example /index.php/articles. In that case, use fastcgi_split_path_info with a two-capture regular expression. The first capture becomes $fastcgi_script_name; the second becomes $fastcgi_path_info.
Rank #4
- Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
- Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
- All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
- Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
- Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.
location ~ ^(.+.php)(/.+)$ {
fastcgi_split_path_info ^(.+.php)(/.+)$;
fastcgi_pass unix:/run/php/php-fpm.sock;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
}Use a PATH_INFO pattern only when the application expects that URL form. A broad pattern can classify unintended URIs as scripts, so verify which locations match real requests and keep the script-handling location as narrow as the application permits.
Location matching and script safety
The selected location controls which FastCGI directives run. Nginx evaluates prefix and regular-expression locations according to its location-selection rules, so a more specific or differently ordered block can prevent the intended FastCGI block from handling a request.
When a request unexpectedly returns static content, a 404, or a different upstream response, inspect the location definitions and their order. Confirm that the URI you tested actually matches the PHP or FastCGI expression. Also verify that the computed script path is inside the intended document root and names a real application file. Passing a nonexistent or unintended path to the backend is the usual cause of a “Primary script unknown” response.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Buffering and timeout settings
FastCGI performance settings have different scopes. Change the setting that corresponds to the observed behavior instead of copying a collection of arbitrary values.
| Directive | Default | What it controls | When to reconsider it |
|---|---|---|---|
fastcgi_buffering |
on |
Whether Nginx reads the backend response into buffers before sending it onward | Disable only when the application requires response streaming |
fastcgi_buffer_size and fastcgi_buffers |
Configuration-dependent buffer sizes | Memory available for FastCGI response headers and body data; excess data can be written to a temporary file | Adjust when large headers or responses cause buffering warnings or excessive temporary-file use |
fastcgi_read_timeout |
60s |
Maximum interval between successive reads from the FastCGI server | Raise it for applications that can legitimately pause longer than 60 seconds between output reads |
fastcgi_connect_timeout |
60s |
Time allowed to establish the backend connection | Investigate listener availability, routing, and overload before increasing it; the documented practical limit is usually 75 seconds |
fastcgi_keep_conn |
off |
Whether Nginx keeps the FastCGI connection open for reuse | Set it to on only when the FastCGI server and deployment support persistent connections |
fastcgi_request_buffering |
on |
Whether Nginx buffers the client request body before sending it upstream | Disable for deliberate request streaming; after body transmission begins, Nginx cannot retry that request to another server |
Choosing a timeout deliberately
A connection timeout and a read timeout describe different failures. A connection timeout means Nginx cannot establish the FastCGI connection promptly. A read timeout means the connection exists but no response data arrived during the configured interval between reads. A script that runs for two minutes and then returns a complete response may require a higher read timeout even though connection establishment is fast.
Do not treat fastcgi_read_timeout 60s as a complete-response deadline. It measures the gap between reads, not the total lifetime of a request. Set it according to the application’s expected pauses, and investigate slow code separately.
When buffering should remain enabled
Buffering is on by default because it lets Nginx absorb differences between backend output and client download speed. Disable it only for a known streaming use case, such as an application that must deliver incremental output as it is generated. Changing buffering without that requirement can increase the effect of slow clients on backend connections.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Response headers and error interception
Nginx hides the FastCGI response headers Status and X-Accel-* from clients by default. Use fastcgi_pass_header only when a particular hidden field must be exposed; do not make all backend headers public by default.
fastcgi_intercept_errors is off by default. When enabled, FastCGI responses with status codes of 300 or higher can be handled by Nginx’s error_page mechanism. This is useful when the server’s standard error pages or redirects should replace the backend response, but it changes which layer owns the final error body.
Step-by-step configuration procedure
- Identify the listener. Find the Unix socket or TCP address configured by PHP-FPM or the other FastCGI server. Record the exact path, hostname, and port, including any container or namespace boundary.
- Confirm the document root. In the relevant
serverblock, identify the root that contains the application scripts. The root used to formSCRIPT_FILENAMEmust be meaningful from the FastCGI server’s filesystem perspective, not merely from Nginx’s perspective. - Add a narrowly matching location. Start with
location ~ .php$for direct PHP script requests, or use the application’s required PATH_INFO expression. Check other prefix and regex locations so the request is not captured elsewhere. - Set
fastcgi_pass. Use the actual socket, TCP endpoint, or upstream group name. Do not leave the example socket unchanged unless that is the listener your runtime exposes. - Include request parameters. Add
include fastcgi_params;, then explicitly setSCRIPT_FILENAME. Confirm that the included parameters provideQUERY_STRINGand the method and content fields required by POST handlers. - Set the index behavior if needed. Add
fastcgi_index index.php;when a trailing-slash URI should resolve to that index script. - Validate the configuration. Run
nginx -twith the privileges and configuration path used by your installation. Fix syntax errors before reloading. - Reload Nginx. Use the service manager or the installation’s supported reload command so existing connections can finish while workers adopt the new configuration.
- Test representative requests. Request an explicit script, a directory URI, a query string, and a POST endpoint. Test a PATH_INFO URL only if the application uses it.
- Read both logs when something fails. Correlate the Nginx error log with the FastCGI server log. The first usually identifies connection, timeout, or script-path problems; the second can reveal application or pool failures.
Troubleshooting common failures
| Symptom | Likely cause | Checks and corrective action |
|---|---|---|
| 502 Bad Gateway immediately | Wrong socket, wrong port, refused connection, or permission problem | Compare fastcgi_pass with the runtime’s listener configuration. Confirm the socket exists, the TCP port is listening, and the Nginx worker can access it. Read the Nginx error log for the exact connection error. |
| 502 after a long pause | Backend connection or read timeout | Determine whether connection establishment failed or an established connection stopped producing data. Check backend load and application execution time, then adjust only fastcgi_connect_timeout or fastcgi_read_timeout as appropriate. |
| “Primary script unknown” | SCRIPT_FILENAME points to a nonexistent path or a path the FastCGI server cannot see |
Log or otherwise inspect the computed value. Confirm the document root, URI-derived script name, filename spelling, mounts, and permissions from the FastCGI server’s filesystem perspective. |
| PHP source is downloaded or shown as static text | The request did not enter the FastCGI location | Check location matching and ordering. Confirm that the URI matches the regular expression and that another location is not serving the file directly. |
Directory URL fails while /index.php works |
No index mapping or an unexpected URI-to-script calculation | Set fastcgi_index index.php; when appropriate and verify the resulting $fastcgi_script_name. |
| POST data is empty or malformed | Required request parameters are missing or incorrect | Verify REQUEST_METHOD, CONTENT_TYPE, and CONTENT_LENGTH, as well as the included parameter file and request-body handling. |
| PATH_INFO routes to the wrong file | The split expression captures the URI incorrectly | Use a two-capture fastcgi_split_path_info expression. Confirm that the first capture is the script and the second is passed as PATH_INFO. |
| Streaming output arrives only at the end | FastCGI response buffering is enabled | Keep buffering enabled for ordinary responses. If the application genuinely requires streaming, evaluate fastcgi_buffering off and test the effect on backend connections and slow clients. |
| One backend works but another fails | Inconsistent files, configuration, permissions, sessions, or health | Compare each upstream server’s listener, document root, deployed code, runtime settings, and shared state. An upstream group distributes requests; it does not synchronize application state. |
Scaling FastCGI safely
An upstream group lets fastcgi_pass select among multiple FastCGI servers. Before using it in production, decide how the application handles sessions and other state. If a user’s session exists only on one backend, ordinary distribution can produce intermittent logouts unless sessions are shared or affinity is deliberately configured.
Uploaded files and generated assets require the same consideration. Every backend must either see the same filesystem or use a shared storage design. Health checks, capacity limits, and failure behavior also need explicit planning; adding a second process does not by itself make an unhealthy application highly available.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
A practical verification checklist
- The FastCGI listener exists at the exact address used by
fastcgi_pass. - Nginx can access a Unix socket, or can reach the configured TCP address and port.
- The intended request enters the intended
locationblock. $document_root$fastcgi_script_nameresolves to the real script path, or an equivalent deliberate mapping is used.QUERY_STRINGis present for requests with URL parameters.- POST handlers receive
REQUEST_METHOD,CONTENT_TYPE, andCONTENT_LENGTH. - Trailing-slash requests behave correctly when
fastcgi_indexis configured. - PATH_INFO is split and passed only when the application requires it.
- Timeout changes correspond to a measured connection, read, or application delay.
- Buffering is changed only for a documented streaming or response-size requirement.
- Each backend in an upstream group has compatible code, files, runtime configuration, and state handling.
Key takeaways for a reliable configuration
fastcgi_pass is the routing directive: it chooses the FastCGI endpoint. fastcgi_param is the translation layer: it supplies the application environment, including the script path and request metadata. The URI-to-file result depends on $fastcgi_script_name, fastcgi_index, and, for PATH_INFO applications, fastcgi_split_path_info.
Most failures become straightforward once you separate four questions: did Nginx select the right location, can it connect to the right listener, did it calculate the right script path, and did it wait or buffer according to the application’s behavior? Answer those in that order, and tune only the directive implicated by the evidence.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
