Documentation › Administration
HTTPS certificate (Let's Encrypt)
Out of the box, Steward IT Census uses a certificate it creates itself, so browsers show a warning. Configuration › HTTPS certificate gets you a free, trusted certificate from Let's Encrypt for a name in a domain you own, for example census.example.com. It is renewed automatically.
You do not need a Let's Encrypt account or password, an open port, a public A record, or a server reachable from the internet. You need:
- a domain you own (for example
example.com), and - the API key or token of its DNS provider (the company that hosts the domain's public DNS: Cloudflare, your registrar…), or one of the methods for any DNS host.
Census creates the Let's Encrypt account by itself (a key stored in the acme data folder). No email address is needed: Let's Encrypt no longer sends expiry reminders, and Census renews by itself and shows any failure on the page.
How it works#
Let's Encrypt has to be sure you control the domain. Census uses the DNS challenge:
- Census asks Let's Encrypt for a certificate for
census.example.com. - Let's Encrypt answers with a random token. Census uses your DNS provider's API to publish it as a temporary TXT record
_acme-challenge.census.example.com. - Let's Encrypt looks the record up on the internet, issues the certificate, and Census deletes the record.
That TXT record is the only proof of ownership Let's Encrypt asks for: no A record pointing at Census is needed for it. No port is opened and nothing connects to your server: the server only makes outgoing HTTPS requests to Let's Encrypt and to your DNS provider. The temporary TXT record contains only the random token, never an address of your network.
The certificate lasts 90 days. Census checks twice a day and renews it 30 days before it expires.
Step 1: choose a name#
Pick a name under your domain for the console, such as census.example.com or inventory.it.example.com. It doesn't have to exist yet.
Step 2: make the name lead to the server on your network#
This step is not for Let's Encrypt: it's for your browsers. A certificate only matches when the console is opened by its name, so https://census.example.com:8443 has to reach the Census server from your computers. The name points to the server's internal address, not your public IP (your public IP is your firewall, which doesn't forward to Census and shouldn't).
The name already works? If your internal DNS (for example an Active Directory DNS zone for example.com) already resolves the name to the server, there's nothing to do: choose The name already works on our network. Otherwise add a local DNS entry (the page shows it with your server's address filled in):
Local DNS entry#
Add a host record on your firewall, router or internal DNS server: census.example.com → <server IP>. Your network's addresses stay out of public DNS; only computers that use your firewall or DNS server can resolve the name.
Where to add it on common systems:
| System | Where |
|---|---|
| Windows DNS Server | DNS Manager › Forward Lookup Zones. If you don't have a zone for your domain, create a zone named exactly census.example.com (so the rest of your domain keeps resolving publicly) and add a blank-name A record (same as parent folder) with the server's IP. |
| pfSense | Services › DNS Resolver › Host Overrides › Add: Host census, Domain example.com, IP address. |
| OPNsense | Services › Unbound DNS › Overrides › Hosts › +: Host census, Domain example.com, IP. |
| FortiGate | Network › DNS Servers › DNS Database: create a zone for census.example.com (or your domain, as shadow / recursive) with an A record; the interface's DNS service must be enabled and handed out by DHCP. |
| Sophos Firewall | Network › DNS › DNS host entry › Add: census.example.com, IP. |
| UniFi | Settings › Routing › DNS (or Policy Table › DNS Record): A record census.example.com → IP. |
| Pi-hole | Local DNS › DNS Records: census.example.com → IP. |
| One PC (testing) | Add 192.168.1.10 census.example.com to C:\Windows\System32\drivers\etc\hosts (as administrator) or /etc/hosts. |
Computers must use that firewall or DNS server for DNS (normally through DHCP). Over VPN, the VPN must hand out the same DNS server.
Check it#
Click Check name on the page: it shows what the name resolves to from the server and whether that is the server. From a PC, run nslookup census.example.com.
Step 3: create the DNS provider API token#
The token lets Census create and delete the temporary TXT record. Give it the smallest permission that allows editing DNS records of your domain.
| Provider | Where | Notes |
|---|---|---|
| Cloudflare | My Profile › API Tokens › Create Token › template Edit zone DNS, zone = your domain | Use an API token, not the global API key. |
| DigitalOcean | API › Tokens › Generate New Token, scope Write (or custom: domain read/write) | |
| Porkbun | Account › API Access › Create API key; then enable API access on the domain (Domain Management › Details) | Both the API key and the secret key are needed. |
| Namecheap | Profile › Tools › API Access: enable, note the API key, and whitelist your public IP address | Namecheap requires an account with enough domains/balance for API access; the API user is your username. |
| GoDaddy | developer.godaddy.com › API Keys (Production) | GoDaddy only allows its DNS API for accounts with 10+ domains or certain plans. |
| Amazon Route 53 | IAM › user with route53:ChangeResourceRecordSets, route53:ListHostedZonesByName, route53:GetChange |
Optionally enter the hosted zone ID. |
| Hetzner | DNS Console (or Hetzner Console › Security) › API tokens | |
| Gandi | Account › Authentication options › Personal Access Token, permission Manage domain technical configurations | |
| OVHcloud | Create an application at https://eu.api.ovh.com/createToken/ (or your region) with GET/POST/DELETE on /domain/zone/* |
Endpoint: ovh-eu, ovh-ca or ovh-us. |
| Linode / Akamai | Profile › API Tokens, Domains: Read/Write | |
| IONOS | developer.hosting.ionos.com › API keys; enter as prefix.secret |
|
| NameSilo, Dynu, deSEC, Duck DNS | API key / token from the account page | Duck DNS only works for names under duckdns.org. |
Also supported (the page lists each with its fields and notes): Akamai Edge DNS, All-Inkl, ANS SafeDNS (UKFast), AutoDNS, Azure DNS, Bunny.net, ClouDNS, Constellix, cPanel / WHM, DirectAdmin, DNSExit, DNS Made Easy, DNSimple, Domeneshop, DreamHost, easyDNS, Google Cloud DNS, Hosting.de, Hosting.nl, Hostinger, Hurricane Electric, Infoblox, Infomaniak, INWX, ISPConfig, Joker, Leaseweb, Loopia, LuaDNS, mijn.host, Mythic Beasts, Name.com, NearlyFreeSpeech.NET, netcup, Netlify, NS1, Plesk, PowerDNS, Rackspace, Scaleway, Selectel, Simply.com, Spaceship, Technitium, TransIP, UltraDNS, Vercel, Vultr, Websupport, WEDOS, ZoneEdit, Zonomi.
- Azure DNS: an app registration (Entra ID › App registrations) with a client secret and the role DNS Zone Contributor on the zone; enter the tenant, client ID, secret, subscription and resource group. The Entra ID sync's app registration can be reused.
- Google Cloud DNS: a service account with the role DNS Administrator; paste its JSON key.
Any DNS host#
If your provider isn't listed, or you'd rather not store a token that can edit your whole zone:
| Method | How |
|---|---|
| acme-dns (CNAME delegation) | Enter an acme-dns server (your own, or a public one such as https://auth.acme-dns.io). The first request registers there and stops with a message naming a CNAME record to create once at your DNS host: _acme-challenge.census.example.com → <id>.auth.acme-dns.io. Create it, request again, and renewals run by themselves. Census only holds the acme-dns account, which can change nothing but that one TXT record. |
| DNS update (RFC 2136) | For your own BIND, PowerDNS, Knot… server: the primary server's address and a TSIG key allowed to update _acme-challenge records. (Windows DNS Server only accepts secure updates with Kerberos from domain members: use acme-dns or a script.) |
| HTTP request | Census POSTs {"fqdn":"_acme-challenge.census.example.com.","value":"…"} to <your URL>/present and /cleanup; your web service changes the record. |
| Script on this server | Put a program in the acme\hooks folder of the Census data folder (e.g. C:\ProgramData\StewardCensus\acme\hooks\dns.cmd) and choose it. Census runs it with present <record name> <value>, then cleanup <record name> <value>; exit code 0 = done. Only scripts in that folder can be chosen, so only someone with access to the server can add one. On Windows, a .cmd can call PowerShell: powershell -NoProfile -File "%~dp0dns.ps1" %*. |
Manual DNS (typing the TXT record yourself) isn't offered: it would have to be repeated at every renewal, every 60 days.
Many registrars also let you move only the DNS hosting of a domain to Cloudflare (free) while keeping the domain where it is.
Enter it under Assets › Certificate renewal, step 1 (Connect your DNS provider). That one setting serves both the console's certificate and your servers' certificates. Test DNS provider there creates a temporary TXT record for a name you enter, waits until public DNS shows it and deletes it, so you know the token and zone work before asking Let's Encrypt.
Tokens are stored encrypted on the server (like credentials) and never shown again; leave the field blank when editing to keep the saved one.
Step 4: request the certificate#
On Configuration › HTTPS certificate:
- Tick Use a Let's Encrypt certificate.
- Enter the name (step 1).
- The DNS provider (step 3) shows here; change it under Assets › Certificate renewal.
- Choose how computers find the server (step 2).
- Optional: tick Test with the Let's Encrypt staging service first. Staging certificates aren't trusted by browsers, but a mistake doesn't count against Let's Encrypt's limits (5 failed attempts per hour, 5 certificates per name per week). Untick it and request again once it works.
- Save, then Request certificate now. It usually takes under a minute, sometimes a few minutes while DNS updates. The status shows the result or the error.
Then open https://census.example.com:8443: no warning.
Step 5: point agents and installers at the new name (optional)#
Agents keep working without any change (see below). To make new agent installs, the USB installer and deployments use the new name, click Use https://census.example.com:8443 as the Server URL on the page (or set it in General settings).
Agents and the certificate#
The server keeps its own certificate as well and decides per connection:
- connections to the name (
census.example.com) get the Let's Encrypt certificate; - everything else, such as agents installed with the server's IP address, gets the original certificate, so their certificate pin keeps matching.
Agents from version 0.16 also accept a publicly trusted certificate for the name they connect to. If agents older than 0.16 connect by this name, update them first (Scanning › Census agents › Update all): the page warns when older agents exist.
Troubleshooting#
| Message | Fix |
|---|---|
… is missing |
Enter the provider's token or keys and save. |
acme-dns: … you must provision the following CNAME … |
Expected the first time: create that CNAME record at your DNS host, wait a few minutes, request again. |
propagation: time limit exceeded |
The TXT record wasn't visible on the internet in time. Check that the token can edit this domain, that the domain's DNS is really hosted at that provider (the domain's nameservers), then request again. |
403 / unauthorized / invalid token from the provider |
Wrong token, missing permission, or (Namecheap) your public IP isn't whitelisted. |
rateLimited |
Too many attempts: wait an hour (failed validations) or use the staging option while testing. |
| Browser still warns | You opened the console by IP address or another name; use https://<the name>:8443. Also check the name resolves to the server (Check name). |
| Name doesn't resolve on some PCs | They don't use the firewall/DNS server with the host record (check their DNS settings, VPN), or a public record is blocked by DNS rebinding protection. |
To go back to the built-in certificate, untick Use a Let's Encrypt certificate and save.
The DNS provider set here is also used to renew your servers' certificates: see Certificate renewal.