Skip to content
SHC Docs

shc connection connect

authenticate a backend and store its credentials

Connect a backend (DNS, proxy, ca-signer, restic) and store its credentials in vault. --type selects the capability implementation (cloudflare, pfsense, bind, powerdns-local, …) and defaults to .

DNS: --zone declares a zone this connection manages (repeatable). It is required for local/LAN-only DNS types (pfsense, bind, powerdns-local, netbird), whose zones cannot be auto-discovered. A public connection owns the zones named, each confirmed against the provider. A zone the provider can’t see refuses the connect, and nothing is stored. With no --zone a cloudflare connection owns every zone its token lists, read again every 15 minutes, and any other public provider owns none. A bare --zone ! makes the named zones the whole declared set, or clears it when no zones are named.

pfSense (REST API v2): install pfSense-pkg-RESTAPI on the box before connecting. --endpoint supplies the pfSense base URL. A 404 from /api/v2 means the package is missing; a 401 means the API key was rejected. SHC does not mint or invent a pfSense API key: paste the one the box already issued.

NetBird: --cred api_url=URL is the management API base URL, and the token field, a NetBird Personal Access Token, is a secret read the way the Credentials paragraph below says. SHC writes the records of the NetBird zones named with --zone, which must already exist in NetBird, and publishes the private ingress address there: dns.lan_address when set, else the private underlay address of the node the system traefik runs on. A netbird connection requires --purpose private, and public is refused.

--purpose declares whether those zones are public (delegated at a registrar, answering the internet) or private (answering only clients on a LAN or VPN plane). A host gets a record in every matching zone, so a public and a private connection covering the same name publish both, the public address and the private one. Private connections also auto-create a zone on demand; public ones never do, because a public zone is only authoritative once a registrar delegates it. --purpose public|private is required whenever zones are named. Stored connections without a purpose keep their inferred value; doctor names the command to declare it.

Credentials: --cred takes a field inline (key=value) only when it is a coordinate connection show displays (s3_endpoint, region, username, bucket, …). Supply the backend endpoint with --endpoint. Every other field is a secret and is refused inline, because ps and shell history keep the command line. A secret comes from the file --value-file names, the flag shc vault set takes: with --cred key=- the file holds that one field’s value; alone, the file holds a JSON object of fields, for the b2 example access_key and secret_key. Without --value-file the same two forms read stdin, key=- at a terminal prompting with echo off, and --value-file - is stdin. One file or stdin per call, and each field comes from one entry. A coordinate is taken as written, including a value that begins with @.

--location binds a proxy connection’s load balancer to one location path as shc node ls prints it, at any level, or a name that ends one path: it fronts only the Traefiks of the nodes at or under that path, and an app’s hostnames point at the edge of the location it runs in. A name that means no node’s path is refused. Without it the edge is cluster-wide.

Incus has no load balancer. The location path its cluster sits under, the prefix of its nodes’ --location, is a credential: --cred location=.

Uniform grammar: inline dns.providers.* config (the same provider/providers. shape vault uses) is the file-config path; connection connect is the connection-backed overlay the factory consults first, falling through to the inline config when no connection owns the provider.

shc connection connect <name> [flags]
shc connection connect b2 --type s3 --cred s3_endpoint=s3.us-west-004.backblazeb2.com \
--cred region=us-west-004 --value-file b2.json
shc connection connect cloudflare --cred token=- --value-file ~/cloudflare.token
printf '%s' "$TOKEN" | shc connection connect cloudflare --cred token=-
--cred stringArray credential field (repeatable): key=value for a coordinate, key=- for one secret, - for a JSON object of fields
--endpoint string backend endpoint (if applicable)
-h, --help help for connect
--location string location path a proxy connection's edge fronts, as shc node ls prints it; incus uses --cred location=<path>; default is cluster-wide
--purpose string DNS zone purpose: public (delegated at a registrar) | private (LAN/VPN resolver only); required when zones are named
--scope string write tier: tenant (default) | system (master/global, admin)
-t, --tenant string owning tenant (defaults to the active tenant)
--type string capability type / impl (cloudflare, pfsense, bind, powerdns-local, …); defaults to <name>
--value-file string read the secret from this file ("-" for stdin)
--zone strings DNS zone this connection manages (repeatable, comma-separated); ! makes named zones the whole set, alone clears; <zone>! is refused
--config stringArray extra YAML config file to layer on top of auto-discovered config; repeatable, later files win
-d, --debug enable debug mode (default: $SHC_DEBUG)
-e, --environment string environment name (default: "prod", or "default" on an estate with no licence and no trial; $SHC_ENVIRONMENT and shc ctx -e override it, and the "master" tenant is always "default")
--exclude string comma-separated dotted paths to drop
--fields string comma-separated columns/keys to show (and their order)
--filter string comma-separated dotted paths to keep (drops everything else)
-o, --output string output format: tty|text|json|yaml (default: $SHC_OUTPUT)
-s, --stack string stack name (default: $SHC_STACK)
-v, --verbose verbose output (default: $SHC_VERBOSE)