Operations
Suggest editsPrerequisites
You can ask Barman to perform operations on upstream servers. If you plan to use that feature, the following setup is expected:
- Postgres backup API (pg-backup-api) must be installed on the same server as Barman. Please check How to install Postgres backup API if you haven't done it already.
- SSH passwordless login must be in place among the different hosts.
- Ownership of destination directory or write permissions must be granted to the user Barman will be connecting as to the Postgres nodes.
- For security reasons, the API will listen to on localhost only. You need to use some proxy to forward the traffic. The Apache http server was used during our tests. Please read our notes about how to define a virtual host.
Available endpoints
- Instance level operations:
/operations/
/operations/OPERATION_ID
- Server level operations:
/servers/NAME/operations/
/servers/NAME/operations/OPERATION_ID
NAME
is an available Barman server configuration. Usually in a file like /etc/barman.d/myserver.conf
OPERATION_ID
is a short string that represents the ID of an operation created by the API.
You can find out how to fetch operations created by the API below
Available operations
GET: /operations
Returns all instance level tasks created by the API, if any.
POST: /operations
Request pg-backup-api to create instance level operations.
Currently pg-backup-api supports only the config_update
operation.
Note
You need to set the content-type
header as application/json
when executing POST
requests to this endpoint, otherwise you will receive a 400 Bad Request error
.
config_update
This operation is used to request a remote execution of barman config-update
command.
The JSON payload of the request must contain the following keys:
type
: set asconfig_update
to request that operationchanges
: an array of documents in JSON format to be used as an argument forbarman config-update
As an example, you could request pg-backup-api to update the configuration of a couple of Barman servers plus a Barman model with a payload like this:
Assume the above JSON content is stored in a file named payload-pg-backup-api.json
, you could issue a request to the API using curl
in the following way:
The operation_id
in the response is the ID of the operation that has been created in by the API.
GET: /operations/OPERATION_ID
This endpoint allows you to check the status of an instance level operation with ID OPERATION_ID
, which can be either of these:
DONE
: if the operation finished successfullyFAILED
: if the operation finished with errorsIN_PROGRESS
: if the operation is still ongoingPlease find an example below:
GET: /servers/NAME/operations
Returns all server level tasks created by the API for Barman server NAME
, if any.
The following example shows the two tasks created on the my-barman-server
Barman server.
POST: /servers/NAME/operations
Request pg-backup-api to create server level operations.
Currently pg-backup-api supports recovery
and config_switch
operations.
Note
You need to set the content-type
header as application/json
when executing POST
requests to this endpoint, otherwise you will receive a 400 Bad Request error
.
recovery
This operation is used to request a remote execution of barman recover
command.
The JSON payload of the request must contain the following keys:
type
: set asrecovery
to request that operation;backup_id
: ID of the backup to be restored from Barman serverNAME
. You could use Barman shortcuts or anything thatbarman recover
supports, includinglatest
for example;remote_ssh_command
: the SSH command to be used to connect to the target Postgres server where the backup will be restored;destination_directory
: the path in the target server where the backup will be restored.
As an example, you could request pg-backup-api to restore the latest backup of Barman server db_server_two
with a payload like this:
The operation_id
in the response is the ID of the operation that has been created in by the API.
config_switch
This operation is used to request a remote execution of barman config-switch
command.
The JSON payload of the request must contain the following key:
type
: set asconfig_switch
to request that operation.
Besides that, it may contain either of the following keys:
model_name
: the name of a model, if you want to apply it to the Barman serverNAME
; orreset
: set withtrue
if you want to unapply the currently active model of the Barman serverNAME
As an example, you could request pg-backup-api to apply the model my-model
to the Barman server with a payload like this:
The operation_id
in the response is the ID of the operation that has been created in by the API.
GET: /servers/NAME/operations/OPERATION_ID
This endpoint allows you to check the status of a server level operation for server NAME
with ID OPERATION_ID
, which can be either of these:
DONE
: if the operation finished successfullyFAILED
: if the operation finished with errorsIN_PROGRESS
: if the operation is still ongoingPlease find an example below:
Could this page be better? Report a problem or suggest an addition!