Skip to content
SHC Docs

A hostname and a certificate

A port reaches a deployment at a number. A hostname reaches it through the system Traefik, the traefik deployment in tenant master that every node runs. --expose <hostname> with no port is an HTTP route: Traefik matches the name and forwards to the service’s VIP. Install the nginx app a third time, as site, routed at site.learn.test:

home01
$ shc install ~/learn/nginx -s site --expose site.learn.test
installing deployment "site"
[site] Healthy 1/1
✔ nginx healthy
✔ installed deployment "site"
exposure: lan
$ shc ingress ls
FILE ROUTER HOST UPSTREAM GATE TARGET
acme-challenge.yaml acme-http-01 - http://shc:8000 - -
ingress-prod_prod_site.yaml prod_prod_site site.learn.test http://10.224.0.23:80 shc-lan-page-prod_prod_site,shc-lan-prod_prod_site,shc-reserved-prod_prod_site front door
ingress-prod_prod_site.yaml prod_prod_site_cloudv1 site.learn.test http://shc:8000 shc-lan-page-prod_prod_site,shc-lan-prod_prod_site,shc-cookiestrip-prod_prod_site -

shc ingress ls lists every router Traefik has. The upstream of prod_prod_site is site’s VIP, so the route follows the replica wherever it runs. TARGET reads front door because the hostname was exposed with no service named: the route goes to the app’s front door, and an update that moves the front door moves the route. A hostname exposed as <hostname>=<service>:<port> reads pinned and stays where it was put. The GATE column is the middlewares in front of it: shc-lan is the LAN allowlist, since the route’s exposure is lan, the default, and only addresses on the cluster’s own networks are let through; shc-lan-page ahead of it answers a browser the allowlist turned away with a page saying the private network is why, still a 403, and leaves the app’s own answers alone; shc-reserved keeps the /.shc/launcher/ paths, which are SHC’s own, from reaching the app. No login gate stands in front of the route: --gated adds one, and the access ladder covers it. The router under it answers one path of the hostname, /.well-known/cloud/v1, from the daemon instead of the app. shc ingress cat prints the file Traefik reads:

home01
$ shc ingress cat ingress-prod_prod_site.yaml
http:
...
rule: Host(`site.learn.test`)
...

Nothing resolves site.learn.test yet. Point curl at a node and send the name. Traefik listens on 80 and 443 on every node that holds a replica of it, which is both here. Plain HTTP is answered with a redirect to HTTPS, and HTTPS with 200, since the node’s own address is on the LAN allowlist:

home01
$ curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' --resolve site.learn.test:80:127.0.0.1 http://site.learn.test/
301 https://site.learn.test/
far01
$ curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' --resolve site.learn.test:80:127.0.0.1 http://site.learn.test/
301 https://site.learn.test/
home01
$ curl -sk -o /dev/null -w '%{http_code}\n' --resolve site.learn.test:443:127.0.0.1 https://site.learn.test/
200

The route works: the name was matched, TLS was ended and nginx answered. Each tenant has a certificate authority of its own, an intermediate under the cluster’s global root, and SHC signs a leaf for every routed hostname with it. -k told curl to accept a certificate it cannot verify, since the root is not in the node’s trust store. Read the chain Traefik serves for the name. openssl s_client keeps the connection open for input, so press Ctrl-D once the chain is printed.

home01
$ openssl s_client -connect 127.0.0.1:443 -servername site.learn.test
Connecting to 127.0.0.1
depth=1 O=shc, CN=shc-prod-ca-intermediate
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 O=shc, CN=site.learn.test
verify return:1
CONNECTED(00000003)
---
Certificate chain
0 s:O=shc, CN=site.learn.test
i:O=shc, CN=shc-prod-ca-intermediate
a:PKEY: EC, (prime256v1); sigalg: ecdsa-with-SHA256
v:NotBefore: Oct 8 17:16:06 2026 GMT; NotAfter: Jan 6 17:16:06 2027 GMT
1 s:O=shc, CN=shc-prod-ca-intermediate
i:O=shc, CN=shc-global-ca
a:PKEY: EC, (prime256v1); sigalg: ecdsa-with-SHA256
v:NotBefore: Oct 8 17:16:06 2026 GMT; NotAfter: Oct 7 17:16:06 2031 GMT
---
Server certificate
...
subject=O=shc, CN=site.learn.test
issuer=O=shc, CN=shc-prod-ca-intermediate
...
Verify return code: 20 (unable to get local issuer certificate)
...

