Skip to content

Latest commit

 

History

History
69 lines (46 loc) · 3.93 KB

BTIP-30.md

File metadata and controls

69 lines (46 loc) · 3.93 KB
Raw
BTIP: 30
title: Simplify Backup and Recovery of BTFS Data
author: Shawn-Huang-Tron<[email protected]>
discussions-to: https://github.com/bittorrent/BTIPs/issues/30
status: Final
type: Client API
category (*only required for Core Protocol): 
created: 2023-07-20

Simple Summary

Before BTFS v2.3.2, migrating a BTFS node required stopping the daemon and creating a tar file of the .btfs directory. After installing a new BTFS node, the tar file was copied and extracted into the .btfs directory on the new machine. This process was error-prone and required expertise, making it difficult for those unfamiliar with BTFS to perform backup and recovery.

To simplify this process, the following commands can be used to back up and recover node data on another machine:

btfs backup -o ./btfs_backup

btfs recovery  -r ./btfs_backup.tar.gz

Abstract

This BTIP suggests the implementation of new commands in BTFS that will enable easy backup and recovery of BTFS node data.

Motivation

Currently, backing up and recovering BTFS data is a complex task for users without in-depth knowledge of BTFS. This BTIP aims to make the process more accessible and user-friendly.

Specification

To simplify the process of BTFS data backup and recovery, the following commands will be introduced:

btfs backup -o ./btfs_backup

btfs recovery  -r ./btfs_backup.tar.gz
  1. The backup command will create a backup of the data from the current BTFS node. The -o option specifies the output file name and path, with the default file name being btfs_backup_{{timestamp}}.tar.gz if not specified. If the -a zip option is specified, the backup file will be saved in zip format (btfs_backup_{{timestamp}}.zip). Additionally, the --exclude option (config/statestore/datastore) can be used to exclude specific directories from the backup.
  2. The recovery command will recover data from a previously created backup file. The -r option specifies the path to the archived file generated by the backup command. The -p option specifies the target recovery path, defaulting to .btfs or the path indicated by the environment variable BTFS_PATH.

NOTE: You are advised not to specify the --exclude option unless you fully understand its implications, as it may result in data loss.

Rationale

  1. The backup command will check if repo.lock is held to prevent inconsistency of data during backup.
  2. If repo.lock is held by another process, the backup command will prompt you to stop the process.
  3. If repo.lock is not held, backup will hold repo.lock and see if the environment variable BTFS_PATH exists.
  4. If it exists, this variable will be viewed as the target path, otherwise it will use ~/.btfs as the default target path.
  5. The backup command will output the backup file to the path specified by the -o option.
  6. The repo.lock will be released after backup.
  7. The recovery command will check if BTFS is initialized before proceeding. It is recommended not to initialize BTFS on a new machine if recovery is intended.
  8. If BTFS is not initialized, the recovery command will restore the archived file specified by the -r option into the BTFS data path (environment variable BTFS_PATH if exists or ~/.btfs).
  9. If BTFS has been initialized, the recovery command will back up BTFS data into another directory and continue to proceed as in the previous step.
  10. Alternatively, using btfs init --recovery ./btfs_backup.tar.gz is recommended for file recovery.

NOTE: During the backup, any operation try to modify the file of BTFS data will fail to prevent inconsistency.

Backwards Compatibility

The process is backwards compatible. The data backup created by the backup command will include information of the BTFS version so that the recovery command could work properly. Every version of BTFS released after this BTIP should be compatible with the recoverycommand.

Test Cases

Implementation