Configuration Files¶

All Proxmox Backup Server configuration files reside in the directory /etc/proxmox-backup/.

`acl.cfg`¶

File Format¶

This file contains the access control list for the Proxmox Backup Server API.

Each line starts with acl:, followed by 4 additional values separated by colon.

propagate:: Propagate permissions down the hierarchy
path:: The object path
User/Token:: List of users and tokens
Role:: List of assigned roles

Here is an example list:

acl:1:/:root@pam!test:Admin
acl:1:/datastore/store1:user1@pbs:DatastoreAdmin

You can use the proxmox-backup-manager acl command to manipulate this file.

Roles¶

The following roles exist:

Admin:: Administrator
Audit:: Auditor
NoAccess:: Disable Access
DatastoreAdmin:: Datastore Administrator
DatastoreReader:: Datastore Reader (inspect datastore content and do restores)
DatastoreBackup:: Datastore Backup (backup and restore owned backups)
DatastorePowerUser:: Datastore PowerUser (backup, restore and prune owned backup)
DatastoreAudit:: Datastore Auditor
RemoteAudit:: Remote Auditor
RemoteAdmin:: Remote Administrator
RemoteSyncOperator:: Synchronization Operator
RemoteSyncPushOperator:: Synchronisation Operator (push direction)
RemoteDatastorePowerUser:: Remote Datastore Prune
RemoteDatastoreAdmin:: Remote Datastore Admin
TapeAudit:: Tape Auditor
TapeAdmin:: Tape Administrator
TapeOperator:: Tape Operator
TapeReader:: Tape Reader

`datastore.cfg`¶

File Format¶

This file contains a list of datastore configuration sections. Each section starts with the header datastore: <name>, followed by the datastore configuration options.

datastore: <name1>
   path <path1>
   <option1> <value1>
   ...

datastore: <name2>
   path <path2>
   ...

You can use the proxmox-backup-manager datastore command to manipulate this file.

Options¶

Required properties:

path<string>: Either the absolute path to the datastore directory, or a relative on-device path for removable datastores.

Optional properties:

backing-device<string>

The UUID of the filesystem partition for removable datastores.

comment<string>

Comment.

gc-schedule<calendar-event>

Run garbage collection job at specified schedule.

maintenance-mode[type=<enum> [,message=<string>]]

Maintenance mode, type is either 'offline' or 'read-only', message should be enclosed in " type = read-only|offline|delete|unmount

Maintenance type.

message = <string>: Message describing the reason for the maintenance.

notification-modelegacy-sendmail|notification-system (default=legacy-sendmail)

Configure how notifications for this datastore should be sent. legacy- sendmail sends email notifications to the user configured in notify-user via the system's sendmail executable. notification-system emits matchable notification events to the notification system.

notify[[gc=<enum>] [,prune=<enum>] [,sync=<enum>] [,verify=<enum>]]

Datastore notification setting, enum can be one of 'always', 'never', or 'error'. gc = never|always|error

When do we send notifications

prune = never|always|error: When do we send notifications
sync = never|always|error: When do we send notifications
verify = never|always|error: When do we send notifications

notify-user<string>

User ID

prune-schedule<calendar-event>

Run prune job at specified schedule.

tuning[[chunk-order=<enum>] [,sync-level=<enum>]]

Datastore tuning options chunk-order = none|inode (default=inode): The order to sort chunks by
sync-level = none|file|filesystem (default=filesystem): The level of syncing that is done when writing into a datastore.

verify-new<boolean>

If enabled, all new backups will be verified right after completion.

keep-daily<integer> (1 - N)

Number of daily backups to keep.

keep-hourly<integer> (1 - N)

Number of hourly backups to keep.

keep-last<integer> (1 - N)

Number of backups to keep.

keep-monthly<integer> (1 - N)

Number of monthly backups to keep.

keep-weekly<integer> (1 - N)

Number of weekly backups to keep.

keep-yearly<integer> (1 - N)

Number of yearly backups to keep.

`domains.cfg`¶

File Format¶

This file contains the list authentication realms.

