[Docs audit] xbcloud pages: provider examples do not run, cloud incremental impossible, .env methods do not export credentials, /tmp restore

Start on the 8.4 branch with docs/xbcloud-s3.md, xbcloud-azure.md, xbcloud-env.md and xbcloud-binary-overview.md, checking the line ranges in D9, D10, D11 and D34. Reproduce one example, such as the S3 full backup, against a local MinIO to see the failure. Each claimed fix is done when the corrected command runs as written and the page is checked for the other items in the issue, since D39 and D62 cover the backoff and reference pages.

Found during a hands-on audit of the Percona XtraBackup docs (2026-10-12): every page was executed as written on Ubuntu 24.04, Ubuntu 26.04, Debian 13, Rocky 9 and Rocky 10 (SELinux enforcing) with PXB 8.0.35-36, 8.4.0-7 and 9.7.1-rc1 against Percona Server 8.0.46/8.4.11/9.7.2 and Oracle MySQL 8.0.46/8.4.11/9.7.2, with data and a concurrent write load; the rendered sites were also crawled and link-checked. Source references are <branch>:docs/<file>.md:<line> (branches 8.0 @6145834, 8.4 @5d943a6, 9.7 @5aff2c7). Finding IDs (D1-D70) are shared across the issues of this audit:

Findings in this issue: D9 (High), D10 (High), D11 (High), D34 (High), D39 (Medium), D62 (Medium)

D9. The xbcloud provider examples do not run: S3, MinIO, GCS, Azure and Swift

• Severity: High
• Series: 8.4 (executed). The 9.7 pages were not executed.
• Pages:
  • 8.4/xbcloud-s3 (8.4:xbcloud-s3.md:6-13,84-86)
  • xbcloud-minio (8.4:xbcloud-minio.md:6-13)
  • xbcloud-gcs (8.4:xbcloud-gcs.md:67-88)
  • xbcloud-azure (8.4:xbcloud-azure.md:14,17,36-46)
  • xbcloud-swift (8.4:xbcloud-swift.md:8-15,71-74,81-94)
• What happened:
  • S3, MinIO, GCS: the full-backup command lacks a \ after --s3-bucket=..., which gives Backup name is required argument and --parallel=10: command not found.
    • The bucket mysql_backups is invalid (S3 returns 400), and xbcloud only says "Probe failed".
    • An endpoint without a scheme defaults to https.
    • GCS puts backticks around the endpoint, which the shell treats as command substitution.
    • The S3 restore example points at Google's endpoint.
    • play.minio.io:9000 does not answer. The MinIO community binaries now return HTTP 410 (archived upstream).
  • Azure: the get and delete commands are split over two lines without \. The format for --azure-endpoint is never stated: with the bare endpoint xbcloud returned HTTP 400 and exited 1 silently, and with /devstoreaccount1 appended it returned 403. Only --azure-development-storage worked.
  • Swift: the bare auth URL fails with "TempAuth failed with code 412"; .../auth/v1.0 works. The delete example has no backup name. A $ prompt sits inside the copyable block. OS_PASSWORD does not apply to TempAuth.
  • What works: with the fixes below, MinIO (full plus 2 incrementals), Azurite and Swift all restored exactly.
• Fix: use a tested template for every provider, for example:

  xtrabackup --backup --stream=xbstream --extra-lsndir=/data/backups/lsn --target-dir=/data/backups/tmp | \
  xbcloud put --storage=s3 --s3-endpoint='https://minio.example.com:9000' \
    --s3-access-key='KEY' --s3-secret-key='SECRET' --s3-bucket='mysql-backups' \
    --s3-bucket-lookup=path --parallel=10 $(date -I)-full_backup
  

  • GCS: --google-endpoint='storage.googleapis.com' --google-bucket='mysql-backups', plus a note on HMAC keys.
  • Azure: --azure-endpoint=https://<account>.blob.core.windows.net, plus a full Azurite example.
  • Swift: --swift-auth-url=http://swift:8080/auth/v1.0 for TempAuth.
  • Add get, delete and restore examples for every provider.
  • Say that xbcloud creates the bucket or container if it is missing.
  • State MinIO's archived status.

D10. The cloud incremental workflow cannot work: stream backups leave no xtrabackup_checkpoints

• Severity: High
• Series: 8.4
• Pages: 8.4/xbcloud-binary-overview (8.4:xbcloud-binary-overview.md:71-88,313-328)
• Doc says: full backup --stream=xbstream --target-dir=/tmp/backup | xbcloud put ..., then incremental --incremental-basedir=/tmp/backup.
• What happened:
  • /tmp/backup is empty after a streamed backup, so the incremental fails: cannot open /tmp/backup//xtrabackup_checkpoints, pipestatus 1 1, "xbcloud: Upload failed.".
  • With --extra-lsndir per backup, the chain uploaded and restored exactly.
