DNS and TLS

The console has one address, THESEUS_HOST, used by browsers and by endpoints. Choose it before you install: endpoints enrolled against one address keep using it.

Choose the address

Option	Certificate	Choose it when
A DNS name, for example soc.example.com, publicly resolvable, with ports 80 and 443 reachable from the internet	Let's Encrypt (acme)	Production with internet-facing access. Browsers trust it with no setup.
A DNS name that is internal, or not reachable from the internet	The stack's own CA (internal)	Private networks, VPN-only access
The server's IP address	The stack's own CA (internal)	Trials, labs, air-gapped sites

Let's Encrypt needs a DNS name; with an IP address the install always uses the stack's own CA.

During the install

On a self-hosted install the install command asks:

1. Domain for the console. The default is the server's IPv4 address on its default route. Type a DNS name to use one.
2. Use a Let's Encrypt certificate? Asked only for a DNS name. The default is yes.
3. E-mail for Let's Encrypt. Asked only when you answered yes.

To answer without prompts (for automation), set environment variables on the command:

curl -fsSL --proto '=https' https://<control>/i/<token> \
  | sudo THESEUS_DOMAIN=soc.example.com THESEUS_TLS=acme THESEUS_ACME_EMAIL=ops@example.com bash

THESEUS_TLS is internal or acme. acme needs a domain name (not an IP) and an e-mail address. Use the exact command we sent you; the line above only shows where the variables go.

Create the DNS record

At the end of the install, the command prints the record to create, for example:

  DNS         create an A record:  soc.example.com  ->  203.0.113.10

The address shown is the one on the server's default route. Behind NAT or a cloud firewall, use the public IP that forwards to the server instead.

For two servers, the console name points to the application server. Endpoints also need a name or address for the core server's port 1514; see Install on two servers.

Let's Encrypt (acme)

• The certificate is requested automatically once the DNS name points to the server and ports 80 and 443 are reachable from the internet. Until then the console shows a temporary certificate.
• Renewal is automatic.
• If no certificate arrives, see Let's Encrypt does not issue.

The stack's own CA (internal)

The install creates a certificate authority for this stack only, in runtime/pki/ of the stack directory, and issues the console's certificate from it.

• Endpoints trust it automatically. The install commands pin the certificate's key (Linux, macOS) or thumbprint (Windows) on the first download, and the installers carry the CA from then on.
• Browsers warn until you trust the CA on your computers. The CA certificate is /opt/theseus/runtime/pki/ca.pem on the server.

Trust the CA on your computers

Copy the CA certificate from the server:

scp root@<server>:/opt/theseus/runtime/pki/ca.pem theseus-ca.pem

Then add it to the trust store of the computers your analysts use:

System	How
Windows	certutil -addstore -f Root theseus-ca.pem in an elevated prompt, or deploy it with Group Policy (Computer Configuration, Public Key Policies, Trusted Root Certification Authorities)
macOS	sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain theseus-ca.pem
Ubuntu, Debian	sudo cp theseus-ca.pem /usr/local/share/ca-certificates/theseus-ca.crt && sudo update-ca-certificates
RHEL family	sudo cp theseus-ca.pem /etc/pki/ca-trust/source/anchors/ && sudo update-ca-trust
Firefox	Uses its own store unless enterprise roots are enabled: Settings, Privacy and Security, Certificates, View Certificates, Authorities, Import

The CA is specific to your stack; trusting it lets that CA vouch for any name, so distribute it only to your own computers.

Change later

Changing the console address or the TLS mode after endpoints are enrolled is not a simple setting change: endpoints keep the address and pin they enrolled with. Ask your provider before you change THESEUS_HOST or TLS_MODE. For a public certificate on a stack that uses the internal CA, ask your provider to switch the console to Let's Encrypt.