How to Redirect a Subdomain to Another IP and Port With Nginx

iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more

Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.

Use proxy_pass when the browser must stay on the subdomain, and use return 301 when the browser should move to a different URL. DNS only maps app.example.com to the public IP address of the Nginx server; it does not send visitors to an arbitrary port. Nginx must listen on the public HTTP or HTTPS port and either reverse-proxy the request to the destination IP and port or return a redirect that tells the client where to go.

The configurations below cover HTTP and HTTPS applications, path rewriting, upstream TLS, raw TCP/UDP services, testing, and the failures most often encountered in production.

#	Preview	Product	Price
1		NGINX Cookbook: Advanced Recipes for High-Performance Load Balancing	$37.53	Buy on Amazon
2		NGINX Cookbook: Over 70 recipes for real-world configuration, deployment, and performance	$23.69	Buy on Amazon
3		NGINX Unit Cookbook: Recipes for Using a Versatile Open Source Server	$12.31	Buy on Amazon
4		NGINX HTTP Server: Harness the power of NGINX with a series of detailed tutorials and real-life...	$51.99	Buy on Amazon
5		NGINX Cookbook: Advanced Recipes for High-Performance Load Balancing	$26.99	Buy on Amazon

Redirect or reverse proxy: choose by the URL you want visitors to see

These two Nginx features solve different problems. A redirect is a response to the client. Nginx sends a status code and a Location header, and the browser makes a new request to that URL. The address bar changes, the destination becomes directly visible, and the client must be able to reach it.

A reverse proxy is an intermediary. The browser requests app.example.com; Nginx opens a second connection to the upstream service, receives its response, and sends that response back. The browser continues to display app.example.com. The upstream can therefore remain on a private address or a port that is never exposed publicly.

#1 Best Overall

Sale

NGINX Cookbook: Advanced Recipes for High-Performance Load Balancing

$37.53

Buy on Amazon

Use a redirect when the destination should be public

Choose return 301 https://new.example.com$request_uri; when changing the canonical hostname, moving a site, or deliberately sending users to another URL. The $request_uri variable preserves the original path and query string. During testing, use a temporary 302; browsers and intermediaries cache a permanent 301 extbackslash n, which can make an incorrect experiment appear to persist after you fix the configuration.

Use a reverse proxy when the subdomain must remain visible

Use proxy_pass when visitors should continue using app.example.com, while the application actually listens on another IP and port such as 192.0.2.10:8080. This is the normal design for an application server behind a public Nginx edge host.

Prepare DNS, listeners, and network access

Point DNS to Nginx, not directly to the application port

Create an A record for app.example.com pointing to the public IPv4 address of the Nginx host, or an AAAA record for its public IPv6 address. DNS records identify addresses; they do not encode an HTTP destination port. A visitor connecting to a normal HTTP URL reaches port 80, and a visitor connecting to HTTPS reaches port 443 unless the URL explicitly includes another port.

Do not point the public record at a private upstream address that Internet clients cannot route to. If you have multiple Nginx hosts, use the address of the host that owns the intended listener and certificate.

Confirm the upstream is reachable from Nginx

From the Nginx machine, verify that the destination service accepts connections at DESTINATION_IP:DESTINATION_PORT. A service bound only to 127.0.0.1 on a different machine, a blocked cloud security-group rule, or a host firewall will produce connection-refused or timeout errors even when DNS and Nginx syntax are correct.

Rank #2

Sale

NGINX Cookbook: Over 70 recipes for real-world configuration, deployment, and performance

$23.69

Buy on Amazon

• Allow inbound port 80 and/or 443 on the Nginx host as appropriate.
• Allow the Nginx host’s address to reach the upstream port.
• Make sure the application is listening on the expected interface and port.
• Check that an IPv6 DNS record is not sending some users to an unconfigured IPv6 listener.

Choose the protocol before writing the block

HTTP and HTTPS applications use Nginx’s HTTP configuration: server, location, and proxy_pass. Raw TCP or UDP protocols such as a database wire protocol, game protocol, or custom service require the Nginx stream module instead. An HTTP location cannot safely proxy arbitrary non-HTTP traffic.

Configure an HTTP reverse proxy to another IP and port

For an application that speaks HTTP on port 8080, create a server block similar to this:

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://192.0.2.10:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

What each directive does

• listen 80; accepts plain HTTP on the standard public port. If Nginx listens on another public port, clients must include that port in the URL.
• server_name app.example.com; associates the hostname with this virtual server. Nginx supports exact names and wildcard names and applies its documented name-matching order when several blocks could match.
• location / handles every URI beneath the host unless a more specific location is selected.
• proxy_pass http://192.0.2.10:8080; tells Nginx to fetch the request from that IP and port using HTTP.
• Host $host sends the requested hostname to the application. Change this only when the upstream requires a different host value.
• X-Real-IP and X-Forwarded-For let an application record the original client address instead of seeing only the Nginx address.
• X-Forwarded-Proto $scheme tells the application whether the client used HTTP or HTTPS at Nginx.

The header policy is deployment-specific. Some applications require the upstream host name, a trusted proxy list, or different forwarded-header handling. Configure the application to trust these headers only from your Nginx network; otherwise a client could forge them when connecting directly.

Install and activate the block

1. Place the block in the configuration file loaded by your Nginx service, or include it from the platform’s enabled-sites directory.
2. Check the complete configuration with nginx -t. Run the test with the same configuration path and privileges used by the service so that included files and certificate paths are evaluated correctly.
3. Reload Nginx using your operating system’s service command after the test succeeds. A reload applies the new workers without unnecessarily dropping existing connections.
4. Resolve the hostname externally and request it with curl -I http://app.example.com/. Confirm that the status and headers come from the expected application.

Use a redirect when the hostname should change

A dedicated redirect server block is intentionally short:

server {
    listen 80;
    server_name app.example.com;
    return 301 https://new.example.com$request_uri;
}

The return directive stops request processing immediately and sends the specified status and rewritten URL. Because $request_uri includes the path and query string, a request such as /account?id=7 becomes https://new.example.com/account?id=7.

Rank #3

Sale

NGINX Unit Cookbook: Recipes for Using a Versatile Open Source Server

$12.31

Buy on Amazon

Use a 302 while validating the target:

return 302 https://new.example.com$request_uri;

Switch to 301 only after the destination is stable. A permanent redirect can be cached by browsers, proxies, and search infrastructure; clearing the Nginx configuration does not necessarily clear those cached responses.

Terminate HTTPS on the subdomain

If users will access https://app.example.com, Nginx needs a certificate that covers that name and a TLS listener. A common arrangement redirects HTTP to HTTPS and proxies HTTPS traffic in a separate block:

server {
    listen 80;
    server_name app.example.com;
    return 301 https://app.example.com$request_uri;
}

