Configuration

Introduction

This page contains the default settings of each config option, as well as the descriptions. The configuration uses the YAML format. If you are unfamiliar with it, it is suggested you read this short article:

https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html

Please take notice of the fact that whitespace is important, and messing up the indentation can and will cause the config to not work properly.

First off, the latest config can be found here. The following contains a list of all possible settings in the latest plugin version and their default values, as well as when they were added.

It should be noted, that although the plugin was designed with safety and performance in mind, incorrect usage can cause problems. The author(s) is/are not responsible for any damage(s) and the plugin comes with no warranty. Please read the documentation carefully when in doubt!

Contents

• Config versions
• Settings
  • Current settings
  • Past settings
• Mode configuration

Config versions

Server administrators should note, that whenever the plugin is updated, unless the previous configuration is deleted, the plugin will not be able to generate the new settings within the config file. This behaviour is not a bug and is there because of the way the Bukkit API handles configuration files. Indeed, the config file will only be generated if a file with the appropriate name does not exist within the plugin's data directory. If you keep an old config around, this condition is not met. When that happens, potential configuration settings that were introduced by the updated version that you are installing do not manifest within the configuration file.

In order to deal with that, AutoBackup will default those "missing" settings to the ones within the default configuration. As such, no harm is done, however the administrators might not be able to customise the new features by tweaking the new config settings. Therefore it is recommended that administrators make a copy of their (outdated) custom configuration and delete the original file so that AutoBackup can regenerate the updated default config. After that, it is possible to copy over the settings from the old file and tweak the new ones.

Settings

Current settings

• disable-updater: false - (v1.0-1.1) - The updater system is a feature that waits for the plugin to load and then checks whether there is a new version by comparing the current version string to the one on SpigotMC. If this is the case, it notifies the server's administrator by logging this to the console.

  Note: The plugin does not download and install the new version, that would be quite a breach of trust.

  Note 2: It is highly recommended that you leave this setting to its default value(false) as the plugin should always be updated to new versions in order to received new features, bug fixes and performance optimizations.

• default-modes: ['overworld', 'nether', 'end'] - (v1.0-1.1) - These are the backup modes that are executed when running the command /backup default. What these modes mean can be specified in the modes section of the config.yml file.

  Note: These names (in the example 'overworld', 'nether', 'end') should be defined in the section below, otherwise the backup cannot be performed and the particular mode name will be ignored.

• exclude-backup: true - (v1.0-1.1) - If set to true, this setting ensures that the backup directory will be excluded from future backups. This is very important because if you include this directory within future backups, this backs past backups up, which causes an exponential increase in both backup time and disk space taken up.

  Note: The only reason why this setting is provided is in case the backup directory exclusion system fails and needs to be disabled, or if your backup directory lies outside the file subsystem that is being backed up (in this case, it does not hurt to leave this enabled anyway).

• relative-paths: true - (v1.0-1.1) - This setting determines whether paths in this config are to be taken relative to the Minecraft server root as opposed to actual system root. Leave the default option (true) unless you know what you are doing and you would like to export the backups outside your Minecraft server directory.

• backup-dir: '/backups' - (v1.0-1.1) - This setting specified the directory where the plugin should dump the backup archives in. The directory '/' represents root, which can be either the Minecraft server root directory or the actual file system root of your operating system (if on a UNIX-like system), depending on what relative-paths is set to. You can also choose a directory that is more deeply nested, for example /data/backups or /world/backups/.

  Note: For reasons connected to the exclude-backup system, setting this value to / may break the backup directory exclusion system, which can have serious consequences such as extremely prolonged backup times and very rapid filling up of your server's disk space. If you are backing stuff up outside of your Minecraft server root, do NOT set the backup directory as a direct parent of the MC server root. An "uncle" directory is fine.

  Examples: If relative-paths: false and if your server root lies at /a/b/c, then setting backup-dir: /a/b/d, /a/c or /a/b/c/a is fine, but a/b and /a/b/c are not. If you are not sure what this means, please contact me and ask (!) by way of SpigotMC or GitHub issues (links above).

  Note 2: Perhaps in the future a check will be introduced to make sure this config is valid.

  If you do not wish to worry about these things, it is recommended you leave this setting to its default value.

• log-to-console: true - (v1.0-1.1) - This setting determines whether or not to log to console when backups are performed successfully. If a backup fails, the plugin will log it regardless of whether this option is set to true or false. It is recommended that you set this to true for logging completeness, especially since the plugin interacts with your filesystem.

• immediate-backup: false - (v1.0-1.1) - This setting determines whether or not to perform the first iteration of a scheduled backup cycle on server start and on plugin reload, or wait the scheduled time interval before the first cycle. Setting to true may cause the server startup TPS to drop, depending on the other plugins on the server and the backup size.

• allow-force-console: true - (v1.0-1.1) - This setting determines whether the console is allowed to perform a backup even if the manual trigger option for the backup (allow-manual option, see backup modes) is disabled. Basically, this decides whether the console should be allowed to bypass settings that are meant to stop admins from performing unwanted in-game commands.

