BARMAN-CLOUD-BACKUP(1)

📦
version 3.20.1 · 10 versions
, in epel 10, fedora 43, fedora 44

💖 NAME 💖

barman-cloud-backup — Barman-cloud Commands

okay so bestie, welcome to the BARMAN-CLOUD-BACKUP(1) page, part 1 of 2, and it's giving absolute banger 🌈✨

📜 Synopsis 📜

here's the whole vibe in one block, literally every flag, no notes:

barman-cloud-backup
                [ { -V | --version } ]
                [ --help ]
                [ { { -v | --verbose } | { -q | --quiet } } ]
                [ { -t | --test } ]
                [ --cloud-provider { aws-s3 | azure-blob-storage | google-cloud-storage } ]
                [ { { -z | --gzip } | { -j | --bzip2 } | --snappy | --lz4 | --zstd } ]
                [ { -h | --host } HOST ]
                [ { -p | --port } PORT ]
                [ { -U | --user } USER ]
                [ { -d | --dbname } DBNAME ]
                [ { -n | --name } BACKUP_NAME ]
                [ { -J | --jobs } JOBS ]
                [ { -S | --max-archive-size } MAX_ARCHIVE_SIZE ]
                [ --immediate-checkpoint ]
                [ --min-chunk-size MIN_CHUNK_SIZE ]
                [ --max-bandwidth MAX_BANDWIDTH ]
                [ --keepalive-interval KEEPALIVE_INTERVAL ]
                [ --snapshot-instance SNAPSHOT_INSTANCE ]
                [ --snapshot-disk NAME [ --snapshot-disk NAME ... ] ]
                [ --snapshot-zone GCP_ZONE ]
                [ -snapshot-gcp-project GCP_PROJECT ]
                [ --tag KEY,VALUE [ --tag KEY,VALUE ... ] ]
                [ --endpoint-url ENDPOINT_URL ]
                [ --addressing-style { auto | virtual | path } ]
                [ { -P | --aws-profile } AWS_PROFILE ]
                [ --profile AWS_PROFILE ]
                [ --read-timeout READ_TIMEOUT ]
                [ { -e | --encryption } { AES256 | aws:kms } ]
                [ --sse-kms-key-id SSE_KMS_KEY_ID ]
                [ --sse-customer-key SSE_CUSTOMER_KEY ]
                [ --aws-region AWS_REGION ]
                [ --aws-await-snapshots-timeout AWS_AWAIT_SNAPSHOTS_TIMEOUT ]
                [ --aws-snapshot-lock-mode { compliance | governance } ]
                [ --aws-snapshot-lock-duration DAYS ]
                [ --aws-snapshot-lock-cool-off-period HOURS ]
                [ --aws-snapshot-lock-expiration-date DATETIME ]
                [ { --azure-credential | --credential } { azure-cli | managed-identity | default } ]
                [ --encryption-scope ENCRYPTION_SCOPE ]
                [ --azure-subscription-id AZURE_SUBSCRIPTION_ID ]
                [ --azure-resource-group AZURE_RESOURCE_GROUP ]
                [ --gcp-project GCP_PROJECT ]
                [ --kms-key-name KMS_KEY_NAME ]
                [ --gcp-zone GCP_ZONE ]
                DESTINATION_URL SERVER_NAME

🌸 Description 🌸

so like, barman-cloud-backup is that girl 💅 — it takes a local backup of a Postgres server and yeets it straight to a supported cloud provider, bypassing the Barman server entirely. main character energy, no middleman. It can also be used as a hook script for copying Barman backups from the Barman server over to one of the supported clouds, specifically as a post_backup_retry_script. versatile queen ✨

this script needs read access to PGDATA and tablespaces, and it's typically run as the postgres user. When you're using it on a Barman server, it needs read access to the directory where Barman backups live. And if --snapshot-arguments are used and snapshots are supported by the cloud provider you picked, then the backup gets performed using snapshots of the specified disks (--snapshot-disk). The backup label and metadata also get uploaded to the cloud, because of course they do 🎀

Note: for GCP, only authentication with the GOOGLE_APPLICATION_CREDENTIALS env is supported. And if you wanna use an alternative GCP universe (e.g. S3NS/T-Systems), set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to the desired universe domain. iykyk 🦋
Important: the cloud upload may fail if any file larger than the configured --max-archive-size is present in the data directory or tablespaces. BUT — Postgres files up to 1GB are always allowed, regardless of the --max-archive-size setting. so don't panic, it's not a free-for-all, but it's also not as strict as it sounds 🫶

