.. _hook-scripts: Hook Scripts ============ Barman allows :term:`DBAs ` to run hook scripts during specific events: * :ref:`Before and after creating a backup `. * :ref:`Before and after deleting a backup `. * :ref:`Before and after a WAL file is archived `. * :ref:`Before and after a WAL file is deleted `. * :ref:`Before and after restoring a backup `. .. important:: These scripts can be configured using the global options, which can be overridden for individual servers. Deletion and recovery hook scripts were introduced in ``version 2.4``. There are two types of hook scripts that Barman can manage: * **Standard Hook Scripts**: These scripts are executed once and do not have their return codes checked. * **Retry Hook Scripts**: These scripts might be executed multiple times, depending on their return codes. When executing a retry hook script, Barman checks the return code and will continue to retry the script until it returns one of the following: * ``SUCCESS`` (standard return code ``0``) * ``ABORT_CONTINUE`` (return code ``62``) * ``ABORT_STOP`` (return code ``63``) Any other return code is treated as a transient failure, prompting Barman to retry the script. This gives users greater control, allowing hook scripts to determine if a failure should be considered transient. Additionally, for a pre-hook script, returning ``ABORT_STOP`` allows users to request that Barman interrupts the main operation with a failure. Hook scripts are executed in the following sequence (skipped if not present): 1. **Standard pre hook script**. 2. **Retry pre hook script**. 3. **Main event** (backup operation, restore operation or WAL archiving), unless the retry pre hook script was aborted with ``ABORT_STOP``. 4. **Retry post hook script**. 5. **Standard post hook script**. All output generated by hook scripts is logged in Barman's log file.. .. note:: Currently, ``ABORT_STOP`` is ignored by retry post-hook scripts. In such cases, this will result in logging an additional warning, and ``ABORT_STOP`` will behave the same as ``ABORT_CONTINUE``. .. _hook-scripts-before-and-after-creating-a-backup: Before and after creating a backup ---------------------------------- * ``pre_backup_script``: A hook script executed once before a base backup, without checking the exit code. * ``pre_backup_retry_script``: A retry hook script executed before a base backup, running repeatedly until it succeeds or is aborted. * ``post_backup_retry_script``: A retry hook script executed after a base backup, running repeatedly until it succeeds or is aborted. * ``post_backup_script``: A hook script executed once after a base backup, without checking the exit code. The shell environment will include the following variables for **backup scripts**: * ``BARMAN_BACKUP_DIR``: The destination directory for the backup. * ``BARMAN_BACKUP_ID``: The ID of the backup. * ``BARMAN_CONFIGURATION``: The configuration file used by Barman. * ``BARMAN_ERROR``: Any error message (only applicable in the ``post`` phase). * ``BARMAN_PHASE``: Indicates the phase of the script, either ``pre`` or ``post``. * ``BARMAN_PREVIOUS_ID``: The ID of the previous backup, if available. * ``BARMAN_RETRY``: Set to ``1`` if it is a retry script; otherwise, it is ``0``. * ``BARMAN_SERVER``: The name of the server. * ``BARMAN_STATUS``: The status of the backup. * ``BARMAN_VERSION``: The version of Barman. .. _hook-scripts-before-and-after-deleting-a-backup: Before and after deleting a backup ---------------------------------- * ``pre_delete_script``: A hook script triggered once before the backup deletion, with no exit code check. * ``pre_delete_retry_script``: A retry hook script that runs before the backup deletion, executing repeatedly until it succeeds or is aborted. * ``post_delete_retry_script``: A retry hook script that runs after the backup deletion, executing repeatedly until it succeeds or is aborted. * ``post_delete_script``: A hook script triggered once after the backup deletion, with no exit code check. **Delete scripts** utilize the same environmental variables as **backup scripts**, plus: ``BARMAN_NEXT_ID``: The ID of the next backup, if available. .. _hook-scripts-before-and-after-a-WAL-file-is-archived: Before and after a WAL is archived ---------------------------------- * ``pre_archive_script``: A hook script that runs once before a WAL file is archived by maintenance (typically via Barman cron), without checking the exit code. * ``pre_archive_retry_script``: A retry hook script that executes before a WAL file is archived by maintenance, running repeatedly until it succeeds or is aborted. * ``post_archive_retry_script``: A retry hook script that executes after a WAL file is archived by maintenance, running repeatedly until it succeeds or is aborted. * ``post_archive_script``: A hook script that runs once after a WAL file is archived by maintenance, without checking the exit code. **WAL archive scripts** share several environmental variables with **backup scripts**: * ``BARMAN_CONFIGURATION``: The configuration file used by Barman. * ``BARMAN_ERROR``: Any error message generated (only for the post phase). * ``BARMAN_PHASE``: The phase of the script, either pre or post. * ``BARMAN_SERVER``: The name of the server. Additionally, the following variables are specific to **WAL archive scripts**: * ``BARMAN_SEGMENT``: The name of the WAL file. * ``BARMAN_FILE``: The full path of the WAL file. * ``BARMAN_SIZE``: The size of the WAL file. * ``BARMAN_TIMESTAMP``: The timestamp of the WAL file. * ``BARMAN_COMPRESSION``: The type of compression applied to the WAL file. .. _hook-scripts-before-and-after-a-WAL-file-is-deleted: Before and after a WAL file is deleted -------------------------------------- * ``pre_wal_delete_script``: A hook script that runs before a WAL file is deleted. * ``pre_wal_delete_retry_script``: A retry hook script that executes before the deletion of a WAL file, running repeatedly until it succeeds or is aborted. * ``post_wal_delete_retry_script``: A retry hook script that runs after a WAL file is deleted, executing repeatedly until it succeeds or is aborted. * ``post_wal_delete_script``: A hook script that runs after a WAL file is deleted. **WAL delete scripts** utilize the same environmental variables as **WAL archive scripts**. .. _hook-scripts-before-and-after-restoring-a-backup: Before and after restoring a backup ----------------------------------- * ``pre_recovery_script``: A hook script that runs once before a backup restore, without checking the exit code. * ``pre_recovery_retry_script``: A retry hook script that executes before a backup restore, running repeatedly until it succeeds or is aborted. * ``post_recovery_retry_script``: A retry hook script that runs after a backup restore, executing repeatedly until it succeeds or is aborted. * ``post_recovery_script``: A hook script that runs once after a backup restore, without checking the exit code. **Recovery scripts** utilize the same environmental variables as **backup scripts**, plus: * ``BARMAN_DESTINATION_DIRECTORY``: The directory where the new instance is restored. * ``BARMAN_TABLESPACES``: The tablespace relocation map (in JSON format, if applicable). * ``BARMAN_REMOTE_COMMAND``: The secure shell command used during restore (if applicable). * ``BARMAN_RECOVER_OPTIONS``: Additional recovery options (in JSON format, if applicable). .. _hook-scripts-using-barman-cloud-scripts-as-hooks-in-barman: Using ``barman-cloud-*`` scripts as hooks in barman --------------------------------------------------- Follow the process in the :ref:`installation section ` to start using the :ref:`barman-cloud commands `. .. note:: For detailed information on configuration options, refer to the :ref:`configuration ` section. You can use ``barman-cloud-backup`` as a ``post-backup script`` for the following Barman backup types: * Backups created with ``backup_method = rsync``. * Backups created with ``backup_method = postgres`` when ``backup_compression`` is not applied. To configure this, add the following line to your server configuration in Barman: .. code-block:: text post_backup_retry_script = barman-cloud-backup [ OPTIONS ] DESTINATION_URL SERVER_NAME .. warning:: When used as a hook script, ``barman-cloud-backup`` requires the backup status to be ``DONE``. It will fail if the backup has any other status. To avoid issues, it is recommended to run backups with the ``-w`` / ``--wait`` option to ensure the hook script is not executed while the backup status is ``WAITING_FOR_WALS``. Additionally, set up ``barman-cloud-wal-archive`` as a pre-WAL archive script by adding the following line to the Barman configuration for your Postgres server: .. code-block:: text pre_archive_retry_script = barman-cloud-wal-archive [ OPTIONS ] DESTINATION_URL SERVER_NAME