Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(backup): note engine auth state copied while in use

Yudhi Armyndharis805134ba8e01
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.md
index 1401a15d3..6f33a1873 100644
--- a/docs/11-operational-runbooks.md
+++ b/docs/11-operational-runbooks.md
@@ -357,7 +357,8 @@ docker stats --no-stream
# 3. Create a backup in the running container, where the data is mounted, and copy it off the
# volume (see Runbook: Database Backup). A host run of ./scripts/backup.sh archives ./data in the
-# checkout, which only a bare-metal install or docker-compose.dev.yml reads
+# checkout, which only a bare-metal install or docker-compose.dev.yml reads. Engine auth state is
+# copied live; stop the sessions first if a restore must not need re-pairing
docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh
docker cp openwa-api:/app/data/backups/. ./backups/
@@ -436,7 +437,8 @@ curl -H "X-API-Key: $API_KEY" \
# files name the container openwa-api. Running ./scripts/backup.sh on the host instead archives
# ./data in the checkout, which the production compose never reads (see Runbook: Database Backup).
# An image older than 0.19.0 has no scripts/backup.sh, and on PostgreSQL one older than 0.22.0 has
-# no pg_dump: see 14 - Known Upgrade Hazards
+# no pg_dump: see 14 - Known Upgrade Hazards. Engine auth state is copied live; stop the sessions
+# first if a rollback must not need re-pairing
export BACKUP_DIR="/backups/openwa"
mkdir -p "$BACKUP_DIR"
docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh
@@ -590,7 +592,10 @@ curl -H "X-API-Key: $API_KEY" http://localhost:2785/api/health
**Trigger:** Daily schedule, before maintenance, before upgrade
-**Impact:** None (online backup)
+**Impact:** None for the databases, which are snapshotted consistently online (`sqlite3 .backup`,
+`pg_dump`). Engine authentication state (`sessions/`, `baileys/`) is copied while the engines write
+it, so a restored session can need re-pairing; for a copy that is consistent by construction, stop
+the sessions first (`POST /api/sessions/:id/stop`), or stop the container and archive the volume.
**Prerequisites:**
@@ -626,7 +631,9 @@ User-managed files outside that list (for example the project-level `.env`) must
# are NOT derived from OPENWA_DATA_DIR. A missing source database fails the run (no silent empty
# backup), the finished archive is checked to contain every configured database, and with the sqlite3
# CLI present the databases are snapshotted online via .backup (otherwise plain-copied with a
-# CONSISTENCY-WARNING marker inside the archive).
+# CONSISTENCY-WARNING marker inside the archive). sessions/ and baileys/ are plain copies: when a
+# whatsapp-web.js profile is open or Baileys state is present, the archive carries an
+# ENGINE-STATE-NOTE naming them, which restore.sh prints and never refuses.
# Run from the repo root (database defaults are ./data/...; state dirs follow OPENWA_DATA_DIR):
./scripts/backup.sh
@@ -713,7 +720,8 @@ docker compose down
# (databases land on MAIN_DATABASE_NAME / DATABASE_NAME, default ./data/... — the same paths
# the app reads, as the environment, ./.env or the archive's .env.generated set them; non-DB
# state follows OPENWA_DATA_DIR. Pass --strict to refuse an archive
-# whose CONSISTENCY-WARNING marker reports plain-copied, possibly-torn database snapshots.
+# whose CONSISTENCY-WARNING marker reports plain-copied, possibly-torn database snapshots;
+# an ENGINE-STATE-NOTE (engine auth state that may have been copied while the app ran) is only printed.
# Restoring over an existing install's live databases requires --force; without it the script
# refuses to overwrite them)
./scripts/restore.sh ./backups/openwa-backup-<timestamp>.tar.gz
diff --git a/scripts/backup.sh b/scripts/backup.sh
index 9bd310f89..2b6fb1541 100755
--- a/scripts/backup.sh
+++ b/scripts/backup.sh
@@ -49,6 +49,12 @@
# sqlite3 CLI is unavailable the databases are plain-copied (possibly torn if the app is live) and
# the archive carries a CONSISTENCY-WARNING marker that restore.sh surfaces.
#
+# Engine authentication state (sessions/, baileys/) is copied, not snapshotted: the engines rewrite
+# it while they run, so an online backup can hold a copy torn mid-write. When a whatsapp-web.js
+# profile is open or Baileys state is present, the archive carries an ENGINE-STATE-NOTE that
+# restore.sh prints without refusing (--strict gates only the database marker). For a copy that is
+# consistent by construction, stop the sessions (or the container) first.
+#
set -euo pipefail
# The archive now contains bootstrap credentials and generated database secrets. Never inherit a
# permissive operator umask for newly-created backup artifacts.
@@ -121,6 +127,24 @@ EOF
echo "plain-copied: $1" >>"$CONSISTENCY_WARNING"
}
+ENGINE_STATE_NOTE="$STAGE/ENGINE-STATE-NOTE"
+
+# Marker file shipped INSIDE the archive: engine auth state was copied while an engine may have been
+# writing it. Separate from the database marker so restore.sh --strict does not refuse every online
+# backup; a torn auth copy costs a re-pair, not data.
+record_engine_state_note() {
+ if [ ! -f "$ENGINE_STATE_NOTE" ]; then
+ cat >"$ENGINE_STATE_NOTE" <<'EOF'
+The engine authentication state listed below was copied while the app may have been writing it:
+these directories are plain copies. This note does not cover the databases; a CONSISTENCY-WARNING
+in the same archive does. If a restored session does not reconnect, pair it again, or re-take the
+backup with the sessions (or the container) stopped.
+EOF
+ fi
+ echo "$1" >>"$ENGINE_STATE_NOTE"
+ log "WARN: engine auth state may have been written during the copy; a restore may need re-pairing: $1"
+}
+
# Online SQLite backup (consistent without stopping the app) when sqlite3 is present. A missing
# source database is FATAL: an archive without the configured databases is not a backup, and a
# silent skip is how an empty archive gets reported as "Backup complete".
@@ -179,6 +203,13 @@ fi
if [ -d "$SESSIONS_DIR" ]; then
log "Backing up whatsapp-web.js sessions"
cp -pRH "$SESSIONS_DIR" "$STAGE/sessions"
+ # Chromium holds a SingletonLock (a symlink, so not `-e`) in every profile it has open, and the
+ # entrypoint clears stale ones at start, so a lock here means a browser was writing that profile.
+ OPEN_PROFILES="$(find -H "$SESSIONS_DIR" -mindepth 2 -maxdepth 2 -name SingletonLock -exec dirname {} \; |
+ sed 's|.*/||' | sort | tr '\n' ' ')"
+ if [ -n "$OPEN_PROFILES" ]; then
+ record_engine_state_note "sessions/ (whatsapp-web.js profiles open in a browser: ${OPEN_PROFILES% })"
+ fi
else
log "WARN: $SESSIONS_DIR not found — skipping sessions"
fi
@@ -186,6 +217,11 @@ fi
if [ -d "$BAILEYS_DIR" ]; then
log "Backing up Baileys authentication state"
cp -pRH "$BAILEYS_DIR" "$STAGE/baileys"
+ # Baileys rewrites creds.json and its key files during normal traffic and leaves no sign of being
+ # live, so any session's state counts, stopped or not.
+ if [ -n "$(find -H "$BAILEYS_DIR" -mindepth 1 -maxdepth 1 -type d -print -quit)" ]; then
+ record_engine_state_note "baileys/ (recorded whenever Baileys state exists; it cannot show whether it was live)"
+ fi
elif [ "${ENGINE_TYPE:-}" = "baileys" ]; then
log "WARN: ENGINE_TYPE=baileys but $BAILEYS_DIR was not found — restored sessions will require pairing"
fi
diff --git a/scripts/restore.sh b/scripts/restore.sh
index becf19660..e4e9c7949 100755
--- a/scripts/restore.sh
+++ b/scripts/restore.sh
@@ -11,7 +11,8 @@
# Options:
# --strict refuse to restore an archive whose CONSISTENCY-WARNING marker reports
# plain-copied (possibly torn) database snapshots; without it the restore
-# continues after a loud warning
+# continues after a loud warning. An ENGINE-STATE-NOTE (engine auth state that
+# may have been copied while the app ran) is printed either way and never refused.
# --force overwrite databases that already hold a working install's data; without it
# the restore refuses to touch a live target before changing anything
# Environment:
@@ -345,6 +346,13 @@ if [ -f "$STAGE/CONSISTENCY-WARNING" ]; then
log "WARN: continuing anyway; verify data integrity after the restore (re-run with --strict to make this fatal)"
fi
+# Engine auth state copied while an engine may have been writing it. Informational only: every
+# online backup of a running install carries it, and the worst case is a re-pair, not lost data.
+if [ -f "$STAGE/ENGINE-STATE-NOTE" ]; then
+ log "WARN: archive carries ENGINE-STATE-NOTE; engine auth state may have been copied while the app was running:"
+ sed 's/^/[restore] /' "$STAGE/ENGINE-STATE-NOTE"
+fi
+
# Refuse to overwrite a live database without --force, BEFORE any existing state is touched (the
# same rule the --strict refusal above follows). Only the databases this archive actually carries
# are checked — a target the archive omits is left alone either way.
diff --git a/scripts/smoke-test-backup-restore.sh b/scripts/smoke-test-backup-restore.sh
index 39c656eaf..e3b482c43 100755
--- a/scripts/smoke-test-backup-restore.sh
+++ b/scripts/smoke-test-backup-restore.sh
@@ -39,6 +39,8 @@
# (y) plugin packages in the legacy ./plugins, which the archive does not carry, are reported
# (z) a leftover ./uploads that was never created, beside an existing ./data/media, resolves there in
# both scripts whatever the uid
+# (aa) engine auth state copied from a running app (an open whatsapp-web.js profile, Baileys state)
+# is noted in the archive and printed by restore, which does not refuse it even with --strict
#
# Usage: ./scripts/smoke-test-backup-restore.sh
# Requires: bash, tar, node (restore.sh path resolution). sqlite3 is optional (see (c) and (k)).
@@ -1173,5 +1175,58 @@ if [ "$(cat "$Z/dst/data/media/a.jpg" 2>/dev/null || true)" != "zulu-media" ] ||
fi
pass "(z) a never-created ./uploads beside ./data/media resolves to ./data/media without a uid check"
+echo ""
+echo "==> (aa) engine auth state copied from a running app is noted, and restore does not refuse it"
+# The databases are snapshotted consistently online, but sessions/ and baileys/ are plain copies of
+# directories the engines keep writing, and the runbook called the online backup impact-free. The
+# note has its own marker: --strict gates only the database one, or it would refuse every online backup.
+AA="$WORK/aa"
+mkdir -p "$AA/src/data/sessions/session-s1" "$AA/src/data/sessions/session-s2" "$AA/src/data/baileys/s1" \
+ "$AA/dst" "$AA/quiet/data/sessions/session-s1"
+make_fixture "$AA/src/data/main.sqlite" "alpha2-main"
+make_fixture "$AA/src/data/openwa.sqlite" "alpha2-data"
+printf 'profile\n' >"$AA/src/data/sessions/session-s1/Preferences"
+printf 'profile\n' >"$AA/src/data/sessions/session-s2/Preferences"
+ln -s host-123 "$AA/src/data/sessions/session-s1/SingletonLock"
+printf '{}' >"$AA/src/data/baileys/s1/creds.json"
+OUT_AA="$(cd "$AA/src" && BACKUP_DIR="$AA/out" "$BACKUP" 2>&1)"
+ARCHIVE_AA="$(ls "$AA"/out/openwa-backup-*.tar.gz)"
+NOTE_AA="$(tar -xOzf "$ARCHIVE_AA" ./ENGINE-STATE-NOTE 2>/dev/null || true)"
+if ! printf '%s\n' "$NOTE_AA" | grep -q 'open in a browser: session-s1)' ||
+ ! printf '%s\n' "$NOTE_AA" | grep -q '^baileys/'; then
+ fail "(aa) the archive does not note the open profile and the Baileys state: $NOTE_AA"
+fi
+# Without sqlite3 the same archive carries CONSISTENCY-WARNING, so the engine note must not vouch
+# for the databases.
+if printf '%s\n' "$NOTE_AA" | grep -qi 'consistent snapshot'; then
+ fail "(aa) the engine note claims the databases are consistent: $NOTE_AA"
+fi
+if ! printf '%s' "$OUT_AA" | grep -q 'may have been written during the copy'; then
+ fail "(aa) backup did not warn that engine auth state may have been written during the copy: $OUT_AA"
+fi
+if ! tar -tvzf "$ARCHIVE_AA" | grep -q '^l.*session-s1/SingletonLock'; then
+ fail "(aa) the profile lock was not archived as the symlink it is"
+fi
+# Without sqlite3 the databases are plain-copied and --strict rightly refuses on that marker.
+if [ "$HAS_SQLITE3" -eq 1 ]; then
+ OUT_AA="$(cd "$AA/dst" && "$RESTORE" "$ARCHIVE_AA" --strict 2>&1)" ||
+ fail "(aa) restore --strict refused an archive whose only note is the engine one: $OUT_AA"
+else
+ OUT_AA="$(cd "$AA/dst" && "$RESTORE" "$ARCHIVE_AA" 2>&1)" || fail "(aa) restore failed: $OUT_AA"
+fi
+if ! printf '%s' "$OUT_AA" | grep -q 'ENGINE-STATE-NOTE; engine auth state may have been copied' ||
+ ! printf '%s' "$OUT_AA" | grep -q 'session-s1'; then
+ fail "(aa) restore did not print the engine state note: $OUT_AA"
+fi
+# No open profile and no Baileys state: nothing to note.
+make_fixture "$AA/quiet/data/main.sqlite" "alpha2-quiet-main"
+make_fixture "$AA/quiet/data/openwa.sqlite" "alpha2-quiet-data"
+printf 'profile\n' >"$AA/quiet/data/sessions/session-s1/Preferences"
+(cd "$AA/quiet" && BACKUP_DIR="$AA/quiet-out" "$BACKUP" >/dev/null 2>&1)
+if tar -tzf "$(ls "$AA"/quiet-out/openwa-backup-*.tar.gz)" | grep -q 'ENGINE-STATE-NOTE'; then
+ fail "(aa) an archive with no open profile and no Baileys state carries the engine note"
+fi
+pass "(aa) live engine auth state is noted in the archive and printed, never refused"
+
echo ""
echo "All smoke tests passed!"
diff --git a/src/common/ci-privilege-gate.spec.ts b/src/common/ci-privilege-gate.spec.ts
index dcf8eede6..9650bc4fd 100644
--- a/src/common/ci-privilege-gate.spec.ts
+++ b/src/common/ci-privilege-gate.spec.ts
@@ -345,4 +345,16 @@ describe('deployment docs describe what the entrypoint, probes and backup script
expect(text).toMatch(/the chart's startupProbe budget/);
}
});
+
+ // The note is written for any archive holding engine state, including one taken with sessions stopped.
+ it('words the ENGINE-STATE-NOTE as a possibility in the restore.sh header', () => {
+ const phrase = 'ENGINE-STATE-NOTE (engine auth state that may have been copied while the app ran)';
+ const header = read('scripts/restore.sh')
+ .split('\n')
+ .filter(line => line.startsWith('#'))
+ .map(line => line.replace(/^#\s*/, ''))
+ .join(' ');
+ expect(header).toContain(phrase);
+ expect(read('docs/11-operational-runbooks.md')).toContain(phrase);
+ });
});