This is documentation for an outdated product. See the current documentation

ISPmanager 5 Business Documentation

Nginx-proxy

 

This article describes how to proxy requests of user applications, such as phpMyAdmin, phpPGAdmin, Roundcube, etc.

How it all works without Nginx-proxy

If Nginx-proxy is not configured, the control panel redirects requests to user applications to the cluster node with the appropriate role (e.g. "Mail server" for Roundcube). A user can access an application by the cluster node's URL (by default, by the primary IP address of the cluster node, https://12.34.56.78/roundcude ).

When you set up Nginx-proxy

If you provide Shared-hosting services, you may need to configure a single point of access to user applications. Its IP address is the domain name specified in the configuration form. This will allow you to:

  • Access all applications and the control panel (if needed) by a single domain name.
  • Use one SSL-certificate (on a certain domain name) for user applications, and the control panel.
  • A user will have a permanent URL for his application that won't change (for example, when the user is moving between cluster nodes).

Proxy workflow

Proxy runs via the master panel. In the list of Nginx-proxy IP addresses you can see only shared and IP addresses that were created outside the control panel. 

Note
For successful proxy of A-records and aliases on authoritative DNS-server, should point to the nginx-proxy IP address which was selected when connecting the WWW-domain to nginx-proxy. Every 30 minutes the control panel check the IP address of nginx-proxy A-records. If A-records do not point to the IP address, the control panel will show the error notifications:


An Nginx web-server allows to proxy client requests. It can be used to complete the tasks described above.

The proxy scheme:

Note
A client request is passed to a web-server --> the system defines a user and application to manage --> passes the request to the web-server of the corresponding cluster node --> delivers the server’s response to the client.

Nginx is set up on the master-server as follows:

  1. A virtual server is created for a certain domain name on a certain IP on port 80 to redirect requests to the secure connection port
  2. A virtual server is created for a certain domain name on a certain IP on secure port 443, which allows for proxy functions
  3. Virtual directories (locations) are created for each cluster node (location @node1). They are responsible for proxying requests to the cluster node.
  4. Virtual directories (locations) are created for each user (location /username)
  5. In the user location virtual directories (locations) are created for every user application (location /username/appname). They will define the location of the cluster node that the request should be passed to.
  6. If you want to proxy requests to the control panel, the system will configure the location / root virtual directory and the location @ispmgr virtual directory that will proxy requests.

Technical details

  • When creating a cluster node or editing the primary IP address, de-synchronization of the primary IP address is registered. It will set up the primary IP address on the cluster node during synchronization. If Nginx is set up on the cluster nodes:
  1. A virtual server is created in the Nginx configuration file. By default, this server handles requests on the primary IP address of the cluster node (it listens to ports 80 and 443).
  2. The "Priority" checkbox will be cleared for all WWW-domain that had this option set on the new primary IP address of the cluster node. Then WWW domains created on the primary IP address of the cluster node cannot be used as priority WWW domains.
  • Configuration details of the Nginx-proxy virtual server are located in the masterproxy.conf file of the directories in the Nginx (conf.d) configuration files.
  • Virtual directories for user applications are configured only when defining the location of the corresponding user role.

Example of the configuration file of the virtual server

server {
         server_name test.net www.test.net;
         ssl on;
         listen 192.168.40.51:443 ssl;
         add_header Strict-Transport-Security "max-age=31536000;";
         client_max_body_size 0;
         ssl_certificate "/usr/local/mgr5/etc/nginx_certs/masterproxy.crtca";
         ssl_certificate_key "/usr/local/mgr5/etc/nginx_certs/masterproxy.key";
         ssl_ciphers HIGH:!RC4:!aNULL:!eNULL:!MD5:!EXPORT:!EXP:!LOW:!SEED:!CAMELLIA:!IDEA:!PSK:!SRP:!SSLv2;
         ssl_prefer_server_ciphers on;
         ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
         location @node1 {
                 proxy_redirect /$2/ /$1/$2/;
                 proxy_redirect [https://192.168.40.51/$2/|https://192.168.40.51/$2/]  /$1/$2/;
                 proxy_cookie_path /$2/ /$1/$2/;
                 proxy_pass [https://192.168.40.51|https://192.168.40.51] ;
                 proxy_request_buffering off;
                 rewrite ^\/(.*?)\/([^\/?]*)(.*)$ /$2$3 break;
         }
         location @node2 {
                 proxy_redirect /$2/ /$1/$2/;
                 proxy_redirect [https://192.168.40.52/$2/|https://192.168.40.52/$2/]  /$1/$2/;
                 proxy_cookie_path /$2/ /$1/$2/;
                 proxy_pass [https://192.168.40.52|https://192.168.40.52] ;
                 proxy_request_buffering off;
                 rewrite ^\/(.*?)\/([^\/?]*)(.*)$ /$2$3 break;
         }
         location /user1 {
                 location /user1/phpmyadmin {
                         try_files /does_not_exists @node1;
                 }
                 location /user1/roundcube {
                         try_files /does_not_exists @node2;
                 }
         }
         location @ispmgr {
                 proxy_set_header Host $host:$server_port;
                 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                 proxy_set_header X-Forwarded-Proto $scheme;
                 proxy_set_header X-Real-IP $remote_addr;
                 proxy_set_header X-Forwarded-Secret kBBoQd5H6CAcwb5G;
                 proxy_pass [https://192.168.40.51:1500|https://192.168.40.51:1500] ;
                 proxy_request_buffering off;
                 proxy_redirect [https://192.168.40.51:1500|https://192.168.40.51:1500]  /;
         }
         location / {
                 try_files /does_not_exists @ispmgr;
         }
 }

server {
         server_name test.net www.test.net;
         return 301 [https://$host:443$request_uri|https://$host:443$request_uri] ;
         listen 192.168.40.51:80;
 }

In the above example, you can see that MysQL database server and mail server user roles are located on different cluster nodes, requests to the corresponding applications (phpMyAdmin and Roundcube) are passed to different virtual proxy directories.

Changes in the module

Changes in version 5.138.0

A number of changes were made to Nginx-proxy in ISPmanager 5.138.0:

  • To configure the module, navigate to "Domains" --> "WWW-domains" – click "Edit";
  • Nginx-proxy can be enabled only for the existing web-domain with SSL-certificate;
  • Any number of web-domains can be connected to the module;
  • The directory with module settings has been changed. The settings are located in the /etc/nginx/conf.d/masterproxy.d/domain_name.conf file.

Please note: when you set up the proxy domain, all traffic will be counted for the owner of that domain.

When you update ISPmanager with the Nginx-proxy to version 5.138.0 and later, the proxyuser user will be created in the control panel. For this user the system will create a new domain which corresponds to Nginx-proxy before the control panel was updated.

Configuration

Only admins and users with higher privileges can enable Nginx-proxy. Navigate to WWW-domains – select a domain – open the edit form – select the «Secure connection (SSL)» checkbox – enable «Nginx-proxy» — enter the «Nginx-proxy IP address».

Note
If nginx-proxy is created on a local node of the cluster, the system will assign the IP address selected in the 'Nginx-proxy IP address" field. The IP addresses from the "IP address" field will be ignored.


Nginx-proxy uses the SSL-certificate connected for the web-domain and updates information about it when needed. You can use Let's Encrypt certificates as well.

How to disable Nginx-proxy

To disable Nginx-proxy, open the WWW-domain edit form and clear the «Nginx-proxy» checkbox.