Endpoints and certificates

An endpoint is an address and port DartRelay listens on — for example "every network address, port 443, HTTPS". This page explains how to manage endpoints, how to give an HTTPS endpoint a certificate (uploaded, already on the server, or issued by Let's Encrypt), and what happens when you change them.

What the Endpoints page controls

Go to System → Endpoints. The table lists every endpoint DartRelay listens on, one row each:

On a new installation the page already shows the endpoint the installer set up — typically HTTP on every address, port 8080 — so you can see exactly what the server is doing before you change anything.

Bind addresses

Host names cannot be used in the bind box. Which name people type in their browser is decided by DNS, not by the endpoint.

Adding or editing an endpoint

1. Open the Endpoints page. Go to System → Endpoints.
2. Click Add endpoint, or the edit button on an existing row. Adding and editing happen on a page of their own.
3. Enter a name, the bind address and the port.
4. Choose the scheme. For Http, the certificate section is hidden because an HTTP endpoint has no certificate. For Https, the certificate section appears.
5. For HTTPS, fill in the Certificate box. Choose a certificate from the list under the box, click Upload… to add one, or type a value. See The Certificate box.
6. Make sure Enabled is ticked, then save.

If what you entered cannot work, the page refuses the save, explains why, and keeps everything you typed. It refuses:

• a host name in the bind box, or a port outside 1–65535;
• an HTTPS endpoint with no certificate;
• an endpoint that overlaps another enabled endpoint on the same address and port;
• more than 16 enabled endpoints.

It warns but still saves when the address is not currently held by this server, or the certificate is not in the store yet, because both may be true later.

How changes are applied

A server can only start listening on a new address or port when its web service starts. So when you save, add or delete an endpoint in a way that changes what the server listens on, DartRelay applies it by restarting its own service a few seconds later. The editor page stays open and tells you this is happening. You do not need to do anything else.

Changes that do not affect listening — renaming an endpoint, or changing the order — are saved without any interruption, and the page says so.

If DartRelay is not running as a Windows service (for example, someone started it from a command prompt), it cannot apply the change itself and the page explains that.

Safety nets

• A row that cannot be used is skipped, not fatal. If a port is already taken by another program, or an address no longer exists, DartRelay skips that endpoint, writes a warning to the log, and carries on with the others.
• Never left with nothing. If every endpoint is unusable, DartRelay listens on the address the installer configured, as it did before the page was ever used.
• One change, one restart. If an endpoint cannot be bound, DartRelay does not keep restarting in the hope that it will. The page tells you which row is the problem.

"Not described by the rows below"

When the endpoints in the table do not match what the server is actually listening on, the page shows what it is listening on now. This can happen after an upgrade from an old version, or when the table was changed on another server in a pool. Where the difference is simply out-of-date rows, DartRelay corrects the table itself when it starts. Otherwise the panel explains the situation, and an Adopt button replaces the rows with the endpoints the server is really using.

If an endpoint change makes the console unreachable

You can tell DartRelay to ignore the Endpoints page and listen on the address the installer configured. Add this to the server configuration file, dartrelay.config.json, alongside what is already there:

{
  "DartRelay": {
    "Endpoints": {
      "FromDatabase": false
    }
  }
}

The Endpoints page shows a banner while this is set. Correct the endpoints, then remove the setting. See Server configuration file. The recovery instructions are also on the Endpoints page, under a collapsed section.

Certificates for HTTPS

An HTTPS endpoint needs a certificate whose name matches the address people browse to, such as portal.example.com, and whose private key is available to DartRelay. You have three ways to provide one:

All three are managed on the Certificates page: on System → Endpoints, click Certificates. It has an upload card, a list of every certificate this server can already use, and the Let's Encrypt card.

The Certificate box

An HTTPS endpoint's Certificate box accepts one of three values:

• A thumbprint — a certificate in the server's certificate store. You can paste one straight from the Windows certificate console.
• A file path — a .pfx file with no password, on the server's disk.
• letsencrypt — the certificate DartRelay obtains and renews from Let's Encrypt.

Under the box, a drop-down lists letsencrypt and every certificate the server can already use, each with its name and expiry date. Choosing one fills in the box for you. Expired certificates are listed and marked EXPIRED.

Uploading a certificate

You can upload from the endpoint editor (Upload… under the Certificate box) or from the Certificates page. Both do the same thing.

1. Choose the certificate file. A .pfx or .p12 file, or a PEM certificate file (.pem, .crt).
2. For PEM, choose the key file too — unless the key is in the same file as the certificate, as it often is with files prepared for other web servers.
3. Type the password, if the file or key has one.
4. Upload. In the endpoint editor the Certificate box is filled in for you, and the certificate joins the drop-down for other endpoints. On the Certificates page, copy the value shown into the endpoint's Certificate box.

What happens to the certificate:

• On Windows it is imported into the server's Local Machine certificate store, and the endpoint refers to it by thumbprint.
• On Linux it is saved without a password in the certificates folder inside DartRelay's data directory, readable only by DartRelay, and the endpoint refers to it by path. On Linux the key is therefore protected by file permissions rather than by an operating-system key store; the page says so.
• The password is used once to open the file and is never stored.

The upload is refused, with a reason, if the file has no private key (a .cer or certificate-only PEM file), if the password is wrong (the page tells a wrong password apart from a damaged file), or if the certificate cannot be written to the store. An expired certificate is accepted on purpose: you get a working endpoint and a browser warning, not a refusal.

Uploading does not change any endpoint by itself; you choose where to use the certificate. Certificates cannot be deleted from the Certificates page.

Let's Encrypt

Let's Encrypt is a free certificate authority trusted by all browsers. DartRelay can request a certificate for your portal's public name, renew it automatically before it expires, and start using each renewal without any interruption to the portal.

Before you begin

• The portal must be reachable from the internet by its public name, for example portal.example.com. Public DNS for that name must point at this server (or at the firewall that forwards to it).
• Let's Encrypt checks the name by connecting to it on port 80, over plain HTTP. You need an enabled Http endpoint on port 80, and port 80 open to the internet.
• The server must be able to reach Let's Encrypt over the internet.
• Wildcard certificates (*.example.com) are not available this way.

Getting the certificate

1. Add the port 80 endpoint. On System → Endpoints, add an Http endpoint on port 80, bound to 0.0.0.0, enabled.
2. Open the Let's Encrypt card. Click Certificates and find the Let's Encrypt section.
3. Tick Use the staging environment for your first attempt. Staging lets you get everything right without using up Let's Encrypt's limit of failed attempts. Its certificates are not trusted by browsers, so you will switch it off afterwards.
4. Enter the public name, a contact email address, and accept Let's Encrypt's agreement. Save.
5. Check the page's readiness checks. It confirms the port 80 endpoint itself. It cannot check public DNS from inside your network, so test from a computer outside it: curl http://portal.example.com/.well-known/acme-challenge/test should return "not found" from this server.
6. Click Request a certificate now. The request runs in the background and usually takes well under a minute. Refresh the page to see the result.
7. When staging succeeds, untick Use the staging environment, save, and click Request a certificate now again for the real certificate.
8. Use it. Add or edit an Https endpoint (port 443, for example) and choose letsencrypt as its certificate. Saving applies the endpoint as described in How changes are applied. From then on, renewals need nothing from you.

Renewal

• DartRelay checks the certificate twice a day and renews it from 30 days before it expires — roughly every 60 days.
• A renewed certificate is used for new connections as soon as it arrives. Open sessions are not interrupted, and nothing restarts.
• Port 80 must be reachable at every renewal, not just the first time. If port 80 is closed when renewal is due, every twice-daily attempt fails until the certificate expires. It may be closed between renewals, but the simplest and safest choice is to leave it open.
• After a failed attempt, automatic retries wait at least 30 minutes, so a problem does not use up Let's Encrypt's limit on failed checks. Clicking Request a certificate now ignores that wait.

The status panel

The top of the Let's Encrypt card shows the current certificate, the names it covers and when it expires. When a request fails, it shows Let's Encrypt's own error message word for word — for example a refused connection on port 80 — because that is the most useful clue to what went wrong.

If the certificate in use came from the staging environment, the panel turns red and says "Not trusted by browsers", whatever the expiry date. Untick staging and either click Request a certificate now or wait for the next twice-daily check, which replaces a staging certificate automatically.

Example: publishing the portal on the internet

A firm wants staff to reach the portal at https://apps.example.com. The administrator creates a public DNS record for apps.example.com pointing at the office's public address, and forwards ports 80 and 443 on the firewall to the DartRelay server. On System → Endpoints they add an Http endpoint on 0.0.0.0 port 80, request a staging certificate, then a real one, and finally add an Https endpoint on 0.0.0.0 port 443 with letsencrypt as its certificate, outside working hours. The certificate renews itself every couple of months from then on.

If something goes wrong

Let's Encrypt says the connection was refused or timed out

Port 80 is not reaching this server from the internet. Check the port 80 endpoint is enabled, the firewall forwards port 80, and public DNS points at the right address. Test with the curl command above from outside your network.

Browsers warn that the certificate is not trusted

If the status panel is red with "Not trusted by browsers", the certificate came from the staging environment: untick staging and request again. For an uploaded certificate, check that its name matches the address people use and that it was issued by a trusted authority.

Some older devices reject the certificate while modern browsers accept it

Windows sends the issuing certificate chain from its own certificate stores. DartRelay tries to add Let's Encrypt's intermediate certificate there; if that was not possible, most browsers fetch it themselves but some older or locked-down clients do not. Check the server's Intermediate Certification Authorities store.

An endpoint was skipped

Another program is probably using the port, or the address is no longer on the server. The log names the row and the reason; the Endpoints page shows what the server is actually listening on.

The upload says the password is wrong

The page distinguishes a wrong password from a damaged file. If it names the password, re-check it with whoever issued the file. If the file has no password at all, leave the box empty.

The console cannot be reached after an endpoint change

Use the recovery setting in If an endpoint change makes the console unreachable.

Related pages