cknife 0.1.8 → 1.1.0

data/bin/cknifemon

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'cknife/cknife_mon'
+
+CKnife::CKnifeMon.start

data/cknife.gemspec

@@ -2,19 +2,19 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: cknife 0.1.8 ruby lib
+# stub: cknife 1.1.0 ruby lib
 
 Gem::Specification.new do |s|
-  s.name = "cknife"
-  s.version = "0.1.8"
+  s.name = "cknife".freeze
+  s.version = "1.1.0"
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.require_paths = ["lib"]
-  s.authors = ["Mike De La Loza"]
-  s.date = "2015-08-01"
-  s.description = "Cali Army Knife, a collection of command line tools, especially for popular API services."
-  s.email = "mikedll@mikedll.com"
-  s.executables = ["cknifeaws", "cknifedub", "cknifemail", "cknifemysql", "cknifenowtimestamp", "cknifepg", "cknifewcdir", "cknifezerigo"]
+  s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib".freeze]
+  s.authors = ["Michael Rivera".freeze]
+  s.date = "2018-10-06"
+  s.description = "A collection of command line tools, especially for popular API services.".freeze
+  s.email = "soymrmike@gmail.com".freeze
+  s.executables = ["cknifeaws".freeze, "cknifedub".freeze, "cknifemail".freeze, "cknifemon".freeze, "cknifemysql".freeze, "cknifenowtimestamp".freeze, "cknifepg".freeze, "cknifewcdir".freeze, "cknifezerigo".freeze]
   s.extra_rdoc_files = [
     "LICENSE",
     "README.md"
@@ -31,6 +31,7 @@ Gem::Specification.new do |s|
     "bin/cknifeaws",
     "bin/cknifedub",
     "bin/cknifemail",
+    "bin/cknifemon",
     "bin/cknifemysql",
     "bin/cknifenowtimestamp",
     "bin/cknifepg",
@@ -38,59 +39,68 @@ Gem::Specification.new do |s|
     "bin/cknifezerigo",
     "cknife.gemspec",
     "cknife.yml.sample",
+    "doc/remote_ubuntu_machine.md",
+    "lib/cknife/backgrounded_polling.rb",
+    "lib/cknife/cknife_aws.rb",
+    "lib/cknife/cknife_mon.rb",
     "lib/cknife/cknife_mysql.rb",
     "lib/cknife/cknife_pg.rb",
     "lib/cknife/command_line.rb",
-    "lib/cknife/config.rb"
+    "lib/cknife/config.rb",
+    "lib/cknife/monitor.rb",
+    "lib/cknife/repetition.rb"
   ]
-  s.homepage = "http://github.com/mikedll/cali-army-knife"
-  s.licenses = ["MIT"]
-  s.rubygems_version = "2.4.7"
-  s.summary = "Cali Army Knife"
+  s.homepage = "http://github.com/mikedll/cknife".freeze
+  s.licenses = ["".freeze]
+  s.rubygems_version = "2.6.14.1".freeze
+  s.summary = "CKnife".freeze
 
   if s.respond_to? :specification_version then
     s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<rest-client>, [">= 1.6", "~> 1"])