🎀 Parameters 🎀

the positional girlies (put these last, fr fr)

  • SERVER_NAME — name of the server to be backed up. that's the one, that's the whole vibe.
  • DESTINATION_URL — URL of the cloud destination, like a bucket in AWS S3. for example: s3://bucket/path/to/folder. yes, that exact shape.

🌟 the options 🌟

  • -V, --version — show version and exit. short and sweet.
  • --help — show this help message and exit. we love a self-aware king.
  • -v, --verbose — increase output verbosity (e.g., -vv is more than -v). more vs, more tea ☕
  • -q, --quiet — decrease output verbosity (e.g., -qq is less than -q). shhh, we're being mysterious 🤫
  • -t, --test — test cloud connectivity and exit. vibe check on your bucket ✨
  • --cloud-provider — the cloud provider to use as a storage backend.

Allowed options:

  • aws-s3.
  • azure-blob-storage.
  • google-cloud-storage.
  • -z, --gzip — gzip-compress the backup while uploading to the cloud (should not be used with python < 3.2). okay periodt, but read the parenthetical.
  • -j, --bzip2 — bzip2-compress the backup while uploading to the cloud (should not be used with python < 3.3).
  • --snappy — snappy-compress the backup while uploading to the cloud (requires the optional python-snappy library).
  • --lz4 — lz4-compress the backup while uploading to the cloud (requires the optional lz4 Python library).
  • --zstd — zstd-compress the backup while uploading to the cloud (requires the optional zstandard Python library).
  • -h, --host — host or Unix socket for the Postgres connection (default: libpq settings).
  • -p, --port — port for the Postgres connection (default: libpq settings).
  • -U, --user — user name for the Postgres connection (default: libpq settings).
  • -d, --dbname — database name or conninfo string for the Postgres connection (default: "postgres").
  • -n, --name — a name which can be used to reference this backup in commands such as barman-cloud-restore and barman-cloud-backup-delete. name your child so you can find it later 💖
  • -J, --jobs — number of subprocesses to upload data to cloud storage (default: 2).
  • -S, --max-archive-size — maximum size of an archive when uploading to cloud storage (default: 100GB).
  • --immediate-checkpoint — forces the initial checkpoint to be done as quickly as possible. no waiting around, we're on go 🏃‍♀️
  • --min-chunk-size — minimum size of an individual chunk when uploading to cloud storage (default: 5MB for aws-s3, 64KB for azure-blob-storage, not applicable for google-cloud-storage).
  • --max-bandwidth — the maximum amount of data to be uploaded per second when backing up to object storages (default: 0 — no limit).
  • --keepalive-interval — an interval, in seconds, at which a heartbeat query is sent to the PostgreSQL server to keep the connection alive during the upload phase (default: 60). A value of 0 disables the heartbeat. keeping the connection alive, keeping the relationship alive 🫶
  • --snapshot-instance — instance where the disks to be backed up as snapshots are attached.
  • --snapshot-disk — name of a disk from which snapshots should be taken.
  • --tag — tag to be added to all uploaded files in cloud storage, and/or to snapshots created, if snapshots are used.
  • --tags — tags to be added to all uploaded files in cloud storage, and/or to snapshots created, if snapshots are used.
Note: if you are using --tags before positional arguments, you must insert -- after it to indicate the end of optional arguments. This tells the parser to treat everything after -- as positional arguments. Without the --, Barman may misinterpret positional arguments as values for the last option. so literally just add the --, bestie, it's two characters, save yourself 😭
Deprecated since version 3.15: --tags is deprecated. Use --tag instead. she's retiring, let her rest 💀

🔥 Extra options for the AWS cloud provider 🔥

  • --endpoint-url — override the default S3 endpoint URL with the given one.
  • --addressing-style — the addressing style to use for S3 requests. This is useful when connecting to S3-compatible services that require a specific addressing style.

Allowed options are:

  • auto (default): uses the addressing style determined by the underlying library.
  • virtual: uses virtual-hosted style addressing (e.g., bucket-name.s3.amazonaws.com).
  • path: uses path-style addressing (e.g., s3.amazonaws.com/bucket-name).
  • -P, --aws-profile — profile name (e.g. INI section in AWS credentials file).
  • --profile (deprecated) — profile name (e.g. INI section in AWS credentials file) — replaced by --aws-profile.
  • --read-timeout — the time in seconds until a timeout is raised when waiting to read from a connection (defaults to 60 seconds).
  • -e, --encryption — the encryption algorithm used when storing the uploaded data in S3.

