Adding and preparing hosts

A host is a Windows machine that runs the applications and desktops you publish. This page explains how to add one, how DartRelay checks whether it is ready, and how it can prepare the host for you remotely.

What a host is, and why it needs preparing

Everything a user opens in the portal actually runs on a host. When somebody clicks an application, DartRelay opens a Remote Desktop session to the host on their behalf and shows that session inside the browser tab. The host does the work; DartRelay delivers the picture.

Most hosts are Windows Server machines. To let several people work on one at the same time, Windows Server needs the Remote Desktop Session Host role. Without it, Windows Server runs in a mode meant for administering the machine, which allows only two connections at once. A desktop published from such a host works for the first two people and then refuses everyone else. This is the single most common reason a new installation "works in testing and fails on Monday morning", so DartRelay checks for it on every host and tells you plainly.

A Windows 10 or Windows 11 desktop edition can be added as a host, but it allows only one session at a time. DartRelay recognises a desktop edition and says so rather than offering to install a role that does not exist there.

Nothing is installed on the host

DartRelay is agentless. There is no DartRelay software, service or agent to install on a host, and nothing to keep up to date there. Instead, you give DartRelay a management account for each host, and it uses Windows' own remote administration features to read the host's state and, when you ask it to, to change it.

It helps to know exactly what DartRelay touches, because you are handing it an administrator account:

DartRelay never switches on RemoteApp list enforcement, never removes RemoteApp entries somebody published by hand, and never runs a command it was not built with: every script it sends is fixed. Every role install, sign-in grant and session sign-out is recorded in the audit log with the administrator who asked for it. See Logs and audit.

Before you begin

• A management account for the host. It must be a member of the host's local Administrators group. A domain account works (CORP\svc-dartrelay or svc-dartrelay@corp.example.com), and so does a local account on the host (.\Administrator). The .\ prefix tells DartRelay the account is local to the host, even when the host belongs to a domain.
• Network access from the DartRelay server to the host on the ports in the next section.
• The host's name or IP address, as the DartRelay server can reach it.

What the host must allow

Add a host

1. Open the Hosts page. In the console, go to Catalog → Hosts. The list shows every host with a Readiness column.
2. Start a new host. Click the button to add a host. The new-host form opens.
3. Give the host a name. This is the name administrators see in the console; pick something people recognise, such as "Finance RDS 1".
4. Enter the host's address. Type the host name or IP address the DartRelay server uses to reach it.
5. Fill in the domain if the host needs one. For a host in an Active Directory domain, enter the domain's short (NetBIOS) name. For a stand-alone host that is not in a domain, enter the host's own computer name. See The Domain field below.
6. Enter the management account. Type the username and password in the Management account panel.
7. Press Connect. DartRelay contacts the host with that account and reports what it found: the Windows edition, whether the Session Host role is installed, and anything that needs attention. If the password is wrong, it says so here, before you have saved anything.
8. Save the host. The result of the check is saved with the host, so the host page opens already showing it. If you change the address after pressing Connect, the result is withdrawn, because it described a different machine; press Connect again.

The role cannot be installed from the new-host form. Installing a Windows role, and possibly restarting a host, is the most consequential thing DartRelay does, so it is only offered on a host that has been saved. Continue on the host's own page.

The Domain field

When DartRelay opens a session with a saved account, Windows needs to know which account database the name belongs to. The host's Domain field supplies it when the account itself does not:

• A saved account written as NAME\user uses NAME, whatever the host's Domain field says.
• Otherwise the host's Domain field is used.
• When the host is the same machine DartRelay is installed on, and nothing else gives a domain, DartRelay uses the machine's own name.

For a stand-alone (workgroup) host with local accounts only, put the host's computer name in the Domain field. Windows refuses a local account with an empty domain when Network Level Authentication is on, and the symptom is the unhelpful "Server refused connection (wrong security type?)".

Readiness: what the host page tells you

Open a host from the list to see its page. The Management account panel at the top holds the account, the Connect button and the readiness verdict, because the verdict describes what that account found.

The same verdict also appears, read-only, on the pages where you publish desktops and applications from that host, with an Open host settings → link for administrators who are allowed to manage hosts. You do not have to remember to check: if a host will refuse the third user, the page you are publishing from says so.

