Giter VIP home page Giter VIP logo

borgjs's Introduction

๐Ÿ“ฆ borgjs

A tiny wrapper for BorgBackup to automate your backup workflow

Gitter npm Travis

npm David JavaScript Style Guide

Overview

Please note borgjs needs you to run node >=6 and has been tested using borg

  • v1.0.7
  • v1.0.8
  • v1.0.9
  • v1.0.10
  • v1.1.4

borgjs is a nodejs command line tool for BorgBackup.

After having tried a lot of backup solutions for my data, I've been using Borg for quite a while. It's rock solid and never let me down. It supports compression, de-duplication and encryption.

Backups should be as boring as possible, that's why I've created this tool in order to automate and constantly monitor the whole process, making it a little bit more user friendly.

Instead of writing complex bash scripts you can now just write a declarative configuration file, run borgjs in a crontab and forget about it.

It will take care of your backup workflow, sending you status reports through different possible channels.

Features

  • backup creation
  • prune old backup according to a set of rules declared in the configuration file.
  • check backups for consistency and integrity.
  • onFinish hook to do anything you want after finishing a backup.
  • lockfile system to prevent concurrent backup process running in the same destination.
  • output borg messages to stdout for easy logging.
  • highly configurable.
  • allow to fully customize borg commands and environment variables.

Usage CLI

In order to use borgjs, you need to configure borg before. This is an easy step, just follow the installation guide on the borg website.

Initialize an empty borg repository (for more details see the borg quickstart guide)

$ borg init /path/to/repo

Install borgjs globally

$ npm i -g borgjs

Running a backup is as easy as creating a borg repository and run

$ borgjs -c /User/me/borgjs.config.js

or

$ borgjs $(date +%Y-%m-%d-%H%M%S) -c /User/me/borgjs.config.js >> /Users/me/logs/$(date +%Y-%m-%d-%H%M%S).log

in case you want to specify the archive name and log to a file (useful if you run in as a cronjob).

$ borgjs --help

  A tiny wrapper for BorgBackup to automate your backup workflow

  Usage
  $ borgjs <archive><options>

Options
  -c, --config         config file path

Examples
  # run borgjs
  $ borgjs -c=/User/me/borgjs.config.js

  #run borgjs specifying the archive name, and log output to a file
  $ borgjs $(date +%Y-%m-%d-%H%M%S) -c /path/to/your/borgjs.config.js >> $(date +%Y-%m-%d-%H%M%S).log

Usage API

You can also use borgjs programmatically:

const borgjs = require('borgjs')
const config = {
  repository: '/Users/arny/Desktop/test/',
  paths: [
    '/Volumes/External/'
  ]
}
const archiveName = new Date().toString()

borgjs(config, archiveName)
.then(() => console.log('success'))
.catch((err) => console.log('error', err))

onFinish hook

By defining an onFinish callback function in the configuration file, it's possible to run any arbitrary code when a backup finishes.

// the config file
module.exports = {
  onFinish: function (err, data, done) {
    if (err) {
      console.log('An error happened', err)
    } else {
      console.log(`Archive ${data.archiveName} created.`)
    }
    // invoke the done callback to let the process terminate properly
    done()
  }
}

It's possible to use the onFinish callback to send emails or notifications about the executed backup (see the paragraph below for an example)

Configuration

module.exports = {
  // Specify an alternative absolute path for the borg executable
  // defaults to the one in $PATH
  // borgPath: '',

  // Borg repository path
  // can be remote or local
  // see http://borgbackup.readthedocs.io/en/stable/usage.html#borg-init
  // e.g. '/Users/me/Desktop/borg_backup' or '[email protected]:borg_backup'
  repository: '', // MANDATORY

  // An array of absolute paths to include in the backup
  // paths that do not exist will be excluded (useful when a network share is not mounted)
  paths: [ // MANDATORY
    //  '/Users/me',
    //  '/etc
  ],

  // An array of files/directories to exclude from backup
  // exclude: [
  //  '*/node_modules',
  //  '*.DS_Store'
  // ],

  // A prefix for backup archives
  // archivePrefix: 'backup-',

  // Create backup archive
  // Use the options array to pass any options supported by borg create
  // See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create
  create: {
    options: [
     '--compression', 'lz4',
     '--filter', 'AME?'
    ]
  },
  // Check repo consistency
  // Use the options array to pass any options supported by borg check
  // See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check
  // check: {
  //  options: []
  // },

  // Retention policy for pruning old backups
  // Use the options array to pass any options supported by borg prune
  // https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
 //  prune: {
 //   options: [
 //    '-d', 30,
 //    '-w', 30,
 //    '--keep-within', '31d'
 //   ]
 // }

  // Set the following environment variables
  // See https://borgbackup.readthedocs.io/en/stable/usage.html#environment-variables
  env: {
    BORG_REMOTE_PATH: 'borg1',
    BORG_PASSPHRASE: 'passphrase'
  },
  // the onFinish callback
  onFinish: function (err, data, done) {
    const message = err
      ? 'the backup failed'
      : `the archive ${data.archiveName} has been created`
    var execSync = require('child_process').execSync

    const command = `
        curl -s --user 'api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0' \
        https://api.mailgun.net/v3/samples.mailgun.org/messages \
        -F from='Excited User <[email protected]>' \
        -F to='[email protected]' \
        -F subject='Hello from borgjs' \
        -F text='${message}'
        `
    try {
      execSync(command)
    } catch (e) {}
    // invoke the done callback to let the process terminate properly
    done()
  }
}

