backup_zh 4.0.3.1

data/lib/backup/database/postgresql.rb

@@ -0,0 +1,133 @@
+# encoding: utf-8
+
+module Backup
+  module Database
+    class PostgreSQL < Base
+      class Error < Backup::Error; end
+
+      ##
+      # Name of the database that needs to get dumped.
+      # To dump all databases, set this to `:all` or leave blank.
+      # +username+ must be a PostgreSQL superuser to run `pg_dumpall`.
+      attr_accessor :name
+
+      ##
+      # Credentials for the specified database
+      attr_accessor :username, :password
+
+      ##
+      # If set the pg_dump(all) command is executed as the given user
+      attr_accessor :sudo_user
+
+      ##
+      # Connectivity options
+      attr_accessor :host, :port, :socket
+
+      ##
+      # Tables to skip while dumping the database.
+      # If `name` is set to :all (or not specified), these are ignored.
+      attr_accessor :skip_tables
+
+      ##
+      # Tables to dump. This in only valid if `name` is specified.
+      # If none are given, the entire database will be dumped.
+      attr_accessor :only_tables
+
+      ##
+      # Additional "pg_dump" or "pg_dumpall" options
+      attr_accessor :additional_options
+
+      def initialize(model, database_id = nil, &block)
+        super
+        instance_eval(&block) if block_given?
+
+        @name ||= :all
+      end
+
+      ##
+      # Performs the pgdump command and outputs the dump file
+      # in the +dump_path+ using +dump_filename+.
+      #
+      #   <trigger>/databases/PostgreSQL[-<database_id>].sql[.gz]
+      def perform!
+        super
+
+        pipeline = Pipeline.new
+        dump_ext = 'sql'
+
+        pipeline << (dump_all? ? pgdumpall : pgdump)
+
+        model.compressor.compress_with do |command, ext|
+          pipeline << command
+          dump_ext << ext
+        end if model.compressor
+
+        pipeline << "#{ utility(:cat) } > " +
+            "'#{ File.join(dump_path, dump_filename) }.#{ dump_ext }'"
+
+        pipeline.run
+        if pipeline.success?
+          log!(:finished)
+        else
+          raise Error, "Dump Failed!\n" + pipeline.error_messages
+        end
+      end
+
+      def pgdump
+        "#{ password_option }" +
+        "#{ sudo_option }" +
+        "#{ utility(:pg_dump) } #{ username_option } #{ connectivity_options } " +
+        "#{ user_options } #{ tables_to_dump } #{ tables_to_skip } #{ name }"
+      end
+
+      def pgdumpall
+        "#{ password_option }" +
+        "#{ sudo_option }" +
+        "#{ utility(:pg_dumpall) } #{ username_option } " +
+        "#{ connectivity_options } #{ user_options }"
+      end
+
+      def password_option
+        "PGPASSWORD='#{ password }' " if password
+      end
+
+      def sudo_option
+        "#{ utility(:sudo) } -n -u #{ sudo_user } " if sudo_user
+      end
+
+      def username_option
+        "--username='#{ username }'" if username
+      end
+
+      def connectivity_options
+        return "--host='#{ socket }'" if socket
+
+        opts = []
+        opts << "--host='#{ host }'" if host
+        opts << "--port='#{ port }'" if port
+        opts.join(' ')
+      end
+
+      def user_options
+        Array(additional_options).join(' ')
+      end
+
+      def tables_to_dump
+        Array(only_tables).map do |table|
+          "--table='#{ table }'"
+        end.join(' ')
+      end
+
+      def tables_to_skip
+        Array(skip_tables).map do |table|
+          "--exclude-table='#{ table }'"
+        end.join(' ')
+      end
+
+      def dump_all?
+        name == :all
+      end
+
+    end
+  end
+end

data/lib/backup/database/redis.rb

