doable 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8049e12988f84644e8ad77af4aa81c69586cd584
-  data.tar.gz: cdde8ea4ff303b1cdd1407ce2a45f4155fad67f4
+  metadata.gz: 12cd4bee334b582b69a835051c8cfeb0314aa3e3
+  data.tar.gz: 84db114358f2ea2f7511900421206ed8ddcbe9d5
 SHA512:
-  metadata.gz: 8e5e57273ae3eb3a16aafa7992a2513bc7eefada445a1feac54d53e55a4633001eeed83b7a7967a3dbced96d7868a7fb041db469c5ed968763c4023a2a2f8af4
-  data.tar.gz: e13885ee5299ae731b16a9d1c83ec4868994a66cd2ed57e5bd0a8372b7758a3645e12c95e5ad4d0eab946e84d42c71af7da200b6d41caef7ccf20bebc9f56074
+  metadata.gz: 380841e88c0f7dcf73a6d9a85bf6d3bdb0941a519f8072e0957515c42a38b224fc3e8be81ed6be0b4c338a7ae071f3c55228f0877fb634bfb8322cf7c69f4745
+  data.tar.gz: 56aea29e8c7bfd238d806d8953ab456ef13239b9ec019d2316b22be8e2a747bf9620106a3f686d7d429c4446d79ef41e2b7adfec0e98ba8de829596deabdfccd

data/lib/doable/exceptions/framework.rb

@@ -1,21 +1,21 @@
 module Doable
   module Exceptions
     module Framework
+      # Exception to be thrown when nothing else applies. Inherited by other exceptions.
       class GenericFrameworkError < StandardError
       end
 
+      # When the provided parameters or other input is not valid.
       class InvalidInput < GenericFrameworkError
       end
 
+      # Correct number of parameters is passed but it is not of the correct type.
+      # i.e., type error in strongly typed languages
       class NotApplicable < InvalidInput
       end
 
-      class InvalidAction < GenericFrameworkError
-      end
-
-      class MissingDefinitionsDirectory < GenericFrameworkError
-      end
-
+      # This can be called when a helper method is expecting a parameter that wasn't passed.
+      # i.e., an options hash doesn't contain the requisite elements. 
       class MissingParameter < InvalidInput
       end
 
@@ -24,11 +24,13 @@ module Doable
       end
 
       # !These exceptions should never be caught by anything!
+      # This is an internal exception used primarily for logging purposes. Provides a clean way to log 
       class SkipStep < StandardError
       end
 
+      # Allows the the application to notify the completion of a Rollback and that the job object was not successfully executed. 
       class RolledBack < StandardError
       end
     end
   end
-end
+end

data/lib/doable/exceptions/linux.rb

@@ -0,0 +1,11 @@
+module Doable
+  module Exceptions
+    module Linux
+      class MissingRPMs < StandardError
+      end
+
+      class InvalidRPMList < StandardError
+      end
+    end
+  end
+end

data/lib/doable/exceptions/os.rb

@@ -1,6 +1,8 @@
 module Doable
   module Exceptions
+    # Exceptions which are agnostic to the underlying OS.
     module OS
+      # Generic exception to be inherited by all other OS-level exceptions.
       class OSException < GenericFrameworkError
       end
 
@@ -16,8 +18,50 @@ module Doable
       class InvalidHostname < OSException
       end
 
+      class FailedPasswordChange < OSException
+      end
+
       class MissingFile < OSException
       end
+
+      class MissingExecutable < OSException
+      end
+
+      class FailedCopy < OSException
+      end
+
+      class NotApplicable < OSException
+      end
+
+      class DuplicateUsers < OSException
+      end
+
+      class DuplicateGroups < OSException
+      end
+
+      class WrongHomedir < OSException
+      end
+
+      class InvalidArchitecture < OSException
+      end
+
+      class MissingUser < OSException
+      end
+
+      class WrongUser < OSException
+      end
+
+      class FailedGroupAdd < OSException
+      end
+
+      class FailedUserModification < OSException
+      end
+
+      class FailedUncompress < OSException
+      end
+
+      class AmbiguousProcess < OSException
+      end
     end
   end
