Skip to content

Configuration

The config is plugins/xBackup/config.yml, written on first start. Apply changes with /xbackup reload; every setting applies on reload, remotes included.

Section What it covers
theme The prefix and colours xBackup’s messages share: see the theme.
messages Shared errors, and optional broadcasts when a backup starts and finishes.
command Whether /backup is on, and its aliases.
repository Where backups are kept.
schedule How often backups run.
sources What’s backed up.
exclude Paths to leave out.
retention Which backups are kept, the most space they may use, and the space always left free.
performance Limits on disk reads and uploads, compression, and the longest autosave may stay off.
verify How often older data is read back and checked.
remotes Copies of the backups elsewhere: see Remotes. Their passwords go in secrets.yml, never here.
update-checker Checks Modrinth for a new version once a day: Privacy.

A folder, relative to the server folder or absolute. A second disk is the best place for it: a backup on the same disk as the server doesn’t survive that disk failing. A network mount works too. Changing it starts a new, empty repository; the old one stays as it is.

every: "1h" backs up once an hour, counted from the last backup, so a restart doesn’t reset the clock. "off" backs up only with /backup now. With skip-when-idle, a scheduled backup is skipped when nobody has been online since the last one, since nothing in the worlds has changed. A restart always counts as a change.

  • worlds: every loaded world’s save folder. On 1.21.11 that’s world, world_nether and world_the_end; on 26.x one world folder holds every dimension. Worlds read during the autosave pause.
  • plugins: the plugins folder, jars and data. xBackup’s own repository and restore folders are never included, nor are secrets.yml, SFTP key files and the other files holding passwords.
  • server-files: server.properties and the .yml, .json, .toml and .txt files beside it (ops, whitelist, bans, bukkit.yml), and the config folder.
  • extra: anything else, by path, such as a world no plugin has loaded.

A source that is a link, such as a world kept on another disk, is backed up as the folder it leads to. A link inside a source is kept as a link; if it leads to a folder outside the server folder, the backup says that folder’s files aren’t in it.

Databases: every SQLite file is copied with SQLite’s own VACUUM INTO, so a plugin writing to it meanwhile is no problem, and its -wal and -shm files aren’t needed. A database that can’t be copied that way (one a plugin holds locked) keeps its previous copy, with a warning; its raw bytes are never copied. MySQL and MariaDB databases live outside the server; back them up with mysqldump.

Each tier keeps the newest backup of each of its last so many hours, days, weeks and months, and a backup can count for several. last keeps the newest few whatever their age. The newest backup and pinned ones (/backup pin) are always kept.

With the defaults (last: 3, hourly: 24, daily: 7, weekly: 4, monthly: 6), an hourly schedule keeps about 40 backups covering six months.

max-size caps the repository, such as "50GB": past it, the oldest backups go first. min-free-space is the space a backup always leaves on the repository’s disk. A backup that might go under it removes old backups first, and if that’s still not enough it doesn’t start; one that runs short part way stops cleanly, and nothing it wrote is used.

read-limit and upload-limit cap how fast a backup reads from disk and sends to remotes, such as "50MB" (per second). A backup runs on one low-priority thread, never on the server’s threads. compression-level is deflate’s, 1 to 9; region files are already compressed and stored as they are.

max-pause is the longest autosave may stay off for one backup (15 minutes by default). Usually it’s off for under a second; the very first backup of a big world reads everything once, before the pause, so even that’s short. If it’s ever passed, autosave goes back on and that backup is abandoned. Chunks aren’t lost either way: while autosave is off, the server holds them until it’s back on.

Each backup reads back what it wrote before it counts. every also reads back percent of the older data now and then (10% weekly by default), so a failing disk is found before you need a restore. /backup verify full reads everything.

