Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Ask for MSP first-run values before installing anything

[email protected]77a6e8b29bc1
diff --git a/deploy/provider-msp/setup.sh b/deploy/provider-msp/setup.sh
index d4b0c4a6a9..2c0eb25478 100755
--- a/deploy/provider-msp/setup.sh
+++ b/deploy/provider-msp/setup.sh
@@ -22,6 +22,11 @@ PULSE_PROVIDER_MSP_LICENSE_URL="${PULSE_PROVIDER_MSP_LICENSE_URL:-https://licens
PULSE_PROVIDER_MSP_SKIP_EVAL_LICENSE="${PULSE_PROVIDER_MSP_SKIP_EVAL_LICENSE:-0}"
PULSE_PROVIDER_MSP_EVAL_EMAIL="${PULSE_PROVIDER_MSP_EVAL_EMAIL:-}"
PULSE_PROVIDER_MSP_SIGNUP_SOURCE="${PULSE_PROVIDER_MSP_SIGNUP_SOURCE:-provider_msp_setup}"
+# The three values only a provider can supply. Seeded into a new .env; an
+# interactive run asks for any left blank before installing anything.
+PULSE_PROVIDER_MSP_DOMAIN="${PULSE_PROVIDER_MSP_DOMAIN:-}"
+PULSE_PROVIDER_MSP_ACME_EMAIL="${PULSE_PROVIDER_MSP_ACME_EMAIL:-}"
+PULSE_PROVIDER_MSP_CF_DNS_API_TOKEN="${PULSE_PROVIDER_MSP_CF_DNS_API_TOKEN:-}"
log() {
echo "[$(date -u +'%Y-%m-%dT%H:%M:%SZ')] $*"
@@ -508,6 +513,67 @@ falsy() {
esac
}
+# Values reach .env unquoted, so each is held to characters that compose and
+# set_env_value read literally: no whitespace, quotes, $, # or backslashes.
+valid_first_run_value() {
+ local key="$1" value="$2"
+ local label='[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?'
+ local domain_re="^(${label}\\.)+[A-Za-z]{2,63}$"
+ local email_re="^[A-Za-z0-9._%+-]+@(${label}\\.)+[A-Za-z]{2,63}$"
+ local token_re='^[A-Za-z0-9_.+/=-]{20,255}$'
+ case "${key}" in
+ DOMAIN) [[ "${value}" =~ ${domain_re} ]] ;;
+ ACME_EMAIL) [[ "${value}" =~ ${email_re} ]] ;;
+ CF_DNS_API_TOKEN) [[ "${value}" =~ ${token_re} ]] ;;
+ *) return 1 ;;
+ esac
+}
+
+# Runs before Docker is installed, so the long unattended part of setup never
+# stops halfway for a file edit. An existing .env is never prompted for.
+collect_first_run_values() {
+ [[ -f "${PULSE_PROVIDER_MSP_INSTALL_DIR}/.env" ]] && return 0
+
+ if [[ -t 0 ]]; then
+ cat <<'EOF'
+
+Pulse Provider MSP needs three values. Leave any blank to edit .env yourself
+when setup pauses (for example to use a DNS provider other than Cloudflare).
+
+EOF
+ if [[ -z "${PULSE_PROVIDER_MSP_DOMAIN}" ]]; then
+ read -r -p "Domain for the portal, e.g. pulse.example.com: " PULSE_PROVIDER_MSP_DOMAIN
+ fi
+ if [[ -z "${PULSE_PROVIDER_MSP_ACME_EMAIL}" ]]; then
+ read -r -p "Email for certificate notices: " PULSE_PROVIDER_MSP_ACME_EMAIL
+ fi
+ if [[ -z "${PULSE_PROVIDER_MSP_CF_DNS_API_TOKEN}" ]]; then
+ read -r -s -p "Cloudflare API token with Zone Read and DNS Edit (hidden): " PULSE_PROVIDER_MSP_CF_DNS_API_TOKEN
+ echo
+ fi
+ fi
+
+ local key var value
+ for key in DOMAIN ACME_EMAIL CF_DNS_API_TOKEN; do
+ var="PULSE_PROVIDER_MSP_${key}"
+ value="${!var}"
+ if [[ -n "${value}" ]] && ! valid_first_run_value "${key}" "${value}"; then
+ die "${key} is not valid; check it and run setup.sh again"
+ fi
+ done
+
+ if [[ -n "${PULSE_PROVIDER_MSP_DOMAIN}" ]]; then
+ cat <<EOF
+
+Before the certificate is issued, point two DNS records at this host's public
+IP (A records; on Cloudflare, proxy status DNS only):
+ ${PULSE_PROVIDER_MSP_DOMAIN} the portal
+ *.${PULSE_PROVIDER_MSP_DOMAIN} one address per client
+
+EOF
+ fi
+}
+
ensure_env_file() {
local env_path="${PULSE_PROVIDER_MSP_INSTALL_DIR}/.env"
if [[ -f "${env_path}" ]]; then
@@ -516,9 +582,23 @@ ensure_env_file() {
fi
log "no ${env_path}; creating from .env.example"
- cp -n "${PULSE_PROVIDER_MSP_INSTALL_DIR}/.env.example" "${env_path}"
+ (umask 077 && cp -n "${PULSE_PROVIDER_MSP_INSTALL_DIR}/.env.example" "${env_path}")
chmod 0600 "${env_path}"
+ local key var missing=0
+ for key in DOMAIN ACME_EMAIL CF_DNS_API_TOKEN; do
+ var="PULSE_PROVIDER_MSP_${key}"
+ if [[ -n "${!var}" ]]; then
+ set_env_value "${key}" "${!var}" "${env_path}"
+ else
+ missing=1
+ fi
+ done
+ if [[ "${missing}" -eq 0 ]]; then
+ log "wrote DOMAIN, ACME_EMAIL and CF_DNS_API_TOKEN to ${env_path}"
+ return 0
+ fi
+
cat <<EOF
Created ${env_path} from .env.example.
@@ -787,11 +867,13 @@ Paths:
Next step: create your operator account (prints your portal sign-in link):
cd ${PULSE_PROVIDER_MSP_INSTALL_DIR}
- docker compose run --rm control-plane provider-msp bootstrap \\
+ sudo docker compose run --rm control-plane provider-msp bootstrap \\
--account-name "Example MSP" --owner-email [email protected]
+Then open the link, choose Add client, and follow Install agents.
+
Prove the platform before the first real client:
- ./run-install-proof.sh --account-name "Example MSP" --owner-email [email protected]
+ sudo ./run-install-proof.sh --account-name "Example MSP" --owner-email [email protected]
Portal (after bootstrap):
https://${domain}/portal
@@ -803,7 +885,7 @@ cancellation.
Day 2: portal sessions last 7 days. Re-run the bootstrap command above any
time to print a fresh owner sign-in link, or use
- docker compose run --rm control-plane provider-msp portal-link --email [email protected]
+ sudo docker compose run --rm control-plane provider-msp portal-link --email [email protected]
for any invited teammate. Set RESEND_API_KEY in .env to enable emailed
sign-in links instead.
@@ -822,6 +904,7 @@ main() {
fi
log "starting provider MSP first-time setup"
+ collect_first_run_values
apt_install apt-transport-https
install_docker_ce
install_ops_tools
diff --git a/docs/MSP.md b/docs/MSP.md
index 61619befd1..3d7ce77d84 100644
--- a/docs/MSP.md
+++ b/docs/MSP.md
@@ -358,26 +358,26 @@ versioned provider archive, checksum, and SSH signature before changing the
version below.
Download the versioned asset, verify it with Pulse's pinned release key, and
-only then extract and run the guided setup:
+only then extract and run the guided setup. The commands are chained, so a
+failed download, signature or checksum stops before anything is extracted or
+run as root:
```bash
export PULSE_VERSION=v6.7.0
export PULSE_MSP_BUNDLE="pulse-provider-msp-${PULSE_VERSION}.tar.gz"
export PULSE_RELEASE_BASE="https://github.com/rcourtman/Pulse/releases/download/${PULSE_VERSION}"
-curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}"
-curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}.sha256"
-curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}.sshsig"
-
+curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}" &&
+curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}.sha256" &&
+curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}.sshsig" &&
ssh-keygen -Y verify \
-f <(printf '%s\n' 'pulse-installer namespaces="pulse-install" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMZd/DaH+BldzOkq1A8KVTcFk73nAyrE8aJOyf7i00jm pulse-installer') \
-I pulse-installer \
-n pulse-install \
- -s "${PULSE_MSP_BUNDLE}.sshsig" < "${PULSE_MSP_BUNDLE}"
-sha256sum -c "${PULSE_MSP_BUNDLE}.sha256"
-
-tar -xzf "${PULSE_MSP_BUNDLE}"
-cd "pulse-provider-msp-${PULSE_VERSION}"
+ -s "${PULSE_MSP_BUNDLE}.sshsig" < "${PULSE_MSP_BUNDLE}" &&
+sha256sum -c "${PULSE_MSP_BUNDLE}.sha256" &&
+tar -xzf "${PULSE_MSP_BUNDLE}" &&
+cd "pulse-provider-msp-${PULSE_VERSION}" &&
sudo -E bash ./setup.sh
```
@@ -386,12 +386,24 @@ The licence request omits an email address unless you export
address is included in the request.
The host needs Ubuntu 24.04 or similar, a domain you can point at it, and
-ports 80 and 443 free. Install `curl`, `openssh-client`, `coreutils`, and `tar`
-before the verification step. The wildcard certificate is issued over DNS-01
-with Cloudflare as the default provider (`CF_DNS_API_TOKEN`); any other
+ports 80 and 443 free; 2 vCPU, 4 GB RAM and 40 GB of disk is enough for an
+evaluation. Install `curl`, `openssh-client`, `coreutils`, and `tar` before the
+verification step. Point two DNS records at the host's public IP: the domain
+you choose for `DOMAIN` (the portal, at `https://DOMAIN/portal`) and
+`*.DOMAIN` (each client workspace, at `https://<client-id>.DOMAIN`). On
+Cloudflare, set both to DNS only. The wildcard certificate is issued over
+DNS-01 with Cloudflare as the default provider (`CF_DNS_API_TOKEN`, a token
+with Zone / Zone / Read and Zone / DNS / Edit on that zone); any other
Traefik dnsChallenge provider works by setting `ACME_DNS_PROVIDER` in `.env`
and putting that provider's credential variables in `dns-credentials.env`.
+When setup pauses for `DOMAIN`, `ACME_EMAIL` and `CF_DNS_API_TOKEN`, edit
+`/opt/pulse-provider-msp/.env` from a second session with `sudo`, because the
+file is readable by root only, then press Enter. It ends with
+`Pulse Provider MSP is running.` and the bootstrap command that prints your
+portal sign-in link; run that command with `sudo` as well. In the portal,
+**Add client** and then **Install agents** walk the first client to live data.
+
Leave `CP_PROVIDER_MSP_LICENSE_FILE` blank and `setup.sh` self-issues a
2-client evaluation licence. The bundle sends the public half of the
signing key generated on your host, a setup-stage marker, and a signup-source
diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md
index 8659a025de..112b482001 100644
--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md
+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md
@@ -4969,6 +4969,27 @@ which have working defaults or are generated. PR #2212 reports a v6.4.1
first-run 404 and a 200 after starting the platform; this assigned candidate
has not repeated that live-host proof.
+### Provider MSP setup asks for its three values before installing
+
+Through v6.7.0, `deploy/provider-msp/setup.sh` installed Docker and then
+stopped, asking the provider to edit a root-only `.env` from a second session
+and press Enter. It now asks for `DOMAIN`, `ACME_EMAIL` and the Cloudflare
+token first (the token without echo), or takes them from
+`PULSE_PROVIDER_MSP_DOMAIN`, `PULSE_PROVIDER_MSP_ACME_EMAIL` and
+`PULSE_PROVIDER_MSP_CF_DNS_API_TOKEN` for an unattended run, and seeds only a
+new `.env`, created with mode 0600. Each value is held to characters that
+compose and `set_env_value` read literally. A blank answer keeps the old
+edit-and-continue path for other DNS-01 providers. Setup names the two DNS
+records the certificate needs (`DOMAIN` and `*.DOMAIN`) and prints the
+bootstrap, portal-link and install-proof commands with `sudo`, because `.env`
+is readable by root only. `docs/MSP.md` chains the bundle download,
+signature, checksum, extraction and setup with `&&`, so a failed verification
+stops before anything runs as root.
+`TestProviderMSPSetupAsksForFirstRunValuesUpFront` and
+`TestProviderMSPEvaluationDocsUsePublishedSignedBundle` pin both. Checked on
+macOS bash 3.2 and bash 5 against a scratch install directory; not yet run on a
+fresh Ubuntu host.
+
### Provider MSP clients survive a support-container recreate
Recreating the control plane or Traefik detaches it from each client's
diff --git a/frontend-modern/public/docs/MSP.md b/frontend-modern/public/docs/MSP.md
index 61619befd1..3d7ce77d84 100644
--- a/frontend-modern/public/docs/MSP.md
+++ b/frontend-modern/public/docs/MSP.md
@@ -358,26 +358,26 @@ versioned provider archive, checksum, and SSH signature before changing the
version below.
Download the versioned asset, verify it with Pulse's pinned release key, and
-only then extract and run the guided setup:
+only then extract and run the guided setup. The commands are chained, so a
+failed download, signature or checksum stops before anything is extracted or
+run as root:
```bash
export PULSE_VERSION=v6.7.0
export PULSE_MSP_BUNDLE="pulse-provider-msp-${PULSE_VERSION}.tar.gz"
export PULSE_RELEASE_BASE="https://github.com/rcourtman/Pulse/releases/download/${PULSE_VERSION}"
-curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}"
-curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}.sha256"
-curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}.sshsig"
-
+curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}" &&
+curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}.sha256" &&
+curl -fsSLO "${PULSE_RELEASE_BASE}/${PULSE_MSP_BUNDLE}.sshsig" &&
ssh-keygen -Y verify \
-f <(printf '%s\n' 'pulse-installer namespaces="pulse-install" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMZd/DaH+BldzOkq1A8KVTcFk73nAyrE8aJOyf7i00jm pulse-installer') \
-I pulse-installer \
-n pulse-install \
- -s "${PULSE_MSP_BUNDLE}.sshsig" < "${PULSE_MSP_BUNDLE}"
-sha256sum -c "${PULSE_MSP_BUNDLE}.sha256"
-
-tar -xzf "${PULSE_MSP_BUNDLE}"
-cd "pulse-provider-msp-${PULSE_VERSION}"
+ -s "${PULSE_MSP_BUNDLE}.sshsig" < "${PULSE_MSP_BUNDLE}" &&
+sha256sum -c "${PULSE_MSP_BUNDLE}.sha256" &&
+tar -xzf "${PULSE_MSP_BUNDLE}" &&
+cd "pulse-provider-msp-${PULSE_VERSION}" &&
sudo -E bash ./setup.sh
```
@@ -386,12 +386,24 @@ The licence request omits an email address unless you export
address is included in the request.
The host needs Ubuntu 24.04 or similar, a domain you can point at it, and
-ports 80 and 443 free. Install `curl`, `openssh-client`, `coreutils`, and `tar`
-before the verification step. The wildcard certificate is issued over DNS-01
-with Cloudflare as the default provider (`CF_DNS_API_TOKEN`); any other
+ports 80 and 443 free; 2 vCPU, 4 GB RAM and 40 GB of disk is enough for an
+evaluation. Install `curl`, `openssh-client`, `coreutils`, and `tar` before the
+verification step. Point two DNS records at the host's public IP: the domain
+you choose for `DOMAIN` (the portal, at `https://DOMAIN/portal`) and
+`*.DOMAIN` (each client workspace, at `https://<client-id>.DOMAIN`). On
+Cloudflare, set both to DNS only. The wildcard certificate is issued over
+DNS-01 with Cloudflare as the default provider (`CF_DNS_API_TOKEN`, a token
+with Zone / Zone / Read and Zone / DNS / Edit on that zone); any other
Traefik dnsChallenge provider works by setting `ACME_DNS_PROVIDER` in `.env`
and putting that provider's credential variables in `dns-credentials.env`.
+When setup pauses for `DOMAIN`, `ACME_EMAIL` and `CF_DNS_API_TOKEN`, edit
+`/opt/pulse-provider-msp/.env` from a second session with `sudo`, because the
+file is readable by root only, then press Enter. It ends with
+`Pulse Provider MSP is running.` and the bootstrap command that prints your
+portal sign-in link; run that command with `sudo` as well. In the portal,
+**Add client** and then **Install agents** walk the first client to live data.
+
Leave `CP_PROVIDER_MSP_LICENSE_FILE` blank and `setup.sh` self-issues a
2-client evaluation licence. The bundle sends the public half of the
signing key generated on your host, a setup-stage marker, and a signup-source
diff --git a/scripts/installtests/provider_msp_deploy_test.go b/scripts/installtests/provider_msp_deploy_test.go
index b04a369b30..bec01f90da 100644
--- a/scripts/installtests/provider_msp_deploy_test.go
+++ b/scripts/installtests/provider_msp_deploy_test.go
@@ -547,8 +547,14 @@ func TestProviderMSPEvaluationDocsUsePublishedSignedBundle(t *testing.T) {
`PULSE_MSP_BUNDLE="pulse-provider-msp-${PULSE_VERSION}.tar.gz"`,
`releases/download/${PULSE_VERSION}`,
"ssh-keygen -Y verify",
- `-s "${PULSE_MSP_BUNDLE}.sshsig" < "${PULSE_MSP_BUNDLE}"`,
- `sha256sum -c "${PULSE_MSP_BUNDLE}.sha256"`,
+ // Chained, so a failed signature or checksum stops before tar or setup.
+ `-s "${PULSE_MSP_BUNDLE}.sshsig" < "${PULSE_MSP_BUNDLE}" &&`,
+ `sha256sum -c "${PULSE_MSP_BUNDLE}.sha256" &&`,
+ "tar -xzf \"${PULSE_MSP_BUNDLE}\" &&",
+ // The portal and client workspaces need both records, and the default
+ // DNS-01 token needs both permissions.
+ "`*.DOMAIN` (each client workspace",
+ "Zone / Zone / Read and Zone / DNS / Edit",
"The licence request omits an email address unless you export",
"`PULSE_PROVIDER_MSP_EVAL_EMAIL` before running `setup.sh`",
"address is included in the request",
@@ -710,6 +716,49 @@ func TestProviderMSPSetupLeavesPlatformRunning(t *testing.T) {
assertContainsAll(t, first, "DOMAIN", "ACME_EMAIL", "CF_DNS_API_TOKEN")
}
+// Setup used to stop after installing Docker and ask the provider to edit a
+// root-only .env from a second session. It now asks for the three values a
+// provider must supply before installing anything, keeps the token off the
+// screen, accepts them from the environment for unattended runs, names the
+// two DNS records the certificate needs, and prints day-2 commands with sudo
+// because .env is readable by root only.
+func TestProviderMSPSetupAsksForFirstRunValuesUpFront(t *testing.T) {
+ scriptBytes, err := os.ReadFile(repoFile("deploy", "provider-msp", "setup.sh"))
+ if err != nil {
+ t.Fatalf("read provider MSP setup: %v", err)
+ }
+ script := string(scriptBytes)
+
+ if !strings.Contains(script, " collect_first_run_values\n apt_install apt-transport-https\n") {
+ t.Fatal("setup must collect first-run values before installing packages")
+ }
+ assertContainsAll(t, script,
+ `PULSE_PROVIDER_MSP_DOMAIN="${PULSE_PROVIDER_MSP_DOMAIN:-}"`,
+ `PULSE_PROVIDER_MSP_ACME_EMAIL="${PULSE_PROVIDER_MSP_ACME_EMAIL:-}"`,
+ `PULSE_PROVIDER_MSP_CF_DNS_API_TOKEN="${PULSE_PROVIDER_MSP_CF_DNS_API_TOKEN:-}"`,
+ `read -r -s -p "Cloudflare API token`,
+ `[[ -f "${PULSE_PROVIDER_MSP_INSTALL_DIR}/.env" ]] && return 0`,
+ `die "${key} is not valid; check it and run setup.sh again"`,
+ `(umask 077 && cp -n "${PULSE_PROVIDER_MSP_INSTALL_DIR}/.env.example" "${env_path}")`,
+ `set_env_value "${key}" "${!var}" "${env_path}"`,
+ " ${PULSE_PROVIDER_MSP_DOMAIN} the portal",
+ " *.${PULSE_PROVIDER_MSP_DOMAIN} one address per client",
+ )
+ // Values reach .env unquoted, so the token pattern must exclude every
+ // character compose or awk -v would interpret.
+ assertContainsAll(t, script, `local token_re='^[A-Za-z0-9_.+/=-]{20,255}$'`)
+
+ summary := script[strings.Index(script, "Pulse Provider MSP is running."):]
+ summary = summary[:strings.Index(summary, "EOF")]
+ assertContainsAll(t, summary,
+ " sudo docker compose run --rm control-plane provider-msp bootstrap",
+ " sudo ./run-install-proof.sh",
+ " sudo docker compose run --rm control-plane provider-msp portal-link",
+ "choose Add client, and follow Install agents",
+ )
+ assertNotContainsAny(t, summary, "\n docker compose run", "\n ./run-install-proof.sh")
+}
+
// Setup pins the images in .env to digests once, so an upgrade used to re-pull
// only the release a provider first installed. Run from a newly extracted
// bundle, upgrade.sh must install that bundle into the existing install,