-end
+end

data/lib/doable/helpers/linux.rb

@@ -0,0 +1,296 @@
+require 'doable/helpers/os'
+require 'doable/exceptions/linux'
+
+module Doable
+  module Helpers
+    module Linux
+      include OS
+      include Exceptions::Linux
+      # Used like Unix chown
+      # @param user [String] User to set as the owner
+      # @param group [String] Group to set as the owner
+      # @param file_list [Array<String>,String] List of files to change the owner of
+      def chown(user, group, file_list, options = {recursive: false})
+        if options[:recursive]
+          options.delete :recursive
+          FileUtils.chown_R(user, group, file_list, options)
+        else
+          options.delete(:recursive) if options.has_key?(:recursive)
+          FileUtils.chown(user, group, file_list, options)
+        end
+      end
+
+      # Used like Unix chmod
+      # @param permission [String, Fixnum] Permissions to set
+      # @param file_list [Array<String>,String] List of files to change the permissions of
+      def chmod(permission, file_list, options = {recursive: false})
+        if options[:recursive]
+          options.delete :recursive
+          FileUtils.chmod_R(permission, file_list, options)
+        else
+          options.delete(:recursive) if options.has_key?(:recursive)
+          FileUtils.chmod(permission, file_list, options)
+        end
+      end
+
+      # Apply a patch file
+      # @param options [String] Options to be added to the `patch` system command
+      # @param patch_file [String] Path to the patch file to apply
+      # @param path [String] Optionally cd to this directory before patching
+      # @param user [String] Optionally apply patch as this user
+      def apply_patch(options, patch_file, path = nil, user = nil)
+        cmd = "patch #{options} < #{patch_file}"
+    
+        olddir = `pwd`.chomp
+        Dir.chdir(path) if path
+        tee 'pwd'
+        if user
+          run_as_user user, cmd
+        else
+          tee cmd
+        end
+        Dir.chdir(olddir) if path
+      end
+
+      # Add an entry to a user's ~/.bashrc
+      # @param user [String] User to add bashrc entries to
+      # @param entry [String] Entry to add to user's .bashrc
+      def add_bashrc_entry(user, entry)
+        File.open(File.expand_path("~#{user}/.bashrc"), "a") {|f| f.puts entry }
+      end
+
+      # Get a list of process matching a Regexp
+      # @param regex [Regexp] Regular expression to use for finding processes
+      # @return [Array<String>] Array of PIDs that match the regex
+      def find_processes(regex)
+        `ps aux`.chomp.split("\n").map {|l| l.split(nil, 11) }.collect {|p| p if p[10].match(regex)}.compact
+      end
+
+      # Kill a process
+      # @param pid [Fixnum,String] PID to kill
+      # @param signal [String] Signal to kill PID with
+      def kill(pid, signal = "TERM")
+        Process.kill(signal, pid)
+      end
+
+      # Does the system have an executable in $PATH? If not, return false.
+      # @param name [String] Executable to verify
+      # @return [String, false]
+      def have_executable?(name)
+        app_path = `which #{name}`.chomp
+        if app_path.match(name)
+          return app_path
+        else
+          return false
+        end
+      end
+
+      # Require an executable to be in $PATH
+      # @raise [MissingExecutable]
+      # @param name [String] Required executable
+      def find_executable(name)
+        have_executable?(name) ? true : raise(MissingExecutable, name)
+      end
+
+      # Check for RPMs (kind of RHEL / SuSE specific)
+      # @raise [InvalidRPMList]
+      # @raise [NotApplicable]
+      # @raise [MissingRPMs]
+      # @param rpms [Array<String>] RPMs to verify
+      # #return [Boolean]
+      def check_for_rpms(rpms)
+        raise InvalidRPMList unless rpms.kind_of?(Array)
+        # Split the list of all installed RPMs into an Array containing only the RPM's base name
+        system_rpms = `rpm -qa`.chomp.split("\n").collect {|rpm| rpm.split(/-[0-9]/)[0]}
+        i686_rpms = `rpm -qa`.chomp.split("\n").collect {|rpm| rpm.split(/-[0-9]/)[0] if rpm.match(/\.i686$/)}.compact
+        raise NotApplicable unless $?.success?
+        missing_rpms = rpms.collect {|rpm| rpm unless rpm.match(/\.i686$/) }.compact - system_rpms  # calculate what RPMs are not installed
+        missing_rpms = (missing_rpms + (rpms.collect {|rpm| rpm.split('.')[0] if rpm.match(/\.i686$/) }.compact - i686_rpms).compact.map {|r| "#{r}.i686" } ).compact
+        if missing_rpms.size > 0
+          log "Missing RPMs: #{missing_rpms.join(', ')}", :error
+          raise MissingRPMs
+        else
+          return true
+        end
+      end
+
+      # Ensure a user exists on the system
+      # @raise [DuplicateUsers]
+      # @raise [WrongHomedir]
+      # @param user [String] User to add or verify
+      # @param homedir [String] User home directory
+      # @return [Boolean]
+      def find_or_create_user(user, homedir, options = {})
+        # Create an Array of Arrays storing all known system users and their attributes
+        all_users = `getent passwd`.chomp.split("\n").map {|line| line.split(':')}
+        # Determine if the user we want exists
+        this_user = all_users.collect {|u| u if u[0] == user}.compact
+        if this_user.size > 1
+          log "Multiple instances of user #{user} found. This is known to cause problems.", :error
+          raise DuplicateUsers
+        elsif this_user.size == 1
+          log "User '#{user}' already exists with uid: #{this_user.flatten[2]}. Skipping creation of user...", :warn
+          full_home = File.expand_path(homedir)
+          current_home = File.expand_path(this_user.flatten[5])
+          if (full_home != current_home) and (homedir != current_home)
+            log "User's home directory is set to #{current_home}, not #{homedir}!", :error
+            raise WrongHomedir
+          end
+        else
+          log "Creating #{user} user..."
+          shell = options[:shell] ? options[:shell] : '/bin/bash'
+          `useradd -d "#{homedir}" -s "#{shell}" -mr "#{user}"`
+        end
+ 		
+        return true
+      end
+
+      # Sets a user's password
+      # @note This _may_ only work on RHEL (and the like), as chpasswd may not be available on other OS's
+      # @raise [FailedPasswordChange]
+      # @param user [String] User to set password for
+      # @param new_pass [String] New password for user
+      # @return [Boolean]
+      def set_user_password(user, new_pass)
+        log "Setting password for #{user}..."
+        `echo "#{user}:#{new_pass}" | chpasswd`
+        raise FailedPasswordChange unless $?.success?
+        return $?.success?
+      end
+
+      # Die if a user doesn't exist
+      # @raise [DuplicateUsers]
+      # @raise [MissingUser]
+      # @param user [String] User to verify
+      # @param noisy [Boolean] Should extra info be logged?
+      # @return [Array]
+      def find_user(user, noisy = false)
+        # Create an Array of Arrays storing all known system users and their attributes
+        all_users = `getent passwd`.chomp.split("\n").map {|line| line.split(':')}
+        # Determine if the user we want exists
+        this_user = all_users.collect {|u| u if u[0] == user}.compact
+        if this_user.size > 1
+          log "Multiple instances of user #{user} found. This is known to cause problems.", :error
+          raise DuplicateUsers
+        elsif this_user.size < 1
+          log "Missing Critical User '#{user}'!", :error
+          raise MissingUser
+        else
+          log "Found required user '#{user}' with uid #{this_user.flatten[2]}..." if noisy
+        end
+        return this_user.flatten
+      end
+
+      # Ensure a group exists
+      # @raise [DuplicateGroups]
+      # @raise [FailedGroupAdd]
+      # @param group [String] Group to create or verify
+      # @return [Boolean]
+      def find_or_create_group(group)
+        all_groups = `getent group`.chomp.split("\n").map {|line| line.split(':')}
+        this_group = all_groups.collect {|g| g if g[0] == group}.compact
+        if this_group.size > 1
+          log "Multiple instances of group #{group} found. This is known to cause problems.", :error
+          raise DuplicateGroups
+        elsif this_group.size == 1
+          log "Group '#{group}' already exists with gid: #{this_group.flatten[2]}. Skipping creation of group...", :warn
+        else
+          log "Creating group '#{group}'..."
+          `groupadd -r "#{group}"`
+          raise FailedGroupAdd unless $?.success?
+          return $?.success?
+        end
+      end
+
+      # Set a user's gid (default group)
+      # @raise [FailedUserModification]
+      # @param user [String] User to update
+      # @param gid [String,Fixnum] Group to set as default for user
+      def update_user_gid(user, gid)
+        user_details = find_user(user)
+        if user_details[3] != gid
+          log "Setting default group for #{user} to #{gid}..."
+          `usermod -g #{gid} "#{user}"`
+          raise FailedUserModification unless $?.success?
+          log "Fixing permissions..."
+          `chown -R #{user}:#{gid} "#{user_details[5]}"`
+        end
+        return gid
+      end
+
+      # Finds the mount point for a directory, then checks it for a minimum number of kilobytes
+      # @param install_dir [String] Directory from which check starts
+      # @param min_space [Fixnum] Minumum amount of space required on mount-point discovered from install_dir
+      def check_disk_space(install_dir, min_space)
+        all_filesystems = `df -PB 1024`.chomp.split("\n").collect {|fs| fs.split if fs.match(/^\/dev/) }.compact
+        best_fit = nil
+        current_test = install_dir
+        until best_fit
+          matching_fs = all_filesystems.collect {|fs| fs if File.expand_path(fs[5]) == File.expand_path(current_test) }.compact
+          if matching_fs.size == 1
+            best_fit = matching_fs.flatten
+          else
+            current_test = File.dirname(current_test)
+          end
+        end
+
+        log "Closest matching filesystem is '#{best_fit[5]}'. Testing for free space..."
+        if Integer(best_fit[3]) >= min_space
+          log "Found sufficient space #{best_fit[3]} for install on #{best_fit[5]} with an install directory of #{install_dir}."
+        else
+          log "Insufficient space #{best_fit[3]} for install on #{best_fit[5]} with an install directory of #{install_dir}!", :error
+        end
+      end
+
+      # Linux specific way to run something as another user. Command must be passed as a String.
+      # @param user [String] User that will run command
+      # @param command [String] Command to be run by user
+      def run_as_user(user, command)
+        log "Running '#{command}' as '#{user}'..."
+        tee("su -l #{user} -c \"#{command}\"")
+      end
+
+      # Set the max number of open files for a user (nofiles) 
+      # (sets both hard and soft, errors out if user is already listed in limits.conf)
+      # Currently does NOT verify the existence of the specified user on the system
+      # @param user [String] User to set 'nofile' ulimit security setting for
+      # @param limit [Fixnum] Limit to set for user
+      # @return [Boolean]
+      def set_nofile(user, limit)
+        # See if the user is already in the limits.conf file
+        user_entries = `grep -E '^#{user}(\s|\t)+' /etc/security/limits.conf`.chomp.split("\n")
+        if user_entries.empty?
+          # Doing this the lazy way for now... this is probably dangerous for very large files
+
+          # Open and copy the current content of the limits file plus a few extra lines towards the end
+          current_file  = File.readlines("/etc/security/limits.conf")
+          temporary     = Tempfile.new("new_limits")
+          current_file[0..(current_file.size - 2)].each {|l| temporary.write l }
+
+          temporary.write "#{user}\t\tsoft\tnofile\t\t#{limit}\n"
+          temporary.write "#{user}\t\thard\tnofile\t\t#{limit}\n"
+          temporary.write "\n"
+          temporary.write current_file[current_file.size - 1]
+          temporary.rewind
+
+          # Create a backup of the current file
+          FileUtils.cp "/etc/security/limits.conf", "/etc/security/limits.conf.#{Time.now.to_i}"
+          # Clear out the current file
+          File.truncate("/etc/security/limits.conf", 0)
+          # Copy the temporary (new) file to the existing
+          current_file = File.new("/etc/security/limits.conf", "w")
+          temporary.each {|l| current_file.puts l }
+          # Close everything up
+          temporary.close
+          temporary.unlink
+          current_file.close
+          return true
+        else
+          log "User '#{user}' already has a specific entry in /etc/security/limits.conf. Ensure 'nofile' is at least #{limit}.", :warn
+          return false
+        end
+      end # set_nofile()
+
+    end 
+  end
+end

