Backup & Restore API Documentation

Provides API functions for server backup, restore, and pruning operations.

This module offers a high-level interface for managing the backup and restoration of Bedrock server data. It orchestrates calls to methods of the BedrockServer class, primarily those provided by the ServerBackupMixin.

Key functionalities include:

Operations involving file modifications are thread-safe using a unified lock (_backup_restore_lock). For actions requiring the server to be offline, this module utilizes the server_lifecycle_manager() to safely stop and restart the server. All functions are exposed to the plugin system.

bedrock_server_manager.api.backup_restore.list_backup_files(server_name: str, backup_type: str, app_context: AppContext | None = None) → Dict[str, Any]

Lists available backup files for a given server and type.

This is a read-only operation and does not require a lock. It calls list_backups().

Parameters:

  • server_name (str) – The name of the server.

  • backup_type (str) – The type of backups to list. Valid options are “world”, “properties”, “allowlist”, “permissions”, or “all” (case-insensitive).

Returns:

A dictionary with the operation result. On success: {"status": "success", "backups": BackupData}. If backup_type is specific (e.g., “world”), BackupData is List[str] of backup file paths. If backup_type is “all”, BackupData is Dict[str, List[str]] categorizing backups (e.g., {"world_backups": [...], "properties_backups": [...]}). An empty list/dict is returned if no backups are found or backup dir is missing. On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.backup_restore.backup_world(server_name: str, stop_start_server: bool = True, app_context: AppContext | None = None) → Dict[str, str]

Creates a backup of the server’s world directory.

This operation is thread-safe and guarded by a lock. It calls the internal _backup_world_data_internal method of the BedrockServer instance, which handles determining the active world, exporting it to a .mcworld file, and pruning old world backups. If stop_start_server is True, the server_lifecycle_manager() is used to manage the server’s state. Triggers before_backup and after_backup plugin events (with type “world”).

Parameters:

  • server_name (str) – The name of the server whose world is to be backed up.

  • stop_start_server (bool, optional) – If True, the server will be stopped before the backup and restarted afterwards. Defaults to True.

Returns:

A dictionary with the operation result. Possible statuses: “success”, “error”, or “skipped” (if lock not acquired). On success: {"status": "success", "message": "World backup '<filename>' created..."} On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises:
bedrock_server_manager.api.backup_restore.backup_config_file(server_name: str, file_to_backup: str, stop_start_server: bool = True, app_context: AppContext | None = None) → Dict[str, str]

Creates a backup of a specific server configuration file.

This operation is thread-safe and guarded by a lock. It calls the internal _backup_config_file_internal method of the BedrockServer instance. This core method copies the specified file (e.g., server.properties) from the server’s installation directory to a timestamped backup in the server’s backup directory, then prunes older backups of that file type. The server_lifecycle_manager() is used if stop_start_server is True, though typically not strictly necessary for config file backups unless there’s a concern about live writes. Triggers before_backup and after_backup plugin events (with type “config_file”).

Parameters:

  • server_name (str) – The name of the server.

  • file_to_backup (str) – The name of the configuration file to back up (e.g., “server.properties”, “allowlist.json”). This file is expected to be in the root of the server’s installation directory.

  • stop_start_server (bool, optional) – If True, the server lifecycle will be managed (stopped before, restarted after if it was running). While often not strictly needed for config file backups, it can ensure consistency if the server might be writing to the file. Defaults to True.

Returns:

A dictionary with the operation result. Possible statuses: “success”, “error”, or “skipped” (if lock not acquired). On success: {"status": "success", "message": "Config file '<name>' backed up as '<backup_name>'..."} If original file not found: {"status": "error", "message": "Config file backup failed: File ... not found."} (or similar from BSMError) On other error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises:
bedrock_server_manager.api.backup_restore.backup_all(server_name: str, stop_start_server: bool = True, app_context: AppContext | None = None) → Dict[str, Any]

Performs a full backup of the server’s world and configuration files.

This operation is thread-safe and guarded by a lock. It calls backup_all_data(). If stop_start_server is True, the server_lifecycle_manager() is used to stop the server before the backup. Note: The server is not automatically restarted by this specific API function after the backup, even if stop_start_server is true; only the stop phase of the lifecycle manager is effectively used here for backup_all. Triggers before_backup and after_backup plugin events (with type “all”).

Parameters:

  • server_name (str) – The name of the server to back up.

  • stop_start_server (bool, optional) – If True, the server will be stopped before the backup operation begins. Defaults to True.

Returns:

A dictionary with the operation result. Possible statuses: “success”, “error”, or “skipped” (if lock not acquired). On success: {"status": "success", "message": "Full backup completed...", "details": BackupResultsDict} where BackupResultsDict maps component names (e.g., “world”, “allowlist.json”) to the path of their backup file, or None if a component’s backup failed. On error (e.g., critical world backup failure): {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.backup_restore.restore_all(server_name: str, stop_start_server: bool = True, app_context: AppContext | None = None) → Dict[str, Any]

Restores the server from the latest available backups.

This operation is thread-safe and guarded by a lock. It calls restore_all_data_from_latest(). If stop_start_server is True, the server_lifecycle_manager() is used to manage the server’s state, restarting it only if the restore operation (all components) is successful.

Warning

This operation OVERWRITES current world data and configuration files in the server’s installation directory with content from the latest backups.

Triggers before_restore and after_restore plugin events (with type “all”).

Parameters:

  • server_name (str) – The name of the server to restore.

  • stop_start_server (bool, optional) – If True, the server will be stopped before restoring and restarted afterwards only if the entire restore operation succeeds. Defaults to True.

Returns:

A dictionary with the operation result. Possible statuses: “success”, “error”, or “skipped” (if lock not acquired). On success: {"status": "success", "message": "Restore_all completed...", "details": RestoreResultsDict} where RestoreResultsDict maps component names to their restored paths or None on failure/skip. If no backups found: {"status": "success", "message": "No backups found..."} On error: {"status": "error", "message": "<error_message>"} (e.g., if a component failed to restore).

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.backup_restore.restore_world(server_name: str, backup_file_path: str, stop_start_server: bool = True, app_context: AppContext | None = None) → Dict[str, str]

Restores a server’s world from a specific backup file.

This operation is thread-safe and guarded by a lock. If stop_start_server is True, it uses the server_lifecycle_manager() to manage the server’s state, restarting it only if the restore is successful. The core world import is performed by import_active_world_from_mcworld().

Warning

This is a DESTRUCTIVE operation. The existing active world directory will be deleted before the new world is imported from the backup.

Triggers before_restore and after_restore plugin events (with type “world”).

Parameters:

  • server_name (str) – The name of the server.

  • backup_file_path (str) – The absolute path to the .mcworld backup file to be restored.

  • stop_start_server (bool, optional) – If True, the server will be stopped before restoring and restarted afterwards only if the restore is successful. Defaults to True.

Returns:

A dictionary with the operation result. Possible statuses: “success”, “error”, or “skipped” (if lock not acquired). On success: {"status": "success", "message": "World restore from '<filename>' completed..."} On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises:
bedrock_server_manager.api.backup_restore.restore_config_file(server_name: str, backup_file_path: str, stop_start_server: bool = True, app_context: AppContext | None = None) → Dict[str, str]

Restores a specific config file from a backup.

This operation is thread-safe and guarded by a lock. If stop_start_server is True, it uses the server_lifecycle_manager() to manage the server’s state, restarting it only if the restore is successful. The core config file restoration is performed by the internal _restore_config_file_internal method of the BedrockServer instance.

Warning

This operation OVERWRITES the current version of the configuration file in the server’s installation directory with the content from the backup.

Triggers before_restore and after_restore plugin events (with type “config_file”).

Parameters:

  • server_name (str) – The name of the server.

  • backup_file_path (str) – The absolute path to the configuration backup file (e.g., .../server_backup_YYYYMMDD_HHMMSS.properties).

  • stop_start_server (bool, optional) – If True, the server will be stopped before restoring and restarted afterwards only if the restore is successful. Defaults to True.

Returns:

A dictionary with the operation result. Possible statuses: “success”, “error”, or “skipped” (if lock not acquired). On success: {"status": "success", "message": "Config file '<original_name>' restored from '<backup_name>'..."} On error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises:
bedrock_server_manager.api.backup_restore.prune_old_backups(server_name: str, app_context: AppContext | None = None) → Dict[str, str]

Prunes old backups for a server based on retention settings.

This operation is thread-safe and guarded by a lock. It iteratively calls prune_server_backups() for the server’s world (.mcworld files) and standard configuration files (server.properties, allowlist.json, permissions.json). The number of backups to keep is determined by the retention.backups application setting. Triggers before_prune_backups and after_prune_backups plugin events.

Parameters:

server_name (str) – The name of the server whose backups are to be pruned.

Returns:

A dictionary with the operation result. Possible statuses: “success”, “error”, or “skipped” (if lock not acquired). On full success: {"status": "success", "message": "Backup pruning completed..."} If some components fail pruning: {"status": "error", "message": "Pruning completed with errors: <details>"} If backup directory not found: {"status": "success", "message": "No backup directory found..."} On other setup error: {"status": "error", "message": "<error_message>"}.

Return type:

Dict[str, str]

Raises: