BARMAN-BACKUP(1)

💖 barman-backup — the Barman sub-commands glow-up 💖

okay bestie, sit down, hydrate, because this is the manual page for barman-backup(1), one of the Barman sub-commands, and honestly? it's giving main character energy. we're gonna walk through every single flag, every default, every warning. no skipping. no cap. 🫶

---

✨ NAME ✨

barman-backup — Barman Sub-Commands

---

🎀 SYNOPSIS 🎀

backup
    [ --bwlimit KBPS ]
    [ --cloud-staging-directory PATH ]
    [ --cloud-staging-max-size SIZE ]
    [ { -h | --help } ]
    [ --incremental BACKUP_ID ]
    [ --immediate-checkpoint ]
    [ { -j | --jobs } PARALLEL_WORKERS ]
    [ --jobs-start-batch-period PERIOD ]
    [ --jobs-start-batch-size SIZE ]
    [ --keepalive-interval SECONDS ]
    [ --manifest ]
    [ --name NAME ]
    [ --no-immediate-checkpoint ]
    [ --no-manifest ]
    [ --no-retry ]
    [ --retry-sleep SECONDS ]
    [ --retry-times NUMBER ]
    [ --reuse-backup { off | copy | link } ]
    [ { --wait | -w } ]
    [ --wait-timeout SECONDS ]
    SERVER_NAME [ SERVER_NAME ... ]

---

🌸 DESCRIPTION 🌸

so basically? this runs a PostgreSQL server backup. Barman will use the parameters specified in the Global and Server configuration files — like, it already knows the vibe from your config, you don't have to re-explain everything.

want backups from every server configured in the Barman node? just say all instead of a server name and it'll go do the rounds. iconic behaviour honestly.

and if you want to be ✨specific✨, you can also list multiple server names in sequence to execute backups for specific servers. one after another, no drama.

---

🦋 PARAMETERS 🦋

• SERVER_NAME — the name of the server in the barman node. that's who we're backing up, bestie.
• --bwlimit — sets the maximum transfer rate in kilobytes per second. a value of 0 means no limit at all, go feral. this setting overrides the bandwidth_limit configuration option.
• --cloud-staging-directory — a staging directory for when you're sending backups to a cloud object storage using backup_method = postgres. it's the temporary hangout spot where chunks of the backup chill before they get sent to the cloud. defaults to /tmp/barman/cloud-staging.
• --cloud-staging-max-size — the maximum size that --cloud-staging-directory can grow to before Barman stops generating new backup chunks. this exists to stop the staging directory from ballooning if uploading chunks can't keep up with the speed of streaming them from Postgres. the default value is 30Gi.

extremely low values are discouraged because they may lead to performance degradation. we recommend a minimum of at least 10Gi. the optimal value will depend on the transfer speed of the backup to Barman and from Barman to the cloud, as well as the size of the backup. basically: it depends, don't be chaotic about it.

the accepted format is n{k|Ki|M|Mi|G|Gi|T|Ti} and it is case-sensitive, where n is an integer greater than zero, with an optional SI or IEC suffix. k stands for kilo with k = 1000, while Ki stands for kilobytes Ki = 1024. the rest of the options have the same reasoning for greater units of measure. math is math 💅

• -h / --help — show a help message and exit. provides information about command usage. your little "wait what do I type again" bestie.
• --incremental — execute a block-level incremental backup. you must provide a BACKUP_ID or a shortcut to a previous backup, which will serve as the parent backup for the incremental backup.

Note: the backup to be and the parent backup must have backup_method=postgres.

• --immediate-checkpoint — forces the initial checkpoint to be executed as soon as possible, overriding any value set for the immediate_checkpoint parameter in the configuration file. no waiting around, we're moving ✨
• -j / --jobs — specify the number of parallel workers to use for copying files during the backup. this setting overrides the parallel_jobs parameter if it's specified in the configuration file. multitasking queen.
• --jobs-start-batch-period — specify the time period, in seconds, for starting a single batch of jobs. this value overrides the parallel_jobs_start_batch_period parameter if it is set in the configuration file. the default is 1 second.
• --jobs-start-batch-size — specify the maximum number of parallel workers to initiate in a single batch. this value overrides the parallel_jobs_start_batch_size parameter if it is defined in the configuration file. the default is 10 workers.
• --keepalive-interval — specify an interval, in seconds, for sending a heartbeat query to the server to keep the libpq connection active during a Rsync backup. the default is 60 seconds. a value of 0 disables the heartbeat entirely.
• --manifest — forces the creation of a backup manifest file upon completing a backup. overrides the autogenerate_manifest parameter from the configuration file. applicable only to rsync backup strategy.
• --name — specify a friendly name for this backup which can be used in place of the backup ID in barman commands. nicknames!! we love a nickname 🥰
• --no-immediate-checkpoint — forces the backup to wait for the checkpoint to be executed, overriding any value set for the immediate_checkpoint parameter in the configuration file. the opposite energy of --immediate-checkpoint, as you may have clocked.
• --no-manifest — disables the automatic creation of a backup manifest file upon completing a backup. this setting overrides the autogenerate_manifest parameter from the configuration file and applies only to rsync backup strategy.
• --no-retry — there will be no retry in case of an error. it is the same as setting --retry-times 0. one shot, one opportunity.
• --retry-sleep — specify the number of seconds to wait after a failed copy before retrying. this setting applies to both backup and recovery operations and overrides the basebackup_retry_sleep parameter if it is defined in the configuration file.
• --retry-times — specify the number of times to retry the base backup copy in case of an error. this applies to both backup and recovery operations and overrides the basebackup_retry_times parameter if it is set in the configuration file.
• --reuse-backup — overrides the behavior of the reuse_backup option configured in the configuration file. the possible values are:
  • off: do not reuse the last available backup.
  • copy: reuse the last available backup for a server and create copies of unchanged files (reduces backup time).
  • link (default): reuse the last available backup for a server and create hard links to unchanged files (saves both backup time and space).

Note: this will only have any effect if the last available backup was executed with backup_method=rsync.

• --wait / -w — wait for all necessary WAL files required by the base backup to be archived. patience, babe.
• --wait-timeout — specify the duration, in seconds, to wait for the required WAL files to be archived before timing out. the clock is ticking ⏰

---

💅 SHORTCUTS 💅

use shortcuts instead of SERVER_NAME. they're the cheat codes, iykyk.

• all — all available servers.

---

👑 Author 👑

EnterpriseDB

---

🌈 Copyright 🌈

© Copyright EnterpriseDB UK Limited 2011-2026

---

okay that's the whole page, you ate that fr fr 💖 this was Barman version 3.20, dated Sep 29, 2026 — go forth and back up your databases, bestie. periodt. 🦋✨