-      s.add_runtime_dependency(%q<nokogiri>, [">= 1.6", "~> 1"])
-      s.add_runtime_dependency(%q<i18n>, ["~> 0"])
-      s.add_runtime_dependency(%q<activesupport>, ["~> 3"])
-      s.add_runtime_dependency(%q<actionpack>, ["~> 3"])
-      s.add_runtime_dependency(%q<mail>, ["~> 2.4"])
-      s.add_runtime_dependency(%q<thor>, [">= 0.14", "~> 0"])
-      s.add_runtime_dependency(%q<builder>, ["~> 3.0"])
-      s.add_runtime_dependency(%q<fog>, ["<= 1.17", ">= 1.15"])
-      s.add_runtime_dependency(%q<unf>, [">= 0.1", "~> 0"])
-      s.add_development_dependency(%q<bundler>, ["~> 1.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 2.0"])
+      s.add_runtime_dependency(%q<rest-client>.freeze, [">= 1.8.0", "~> 1"])
+      s.add_runtime_dependency(%q<nokogiri>.freeze, [">= 1.8.2", "~> 1"])
+      s.add_runtime_dependency(%q<i18n>.freeze, [">= 0.6.6"])
+      s.add_runtime_dependency(%q<activesupport>.freeze, ["~> 4.2.9"])
+      s.add_runtime_dependency(%q<actionpack>.freeze, ["~> 4.2.9"])
+      s.add_runtime_dependency(%q<mail>.freeze, ["~> 2.5.5"])
+      s.add_runtime_dependency(%q<thor>.freeze, [">= 0.14", "~> 0"])
+      s.add_runtime_dependency(%q<builder>.freeze, ["~> 3.0"])
+      s.add_runtime_dependency(%q<fog-aws>.freeze, ["< 3.0"])
+      s.add_runtime_dependency(%q<unf>.freeze, [">= 0.1", "~> 0"])
+      s.add_runtime_dependency(%q<daemons>.freeze, [">= 0"])
+      s.add_development_dependency(%q<bundler>.freeze, ["~> 1.0"])
+      s.add_development_dependency(%q<jeweler>.freeze, ["~> 2.1"])
     else
-      s.add_dependency(%q<rest-client>, [">= 1.6", "~> 1"])
-      s.add_dependency(%q<nokogiri>, [">= 1.6", "~> 1"])
-      s.add_dependency(%q<i18n>, ["~> 0"])
-      s.add_dependency(%q<activesupport>, ["~> 3"])
-      s.add_dependency(%q<actionpack>, ["~> 3"])
-      s.add_dependency(%q<mail>, ["~> 2.4"])
-      s.add_dependency(%q<thor>, [">= 0.14", "~> 0"])
-      s.add_dependency(%q<builder>, ["~> 3.0"])
-      s.add_dependency(%q<fog>, ["<= 1.17", ">= 1.15"])
-      s.add_dependency(%q<unf>, [">= 0.1", "~> 0"])
-      s.add_dependency(%q<bundler>, ["~> 1.0"])
-      s.add_dependency(%q<jeweler>, ["~> 2.0"])
+      s.add_dependency(%q<rest-client>.freeze, [">= 1.8.0", "~> 1"])
+      s.add_dependency(%q<nokogiri>.freeze, [">= 1.8.2", "~> 1"])
+      s.add_dependency(%q<i18n>.freeze, [">= 0.6.6"])
+      s.add_dependency(%q<activesupport>.freeze, ["~> 4.2.9"])
+      s.add_dependency(%q<actionpack>.freeze, ["~> 4.2.9"])
+      s.add_dependency(%q<mail>.freeze, ["~> 2.5.5"])
+      s.add_dependency(%q<thor>.freeze, [">= 0.14", "~> 0"])
+      s.add_dependency(%q<builder>.freeze, ["~> 3.0"])
+      s.add_dependency(%q<fog-aws>.freeze, ["< 3.0"])
+      s.add_dependency(%q<unf>.freeze, [">= 0.1", "~> 0"])
+      s.add_dependency(%q<daemons>.freeze, [">= 0"])
+      s.add_dependency(%q<bundler>.freeze, ["~> 1.0"])
+      s.add_dependency(%q<jeweler>.freeze, ["~> 2.1"])
     end
   else
-    s.add_dependency(%q<rest-client>, [">= 1.6", "~> 1"])
-    s.add_dependency(%q<nokogiri>, [">= 1.6", "~> 1"])
-    s.add_dependency(%q<i18n>, ["~> 0"])
-    s.add_dependency(%q<activesupport>, ["~> 3"])
-    s.add_dependency(%q<actionpack>, ["~> 3"])
-    s.add_dependency(%q<mail>, ["~> 2.4"])
-    s.add_dependency(%q<thor>, [">= 0.14", "~> 0"])
-    s.add_dependency(%q<builder>, ["~> 3.0"])
-    s.add_dependency(%q<fog>, ["<= 1.17", ">= 1.15"])
-    s.add_dependency(%q<unf>, [">= 0.1", "~> 0"])
-    s.add_dependency(%q<bundler>, ["~> 1.0"])
-    s.add_dependency(%q<jeweler>, ["~> 2.0"])
+    s.add_dependency(%q<rest-client>.freeze, [">= 1.8.0", "~> 1"])
+    s.add_dependency(%q<nokogiri>.freeze, [">= 1.8.2", "~> 1"])
+    s.add_dependency(%q<i18n>.freeze, [">= 0.6.6"])
+    s.add_dependency(%q<activesupport>.freeze, ["~> 4.2.9"])
+    s.add_dependency(%q<actionpack>.freeze, ["~> 4.2.9"])
+    s.add_dependency(%q<mail>.freeze, ["~> 2.5.5"])
+    s.add_dependency(%q<thor>.freeze, [">= 0.14", "~> 0"])
+    s.add_dependency(%q<builder>.freeze, ["~> 3.0"])
+    s.add_dependency(%q<fog-aws>.freeze, ["< 3.0"])
+    s.add_dependency(%q<unf>.freeze, [">= 0.1", "~> 0"])
+    s.add_dependency(%q<daemons>.freeze, [">= 0"])
+    s.add_dependency(%q<bundler>.freeze, ["~> 1.0"])
+    s.add_dependency(%q<jeweler>.freeze, ["~> 2.1"])
   end
 end
 

data/cknife.yml.sample

@@ -2,6 +2,9 @@
 key: AKIAblahblahb...
 secret: 8xILhOsecretsecretsecretsecret...
 
+mon:
+  url: http://some.server.com/monitored_computers/heartbeat
+  api_key: someapikey
 
 mail:
   from: me@mydomain.com

data/doc/remote_ubuntu_machine.md

@@ -0,0 +1,87 @@
+
+The example deployment user here has username `alexan`. (Alexa N.)
+
+This presumes an Ubunto 14.x server base installation.
+
+    > lsb_release -a 
+    No LSB modules are available.
+    Distributor ID:	Ubuntu
+    Description:	Ubuntu 14.04.5 LTS
+    Release:	14.04
+    Codename:	trusty
+
+# Non-root user creation
+
+Applications are expected to be served from that user's home
+directory.
+
+    > adduser -G sudo alexan
+
+Provide a password. Answer some questions.
+
+    > usermod -a -G sudo alexan 
+    > groups alexan
+    alexan : alexan sudo
+
+You may inspect the sudo file:
+
+    > less /etc/sudoers
+
+    ...
+
+    # Members of the admin group may gain root privileges.
+    %admin ALL=(ALL) ALL
+
+    # Allow members of group sudo to execute any command
+    %sudo	ALL=(ALL:ALL) ALL
+
+# Upgrade to latest release.
+
+This is not recommended at this time. This could upgrade to Ubuntu 16.x.
+
+    # > sudo do-release-upgrade
+    
+# Directory Structure
+
+Ensure you create these directories:
+
+    mkdir ~/backups
+    mkdir ~/packages
+
+Pick a package directory like the packages directory described
+above for doing package building.
+
+# Passwordless Login Setup
+
+Ensure you have a key installed for this user. You're about
+to lose access to the root account.
+
+    > cd ~
+    > mkdir .ssh
+    > chmod 700 .ssh 
+    > touch ~/.ssh/authorized_keys
+    > chomd 644 ~/.ssh/authorized_keys 
+    > vi ~/.ssh/authorized_keys
+
+Paste in your .pub contents. Save the file.
+
+Test the machine to verify that you can do a passwordless login.
+
+Then you are ready to turn off password logins.
+
+# Disable Password Logins
+
+**Requires** that you've completed Passwordless Login Setup, or you'll
+lose control of your machine.
+
+    > sudo vi /etc/ssh/sshd_config
+    
+    ...
+    
+    PubkeyAuthentication yes
+    ...
+    ChallengeResponseAuthentication no
+    ...
+    PasswordAuthentication no            # you'll likely change this line.
+
+You may further setup this machine for your purposes.

