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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
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.mdindex 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 namespaceThe installer's configuration snapshot rotation treats the configured basenamediff --git a/install.sh b/install.shindex 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 existfor config_file in "$CONFIG_DIR"/alerts.json "$CONFIG_DIR"/system.json "$CONFIG_DIR"/*.enc "$CONFIG_DIR"/*.json; doif [[ -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+ fifidonefor config_dir in "$CONFIG_DIR"/alerts "$CONFIG_DIR"/notifications "$CONFIG_DIR"/audit; doif [[ -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+ fifidone# 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=6EOF+ then+ print_error "Could not write Pulse environment configuration; directory setup is incomplete"+ return 1+ fifiif [[ -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+ fifiif [[ -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+ fifi+ return 0}setup_update_command() {@@ -5329,7 +5350,7 @@ main() {# If building from source was requested, skip the update promptif [[ "$BUILD_FROM_SOURCE" == "true" ]]; thencreate_user- setup_directories+ setup_directories || return 1if ! build_from_source "$SOURCE_BRANCH"; thenexit 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 1setup_update_commandensure_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 1setup_update_commandensure_systemd_service_installed || return 1@@ -5615,7 +5636,7 @@ main() {backup_existing || return 1create_userdownload_pulse- setup_directories+ setup_directories || return 1setup_update_commandinstall_systemd_service || return 1@@ -5724,7 +5745,7 @@ main() {install_dependenciescreate_user- setup_directories+ setup_directories || return 1download_pulsesetup_update_commandinstall_systemd_service || return 1diff --git a/scripts/installtests/root_install_sh_test.go b/scripts/installtests/root_install_sh_test.goindex 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.pynew file mode 100644index 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)