Relay Balancer (HALB) New in 2.2
The Relay Balancer (HALB) is DartRelay's own high-availability load balancer, for sites that run two or more DartRelay servers and have no load balancer of their own in front of them. One server in the pool answers for it at a time, shares the launches out between the servers, and if that server stops, another takes over by itself.
What the Relay Balancer does
Every DartRelay server in a pool can serve the portal, because they share one database. What a pool needs is one address that people use, and something that sends each launch to a server that is up. The Relay Balancer does both from inside DartRelay:
- One server answers for the pool. It carries the pool's address, or the portal's DNS name points at it. People sign in through it exactly as they would on a single server.
- Launches are shared out. Each launch goes to the least busy healthy server. A person's applications are kept together on the server that already runs their session, so they share one Windows session as they would on a single server.
- Another server takes over. The servers keep a lease in the shared database. If the server answering for the pool stops, crashes, or loses its network or database, another server takes over within about ten seconds.
- Open tabs reconnect by themselves. A tab whose connection ran through a server that stopped shows Reconnecting to your session… and comes back through another server, with the same windows. See What people see during a failover.
- Drained servers are left out. A server you drain for maintenance is given no new launches and does not answer for the pool.
If you already run NetScaler, F5 BIG-IP, nginx, Kemp LoadMaster or another load balancer, keep using it: see High availability (server pools) and Load balancer and ADC integration. The Relay Balancer is the alternative for sites that don't.
Choosing a mode
Open System → Relay Balancer (HALB). The Mode list has three choices.
| Mode | How people reach the pool | Use it when |
|---|---|---|
| Off | Through your own load balancer, or straight to one server. | You have an appliance, or a single server. |
| Floating address | A spare IPv4 address on the servers' subnet. The server answering for the pool carries it, and the next one carries it after a move. | The servers are on one ordinary office or data-centre network (any firewall, switch, Hyper-V or VMware). Your firewall forwards the public address to the pool address. |
| DNS name | The portal's DNS name. The server answering for the pool points the name's A record at its own public address. | The servers are in a public cloud, on VPSs, at several sites, or behind a firewall with one public address per server. Cloud networks ignore a floating address, so use this mode there. |
Before you start
- A pool. Two or more DartRelay servers on one shared SQL Server, MySQL or PostgreSQL database. See Adding a server to a pool.
- The same HTTPS certificate on every server. A Let's Encrypt certificate obtained in the console is shared through the database already. A certificate you imported has to be imported on each server.
- Every server listening on all addresses. On System → Endpoints, the HTTPS endpoint uses
0.0.0.0, so a server answers on the pool address or its public address when it is its turn. - The servers can reach each other on their own addresses and DartRelay port, to hand over launches and sessions. Allow that through Windows Firewall between them.
- Permissions. Changing the Relay Balancer needs the Security permission as well as Endpoints.
Setting up a floating address
- Pick a spare address. An unused IPv4 address on the same subnet as the servers, outside your DHCP range, for example
192.168.10.160. - Choose the mode. On System → Relay Balancer (HALB), set Mode to Floating address, enter the address in Pool address and click Save. Within a few seconds one server carries it; the Now panel says which.
- Point the firewall at it. Forward your public address (port 443) to the pool address, not to a server. For people inside the network, point the portal's DNS name at the pool address too.
- Check it. Open the portal through its public name, sign in and launch something.
DartRelay adds and removes the address itself. On Windows it runs as a service with the rights to; on Linux it needs root or CAP_NET_ADMIN, and arping to announce a move straight away. If a server has two network cards on the subnet, name the one to use in its configuration file.
Setting up a DNS name
- Give each server its own public address. On your firewall or cloud platform, forward one public address (port 443) to each server. Each server needs an address that reaches it alone.
- Choose the mode and the name. Set Mode to DNS name and enter the name your users type in DNS name, for example
apps.example.com. - Choose the DNS provider that hosts that name, and enter its credentials: see DNS providers. Click Test to check that DartRelay can read the zone and the record; it changes nothing.
- Save. Within a few seconds one server points the name at its public address. The Now panel shows which server answers and when the record was last written.
- Set each server's public address in the table under Which servers can answer for it, if the servers share an outgoing address. See Each server's public address.
DartRelay keeps one plain A record for the name. If none exists it creates one with a 1-minute TTL; an existing record keeps its own TTL, so set it to 1 minute for the fastest moves. The name must not be a CNAME, an alias, an IPv6 (AAAA) record or a record with several addresses: DartRelay refuses those and says what to delete. While a server answers for the pool it reads the record back every minute and puts it right if someone has changed it.
DNS providers
| Provider | What to enter | Rights it needs |
|---|---|---|
| Cloudflare | An API token. | Zone → DNS → Edit, and Zone → Zone → Read, for the zone that holds the name. A proxied record moves at once; a DNS-only record within its TTL. |
| Amazon Route 53 | An access key ID and secret access key. | An IAM user allowed route53:ListHostedZonesByName, route53:ListResourceRecordSets and route53:ChangeResourceRecordSets, ideally limited to the hosted zone. The zone must be public. |
| Azure DNS | The tenant ID, client (application) ID, a client secret, and the subscription that holds the zone. | An app registration in Microsoft Entra ID with the DNS Zone Contributor role on the zone or its resource group. DartRelay finds the zone in the subscription itself. |
| My own script, on each server | Nothing on the console. Each server names its own script in its configuration file. | Whatever your DNS service needs. See Using your own script. |
Credentials are kept encrypted in the shared database and never shown again; leave a secret box empty to keep the saved one. Each provider keeps its own credentials, so switching provider and back does not lose them.
Each server's public address
Each server finds out its public address by asking the internet what its outgoing address is. That is right for a server with its own public address, as in most clouds. It is not right for servers behind one firewall that share an outgoing address: every one of them sees the same address, and that address does not reach any one server.
For those, type each server's own public address (the one your firewall forwards to it) in its row of the table and click Set. The row shows the address with set or detected beside it. Click Set with the box empty to go back to detecting.
A server that has no address set will not point the name at an address another server also detects. That address belongs to a shared firewall, and pointing the name at it would leave the portal unreachable. The server stays out of the running and its row says why, until you set its address.
Using your own script
For any other DNS service, each server runs a script of yours. Name its full path in that server's configuration file as DartRelay:Balancer:DnsScript; it is set there rather than on the console, so the console can never make the servers run a program. On Windows a .ps1 script is run with -Name apps.example.com -Address 203.0.113.10; any other script gets the name and the address as its two arguments. Both are also in the environment variables DARTRELAY_DNS_NAME and DARTRELAY_DNS_ADDRESS. Exit code 0 means done. The script has a minute to finish, runs again every ten minutes while its server answers for the pool, and what it prints goes to that server's log.
What people see during a failover
- New sign-ins and launches go to the server that took over. With a floating address that is within seconds. With a DNS name, people's computers notice the new address within the record's TTL, usually a minute or two.
- Open tabs whose connection ran through the server that stopped show Connection lost — Reconnecting to your session… with Reconnect now and Close. The portal keeps trying for about two and a half minutes, then says it could not reconnect and leaves Reconnect now to try again.
- Nothing is opened twice. The Windows session on the host is still there, so the reconnected tab is handed the program's windows back instead of starting another copy. Other programs that were open come back as tabs of their own a few seconds later. A program that turns out not to be running any more is started as usual.
- No second password prompt. For Pass-Through resources, the Windows password a person typed is kept for the pool as a temporary, encrypted copy in the shared database, so the server that takes over can use it. The copy is removed when the person signs out, when their sign-in would expire, or when the password is changed.
- Tabs ended on purpose do not reconnect. A session an administrator ended, an idle sign-out or a released seat says so instead.
Moving it by hand
To move the pool to another server, for example before maintenance on the one answering for it, click Move address here (floating address) or Answer from here (DNS name) in that server's row. Tabs carried through the server that answered until then reconnect, as in a failover. A server that comes back after a failover does not take the pool back by itself; that avoids interrupting people twice. Use the button if you want it back.
To take a server out for maintenance, drain it on System → Load balancer. A drained server gets no new launches and does not answer for the pool.
Per-server settings
A few settings describe one server rather than the pool, and live in that server's configuration file:
| Setting | What it does |
|---|---|
DartRelay:Balancer:DnsScript | The full path of this server's DNS script, for My own script. |
DartRelay:Balancer:NeverHold | true: this server never answers for the pool. It still serves launches handed to it. |
DartRelay:Balancer:Interface | Which network card carries the floating address, when two are on the subnet. |
DartRelay:Balancer:AllowInCloud | true: allow floating-address mode on a server that looks like a cloud machine. Use DNS name mode there instead unless you know the network passes the address. |
If something goes wrong
The portal is refused after a move (DNS name)
The name points at an address that does not reach the server answering for the pool. Check the A record and the Public address column: each server should show its own address with set, and your firewall must forward each of those addresses to its server on port 443.
A server says it detects a shared address
That is the safeguard at work. Set that server's own public address in its row.
Test says the token, key or app was refused
The credentials lack a right listed in DNS providers, or cover a different zone. Fix the rights in the provider's console and click Test again.
Test says the name is a CNAME, an alias or an IPv6 record
Delete that record in your DNS provider. DartRelay creates the A record itself.
Nobody carries the floating address
Look at the Can carry it column for the reason on each server: drained, Relay Core not answering, no network card on the address's subnet, or a cloud machine. The log on each server has the details.
Clients keep reaching the old server for minutes after a move
The record's TTL is long. Set it to 1 minute, or with Cloudflare make the record proxied.
Related pages
High availability (server pools)
What a pool is and how to add servers.
Load balancer and ADC integration
Using your own load balancer instead.
Endpoints and certificates
Listeners and the shared certificate.
Server configuration file
Per-server settings.