data/lib/doable/helpers/password.rb

@@ -10,6 +10,19 @@ module Doable
       
         (1..length).collect{|a| options[:characters][rand(options[:characters].size)] }.join
       end # generate_password()
+
+      def sha1_hash(password, add_salt = true)
+        salt = if add_salt?
+          if add_salt.kind_of?(String) and add_salt.downcase.match(/^[0-9a-f]+$/)
+            add_salt.downcase
+          else
+            generate_password(16, characters: [*(0..9), *('a'..'f')])
+          end
+        else
+          ''
+        end
+        Base64.encode64(Digest::SHA1.digest(password + salt) + salt).chomp
+      end
     end
   end
 end

data/lib/doable/job.rb

@@ -8,10 +8,19 @@ module Doable
     include Helpers::Logging
     attr_reader :steps, :hooks, :handlers, :threads
     
+    # Allows sequential definition of job steps.
+    # @example usage
+    #   job = Doable::Job.plan do |j|
+    #     j.before  { log "Starting my awesome job" }
+    #     j.step    { # do some stuff here }
+    #     j.attempt { # try to do some other stuff here }
+    #     j.after   { log "Looks like we're all set" }
+    #   end
     def self.plan(&block)
       self.new(&block)
     end
-
+    
+    # Yields itself to allow the syntax seen in the plan class method.
     def initialize
       @hooks    = {}
       @steps    = []