server {
    listen 443 ssl;
    server_name app.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://192.0.2.10:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Use certificate paths that exist on the Nginx host and keep the private key readable only by the account that needs it. The public listener handles TLS; the upstream connection can remain HTTP on a protected network or use HTTPS when encryption is required between Nginx and the application.

Proxy to an HTTPS upstream

Change the upstream URL to an HTTPS URL when the destination service expects TLS:

location / {
    proxy_pass https://192.0.2.10:8443;
    proxy_set_header Host app.internal.example;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Certificate validation and SNI matter when the upstream certificate is issued to a hostname rather than the IP address. In that situation, configure the appropriate trusted CA and use proxy_ssl_name with the upstream host name. Send a matching Host header when the upstream virtual host requires it. Do not disable certificate verification merely to hide a name mismatch; correct the trust chain, server name, or certificate instead.

Rank #4

NGINX HTTP Server: Harness the power of NGINX with a series of detailed tutorials and real-life examples

$51.99

Buy on Amazon

Handle paths and trailing slashes deliberately

The URI portion of proxy_pass changes how Nginx constructs the upstream request. When a URI is included, Nginx replaces the part of the original request URI that matched the location. Without a URI, Nginx generally passes the original request URI through.

Test both the root path and nested paths after every change. A missing trailing slash can make HTML load while images, API calls, or redirects fail because the application receives a different path than expected.

Forward raw TCP or UDP with the stream module

For non-HTTP traffic, configure the stream context rather than an HTTP server block:

stream {
    server {
        listen 12345;
        proxy_pass 192.0.2.10:12345;
    }
}

This makes Nginx listen on port 12345 and relay the TCP or UDP stream to the destination port. The stream module must be available in your Nginx build, and the firewall must permit the chosen public port. There are no HTTP headers, URL paths, browser redirects, or HTTP status codes in this mode, so an HTTP configuration cannot substitute for it.

Validate from outside and inspect the right evidence

1. Check DNS from an external network and verify that the name resolves to the Nginx public address. If DNS still points directly to the upstream, the request will bypass your configuration.
2. Run nginx -t and fix every syntax or file-permission error before reloading.
3. Request HTTP headers with curl -I http://app.example.com/. A reverse proxy should return the application’s response; a redirect should return the expected 301 or temporary 302 and a Location header.
4. For HTTPS diagnostics, run curl -vkI https://app.example.com/. The verbose output helps distinguish DNS failure, TCP refusal, certificate problems, and an HTTP response from the upstream.
5. Check Nginx error logs immediately after a failed request. Look for connection refusals, connect timeouts, upstream timeouts, TLS handshake errors, and host-header or certificate-name failures.
6. Test a nested path, a query string, and (if applicable) an application redirect. These expose path-rewrite and forwarded-protocol mistakes that a root request can miss.

Troubleshoot common failures

DNS resolves, but the request times out

Confirm that the DNS address is the Nginx host, that port 80 or 443 is allowed by the host firewall and cloud security group, and that Nginx is listening on the expected address. An AAAA record can cause only IPv6 clients to fail if IPv6 is not configured.

Best Value

NGINX Cookbook: Advanced Recipes for High-Performance Load Balancing

$26.99

Buy on Amazon

Nginx returns 502 Bad Gateway

A 502 usually means Nginx could not obtain a valid response from the upstream. Check that the service is running, listening on the configured interface, and reachable from Nginx at the exact IP and port. Verify protocol compatibility: an HTTP proxy to a raw TCP service, or an HTTPS proxy to a plain-HTTP port, will fail.

The application generates the wrong absolute URLs or redirect scheme

Ensure the application understands the forwarded headers and is configured to trust Nginx. The X-Forwarded-Proto value should reflect the client-facing scheme, while the Host value should match the hostname the application is expected to serve.

Only subpaths fail

Compare the request path with the two proxy_pass forms in the path table. Add or remove the URI and trailing slash deliberately, then test static files, API routes, and redirects rather than only /.

HTTPS shows a certificate warning

Check that the certificate covers the exact subdomain, that the full certificate chain is installed, and that the client is reaching the intended Nginx listener. If the public certificate is correct but Nginx cannot connect to an HTTPS upstream, investigate upstream trust and SNI separately.

A redirect keeps appearing after it was removed

Inspect the response with curl from a cache-free external vantage point and test with a different browser or network. A previously cached 301 can outlive the configuration that created it; use a temporary redirect while experimenting with future changes.

Production decisions and security boundaries

• Keep the upstream private when possible and allow only the Nginx host or network to reach its service port.
• Expose only the public ports you actually use. A backend port such as 8080 does not need to be Internet-facing when Nginx proxies it.
• Use separate server blocks for HTTP redirection and HTTPS application traffic so certificate handling and redirect behavior are explicit.
• Preserve client information with forwarded headers, but configure the application’s trusted-proxy list so untrusted clients cannot impersonate an address or scheme.
• Log both the public request and upstream failures. Correlating the hostname, path, status, and error-log timestamp makes intermittent network problems easier to isolate.
• When changing a path prefix, deploy the Nginx change together with the application’s expected base URL and test links, cookies, API endpoints, and redirects.
• For upstream HTTPS, validate certificates and send the correct SNI name instead of turning verification off.

The practical rule is simple: DNS gets the subdomain to Nginx, server_name selects the virtual server, and either return or proxy_pass determines what happens next. A redirect moves the client; a reverse proxy moves the request behind the scenes.

Quick Recap

SaleBestseller No. 1

NGINX Cookbook: Advanced Recipes for High-Performance Load Balancing

$37.53

SaleBestseller No. 2

NGINX Cookbook: Over 70 recipes for real-world configuration, deployment, and performance

$23.69

SaleBestseller No. 3

NGINX Unit Cookbook: Recipes for Using a Versatile Open Source Server

$12.31

Bestseller No. 4

NGINX HTTP Server: Harness the power of NGINX with a series of detailed tutorials and real-life examples

$51.99

Bestseller No. 5

NGINX Cookbook: Advanced Recipes for High-Performance Load Balancing

$26.99

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.