Merge pull request 'Add internal services guide' (#5254) from internal-service-doc into main
Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/5254
This commit is contained in:
pinpox
@@ -1,5 +1,5 @@
|
||||
# Serve documentation locally
|
||||
|
||||
```
|
||||
$ nix develop .#docs -c mkdocs serve
|
||||
nix develop .#docs -c mkdocs serve
|
||||
```
|
||||
|
||||
@@ -66,6 +66,7 @@ nav:
|
||||
- Services:
|
||||
- Introduction to Services: guides/services/introduction-to-services.md
|
||||
- Author Your Own Service: guides/services/community.md
|
||||
- Internal Services with SSL: guides/internal-ssl-services.md
|
||||
- Vars:
|
||||
- Introduction to Vars: guides/vars/vars-overview.md
|
||||
- Minimal Example: guides/vars/vars-backend.md
|
||||
|
||||
213
docs/site/guides/internal-ssl-services.md
Normal file
213
docs/site/guides/internal-ssl-services.md
Normal file
@@ -0,0 +1,213 @@
|
||||
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
|
||||
|
||||
1. A clan machine tries to access `https://service.c`
|
||||
2. The machine queries its local DNS resolver (unbound)
|
||||
3. For `.c` domains, the query is forwarded to your clan's CoreDNS server. All
|
||||
other domains will be resolved as usual.
|
||||
4. CoreDNS returns the IP address of the machine hosting the service
|
||||
5. The machine connects directly to the service over HTTPS
|
||||
6. 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:
|
||||
|
||||
```nix
|
||||
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:
|
||||
|
||||
```nix
|
||||
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:
|
||||
|
||||
```nix
|
||||
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:
|
||||
|
||||
```bash
|
||||
# On any clan machine, test DNS resolution
|
||||
nslookup ca.c
|
||||
nslookup blub.c
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
1. **Check if DNS server is running**:
|
||||
```bash
|
||||
# On the DNS server machine
|
||||
systemctl status coredns
|
||||
```
|
||||
|
||||
2. **Verify DNS configuration**:
|
||||
```bash
|
||||
# Check if the right nameservers are configured
|
||||
cat /etc/resolv.conf
|
||||
systemctl status systemd-resolved
|
||||
```
|
||||
|
||||
3. **Test DNS directly**:
|
||||
```bash
|
||||
# Query the DNS server directly
|
||||
dig @192.168.8.5 ca.c
|
||||
```
|
||||
|
||||
### Certificate Issues
|
||||
|
||||
1. **Check CA status**:
|
||||
```bash
|
||||
# On the CA machine
|
||||
systemctl status step-ca
|
||||
systemctl status nginx
|
||||
```
|
||||
|
||||
2. **Verify certificate trust**:
|
||||
```bash
|
||||
# Test certificate trust
|
||||
curl -v https://ca.c
|
||||
openssl s_client -connect ca.c:443 -verify_return_error
|
||||
```
|
||||
|
||||
3. **Check ACME configuration**:
|
||||
```bash
|
||||
# View ACME certificates
|
||||
ls /var/lib/acme/
|
||||
journalctl -u acme-ca.c.service
|
||||
```
|
||||
Reference in New Issue
Block a user