Each user configuration section starts with the header <realm-type>: <name>, followed by the realm's configuration options.

For LDAP realms, the LDAP bind password is stored in ldap_passwords.json.

openid: master
      client-id pbs
      comment
      issuer-url http://192.168.0.10:8080/realms/master
      username-claim username

ldap: ldap-server
      base-dn OU=People,DC=ldap-server,DC=example,DC=com
      mode ldaps
      server1 192.168.0.10
      sync-attributes email=mail
      sync-defaults-options enable-new=0,remove-vanished=acl;entry
      user-attr uid
      user-classes inetorgperson,posixaccount,person,user

You can use the proxmox-backup-manager openid, proxmox-backup-manager ldap and proxmox-backup-manager ad commands to manipulate this file.

Options¶

Section type 'ad': AD realm configuration properties.

Required properties:

server1<string>: AD server address

Optional properties:

base-dn<string>

LDAP Domain

bind-dn<string>

LDAP Domain

capath<string>

CA certificate to use for the server. The path can point to either a file, or a directory. If it points to a file, the PEM-formatted X.509 certificate stored at the path will be added as a trusted certificate. If the path points to a directory, the directory replaces the system's default certificate store at /etc/ssl/certs - Every file in the directory will be loaded as a trusted certificate.

comment<string>

Comment.

filter<string>

Custom LDAP search filter for user sync

modeldap|ldap+starttls|ldaps (default=ldap)

LDAP connection type

port<integer> (0 - 65535)

AD server Port

server2<string>

Fallback AD server address

sync-attributes[[email=<string>] [,firstname=<string>] [,lastname=<string>]]

Comma-separated list of key=value pairs for specifying which LDAP attributes map to which PBS user field. For example, to map the LDAP attribute mail to PBS's email, write email=mail. email = <string>

Name of the LDAP attribute containing the user's email address

firstname = <string>: Name of the LDAP attribute containing the user's first name
lastname = <string>: Name of the LDAP attribute containing the user's last name

sync-defaults-options[[enable-new=<1|0>] [,remove-vanished=<string>]]

sync defaults options enable-new = <boolean>: Enable new users after sync
remove-vanished = [acl|entry|properties, ...]: A semicolon-separated list of things to remove when they or the user vanishes during user synchronization. The following values are possible: entry removes the user when not returned from the sync; properties removes any properties on existing user that do not appear in the source. acl removes ACLs when the user is not returned from the sync.

user-classes[<string>, ...] (default=inetorgperson,posixaccount,person,user)

Comma-separated list of allowed objectClass values for user synchronization. For instance, if user-classes is set to person,user, then user synchronization will consider all LDAP entities where objectClass: person or objectClass: user.

verify<boolean> (default=false)

Verify server certificate

Section type 'ldap': LDAP configuration properties.

Required properties:

base-dn<string>: LDAP Domain
server1<string>: LDAP server address
user-attr<string>: Username attribute. Used to map a userid to LDAP to an LDAP dn.

Optional properties:

bind-dn<string>

LDAP Domain

capath<string>

CA certificate to use for the server. The path can point to either a file, or a directory. If it points to a file, the PEM-formatted X.509 certificate stored at the path will be added as a trusted certificate. If the path points to a directory, the directory replaces the system's default certificate store at /etc/ssl/certs - Every file in the directory will be loaded as a trusted certificate.

comment<string>

Comment.

filter<string>

Custom LDAP search filter for user sync

modeldap|ldap+starttls|ldaps (default=ldap)

LDAP connection type

port<integer> (0 - 65535)

Port

server2<string>

Fallback LDAP server address

sync-attributes[[email=<string>] [,firstname=<string>] [,lastname=<string>]]

Comma-separated list of key=value pairs for specifying which LDAP attributes map to which PBS user field. For example, to map the LDAP attribute mail to PBS's email, write email=mail. email = <string>

Name of the LDAP attribute containing the user's email address

firstname = <string>: Name of the LDAP attribute containing the user's first name
lastname = <string>: Name of the LDAP attribute containing the user's last name

sync-defaults-options[[enable-new=<1|0>] [,remove-vanished=<string>]]