@@ -58,7 +67,7 @@ module Doable
     # WARNING! Exception handlers are __not__ used with these steps, as they never actually raise exceptions
     # @param options [Hash]
     # @param block [Proc]
-    # @return [Boolean]
+    # @return [Boolean] this will __always__ be true by the nature of "attempt"
     def attempt(options = {}, &block)
       @steps << Step.new(self, options) do
         begin
@@ -113,6 +122,7 @@ module Doable
 
     # This triggers a block associated with a hook
     # @param hook [Symbol] Hook to trigger
+    # @return [Boolean] returns true no exceptions are encounter during enumeration of hook steps.
     def trigger(hook)
       @hooks[hook].each_with_index do |step, index|
         begin
@@ -151,6 +161,7 @@ module Doable
           end
         end # begin()
       end if @hooks[hook] # each_with_index()
+      return true
     end # trigger()
 
     # Here we actually trigger the execution of a Job
@@ -221,4 +232,4 @@ module Doable
       log "All Job steps completed successfully!", :success   # This should only happen if everything goes well
     end # run()
   end
-end
+end

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: doable
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Jonathan Gnagy
+- Tim Earle
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-29 00:00:00.000000000 Z
+date: 2015-02-02 00:00:00.000000000 Z
 dependencies: []
 description: A framework for automating tasks with ease
 email: jonathan.gnagy@gmail.com
@@ -20,8 +21,10 @@ files:
 - README.md
 - lib/doable.rb
 - lib/doable/exceptions/framework.rb
+- lib/doable/exceptions/linux.rb
 - lib/doable/exceptions/os.rb
 - lib/doable/helpers/framework.rb
+- lib/doable/helpers/linux.rb
 - lib/doable/helpers/logging.rb
 - lib/doable/helpers/os.rb
 - lib/doable/helpers/password.rb