• Fix:
  • Full backup: add --extra-lsndir=/data/backups/lsn/full.
  • inc1: --incremental-basedir=/data/backups/lsn/full --extra-lsndir=/data/backups/lsn/inc1.
  • Explain that the LSN directory must be kept on the backup host, or fetched with xbcloud get <full> xtrabackup_checkpoints.
  • Say that --target-dir only holds temporary files when streaming.

D11. The xbcloud-env methods 1 and 2 do not pass credentials to xbcloud

• Severity: High
• Series: 8.4
• Pages: 8.4/xbcloud-env (8.4:xbcloud-env.md:127-158,212-297)
• Doc says:
  • Method 1: "source .env ... makes all variables ... available to subsequent commands".
  • Method 2: env $(cat .env | xargs) xtrabackup ... | xbcloud put ....
• What happened:
  • Both methods fail with xbcloud: S3 access key is not specified. Sourced variables are not exported, and env only applies to the left side of the pipe.
  • Method 3 (set -a) works.
  • /secure/path does not exist.
• Fix:
  • Method 1: set -a; source .env; set +a, or export on every line.
  • Method 2: xtrabackup ... | env $(xargs < .env) xbcloud put ....
  • Add mkdir -p -m 700 /secure/path.
  • Add pipefail checks (see D3).

D34. xbcloud restore examples extract into /tmp, which is a 2 GB RAM-backed tmpfs on Ubuntu 26.04

• Severity: High
• Series: 8.4
• Pages: 8.4/xbcloud-binary-overview (8.4:xbcloud-binary-overview.md:94-101,334-350)
• What happened:
  • The full backup (1.7 GB) fit. The incremental then failed: xbstream: Error writing file './xtrabackup_logfile' (OS errno 28 - No space left on device), and the final prepare failed.
  • xbstream -C on a missing directory fails with Can't change dir ... (OS errno 2).
• Fix:
  • Use disk paths (/data/restore, /data/inc1) and mkdir -p in every example.
  • Add the note: "Do not extract backups into /tmp: on Ubuntu 25.04+, Fedora and RHEL 10, /tmp is a RAM-backed tmpfs."

D39. xbcloud backoff: "Could not connect" is not retried by default, and orphaned objects are left behind

• Severity: Medium
• Series: 8.4
• Pages: 8.4/xbcloud-exbackoff (8.4:xbcloud-exbackoff.md:28-66)
• What happened:
  • A MinIO restart during the upload gave 11 "Could not connect to server" errors and "Upload failed." within 3 s, with no retry. 57 orphaned objects were left in the bucket.
  • With --curl-retriable-errors=7, the upload survived the same outage and restored exactly.
  • The sample paths contain an unrendered {{vers}}, and the option names use en dashes.
• Fix:
  • Add: "a restarting endpoint returns curl error 7, which is not retried by default; add --curl-retriable-errors=7 (and e.g. --http-retriable-errors=502)."
  • Add: "a failed upload leaves partial objects; remove them with xbcloud delete <name> before reusing the name."

D62. Reference pages for xbcloud, xbstream and xbcrypt have wrong option names and syntax

• Severity: Medium
• Series: 8.4
• Pages:
  • 8.4/xbcloud-options
  • xbcrypt-options (:5,18-62) and xbcrypt-binary-overview (:9)
  • xbstream-options (:31,81,120-123) and xbstream-binary-overview (:3,11,17)
  • xbcloud-binary-overview (:180-183)
  • xbcloud-s3 (:18-26)
• What happened:
  • xbcloud options:
    • --google-bucket-name fails with unknown variable; the real option is --google-bucket.
    • --max-retires is a typo for --max-retries.
    • STANDARD_ID should be STANDARD_IA.
    • --azure-development-storage=name and --md5=name are shown with values, but both are flags.
    • -c/--defaults-file, which must come first, is missing.
  • Google environment variables: GOOGLE_ACCESS_KEY, GOOGLE_SECRET_KEY and GOOGLE_BUCKET_NAME do not exist ("Google bucket is not specified").
  • Undocumented environment variables: AWS_SESSION_TOKEN, AWS_STORAGE_CLASS, S3_*, AZURE_ENDPOINT and OS_* are not listed.
  • xbcrypt:
    • the short option -a=AES256 fails (it is -a AES256);
    • the default chunk size is 64K, not 64000;
    • -t, -r and -V are missing.
  • xbstream:
    • the directory option is -C, not -c (which is --create);
    • -absolute-names should be -P/--absolute-names;
    • --encrypt-threads-=# has a stray dash;
    • "tar format" has been removed;
    • the "command-line options" link goes to the xbcloud page.
  • Rendering: <AUTO|2|4> is swallowed as an HTML tag.
• Fix: correct each item above, and generate these pages from --help.

Found in a hands-on docs audit run with Claude Code.