Automate

A backup is not a backup if it's not automated.

I personally use cronnix to schedule my backup sessions on my mac.

Recipes

  • Borg can store data on any remote host accessible over SSH. If you prefer to store your offsite backup in some other fancy cloud storage, you can always backup to a local target, then upload it anywhere using rclone

  • I personally use rsync.net for my backup, they also apply dirt cheap pricing model to borg users. Please note I'm not affiliated with them, I'm just an happy paying customer.

Change Log

This project adheres to Semantic Versioning.
Every release, along with the migration instructions, is documented in the CHANGELOG.md file.

License

MIT

borgjs's People

Contributors

vesparny avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

borgjs's Issues

Ability to set more environment variables

Would it be possible to add the ability to set a few more environment variables?

I do not keep my cache directory in my home folder. My scripts use the environment variable to set it to another location...

Can you add that capability?

Awesome project!

Thanks

borgjs support to handle lvm

I'm using borgbackup for my kvm virtual machines on lvm disks. I saw borgjs. Very impressiv. Could you enhance it to handle lvm snapshots and the feature of borgbackup to handle lvm snapshots (--read-special).

Thank You,

Michael

MaxBuffer Exceeded

The --list command dumps everything to output which gives me an An error has occurred: Error: stderr maxBuffer exceeded error. This occurs no matter where I dump the output.

Note: I am running this on OS X

hook

Make the backup script hookable.
Something has already been implemented in v2 branch

onFinish - SyntaxError: Unexpected identifier

Hello, I'm attempting to use the borgjs wrapper and I'm receiving the following error when I uncomment the 'onFinish' section of the config (I filled in my own info for the mailgun service that was used in the example you provided)

root@customer-fs01:~# borgjs -c /etc/borgjs.config.js >> /var/log/borg/$(date +%Y-%m-%d-%H%M%S).log
/etc/borgjs.config.js:86
onFinish: function (err, data, done) {
^^^^^^^^
SyntaxError: Unexpected identifier
at createScript (vm.js:56:10)
at Object.runInThisContext (vm.js:97:10)
at Module._compile (module.js:542:28)
at Object.Module._extensions..js (module.js:579:10)
at Module.load (module.js:487:32)
at tryModuleLoad (module.js:446:12)
at Function.Module._load (module.js:438:3)
at Module.require (module.js:497:17)
at require (internal/module.js:20:19)
at Object. (/usr/lib/node_modules/borgjs/bin/index.js:77:16)

Here is a snippet of the onFinish section I'm using in the borgjs.conf.js config file (some values changed for privacy reasons):

// the onFinish callback
onFinish: function (err, data, done) {
const message = err
? 'the backup failed'
: the archive ${data.archiveName} has been created
var execSync = require('child_process').execSync

const command = `
    curl -s --user 'api:key-lkin3liknm456lkin345li7nlin345' \
    https://api.mailgun.net/v3/mg.example.com/messages \
    -F from='borgbackup <[email protected]>' \
    -F to='Customer Support <[email protected]>' \
    -F subject='customer-fs01.example.local - borgbackup status' \
    -F text='${message}'
    `
try {
  execSync(command)
} catch (e) {}
// invoke the done callback to let the process terminate properly
done()

}
}

Would you mind assisting me in determining why I'm receiving the error I referenced above? I copied the entire example config which works great except for the onFinish bit. I also tested the curl function by itself to ensure it sends the email as expected (I don't think the curl command is the issue though).

Please let me know if you need any additional information.

Any help is appreciate and thanks for creating borgjs, it's very handy.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.