• The next setting (backup-log, added in v1.1.0) is a multiple-line block (see below):

  backup-log:
    enable: true
    log-entity: true
    log-success: true
    log-failure: true`
  

  This feature was requested by a user, and consists in the file-logging of backups. If enable is set to true, then all backups that are performed are logged to a file called backup-log.txt, which resides within the backups directory specified by the backup-dir option. log-entity determines whether the entity (player or console) who performs the backup should be logged as well, the default being true since server owners might find it interesting to know who performed an unexpected backup. The options log-success and log-failure determine whether successful and unsuccessful backups should be logged, respectively. If they are both set to false, nothing is logged, regardless of whether enable is set to true or false. An example backup-log.txt file can be found here - LINK SOON (taken from my test server).

  Note: This feature has nothing to do with the feature tied to the log-to-console setting: that one logs to the console, this one to a file. The settings are completely independent from each other.

• allow-players-purge: false - (v1.2.0) - Determines whether admins should be able to purge all past backups using the /backup purge command (requires the permission node autobackup.purge). If set to false, this command cannot be used by in-game players regardless of other permissions and/or operator status.

• allow-console-purge: true - (v1.2.0) - Determines whether the console should be able to purge all past backups using the /backup purge command (requires the permission node autobackup.purge). If set to false, this command cannot be used by the console.

Past Settings

These settings are no longer present in the latest version and are described here in case you are running an old version of the plugin, in which case it is highly recommended that you update (download link) or, if that is not possible due to an incompatibility, please notify the author by posting an issue (preferred) or, if you do not wish to open a GitHub account, reply to the plugin's discussion thread on SpigotMC.org.

Backup Modes

A backup mode is just a preconfigured way to perform a backup. A mode is linked to a folder (or subfolder) of your Minecraft server, along with a few useful settings, which we will describe below. All modes are configured within the backup-modes node of the config.yml file. The default configuration is

backup-modes:
  - name: 'everything'
    dir: '/'
    allow-manual: true
    schedule: 0
    compression: 0
    recursive: true

  - name: 'server-data'
    dir: '/'
    allow-manual: true
    schedule: 0
    compression: 0
    recursive: false

  - name: 'plugins'
    dir: '/plugins'
    allow-manual: false
    schedule: 0
    compression: 0
    recursive: true

  - name: 'plugin-jars'
    dir: '/plugins'
    allow-manual: false
    schedule: 0
    compression: 0
    recursive: false

  - name: 'overworld'
    dir: '/world'
    allow-manual: true
    schedule: 720
    compression: 0
    recursive: true

  - name: 'nether'
    dir: '/world_nether'
    allow-manual: true
    schedule: 1440
    compression: 0
    recursive: true

  - name: 'end'
    dir: '/world_the_end'
    allow-manual: true
    schedule: 2880
    compression: 0
    recursive: true

Note: These are just (working) examples! You should add and tweak the ones you need and get rid of those you do not need. In particular, the backup everything is extremely inefficient and can take very long times (more about this topic below). It is therefore highly discouraged. You should rather setup separate smaller backups, ie. one for plugin data, one for each world, etc.

This structure is a list of dictionaries, and every mode is a list item which starts with a dash (-). For every mode, the same settings are available:

• name - (v1.0-1.1) - This is just the name of the backup mode, to be used when actually performing this backup. It is the very string that should be used in the default-modes setting (see above), as well as when performing a backup manually by executing the /backup take <name> command. This string can be chosen freely, although it should not contain spaces as that will break the /backup take command (but not the mode scheduler). It is also recommended that you avoid the name default, as this can cause confusion. If you understand how the plugin works, however, there is no technical reason why you should abstain from using default as a mode name.

• dir - (v1.0-1.1) - This is the path of the directory (folder) you wish to back up. It is a relative path, relative to the root directory, which can be either the Minecraft server root (default behaviour) or the actual system root of your machine, depending on how you configured the relative-paths setting (see above). You can specify the root itself (/), as well as any subpaths, such as /world, /world_nether/data. It is recommended not to use /, because it can have a rather long backup time and a large size, depending on the server size. Furthermore, things such as world folders should be backed up more frequently than the plugins folder or the files in the root directory, such as the banned list or whitelist or op list. Hence why it is recommended that you set up several smaller backups, potentially with different scheduled intervals (see schedule setting).

• allow-manual - (v1.0-1.1) - This determines whether players can manually take this backup using the /backup take <name> command, or whether this mode is solely intended for automatic scheduled backups. If the allow-force-console option is set to true, the console itself can override this setting, as in manually take backups with allow-manual: false, otherwise the console itself is also prevented from doing that. In principle, this setting is intended to provide a way to stop admins from messing with backups, and let the automatic backup scheduler take care of everything. Whether you wish for the console to be able to override this is a matter of taste and/or convenience.

• schedule - (v1.0-1.1) - This option manages the automatic backup scheduler. If set to 0 or negative, this mode will not be scheduled at all and can only be triggered by using the in-game command /backup take <name>. Otherwise, if set to a positive integer, this decides the interval of the scheduled backups, in minutes.

  Note: Decimals are not (yet) supported, as such, things like 1.5 (minutes) will not work properly. Nevertheless this should not be a problem, as backups are not supposed to be taken that frequently that fractions of 1 minute become relevant.

• compression - (v1.0-1.1) - Specifies the compression level. Higher compression levels yield smaller backup file disk sizes, however it takes longer to actually perform the entire backup. As such, you are encouraged to experiment and find the best suited combination. Possible values for this setting are:

  -1 (No compression); 0 (Default Compression); 1 (Best speed); 2 (Best Compression).

  Note: Experimental results show that options 0 and 1 can yield very similar results, although 0 has very slightly better compression and 1 has very slightly better speed. It is still possible that larger backup sizes lead to a divergence between these two as data entropy is expected to be larger.

• recursive - (1.2.0) - Specifies whether or not to back the folder up recursively, as in include the files within subdirectories of the given directory. If set to false, only the files at the top sublevel of the given path are backed up.

  Example: If you have a filesystem that looks like this:

  /
    plugins/
      AutoBackup/
          config.yml
      AutoBackup.jar
  

  and you set dir to plugins, then using recursive: false (see example mode plugin-jars results in the backup archive containing only AutoBackup.jar, and recursive: true (see example mode plugins) results in the inclusion of the file AutoBackup/config.yml.