DoSnapshot CLI

Project Page at Digital Ocean, comment or vote for this project.

Use this tool to backup DigitalOcean droplet's via snapshot method, on the fly!

API Changes:

20.08.17: Change Barge to DropletKit. Release 1.0.0.
03.08.16: DO now automagically keeps our droplets running when snapshot is processing, so:
Added options --shutdown, --no-shutdown.
shutdown now disabled by default, no downtime anymore, YES!
If you want shutdown back use --shutdown option.
08.01.16: now we have to use DO API V2 only, because V1 is not work anymore.
17.10.15: now we use DO API V2 by default, due V1 deprecation at 11.2015.

Here are some features:

Multiple threads out of the box, no matter how many droplets you have.
Snapshots Auto-Cleanup.
Auto-Boot Droplet if Snapshot Event fails or encounters a bad connection exception.
Special binaries for cron and command-line, Homebrew, and standalone installers.
Mail notifications when a snapshot fails or the maximum number of snapshots is reached for a droplet or droplets.
Custom mail settings (You can set Pony mail settings).
Stop mode (automatically stop creating new snapshots when the maximum is reached).
Timeout option for long requests or uncaught loops. Defaults to 600 seconds, but can be changed.
Logging into selected directory.
Verbose mode for research.
Quiet mode for silence.

Compatibility

From 1.0.0:

Ruby version 2.0.0 or higher
JRuby 9.1.0.0 or higher

Prior to 0.6.4:

Ruby version 1.9.3 or higher
JRuby 1.7, 9.0.0.0 or higher

Installation

Install it yourself as:

$ gem install do_snapshot

System Wide Install (OSX, *nix):

$ sudo gem install do_snapshot

For OSX users (Homebrew Tap):

$ brew tap merqlove/do-snapshot && brew install do_snapshot

$ do_snapshot -V

Standalone with one-liner:

$ wget https://s3.amazonaws.com/assets.merqlove.ru/do_snapshot/do_snapshot.tgz && sudo tar -xzf do_snapshot.tgz /usr/local/lib/ && sudo ln -s /usr/local/lib/do_snapshot/bin/do_snapshot /usr/local/bin/do_snapshot

Standalone pack for Unix/Linux users: Download

$ wget https://s3.amazonaws.com/assets.merqlove.ru/do_snapshot/do_snapshot.tgz # if not done.

# Example Install into /usr/local

$ tar -xzf do_snapshot.tgz /usr/local/ && ln -s /usr/local/do_snapshot/bin/do_snapshot /usr/local/bin/do_snapshot 
$ do_snapshot help

Standalone Zip pack for others: Download

Usage

Mainly it's pretty simple:

$ do_snapshot --only 123456 -k 5 -c -v

Setup

Digitalocean API V2 (default):

You'll need to generate an access token in Digital Ocean's control panel at https://cloud.digitalocean.com/settings/applications

$ export DIGITAL_OCEAN_ACCESS_TOKEN="SOMETOKEN"

If you want to set keys without environment, than set it via options when you run do_snapshot:

$ do_snapshot --digital-ocean-access-token YOURLONGTOKEN

How-To

Tutorials:

Here we keeping only 5 latest snapshots and cleanup older after new one is created. If creation of snapshots failed no one will be deleted. By default we keeping 10 droplets.

$ do_snapshot --keep 5 -c

Keep latest 3 from selected droplet:

$ do_snapshot --only 123456 --keep 3

Working with all except droplets:

$ do_snapshot --exclude 123456 123457

Keep latest 5 snapshots, send mail notification instead of creating new one:

$ do_snapshot --keep 10 --stop --mail to:yourmail@example.com

E-mail notifications disabled out of the box. For working mailer you need to set e-mail settings via run options.

--mail to:mail@somehost.com from:from@host.com --smtp address:smtp.gmail.com port:25 user_name:someuser password:somepassword

Cron example

0 4 * * 7 . /.../.digitalocean_keys && /.../bin/do_snapshot -k 5 -m to:TO from:FROM -t address:HOST user_name:LOGIN password:PASSWORD port:2525 -q -c