@@ -0,0 +1,179 @@
+# encoding: utf-8
+
+module Backup
+  module Database
+    class Redis < Base
+      class Error < Backup::Error; end
+
+      MODES = [:copy, :sync]
+
+      ##
+      # Mode of operation.
+      #
+      # [:copy]
+      #   Copies the redis dump file specified by {#rdb_path}.
+      #   This data will be current as of the last RDB Snapshot
+      #   performed by the server (per your redis.conf settings).
+      #   You may set {#invoke_save} to +true+ to have Backup issue
+      #   a +SAVE+ command to update the dump file with the current
+      #   data before performing the copy.
+      #
+      # [:sync]
+      #   Performs a dump of your redis data using +redis-cli --rdb -+.
+      #   Redis implements this internally using a +SYNC+ command.
+      #   The operation is analogous to requesting a +BGSAVE+, then having the
+      #   dump returned. This mode is capable of dumping data from a local or
+      #   remote server. Requires Redis v2.6 or better.
+      #
+      # Defaults to +:copy+.
+      attr_accessor :mode
+
+      ##
+      # Full path to the redis dump file.
+      #
+      # Required when {#mode} is +:copy+.
+      attr_accessor :rdb_path
+
+      ##
+      # Perform a +SAVE+ command using the +redis-cli+ utility
+      # before copying the dump file specified by {#rdb_path}.
+      #
+      # Only valid when {#mode} is +:copy+.
+      attr_accessor :invoke_save
+
+      ##
+      # Connectivity options for the +redis-cli+ utility.
+      attr_accessor :host, :port, :socket
+
+      ##
+      # Password for the +redis-cli+ utility.
+      attr_accessor :password
+
+      ##
+      # Additional options for the +redis-cli+ utility.
+      attr_accessor :additional_options
+
+      def initialize(model, database_id = nil, &block)
+        super
+        instance_eval(&block) if block_given?
+
+        @mode ||= :copy
+
+        unless MODES.include?(mode)
+          raise Error, "'#{ mode }' is not a valid mode"
+        end
+
+        if mode == :copy && rdb_path.nil?
+          raise Error, '`rdb_path` must be set when `mode` is :copy'
+        end
+      end
+
+      ##
+      # Performs the dump based on {#mode} and stores the Redis dump file
+      # to the +dump_path+ using the +dump_filename+.
+      #
+      #   <trigger>/databases/Redis[-<database_id>].rdb[.gz]
+      def perform!
+        super
+
+        case mode
+        when :sync
+          # messages output by `redis-cli --rdb` on $stderr
+          Logger.configure do
+            ignore_warning(/Transfer finished with success/)
+            ignore_warning(/SYNC sent to master/)
+          end
+          sync!
+        when :copy
+          save! if invoke_save
+          copy!
+        end
+
+        log!(:finished)
+      end
+
+      private
+
+      def sync!
+        pipeline = Pipeline.new
+        dump_ext = 'rdb'
+
+        pipeline << "#{ redis_cli_cmd } --rdb -"
+
+        model.compressor.compress_with do |command, ext|
+          pipeline << command
+          dump_ext << ext
+        end if model.compressor
+
+        pipeline << "#{ utility(:cat) } > " +
+            "'#{ File.join(dump_path, dump_filename) }.#{ dump_ext }'"
+
+        pipeline.run
+
+        unless pipeline.success?
+          raise Error, "Dump Failed!\n" + pipeline.error_messages
+        end
+      end
+
+      def save!
+        resp = run("#{ redis_cli_cmd } SAVE")
+        unless resp =~ /OK$/
+          raise Error, <<-EOS
+            Failed to invoke the `SAVE` command
+            Response was: #{ resp }
+          EOS
+        end
+
+      rescue Error
+        if resp =~ /save already in progress/
+          unless (attempts ||= '0').next! == '5'
+            sleep 5
+            retry
+          end
+        end
+        raise
+      end
+
+      def copy!
+        unless File.exist?(rdb_path)
+          raise Error, <<-EOS
+            Redis database dump not found
+            `rdb_path` was '#{ rdb_path }'
+          EOS
+        end
+
+        dst_path = File.join(dump_path, dump_filename + '.rdb')
+        if model.compressor
+          model.compressor.compress_with do |command, ext|
+            run("#{ command } -c '#{ rdb_path }' > '#{ dst_path + ext }'")
+          end
+        else
+          FileUtils.cp(rdb_path, dst_path)
+        end
+      end
+
+      def redis_cli_cmd
+        "#{ utility('redis-cli') } #{ password_option } " +
+        "#{ connectivity_options } #{ user_options }"
+      end
+
+      def password_option
+        "-a '#{ password }'" if password
+      end
+
+      def connectivity_options
+        return "-s '#{ socket }'" if socket
+
+        opts = []
+        opts << "-h '#{ host }'" if host
+        opts << "-p '#{ port }'" if port
+        opts.join(' ')
+      end
+
+      def user_options
+        Array(additional_options).join(' ')
+      end
+
+    end
+  end
+end

data/lib/backup/database/riak.rb

