maxhoesel.proxmox.pbs_client role – Installs and configures the Proxmox backup client on a supported system.

Note

This role is part of the maxhoesel.proxmox collection (version 5.1.1).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: ansible-galaxy collection install maxhoesel.proxmox.

To use it in a playbook, specify: maxhoesel.proxmox.pbs_client.

Entry point main – Installs and configures the Proxmox backup client on a supported system.

Synopsis

  • The client is installed and configured for usage by the root user. Additionally, a backup job can be configured and scheduled.

  • Requirements: - Ubuntu 20.04 or later - Debian 11 or later - Root access via `become: yes` or equivalent

  • NOTE ON ENABLING ENCRYPTION: Before you enable encryption, make sure to familiarize yourself with the way PBS handles encryption keys and passwords (see here). All encryption modes require you to somehow save the encryption keyfile/private key to a separate machine. The backup will become irrecoverable if you do not have a copy of the encryption key!

Parameters

Parameter

Comments

pbs_client_backup_archives

list / elements=string

List of archive specifications as passed to the `backup` subcommand.

An archive specification has the format `name.type:/path`

Common types are `.pxar` and `.img`

Example: ['fs.pxar:/'] will create a file-based pxar archive of the root file system

pbs_client_backup_id

string

Unique ID used to identify this backup group (see here)

If undefined, the PBS default (hostname) is used

pbs_client_configure_backup

boolean

Whether to configure a backup task

If false, the PBS client will be installed with no further configuration done

Choices:

  • false

  • true ← (default)

pbs_client_encryption_mode

string

Select the type of client-side encryption that should be used to encrypt backups on the remote server

Note that this does not affect the backup transport security - PBS always uses TLS connections for transferring your backup.

When set to none, no encryption is used

When set to keyfile, an AES-256 encryption key is generated and saved on the client. This key is used to encrypt every backup archive. Please make sure to backup this keyfile to an external location. You will not be able to restore from backup without this key!. The key is stored without password protection to enable automatic backups.

When set to rsa, a keyfile is generated just as above, but a RSA public key is used to encrypt the backup keyfile, which is then appended to every backup. This allows you to restore from a backup with the private key and without needing to know the AES keyfile. This is especially useful if you want to reuse an existing RSA keypair. Please make sure to keep a copy of the private key corresponding to the public key around. You will not be able to restore from backup without this key!

Choices:

  • "none" ← (default)

  • "keyfile"

  • "rsa"

pbs_client_encryption_pubkey

string

Public RSA key to use for encrypting the backup key

Must be in the string representation generated by PBS (C—–BEGIN PUBLIC KEY—–)…)

pbs_client_fingerprint

string

Fingerprint of the backup servers certificate

Used to verify self-signed certificates, not needed if your backup server has a valid CA certificate that is trusted by the client.

pbs_client_include_mountpoints

list / elements=string

Include the following mountpoints into the backup

Must be a list of paths or all

If set to a list, items must be paths as passed to the --include-dev flag (see here)

If set to all, the --all-file-systems flag will be used to include all mounted filesystems in the path

Default: []

pbs_client_on_error_units

list / elements=string

List of systemd units to be started if the backup task fails

Example: ['mail-notify@i.service']

Default: []

pbs_client_password

string

Password or Token secret to authenticate with when talking to the backup server

pbs_client_repository

string

Repository to backup to

Format: [[username@]server[:port]:]datastore

Example: apps@pbs!mytoken@backuphost.example.org:datastore

pbs_client_schedule

string

Time at which to run the backup job, specified as a systemd time expression

Examples: daily, Mon..Sun 1:30:00 UTC

Default: "daily"

pbs_client_schedule_name

string

Name of the systemd timer and unitfile that will be used to run the backup job

Default: "proxmox-backup-client"

pbs_client_schedule_persistent

boolean

Whether the backup task should be started immediately if the task did not run the previous time, for example because the host was shut down

Choices:

  • false

  • true ← (default)

pbs_client_schedule_randomdelay

integer

Random delay in seconds before the backup actually starts. Useful to prevent bursts of backup traffic from multiple hosts.

Default: 1800

pbs_client_schedule_require_ac

boolean

Whether the backup should be skipped if no AC power is present.

This should work on all modern systems, but it is set to `false` by default just to be sure.

Choices:

  • false ← (default)

  • true

pbs_client_skip_install

boolean

When to true, this role will not attempt to install the backup client and instead just assume that it is already present.

This is useful if you already installed the backup client manually

Choices:

  • false ← (default)

  • true