CLI symbols
Seven symbols carry the grammar inside a flag’s value, and each means one thing
wherever it appears, except /, which has two meanings told apart by where it
sits. A flag prefers a richer value over a second flag, so learn
these once and every value reads the same way.
| symbol | read it as | meaning | example |
|---|---|---|---|
= | is | the thing on the left is set to the right | web=3 |
: | its | a part inside the thing on its left | web:8080 is web’s port 8080, db:location=nbg1 is db’s own rule, pgdata=ceph:50Gi is 50Gi of ceph |
@ | at | which one or where: a version, an environment, a connection, a place | nextcloud@30, 2@hel |
/ | under | a path below, after a name: in a hostname, after @, in a repo/app name | app.example.com/api, 2@eu/hel, bitspur/frappe |
/ | per | after a bare count in --scale: that many in each fence of the kind | 2/location, 1/node |
+ | with | an option switched on | 53+udp |
! | not | at the end it removes | blog.example.com! |
, | and | another item | 2@eu,1@us |
A flag that sets something per service has one shape:
<service>[:<port>]=<value>[+<option>][@<where>]The service comes first for per-service settings. Exposure starts with the
outside address and puts the service after =.
Values are opaque
Section titled “Values are opaque”A symbol inside a literal value belongs to the value. The dots in a hostname are
the hostname’s. What follows @ in a version is a version and nothing else, so
nextcloud@30+2 pins packaged revision 2 of version 30 and the + there is not
an option. A URL keeps its own @, : and /.
Apps: <repo>/<app>
Section titled “Apps: <repo>/<app>”<repo>/<app>[@<version>]An app reads like an image reference: the repo it comes from, a slash, the
app, and @ the version. -r/--repo is the long form of the repo half.
shc repoint photos apps/immichThe slash keeps its other meaning first. When the app before it publishes
the name after it as an add-on or a vApp, shc install nextcloud/deck is
that add-on, and when a deployment of that name exists, shc update nc/[email protected] is that vApp instance. Otherwise the first half is a repo the
install must be able to see. A repo in the token and a different -r/--repo
are refused with X400076REPTWO; the same repo stated twice is accepted.
Places
Section titled “Places”@<name> names a place. A location path is a place, and so is every prefix of
it: hel, eu/hel, hetzner/eu/hel. A name that is no location is refused,
and the refusal lists the locations.
Exposure: --expose
Section titled “Exposure: --expose”How a deployment is reached once the flag is accepted, the ledger, the listen rules and the refusals are Published ports.
--expose <outside>[+<option>...][@<where>][=<service>[:<container port>]]Repeatable; comma lists are accepted. <outside> is a port number, or a
hostname with an optional path (hostname[:port][/path]). A hostname with an
outside port is an L4 listener that also gets a DNS record. A path on that
form (db.example.com:5432/x) is refused with X400495EXPPTH: a port has
no path.
A value that is only digits is a port, so 8080 is L4 port 8080 and must be
from 1 to 65535. A hostname must contain a letter or a dot: wiki and
8080.example.com are hostnames, and a hostname that is only digits cannot be
added or removed through --expose.
Options and placement belong to the outside part, before =, as in
36094+udp@(node=home01)=echo:9999. The first = outside parentheses
separates the target. An = inside @(...) belongs to the node selector.
No outside port means HTTP(S) through Traefik. The target on the right says
which service or service selector answers, and may name its container port.
Leave it out to use the app default: the service marked x-shc-primary, else
the first service in file order, with its default port. An explicit target
must resolve to one ingress candidate. A service selector over labels other
than group has no ports of its own, so its target names one,
app.example.com=web:8080. A target that is neither a service nor a service
selector of the app is refused with X400498EXPTGT, which lists both.
shc install wiki --expose wiki.example.comshc install wiki --expose wiki.example.com=webshc install wiki --expose wiki.example.com/docs=web:8080shc update wiki --expose metrics.example.com=:9000shc update wiki --expose wiki.example.com/a+bshc update wiki --expose wiki.example.com/@aliceAn outside port is an L4 listener. The same flag publishes it; +udp is UDP,
and @<connection> sends it through that connection’s load balancer.
A fully omitted target uses the app default service and port. A named service
without a container port uses the outside port as its container port;
8080=:80 selects the one service that declares container port 80.
A service selector takes the same place as a service: 5432=postgres, with
postgres: role=primary:1, reaches whichever replica is primary now and
follows a failover with no update. Some service of the app must declare its
container port, and the cluster must run service VIPs (X400499EXPVIP).
A port the node itself owns is refused with X400992PRTOWN: sshd’s 22 and
any port its config adds, shcd’s 4001-4003 and 8000, the WireGuard ports
4243 and 4244 over UDP, 53 where shcd answers DNS, and the edge’s 80 and 443.
shc install postgres --expose 5432shc install postgres --expose 5432=dbshc install gitea --expose 8022=gitea:22shc install syslog --expose 514+udp=syslog:514shc install postgres --expose 5432@hz-lb=dbshc install postgres --expose 5432+spreadshc install mailcow --expose '25+local=postfix-mailcow:25'shc install wazuh --expose 514+udp+private=wazuh-manager:514shc install postgres --expose '5432@(edge=true)'shc install postgres --expose 5432@eu/hel+spread sends a connection to any ready replica. A publish without +spread
prefers a replica on the node that accepted the connection. +local answers only
on nodes that hold a ready replica and never forwards, so the app sees the
client’s address; it cannot be combined with +spread. +private takes the port
on each node’s private address only, never a public one. @(edge=true) listens on the nodes whose labels match
that node selector. @eu/hel is a location path and listens on the nodes in that
location. A name with no slash, @hel1, is a location when a node is in that
location and no connection has the name. It is that connection’s load balancer
when the name is a connection. A name that is both is refused with
X409137PUBAMB. An L4 publish that names no @ follows the publish.listen
node selector, and every node when that key is unset.
Two deployments cannot listen on one port and protocol on one node. Install,
update, and a label edit that would cause that are refused with
X409136PUBOVR, which names the deployment that already listens and the
nodes. On a cluster whose fabric mode is shc and whose fabric range does
not overlap the service VIP range, a published port is an SHC listen rule on
each listening node, a connection publish included. The rendered compose has
no ports: entry for it, so the port does not answer on 127.0.0.1 from the
node itself. A connection publish whose owner is a proxy connection, or whose
owner is not recorded, matches the node’s private address.
An app’s own ports: entries publish nothing there: the render declares
their container ports, and the install warns with X200141PUBTPL naming the
--expose that would publish each one.
A hostname with an outside port (db.example.com:5432=db) is that listener
plus a DNS record from the tenant’s DNS connection, the same managed-DNS
plane an HTTP host uses. No hostname means no record. @<connection> points
the record at that connection’s load-balancer endpoints. A plain publish
points it at the nodes that listen: exposure=internet uses each listening
node’s public address, drops a private or loopback address, and defers with
X200980DNSDEF when none is left. Any other exposure uses dns.lan_address,
then dns.public_address, then each listening node’s underlay address. An L4
host never follows the system Traefik. An L4 hostname another deployment
already serves, as a route host or an L4 host, is refused with
X409142PUBHST. A removal names the outside port, protocol and connection;
db.example.com:5432! and 5432! remove the same mapping.
On shc update a trailing ! removes one entry by its outside part. A
removal never names a node selector. Protocol is part of a port entry’s identity:
514! and 514+tcp! remove only TCP, and 514+udp! removes only UDP.
shc update wiki --expose old.example.com!shc update wiki --expose 'old.example.com!,wiki.example.com/docs!'shc update postgres --expose 5432!shc update syslog --expose 514+tcp!shc update syslog --expose 514+udp!A bare ! removes every expose entry the same command does not name. The
entries beside it are then the whole set, in the order given, and the first
HTTP route is the canonical origin. Alone, it leaves the deployment with no
exposure.
shc update wiki --expose '!' --expose wiki.example.com --expose docs.example.com=web:8080shc update wiki --expose '!'Replicas: --scale
Section titled “Replicas: --scale”--scale <name>=<n>--scale <name>=<n>@<place>[,<n>@<place>...]--scale <service>=<n>/<kind>A count, exact counts per place, or a count per value of a kind. 2/location
is two replicas in every location, on different nodes where the location has
them, and a location added later gets its two without a new value. 1/node is
one on every node. The / here is per, so it comes straight after the count;
a path keeps its / after @. The name is a service, or a group a
{% members %} block stamps. A group takes a count or counts per place.
shc install wiki --scale web=3shc update wiki --scale db=2@home,1@farshc update wiki --scale db=2@hetzner/eu/hel,1@usshc update wiki --scale proxy=1/nodeshc install postgres --scale postgres=2/locationPlacement: --where and --prefer
Section titled “Placement: --where and --prefer”--where <node selector>--where <service>:<node selector>--where <service>!--where '!'Repeatable, and --prefer takes the same forms. A bare node selector is the
deployment-wide rule. <service>:<node selector> is that service’s own rule, and
the service is a service or a group, as in --scale. A trailing ! drops
that service’s own rule, so it falls back to the deployment-wide one. A bare
! drops every rule of the flag.
shc update wiki --where location=hel1 --where db:location=nbg1shc update wiki --prefer web:tier=edgeshc update wiki --where 'db!'Zones: --zone
Section titled “Zones: --zone”--zone <zone>[!]--zone '!'Repeatable; comma lists are accepted. A name adds the zone. A trailing !
removes it. A bare ! alone leaves the connection with no zones. The zones
named beside a bare ! are the whole set.
shc connection zones cloudflare -t corp --zone example.orgPort forward
Section titled “Port forward”[<service>][:<port>][=<local port>]<service>:<port> is the service’s port. =<local port> sets the local port.
An all-digit value is a remote port. Leave the local port out and one is chosen.
shc forward postgres web:5432=15432Retired spellings
Section titled “Retired spellings”No old spelling is read. Each is refused with a code that prints the value as it is written now.
| typed | refused with | write |
|---|---|---|
--host wiki.example.com | X400226FLGOLD | --expose wiki.example.com |
--hosts-exact | X400226FLGOLD | --expose '!' beside every route and port to keep |
--route web:8080=wiki.example.com | X400226FLGOLD | --expose wiki.example.com=web:8080 |
--port 53/udp! | X400226FLGOLD | --expose 53+udp! |
--scale db=home:2,far:1 | X400225SCLOLD | --scale db=2@home,1@far |
--scale proxy=per:location | X400225SCLOLD | --scale proxy=1/location |
--scale pg=2+per@location | X400225SCLOLD | --scale pg=2/location |
--add example.org | X400551ZNEOLD | --zone example.org |
--remove x | X400551ZNEOLD | --zone x! |
--set a,b | X400551ZNEOLD | --zone '!' --zone a,b |
15432:5432 | X400911FWDOLD | 5432=15432 |
15432:web | X400911FWDOLD | web=15432 |
15432:web:5432 | X400911FWDOLD | web:5432=15432 |
--rename blog:blog2 | X400449RCVOLD | --rename blog=blog2 |
--from-backup blog.bak:blog2 | X400449RCVOLD | --from-backup blog.bak=blog2 |
--override host=old.example:new.example | X400449RCVOLD | --override host:old.example=new.example |
--rename a:b | X400649CLNOLD | --rename a=b |
cluster fabric explain acme/prod/webapp 10.84.1.130 | X400384FBROLD | webapp -t acme -e prod |
adapter migrate lw --adapter runtipi --version 1 --from acme/linkwarden@prod | X400968ADPOLD | --stack linkwarden -t acme -e prod |
A deployment that stored a scale in a retired spelling is refused the same way
when the value is read. One shc update --scale in the new spelling replaces
it. Stored routes are not text and need nothing.
The same symbols elsewhere
Section titled “The same symbols elsewhere”| flag | grammar |
|---|---|
shc install <app>[/<add-on>][@<version>] | / under, @ at |
shc install, shc update, shc repoint: <repo>/<app>[@<version>] | / under: the app under that repo, as -r <repo>; @ at |
-i, --integrate | [<plug>=]<provider>[@<environment>], <plug>=@<connection>; <plug>! on update |
-C, --connection | <name>=<connection> |
--var, -c, --config-set | <key>=<value>; <key>! on update |
--cpu-quota, --memory-quota | <service>=<value> |
shc recover --rename | <old>=<new> |
shc recover --from-backup | <backup>[=<target>] |
shc recover --override | [<stack>:]host:<old>=<new> or [<stack>:]hosts=<new> |
shc clone --rename | <old>=<new>[,<old>=<new>...] |
shc cluster fabric explain <from> <to> | a fabric address, or <stack>[:<service>]; -t/-e name the tenant and environment, --target-tenant/--target-environment place <to> |
shc adapter migrate --stack | an SHC stack, in the tenant and environment from -t/-e; --from stays <path> or ssh://[user@]host |