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.

Stop installation when directory setup is incomplete

pulse-triage[bot]5003b7c55f3a
diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md
index cbb041ffe1..ad6a06fcda 100644
--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md
+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md
@@ -16,6 +16,26 @@
## Purpose
+### Directory setup failure cannot become installation success
+
+The server installer's five source, pinned, menu-update, reinstall and fresh
+entry paths require successful directory setup before the next build/helper,
+unit, timer, service-start or completion step. Creating either directory,
+setting directory/configuration ownership, creating the default environment,
+and protecting `.env` or `.encryption.key` must each propagate a failed command
+explicitly. This also applies when a caller puts `main` or `setup_directories`
+in an OR-list and Bash therefore disables `errexit` in its callees.
+
+Failure reports incomplete directory setup and does not claim rollback or an
+unchanged whole installation: an update may already have replaced its binary,
+and earlier successful ownership/mode changes remain. Existing configuration,
+keys and recovery snapshots are not deleted to repair admission. Successful
+setup retains existing contents, configured paths and current ownership/mode
+policy. The registered `TestRootInstallDirectorySetupStopsOnFailures` executes
+all operations with private text files and inert ownership/lifecycle doubles,
+including every failure boundary and all five callers. It is source-bound
+failure/preservation proof, not native signed upgrade or original recovery.
+
### Configuration snapshot rotation stays in its literal instance namespace
The installer's configuration snapshot rotation treats the configured basename
diff --git a/install.sh b/install.sh
index cff6aa471c..a89910f61a 100644
--- a/install.sh
+++ b/install.sh
@@ -4219,31 +4219,43 @@ setup_directories() {
print_info "Setting up directories..."
# Create directories (only if they don't exist)
- mkdir -p "$CONFIG_DIR"
- mkdir -p "$INSTALL_DIR"
+ if ! mkdir -p -- "$CONFIG_DIR" || ! mkdir -p -- "$INSTALL_DIR"; then
+ print_error "Could not create Pulse directories; directory setup is incomplete"
+ return 1
+ fi
# Set permissions (preserve existing files)
# Use chown without -R on CONFIG_DIR to avoid changing existing file permissions
- chown pulse:pulse "$CONFIG_DIR"
- chown_install_dir_for_pulse
- chmod 700 "$CONFIG_DIR"
+ # main can itself be called in an OR-list, where Bash disables errexit
+ # throughout its callees. Every required operation must propagate failure
+ # explicitly before service setup/start or a completion message is allowed.
+ if ! chown pulse:pulse "$CONFIG_DIR" || ! chown_install_dir_for_pulse || ! chmod 700 "$CONFIG_DIR"; then
+ print_error "Could not set Pulse directory ownership or permissions; directory setup is incomplete"
+ return 1
+ fi
# Ensure critical config files retain proper permissions if they exist
for config_file in "$CONFIG_DIR"/alerts.json "$CONFIG_DIR"/system.json "$CONFIG_DIR"/*.enc "$CONFIG_DIR"/*.json; do
if [[ -f "$config_file" ]]; then
- chown pulse:pulse "$config_file"
+ if ! chown pulse:pulse "$config_file"; then
+ print_error "Could not set ownership of $config_file; directory setup is incomplete"
+ return 1
+ fi
fi
done
for config_dir in "$CONFIG_DIR"/alerts "$CONFIG_DIR"/notifications "$CONFIG_DIR"/audit; do
if [[ -d "$config_dir" ]]; then
- chown -R pulse:pulse "$config_dir"
+ if ! chown -R pulse:pulse "$config_dir"; then
+ print_error "Could not set ownership of $config_dir; directory setup is incomplete"
+ return 1
+ fi
fi
done
# Create .env file with mock mode explicitly disabled (unless it already exists)
if [[ ! -f "$CONFIG_DIR/.env" ]]; then
- cat > "$CONFIG_DIR/.env" << 'EOF'
+ if ! cat > "$CONFIG_DIR/.env" << 'EOF'
# Pulse Environment Configuration
# This file is loaded by systemd when starting Pulse
@@ -4258,16 +4270,25 @@ PULSE_MOCK_MODE=false
#PULSE_MOCK_RANDOM_METRICS=true
#PULSE_MOCK_STOPPED_PERCENT=6
EOF
+ then
+ print_error "Could not write Pulse environment configuration; directory setup is incomplete"
+ return 1
+ fi
fi
if [[ -f "$CONFIG_DIR/.env" ]]; then
- chown pulse:pulse "$CONFIG_DIR/.env"
- chmod 600 "$CONFIG_DIR/.env"
+ if ! chown pulse:pulse "$CONFIG_DIR/.env" || ! chmod 600 "$CONFIG_DIR/.env"; then
+ print_error "Could not protect Pulse environment configuration; directory setup is incomplete"
+ return 1
+ fi
fi
if [[ -f "$CONFIG_DIR/.encryption.key" ]]; then
- chown pulse:pulse "$CONFIG_DIR/.encryption.key"
- chmod 600 "$CONFIG_DIR/.encryption.key"
+ if ! chown pulse:pulse "$CONFIG_DIR/.encryption.key" || ! chmod 600 "$CONFIG_DIR/.encryption.key"; then
+ print_error "Could not protect the Pulse encryption key; directory setup is incomplete"
+ return 1
+ fi
fi
+ return 0
}
setup_update_command() {
@@ -5329,7 +5350,7 @@ main() {
# If building from source was requested, skip the update prompt
if [[ "$BUILD_FROM_SOURCE" == "true" ]]; then
create_user
- setup_directories
+ setup_directories || return 1
if ! build_from_source "$SOURCE_BRANCH"; then
exit 1
@@ -5381,7 +5402,7 @@ main() {
# unit file deleted, #1663) reaches this update path; recreate
# the environment the steps below assume instead of crashing on
# a missing config dir or reporting success over a missing unit.
- setup_directories
+ setup_directories || return 1
setup_update_command
ensure_systemd_service_installed || return 1
@@ -5586,7 +5607,7 @@ main() {
# Same repair as the --version path: a half-removed
# installation (#1663) must get its config dir and unit
# file back before auto-update setup and start.
- setup_directories
+ setup_directories || return 1
setup_update_command
ensure_systemd_service_installed || return 1
@@ -5615,7 +5636,7 @@ main() {
backup_existing || return 1
create_user
download_pulse
- setup_directories
+ setup_directories || return 1
setup_update_command
install_systemd_service || return 1
@@ -5724,7 +5745,7 @@ main() {
install_dependencies
create_user
- setup_directories
+ setup_directories || return 1
download_pulse
setup_update_command
install_systemd_service || return 1
diff --git a/scripts/installtests/root_install_sh_test.go b/scripts/installtests/root_install_sh_test.go
index b526475ddd..12ab960381 100644
--- a/scripts/installtests/root_install_sh_test.go
+++ b/scripts/installtests/root_install_sh_test.go
@@ -3004,6 +3004,19 @@ func TestRootInstallScriptConfigBackupPublicationPreservesPriorSnapshots(t *test
}, 30*time.Second, "PULSE_INSTALLER_UNDER_TEST="+repoFile("install.sh"))
}
+// The real directory admission and all five main entry paths run only against
+// private text files and inert chown/lifecycle doubles. In particular, an OR-list
+// must not turn an incomplete permission repair into successful installation.
+func TestRootInstallDirectorySetupStopsOnFailures(t *testing.T) {
+ runPythonFixtureControls(t, repoFile("scripts", "tests", "test_server_directory_setup.py"), "DirectorySetup", []string{
+ "test_every_permission_and_directory_failure_stops_in_conditional_call",
+ "test_new_environment_write_failure_stops_before_ownership_or_completion",
+ "test_success_preserves_existing_bytes_and_tightens_only_required_modes",
+ "test_fresh_environment_has_private_mode_and_explicit_mock_default",
+ "test_all_five_entry_paths_stop_on_directory_failure_even_in_or_list",
+ }, 30*time.Second, "PULSE_INSTALLER_UNDER_TEST="+repoFile("install.sh"))
+}
+
// Run the emitted helper and real SSH verifier. Curl exits are modelled, so
// these controls prove deadline arguments and safe failure, not a live outage.
func TestRootManualUpdateDownloadDeadlines(t *testing.T) {
diff --git a/scripts/tests/test_server_directory_setup.py b/scripts/tests/test_server_directory_setup.py
new file mode 100644
index 0000000000..121ab903c7
--- /dev/null
+++ b/scripts/tests/test_server_directory_setup.py
@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Execute directory admission with private text files and inert ownership calls.
+
+No system user, manager, real configuration or binary is changed. These controls
+prove failure propagation and retained bytes, not native install/rollback.
+"""
+import os
+from pathlib import Path
+import stat
+import subprocess
+import tempfile
+import unittest
+
+ROOT = Path(__file__).resolve().parents[2]
+INSTALLER = Path(os.environ.get("PULSE_INSTALLER_UNDER_TEST", ROOT / "install.sh")).resolve()
+
+PRELUDE = r'''
+set -euo pipefail
+source "$INSTALLER"
+print_info() { :; }
+print_error() { printf '%s\n' "$*" >&2; }
+step() { printf '%s\n' "$1" >> "$FIXTURE/calls"; [[ "$1" != "$FAULT" ]]; }
+mkdir() { step "mkdir:${@: -1}" || return 23; command mkdir "$@"; }
+chown() { step "chown:${@: -1}" || return 23; }
+chmod() { step "chmod:${@: -1}" || return 23; command chmod "$@"; }
+chown_install_dir_for_pulse() { step install-owner || return 23; }
+cat() { step env-write || return 23; command cat "$@"; }
+'''
+
+
+class DirectorySetup(unittest.TestCase):
+ def setUp(self):
+ self.temporary = tempfile.TemporaryDirectory(prefix="pulse-directory-setup-")
+ self.addCleanup(self.temporary.cleanup)
+ self.root = Path(self.temporary.name)
+ self.config = self.root / "config with spaces"
+ self.install = self.root / "install with spaces"
+ self.config.mkdir()
+ self.install.mkdir()
+ for name in ("alerts.json", "system.json", "extra.json", "nodes.enc", ".env", ".encryption.key"):
+ path = self.config / name
+ path.write_text("synthetic preserved " + name + "\n")
+ path.chmod(0o644)
+ for name in ("alerts", "notifications", "audit"):
+ path = self.config / name
+ path.mkdir()
+ (path / "retained").write_text("preserved tree\n")
+ (self.install / "VERSION").write_text("v6.5.0\n")
+ self.before = {p.relative_to(self.root): p.read_bytes()
+ for p in self.root.rglob("*") if p.is_file()}
+
+ def shell(self, body, fault="", **extra):
+ env = {k: v for k, v in os.environ.items() if not k.startswith("PULSE_")}
+ env.update(INSTALLER=str(INSTALLER), FIXTURE=str(self.root), FAULT=fault,
+ PULSE_INSTALL_DIR=str(self.install), PULSE_CONFIG_DIR=str(self.config))
+ env.update(extra)
+ return subprocess.run(["bash", "-c", PRELUDE + body], cwd=self.root,
+ env=env, capture_output=True, text=True, timeout=10)
+
+ def assert_preserved(self):
+ for name, content in self.before.items():
+ self.assertEqual((self.root / name).read_bytes(), content, str(name))
+
+ def test_every_permission_and_directory_failure_stops_in_conditional_call(self):
+ targets = ["mkdir:" + str(self.config), "mkdir:" + str(self.install),
+ "chown:" + str(self.config), "install-owner", "chmod:" + str(self.config)]
+ targets += ["chown:" + str(self.config / name) for name in
+ ("alerts.json", "system.json", "extra.json", "nodes.enc",
+ "alerts", "notifications", "audit", ".env", ".encryption.key")]
+ targets += ["chmod:" + str(self.config / name) for name in (".env", ".encryption.key")]
+ for fault in targets:
+ with self.subTest(fault=fault):
+ calls = self.root / "calls"
+ calls.unlink(missing_ok=True)
+ result = self.shell('status=0\nsetup_directories || status=$?\n'
+ 'printf "SETUP_EXIT=%s\\n" "$status"\n', fault=fault)
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertIn("SETUP_EXIT=1\n", result.stdout)
+ self.assertIn("Could not", result.stderr)
+ events = calls.read_text().splitlines()
+ self.assertEqual(events[-1], fault, "continued after failed filesystem operation")
+ self.assert_preserved()
+
+ def test_new_environment_write_failure_stops_before_ownership_or_completion(self):
+ environment = self.config / ".env"
+ environment.unlink()
+ del self.before[Path(environment.relative_to(self.root))]
+ result = self.shell('status=0\nsetup_directories || status=$?\n'
+ 'printf "SETUP_EXIT=%s\\n" "$status"\n', fault="env-write")
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertIn("SETUP_EXIT=1\n", result.stdout)
+ self.assertIn("environment", result.stderr)
+ self.assertEqual((self.root / "calls").read_text().splitlines()[-1], "env-write")
+ self.assert_preserved()
+
+ def test_success_preserves_existing_bytes_and_tightens_only_required_modes(self):
+ result = self.shell('setup_directories\n')
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assert_preserved()
+ self.assertEqual(stat.S_IMODE(self.config.stat().st_mode), 0o700)
+ for name in (".env", ".encryption.key"):
+ self.assertEqual(stat.S_IMODE((self.config / name).stat().st_mode), 0o600)
+ for name in ("alerts.json", "system.json", "extra.json", "nodes.enc"):
+ self.assertEqual(stat.S_IMODE((self.config / name).stat().st_mode), 0o644)
+
+ def test_fresh_environment_has_private_mode_and_explicit_mock_default(self):
+ environment = self.config / ".env"
+ environment.unlink()
+ del self.before[Path(environment.relative_to(self.root))]
+ result = self.shell('umask 022\nsetup_directories\n')
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertIn("PULSE_MOCK_MODE=false\n", environment.read_text())
+ self.assertEqual(stat.S_IMODE(environment.stat().st_mode), 0o600)
+ self.assert_preserved()
+
+ def test_all_five_entry_paths_stop_on_directory_failure_even_in_or_list(self):
+ for flow in ("source", "pinned", "menu-update", "menu-reinstall", "fresh"):
+ with self.subTest(flow=flow):
+ result = self.shell(r'''
+CURRENT_VERSION=v6.5.0
+FORCE_VERSION=""
+FORCE_CHANNEL=stable
+BUILD_FROM_SOURCE=false
+IN_CONTAINER=true
+IN_DOCKER=false
+[[ "$FLOW" != pinned ]] || FORCE_VERSION=v6.6.0
+[[ "$FLOW" != source ]] || BUILD_FROM_SOURCE=true
+print_header() { :; }
+check_root() { :; }
+detect_os() { :; }
+check_docker_environment() { :; }
+check_existing_installation() { [[ "$FLOW" != fresh ]]; }
+check_proxmox_host() { return 1; }
+resolve_latest_release_tag_for_channel() { printf 'v6.6.0\n'; }
+detect_service_name() { printf 'pulse\n'; }
+safe_read() { local selection=1; [[ "$FLOW" != menu-reinstall ]] || selection=2; printf -v "$2" '%s' "$selection"; }
+offer_existing_auto_updates() { :; }
+run_upgrade_readiness_preflight() { :; }
+backup_existing() { :; }
+install_dependencies() { :; }
+create_user() { :; }
+download_pulse() { :; }
+setup_directories() { printf 'directory admission refused\n' >&2; return 23; }
+# No real build, systemd, updater, process or HOME marker is admitted.
+after_failure() { printf '%s\n' unexpected >> "$FIXTURE/unexpected"; }
+build_from_source() { after_failure; }
+setup_update_command() { after_failure; }
+install_systemd_service() { after_failure; }
+ensure_systemd_service_installed() { after_failure; }
+setup_auto_updates() { after_failure; }
+update_timer_exists() { after_failure; }
+refresh_auto_updates() { after_failure; }
+start_pulse() { after_failure; }
+create_marker_file() { after_failure; }
+print_completion() { after_failure; }
+status=0
+main || status=$?
+printf 'MAIN_EXIT=%s\n' "$status"
+''', FLOW=flow)
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertIn("MAIN_EXIT=1\n", result.stdout)
+ self.assertIn("directory admission refused", result.stderr)
+ self.assertFalse((self.root / "unexpected").exists(), result.stdout + result.stderr)
+ self.assert_preserved()
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)