data/lib/cknife/backgrounded_polling.rb

@@ -0,0 +1,71 @@
+require 'active_support/concern'
+
+# mixin client must define:
+#
+#   before_poll
+#   handle_poll_result(response, request, result)
+#   target_endpoint
+#
+# And these fields:
+#
+#  last_error
+#  last_polled_at
+#  active
+#  consecutive_error_count
+#
+# And implement a loop that calls poll_background.
+# This is optional:
+#
+#  payload
+#
+module CKnife
+  module BackgroundedPolling
+    extend ActiveSupport::Concern
+
+    class IneligibleToPoll < StandardError
+    end
+
+    BACKGROUND_POLL = 'background_poll'
+
+    included do
+      def payload
+        {}
+      end
+
+      def poll_background
+        if active && (last_polled_at.nil? || (last_polled_at < Time.now - 15.minutes))
+          before_poll
+          self.last_error = ""
+
+          begin
+            result = RestClient.post(target_endpoint, payload) do |response, request, result|
+              if ![200, 201].include?(response.net_http_res.code.to_i)
+                self.last_error = "Unexpected HTTP Result: #{response.net_http_res.code.to_i}"
+              else
+                handle_poll_result(response, request, result)
+              end
+            end
+          rescue => e
+            self.last_error = e.message
+          end
+
+          if !last_error.blank?
+            self.consecutive_error_count += 1
+            self.active = false if consecutive_error_count >= Repetition::MAX_CONSECUTIVE
+            puts "#{Time.now}: Failed to ping home url. Last error: #{last_error}."
+          else
+            self.consecutive_error_count = 0
+            puts "#{Time.now}: Pinged home url with result #{last_result}."
+          end
+
+          self.last_polled_at = Time.now
+        end
+      end
+
+      def reset_last_poll
+        self.last_polled_at = Time.now
+      end
+    end
+
+  end
+end

data/lib/cknife/cknife_aws.rb