The leaf for site.learn.test was issued by the prod tenant’s intermediate, and that by the global root. The verification error is the node’s own trust store, which does not hold the root. The certificates SHC keeps, and the one for prod:

home01
$ shc cert ls
NAME KIND FINGERPRINT EXPIRY
cluster root 071ad59f52510fb0a17b50cff1d9705f33b5d98e2b73e5080bbfbbafa35780ff -
global-root root c2b092640a1b1a1c5252c2f0dfadabba65814f47b2a7a8640027e2e85250df30 -
prod intermediate 586421d8dcf7da322d9496b2b6c9621b8c7a761533eaf4631aacfc11e5af5323 2031-10-09T18:44:47Z
$ shc ca show --tenant prod
TENANT PROVENANCE INTERMEDIATE KEY EXPIRY
prod autogen ca/tenants/prod/intermediate-key.55587fc395e37d25d7b4c77fd95f6a8fbd3a3e7b9c90c3f887da86c58ce226c9 2031-10-09T18:44:47Z

autogen says SHC made this CA itself. shc ca import installs one you bring as PEM files, shc ca provision has a ca-signer connection make one, and shc ca reprovision swaps a tenant’s CA for one from either source:

explained, not walked: needs PEM files you bring or a ca-signer connection, and this cluster has neither
$ shc ca import --root ~/ca/root.pem --intermediate ~/ca/prod.pem --key ~/ca/prod-key.pem --tenant prod
$ shc ca provision --signer vault-pki --tenant prod
$ shc ca reprovision --signer vault-pki --tenant prod --yes
$ shc ca reprovision --root ~/ca/root.pem --intermediate ~/ca/prod.pem --key ~/ca/prod-key.pem --tenant prod --yes

shc cert edge reads what the edge serves for ACME-issued names, and this cluster has none. shc cert delivery reads the certificate material SHC keeps on a node for a deployment that ends TLS itself. SHC delivers a hostname’s material only to a deployment that binds it, on the node that runs it. site binds none, so there is nothing to list; the last page of this ladder installs an app that does.

home01
$ shc cert edge
no acme-issued hostnames in tenant "prod"
$ shc cert delivery
no certificate deliveries in tenant "prod"

The nodes have certificates of their own too. shc cert ls --cert adds each certificate’s body, --nodes adds the leaf each node presents, and shc cluster cert ls reads the cluster CA and the mTLS certificates the nodes present to each other. A node renews its own leaf off the cluster CA when it nears expiry; shc cluster cert rotate-now makes it check now. The system apps answer on the ingress host shc cluster host show prints, the name shc init was given or the node’s own.

home01
$ shc cert ls --cert
...
$ shc cert ls --nodes
NAME KIND FINGERPRINT EXPIRY
cluster root 071ad59f52510fb0a17b50cff1d9705f33b5d98e2b73e5080bbfbbafa35780ff -
global-root root c2b092640a1b1a1c5252c2f0dfadabba65814f47b2a7a8640027e2e85250df30 -
prod intermediate 586421d8dcf7da322d9496b2b6c9621b8c7a761533eaf4631aacfc11e5af5323 2031-10-09T18:44:47Z
NODE LEAF FINGERPRINT EXPIRY
far01 abfc3725cd47b04363617e7d799c9e6ca755be02164009f93669d3a067ab6d1f 2026-10-17T18:39:11Z
home01 bf42a58068e231a1277af9a99f0eb3c31c88b89a9a2d45a2e4a46d181f05cc82 2026-10-17T18:25:12Z
$ shc cluster cert ls
...
$ shc cluster cert rotate-now
...
$ shc cluster host show
...

Typed with no subcommand, shc ingress lists the routers as shc ingress ls does, shc cluster cert lists the certificates as shc cluster cert ls does, and shc cluster host prints the host as shc cluster host show does:

explained, not walked: each prints what the step it shortens printed above
$ shc ingress
$ shc cluster cert
$ shc cluster host

shc cluster cert rotate re-keys the cluster CA, the global root or every node’s mTLS leaf, in phases so the cluster keeps running, and shc cluster host set moves the system apps to a new domain, which ends every SSO session. Both are maintenance, not a step of this ladder:

explained, not walked: a rotation re-keys every node and a host change ends every session, maintenance this ladder does not run
$ shc cluster cert rotate --type mtls --yes
$ shc cluster cert rotate --type cluster-ca --algo p256 --yes
$ shc cluster cert rotate --type cluster-ca --rollback --force --yes
$ shc cluster host set cluster.learn.test --grace 1h --yes

A route is LAN-only unless you say otherwise. --public opens it to the internet; --private on shc update takes that back.

home01
$ shc update site --public
updating deployment "site"
[site] Healthy 1/1
✔ nginx healthy
source: /root/learn/nginx, replayed from the deployment's persisted source (path)
the rollout of prod/site/prod to v1:sha256:72925d4032f79ea64f0404d6aa578fd94d0c705f09b31fbb0109934eec845c87 finished
$ shc update site --private
updating deployment "site"
[site] Healthy 1/1
✔ nginx healthy
source: /root/learn/nginx, replayed from the deployment's persisted source (path)
site: changed: exposure internet -> lan stored on the deployment. The app package and the compose bytes are UNCHANGED; anything this changes in what a replica runs is on the rollout's own line
the rollout of prod/site/prod to v1:sha256:81ca6cd8a3f96095747787534db25b1e473100e5a6d9ec937933841717f3c0c8 finished

A browser trusts a certificate from a public CA, not from the tenant’s own. SHC asks Let’s Encrypt or another ACME CA for one when the route has a public name. Name the ACME account and provider once. acme.wildcards lists base domains that get one wildcard certificate each instead of one per host:

explained, not walked: www.example.com is not a name this rig owns, so no ACME CA issues for it
$ shc config set acme.email [email protected]
$ shc config set acme.providers.letsencrypt.directory https://acme-v02.api.letsencrypt.org/directory
$ shc config set acme.default letsencrypt
$ shc config set acme.wildcards '[example.com]'

Then a public deployment gets a certificate through DNS-01 when a DNS connection of its tenant owns the hostname’s zone, and through an HTTP-01 challenge otherwise, which needs port 80 reachable from the internet. --acme-provider names the provider for one deployment, and --public on shc install opens the route to the internet from the start:

explained, not walked: the same name, which no ACME CA issues for
$ shc install ~/learn/nginx -s www --expose www.example.com --public --acme-provider letsencrypt
$ shc update www --acme-provider letsencrypt

site.learn.test is not a name the internet resolves, so no ACME CA can issue for it, and this page does not run those commands. The tenant’s own chain is what a private cluster serves.

Behind Traefik sits the daemon’s own API as well, on every node, and the routers above whose upstream is http://shc:8000 are routes to it. It limits each remote address per window, in classes: a default class for every route, one for the forward-auth gate, one for the login routes and one for the status endpoint. ip_ceiling_multiplier caps one address at that many times a single budget however many hostnames it sends. These keys are not set through shc config set, which refuses them:

home01
$ shc config set rate_limit.requests 1500
shc: [X400050CFGSTP] config key rate_limit.requests can only be set in yaml config files
explained, not walked: every rate_limit key is refused the same way, X400050CFGSTP, so the file below sets them
$ shc config set rate_limit.window 30
$ shc config set rate_limit.ip_ceiling_multiplier 8
$ shc config set rate_limit.forward_auth.requests 3000
$ shc config set rate_limit.forward_auth.window 10
$ shc config set rate_limit.auth.requests 3000
$ shc config set rate_limit.auth.window 10
$ shc config set rate_limit.status.requests 600
$ shc config set rate_limit.status.window 60

They live in the daemon’s yaml files, /etc/shc/config.yaml and /etc/shc/config.d/*.yaml, and the daemon reloads the whole block when a file changes:

/etc/shc/config.d/rate-limit.yaml
rate_limit:
requests: 1500
window: 30
ip_ceiling_multiplier: 8
forward_auth:
requests: 3000
window: 10
auth:
requests: 3000
window: 10
status:
requests: 600
window: 60
home01
$ shc config get rate_limit.requests
...
$ shc config ls --prefix rate_limit.
...

Those are the defaults, written down so the estate carries them. Keep site installed.

Next: A zone SHC writes.