plugins/xBackup/config.yml
# xBackup: incremental backups that cost almost nothing, and a restore you can trust.
# Docs: https://docs.xenastudios.co/xbackup/configuration/
#
# Apply changes with /xbackup reload. A bad value falls back to its default with a
# warning in the console; xBackup never stops over config. All text is MiniMessage:
# https://docs.xenastudios.co/start/formatting/
# Managed by the plugin, to carry your settings forward on updates. Don't edit it.
config-version: 1
# The look xBackup's messages share. The default messages use these as tags, so changing
# a colour here restyles them all. Write a style as MiniMessage tags: <gray>,
# <#5AA9FF>, or <gold><bold>.
theme:
# <prefix> starts the default messages. Make it your server's name, such as
# "<dark_gray>[<gradient:#B48CFF:#5EE08A>MyServer</gradient>]</dark_gray> ", or blank for none.
prefix: "<#5AA9FF>»</#5AA9FF> "
# The colour of message text that has no tag of its own.
base: "<gray>"
# <highlight>: names and values, such as a player or a speed.
highlight: "<#5AA9FF>"
# <success>: something turned on or done.
success: "<#5EE08A>"
# <error>: something refused or turned off.
error: "<#FF6B6B>"
# What players and staff are told.
messages:
error:
# The console or a command block ran a command only players can use.
player-only: "<prefix><error>Only players can use this command."
# The sender lacks the command's permission.
no-permission: "<prefix><error>You don't have permission to do that."
# No online player has that name. <player> is the name typed.
player-not-found: "<prefix><error>No player named <highlight><player></highlight> is online."
# The command was typed wrong. <usage> is how to type it.
usage: "<prefix><error>Usage:</error> <usage>"
# The command hit an error. The console has the details.
failed: "<prefix><error>Something went wrong. The console has the details."
# Told to everyone online when a backup starts. Blank says nothing.
broadcast-start: ""
# Told to everyone online when a backup is done. <time> is how long it took. Blank says nothing.
broadcast-done: ""
# /backup: run, list, check and restore backups. Each subcommand has its own permission,
# xbackup.<subcommand>, which operators have by default.
command:
enabled: true
aliases: ["backups"]
# Where backups are kept: a folder, relative to the server folder or absolute. Put it on
# a second disk if you have one. Changing it starts a new, empty repository there; the
# old one is left as it is.
repository: "plugins/xBackup/repository"
# When backups run.
schedule:
# How often a backup runs, such as 1h, 30m or 6h. "off" runs them only when asked
# (/backup now). Counted from the last backup, so a restart doesn't reset it.
every: "1h"
# Skip a scheduled backup when nobody has been online since the last one.
skip-when-idle: true
# What's backed up.
sources:
# Every loaded world's save folder, with its nether and end.
worlds: true
# The plugins folder: every plugin's data and jar. xBackup's own repository is never included.
plugins: true
# The server's own settings: server.properties, the .yml, .json, .toml and .txt files
# beside it (ops, whitelist, bans), and the config folder.
server-files: true
# More paths to back up, relative to the server folder, such as an unloaded world.
extra: []
# Paths to leave out, relative to the server folder. * is anything but /, ** is anything,
# so "plugins/*/logs/**" leaves out every plugin's logs folder.
exclude: ["**/session.lock", "plugins/.paper-remapped/**", "plugins/*/logs/**", "plugins/*/cache/**", "plugins/bStats/**", "**/*.tmp", "**/*.lck"]
# Which backups to keep. Each tier keeps the newest backup of each of its last so many
# hours, days, weeks or months; a backup can count for several. The newest backup and
# pinned ones (/backup pin) are always kept. Space is given back once a day.
retention:
# Always keep this many of the newest backups, however close together.
last: 3
hourly: 24
daily: 7
weekly: 4
monthly: 6
# The most space the repository may use, such as 50GB. Past it, the oldest backups go
# first. "off" for no limit.
max-size: "off"
# Free space a backup always leaves on the repository's disk. A backup that would go
# under it removes old backups first, and if that's not enough, doesn't start.
min-free-space: "2GB"
# Keeping backups cheap to run. Hashing and compressing happen off the server's threads;
# these keep them from crowding the disk or the network.
performance:
# The most a backup reads from disk per second, such as 50MB. "off" for no limit.
read-limit: "off"
# The most sent to remotes per second, such as 5MB. "off" for no limit.
upload-limit: "off"
# Deflate level for files that compress, 1 (fastest) to 9 (smallest). Region files are
# already compressed and stored as they are.
compression-level: 6
# The longest autosave may stay off for a backup. If reading the worlds takes longer,
# autosave goes back on and that backup is abandoned. Nothing is lost either way.
max-pause: "15m"
# Each backup checks what it just wrote. This also reads back a share of the older data
# now and then, so damage on the disk is found before you need a restore.
verify:
# How often to read back older data, such as 7d. "off" never does.
every: "7d"
# What share of the data each check reads, in percent.
percent: 10
# Copies of the repository somewhere else, updated after each backup. Only new files are
# sent. Name each one; the docs list every type and its settings:
# https://docs.xenastudios.co/xbackup/remotes/
remotes: {}
# Tells you when a new version is out.
update-checker:
# Ask Modrinth for the newest version at startup and every 24 hours. It sends
# only the plugin version, the platform and the Minecraft version.
enabled: true
# Logged, and shown to admins when they join, when a newer version is out.
# <plugin>, <current>, <latest> and <url> are filled in.
message: "<prefix><plugin> <highlight><latest></highlight> is out (you have <current>): <click:open_url:'<url>'><hover:show_text:'Open on Modrinth'><highlight><underlined><url>"