Beta. This feature works and is being tested on more setups. Report anything that does not behave as described here.
Servers behind NAT share the node's public IPv4 address, and port forwards only give them ports from 1024 up. With websites by domain, the node's agent listens on ports 80 and 443 of that shared address and passes each connection to the NAT server whose domain it names, so cheap NAT plans can host ordinary websites.
This feature is beta: it works, and is being tested on more setups; please report problems you find.
How it works#
The proxy is part of the VMStack agent (no HAProxy or nginx on the node). It listens on IPv4 ports 80 and 443 of the node only while at least one domain is configured on the node.
| Port | How the server is chosen | What reaches the server |
|---|---|---|
| 443 (HTTPS) | The TLS server name (SNI) in the visitor's ClientHello | The untouched TLS stream, on the server's port 443. Nothing is decrypted. |
| 80 (HTTP) | The Host of the first request (or an absolute-form request target) |
The whole request, unchanged, on the server's port 80. Later requests on the same kept-alive connection go to the same server. |
The destination is always the server's own private NAT address on that node, looked up by the agent; nobody can point a domain at another address.
Certificates#
VMStack holds no certificates and no private keys. The server keeps its own certificate (certbot, acme.sh or its control panel's), and the visitor's browser checks that certificate. Let's Encrypt HTTP-01 validation works: requests for /.well-known/acme-challenge/... on port 80 reach the server like any other request. There is no "free certificate" option in the panel.
Names and wildcards#
- A domain is one exact name, such as
shop.example.com, or a wildcard such as*.example.com. - A wildcard matches one level only:
a.example.com, nota.b.example.com. Exact names are matched first. - Internationalised names are stored in punycode. IP addresses, single labels and numeric top-level domains are refused: "Enter a domain such as example.com or *.example.com."
- A verified domain belongs to one server across the whole panel.
Answers for unknown names and errors#
| Situation | Port 80 | Port 443 |
|---|---|---|
| No website for this name on this node | 404 "No website is configured for this name on this host." |
TLS alert unrecognized_name |
No Host, two Host headers, an IPv6 literal, a malformed request |
400 |
TLS alert decode_error (malformed ClientHello) |
| Request head larger than 16 KiB | 431 |
ClientHello larger than 64 KiB is refused |
| Head not sent within 10 seconds | 408 |
Connection closed |
| The server does not answer | 502 |
Connection closed |
| More connections than the domain's limit | 503 |
Connection closed |
Before you start#
Admin side.
- The node has a NAT network and NAT servers: see NAT servers and port forwards.
- The node's agent has the domain proxy (agent 0.44.0 or later). Without it the section says "Websites by domain can be used once this server's host is updated."
- Nothing else on the node listens on TCP port 80 or 443 of its IPv4 addresses. If something does, the proxy reports "port 80 is used by another program on this node" (or 443), tries again every minute, and serves the other port meanwhile.
- Give the plan an allowance: in Customers › Hosting plans, with Network set to Behind NAT, set Website domains included (0-100, default 0). The default 0 means existing plans do not offer it until you choose to. Administrators creating a server with a size of their own set Website domains (0-1000) on the create form.
With the node firewall on, the agent opens TCP 80 and 443 over IPv4 from anywhere while the node has domains, and closes them again when the last domain goes. IPv6 to these ports stays closed: the proxy is IPv4 only.
Add a domain#
Customer side. The server's owner, the owner's reseller or an administrator does this; a customer needs the Port forwards permission, which covers website domains too (see Customer permissions).
- Open the server, go to its Network tab and find Websites by domain, under Port forwards. The header shows "1 of 3 in use" and the public address.
- Click Add a domain and enter the Domain, for example
shop.example.comor*.example.com. - Optionally tick Server ports and PROXY protocol to change:
- HTTP (80) to server port, default 80;
- HTTPS (443) to server port, default 443;
- PROXY protocol: Off, Version 1 or Version 2 (see PROXY protocol);
- Connections at most (administrators only), 1 to 10000; empty uses the panel default of 256.
- Click Add domain.
The domain is added in the state Waiting for the TXT record, and the row shows the TXT record to create.
Prove the domain is yours#
Traffic is sent only after the customer proves control of the domain's DNS zone with a TXT record:
| Record | Name | Value |
|---|---|---|
| TXT | _vmstack-verify.example.com |
vmstack-verify=<token> (shown on the row, with a copy button) |
For a wildcard *.example.com the record is also at _vmstack-verify.example.com.
After adding the record, click Check now (at most 10 checks a minute per account). The panel also checks by itself every 10 minutes for 7 days after the domain was added; after that only Check now checks. While the record is missing the row says "No TXT record _vmstack-verify.example.com with the value shown yet."
Once found, the domain is verified and goes to Waiting for the host, then Active when the node confirms it.
Pointing the A record at the node is not enough to verify: on a shared NAT node a neighbour could otherwise claim a domain that already points there. An unverified domain reserves nothing; if two servers add the same name, the first to verify gets it, and the other sees "This domain was verified on another server first."
Administrators can click Mark verified on a pending domain for support cases. This is recorded in the audit log.
DNS records for visitors#
| Record | Should name |
|---|---|
| A | The node's public IPv4 address (the Public address in the section header) |
| AAAA | One of the server's own IPv6 addresses, or nothing. Not the node. |
The panel reads the domain's A and AAAA records at each check and once a day for verified domains, and shows a DNS line on the row:
- "Points here."
- "Points to 203.0.113.9: change the A record to 198.51.100.7."
- "No A record yet: add one with 198.51.100.7."
- An added warning when the AAAA record names an address that is not the server's: "IPv6 visitors go to ...: name your server's own IPv6 address in the AAAA record, or remove it."
For a wildcard, a random name under it is looked up. The panel does not write DNS records: the customer's domain lives in the customer's own DNS.
PROXY protocol#
Without PROXY protocol the server sees every connection coming from the node's NAT gateway address. With Version 1 or Version 2, the agent sends a PROXY header first, so the server's logs show the visitor's address.
Warning: The server's web server must expect the header, or every request fails there. For nginx:
listen 443 ssl proxy_protocol;(andlisten 80 proxy_protocol;), withset_real_ip_from <NAT gateway>;andreal_ip_header proxy_protocol;. For Apache:RemoteIPProxyProtocol On.
Edit and remove#
Edit changes the server ports, PROXY protocol and, for administrators, the connection limit; the node gets the new list at once. Remove asks for confirmation: "Visitors get a 'no website' page at once, and the name may be taken by another server."
The allowance#
Staff change a server's number with Change allowance in the section: administrators 0 to 1000, resellers up to the plan's value. An upgrade to a plan with more raises it. Lowering it removes nothing; the owner cannot add another until under it. When the allowance is used up: "This server uses all 3 of its website domains. Remove one to add another."
Domain states#
| State | Meaning |
|---|---|
| Waiting for the TXT record | Added, not verified yet. |
| Waiting for the host | Verified, sent to the node, not confirmed yet. Also shown while the server is being built or deleted. |
| Active | The node serves it. |
| Off while the server is suspended | A suspended server's domains are left out of the node's list; visitors get the 404 page. They come back when the server is unsuspended. |
| Not active: ... | The node does not serve it, with the node's reason, for example "no server behind NAT with this id on this node". |
What staff see on the node#
Admin side. The node page has a Domains tab, after Port forwards. It shows the proxy's state (serving, the node's problem, or not running because the node has no domain) and lists every domain on the node with its server and owner, state, DNS line, verification date and how it was verified. Filters: Domain or server and State. Remove takes a domain off after confirmation; it is recorded in the audit log with your name. The customer is not mailed.
Limits#
| Limit | Value |
|---|---|
| Time to send the ClientHello or request head | 10 seconds (slow senders are cut) |
| Time to reach the server | 5 seconds |
| Idle connection | 10 minutes without a byte either way |
| Connections per domain | 256 by default (panel), 1 to 10000 set by administrators |
| Connections per client address still sending their head | 32 |
| Proxied connections per client address | 256 |
| Connections on the node in all | 8192 |
| Domains per node | 4096 |
Firewalls#
Proxied connections come from the node itself, not through the forward path, so the server's panel firewall does not filter them. A firewall inside the server does. To block visitors of a domain, remove the domain or filter inside the server.
Moves and deletion#
- When a server moves to another node, its domains move with it and both nodes get their new lists. If the public address changes, the mail Server moved to another host and the audit log name the domains whose A record must change, and their DNS line says "Points to ..." until it is changed.
- When a server is deleted, its domains are removed and the node's list is sent again.
API and webhooks#
The API has GET/POST /servers/{id}/domains, PATCH/DELETE /servers/{id}/domains/{domain}, POST /servers/{id}/domains/{domain}/check, POST /servers/{id}/domains/{domain}/mark-verified (administrators) and GET /nodes/{id}/domains. The allowance is nat_domains_limit in PATCH /servers/{id}. The webhook events server.domain_added, server.domain_verified and server.domain_removed let a billing or DNS system act, for example to create the A record. See Webhooks.
Not supported#
- TLS termination or certificates issued by the panel.
- HTTP/3 (QUIC on UDP 443): browsers fall back to TCP.
- Other TCP services by name, or IPv6 on the proxy.
- Several public addresses per node.
- Billing module client areas (WHMCS, Blesta) for domains.
- A mail to the customer when staff remove a domain.
- A load balancer on ports 80 or 443 of a node that serves website domains: the proxy listens on those ports of every address of the node. The panel refuses such a listener; a domain added after a balancer took 80 or 443 is not refused, and the proxy reports a port problem instead.