Skip to content

Home

Jump to bottom
Mark Bromell edited this page Sep 21, 2020 · 3 revisions

What is simbak

Simbak is a simple backup solution that is aimed towards individuals who just want a quick and easy way to backup their files. Backups are stored as tar.gz files, so there is no dependence on any application to restore you backups.

Benefits

  • Simbak uses tar and gzip in order to store the backups, so that recovering the data in backups does not depend on simbak itself.
  • Simbak is also very light, portable, and very easy to use, meaning that there's no large application to install.
  • It's free and open source, meaning anyone can contribute or change simbak to meet their own needs.

Notice

This is in early development and changes to the API may be frequent. This project uses semantic versioning. The format of versions are {major}.{minor}.{patch}, so so while we are at version 0.x.x assume that each minor release has API changes.

Installation

To install simbak you can simple use pip.

$ pip install simbak

Usage

Terminal

You can use simbak in many ways, the fastest way would be to use the simbak command in the terminal directly, this will perform a normal backup, use $ simbak --help to see your options.

$ simbak [...]

You can also use the simbak module itself through the python executable.

$ python3 -m simbak [...]

Python script

You can use simbak within your own python code, and you can make python scripts to use simbak (a python script can be prettier than shell script).

import simbak

# This will perform a normal backup.
simbak.backup(...)

Example usages

Each of these examples will achieve the same reults. They will create a backup of /home/projects/my_project/ and /home/docs/important.txt and it will store the backup in /remote/backups and /local/backups. The backup will be a tar.gz file and it will have the name of important--YYYY-MM-DD--hh-mm-ss, the time is stamped at the end of the backup to ensure the file is unique and not conflicting with other backups.

Python script example

# backup.py

import simbak

simbak.backup(
    sources=[
        "/home/projects/my_project/",
        "/home/docs/important.txt",
    ],
    destinations=[
        "/local/backups/",
        "/remote/backups/",
    ],
    name="important"
)

You can then run this script through the terminal using $ python3 backup.py.

Bash script example

Note: I am using a backslash at the end of each line in order to have a command spread across multiple lines, this helps readability.

# backup.bash

simbak \
    --source \
        "/home/projects/my_project/" \
        "/home/docs/important.txt" \
    --destination \
        "/local/backups/" \
        "/remote/backups/" \
    --name "important"

Terminal

Using simbak directly in the terminal isn't recommended unless you are backing up one directory or file to one location for a one time occurrence, as you can see the lines can get quite long.

$ simbak -s "/home/projects/my_project/" "/home/docs/important.txt" \
> -d "/local/backups/" "/remote/backups/" \
> --name "important"

Backup agents

Backup agents are what actually perform and coordinate backups. They should be used instead of the standard simbak.backup function, if that function isn't enough for your use case, although keep in mind that the simback.backup function uses the NormalAgent to perform its backup. Here's the current list of agents.

  • simbak.agent.BaseAgent
  • simbak.agent.NormalAgent
  • simbak.agent.RotatingAgent

The BaseAgent is an abstract class, so you won't use it directly for making backups, although each other agent inherits from the BaseAgent. Each other agent has a relatively unique usage and will be explained in the later sections of this document.

For a general guideline, each agent currently has a backup method. In order to perform a backup with a specific agent you need to create an object from one of the agents and then call the backup method on that object. Here's a very general outline for how it would look.

from simbak.agent import NormalAgent

# Initialization of the agent
agent = NormalAgent(...)

# Performing the backup
agent.backup()

The configuration for how the agent should perform its backups are defined upon initialization of the the agent object.

Normal agent

This agent is the most basic agent you can use. It is essentially used to get sources and put them in a tar.gz backup file, and it will distribute that backup file to each of the specified destinations.

Normal agent constructor

__init__(
    sources: list, 
    destinations: list, 
    name: str, 
    compression_level: int = 6
)

sources (list of str): Paths to the files that you are backing up.

destinations (list of str): Paths of where you want the backup to be stored.

name (str): Name of the backup, this will name the backup files.

compression_level (int, optional): The gzip compression level that you want to use for the backup. Default to 6.

Rotating agent

This will perform a backup the same way the Normal agent does, although you now have the ability to limit the amount of backups that are stored in destinations. For your given backup, if the amount of backups in a destination has exceeded the rotate limit, then it will remove the oldest backup inside that destination. The discovery of the oldest backup depends on the backup file name convention of backup_name--YYYY-MM-DD--hh-mm-ss.tar.gz, which is how backups are created by default, so any changes to the file name may alter the desired outcome for the rotating agent. The rotating agent also depends on the name part of each backup file as a way to identify backups related to the current Rotating agent performing its backup.

Rotating agent constructor

__init__(
    sources: list, 
    destinations: list, 
    name: str,
    rotate_limit: int,
    compression_level: int = 6
)

sources (list of str): Paths to the files that you are backing up.

destinations (list of str): Paths of where you want the backup to be stored.

name (str): Name of the backup, this will name the backup files.

rotate_limit (int): The maximum amount of backups to keep in a destination.

compression_level (int, optional): The gzip compression level that you want to use for the backup. Default to 6.

Scheduling

placeholder

Windows

placeholder

Linux

placeholder

Clone this wiki locally