Real world example

$ bin/do_snapshot --only 123456 -k 3 -c -m to:TO from:FROM -t address:HOST user_name:LOGIN password:PASSWORD port:2525 -v

Checking DigitalOcean Id's.
Start performing operations
Setting DigitalOcean Id's.
Loading list of DigitalOcean droplets
Working with list of DigitalOcean droplets
Preparing droplet id: 123456 name: mrcr.ru to take snapshot.
Shutting down droplet.
Start creating snapshot for droplet id: 123456 name: mrcr.ru.
Wait until snapshot will be created.
Snapshot name: mrcr.ru_2014_07_18 created successfully.
Droplet id: 123456 name: mrcr.ru snapshots: 4.
For droplet with id: 123456 and name: mrcr.ru the maximum number 3 of snapshots is reached.
Cleaning up snapshots for droplet id: 123456 name: mrcr.ru.
Snapshot name: mrcr.ru_2014_07_17 delete requested.
All operations has been finished.
Sending e-mail notification.

All options:

> $ do_snapshot c  

aliases: s, snap, create

Options:
  -p, [--protocol=1]                                             # Select api version.
                                                                 # Default: 2
      [--shutdown], [--no-shutdown]                              # Check if you want to stop your droplet before the snapshot.
  -o, [--only=123456 123456 123456]                              # Select some droplets.
  -e, [--exclude=123456 123456 123456]                           # Except some droplets.
  -k, [--keep=5]                                                 # How much snapshots you want to keep?
                                                                 # Default: 10
  -d, [--delay=5]                                                # Delay between snapshot operation status requests.
                                                                 # Default: 10                                                                    
      [--timeout=250]                                            # Timeout in sec's for events like Power Off or Create Snapshot.
                                                                 # Default: 3600                                                                     
  -m, [--mail=to:yourmail@example.com]                           # Receive mail if fail or maximum is reached.
  -t, [--smtp=user_name:yourmail@example.com password:password]  # SMTP options.
  -l, [--log=/Users/someone/.do_snapshot/main.log]               # Log file path. By default logging is disabled.
  -c, [--clean], [--no-clean]                                    # Cleanup snapshots after create. If you have more images than you want to `keep`, older will be deleted.
  -s, [--stop], [--no-stop]                                      # Stop creating snapshots if maximum is reached.
      [--stop-by-power], [--no-stop-by-power]                    # Droplet stop method, by it's power status (instead of waiting for event completed state).
  -v, [--trace], [--no-trace]                                    # Verbose mode.
  -q, [--quiet], [--no-quiet]                                    # Quiet mode. If don't need any messages in console.
      [--digital-ocean-access-token=YOURLONGAPITOKEN]            # DIGITAL_OCEAN_ACCESS_TOKEN. if you can't use environment.
      [--digital-ocean-client-id=YOURLONGAPICLIENTID]            # DIGITAL_OCEAN_CLIENT_ID. if you can't use environment.
      [--digital-ocean-api-key=YOURLONGAPIKEY]                   # DIGITAL_OCEAN_API_KEY. if you can't use environment.    

Description:
  `do_snapshot` able to create and cleanup snapshots on your droplets.

  You can optionally specify parameters to select or exclude some droplets.

You can ask, "Why you made this tool?"

First. I needed stable tool, which can provide for me automatic Snapshot feature for all of my Droplets via Cron planner.
I don't want to think how much snapshots for each droplet i have.
I don't wont to sleep when my droplets Offline!!! And i wanted tool which can BOOT back droplets, which failed to snapshot.
Also i want to understand what's going on if there some error. Mail is my choice. But logs also good.
And ... sure ;) We want to do it fast as rocket! :)
more more more...
So this tool can save a lot of time for people.

Donating:

Support this project and others by merqlove via gratipay.

Dependencies:

Thor for CLI.
DropletKit for API V2 requests.
Pony for mail notifications.

Contributing

Fork it ( https://github.com/merqlove/do_snapshot/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Testing

$ rake spec

MIT License

do_snapshot

Runtime