shc connection connect
shc connection connect
Section titled “shc connection connect”authenticate a backend and store its credentials
Synopsis
Section titled “Synopsis”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.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]Examples
Section titled “Examples” 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=-Options
Section titled “Options” --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 refusedOptions inherited from parent commands
Section titled “Options inherited from parent commands” --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)SEE ALSO
Section titled “SEE ALSO”- shc connection - manage backend connections and their providers