@@ -0,0 +1,82 @@
+# encoding: utf-8
+
+module Backup
+  module Database
+    class Riak < Base
+
+      ##
+      # Node is the node from which to perform the backup.
+      # Default: riak@127.0.0.1
+      attr_accessor :node
+
+      ##
+      # Cookie is the Erlang cookie/shared secret used to connect to the node.
+      # Default: riak
+      attr_accessor :cookie
+
+      ##
+      # Username for the riak instance
+      # Default: riak
+      attr_accessor :user
+
+      def initialize(model, database_id = nil, &block)
+        super
+        instance_eval(&block) if block_given?
+
+        @node   ||= 'riak@127.0.0.1'
+        @cookie ||= 'riak'
+        @user   ||= 'riak'
+      end
+
+      ##
+      # Performs the dump using `riak-admin backup`.
+      #
+      # This will be stored in the final backup package as
+      # <trigger>/databases/<dump_filename>-<node>[.gz]
+      def perform!
+        super
+
+        dump_file = File.join(dump_path, dump_filename)
+        with_riak_owned_dump_path do
+          run("#{ riakadmin } backup #{ node } #{ cookie } '#{ dump_file }' node")
+        end
+
+        model.compressor.compress_with do |command, ext|
+          dump_file << "-#{ node }" # `riak-admin` appends `node` to the filename.
+          run("#{ command } -c '#{ dump_file }' > '#{ dump_file + ext }'")
+          FileUtils.rm_f(dump_file)
+        end if model.compressor
+
+        log!(:finished)
+      end
+
+      private
+
+      ##
+      # The `riak-admin backup` command is run as the riak +user+,
+      # so +user+ must have write priviledges to the +dump_path+.
+      #
+      # Note that the riak +user+ must also have access to +dump_path+.
+      # This means Backup's +tmp_path+ can not be under the home directory of
+      # the user running Backup, since the absence of the execute bit on their
+      # home directory would deny +user+ access.
+      def with_riak_owned_dump_path
+        run("#{ utility(:sudo) } -n #{ utility(:chown) } " +
+            "#{ user } '#{ dump_path }'")
+        yield
+      ensure
+        # reclaim ownership
+        run("#{ utility(:sudo) } -n #{ utility(:chown) } -R " +
+            "#{ Config.user } '#{ dump_path }'")
+      end
+
+      ##
+      # `riak-admin` must be run as the riak +user+.
+      # It will do this itself, but without `-n` and emits a message on STDERR.
+      def riakadmin
+        "#{ utility(:sudo) } -n -u #{ user } #{ utility('riak-admin') }"
+      end
+
+    end
+  end
+end

data/lib/backup/encryptor/base.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+module Backup
+  module Encryptor
+    class Base
+      include Utilities::Helpers
+      include Config::Helpers
+
+      def initialize
+        load_defaults!
+      end
+
+      private
+
+      ##
+      # Return the encryptor name, with Backup namespace removed
+      def encryptor_name
+        self.class.to_s.sub('Backup::', '')
+      end
+
+      ##
+      # Logs a message to the console and log file to inform
+      # the client that Backup is encrypting the archive
+      def log!
+        Logger.info "Using #{ encryptor_name } to encrypt the archive."
+      end
+    end
+  end
+end

data/lib/backup/encryptor/gpg.rb

