Internal Services with SSL
A common use case you might have is to host services and applications which are only reachable within your clan.
This guide explains how to set up such secure, clan-internal web services using a custom top-level domain (TLD) with SSL certificates.
Your services will be accessible only within your clan network and secured with proper SSL certificates that all clan machines trust.
Overview
By combining the coredns
and certificates
clan services, you can:
- Create a custom TLD for your clan (e.g.
.c
) - Host internal web services accessible via HTTPS (e.g.
https://api.c
,https://dashboard.c
) - Automatically provision and trust SSL certificates across all clan machines
- Keep internal services secure and isolated from the public internet
The setup uses two clan services working together:
- coredns service: Provides DNS resolution for your custom TLD within the clan
- certificates service: Creates a certificate authority (CA) and issues SSL certificates for your TLD
DNS Resolution Flow
- A clan machine tries to access
https://service.c
- The machine queries its local DNS resolver (unbound)
- For
.c
domains, the query is forwarded to your clan's CoreDNS server. All other domains will be resolved as usual. - CoreDNS returns the IP address of the machine hosting the service
- The machine connects directly to the service over HTTPS
- The SSL certificate is trusted because all machines trust your clan's CA
Step-by-Step Setup
The following setup assumes you have a VPN (e.g. Zerotier) already running. The IPs configured in the options below will probably the Zerotier-IPs of the respective machines.
Configure the CoreDNS Service
The CoreDNS service has two roles:
- server
: Runs the DNS server for your custom TLD
- default
: Makes machines use the DNS server for TLD resolution and allows exposing services
Add this to your inventory:
inventory = {
machines = {
dns-server = { }; # Machine that will run the DNS server
web-server = { }; # Machine that will host web services
client = { }; # Any other machines in your clan
};
instances = {
coredns = {
# Add the default role to all machines
roles.default.tags = [ "all" ];
# DNS server for the .c TLD
roles.server.machines.dns-server.settings = {
ip = "192.168.1.10"; # IP of your DNS server machine
tld = "c";
};
# Machine hosting services (example: ca.c and admin.c)
roles.default.machines.web-server.settings = {
ip = "192.168.1.20"; # IP of your web server
services = [ "ca" "admin" ];
};
};
};
};
Configure the Certificates Service
The certificates service also has two roles:
- ca
: Sets up the certificate authority on a server
- default
: Makes machines trust the CA and allows them to request certificates
Add this to your inventory:
inventory = {
instances = {
# ... coredns configuration from above ...
certificates = {
# Set up CA for .c domain
roles.ca.machines.dns-server.settings = {
tlds = [ "c" ];
acmeEmail = "admin@example.com"; # Optional: your email
};
# Add default role to all machines to trust the CA
roles.default.tags = [ "all" ];
};
};
};
Complete Example Configuration
Here's a complete working example:
nventory = {
machines = {
caserver = { }; # DNS server + CA + web services
webserver = { }; # Additional web services
client = { }; # Client machine
};
instances = {
coredns = {
# Add the default role to all machines
roles.default.tags = [ "all" ];
# DNS server for the .c TLD
roles.server.machines.caserver.settings = {
ip = "192.168.8.5";
tld = "c";
};
# machine hosting https://ca.c (our CA for SSL)
roles.default.machines.caserver.settings = {
ip = "192.168.8.5";
services = [ "ca" ];
};
# machine hosting https://blub.c (some internal web-service)
roles.default.machines.webserver.settings = {
ip = "192.168.8.6";
services = [ "blub" ];
};
};
# Provide https for the .c top-level domain
certificates = {
roles.ca.machines.caserver.settings = {
tlds = [ "c" ];
acmeEmail = "admin@example.com";
};
roles.default.tags = [ "all" ];
};
};
};
Testing Your Configuration
DNS resolution can be tested with:
You should also now be able to visit https://ca.c
to access the certificate authority or visit https://blub.c
to access your web service.
Troubleshooting
DNS Resolution Issues
-
Check if DNS server is running:
-
Verify DNS configuration:
-
Test DNS directly:
Certificate Issues
-
Check CA status:
-
Verify certificate trust:
-
Check ACME configuration: