Who answers a port
Which node answers a published port, and where it sends the connection,
only shows on a cluster with more than one node and more than one place.
home01 is one node in location home, so this page adds far01 in location
far first. Prepare a second Debian 13 machine the way home01 was prepared,
with 2 CPUs, 8 GB of memory and SHC installed, named far01. It must reach
home01, and root on it must be able to ssh home01 with a key and no prompt:
the join reads its token from home01 that way.
The join asks home01 for a fresh token over ssh and hands it to
shc node join -, which reads it from standard input. It also names the
node, its cloud and its location.
$ ssh home01 shc node token --fields token -o text | shc node join - --name far01 --cloud learn --location far✔ joined cluster as node "far01" at 65.21.55.73Run this again if far01 is still vault-locked or not ready. Within a minute of this first join home01’s daemon restarts once, as SHC promotes its database from one file into a replicated one; type a command again if it fails in that moment.
$ shc node lsNAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTERfar01 healthy ready active learn learn/far ok 0.1.0 no nohome01 healthy ready active learn learn/home ok 0.1.0 yes yesThe deployments stay on home01: a node joining moves nothing. web is
published on 18080 and every node answers it, far01 too. The listener on a
Linux node is an nftables rule in the shc_vip table, one per published
port, sending the connection to a replica’s address on the fabric. Read
the chain on far01. The system Traefik takes a few minutes to start on a
node that just joined; read the chain again until its rules for 80 and 443
are there.
$ nft list chain ip shc_vip publishedtable ip shc_vip { chain published { tcp dport 80 counter packets 0 bytes 0 ct mark set ct mark | 0x10000000 dnat to 10.128.64.131:80 comment "master/default/traefik/traefik 80/tcp local" tcp dport 443 counter packets 0 bytes 0 ct mark set ct mark | 0x10000000 dnat to 10.128.64.131:443 comment "master/default/traefik/traefik 443/tcp local"... }}The rules for 80 and 443 belong to the system Traefik, which runs on
every node, so they are marked local everywhere. The rule for 18080
names web’s replica on the fabric and ends with the tier the node sends
to; on this cluster it read tcp dport 18080 counter packets 0 bytes 0 ct mark set ct mark | 0x10000000 dnat to 10.128.17.4:80 comment "prod/prod/web/nginx 18080/tcp any", far01 forwarding across the fabric
to a replica on home01.
The @ part of --expose chooses which nodes listen. @learn/far is a
location path; @(edge=true) is a label selector. On shc update, a
trailing ! removes an entry by its outside part, so this replaces the
port’s listeners:
$ shc update web --expose '18080!' --expose 18080@learn/far=nginx:80updating deployment "web"X200972RMVDON: --expose removal 18080/tcp matched this deployment and was applied to its persisted state[web] Healthy 1/1✔ nginx healthysource: /root/learn/nginx, replayed from the deployment's persisted source (path)web: no change: nothing was updated; the re-render read the same app package, apppkg-v1:7753cc3b9cfd1d7365d699a8c416e585449bbbf8dde5839cc4c7e2ad9d264a08 from /root/learn/nginx, and produced the compose the deployment already had$ shc status -s web...Published ports...runs on home01; can move to far01
2 nodes, 1 deploymentThe published line now reads listen=location=learn/far and names one
node. Only far01 listens, and it still forwards across the fabric when
the replica is elsewhere. The port answers on far01:
$ curl -s http://localhost:18080/<!doctype html><title>hello</title><p>Hello from SHC.</p>On home01 the 18080 rule is gone from the chain. The two system rules
stay, and hello’s 18081 from the last page is there too:
$ nft list chain ip shc_vip publishedtable ip shc_vip { chain published { tcp dport 80 counter packets 0 bytes 0 ct mark set ct mark | 0x10000000 dnat to 10.128.16.136:80 comment "master/default/traefik/traefik 80/tcp local" tcp dport 443 counter packets 0 bytes 0 ct mark set ct mark | 0x10000000 dnat to 10.128.16.136:443 comment "master/default/traefik/traefik 443/tcp local"... }}A listening node sends a connection to a replica of its own first, then
one under the deepest location level it shares with a ready replica, then
any. +spread sends it to any ready replica
instead, chosen at random. Give web a second replica, then publish the
port everywhere again with +spread:
$ shc update web --scale nginx=2updating deployment "web"[web] Healthy 1/1✔ nginx healthysource: /root/learn/nginx, replayed from the deployment's persisted source (path)the rollout of prod/web/prod to v1:sha256:0fb81e227e4e7a26e9b14676ac253b4620a120ae24ac4ddd500ced7c59d1f24a finishedThe VIP now has two replicas behind it, listed in address order, so which of the two comes first is where the scheduler put them:
$ shc cluster fabric vips --stack webnode node-58c0a3a3fbef revision 488 converged sha256:7b14bec5b9c439f6e8750cd8e8d4d8e4c4fbc9c28a5a506ebc66e802e6fbcba5... nginx-r1 10.128.65.6 node-77f4031d2159 ready...$ shc update web --expose '18080!' --expose 18080+spread=nginx:80updating deployment "web"X200972RMVDON: --expose removal 18080/tcp matched this deployment and was applied to its persisted state[web] Healthy 1/1✔ nginx healthysource: /root/learn/nginx, replayed from the deployment's persisted source (path)web: no change: nothing was updated; the re-render read the same app package, apppkg-v1:7753cc3b9cfd1d7365d699a8c416e585449bbbf8dde5839cc4c7e2ad9d264a08 from /root/learn/nginx, and produced the compose the deployment already had$ shc status -s weblast polled 2026-10-09 01:10:05 UTCNODE STATE CPU% MEM% DISK% LOADfar01 healthy 67.7 15.8 11.8 1.49home01 healthy 34.5 20.6 8.2 1.28
all 224 queues green on 2 nodes
TENANT STACK ENVIRONMENT STATE SERVICES NODES LABELS NO HEALTHCHECKprod web prod healthy 1/1 far01, home01 app=/root/learn/nginx environment=prod stack=web tenant=prod 1
TENANT STACK ENVIRONMENT REPLICA NODE STATEprod web prod nginx-r0 home01 readyprod web prod nginx-r1 far01 ready
Published portsprod/prod/web nginx 18080/tcp listen=every node +spread nodes: far01 crossing, home01 crossingruns on far01, home01
2 nodes, 1 deploymentTwo replicas, and the published line carries +spread with both nodes. every node is what a port with no @ falls back to. The config
key publish.listen changes that fallback for every such port, and the
line then reads the key’s own selector. Set it to the home location and
read web again, whose spread port names no place:
$ shc config set publish.listen location=learn/hometakes effect on the running estate: the next reconcile sweep picks it up, no reinstall or restart neededa publish with no @ place listens on the nodes this selector matches; unset means every node; the next fabric render applies itKEY VALUE SCOPE ACTIVATIONpublish.listen location=learn/home global live$ shc status -s web...Published portsprod/prod/web nginx 18080/tcp listen=location=learn/home +spread nodes: home01 crossingruns on far01, home01
2 nodes, 1 deploymentThe line reads listen=location=learn/home with home01 alone: far01 no
longer listens for 18080. hello’s port names no place either and reads
the same selector. A port that names its own @ keeps it. Put the
fallback back:
$ shc config unset publish.listen...$ shc status -s web...Published portsprod/prod/web nginx 18080/tcp listen=every node +spread nodes: far01 crossing, home01 crossingruns on far01, home01
2 nodes, 1 deployment+local works the other way round. A node listens on the port only while a
ready replica runs on it, and never forwards, so the app sees the client’s
own address. Without it, a connection sent across to a replica on another
node wears the listening node’s fabric address. A mail server’s spam checks
and a STUN server publish this way. +local and +spread on one port are
refused.
$ shc update web --expose '18080!' --expose 18080+local=nginx:80web keeps two replicas and its spread port. Keep both deployments.
Next: A hostname and a certificate.