Remote Desktop licensing

Once the Session Host role is installed, Microsoft requires a Remote Desktop Services client access licence (RDS CAL) for every connecting user or device, after a grace period of 120 days. When the grace period ends with no licence server configured, Windows refuses everyone except administrators. What a user sees is a connection error about the security type, which points nowhere near licensing.

To catch this before it happens, the readiness check reads the host's licensing mode, the days left in its grace period, the licence servers it is configured to use, and whether it can reach them. The host page shows a plain sentence, such as a countdown of days left, or a warning that the configured licence server cannot issue licences, with what to do about each case. DartRelay does not sell or manage Microsoft licences; it only tells you what the host reports.

Install the Remote Desktop Session Host role

If a host has no Session Host role, DartRelay can install it for you.

1. Open the host's page from Catalog → Hosts.
2. Make sure the management account is saved and Connect succeeds. The install panel appears when the role is missing.
3. Leave Let the domain's users sign in ticked unless you manage Remote Desktop access yourself. See Who may sign in through Remote Desktop.
4. Decide whether DartRelay may restart the host. Restarting is a separate tick box. If you leave it clear, the role is installed and the host shows ⚠ Restart needed until you restart it at a time that suits you.
5. Press Install RD Session Host role. A progress bar and an elapsed-time counter run while Windows installs the role. This usually takes several minutes, and Windows reports no percentage, so the counter is the honest measure. Leave the page open.
6. Read the result. If you allowed a restart, the host goes down about a minute later and, once it is back, the next page that shows it confirms the role. If you did not, restart it yourself; the warning clears on its own afterwards.

If you have restarted and the host still reports no role, the panel offers the install again under Already restarted, and still no role?. Running it again is safe: a host that already has the role answers that nothing needed changing.

Who may sign in through Remote Desktop New in 2.0

A Windows server that has just joined a domain lets only administrators sign in through Remote Desktop. Ordinary users are refused during the connection, before a session exists, and the browser can only report it as "Server refused connection".

So the role install, with Let the domain's users sign in ticked, also adds the host's own domain's Domain Users group to the host's Remote Desktop Users group. It finds both groups by their security identifier, so it works on Windows in any language. On a host where the role is already present, the same step is offered on its own under a folded section, Users other than administrators refused with "Server refused connection"?, with a Let domain users sign in button.

Only the host's own domain is added. People from another domain (for example, users of a trusted domain signing in to a host in a child domain) need their group added by hand, on the host:

net localgroup "Remote Desktop Users" "OTHERDOMAIN\Domain Users" /add

If the step fails, the host page shows the exact command to run instead.

Session settings on the host page

The host page also holds settings that decide how Windows sessions behave for the people using that host: whether the same person gets one session or one per device, and how long disconnected sessions are kept before Windows ends them. These are explained on their own page, Host session options.

Certificate sign-in New in 2.1

When Relay Pass is in use, the host page also carries a Certificate sign-in card with Check and Prepare this host, which check and apply the settings a host needs for passwordless Windows logon. The same card holds the Sign out disconnected sessions button described in Host session options.

Example: a small office with one new host

A company has bought one Windows Server 2022 machine, RDS01, joined to its CORP domain, and wants to publish its accounts package to twelve people.

1. Prepare the firewall. On RDS01 the administrator runs Enable-NetFirewallRule -Group '@FirewallAPI.dll,-33252' once.
2. Add the host. Name "Accounts server", address rds01.corp.example.com, domain CORP, management account CORP\svc-dartrelay (a member of the server's local Administrators group). Connect reports "Windows Server 2022 Standard" and no Session Host role.
3. Install the role. On the host page, with Let the domain's users sign in ticked and the restart box ticked, the administrator installs the role during a quiet hour. The host restarts, and the next time the Hosts list is opened it shows the host as ready.
4. Plan licensing. The licensing line shows the grace-period countdown, a reminder to configure an RDS licence server within 120 days.
5. Publish. The accounts package is then published as described in Publishing applications.

If something goes wrong

For more, including users being refused at sign-in, see Troubleshooting.

Related pages