Reverse proxy
A reverse proxy allows you to provide access to a website or application via a domain configured in ispmanager. It receives user requests, forwards them to a target server or application, and returns the resulting responses. This destination for requests is called an "upstream"—it could be an application on the same server, an application running in a Docker container, a remote web server, or another proxy.
User → Reverse Proxy → Upstream
User ← Reverse Proxy ← UpstreamBenefits of reverse proxying:
- Security: a proxy helps hide the IP address and internal structure of the upstream server from clients.
- SSL termination: HTTPS can be configured on the proxy. The proxy then decrypts incoming HTTPS traffic—reducing the load on the upstream server—while the connection between the proxy and the upstream server can operate via HTTP.
- Caching: response caching can be configured on the proxy. For subsequent requests, the proxy can serve responses directly without needing to contact the upstream server again, which speeds up the website or application.
How proxying works
In ispmanager, Nginx is used as a proxy.
Proxying methods
There are two available proxying methods: proxying an entire site or proxying specific paths. Rules for proxying specific paths can be configured for both a standard site and a proxy site.
| Option | What is proxied | What happens to other requests |
|---|---|---|
| Proxying a site | All requests to the domain. Additional rules can be configured for specific paths, routing them to a different upstream | Requests to the site root and to paths without specific rules are forwarded to the primary upstream |
| Proxying specific paths | Only requests to the specified paths | Other requests are handled by the primary site—for example, a PHP, Node.js, or Python application |
Upstream connection methods
The connection method depends on the proxying target, i.e., where the upstream is located:
| Proxy target | Connection method |
|---|---|
| Local server | Socket file or URL of the format http://127.0.0.1:PORT |
| Remote server | URL |
| Docker container | Docker container port |
When a proxy is needed
The choice of proxying method and connection type depends on your specific requirements. For example:
| Task | Proxying method | Connection type |
|---|---|---|
| Exposing an application running in a Docker container via a domain name | Proxy site | Docker container port |
A main PHP-based site, with a Java application handling the /api path | Standard site + proxying for the /api path | URL http://127.0.0.1:3000 or a socket |
| A site has been moved to a different server, while the domain and SSL configuration remain in the control panel | Proxy site | URL of the external server |
| An application supports only HTTP, but HTTPS is required | Proxy site with an SSL certificate | URL using http:// |
Requirements for proxy configuration
- ispmanager lite, pro, or host panel
- Nginx web server or an Apache + Nginx combination
- Docker installed (if you plan to use a Docker container)
The upstream must be accessible from the ISPmanager server where the proxy is running:
Connection method What to specify or prepare URL The HTTP or HTTPS address of the upstream. This can be local (e.g., http://127.0.0.1:3000) or remote (e.g.,https://app.example.com). For access via a domain name, the domain's DNS records must point to the server hosting the proxy. For HTTPS access, a valid SSL certificate must be configured for the domain.Socket file The path to the application's socket file. The socket must be accessible to Nginx processes Docker container port A running container, with the application port inside the container mapped to a server port through which the proxy can connect to the application
Limitations for a proxy site
The following features are unavailable for a proxy site:
- installation of CMS and web scripts
- Site.pro website builder
- error pages, redirects, and directory access control
- configuration of PHP / Node.js / Python handlers, CGI, and the site directory
- Nginx static content caching, static file extensions, and cache duration settings
For a standard website where only specific paths are proxied, these features remain available.
Proxy configuration
Proxy configuration must be performed using an administrator-level account or above.
Step 1. Preparing the application
Launch the application and ensure that it is accepting requests.
If the application is running in a Docker container, verify the port mapping. For example, if the application listens on port 3000 inside the container and this port is mapped to port 8080 on the server, then port 8080 should be used for connections from the server.
If the application is accessible via a URL, first verify its response from the server where the proxy is running:
curl -i http://127.0.0.1:8080/Replace the address and port with your own. For a remote upstream, use its URL.
Step 2. Creating a proxy site
- Go to the Sites section.
- On the toolbar, click Create a site → Reverse proxy.
- Specify the site settings. Required fields are marked with an asterisk.
- Proxied domain* — the domain name through which the site will be accessible on the internet
- Site owner* — the user who will own the site
- SSL certificate * — a certificate for a secure connection:
- New free certificate from Let's Encrypt
- New self-signed certificate
- Existing certificate
- None (not used)
- Specify the proxy settings. Required fields are marked with an asterisk.
- Save the changes.
The proxied site will appear in the Sites section, marked with the
icon. Click this icon to view the configured proxies. Immediately after the site is created, it will show one proxy configuration — for the site root.
Step 3. Adding a proxy for a specific path
- Go to the Sites section.
- Next to the desired site, click
. - Select Request proxy from the context menu.
- Click Create proxying on the toolbar.
- Specify the proxy path:
- Proxied path* — the path on the domain for which requests will be forwarded to the upstream server. The path is defined relative to the domain root. For example, if you specify the path
blogfor the domainexample.com, requests tohttp(s)://example.com/blogwill be proxied. You can create only one proxy configuration for each path.
- Proxied path* — the path on the domain for which requests will be forwarded to the upstream server. The path is defined relative to the domain root. For example, if you specify the path
- Specify the proxy settings. Required fields are marked with an asterisk.
- Save the changes.
The
icon will appear next to the site for which proxy configurations have been added. Click this icon to view the configured proxies.
Step 4. Verifying the proxy
Check access via the domain
Open the site at the configured address. Verify not only the main page but also key functions, such as loading resources, navigating between pages, and making API requests (if applicable).
To verify the response via the command line, run the appropriate command. If HTTPS has not yet been configured, use http://.
curl -i https://PROXY_DOMAIN/The expected result depends on the application: it could be a successful response, a redirect to the login page, or a request for authorization.
Check a specific path
If proxying for /api is configured, request an existing application resource:
curl -i https://example.com/apiNext, test a resource located outside the proxied path. It should be handled by the regular site or the primary upstream, depending on your chosen configuration.
Check HTTPS and redirects.
Ensure that the browser does not report a certificate error, that the application does not redirect the user to an internal address, and that no redirect loops occur.
If the result is not what you expected, check the Nginx and application logs.
Proxy settings
Basic settings
Proxy target* — upstream address:
URL* — URL in the format
http(s)://IP_OR_DOMAIN/SOURCEPath to the socket file — the path to the socket file on the local server running ispmanager
- Docker container — a container in which an application is running, acting as an upstream
- Port — the container port that you specified when configuring port mapping
Advanced settings
- Cache upstream responses — check this box to enable caching of upstream responses on the proxy. By default, responses to GET and HEAD requests are cached. Caching parameters (such as size and TTL/lifetime) are defined in the panel's configuration file.
- Timeouts*:
- Connection timeout — the time allowed for establishing a connection between the proxy and the upstream server. If a connection is not established within this period, the request will be terminated, and the client will receive an error. Default value: 30 seconds.
- Send timeout — the time allowed for sending a request from the proxy to the upstream server. This is measured between successive write operations; if the upstream server fails to accept the next portion of data within this time, the connection will be dropped. Default value: 120 seconds.
- Response wait timeout — the time allowed for the proxy to receive a response from the upstream server. This is measured between successive read operations; if the upstream server does not respond within the specified time, the connection will be closed. Default value: 180 seconds.
- Headers — headers that the proxy forwards to the upstream server along with the request. The `Host`, `X-Forwarded-For`, `X-Forwarded-Proto`, and `X-Forwarded-Port` headers are added automatically. To override the `Host` header, add a new `Host` header with your own value. Header values are enclosed in quotation marks to prevent the injection of directives.
Managing proxy
Clearing the proxy cache
The cache is updated automatically when its time-to-live (TTL) expires. You can also clear it manually if needed:
- Log in to the control panel using an administrator-level account or above.
- Go to the Sites section.
- Next to the desired site, click
. - Select Request proxy from the context menu.
- Select the proxied path and click
Clear the upstream response cache for the selected paths on the toolbar. .
The cache directory for the selected proxy configuration will be deleted and recreated as an empty directory.
Deleting proxy
- Log in to the control panel using an administrator-level account or above.
- Go to the Sites section.
- Select the desired site and click
on the toolbar.
This will remove the site, all its proxy configurations, Nginx configuration files, cache directories, and auxiliary directories.
- Log in to the control panel using an administrator-level account or above.
- Go to the Sites section.
- Next to the desired site, click
. - Select Request proxy from the context menu.
- Select the desired path and click
on the toolbar.
The proxy configuration, its Nginx configuration file, and the cache directory will be removed.
Proxy configuration files
Proxying rules
The configuration of proxying rules consists of two levels and includes the following files:
/etc/nginx/vhosts-resources/DOMAIN/reverse-proxy.d/PROXY_ID.conf— a configuration file for proxying rules applicable to a specific path. It is named according to the identifier found in the reverse_proxy database table./etc/nginx/vhosts-resources/DOMAIN/reverse-proxy.conf— an index file that incorporates the proxying rule configuration files for all paths on a given domain. This file is included within theserverblock of the site's configuration file.
Below is the structure for how these configuration files are linked:
To view and edit the proxy configuration file:
- Log in to the control panel using an administrator-level account or above.
- Go to the Sites section.
- Next to the desired site, click
. - Select Request proxy from the context menu.
- Select the proxied path and click
on the toolbar.
location / {
resolver 1.1.1.1 8.8.8.8 valid=300s;
proxy_pass $rp_upstream$request_uri;
proxy_redirect https://PROXY /;
access_log /usr/local/mgr5/var/nginx.log ispmgr_trafstat;
access_log /var/www/httpd-logs/ПРОКСИ.access.log ispmgr_reverse_proxy;
proxy_set_header Host "custom_host";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Port $server_port;
proxy_connect_timeout 30s;
proxy_send_timeout 120s;
proxy_read_timeout 180s;
set $rp_upstream https://UPSTREAM;
proxy_ssl_server_name on;
proxy_ssl_name "Custom host";
proxy_cache rp_2;
proxy_cache_key $scheme$host$request_uri;
proxy_cache_methods GET HEAD;
proxy_cache_lock on;
proxy_cache_revalidate on;
proxy_cache_use_stale updating;
}For more details on proxy configuration parameters, please refer to the official Nginx documentation.
- resolver — name servers used to resolve an upstream name into an IP address. They can be specified as a domain name or IP address, with an optional port number. Default values: 1.1.1.1, 8.8.8.8. The `valid` parameter determines how long the responses from the name servers are cached. Default value: 300s (300 seconds)
- proxy_pass — the address of the proxied resource
- proxy_redirect — the address of the proxy site that Nginx will pass to the client in the response header
- access_log — settings for logging traffic and visits for the proxy: the directive with ispmgr_reverse_proxy defines a custom access log format, while the directive with ispmgr_trafstat enables traffic logging for the site
- proxy_set_header — request headers that the proxy passes to the upstream server
- proxy_connect_timeout — connection timeout. Default value: 30s (30 seconds)
- proxy_send_timeout — send timeout. Default value: 120s (120 seconds)
- proxy_read_timeout — response wait timeout. Default value: 180s (180 seconds)
- set $rp_upstream — creates an Nginx variable that stores the address of the upstream server to which the proxy will forward requests
- proxy_cache — the proxy cache zone—that is, the name of the directory on the disk where the cache for a given path is stored. rp_ID is significant, where `ID` represents the proxying identifier within the reverse_proxy database table
- proxy_cache_key — the caching key, i.e., the identifier for a cached response to a request, defined as $scheme$host$request_uri, where `$scheme` is the request protocol (HTTP or HTTPS), `$host` is the request domain, and `$request_uri` is the path to the resource on that domain
- proxy_cache_methods — the types of requests for which responses are cached and served from the cache. The default values are GET and HEAD. All other request types are always forwarded to the upstream server
- proxy_cache_lock — when enabled, if multiple simultaneous requests are made for the same uncached resource, only one request is forwarded to the upstream server, while the others wait for its response. This protects the upstream server from a surge of identical requests. The default setting is on (enabled)
- proxy_cache_revalidate — when enabled, if a cache entry expires, Nginx queries the upstream server to check whether the response has changed. If there are no changes, the cache entry is extended without requiring a full refresh. This speeds up request processing when the cache expires. The default setting is on (enabled)
- proxy_cache_use_stale — if this directive includes the updating parameter, an outdated copy of a cache entry is passed to clients while the entry itself is being updated. This accelerates request processing during cache updates
Cache
The proxy cache configuration consists of two levels and includes the following files:
/etc/nginx/conf.d/reverse-proxy-cache.d/DOMAIN/PROXY_ID.conf— a cache configuration file for a specific path. It is named according to the identifier found in the reverse_proxy database table./etc/nginx/conf.d/reverse-proxy-cache.conf— an index file that includes the cache configuration files for all paths within a domain. This file is included in thehttpsection of the global Nginx configuration file.
Cache data is stored in the /var/cache/nginx/reverse-proxy/DOMAIN/PROXY_ID directory.
Below is the structure for the configuration file inclusion:
proxy_cache_path /var/cache/nginx/reverse-proxy/DOMAIN/PROXY_ID levels=1:2 keys_zone=rp_PROXY_ID:1m max_size=64m inactive=24h use_temp_path=off;Directive parameters are taken from the ispmgr.conf panel configuration.
proxy_cache_path — defines caching parameters:
- /var/cache/nginx/reverse-proxy/DOMAIN/PROXY_ID — the directory where the cache is stored
- levels — the directory nesting hierarchy for the cache. The default value, 1:2, means that Nginx will create a two-level structure:
• First level — a directory named using the last character of the hash (e.g.,/c/)
• Second level — a directory named using the two preceding characters (e.g.,/29/)
• The resulting file, b7f54b2df7773722d382f4809d65029c, will be stored in the directory/var/cache/nginx/reverse-proxy/DOMAIN/PROXY_ID/c/29/ - keys_zone — a zone in RAM used to store cache metadata for a given proxy configuration. Default values:
- rp_PROXY_ID — the zone key (identifier)
- 1m — the size of the zone (1 MB)
- max_size — the maximum size of the cache on disk for a given proxy configuration. Default value: 64m (64 MB)
- inactive — the lifespan of an inactive cache item. If a cached file is not accessed within this period, Nginx will remove it from the disk. Default value: 24h (24 hours)
- use_temp_path — the use of a temporary directory. If enabled, Nginx first saves the file to a general temporary directory before copying it to the cache directory. Default value: off (disabled)
Proxy tables in the database
Information about proxy configurations is stored in the panel's database.
The site status is stored in the webdomain table in the reverse_proxy field: on indicates that the site is a proxy, while off indicates that it is a regular site.
Proxy settings are stored in the reverse_proxy table.
- id — proxy ID
- site_id — link to the webdomain table. When a site is deleted, the proxy entry is also deleted.
- location — proxied path
- target_type — proxy target type: 0 — URL, 1 — socket, 2 — Docker container
- target — target resource (URL, socket path, or CONTAINER:PORT)
- cache_upstream_answer — response caching status: on — enabled, off — disabled.
- connect_timeout — connection timeout
- send_timeout — request sending timeout
- read_timeout — response waiting timeout
- headers — custom headers in base64 encoding