@@ -0,0 +1,747 @@
+# encoding: utf-8
+
+module Backup
+  module Encryptor
+    ##
+    # The GPG Encryptor allows you to encrypt your final archive using GnuPG,
+    # using one of three {#mode modes} of operation.
+    #
+    # == First, setup defaults in your +config.rb+ file
+    #
+    # Configure the {#keys} Hash using {.defaults} in your +config.rb+
+    # to specify all valid {#recipients} and their Public Key.
+    #
+    #   Backup::Encryptor::GPG.defaults do |encryptor|
+    #     # setup all GnuPG public keys
+    #     encryptor.keys = {}
+    #     encryptor.keys['joe@example.com'] = <<-EOS
+    #       # ...public key here...
+    #     EOS
+    #     encryptor.keys['mary@example.com'] = <<-EOS
+    #       # ...public key here...
+    #     EOS
+    #   end
+    #
+    # The optional {#gpg_config} and {#gpg_homedir} options would also
+    # typically be set using {.defaults} in +config.rb+ as well.
+    #
+    # == Then, setup each of your Models
+    #
+    # Set the desired {#recipients} and/or {#passphrase} (or {#passphrase_file})
+    # for each {Model}, depending on the {#mode} used.
+    #
+    # === my_backup_01
+    #
+    # This archive can only be decrypted using the private key for joe@example.com
+    #
+    #   Model.new(:my_backup_01, 'Backup Job #1') do
+    #     # ... archives, databases, compressor and storage options, etc...
+    #     encrypt_with GPG do |encryptor|
+    #       encryptor.mode = :asymmetric
+    #       encryptor.recipients = 'joe@example.com'
+    #     end
+    #   end
+    #
+    # === my_backup_02
+    #
+    # This archive can only be decrypted using the passphrase "a secret".
+    #
+    #   Model.new(:my_backup_02, 'Backup Job #2') do
+    #     # ... archives, databases, compressor and storage options, etc...
+    #     encrypt_with GPG do |encryptor|
+    #       encryptor.mode = :symmetric
+    #       encryptor.passphrase = 'a secret'
+    #     end
+    #   end
+    #
+    # === my_backup_03
+    #
+    # This archive may be decrypted using either the private key for joe@example.com
+    # *or* mary@example.com, *and* may also be decrypted using the passphrase.
+    #
+    #   Model.new(:my_backup_03, 'Backup Job #3') do
+    #     # ... archives, databases, compressor and storage options, etc...
+    #     encrypt_with GPG do |encryptor|
+    #       encryptor.mode = :both
+    #       encryptor.passphrase = 'a secret'
+    #       encryptor.recipients = ['joe@example.com', 'mary@example.com']
+    #     end
+    #   end
+    #
+    class GPG < Base
+      class Error < Backup::Error; end
+
+      MODES = [:asymmetric, :symmetric, :both]
+
+      ##
+      # Sets the mode of operation.
+      #
+      # [:asymmetric]
+      #   In this mode, the final backup archive will be encrypted using the
+      #   public key(s) specified by the key identifiers in {#recipients}.
+      #   The archive may then be decrypted by anyone with a private key that
+      #   corresponds to one of the public keys used. See {#recipients} and
+      #   {#keys} for more information.
+      #
+      # [:symmetric]
+      #   In this mode, the final backup archive will be encrypted using the
+      #   passphrase specified by {#passphrase} or {#passphrase_file}.
+      #   The archive will be encrypted using the encryption algorithm
+      #   specified in your GnuPG configuration. See {#gpg_config} for more
+      #   information. Anyone with the passphrase may decrypt the archive.
+      #
+      # [:both]
+      #   In this mode, both +:asymmetric+ and +:symmetric+ options are used.
+      #   Meaning that the archive may be decrypted by anyone with a valid
+      #   private key or by using the proper passphrase.
+      #
+      # @param mode [String, Symbol] Sets the mode of operation.
+      #   (Defaults to +:asymmetric+)
+      # @return [Symbol] mode that was set.
+      # @raise [Backup::Errors::Encryptor::GPG::InvalidModeError]
+      #   if mode given is invalid.
+      #
+      attr_reader :mode
+      def mode=(mode)
+        @mode = mode.to_sym
+        raise Error, "'#{ @mode }' is not a valid mode." unless MODES.include?(@mode)
+      end
+
+      ##
+      # Specifies the GnuPG configuration to be used.
+      #
+      # This should be given as the text of a +gpg.conf+ file. It will be
+      # written to a temporary file, which will be passed to the +gpg+ command
+      # to use instead of the +gpg.conf+ found in the GnuPG home directory.
+      # This allows you to be certain your preferences are used.
+      #
+      # This is especially useful if you've also set {#gpg_homedir} and plan
+      # on allowing Backup to automatically create that directory and import
+      # all your public keys specified in {#keys}. In this situation, that
+      # folder would not contain any +gpg.conf+ file, so GnuPG would simply
+      # use it's defaults.
+      #
+      # While this may be specified on a per-Model basis, you would generally
+      # just specify this in the defaults. Leading tabs/spaces are stripped
+      # before writing the given string to the temporary configuration file.
+      #
+      #   Backup::Encryptor::GPG.defaults do |enc|
+      #     enc.gpg_config = <<-EOF
+      #       # safely override preferences set in the receiver's public key(s)
+      #       personal-cipher-preferences TWOFISH AES256 BLOWFISH AES192 CAST5 AES
+      #       personal-digest-preferences SHA512 SHA256 SHA1 MD5
+      #       personal-compress-preferences BZIP2 ZLIB ZIP Uncompressed
+      #       # cipher algorithm for symmetric encryption
+      #       # (if personal-cipher-preferences are not specified)
+      #       s2k-cipher-algo TWOFISH
+      #       # digest algorithm for mangling the symmetric encryption passphrase
+      #       s2k-digest-algo SHA512
+      #     EOF
+      #   end
+      #
+      # @see #gpg_homedir
+      # @return [String]
+      attr_accessor :gpg_config
+
+      ##
+      # Set the GnuPG home directory to be used.
+      #
+      # This allows you to specify the GnuPG home directory on the system
+      # where Backup will be run, keeping the keyrings used by Backup separate
+      # from the default keyrings of the user running Backup.
+      # By default, this would be +`~/.gnupg`+.
+      #
+      # If a directory is specified here, Backup will create it if needed
+      # and ensure the correct permissions are set. All public keys Backup
+      # imports would be added to the +pubring.gpg+ file within this directory,
+      # and +gpg+ would be given this directory using it's +--homedir+ option.
+      #
+      # Any +gpg.conf+ file located in this directory would also be used by
+      # +gpg+, unless {#gpg_config} is specified.
+      #
+      # The given path will be expanded before use.
+      #
+      # @return [String]
+      attr_accessor :gpg_homedir
+
+      ##
+      # Specifies a Hash of public key identifiers and their public keys.
+      #
+      # While not _required_, it is recommended that all public keys you intend
+      # to use be setup in {#keys}. The best place to do this is in your defaults
+      # in +config.rb+.
+      #
+      #   Backup::Encryptor::GPG.defaults do |enc|
+      #     enc.keys = {}
+      #
+      #     enc.keys['joe@example.com'] = <<-EOS
+      #       -----BEGIN PGP PUBLIC KEY BLOCK-----
+      #       Version: GnuPG v1.4.12 (GNU/Linux)
+      #
+      #       mQMqBEd5F8MRCACfArHCJFR6nkmxNiW+UE4PAW3bQla9JWFqCwu4VqLkPI/lHb5p
+      #       xHff8Fzy2O89BxD/6hXSDx2SlVmAGHOCJhShx1vfNGVYNsJn2oNK50in9kGvD0+m
+      #       [...]
+      #       SkQEHOxhMiFjAN9q4LuirSOu65uR1bnTmF+Z92++qMIuEkH4/LnN
+      #       =8gNa
+      #       -----END PGP PUBLIC KEY BLOCK-----
+      #     EOS
+      #
+      #     enc.keys['mary@example.com'] = <<-EOS
+      #       -----BEGIN PGP PUBLIC KEY BLOCK-----
+      #       Version: GnuPG v1.4.12 (GNU/Linux)
+      #
+      #       2SlVmAGHOCJhShx1vfNGVYNxHff8Fzy2O89BxD/6in9kGvD0+mhXSDxsJn2oNK50
+      #       kmxNiW+UmQMqBEd5F8MRCACfArHCJFR6qCwu4VqLkPI/lHb5pnE4PAW3bQla9JWF
+      #       [...]
+      #       AN9q4LSkQEHOxhMiFjuirSOu65u++qMIuEkH4/LnNR1bnTmF+Z92
+      #       =8gNa
+      #       -----END PGP PUBLIC KEY BLOCK-----
+      #
+      #     EOS
+      #   end
+      #
+      # All leading spaces/tabs will be stripped from the key, so the above
+      # form may be used to set each identifier's key.
+      #
+      # When a public key can not be found for an identifier specified in
+      # {#recipients}, the corresponding public key from this Hash will be
+      # imported into +pubring.gpg+ in the GnuPG home directory ({#gpg_homedir}).
+      # Therefore, each key *must* be the same identifier used in {#recipients}.
+      #
+      # To obtain the public key in ASCII format, use:
+      #
+      #   $ gpg -a --export joe@example.com
+      #
+      # See {#recipients} for information on what may be used as valid identifiers.
+      #
+      # @return [Hash]
+      attr_accessor :keys
+
+      ##
+      # Specifies the recipients to use when encrypting the backup archive.
+      #
+      # When {#mode} is set to +:asymmetric+ or +:both+, the public key for
+      # each recipient given here will be used to encrypt the archive. Each
+      # recipient will be able to decrypt the archive using their private key.
+      #
+      # If there is only one recipient, this may be specified as a String.
+      # Otherwise, this should be an Array of Strings. Each String must be a
+      # valid public key identifier, and *must* be the same identifier used to
+      # specify the recipient's public key in {#keys}. This is so that if a
+      # public key is not found for the given identifier, it may be imported
+      # from {#keys}.
+      #
+      # Valid identifiers which may be used are as follows:
+      #
+      # [Key Fingerprint]
+      #   The key fingerprint is a 40-character hex string, which uniquely
+      #   identifies a public key. This may be obtained using the following:
+      #
+      #     $ gpg --fingerprint john.smith@example.com
+      #     pub   1024R/4E5E8D8A 2012-07-20
+      #     Key fingerprint = FFEA D1DB 201F B214 873E  7399 4A83 569F 4E5E 8D8A
+      #     uid                  John Smith <john.smith@example.com>
+      #     sub   1024R/92C8DFD8 2012-07-20
+      #
+      # [Long Key ID]
+      #   The long Key ID is the last 16-characters of the key's fingerprint.
+      #
+      #   The Long Key ID in this example is: 4A83569F4E5E8D8A
+      #
+      #     $ gpg --keyid-format long -k john.smith@example.com
+      #     pub   1024R/4A83569F4E5E8D8A 2012-07-20
+      #     uid                          John Smith <john.smith@example.com>
+      #     sub   1024R/662F18DB92C8DFD8 2012-07-20
+      #
+      # [Short Key ID]
+      #   The short Key ID is the last 8-characters of the key's fingerprint.
+      #   This is the default key format seen when listing keys.
+      #
+      #   The Short Key ID in this example is: 4E5E8D8A
+      #
+      #     $ gpg -k john.smith@example.com
+      #     pub   1024R/4E5E8D8A 2012-07-20
+      #     uid                  John Smith <john.smith@example.com>
+      #     sub   1024R/92C8DFD8 2012-07-20
+      #
+      # [Email Address]
+      #   This must exactly match an email address for one of the UID records
+      #   associated with the recipient's public key.
+      #
+      # Recipient identifier forms may be mixed, as long as the identifier used
+      # here is the same as that used in {#keys}. Also, all spaces will be stripped
+      # from the identifier when used, so the following would be valid.
+      #
+      #   Backup::Model.new(:my_backup, 'My Backup') do
+      #     encrypt_with GPG do |enc|
+      #       enc.recipients = [
+      #         # John Smith
+      #         '4A83 569F 4E5E 8D8A',
+      #         # Mary Smith
+      #         'mary.smith@example.com'
+      #       ]
+      #     end
+      #   end
+      #
+      # @return [String, Array]
+      attr_accessor :recipients
+
+      ##
+      # Specifies the passphrase to use symmetric encryption.
+      #
+      # When {#mode} is +:symmetric+ or +:both+, this passphrase will be used
+      # to symmetrically encrypt the archive.
+      #
+      # Use of this option will override the use of {#passphrase_file}.
+      #
+      # @return [String]
+      attr_accessor :passphrase
+
+      ##
+      # Specifies the passphrase file to use symmetric encryption.
+      #
+      # When {#mode} is +:symmetric+ or +:both+, this file will be passed
+      # to the +gpg+ command line, where +gpg+ will read the first line from
+      # this file and use it for the passphrase.
+      #
+      # The file path given here will be expanded to a full path.
+      #
+      # If {#passphrase} is specified, {#passphrase_file} will be ignored.
+      # Therefore, if you have set {#passphrase} in your global defaults,
+      # but wish to use {#passphrase_file} with a specific {Model}, be sure
+      # to clear {#passphrase} within that model's configuration.
+      #
+      #   Backup::Encryptor::GPG.defaults do |enc|
+      #     enc.passphrase = 'secret phrase'
+      #   end
+      #
+      #   Backup::Model.new(:my_backup, 'My Backup') do
+      #     # other directives...
+      #     encrypt_with GPG do |enc|
+      #       enc.mode = :symmetric
+      #       enc.passphrase = nil
+      #       enc.passphrase_file = '/path/to/passphrase.file'
+      #     end
+      #   end
+      #
+      # @return [String]
+      attr_accessor :passphrase_file
+
+      ##
+      # Configures default accessor values for new class instances.
+      #
+      # If all required options are set, then no further configuration
+      # would be needed within a Model's definition when an Encryptor is added.
+      # Therefore, the following example is sufficient to encrypt +:my_backup+:
+      #
+      #   # Defaults set in config.rb
+      #   Backup::Encryptor::GPG.defaults do |encryptor|
+      #     encryptor.keys = {}
+      #     encryptor.keys['joe@example.com'] = <<-EOS
+      #       -----BEGIN PGP PUBLIC KEY BLOCK-----
+      #       Version: GnuPG v1.4.12 (GNU/Linux)
+      #
+      #       mI0EUBR6CwEEAMVSlFtAXO4jXYnVFAWy6chyaMw+gXOFKlWojNXOOKmE3SujdLKh
+      #       kWqnafx7VNrb8cjqxz6VZbumN9UgerFpusM3uLCYHnwyv/rGMf4cdiuX7gGltwGb
+      #       (...etc...)
+      #       mLekS3xntUhhgHKc4lhf4IVBqG4cFmwSZ0tZEJJUSESb3TqkkdnNLjE=
+      #       =KEW+
+      #       -----END PGP PUBLIC KEY BLOCK-----
+      #     EOS
+      #
+      #     encryptor.recipients = 'joe@example.com'
+      #   end
+      #
+      #   # Encryptor set in the model
+      #   Backup::Model.new(:my_backup, 'My Backup') do
+      #     # archives, storage options, etc...
+      #     encrypt_with GPG
+      #   end
+      #
+      # @!scope class
+      # @see Config::Helpers::ClassMethods#defaults
+      # @yield [config] OpenStruct object
+      # @!method defaults
+
+      ##
+      # Creates a new instance of Backup::Encryptor::GPG.
+      #
+      # This constructor is not used directly when configuring Backup.
+      # Use {Model#encrypt_with}.
+      #
+      #   Model.new(:backup_trigger, 'Backup Label') do
+      #     archive :my_archive do |archive|
+      #       archive.add '/some/directory'
+      #     end
+      #
+      #     compress_with Gzip
+      #
+      #     encrypt_with GPG do |encryptor|
+      #       encryptor.mode = :both
+      #       encryptor.passphrase = 'a secret'
+      #       encryptor.recipients = ['joe@example.com', 'mary@example.com']
+      #     end
+      #
+      #     store_with SFTP
+      #
+      #     notify_by Mail
+      #   end
+      #
+      # @api private
+      def initialize(&block)
+        super
+
+        instance_eval(&block) if block_given?
+
+        @mode ||= :asymmetric
+      end
+
+      ##
+      # This is called as part of the procedure run by the Packager.
+      # It sets up the needed options to pass to the gpg command,
+      # then yields the command to use as part of the packaging procedure.
+      # Once the packaging procedure is complete, it will return
+      # so that any clean-up may be performed after the yield.
+      # Cleanup is also ensured, as temporary files may hold sensitive data.
+      # If no options can be built, the packaging process will be aborted.
+      #
+      # @api private
+      def encrypt_with
+        log!
+        prepare
+
+        if mode_options.empty?
+          raise Error, "Encryption could not be performed for mode '#{ mode }'"
+        end
+
+        yield "#{ utility(:gpg) } #{ base_options } #{ mode_options }", '.gpg'
+
+      ensure
+        cleanup
+      end
+
+      private
+
+      ##
+      # Remove any temporary directories and reset all instance variables.
+      #
+      def prepare
+        FileUtils.rm_rf(@tempdirs, :secure => true) if @tempdirs
+        @tempdirs = []
+        @base_options = nil
+        @mode_options = nil
+        @user_recipients = nil
+        @user_keys = nil
+        @system_identifiers = nil
+      end
+      alias :cleanup :prepare
+
+      ##
+      # Returns the options needed for the gpg command line which are
+      # not dependant on the #mode. --no-tty supresses output of certain
+      # messages, like the "Reading passphrase from file descriptor..."
+      # messages during symmetric encryption
+      #
+      def base_options
+        @base_options ||= begin
+          opts = ['--no-tty']
+          path = setup_gpg_homedir
+          opts << "--homedir '#{ path }'" if path
+          path = setup_gpg_config
+          opts << "--options '#{ path }'" if path
+          opts.join(' ')
+        end
+      end
+
+      ##
+      # Setup the given :gpg_homedir if needed, ensure the proper permissions
+      # are set, and return the directory's path. Otherwise, return false.
+      #
+      # If the GnuPG files do not exist, trigger their creation by requesting
+      # --list-secret-keys. Some commands, like for symmetric encryption, will
+      # issue messages about their creation on STDERR, which generates unwanted
+      # warnings in the log. This way, if any of these files are created here,
+      # we will get those messages on STDOUT for the log, without the actual
+      # secret key listing which we don't care about.
+      #
+      def setup_gpg_homedir
+        return false unless gpg_homedir
+
+        path = File.expand_path(gpg_homedir)
+        FileUtils.mkdir_p(path)
+        FileUtils.chown(Config.user, nil, path)
+        FileUtils.chmod(0700, path)
+
+        unless %w{ pubring.gpg secring.gpg trustdb.gpg }.
+            all? {|name| File.exist? File.join(path, name) }
+          run("#{ utility(:gpg) } --homedir '#{ path }' -K 2>&1 >/dev/null")
+        end
+
+        path
+
+      rescue => err
+        raise Error.wrap(
+            err, "Failed to create or set permissions for #gpg_homedir")
+      end
+
+      ##
+      # Write the given #gpg_config to a tempfile, within a tempdir, and
+      # return the file's path to be given to the gpg --options argument.
+      # If no #gpg_config is set, return false.
+      #
+      # This is required in order to set the proper permissions on the
+      # directory containing the tempfile. The tempdir will be removed
+      # after the packaging procedure is completed.
+      #
+      # Once written, we'll call check_gpg_config to make sure there are
+      # no problems that would prevent gpg from running with this config.
+      # If any errors occur during this process, we can not proceed.
+      # We'll cleanup to remove the tempdir (if created) and raise an error.
+      #
+      def setup_gpg_config
+        return false unless gpg_config
+
+        dir = Dir.mktmpdir('backup-gpg_config', Config.tmp_path)
+        @tempdirs << dir
+        file = Tempfile.open('backup-gpg_config', dir)
+        file.write gpg_config.gsub(/^[[:blank:]]+/, '')
+        file.close
+
+        check_gpg_config(file.path)
+
+        file.path
+
+      rescue => err
+        cleanup
+        raise Error.wrap(err, "Error creating temporary file for #gpg_config.")
+      end
+
+      ##
+      # Make sure the temporary GnuPG config file created from #gpg_config
+      # does not have any syntax errors that would prevent gpg from running.
+      # If so, raise the returned error message.
+      # Note that Cli::Helpers#run may also raise an error here.
+      #
+      def check_gpg_config(path)
+        ret = run(
+          "#{ utility(:gpg) } --options '#{ path }' --gpgconf-test 2>&1"
+        ).chomp
+        raise ret unless ret.empty?
+      end
+
+      ##
+      # Returns the options needed for the gpg command line to perform
+      # the encryption based on the #mode.
+      #
+      def mode_options
+        @mode_options ||= begin
+          s_opts = symmetric_options if mode != :asymmetric
+          a_opts = asymmetric_options if mode != :symmetric
+          [s_opts, a_opts].compact.join(' ')
+        end
+      end
+
+      ##
+      # Process :passphrase or :passphrase_file and return the command line
+      # options to perform symmetric encryption. If no :passphrase is
+      # specified, or an error occurs creating a temporary file for it, then
+      # try to use :passphrase_file if it's set.
+      # If the option can not be set, log a warning and return nil.
+      #
+      def symmetric_options
+        path = setup_passphrase_file
+        unless path || passphrase_file.to_s.empty?
+          path = File.expand_path(passphrase_file.to_s)
+        end
+
+        if path && File.exist?(path)
+          "-c --passphrase-file '#{ path }'"
+        else
+          Logger.warn("Symmetric encryption options could not be set.")
+          nil
+        end
+      end
+
+      ##
+      # Create a temporary file, within a tempdir, to hold the :passphrase and
+      # return the file's path. If an error occurs, log a warning.
+      # Return false if no :passphrase is set or an error occurs.
+      #
+      def setup_passphrase_file
+        return false if passphrase.to_s.empty?
+
+        dir = Dir.mktmpdir('backup-gpg_passphrase', Config.tmp_path)
+        @tempdirs << dir
+        file = Tempfile.open('backup-gpg_passphrase', dir)
+        file.write passphrase.to_s
+        file.close
+
+        file.path
+
+      rescue => err
+        Logger.warn Error.wrap(err, "Error creating temporary passphrase file.")
+        false
+      end
+
+      ##
+      # Process :recipients, importing their public key from :keys if needed,
+      # and return the command line options to perform asymmetric encryption.
+      # Log a warning and return nil if no valid recipients are found.
+      #
+      def asymmetric_options
+        if user_recipients.empty?
+          Logger.warn "No recipients available for asymmetric encryption."
+          nil
+        else
+          # skip trust database checks
+          "-e --trust-model always " +
+              user_recipients.map {|r| "-r '#{ r }'" }.join(' ')
+        end
+      end
+
+      ##
+      # Returns an Array of the public key identifiers the user specified
+      # in :recipients. Each identifier is 'cleaned' so that exact matches
+      # can be performed. Then each is checked to ensure it will find a
+      # public key that exists in the system's public keyring.
+      # If the identifier does not match an existing key, the public key
+      # associated with the identifier in :keys will be imported for use.
+      # If no key can be found in the system or in :keys for the identifier,
+      # a warning will be issued; as we will attempt to encrypt the backup
+      # and proceed if at all possible.
+      #
+      def user_recipients
+        @user_recipients ||= begin
+          [recipients].flatten.compact.map do |identifier|
+            identifier = clean_identifier(identifier)
+            if system_identifiers.include?(identifier)
+              identifier
+            else
+              key = user_keys[identifier]
+              if key
+                # will log a warning and return nil if the import fails
+                import_key(identifier, key)
+              else
+                Logger.warn(
+                  "No public key was found in #keys for '#{ identifier }'"
+                )
+                nil
+              end
+            end
+          end.compact
+        end
+      end
+
+      ##
+      # Returns the #keys hash set by the user with all identifiers
+      # (Hash keys) 'cleaned' for exact matching. If the cleaning process
+      # creates duplicate keys, the user will be warned.
+      #
+      def user_keys
+        @user_keys ||= begin
+          _keys = keys || {}
+          ret = Hash[_keys.map {|k,v| [clean_identifier(k), v] }]
+          Logger.warn(
+            "Duplicate public key identifiers were detected in #keys."
+          ) if ret.keys.count != _keys.keys.count
+          ret
+        end
+      end
+
+      ##
+      # Cleans a public key identifier.
+      # Strip out all spaces, upcase non-email identifiers,
+      # and wrap email addresses in <> to perform exact matching.
+      #
+      def clean_identifier(str)
+        str = str.to_s.gsub(/[[:blank:]]+/, '')
+        str =~ /@/ ? "<#{ str.gsub(/(<|>)/,'') }>" : str.upcase
+      end
+
+      ##
+      # Import the given public key and return the 16 character Key ID.
+      # If the import fails, return nil.
+      # Note that errors raised by Cli::Helpers#run may also be rescued here.
+      #
+      def import_key(identifier, key)
+        file = Tempfile.open('backup-gpg_import', Config.tmp_path)
+        file.write(key.gsub(/^[[:blank:]]+/, ''))
+        file.close
+        ret = run(
+          "#{ utility(:gpg) } #{ base_options } " +
+          "--keyid-format 0xlong --import '#{ file.path }' 2>&1"
+        )
+        file.delete
+
+        keyid = ret.match(/ 0x(\w{16})/).to_a[1]
+        raise "GPG Returned:\n#{ ret.gsub(/^\s*/, '  ') }" unless keyid
+        keyid
+
+      rescue => err
+        Logger.warn Error.wrap(
+            err, "Public key import failed for '#{ identifier }'")
+        nil
+      end
+
+      ##
+      # Parse the information for all the public keys found in the public
+      # keyring (based on #gpg_homedir setting) and return an Array of all
+      # identifiers which could be used to specify a valid key.
+      #
+      def system_identifiers
+        @system_identifiers ||= begin
+          skip_key = false
+          data = run(
+            "#{ utility(:gpg) } #{ base_options } " +
+            "--with-colons --fixed-list-mode --fingerprint"
+          )
+          data.lines.map do |line|
+            line.strip!
+
+            # process public key record
+            if line =~ /^pub:/
+              validity, keyid, capabilities =
+                  line.split(':').values_at(1, 4, 11)
+              # skip keys marked as revoked ('r'), expired ('e'),
+              # invalid ('i') or disabled ('D')
+              if validity[0,1] =~ /(r|e|i)/ || capabilities =~ /D/
+                skip_key = true
+                next nil
+              else
+                skip_key = false
+                # return both the long and short id
+                next [keyid[-8..-1], keyid]
+              end
+            else
+              # wait for the next valid public key record
+              next nil if skip_key
+
+              # process UID records for the current public key
+              if line =~ /^uid:/
+                validity, userid = line.split(':').values_at(1, 9)
+                # skip records marked as revoked ('r'), expired ('e')
+                # or invalid ('i')
+                if validity !~ /(r|e|i)/
+                  # return the last email found in user id string,
+                  # since this includes user supplied comments.
+                  # return nil if no email found.
+                  email, str = nil, userid
+                  while match = str.match(/<.+?@.+?>/)
+                    email, str = match[0], match.post_match
+                  end
+                  next email
+                end
+              # return public key's fingerprint
+              elsif line =~ /^fpr:/
+                next line.split(':')[9]
+              end
+
+              nil # ignore any other lines
+            end
+          end.flatten.compact
+        end
+      end
+
+    end
+  end
+end