@@ -0,0 +1,572 @@
+require 'fog/aws'
+require 'thor'
+require 'active_support/all'
+require 'zlib'
+require 'digest/md5'
+require 'pathname'
+
+class CKnifeAws < Thor
+
+  FILE_BUFFER_SIZE = 10.megabytes
+  LOCAL_MOD_KEY = "x-amz-meta-mtime"
+  EPSILON = 1.second
+
+  no_tasks do
+
+    def config
+      return @config if @config
+
+      @config = {
+        :key => ENV["KEY"] || ENV['AMAZON_ACCESS_KEY_ID'],
+        :secret => ENV["SECRET"] || ENV['AMAZON_SECRET_ACCESS_KEY']
+      }
+
+      config_file = nil
+      Pathname.new(Dir.getwd).tap do |here|
+        config_file = [["cknife.yml"], ["tmp", "cknife.yml"]].map { |args|
+          here.join(*args)
+        }.select { |path|
+          File.exists?(path)
+        }.first
+      end
+
+      if config_file
+        begin
+          @config.merge!(YAML.load(config_file.read).symbolize_keys!)
+        rescue
+          say ("Found, but could not parse config: #{config_file}")
+        end
+      end
+
+      @config
+    end
+
+    def fog_opts
+      opts = {
+        :provider => 'AWS',
+        :aws_access_key_id => config[:key],
+        :aws_secret_access_key => config[:secret]
+      }
+      opts.merge!({ :region => options[:region] }) if !options[:region].blank?
+      opts
+    end
+
+    def fog_storage
+      return @storage if @storage
+      @storage = Fog::Storage.new(fog_opts)
+      begin
+        @storage.directories.count # test login
+      rescue Excon::Errors::Forbidden => e
+        say("Received Forbidden error while accessing account info. Is your key/secret correct?")
+        raise SystemExit
+      end
+      @storage
+    end
+
+    def fog_compute
+      @compute ||= Fog::Compute.new(fog_opts)
+    end
+
+    def fog_cdn
+      @cdn ||= Fog::CDN.new(fog_opts)
+    end
+
+    def show_buckets
+      fog_storage.directories.sort { |a,b| a.key <=> b.key }.each { |b| puts "#{b.key}" }
+    end
+
+    def show_servers
+      fog_compute.servers.sort { |a,b| a.key_name <=> b.key_name }.each do |s|
+        puts "#{s.tags['Name']} (state: #{s.state}): id=#{s.id} keyname=#{s.key_name} dns=#{s.dns_name} flavor=#{s.flavor_id}"
+      end
+    end
+
+    def show_cdns
+      puts fog_cdn.get_distribution_list.body['DistributionSummary'].to_yaml
+    end
+
+    def with_bucket(bucket_name)
+      d = fog_storage.directories.select { |d| d.key == bucket_name }.first
+      if d.nil?
+        say ("Could not find bucket with name #{bucket_name}")
+        return
+      end
+
+      say ("Found bucket named #{bucket_name}")
+      yield d
+    end
+
+    def s3_download(s3_file)
+      dir_path = Pathname.new(s3_file.key).dirname
+      dir_path.mkpath
+      File.open(s3_file.key, "w") do |f|
+        f.write s3_file.body
+      end
+    end
+
+
+    def content_hash(file)
+      md5 = Digest::MD5.new
+
+      while !file.eof?
+        md5.update(file.read(FILE_BUFFER_SIZE))
+      end
+
+      md5.hexdigest
+    end
+
+    def fresh_file_upload(to_upload, d, key, is_public)
+      File.open(to_upload) do |localfile|
+        file = d.files.create(
+                              :key    => key,
+                              :public => is_public,
+                              :body => ""
+                              )
+        file.metadata = { LOCAL_MOD_KEY => localfile.mtime.to_s }
+        file.multipart_chunk_size = FILE_BUFFER_SIZE # creates multipart_save
+        file.body = localfile
+        file.save
+      end
+    end
+
+    def n_file_heads(directory, glob=nil, max=30)
+      found = []
+
+      n = 0
+      directory.files.each do |f|
+        if glob.nil? || File.fnmatch(glob, f.key)
+          found.push(directory.files.head(f.key))
+          break if n >= max
+          n += 1
+        end
+      end
+
+      found
+    end
+  end
+
+  desc "list_servers", "Show all servers"
+  def list_servers
+    show_servers
+  end
+
+  desc "start_server [SERVER_ID]", "Start a given EC2 server"
+  def start_server(server_id)
+    s = fog_compute.servers.select { |s| s.id == server_id}.first
+    if s
+      say("found server. starting/resuming. #{s.id}")
+      s.start
+      show_servers
+    else
+      say("no server with that id found. nothing done.")
+    end
+  end
+
+  desc "stop_server [SERVER_ID]", "Stop a given EC2 server (does not terminate it)"
+  def stop_server(server_id)
+    s = fog_compute.servers.select { |s| s.id == server_id}.first
+    if s
+      say("found server. stopping. #{s.id}")
+      s.stop
+    else
+      say("no server with that id found. nothing done.")
+    end
+  end
+
+  desc "list_cloudfront", "List cloudfront distributions (CDNs)"
+  def list_cloudfront
+    show_cdns
+  end
+
+  desc "create_cloudfront [BUCKET_NAME]", "Create a cloudfront distribution (a CDN)"
+  def create_cloudfront(bucket_id)
+    fog_cdn.post_distribution({
+                            'S3Origin' => {
+                              'DNSName' => "#{bucket_id}.s3.amazonaws.com"
+                            },
+                            'Enabled' => true
+                          })
+
+    show_cdns
+  end
+
+  desc "list", "Show all buckets"
+  method_options :region => "us-east-1"
+  def list
+    show_buckets
+  end
+
+  desc "afew [BUCKET_NAME]", "Show first 5 files in bucket"
+  method_options :count => "5"
+  method_options :glob => "*"
+  def afew(bucket_name)
+    d = fog_storage.directories.select { |d| d.key == bucket_name }.first
+    if d.nil?
+      say ("Found no bucket by name #{bucket_name}")
+      return
+    end
+
+    found = n_file_heads(d, options[:glob], options[:count].to_i)
+
+    unit_to_mult = {
+      'B' => 1,
+      'K' => 2**10,
+      'M' => 2**20,
+      'G' => 2**30
+    }
+
+    found.map { |f|
+      matching = unit_to_mult.keys.select { |k|
+        f.content_length >= unit_to_mult[k]
+      }.last
+
+      [f.key,
+       "#{f.content_length == 0 ? 0 : (f.content_length.to_f / unit_to_mult[matching]).round(2)}#{matching}",
+       f.content_type,
+       f.last_modified
+      ]
+    }.tap do |tabular|
+      print_table(tabular, :ident => 2)
+    end
+
+  end
+
+  desc "download [BUCKET_NAME]", "Download all files in a bucket to CWD. Or one file."
+  method_options :region => "us-east-1"
+  method_options :one => nil
+  def download(bucket_name)
+    with_bucket bucket_name do |d|
+      if options[:one].nil?
+        if yes?("Are you sure you want to download all files into the CWD?", :red)
+          d.files.each do |s3_file|
+            say("Creating path for and downloading #{s3_file.key}")
+            s3_download(s3_file)
+          end
+        else
+          say("No action taken.")
+        end
+      else
+        s3_file = d.files.get(options[:one])
+        if !s3_file.nil?
+          s3_download(s3_file)
+        else
+          say("Could not find #{options[:one]}. No action taken.")
+        end
+      end
+    end
+  end
+
+  desc "upsync [BUCKET_NAME] [DIRECTORY]", "Push local files matching glob PATTERN into bucket. Ignore unchanged files."
+  method_options :public => false
+  method_options :region => "us-east-1"
+  method_options :noprompt => nil
+  method_options :glob => "**/*"
+  method_options :backups_retain => false
+  method_options :days_retain => 30
+  method_options :months_retain => 3
+  method_options :weeks_retain => 5
+  method_options :dry_run => false
+  def upsync(bucket_name, directory)
+
+    say("This is a dry run.") if options[:dry_run]
+
+    if !File.exists?(directory) || !File.directory?(directory)
+      say("'#{directory} does not exist or is not a directory.")
+      return
+    end
+
+    target_root = Pathname.new(directory)
+
+    files = Dir.glob(target_root.join(options[:glob])).select { |f| !File.directory?(f) }.map(&:to_s)
+    if !options[:backups_retain] && files.count == 0
+      say("No files to upload and no backups retain requested.")
+      return
+    end
+
+    say("Found #{files.count} candidate file upload(s).")
+
+    spn = dn = sn = un = cn = 0
+    with_bucket bucket_name do |d|
+
+      # having a brain fart and cant get this to simplify
+      go = false
+      if options[:noprompt] != nil
+        go = true
+      else
+        go = yes?("Proceed?", :red)
+      end
+
+      if go
+        time_marks = []
+        immediate_successors = {}
+        if options[:backups_retain]
+          # inclusive lower bound, exclusive upper bound
+          time_marks = []
+          Time.now.beginning_of_day.tap do |start|
+            options[:days_retain].times do |i|
+              time_marks.push(start - i.days)
+            end
+          end
+
+          Time.now.beginning_of_week.tap do |start|
+            options[:weeks_retain].times do |i|
+              time_marks.push(start - i.weeks)
+            end
+          end
+
+          Time.now.beginning_of_month.tap do |start|
+            options[:months_retain].times do |i|
+              time_marks.push(start - i.months)
+            end
+          end
+
+          time_marks.each do |tm|
+            files.each do |to_upload|
+              File.open(to_upload) do |localfile|
+                if localfile.mtime >= tm && (immediate_successors[tm].nil? || localfile.mtime < immediate_successors[tm][:last_modified])
+                  immediate_successors[tm] = { :local_path => to_upload, :last_modified => localfile.mtime }
+                end
+              end
+            end
+          end
+        end
+
+        # don't pointlessly upload large files if we already know we're going to delete them!
+        if options[:backups_retain]
+          immediate_successors.values.map { |h| h[:local_path] }.tap do |kept_files|
+            before_reject = files.count # blah...lame
+            files.reject! { |to_upload| !kept_files.include?(to_upload) }
+            sn += before_reject - files.count
+
+            say("Found #{files.count} file(s) that meet backups retention criteria for upload. Comparing against bucket...")
+
+          end
+        end
+
+        files.each do |to_upload|
+          say("#{to_upload} (no output if skipped)...")
+          k = File.basename(to_upload)
+
+          existing_head = d.files.head(k)
+
+          time_mismatch = false
+          content_hash_mistmatched = false
+          File.open(to_upload) do |localfile|
+            time_mismatch = !existing_head.nil? && (existing_head.metadata[LOCAL_MOD_KEY].nil? || (Time.parse(existing_head.metadata[LOCAL_MOD_KEY]) - localfile.mtime).abs > EPSILON)
+            if time_mismatch
+              content_hash_mistmatched = existing_head.etag != content_hash(localfile)
+            end
+          end
+
+          if existing_head && time_mismatch && content_hash_mistmatched
+            if !options[:dry_run]
+              File.open(to_upload) do |localfile|
+                existing_head.metadata = { LOCAL_MOD_KEY => localfile.mtime.to_s }
+                existing_head.body = localfile
+                existing_head.multipart_chunk_size = FILE_BUFFER_SIZE # creates multipart_save
+                existing_head.save
+              end
+            end
+            say("updated.")
+            un += 1
+          elsif existing_head && time_mismatch
+            if !options[:dry_run]
+              File.open(to_upload) do |localfile|
+                existing_head.metadata = { LOCAL_MOD_KEY => localfile.mtime.to_s }
+                existing_head.save
+              end
+            end
+            say("updated.")
+            un += 1
+          elsif existing_head.nil?
+            if !options[:dry_run]
+              fresh_file_upload(to_upload, d, k, options[:public])
+            end
+            say("created.")
+            cn += 1
+          else
+            sn += 1
+            # skipped
+          end
+        end
+
+
+        if options[:backups_retain]
+
+          # This array of hashes is computed because we need to do
+          # nested for loops of M*N complexity, where M=time_marks
+          # and N=files.  We also need to do an remote get call to
+          # fetch the metadata of all N remote files (d.files.each
+          # will not do this). so, for performance sanity, we cache
+          # all the meta data for all the N files.
+          file_keys_modtimes = []
+          d.files.each { |f|
+            if File.fnmatch(options[:glob], f.key)
+              existing_head = d.files.head(f.key)
+              md = existing_head.metadata
+              file_keys_modtimes.push({
+                                        :key => f.key,
+                                        :last_modified => md[LOCAL_MOD_KEY] ? Time.parse(md[LOCAL_MOD_KEY]) : f.last_modified,
+                                        :existing_head => existing_head
+                                      })
+            end
+          }
+
+          say("#{file_keys_modtimes.length} file(s) found to consider for remote retention or remote deletion.")
+
+          # this generates as many 'kept files' as there are time marks...which seems wrong.
+          immediate_successors = {}
+          time_marks.each do |tm|
+            file_keys_modtimes.each do |fkm|
+              if fkm[:last_modified] >= tm && (immediate_successors[tm].nil? || fkm[:last_modified] < immediate_successors[tm][:last_modified])
+                immediate_successors[tm] = fkm
+              end
+            end
+          end
+
+          immediate_successors.values.map { |v| v[:key] }.tap do |kept_keys|
+            file_keys_modtimes.each do |fkm|
+              if kept_keys.include?(fkm[:key])
+                say("Remote retained #{fkm[:key]}.")
+                spn += 1
+              else
+                fkm[:existing_head].destroy if !options[:dry_run]
+                say("Remote deleted #{fkm[:key]}.")
+                dn += 1
+              end
+            end
+          end
+        end
+      else
+        say ("No action taken.")
+      end
+    end
+    say("Done. #{cn} created. #{un} updated. #{sn} local skipped. #{dn} deleted remotely. #{spn} retained remotely.")
+  end
+
+  desc "fdelete [BUCKET_NAME] [FILE_NAME]", "Delete a file in a bucket."
+  method_options :noprompt => false
+  method_options :region => "us-east-1"
+  def fdelete(bucket_name, file_name)
+    d = fog_storage.directories.select { |d| d.key == bucket_name }.first
+
+    if d.nil?
+      say ("Found no bucket by name #{bucket_name}")
+      return
+    end
+
+    f = d.files.select { |f| f.key == file_name }.first
+    if f.nil?
+      say("Found no file in #{d.key} having name #{file_name}.")
+      return
+    end
+
+    if options[:noprompt] || yes?("Are you sure you want to delete #{f.key} in #{d.key}?", :red)
+      f.destroy
+      say "Destroyed #{f.key} in #{d.key}."
+    else
+      say "No action taken."
+    end
+  end
+
+  desc "fupload [BUCKET_NAME] [LOCAL_FILE]", "Upload a file to a bucket. Path to file is ignored."
+  method_options :public => false
+  method_options :region => "us-east-1"
+  def fupload(bucket_name, file_name)
+    d = fog_storage.directories.select { |d| d.key == bucket_name }.first
+
+    if d.nil?
+      say ("Found no bucket by name #{bucket_name}")
+      return
+    end
+
+    if !File.exists?(file_name)
+      say("Found no such file #{file_name} on the local disk.")
+      return
+    end
+
+    key = File.basename(file_name)
+    f = d.files.select { |f| f.key == key }.first
+    if !f.nil? && !yes?("There is already a file named #{key} in #{d.key}. Do you want to overwrite it with this upload?", :red)
+      say("No action taken.")
+      return
+      f.destroy
+      say "Destroyed #{f.key} in #{d.key}."
+    end
+
+    fresh_file_upload(file_name, d, key, options[:public])
+    say "Uploaded #{key} to #{d.key}."
+  end
+
+  desc "delete [BUCKET_NAME]", "Destroy a bucket"
+  method_options :noprompt => false
+  method_options :region => "us-east-1"
+  method_options :deep => false
+  def delete(bucket_name)
+    d = fog_storage.directories.select { |d| d.key == bucket_name }.first
+
+    if d.nil?
+      say ("Found no bucket by name #{bucket_name}")
+      return
+    end
+
+    if options[:noprompt] || yes?("Are you sure you want to delete this bucket #{d.key}?", :red)
+
+      if d.files.length > 0
+        if !options[:deep]
+          say "Bucket has #{d.files.length} files. Please empty before destroying."
+          return
+        end
+
+        found = n_file_heads(d)
+        while found.length > 0
+          found.each do |f|
+            f.destroy
+            say("Deleted file #{f.key}.")
+          end
+          found = n_file_heads(d)
+        end
+      end
+
+      d.destroy
+      say "Destroyed bucket named #{bucket_name}."
+      show_buckets
+    else
+      say "No action taken."
+    end
+
+  end
+
+  desc "create [BUCKET_NAME]", "Create a bucket"
+  method_options :region => "us-east-1"
+  def create(bucket_name = nil)
+    if !bucket_name
+      puts "No bucket name given."
+      return
+    end
+
+    fog_storage.directories.create(
+                                   :key => bucket_name,
+                                   :location => options[:region]
+                                   )
+
+    puts "Created bucket #{bucket_name}."
+    show_buckets
+  end
+
+  desc "show [BUCKET_NAME]", "Show info about bucket"
+  method_options :region => "us-east-1"
+  def show(bucket_name = nil)
+    if !bucket_name
+      puts "No bucket name given."
+      return
+    end
+
+    with_bucket(bucket_name) do |d|
+      say "#{d}: "
+      say d.location
+    end
+  end
+
+end
+