Skip to content
SHC Docs

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.

far01
$ 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.73

Run 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.

home01
$ shc node ls
NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTER
far01 healthy ready active learn learn/far ok 0.1.0 no no
home01 healthy ready active learn learn/home ok 0.1.0 yes yes

The 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.

far01
$ nft list chain ip shc_vip published
table 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:

home01
$ shc update web --expose '18080!' --expose 18080@learn/far=nginx:80
updating deployment "web"
X200972RMVDON: --expose removal 18080/tcp matched this deployment and was applied to its persisted state
[web] Healthy 1/1
✔ nginx healthy
source: /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 deployment

The 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:

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:

home01
$ nft list chain ip shc_vip published
table 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:

home01
$ shc update web --scale nginx=2
updating deployment "web"
[web] Healthy 1/1
✔ nginx healthy
source: /root/learn/nginx, replayed from the deployment's persisted source (path)
the rollout of prod/web/prod to v1:sha256:0fb81e227e4e7a26e9b14676ac253b4620a120ae24ac4ddd500ced7c59d1f24a finished

The VIP now has two replicas behind it, listed in address order, so which of the two comes first is where the scheduler put them:

home01
$ shc cluster fabric vips --stack web
node node-58c0a3a3fbef revision 488 converged sha256:7b14bec5b9c439f6e8750cd8e8d4d8e4c4fbc9c28a5a506ebc66e802e6fbcba5
...
nginx-r1 10.128.65.6 node-77f4031d2159 ready
...
home01
$ shc update web --expose '18080!' --expose 18080+spread=nginx:80
updating deployment "web"
X200972RMVDON: --expose removal 18080/tcp matched this deployment and was applied to its persisted state
[web] Healthy 1/1
✔ nginx healthy
source: /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
home01
$ shc status -s web
last polled 2026-10-09 01:10:05 UTC
NODE STATE CPU% MEM% DISK% LOAD
far01 healthy 67.7 15.8 11.8 1.49
home01 healthy 34.5 20.6 8.2 1.28
all 224 queues green on 2 nodes
TENANT STACK ENVIRONMENT STATE SERVICES NODES LABELS NO HEALTHCHECK
prod web prod healthy 1/1 far01, home01 app=/root/learn/nginx environment=prod stack=web tenant=prod 1
TENANT STACK ENVIRONMENT REPLICA NODE STATE
prod web prod nginx-r0 home01 ready
prod web prod nginx-r1 far01 ready
Published ports
prod/prod/web nginx 18080/tcp listen=every node +spread nodes: far01 crossing, home01 crossing
runs on far01, home01
2 nodes, 1 deployment

Two 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:

home01
$ shc config set publish.listen location=learn/home
takes effect on the running estate: the next reconcile sweep picks it up, no reinstall or restart needed
a publish with no @ place listens on the nodes this selector matches; unset means every node; the next fabric render applies it
KEY VALUE SCOPE ACTIVATION
publish.listen location=learn/home global live
home01
$ shc status -s web
...
Published ports
prod/prod/web nginx 18080/tcp listen=location=learn/home +spread nodes: home01 crossing
runs on far01, home01
2 nodes, 1 deployment

The 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:

home01
$ shc config unset publish.listen
...
home01
$ shc status -s web
...
Published ports
prod/prod/web nginx 18080/tcp listen=every node +spread nodes: far01 crossing, home01 crossing
runs 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.

explained, not walked: this page keeps web's spread port
$ shc update web --expose '18080!' --expose 18080+local=nginx:80

web keeps two replicas and its spread port. Keep both deployments.

Next: A hostname and a certificate.