snap-ebs 0.0.11 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: adbce5a0782103ad9050e9e643af42782e61eb95
-  data.tar.gz: 2180be623ea74f1adec4e6f8c7d534f70d8fa3fd
+  metadata.gz: 09451fa9061511bfe1442cac3f15884407f08232
+  data.tar.gz: de83068b869c4ea72a3020c4946121743f269dee
 SHA512:
-  metadata.gz: 68736848b73e037d82a3ac4dcd66934a747f0bb6a207d8b7da609f9b9d50baefdf0af55f5cdcd38aa21d9015f278d1594d0e591b4a611f119a53f39792e7fd9f
-  data.tar.gz: 1a597eeb20d2921d5db002e8a4d62c35b642537bf18e3c2bc19516b0c467557beeb24829596e677302cd20b977323b4403053c69045460b03a479d989771ae02
+  metadata.gz: 9cdd818bb391797aa7b9f63349a06bbe7d492c9f2327f9d65a90ad050daadbd62fa5d75487bde5e1790870a5f85aa41da8a2733915af4fa4181bc39d62dc60e7
+  data.tar.gz: d4d9ba9c19e88163ba9afefa271b41a9b2ed54737464607e81091e9a41d8a88e3e39caa677fac3220686f02915f908c660f5cbd5fa51a240d10e10b6f59a77f5

data/README.md

@@ -1,14 +1,17 @@
 snap-ebs
 ===
 
+![snap-ebs logo -- the snapping turtle](http://i.imgur.com/DgUZmIq.png)
+> Backup your EBS volumes in a snap
+
 This project aims to provide easy, automatic, and consistent snapshots for AWS
 EBS volumes on EC2 instances.
 
 Some specific goals and how they are achieved:
 
- - *Safety*: refuses to operate unless everything seems ok, and tries desperately to leave your system no worse than it started
- - *Reliability*: comprehensive test sweet makes sure that `snap-ebs` behaves as expected, even in unexpected conditions.
- - *Visibility*: verbose logging options to inspect the decision-making process for any action
+ - *Safety*: refuses to operate unless everything seems ok, and tries desperately to leave your system no worse than it was found
+ - *Reliability*: comprehensive test suite ensures that `snap-ebs` behaves as expected, even in unexpected conditions
+ - *Visibility*: verbose logging options to inspect the decision-making process for any action or non-action
  - *Ease of Installation*: just install the gem and add one line to your crontab
  - *Ease of Use*: automatically detects volumes mounted to the machine
  - *Ease of Monitoring*: 100% visibility of operation can be gained from off-the-shelf monitoring solution plugins
@@ -32,15 +35,21 @@ sudo yum install gcc \
                  zlib-devel
 
 gem install snap-ebs
-crontab -e
 ```
 
 Usage
 ===
 
-Put something like this in your root crontab:
+1. Create an IAM user with the necessary permissions: `ec2:CreateSnapshot`, `ec2:DescribeTags`, `ec2:DescribeVolumes`
+2. Download the user's credentials file (as `.csv`) and put it somewhere on the server (I would suggest `/opt/snap-ebs-credentials.csv`, ideally with mode 600 and owned by the user who will run `snap-ebs`)
+3. Add something like this to your root crontab:
 ```
-snap-ebs -a AWSACCESSKEY -s AWSSECRETKEY --directory /data,/log,/journal --mongo --mongo-shutdown yes --logfile /var/log/snap-ebs.log
+0 0 * * * * /bin/bash -lc 'snap-ebs -c /opt/snap-ebs-credentials.csv --directory /data,/log,/journal --logfile /var/log/snap-ebs.log --mongo --mongo-shutdown yes'
+```
+
+4. If you're using rvm with a passwordless-sudo user, you might use this instead:
+```
+0 0 * * * * /bin/bash -lc 'rvmsudo snap-ebs -c /opt/snap-ebs-credentials.csv --directory /data,/log,/journal --logfile /var/log/snap-ebs.log --mongo --mongo-shutdown yes'
 ```
 
 Testing
@@ -51,12 +60,21 @@ Because you'll be running this against production servers with critical data, it
 Unit Tests
 ---
 
+```
+rspec spec/*
+```
+
 Like any good Ruby software, this tool has a unit test suite that seeks mostly to verify the plumbing and ensure that there are no runtime errors on the expected execution paths. This is only the tip of the iceberg...
 
 Vagrant Integration Testing
 ---
 
+```
+vagrant up
+```
+
 The integration layer contains an Ansible + Vagrant setup to configure clusters of services for live-fire testing (the AWS bits are mocked out via `snap-ebs`'s `--mock` flag). Simply running `vagrant up` will build a cluster of servers running MySQL, MongoDB, etc, configured in a master/slave architecture as approprite for the given system.
 
-There is also a set of Ansible tasks that verify the operation of each plugin under **both ideal and pathological** conditions. This means that `snap-ebs` runs reliably, even when the services it operates on do not. Things like timeouts and service restart failures are modeled via `socat`, and assertions are made on the correct error output for each condition. For more info on how this is done, check `roles/integration-test/tasks/*.yml`
+There is also a set of Ansible tasks that verify the operation of each plugin under **both ideal and degenerate** conditions. This means that `snap-ebs` runs reliably, even when the services it operates on do not. Things like timeouts and service restart failures are modeled via `socat`, and assertions are made on the correct error output for each condition. For more info on how this is done, check `roles/integration-test/tasks/*.yml`
 
+Your local copy of `snap-ebs` is mounted to each machine, so all modifications carry over immediately. If you are hacking on `snap-ebs` and just want to run the integration tests, rather than the full ansible provisioning playbook, simply add `-t test` to the command Vagrant spits out when starting the ansible provisioner.

data/lib/plugins/mongo_plugin.rb

@@ -34,22 +34,6 @@ class SnapEbs::Plugin::MongoPlugin < SnapEbs::Plugin
     }
   end
 
-  def client
-    @client ||= Mongo::Client.new [ "#{options.host}:#{options.port}" ], client_options
-  end
-
-  def client_options
-    {
-      connect: :direct,
-      user: options.user,
-      password: options.password,
-      server_selection_timeout: options.server_selection_timeout.to_i,
-      wait_queue_timeout: options.wait_queue_timeout.to_i,
-      connection_timeout: options.connection_timeout.to_i,
-      socket_timeout: options.socket_timeout.to_i
-    }
-  end
-
   def before
     require 'mongo'
     Mongo::Logger.logger = logger
@@ -76,6 +60,8 @@ class SnapEbs::Plugin::MongoPlugin < SnapEbs::Plugin
     "Mongo"
   end
 
+  private
+
   def unlock_or_start_mongo
     (options.retry.to_i + 1).times do
       if wired_tiger?
@@ -151,4 +137,20 @@ class SnapEbs::Plugin::MongoPlugin < SnapEbs::Plugin
     logger.info "Unlocking mongo"
     client.database['$cmd.sys.unlock'].find().read
   end
+
+  def client
+    @client ||= Mongo::Client.new [ "#{options.host}:#{options.port}" ], client_options
+  end
+
+  def client_options
+    {
+      connect: :direct,
+      user: options.user,
+      password: options.password,
+      server_selection_timeout: options.server_selection_timeout.to_i,
+      wait_queue_timeout: options.wait_queue_timeout.to_i,
+      connection_timeout: options.connection_timeout.to_i,
+      socket_timeout: options.socket_timeout.to_i
+    }
+  end
 end

data/lib/snap_ebs/options.rb

@@ -2,6 +2,10 @@ require 'optparse'
 
 class SnapEbs
   module Options
+    # Gets the root `option_parser`. Plugins do not append to this directly,
+    # but instead supply a list of options, arguments, descriptions, and
+    # default values. `SnapEbs` manages the namespacing of options, and each
+    # plugin receives its own `options` object.
     def option_parser
       unless @option_parser
         @option_parser = OptionParser.new do |o|
@@ -29,7 +33,10 @@ class SnapEbs
 
           o.on("-l", "--logfile FILE", "Path to a file used for logging") do |filename|
             options.logfile = filename
-            logger.debug filename
+          end
+
+          o.on("-f", "--fs-freeze", "Freeze filesystems for fsfreeze or xfs_freeze before snapping (unfreezes after)") do |fs_freeze|
+            options.fs_freeze = fs_freeze
           end
 
           o.on("-d", "--directory PATH", "Only snap volumes mounted to PATH, a comma-separated list of directories") do |d|
@@ -44,6 +51,7 @@ class SnapEbs
     end
   end
 
+  # Get the root `options` object, and instance of OpenStruct
   def options
     @options ||= OpenStruct.new
   end

data/lib/snap_ebs/plugin.rb

@@ -20,10 +20,6 @@ class SnapEbs::Plugin
     @options ||= OpenStruct.new default_options
   end
 
-  def logger
-    SnapEbs.logger false
-  end
-
   def collect_options option_parser
     option_parser.on "--#{name.downcase}", "Enable the #{name} plugin" do
       options.enable = true
@@ -36,6 +32,19 @@ class SnapEbs::Plugin
     end
   end
 
+  protected
+
+  # Executes the given block with error handling, and prints helpful error
+  # messages when an exception is caught.
+  #
+  # Returns the result of the block, or nil if an exception occured
+  #
+  # ```
+  # carefully 'reticulate splines' do
+  #   splines.each &:reticulate
+  # end
+  # ```
+  #
   def carefully msg
     yield
   rescue => e
@@ -43,6 +52,10 @@ class SnapEbs::Plugin
     logger.error e
     nil
   end
+
+  def logger
+    SnapEbs.logger false
+  end
 end
 
 require 'plugins/mysql_plugin'

data/lib/snap_ebs/snapshotter.rb

@@ -5,8 +5,13 @@ module SnapEbs::Snapshotter
 
   attr_writer :compute
 
+  # Takes snapshots of attached volumes (optionally filtering by volumes
+  # mounted to the given directories)
   def take_snapshots
+    system 'sync'
     attached_volumes.collect do |vol|
+      dir = device_to_directory device_name vol
+      fs_freeze dir if options[:fs_freeze]
       next unless should_snap vol
       logger.debug "Snapping #{vol.id}"
       snapshot = compute.snapshots.new
@@ -14,10 +19,13 @@ module SnapEbs::Snapshotter
       snapshot.description = snapshot_name(vol)
       snapshot.save
       snapshot
+      fs_unfreeze dir if options[:fs_freeze]
     end
   end
 
-  # lazy loaders
+  # Get the Fog compute object. When `--mock` is given, `Fog.mock!` is called
+  # and  information normally auto-detected from AWS is injected with dummy
+  # values to circumvent the lazy loaders.
   def compute
     require 'fog/aws'
     if options[:mock]
@@ -35,6 +43,8 @@ module SnapEbs::Snapshotter
     }) 
   end
 
+  private
+
   def attached_volumes
     @attached_volumes ||= compute.volumes.select { |vol| vol.server_id == instance_id }
   end
@@ -69,14 +79,44 @@ module SnapEbs::Snapshotter
     "#{Time.now.strftime "%Y%m%d%H%M%S"}-#{id}-#{vol.device}"
   end
 
+  def directory_to_device dir
+    `df -T #{dir} | grep dev`.split(/\s/).first.strip
+  end
+
+  def device_to_directory device
+    `df -T | grep dev`.lines.each do |lines|
+      parts = line.split(/\s/).map &:strip
+      return parts.list if parts.first == device
+    end
+  end
+
+  def is_root_device? dir
+    directory_to_device('/') == directory_to_device(dir)
+  end
+
+  def device_name vol
+    vol.device.gsub('/dev/s', '/dev/xv') rescue vol.device
+  end
+
   def should_snap vol
-    normalized_device = vol.device.gsub('/dev/s', '/dev/xv') rescue vol.device
-    options.directory.nil? or devices_to_snap.include?(normalized_device)
+    options.directory.nil? or devices_to_snap.include?(device_name vol)
   end
 
   def devices_to_snap
-    @devices_to_snap ||= options.directory.split(',').map { |dir| `df -T #{dir} | grep dev`.split(/\s/).first.strip }
-    logger.debug @devices_to_snap
-    @devices_to_snap
+    @devices_to_snap ||= options.directory.split(',').map { |dir| directory_to_device dir }
+  end
+
+  def fs_freeze_command
+    @fs_freeze_command ||= system('which fsfreeze > /dev/null') ? 'fsfreeze' : 'xfs_freeze'
+  end
+
+  def fs_freeze dir
+    return logger.warn "Refusing to freeze #{dir}, which is the root device (#{directory_to_device dir})" if is_root_device? dir
+    system("#{fs_freeze_command} -f #{dir}")
+  end
+
+  def fs_unfreeze dir
+    return logger.warn "Refusing to unfreeze #{dir}, which is the root device (#{directory_to_device dir})" if is_root_device? dir
+    system("#{fs_freeze_command} -u #{dir}")
   end
 end

data/lib/snap_ebs.rb

@@ -34,11 +34,16 @@ class SnapEbs
     SnapEbs::Plugin.registered_plugins
   end
 
+  # Executes plugin before hooks, takes the snapshot, then runs the after
+  # hooks. Plugin hooks are called within `rescue` blocks to isolate errors
+  # from affecting other plugins or the snapshot plugins. Note that non-
+  # standard exceptions (i.e. out of memory or keyboard interrupt) will still
+  # cause a execution to abort.
   def run
     plugins.each do |plugin|
       begin
         plugin.before if plugin.options.enable
-      rescue Exception => e
+      rescue => e
         logger.error "Encountered error while running the #{plugin.name} plugin's before hook"
         logger.error e
       end
@@ -49,19 +54,22 @@ class SnapEbs
     plugins.each do |plugin|
       begin
         plugin.after if plugin.options.enable
-      rescue Exception => e
+      rescue => e
         logger.error "Encountered error while running the #{plugin.name} plugin's after hook"
         logger.error e
       end
     end
   end
 
+  # Entry point for the `snap-ebs` binary
   def execute
     option_parser.parse!
     logger.debug "Debug logging enabled"
     run
   end
 
+  # Get the global logger instance
+  # `logger.debug 'reticulating splines'`
   def logger
     # HACK -- the logfile argument only gets used on the first invocation
     SnapEbs.logger options.logfile

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: snap-ebs
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.0.20
 platform: ruby
 authors:
 - Bryan Conrad
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-29 00:00:00.000000000 Z
+date: 2015-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fog
@@ -66,7 +66,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.0'
-description: Easy EBS snapshots that work
+description: Tested, service-aware and consistent AWS EC2 backups via EBS snapshots.
 email: bryan.conrad@synctree.com
 executables:
 - snap-ebs
@@ -104,5 +104,5 @@ rubyforge_project:
 rubygems_version: 2.4.3
 signing_key: 
 specification_version: 4
-summary: Easy EBS snapshots that work
+summary: EBS backups in a snap
 test_files: []