sync defaults options enable-new = <boolean>: Enable new users after sync
remove-vanished = [acl|entry|properties, ...]: A semicolon-separated list of things to remove when they or the user vanishes during user synchronization. The following values are possible: entry removes the user when not returned from the sync; properties removes any properties on existing user that do not appear in the source. acl removes ACLs when the user is not returned from the sync.

user-classes[<string>, ...] (default=inetorgperson,posixaccount,person,user)

Comma-separated list of allowed objectClass values for user synchronization. For instance, if user-classes is set to person,user, then user synchronization will consider all LDAP entities where objectClass: person or objectClass: user.

verify<boolean> (default=false)

Verify server certificate

Section type 'openid': OpenID configuration properties.

Required properties:

client-id<string>: OpenID Client ID
issuer-url<string>: OpenID Issuer Url

Optional properties:

acr-values[<string>, ...]: OpenID ACR List
autocreate<boolean> (default=false): Automatically create users if they do not exist.
client-key<string>: OpenID Client Key
comment<string>: Comment.
prompt<string>: OpenID Prompt
scopes[<string>, ...] (default=email profile): OpenID Scope List
username-claim<string>: Use the value of this attribute/claim as unique user name. It is up to the identity provider to guarantee the uniqueness. The OpenID specification only guarantees that Subject ('sub') is unique. Also make sure that the user is not allowed to change that attribute by himself!

`media-pool.cfg`¶

File Format¶

Each entry starts with the header pool: <name>, followed by the media pool configuration options.

pool: company1
      allocation always
      retention overwrite

pool: ...

You can use the proxmox-tape pool command to manipulate this file.

Options¶

Optional properties:

allocation<string>: Media set allocation policy ('continue', 'always', or a calendar event).
comment<string>: Comment.
encrypt<string>: Tape encryption key fingerprint (sha256).
retention<string>: Media retention policy ('overwrite', 'keep', or time span).
template<string>: Media set naming template (may contain strftime() time format specifications).

`node.cfg`¶

Options¶

The file contains these options:

acme:: The ACME account to use on this node.
acmedomain0:: ACME domain.
acmedomain1:: ACME domain.
acmedomain2:: ACME domain.
acmedomain3:: ACME domain.
acmedomain4:: ACME domain.
http-proxy:: Set proxy for apt and subscription checks.
email-from:: Fallback email from which notifications will be sent.
ciphers-tls-1.3:: List of TLS ciphers for TLS 1.3 that will be used by the proxy. Colon-separated and in descending priority (https://docs.openssl.org/master/man1/openssl-ciphers/). (Proxy has to be restarted for changes to take effect.)
ciphers-tls-1.2:: List of TLS ciphers for TLS <= 1.2 that will be used by the proxy. Colon-separated and in descending priority (https://docs.openssl.org/master/man1/openssl-ciphers/). (Proxy has to be restarted for changes to take effect.)
default-lang:: Default language used in the GUI.
description:: Node description.
task-log-max-days:: Maximum days to keep task logs.

For example:

acme: local
acmedomain0: first.domain.com
acmedomain1: second.domain.com
acmedomain2: third.domain.com
acmedomain3: fourth.domain.com
acmedomain4: fifth.domain.com
http-proxy: internal.proxy.com
email-from: proxmox@mail.com
ciphers-tls-1.3: TLS_AES_128_GCM_SHA256:TLS_AES_128_CCM_8_SHA256:TLS_CHACHA20_POLY1305_SHA256
ciphers-tls-1.2: RSA_WITH_AES_128_CCM:DHE_RSA_WITH_AES_128_CCM
default-lang: en
description: Primary PBS instance
task-log-max-days: 30

You can use the proxmox-backup-manager node command to manipulate this file.

`notifications.cfg`¶

File Format¶

This file contains configuration for notification targets and notification matchers.

Options¶

Section type 'filter': Config for the old filter system - can be removed at some point.

Section type 'gotify': Config for Gotify notification endpoints

Required properties:

server<string>: Gotify Server URL.

Optional properties:

comment<string>: Comment.
disable<boolean>: Disable this target.
filter<string>: Deprecated.
originuser-created|builtin|modified-builtin: The origin of a notification configuration entry.

Section type 'group': Config for the old target groups - can be removed at some point.

Section type 'matcher': Config for Sendmail notification endpoints

Optional properties:

comment<string>: Comment.
disable<boolean>: Disable this matcher.
invert-match<boolean>: Invert match of the whole filter.
match-calendar<string>: List of matched severity levels. Can be specified more than once.
match-field<string>: List of matched metadata fields. Can be specified more than once.
match-severity<string>: List of matched severity levels. Can be specified more than once.
modeall|any (default=all): The mode in which the results of matches are combined.
originuser-created|builtin|modified-builtin: The origin of a notification configuration entry.
target<string>: Targets to notify. Can be specified more than once.

Section type 'sendmail': Config for Sendmail notification endpoints

Optional properties:

author<string>: Author of the mail. Defaults to 'Proxmox Backup Server ($hostname)'
comment<string>: Comment.
disable<boolean>: Disable this target.
filter<string>: Deprecated.
from-address<string>: From address for sent E-Mails. If the parameter is not set, the plugin will fall back to the email-from setting from node.cfg (PBS). If that is also not set, the plugin will default to root@$hostname, where $hostname is the hostname of the node.
mailto<string>: Mail address to send a mail to. Can be specified more than once.
mailto-user<string>: Users to send a mail to. The email address of the user will be looked up in users.cfg. Can be specified more than once.
originuser-created|builtin|modified-builtin: The origin of a notification configuration entry.

Section type 'smtp': Config for Sendmail notification endpoints

Required properties:

from-address<string>: From address for the mail. SMTP relays might require that this address is owned by the user in order to avoid spoofing. The From header in the email will be set to $author <$from-address>.
server<string>: Host name or IP of the SMTP relay.

Optional properties:

author<string>: Author of the mail. Defaults to 'Proxmox Backup Server ($hostname)'
comment<string>: Comment.
disable<boolean>: Disable this target.
mailto<string>: Mail address to send a mail to. Can be specified more than once.
mailto-user<string>: Users to send a mail to. The email address of the user will be looked up in users.cfg. Can be specified more than once.
modeinsecure|starttls|tls (default=tls): Connection security
originuser-created|builtin|modified-builtin: The origin of a notification configuration entry.
port<integer> (0 - 65535): The port to connect to. If not set, the used port defaults to 25 (insecure), 465 (tls) or 587 (starttls), depending on the value of mode
username<string>: Username to use during authentication. If no username is set, no authentication will be performed. The PLAIN and LOGIN authentication methods are supported

Section type 'webhook': Config for Webhook notification endpoints

Required properties:

methodpost|put|get (default=post): HTTP Method to use.
url<string>: HTTP(s) url with optional port.

Optional properties:

body<string>: The HTTP body to send. Supports templating.
comment<string>: Comment.
disable<boolean>: Disable this target.
header[name=<string> [,value=<string>]]: Array of HTTP headers. Each entry is a property string with a name and a value. The value property contains the header in base64 encoding. Supports templating. Can be specified more than once.
originuser-created|builtin|modified-builtin: The origin of a notification configuration entry.
secret[name=<string> [,value=<string>]]: Array of secrets. Each entry is a property string with a name and an optional value. The value property contains the secret in base64 encoding. For any API endpoints returning the endpoint config, only the secret name but not the value will be returned. When updating the config, also send all secrets that you want to keep, setting only the name but not the value. Can be accessed from templates. Can be specified more than once.

`notifications-priv.cfg`¶

File Format¶

This file contains protected credentials for notification targets.

Options¶

Section type 'gotify': Private configuration for Gotify notification endpoints. This config will be saved to a separate configuration file with stricter permissions (root:root 0600)

Required properties:

token<string>: Authentication token

Section type 'smtp': Private configuration for SMTP notification endpoints. This config will be saved to a separate configuration file with stricter permissions (root:root 0600)

Optional properties:

password<string>: The password to use during authentication.

Section type 'webhook': Private configuration for Webhook notification endpoints. This config will be saved to a separate configuration file with stricter permissions (root:root 0600).

Optional properties:

secret[name=<string> [,value=<string>]]: Array of secrets. Each entry is a property string with a name, and a value property. The value property contains the secret in base64 encoding. Can be accessed from templates. Can be specified more than once.

`tape.cfg`¶

File Format¶

Each LTO drive configuration section starts with the header lto: <name>, followed by the drive configuration options.

Tape changer configurations start with the header changer: <name>, followed by the changer configuration options.

lto: hh8
      changer sl3
      path /dev/tape/by-id/scsi-10WT065325-nst

changer: sl3
      export-slots 14,15,16
      path /dev/tape/by-id/scsi-CJ0JBE0059

You can use the proxmox-tape drive and proxmox-tape changer commands to manipulate this file.

Note

The virtual: drive type is experimental and should only be used for debugging.

Options¶

Section type 'changer': SCSI tape changer

Required properties:

path<string>: Path to Linux generic SCSI device (e.g. '/dev/sg4')

Optional properties:

eject-before-unload<boolean> (default=false): if set to true, tapes are ejected manually before unloading
export-slots[<integer>, ...]: A list of slot numbers, comma separated. Those slots are reserved for Import/ Export, i.e. any media in those slots are considered to be 'offline'.

Section type 'lto': Lto SCSI tape driver

Required properties:

path<string>: The path to a LTO SCSI-generic tape device (i.e. '/dev/sg0')

Optional properties:

changer<string>: Tape Changer Identifier.
changer-drivenum<integer> (0 - 255) (default=0): Associated changer drive number (requires option changer)

Section type 'virtual': Simulate tape drives (only for test and debug)

Required properties:

path<string>: Path to directory

Optional properties:

max-size<integer> (0 - N): Virtual tape size

`tape-job.cfg`¶

File Format¶

Each entry starts with the header backup: <name>, followed by the job configuration options.

backup: job1
      drive hh8
      pool p4
      store store3
      schedule daily

backup: ...

You can use the proxmox-tape backup-job command to manipulate this file.

Options¶

Required properties:

drive<string>: Drive Identifier.
pool<string>: Media pool name.
store<string>: Datastore name.

Optional properties:

comment<string>: Comment.
schedule<calendar-event>: Run sync job at specified schedule.
eject-media<boolean>: Eject media upon job completion.
export-media-set<boolean>: Export media set upon job completion.
group-filter[<exclude:|include:>]<type:<vm|ct|host>|group:GROUP|regex:RE>: List of group filters. Can be specified more than once.
latest-only<boolean>: Backup latest snapshots only.
max-depth<integer> (0 - 7) (default=7): How many levels of namespaces should be operated on (0 == no recursion)
notification-modelegacy-sendmail|notification-system (default=legacy-sendmail): Configure how notifications for this datastore should be sent. legacy- sendmail sends email notifications to the user configured in notify-user via the system's sendmail executable. notification-system emits matchable notification events to the notification system.
notify-user<string>: User ID
ns<string>: Namespace.

`user.cfg`¶

File Format¶

This file contains the list of API users and API tokens.

Each user configuration section starts with the header user: <name>, followed by the user configuration options.

API token configuration starts with the header token: <userid!token_name>, followed by the token configuration. The data used to authenticate tokens is stored in a separate file (token.shadow).

user: root@pam
      comment Superuser
      email test@example.local
      ...

token: root@pam!token1
      comment API test token
      enable true
      expire 0

user: ...

You can use the proxmox-backup-manager user command to manipulate this file.

Options¶

Section type 'token': ApiToken properties.

Optional properties:

comment<string>: Comment.
enable<boolean> (default=true): Enable the account (default). You can set this to '0' to disable the account.
expire<integer> (0 - N) (default=0): Account expiration date (seconds since epoch). '0' means no expiration date.

Section type 'user': User properties.

Optional properties:

comment<string>: Comment.
email<string>: E-Mail Address.
enable<boolean> (default=true): Enable the account (default). You can set this to '0' to disable the account.
expire<integer> (0 - N) (default=0): Account expiration date (seconds since epoch). '0' means no expiration date.
firstname<string>: First name.
lastname<string>: Last name.

`remote.cfg`¶

File Format¶

This file contains information used to access remote servers.

Each entry starts with the header remote: <name>, followed by the remote configuration options.

remote: server1
      host server1.local
      auth-id sync@pbs
      ...

remote: ...

You can use the proxmox-backup-manager remote command to manipulate this file.

Options¶

Required properties:

password<string>: Password or auth token for remote host (stored as base64 string).
auth-id<string>: Authentication ID
host<string>: DNS name or IP address.

Optional properties:

comment<string>: Comment.
fingerprint<string>: X509 certificate fingerprint (sha256).
port<integer>: The (optional) port

`sync.cfg`¶

File Format¶

Each entry starts with the header sync: <name>, followed by the job configuration options.

sync: job1
      store store1
      remote-store store1
      remote lina

sync: ...

You can use the proxmox-backup-manager sync-job command to manipulate this file.

Options¶

Required properties:

remote-store<string>: Datastore name.
store<string>: Datastore name.

Optional properties:

comment<string>: Comment.
group-filter[<exclude:|include:>]<type:<vm|ct|host>|group:GROUP|regex:RE>: List of group filters. Can be specified more than once.
max-depth<integer> (0 - 7): How many levels of namespaces should be operated on (0 == no recursion, empty == automatic full recursion, namespace depths reduce maximum allowed value)
ns<string>: Namespace.
owner<string>: Authentication ID
remote<string>: Remote ID.
remote-ns<string>: Namespace.
remove-vanished<boolean> (default=false): Delete vanished backups. This remove the local copy if the remote backup was deleted.
resync-corrupt<boolean>: If the verification failed for a local snapshot, try to pull it again.
schedule<calendar-event>: Run sync job at specified schedule.
sync-directionpull|push (default=pull): Direction of the sync job, push or pull
transfer-last<integer> (1 - N): Limit transfer to last N snapshots (per group), skipping others
burst-in<string>: Byte size with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).
burst-out<string>: Byte size with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).
rate-in<string>: Byte size with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).
rate-out<string>: Byte size with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).

