rouster 0.5

data/lib/rouster/puppet.rb

@@ -0,0 +1,398 @@
+require sprintf('%s/../../%s', File.dirname(File.expand_path(__FILE__)), 'path_helper')
+
+require 'json'
+require 'net/https'
+require 'socket'
+require 'uri'
+
+# TODO use @cache_timeout to invalidate data cached here
+
+class Rouster
+
+  ##
+  # facter
+  #
+  # runs facter, returns parsed hash of { fact1 => value1, factN => valueN }
+  #
+  # parameters
+  # * [cache] - whether to store/return cached facter data, if available
+  # * [custom_facts] - whether to include custom facts in return (uses -p argument)
+  def facter(cache=true, custom_facts=true)
+    if cache.true? and ! self.facts.nil?
+      return self.facts
+    end
+
+    raw  = self.run(sprintf('facter %s', custom_facts.true? ? '-p' : ''))
+    res  = Hash.new()
+
+    raw.split("\n").each do |line|
+      next unless line.match(/(\S*?)\s\=\>\s(.*)/)
+      res[$1] = $2
+    end
+
+    if cache.true?
+      self.facts = res
+    end
+
+    res
+  end
+
+  ##
+  # get_catalog
+  #
+  # not completely implemented method to get a compiled catalog about a node (based on its facts) from a puppetmaster
+  #
+  # original implementation used the catalog face, which does not actually work. switched to an API call, but still need to convert facts into PSON
+  #
+  # parameters
+  # * [hostname] - hostname of node to return catalog for, if not specified, will use `hostname --fqdn`
+  # * [puppetmaster] - hostname of puppetmaster to use in API call, defaults to 'puppet'
+  # * [facts] - hash of facts to pass to puppetmaster
+  # * [puppetmaster_port] - port to talk to the puppetmaster on, defaults to 8140
+  def get_catalog(hostname=nil, puppetmaster=nil, facts=nil, puppetmaster_port=8140)
+    # post https://<puppetmaster>/catalog/<node>?facts_format=pson&facts=<pson URL encoded> == ht to patrick@puppetlabs
+    certname     = hostname.nil? ? self.run('hostname --fqdn').chomp : hostname
+    puppetmaster = puppetmaster.nil? ? 'puppet' : puppetmaster
+    facts        = facts.nil? ? self.facter() : facts
+
+    %w(fqdn hostname operatingsystem operatingsystemrelease osfamily rubyversion).each do |required|
+      raise ArgumentError.new(sprintf('missing required fact[%s]', required)) unless facts.has_key?(required)
+    end
+
+    raise InternalError.new('need to finish conversion of facts to PSON')
+    facts.to_pson # this does not work, but needs to
+
+    json = nil
+    url  = sprintf('https://%s:%s/catalog/%s?facts_format=pson&facts=%s', puppetmaster, puppetmaster_port, certname, facts)
+    uri  = URI.parse(url)
+
+    begin
+      res  = Net::HTTP.get(uri)
+      json = res.to_json
+    rescue => e
+      raise ExternalError.new("calling[#{url}] led to exception[#{e}")
+    end
+
+    json
+  end
+
+  ##
+  # get_puppet_errors
+  #
+  # parses input for puppet errors, returns array of strings
+  #
+  # parameters
+  # * [input] - string to look at, defaults to self.get_output()
+  def get_puppet_errors(input=nil)
+    str    = input.nil? ? self.get_output() : input
+    errors = str.scan(/35merr:.*/)
+
+    errors.empty? ? nil : errors
+  end
+
+  ##
+  # get_puppet_notices
+  #
+  # parses input for puppet notices, returns array of strings
+  #
+  # parameters
+  # * [input] - string to look at, defaults to self.get_output()
+  def get_puppet_notices(input=nil)
+    str     = input.nil? ? self.get_output() : input
+    notices = str.scan(/36mnotice:.*/)
+
+    notices.empty? ? nil : notices
+  end
+
+  ##
+  # get_puppet_version
+  #
+  # executes `puppet --version` and returns parsed version string or nil
+  def get_puppet_version
+    version   = nil
+    installed = self.is_in_path?('puppet')
+
+    if installed
+      raw = self.run('puppet --version')
+      version = raw.match(/([\d\.]*)\s/) ? $1 : nil
+    else
+      version = nil
+    end
+
+    version
+  end
+
+  ##
+  # hiera
+  #
+  # returns hiera results from self
+  #
+  # parameters
+  # * <key> - hiera key to look up
+  # * [config] - path to hiera configuration -- this is only optional if you have a hiera.yaml file in ~/vagrant
+  def hiera(key, config=nil, options=nil)
+
+    cmd = 'hiera'
+    cmd << sprintf(' -c %s', config) unless config.nil?
+    cmd << sprintf(' %s', options) unless options.nil?
+    cmd << sprintf(' %s', key)
+
+    self.run(cmd)
+  end
+
+  ##
+  # parse_catalog
+  #
+  # looks at the ['data']['resources'] keys in catalog for Files, Groups, Packages, Services and Users, returns hash of expectations compatible with validate_*
+  #
+  # this is a very lightly tested implementation, please open issues as necessary
+  #
+  # parameters
+  # * <catalog> - JSON string or Hash representation of catalog, typically from get_catalog()
+  def parse_catalog(catalog)
+    classes   = nil
+    resources = nil
+    results   = Hash.new()
+
+    if catalog.is_a?(String)
+      begin
+        JSON.parse!(catalog)
+      rescue
+        raise InternalError.new(sprintf('unable to parse catalog[%s] as JSON', catalog))
+      end
+    end
+
+    unless catalog.has_key?('data') and catalog['data'].has_key?('classes')
+      raise InternalError.new(sprintf('catalog does not contain a classes key[%s]', catalog))
+    end
+
+    unless catalog.has_key?('data') and catalog['data'].has_key?('resources')
+      raise InternalError.new(sprintf('catalog does not contain a resources key[%s]', catalog))
+    end
+
+    raw_resources = catalog['data']['resources']
+
+    raw_resources.each do |r|
+      # samples of eacb type of resource is available at
+      # https://github.com/chorankates/rouster/issues/20#issuecomment-18635576
+      #
+      # we can do a lot better here
+      type = r['type']
+      case type
+        when 'Class'
+          classes.push(r['title'])
+        when 'File'
+          name = r['title']
+          resources[name] = Hash.new()
+
+          resources[name][:type]      = :file
+          resources[name][:directory] = false
+          resources[name][:ensure]    = r['ensure'] ||= 'present'
+          resources[name][:file]      = true
+          resources[name][:group]     = r['parameters'].has_key?('group') ? r['parameters']['group'] : nil
+          resources[name][:mode]      = r['parameters'].has_key?('mode')  ? r['parameters']['mode']  : nil
+          resources[name][:owner]     = r['parameters'].has_key?('owner') ? r['parameters']['owner'] : nil
+          resources[name][:contains]  = r.has_key?('content') ? r['content'] : nil
+
+        when 'Group'
+          name = r['title']
+          resources[name] = Hash.new()
+
+          resources[name][:type]   = :group
+          resources[name][:ensure] = r['ensure'] ||= 'present'
+          resources[name][:gid]    = r['parameters'].has_key?('gid') ? r['parameters']['gid'] : nil
+
+        when 'Package'
+          name = r['title']
+          resources[name] = Hash.new()
+
+          resources[name][:type]    = :package
+          resources[name][:ensure]  = r['ensure'] ||= 'present'
+          resources[name][:version] = r['ensure'] =~ /\d/ ? r['ensure'] : nil
+
+        when 'Service'
+          name = r['title']
+          resources[name] = Hash.new()
+
+          resources[name][:type]   = :service
+          resources[name][:ensure] = r['ensure'] ||= 'present'
+          resources[name][:state]  = r['ensure']
+
+        when 'User'
+          name = r['title']
+          resources[name] = Hash.new()
+
+          resources[name][:type]   = :user
+          resources[name][:ensure] = r['ensure'] ||= 'present'
+          resources[name][:home]   = r['parameters'].has_key?('home')   ? r['parameters']['home']   : nil
+          resources[name][:gid]    = r['parameters'].has_key?('gid')    ? r['parameters']['gid']    : nil
+          resources[name][:group]  = r['parameters'].has_key?('groups') ? r['parameters']['groups'] : nil
+          resources[name][:shell]  = r['parameters'].has_key?('shell')  ? r['parameters']['shell']  : nil
+          resources[name][:uid]    = r['parameters'].has_key?('uid')    ? r['parameters']['uid']    : nil
+
+        else
+          raise NotImplementedError.new(sprintf('parsing support for [%s] is incomplete', type))
+      end
+
+    end
+
+    # remove all nil references
+    resources.each_key do |name|
+      resources[name].each_pair do |k,v|
+        unless v
+          resources[name].delete(k)
+        end
+      end
+    end
+
+
+    results[:classes]   = classes
+    results[:resources] = resources
+
+    results
+  end
+
+  ##
+  # remove_existing_certs
+  #
+  # ... removes existing certificates - really only useful when called on a puppetmaster
+  # useful in testing environments where you want to destroy/rebuild agents without rebuilding the puppetmaster every time (think autosign)
+  #
+  # parameters
+  # * <puppetmaster> - string/partial regex of certificate names to keep
+  def remove_existing_certs (puppetmaster)
+    hosts = Array.new()
+
+    res = self.run('puppet cert list --all')
+
+    res.each_line do |line|
+      next if line.match(/#{puppetmaster}/)
+      host = $1 if line.match(/^\+\s"(.*?)"/)
+
+      hosts.push(host) unless host.nil? # only want to clear signed certs
+    end
+
+    hosts.each do |host|
+      self.run(sprintf('puppet cert --clean %s', host))
+    end
+
+  end
+
+  ##
+  # run_puppet
+  #
+  # ... runs puppet on self, returns nothing
+  #
+  # currently supports 2 methods of running puppet:
+  #  * master - runs 'puppet agent -t'
+  #    * supported options
+  #      * expected_exitcode - string/integer/array of acceptable exit code(s)
+  #      * configtimeout - string/integer of the acceptable configtimeout value
+  #      * environment - string of the environment to use
+  #      * certname - string of the certname to use in place of the host fqdn
+  #      * pluginsync - bool value if pluginsync should be used
+  #      * server - string value of the puppetmasters fqdn / ip
+  #      * additional_options - string of various options that would be passed to puppet
+  #  * masterless - runs 'puppet apply <options>' after determining version of puppet running and adjusting arguments
+  #    * supported options
+  #      * expected_exitcode - string/integer/array of acceptable exit code(s)
+  #      * hiera_config - path to hiera configuration -- only supported by Puppet 3.0+
+  #      * manifest_file - string/array of strings of paths to manifest(s) to apply
+  #      * manifest_dir - string/array of strings of directories containing manifest(s) to apply - is recursive
+  #      * module_dir - path to module directory -- currently a required parameter, is this correct?
+  #      * environment - string of the environment to use (default: production)
+  #      * certname - string of the certname to use in place of the host fqdn (default: unused)
+  #      * pluginsync - bool value if pluginsync should be used (default: true)
+  #      * additional_options - string of various options that would be passed to puppet
+  #
+  # parameters
+  # * [mode] - method to run puppet, defaults to 'master'
+  # * [opts] - hash of additional options
+  def run_puppet(mode='master', passed_opts=nil)
+
+    if mode.eql?('master')
+      opts = {
+        :expected_exitcode  => 0,
+        :configtimeout      => nil,
+        :environment        => nil,
+        :certname           => nil,
+        :server             => nil,
+        :pluginsync         => false,
+        :additional_options => nil
+      }.merge!(passed_opts)
+
+      cmd = 'puppet agent -t'
+      cmd << sprintf(' --configtimeout %s', opts[:configtimeout]) unless opts[:configtimeout].nil?
+      cmd << sprintf(' --environment %s', opts[:environment]) unless opts[:environment].nil?
+      cmd << sprintf(' --certname %s', opts[:certname]) unless opts[:certname].nil?
+      cmd << sprintf(' --server %s', opts[:server]) unless opts[:server].nil?
+      cmd << ' --pluginsync' if opts[:pluginsync]
+      cmd << opts[:additional_options] unless opts[:additional_options].nil?
+
+      self.run(cmd, opts[:expected_exitcode])
+
+    elsif mode.eql?('masterless')
+      opts = {
+        :expected_exitcode  => 2,
+        :hiera_config       => nil,
+        :manifest_file      => nil, # can be a string or array, will 'puppet apply' each
+        :manifest_dir       => nil, # can be a string or array, will 'puppet apply' each module in the dir (recursively)
+        :module_dir         => nil,
+        :environment        => nil,
+        :certname           => nil,
+        :pluginsync         => false,
+        :additional_options => nil
+      }.merge!(passed_opts)
+
+      ## validate required arguments
+      raise InternalError.new(sprintf('invalid hiera config specified[%s]', opts[:hiera_config])) unless self.is_file?(opts[:hiera_config])
+      raise InternalError.new(sprintf('invalid module dir specified[%s]', opts[:module_dir])) unless self.is_dir?(opts[:module_dir])
+
+      puppet_version = self.get_puppet_version() # hiera_config specification is only supported in >3.0
+
+      if opts[:manifest_file]
+        opts[:manifest_file] = opts[:manifest_file].class.eql?(Array) ? opts[:manifest_file] : [opts[:manifest_file]]
+        opts[:manifest_file].each do |file|
+          raise InternalError.new(sprintf('invalid manifest file specified[%s]', file)) unless self.is_file?(file)
+
+          cmd = sprintf('puppet apply %s --modulepath=%s', (puppet_version > '3.0') ? "--hiera_config=#{opts[:hiera_config]}" : '', opts[:module_dir])
+          cmd << sprintf(' --environment %s', opts[:environment]) unless opts[:environment].nil?
+          cmd << sprintf(' --certname %s', opts[:certname]) unless opts[:certname].nil?
+          cmd << ' --pluginsync' if opts[:pluginsync]
+          cmd << opts[:additional_options] unless opts[:additional_options].nil?
+          cmd << sprintf(' %s', file)
+
+          self.run(cmd, opts[:expected_exitcode])
+        end
+      end
+
+      if opts[:manifest_dir]
+        opts[:manifest_dir] = opts[:manifest_dir].class.eql?(Array) ? opts[:manifest_dir] : [opts[:manifest_dir]]
+        opts[:manifest_dir].each do |dir|
+          raise InternalError.new(sprintf('invalid manifest dir specified[%s]', dir)) unless self.is_dir?(dir)
+
+          manifests = self.files(dir, '*.pp', true)
+
+          manifests.each do |m|
+
+            cmd = sprintf('puppet apply %s --modulepath=%s', (puppet_version > '3.0') ? "--hiera_config=#{opts[:hiera_config]}" : '', opts[:module_dir])
+            cmd << sprintf(' --environment %s', opts[:environment]) unless opts[:environment].nil?
+            cmd << sprintf(' --certname %s', opts[:certname]) unless opts[:certname].nil?
+            cmd << ' --pluginsync' if opts[:pluginsync]
+            cmd << opts[:additional_options] unless opts[:additional_options].nil?
+            cmd << sprintf(' %s', m)
+
+            self.run(cmd, opts[:expected_exitcode])
+          end
+
+        end
+      end
+
+    else
+      raise InternalError.new(sprintf('unknown mode [%s]', mode))
+    end
+
+
+  end
+
+end

data/lib/rouster/testing.rb

@@ -0,0 +1,743 @@
+require sprintf('%s/../../%s', File.dirname(File.expand_path(__FILE__)), 'path_helper')
+require 'rouster/deltas'
+
+# TODO better document keys :constrain and :version
+
+class Rouster
+
+  ##
+  # validate_file
+  #
+  # given a filename and a hash of expectations, returns true|false whether file matches expectations
+  #
+  # parameters
+  # * <name> - full file name or relative (to ~vagrant)
+  # * <expectations> - hash of expectations, see examples
+  # * <fail_fast> - return false immediately on any failure (default is false)
+  #
+  # example expectations:
+  # '/sys/kernel/mm/redhat_transparent_hugepage/enabled', {
+  #   :contains => 'never',
+  # },
+  #
+  # '/etc/fstab', {
+  #   :contains  => '/dev/fioa*/iodata*xfs',
+  #   :constrain => 'is_virtual false' # syntax is '<fact> <expected>', file is only tested if <expected> matches <actual>
+  #   :exists    => 'file',
+  #   :mode      => '0644'
+  # },
+  #
+  # '/etc/hosts', {
+  #   :constrain => ['! is_virtual true', 'is_virtual false'],
+  #   :mode      => '0644'
+  # }
+  #
+  # '/etc/nrpe.cfg', {
+  #   :ensure   => 'file',
+  #   :contains => ['dont_blame_nrpe=1', 'allowed_hosts=' ]
+  # }
+  #
+  # supported keys:
+  #   * :exists|:ensure -- defaults to file if not specified
+  #   * :file
+  #   * :directory
+  #   * :contains (string or array)
+  #   * :mode/:permissions
+  #   * :size
+  #   * :owner
+  #   * :group
+  #   * :constrain
+  def validate_file(name, expectations, fail_fast=false, cache=false)
+
+    if expectations[:ensure].nil? and expectations[:exists].nil? and expectations[:directory].nil? and expectations[:file?].nil?
+      expectations[:ensure] = 'file'
+    end
+
+    if expectations.has_key?(:constrain)
+      expectations[:constrain] = expectations[:constrain].class.eql?(Array) ? expectations[:constrain] : [expectations[:constrain]]
+
+      expectations[:constrain].each do |constraint|
+        fact, expectation = constraint.split("\s")
+        unless meets_constraint?(fact, expectation)
+          @log.info(sprintf('returning true for expectation [%s], did not meet constraint[%s/%s]', name, fact, expectation))
+          return true
+        end
+      end
+
+      expectations.delete(:constrain)
+    end
+
+    properties = (expectations[:ensure].eql?('file')) ?  self.file(name, cache) : self.dir(name, cache)
+    results = Hash.new()
+    local = nil
+
+    expectations.each do |k,v|
+
+      case k
+        when :ensure, :exists
+          if properties.nil? and v.to_s.match(/absent|false/)
+            local = true
+          elsif properties.nil?
+            local = false
+          else
+            case v
+              when 'dir', 'directory'
+                local = properties[:directory?]
+              else
+                local = properties[:file?]
+            end
+          end
+        when :file
+          if properties.nil?
+            if v.to_s.match(/absent|false/)
+              local = true
+            else
+              local = false
+            end
+          elsif properties[:file?].true?
+            local = ! v.to_s.match(/absent|false/)
+          else
+            false
+          end
+        when :dir, :directory
+          if properties.nil?
+            if v.to_s.match(/absent|false/)
+              local = true
+            else
+              local = false
+            end
+          elsif properties.has_key?(:directory?)
+            if properties[:directory?]
+              local = v.to_s.match(/absent|false/).nil?
+            else
+              local = ! v.to_s.match(/absent|false/).nil?
+            end
+          else
+            local = false
+          end
+        when :contains
+          v = v.class.eql?(Array) ? v : [v]
+          v.each do |regex|
+            local = true
+            begin
+              self.run(sprintf("grep -c '%s' %s", regex, name))
+            rescue
+              local = false
+            end
+            next if local.false?
+          end
+        when :mode, :permissions
+          if properties.nil?
+            local = false
+          elsif v.to_s.match(/#{properties[:mode].to_s}/)
+            local = true
+          else
+            local = false
+          end
+        when :size
+          if properties.nil?
+            local = false
+          else
+            local = v.to_i.eql?(properties[:size].to_i)
+          end
+        when :owner
+          if properties.nil?
+            local = false
+          elsif v.to_s.match(/#{properties[:owner].to_s}/)
+            local = true
+          else
+            local = false
+          end
+        when :group
+          if properties.nil?
+            local = false
+          elsif v.match(/#{properties[:group]}/)
+            local = true
+          else
+            local = false
+          end
+        when :type
+          # noop allowing parse_catalog() output to be passed directly
+        else
+          raise InternalError.new(sprintf('unknown expectation[%s / %s]', k, v))
+      end
+
+      return false if local.eql?(false) and fail_fast.eql?(true)
+      results[k] = local
+    end
+
+    @log.info(results)
+    results.find{|k,v| v.false? }.nil?
+
+  end
+
+  ##
+  # validate_group
+  #
+  # given a group and a hash of expectations, returns true|false whether group matches expectations
+  #
+  # paramaters
+  # * <name> - group name
+  # * <expectations> - hash of expectations, see examples
+  # * <fail_fast> - return false immediately on any failure (default is false)
+  #
+  # example expectations:
+  # 'root', {
+  #   # if ensure is not specified, 'present' is implied
+  #   :gid => 0,
+  #   :user => 'root'
+  # }
+  # 'sys', {
+  #   :ensure => 'present',
+  #   :user   => ['root', 'bin', 'daemon']
+  # },
+  #
+  # 'fizz', {
+  #   :exists => false
+  # },
+  #
+  # supported keys:
+  #  * :exists|:ensure
+  #  * :gid
+  #  * :user|:users (string or array)
+  #  * :constrain
+  def validate_group(name, expectations, fail_fast=false)
+    groups = self.get_groups(true)
+
+    if expectations[:ensure].nil? and expectations[:exists].nil?
+      expectations[:ensure] = 'present'
+    end
+
+    if expectations.has_key?(:constrain)
+      expectations[:constrain] = expectations[:constrain].class.eql?(Array) ? expectations[:constrain] : [expectations[:constrain]]
+
+      expectations[:constrain].each do |constraint|
+        fact, expectation = constraint.split("\s")
+        unless meets_constraint?(fact, expectation)
+          @log.info(sprintf('returning true for expectation [%s], did not meet constraint[%s/%s]', name, fact, expectation))
+          return true
+        end
+      end
+
+      expectations.delete(:constrain)
+    end
+
+    results = Hash.new()
+    local = nil
+
+    expectations.each do |k,v|
+      case k
+        when :ensure, :exists
+          if groups.has_key?(name)
+            if v.to_s.match(/absent|false/).nil?
+              local = true
+            else
+              local = false
+            end
+          else
+            local = v.to_s.match(/absent|false/).nil? ? false : true
+          end
+        when :gid
+          if groups[name].is_a?(Hash) and groups[name].has_key?(:gid)
+            local = v.to_s.eql?(groups[name][:gid].to_s)
+          else
+            local = false
+          end
+        when :user, :users
+          v = v.class.eql?(Array) ? v : [v]
+          v.each do |user|
+            if groups[name].is_a?(Hash) and groups[name].has_key?(:users)
+              local = groups[name][:users].member?(user)
+            else
+              local = false
+            end
+            break unless local.true? # need to make the return value smarter if we want to store data on which user failed
+          end
+        when :type
+          # noop allowing parse_catalog() output to be passed directly
+        else
+          raise InternalError.new(sprintf('unknown expectation[%s / %s]', k, v))
+      end
+
+      return false if local.eql?(false) and fail_fast.eql?(true)
+      results[k] = local
+    end
+
+    @log.info(results)
+    results.find{|k,v| v.false? }.nil?
+  end
+
+  ##
+  # validate_package
+  #
+  # given a package name and a hash of expectations, returns true|false whether package meets expectations
+  #
+  # parameters
+  # * <name> - package name
+  # * <expectations> - hash of expectations, see examples
+  # * <fail_fast> - return false immediately on any failure (default is false)
+  #
+  # example expectations:
+  # 'perl-Net-SNMP', {
+  #   :ensure => 'absent'
+  # },
+  #
+  # 'pixman', {
+  #   :ensure => 'present',
+  #   :version => '1.0',
+  # },
+  #
+  # 'rrdtool', {
+  #   # if ensure is not specified, 'present' is implied
+  #   :version => '> 2.1',
+  #   :constrain => 'is_virtual false',
+  # },
+  # supported keys:
+  #  * :exists|ensure
+  #  * :version  (literal or basic comparison)
+  #  * :constrain
+  def validate_package(name, expectations, fail_fast=false)
+    packages = self.get_packages(true)
+
+    if expectations[:ensure].nil? and expectations[:exists].nil?
+      expectations[:ensure] = 'present'
+    end
+
+    if expectations.has_key?(:constrain)
+      expectations[:constrain] = expectations[:constrain].class.eql?(Array) ? expectations[:constrain] : [expectations[:constrain]]
+
+      expectations[:constrain].each do |constraint|
+        fact, expectation = constraint.split("\s")
+        unless meets_constraint?(fact, expectation)
+          @log.info(sprintf('returning true for expectation [%s], did not meet constraint[%s/%s]', name, fact, expectation))
+          return true
+        end
+      end
+
+      expectations.delete(:constrain)
+    end
+
+    results = Hash.new()
+    local = nil
+
+    expectations.each do |k,v|
+      case k
+        when :ensure, :exists
+          if packages.has_key?(name)
+            if v.to_s.match(/absent|false/).nil?
+              local = true
+            else
+              local = false
+            end
+          else
+            local = v.to_s.match(/absent|false/).nil? ? false : true
+          end
+        when :version
+          if packages.has_key?(name)
+            if v.split("\s").size > 1
+              ## generic comparator functionality
+              comp, expectation = v.split("\s")
+              local = generic_comparator(packages[name], comp, expectation)
+            else
+              local = ! v.to_s.match(/#{packages[name]}/).nil?
+            end
+          else
+            local = false
+          end
+        when :type
+          # noop allowing parse_catalog() output to be passed directly
+        else
+          raise InternalError.new(sprintf('unknown expectation[%s / %s]', k, v))
+      end
+
+      return false if local.eql?(false) and fail_fast.eql?(true)
+      results[k] = local
+    end
+
+    # TODO figure out a good way to allow access to the entire hash, not just boolean -- for now just print at an info level
+    @log.info(results)
+
+    results.find{|k,v| v.false? }.nil?
+  end
+
+  # given a port nnumber and a hash of expectations, returns true|false whether port meets expectations
+  #
+  # parameters
+  # * <number> - port number
+  # * <expectations> - hash of expectations, see examples
+  #
+  # example expectations:
+  # '22', {
+  #   :ensure => 'active',
+  #   :protocol => 'tcp',
+  #   :address => '0.0.0.0'
+  # },
+  #
+  # '1234', {
+  #   :ensure => 'open',
+  #   :address => '*',
+  #   :constrain => 'is_virtual false'
+  # }
+  #
+  # supported keys:
+  #  * :exists|ensure|state
+  #  * :address
+  #  * :protocol|proto
+  #  * :constrain
+  def validate_port(number, expectations, fail_fast=false)
+    number = number.to_s
+    ports  = self.get_ports(true)
+
+    if expectations[:ensure].nil? and expectations[:exists].nil? and expectations[:state].nil?
+      expectations[:ensure] = 'present'
+    end
+
+    if expectations[:protocol].nil? and expectations[:proto].nil?
+      expectations[:protocol] = 'tcp'
+    elsif ! expectations[:proto].nil?
+      expectations[:protocol] = expectations[:proto]
+    end
+
+    if expectations.has_key?(:constrain)
+      expectations[:constrain] = expectations[:constrain].class.eql?(Array) ? expectations[:constrain] : [expectations[:constrain]]
+
+      expectations[:constrain].each do |constraint|
+        fact, expectation = constraint.split("\s")
+        unless meets_constraint?(fact, expectation)
+          @log.info(sprintf('returning true for expectation [%s], did not meet constraint[%s/%s]', name, fact, expectation))
+          return true
+        end
+      end
+
+      expectations.delete(:constrain)
+    end
+
+    results = Hash.new()
+    local = nil
+
+    expectations.each do |k,v|
+      case k
+        when :ensure, :exists, :state
+          if v.to_s.match(/absent|false|open/)
+            local = ports[expectations[:protocol]][number].nil?
+          else
+            local = ! ports[expectations[:protocol]][number].nil?
+          end
+        when :protocol, :proto
+          # TODO rewrite this in a less hacky way
+          if expectations[:ensure].to_s.match(/absent|false|open/) or expectations[:exists].to_s.match(/absent|false|open/) or expectations[:state].to_s.match(/absent|false|open/)
+            local = true
+          else
+            local = ports[v].has_key?(number)
+          end
+
+        when :address
+          lr = Array.new
+          addresses = ports[expectations[:protocol]][number][:address]
+          addresses.each_key do |address|
+            lr.push(address.eql?(v.to_s))
+          end
+
+          local = ! lr.find{|e| e.true? }.nil? # this feels jankity
+
+        else
+          raise InternalError.new(sprintf('unknown expectation[%s / %s]', k, v))
+      end
+
+      return false if local.eql?(false) and fail_fast.eql?(true)
+      results[k] = local
+    end
+
+    @log.info(results)
+
+    results.find{|k,v| v.false? }.nil?
+  end
+
+  ##
+  # validate_service
+  #
+  # given a service name and a hash of expectations, returns true|false whether package meets expectations
+  #
+  # parameters
+  # * <name> - service name
+  # * <expectations> - hash of expectations, see examples
+  # * <fail_fast> - return false immediately on any failure (default is false)
+  #
+  # example expectations:
+  # 'ntp', {
+  #   :ensure => 'present',
+  #   :state  => 'started'
+  # },
+  #
+  # 'ypbind', {
+  #   :state => 'stopped',
+  # }
+  #
+  # supported keys:
+  #  * :exists|:ensure
+  #  * :state,:status
+  #  * :constrain
+  def validate_service(name, expectations, fail_fast=false)
+    services = self.get_services(true)
+
+    if expectations[:ensure].nil? and expectations[:exists].nil?
+      expectations[:ensure] = 'present'
+    end
+
+    if expectations.has_key?(:constrain)
+      expectations[:constrain] = expectations[:constrain].class.eql?(Array) ? expectations[:constrain] : [expectations[:constrain]]
+
+      expectations[:constrain].each do |constraint|
+        fact, expectation = constraint.split("\s")
+        unless meets_constraint?(fact, expectation)
+          @log.info(sprintf('returning true for expectation [%s], did not meet constraint[%s/%s]', name, fact, expectation))
+          return true
+        end
+      end
+
+      expectations.delete(:constrain)
+    end
+
+    results = Hash.new()
+    local = nil
+
+    expectations.each do |k,v|
+      case k
+        when :ensure, :exists
+          if services.has_key?(name)
+            if v.to_s.match(/absent|false/)
+              local = false
+            else
+              local = true
+            end
+          else
+            local = v.to_s.match(/absent|false/).nil? ? false : true
+          end
+        when :state, :status
+          if services.has_key?(name)
+            local = ! v.match(/#{services[name]}/).nil?
+          else
+            local = false
+          end
+        when :type
+          # noop allowing parse_catalog() output to be passed directly
+        else
+          raise InternalError.new(sprintf('unknown expectation[%s / %s]', k, v))
+      end
+
+      return false if local.eql?(false) and fail_fast.eql?(true)
+      results[k] = local
+    end
+
+    @log.info(results)
+    results.find{|k,v| v.false? }.nil?
+
+  end
+
+  ##
+  # validate_user
+  #
+  # given a user name and a hash of expectations, returns true|false whether user meets expectations
+  #
+  # parameters
+  # * <name> - user name
+  # * <expectations> - hash of expectations, see examples
+  # * <fail_fast> - return false immediately on any failure (default is false)
+  #
+  # example expectations:
+  # 'root' => {
+  #   :uid => 0
+  # },
+  #
+  # 'ftp' => {
+  #   :exists => true,
+  #   :home   => '/var/ftp',
+  #   :shell  => 'nologin'
+  # },
+  #
+  # 'developer' => {
+  #   :exists    => 'false',
+  #   :constrain => 'environment != production'
+  # }
+  #
+  # supported keys:
+  #  * :exists|ensure
+  #  * :home
+  #  * :group
+  #  * :shell
+  #  * :uid
+  #  * :gid
+  #  * :constrain
+  def validate_user(name, expectations, fail_fast=false)
+    users = self.get_users(true)
+
+    if expectations[:ensure].nil? and expectations[:exists].nil?
+      expectations[:ensure] = 'present'
+    end
+
+    if expectations.has_key?(:constrain)
+      expectations[:constrain] = expectations[:constrain].class.eql?(Array) ? expectations[:constrain] : [expectations[:constrain]]
+
+      expectations[:constrain].each do |constraint|
+        fact, expectation = constraint.split("\s")
+        unless meets_constraint?(fact, expectation)
+          @log.info(sprintf('returning true for expectation [%s], did not meet constraint[%s/%s]', name, fact, expectation))
+          return true
+        end
+      end
+
+      expectations.delete(:constrain)
+    end
+
+    results = Hash.new()
+    local = nil
+
+    expectations.each do |k,v|
+      case k
+        when :ensure, :exists
+          if users.has_key?(name)
+            if v.to_s.match(/absent|false/).nil?
+              local = true
+            else
+              local = false
+            end
+          else
+            local = v.to_s.match(/absent|false/).nil? ? false : true
+          end
+        when :group
+          v = v.class.eql?(Array) ? v : [v]
+          v.each do |group|
+            local = is_user_in_group?(name, group)
+            break unless local.true?
+          end
+        when :gid
+          if users[name].is_a?(Hash) and users[name].has_key?(:gid)
+            local = v.to_i.eql?(users[name][:gid].to_i)
+          else
+            local = false
+          end
+        when :home
+          if users[name].is_a?(Hash) and users[name].has_key?(:home)
+            local = ! v.match(/#{users[name][:home]}/).nil?
+          else
+            local = false
+          end
+        when :home_exists
+          if users[name].is_a?(Hash) and users[name].has_key?(:home_exists)
+            local = ! v.to_s.match(/#{users[name][:home_exists].to_s}/).nil?
+          else
+            local = false
+          end
+        when :shell
+          if users[name].is_a?(Hash) and users[name].has_key?(:shell)
+            local = ! v.match(/#{users[name][:shell]}/).nil?
+          else
+            local = false
+          end
+        when :uid
+          if users[name].is_a?(Hash) and users[name].has_key?(:uid)
+            local = v.to_i.eql?(users[name][:uid].to_i)
+          else
+            local = false
+          end
+        when :type
+          # noop allowing parse_catalog() output to be passed directly
+        else
+          raise InternalError.new(sprintf('unknown expectation[%s / %s]', k, v))
+      end
+
+      return false if local.eql?(false) and fail_fast.eql?(true)
+      results[k] = local
+    end
+
+    @log.info(results)
+    results.find{|k,v| v.false? }.nil?
+
+  end
+
+  ## internal methods
+  private
+
+  ##
+  # meets_constraint?
+  #
+  # powers the :constrain value in expectations passed to validate_*
+  # gets facts from node, and if fact expectation regex matches actual fact, returns true
+  #
+  # parameters
+  # * <fact> - fact
+  # * <expectation>
+  # * [cache]
+  def meets_constraint?(fact, expectation, cache=true)
+
+    unless self.respond_to?('facter')
+      # if we haven't loaded puppet.rb, we won't have access to facts
+      @log.warn('using constraints without loading [rouster/puppet] will not work, forcing no-op')
+      return false
+    end
+
+    expectation = expectation.to_s
+    facts = self.facter(cache)
+
+    res = nil
+    if expectation.split("\s").size > 1
+      ## generic comparator functionality
+      comp, expectation = expectation.split("\s")
+
+      res = generic_comparator(facts[fact], comp, expectation)
+
+    else
+      res = ! expectation.match(/#{facts[fact]}/).nil?
+      @log.debug(sprintf('meets_constraint?(%s, %s): %s', fact, expectation, res.nil?))
+    end
+
+    res
+  end
+
+  ##
+  # generic_comparator
+  #
+  # powers the 3 argument form of constraint (i.e. 'is_virtual != true', '<package_version> > 3.0', etc)
+  #
+  # should really be an eval{} of some sort (or would be in the perl world)
+  #
+  # parameters
+  # * <comparand1> - left side of the comparison
+  # * <comparator> - comparison to make
+  # * <comparand2> - right side of the comparison
+  def generic_comparator(comparand1, comparator, comparand2)
+
+    # TODO rewrite this as an eval so we don't have to support everything..
+    case comparator
+      when '!='
+        # ugh
+        if comparand1.to_s.match(/\d/) or comparand2.to_s.match(/\d/)
+          res = ! comparand1.to_i.eql?(comparand2.to_i)
+        else
+          res = ! comparand1.eql?(comparand2)
+        end
+      when '<'
+        res = comparand1.to_i < comparand2.to_i
+      when '<='
+        res = comparand1.to_i <= comparand2.to_i
+      when '>'
+        res = comparand1.to_i > comparand2.to_i
+      when '>='
+        res = comparand1.to_i >= comparand2.to_i
+      when '=='
+        # ugh ugh
+        if comparand1.to_s.match(/\d/) or comparand2.to_s.match(/\d/)
+          res = comparand1.to_i.eql?(comparand2.to_i)
+        else
+          res = comparand1.eql?(comparand2)
+        end
+      else
+        raise NotImplementedError.new(sprintf('unknown comparator[%s]', comparator))
+    end
+
+
+
+    res
+  end
+
+end