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:
$ shc install ~/learn/nginx -s site --expose site.learn.testinstalling deployment "site"[site] Healthy 1/1✔ nginx healthy✔ installed deployment "site"exposure: lan$ shc ingress lsFILE ROUTER HOST UPSTREAM GATE TARGETacme-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 dooringress-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:
$ shc ingress cat ingress-prod_prod_site.yamlhttp:... 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:
$ 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/$ 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/$ curl -sk -o /dev/null -w '%{http_code}\n' --resolve site.learn.test:443:127.0.0.1 https://site.learn.test/200The 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.
$ openssl s_client -connect 127.0.0.1:443 -servername site.learn.testConnecting to 127.0.0.1depth=1 O=shc, CN=shc-prod-ca-intermediateverify error:num=20:unable to get local issuer certificateverify return:1depth=0 O=shc, CN=site.learn.testverify return:1CONNECTED(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.testissuer=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:
$ shc cert lsNAME KIND FINGERPRINT EXPIRYcluster root 071ad59f52510fb0a17b50cff1d9705f33b5d98e2b73e5080bbfbbafa35780ff -global-root root c2b092640a1b1a1c5252c2f0dfadabba65814f47b2a7a8640027e2e85250df30 -prod intermediate 586421d8dcf7da322d9496b2b6c9621b8c7a761533eaf4631aacfc11e5af5323 2031-10-09T18:44:47Z$ shc ca show --tenant prodTENANT PROVENANCE INTERMEDIATE KEY EXPIRYprod autogen ca/tenants/prod/intermediate-key.55587fc395e37d25d7b4c77fd95f6a8fbd3a3e7b9c90c3f887da86c58ce226c9 2031-10-09T18:44:47Zautogen 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:
$ 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 --yesshc 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.
$ shc cert edgeno acme-issued hostnames in tenant "prod"$ shc cert deliveryno 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.
$ shc cert ls --cert...$ shc cert ls --nodesNAME KIND FINGERPRINT EXPIRYcluster root 071ad59f52510fb0a17b50cff1d9705f33b5d98e2b73e5080bbfbbafa35780ff -global-root root c2b092640a1b1a1c5252c2f0dfadabba65814f47b2a7a8640027e2e85250df30 -prod intermediate 586421d8dcf7da322d9496b2b6c9621b8c7a761533eaf4631aacfc11e5af5323 2031-10-09T18:44:47Z
NODE LEAF FINGERPRINT EXPIRYfar01 abfc3725cd47b04363617e7d799c9e6ca755be02164009f93669d3a067ab6d1f 2026-10-17T18:39:11Zhome01 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:
$ shc ingress$ shc cluster cert$ shc cluster hostshc 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:
$ 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 --yesExposure
Section titled “Exposure”A route is LAN-only unless you say otherwise. --public opens it to the
internet; --private on shc update takes that back.
$ shc update site --publicupdating deployment "site"[site] Healthy 1/1✔ nginx healthysource: /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 --privateupdating deployment "site"[site] Healthy 1/1✔ nginx healthysource: /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 linethe rollout of prod/site/prod to v1:sha256:81ca6cd8a3f96095747787534db25b1e473100e5a6d9ec937933841717f3c0c8 finishedA 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:
$ 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:
$ shc install ~/learn/nginx -s www --expose www.example.com --public --acme-provider letsencrypt$ shc update www --acme-provider letsencryptsite.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.
The API’s rate limits
Section titled “The API’s rate limits”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:
$ shc config set rate_limit.requests 1500shc: [X400050CFGSTP] config key rate_limit.requests can only be set in yaml config files$ 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 60They 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:
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$ 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.