Allowed options:

  • AES256.
  • aws:kms.
  • --sse-kms-key-id — the AWS KMS key ID that should be used for encrypting the uploaded data in S3. Can be specified using the key ID on its own or using the full ARN for the key. Only allowed if -e / --encryption is set to aws:kms.
  • --sse-customer-key — the customer-provided encryption key (SSE-C) to use for encrypting and decrypting data in S3. The value must be a file:// URI pointing to a file containing a base64-encoded 256-bit (32-byte) key (e.g. file:///etc/barman/sse-c.b64). Cannot be used together with --sse-kms-key-id or -e / --encryption.
Important: all backups and WAL files for a given server must be encrypted with the same SSE-C key. Mixing SSE-C-encrypted and unencrypted objects, or using different keys across backups, will cause barman commands to fail when S3 rejects requests with a mismatched or missing key. this is the "no take-backs" rule, do not test it 😭
  • --aws-region — the name of the AWS region containing the EC2 VM and storage volumes defined by the --snapshot-instance and --snapshot-disk arguments.
  • --aws-await-snapshots-timeout — the length of time in seconds to wait for snapshots to be created in AWS before timing out (default: 3600 seconds).
  • --aws-snapshot-lock-mode — the lock mode for the snapshot. This is only valid if --snapshot-instance and --snapshot-disk are set.

Allowed options:

  • compliance.
  • governance.
  • --aws-snapshot-lock-duration — the lock duration is the period of time (in days) for which the snapshot is to remain locked, ranging from 1 to 36,500. Set either the lock duration or the expiration date (not both).

🌙 and that's part 1, keep scrolling because there is literally so much more 💜

  • --aws-snapshot-lock-cool-off-period — okay so this one is the optional cooling-off period, and it's measured in hours 💅. You only get to use it when you're locking a snapshot in compliance mode, and the range is 1 to 72. That's it, that's the whole vibe.
  • --aws-snapshot-lock-expiration-date — instead of a duration, you tell it when the lock ends, using an expiration date in the future. It has to be at least 1 day after the snapshot creation date and time, and the format is YYYY-MM-DDTHH:MM:SS.sssZ — yes bestie, that exact format, don't freestyle it 🙈.
🚨 Real talk: set either the lock duration or the expiration date. Not both. Pick a lane, periodt.

🫶 Extra options for the Azure cloud provider 🫶

  • --azure-credential / --credential — you can optionally tell it which type of credential to use when authenticating with Azure. But if you don't? Then Azure Blob Storage credentials get pulled from the environment and the default Azure authentication flow handles authenticating with all the other Azure services. And if the environment has no credentials at all, then the default Azure authentication flow gets used for Azure Blob Storage too. It's giving "we'll figure it out" ✨

The allowed options, bestie:

  • azure-cli.
  • managed-identity.
  • default.
  • --encryption-scope — the name of an encryption scope defined in the Azure Blob Storage service, which is what gets used to encrypt your data in Azure 🔐. Fancy.
  • --azure-subscription-id — the ID of the Azure subscription that owns the instance and storage volumes defined by the --snapshot-instance and --snapshot-disk arguments. Gotta tell it whose stuff this is 💖
  • --azure-resource-group — the name of the Azure resource group that the compute instance and disks defined by the --snapshot-instance and --snapshot-disk arguments belong to. Same energy, different container 🎀

🌈 Extra options for GCP cloud provider 🌈

  • --gcp-project — the GCP project under which disk snapshots should be stored. That's the one you want, queen 👑
  • --snapshot-gcp-project (deprecated) — GCP project under which disk snapshots should be stored — but heads up, this one got replaced by --gcp-project. Still documented, still here, but it's the old thing 💀
  • --kms-key-name — the name of the GCP KMS key that should be used for encrypting the uploaded data in GCS 🔒. Keep your stuff cute and locked.
  • --gcp-zone — zone of the disks from which snapshots should be taken. Location matters, bestie 🌍
  • --snapshot-zone (deprecated) — zone of the disks from which snapshots should be taken — replaced by --gcp-zone. Same deprecated-girlie situation as above, no cap.

✍️ Author ✍️

EnterpriseDB

© Copyright EnterpriseDB UK Limited 2011-2026

And that's the whole page, bestie 🫶✨ This was version 3.20, dated Sep 29, 2026, and it's the BARMAN-CLOUD-BACKUP(1) manual page — go back up to part 1 if you skipped it, and slay your backups 💖🎀🦋

📦 where this page comes from