`verification.cfg`¶

File Format¶

Each entry starts with the header verification: <name>, followed by the job configuration options.

verification: verify-store2
      ignore-verified true
      outdated-after 7
      schedule daily
      store store2

verification: ...

You can use the proxmox-backup-manager verify-job command to manipulate this file.

Options¶

Required properties:

store<string>: Datastore name.

Optional properties:

comment<string>: Comment.
ignore-verified<boolean> (default=true): Do not verify backups that are already verified if their verification is not outdated.
max-depth<integer> (0 - 7) (default=7): How many levels of namespaces should be operated on (0 == no recursion)
ns<string>: Namespace.
outdated-after<integer> (0 - N): Days after that a verification becomes outdated. (0 is deprecated)'
schedule<calendar-event>: Run verify job at specified schedule.

Configuration Files¶

acl.cfg¶

File Format¶

Roles¶

datastore.cfg¶

File Format¶

Options¶

domains.cfg¶

File Format¶

Options¶

media-pool.cfg¶

File Format¶

Options¶

node.cfg¶

Options¶

notifications.cfg¶

File Format¶

Options¶

notifications-priv.cfg¶

File Format¶

Options¶

tape.cfg¶

File Format¶

Options¶

tape-job.cfg¶

File Format¶

Options¶

user.cfg¶

File Format¶

Options¶

remote.cfg¶

File Format¶

Options¶

sync.cfg¶

File Format¶

Options¶

verification.cfg¶

File Format¶

Options¶

`acl.cfg`¶

`datastore.cfg`¶

`domains.cfg`¶

`media-pool.cfg`¶

`node.cfg`¶

`notifications.cfg`¶

`notifications-priv.cfg`¶

`tape.cfg`¶

`tape-job.cfg`¶

`user.cfg`¶

`remote.cfg`¶

`sync.cfg`¶

`verification.cfg`¶