sys-admin 1.5.3-x86-mingw32

data/lib/sys/admin.rb

@@ -0,0 +1,980 @@
+require 'win32ole'
+require 'win32/security'
+require 'win32/registry'
+require 'socket'
+
+module Sys
+   class Group
+      # Short description of the object.
+      attr_accessor :caption
+
+      # Description of the group.
+      attr_accessor :description
+      
+      # Name of the Windows domain to which the group account belongs.
+      attr_accessor :domain
+      
+      # Date the group was added.
+      attr_accessor :install_date
+
+      # Name of the Windows group account on the Group#domain specified.
+      attr_accessor :name
+
+      # Security identifier for this group.
+      attr_accessor :sid
+
+      # Current status for the group, such as "ok", "error", etc.
+      attr_accessor :status
+
+      # The group ID.
+      attr_accessor :gid
+
+      # Sets whether or not the group is local (as opposed to global).
+      attr_writer :local
+
+      # An array of members for that group. May contain SID's.
+      attr_accessor :members
+
+      # Creates and returns a new Group object.  This class encapsulates
+      # the information for a group account, whether it be global or local.
+      #
+      # Yields +self+ if a block is given.
+      #
+      def initialize
+         yield self if block_given?
+      end
+      
+      # Returns whether or not the group is a local group.
+      #
+      def local?
+         @local
+      end
+      
+      # Returns the type of SID (Security Identifier) as a stringified value.
+      #
+      def sid_type
+         @sid_type
+      end
+      
+      # Sets the SID (Security Identifier) type to +stype+, which can be
+      # one of the following constant values:
+      #
+      # * Admin::SidTypeUser
+      # * Admin::SidTypeGroup
+      # * Admin::SidTypeDomain
+      # * Admin::SidTypeAlias
+      # * Admin::SidTypeWellKnownGroup
+      # * Admin::SidTypeDeletedAccount
+      # * Admin::SidTypeInvalid
+      # * Admin::SidTypeUnknown
+      # * Admin::SidTypeComputer
+      #
+      def sid_type=(stype)
+         if stype.kind_of?(String)
+            @sid_type = stype.downcase
+         else
+            case stype
+               when Admin::SidTypeUser
+                  @sid_type = "user"
+               when Admin::SidTypeGroup
+                  @sid_type = "group"
+               when Admin::SidTypeDomain
+                  @sid_type = "domain"
+               when Admin::SidTypeAlias
+                  @sid_type = "alias"
+               when Admin::SidTypeWellKnownGroup
+                  @sid_type = "well_known_group"
+               when Admin::SidTypeDeletedAccount
+                  @sid_type = "deleted_account"
+               when Admin::SidTypeInvalid
+                  @sid_type = "invalid"
+               when Admin::SidTypeUnknown
+                  @sid_type = "unknown"
+               when Admin::SidTypeComputer
+                  @sid_type = "computer"
+               else
+                  @sid_type = "unknown"
+            end
+         end
+         @sid_type
+      end
+   end
+   
+   class User
+      # An account for users whose primary account is in another domain.
+      TEMP_DUPLICATE = 0x0100
+      
+      # Default account type that represents a typical user.
+      NORMAL = 0x0200
+      
+      # A permit to trust account for a domain that trusts other domains.
+      INTERDOMAIN_TRUST = 0x0800
+      
+      # An account for a Windows NT/2000 workstation or server that is a
+      # member of this domain.
+      WORKSTATION_TRUST = 0x1000
+      
+      # A computer account for a backup domain controller that is a member
+      # of this domain.
+      SERVER_TRUST = 0x2000
+      
+      # Domain and username of the account.
+      attr_accessor :caption
+      
+      # Description of the account.
+      attr_accessor :description
+      
+      # Name of the Windows domain to which a user account belongs.
+      attr_accessor :domain
+      
+      # The user's password.
+      attr_accessor :password
+
+      # Full name of a local user.
+      attr_accessor :full_name
+
+      # An array of groups to which the user belongs.
+      attr_accessor :groups
+      
+      # Date the user account was created.
+      attr_accessor :install_date
+      
+      # Name of the Windows user account on the domain that the User#domain
+      # property specifies.
+      attr_accessor :name
+      
+      # The user's security identifier.
+      attr_accessor :sid
+      
+      # Current status for the user, such as "ok", "error", etc.
+      attr_accessor :status
+
+      # The user's id (RID).
+      attr_accessor :uid
+
+      # The user's home directory
+      attr_accessor :dir
+
+      # Used to set whether or not the account is disabled.
+      attr_writer :disabled
+      
+      # Sets whether or not the account is defined on the local computer.
+      attr_writer :local
+      
+      # Sets whether or not the account is locked out of the OS.
+      attr_writer :lockout
+
+      # Sets whether or not the password for the account can be changed.
+      attr_writer :password_changeable
+
+      # Sets whether or not the password for the account expires.
+      attr_writer :password_expires
+
+      # Sets whether or not a password is required for the account.
+      attr_writer :password_required
+
+      # Returns the account type as a human readable string.
+      attr_reader :account_type
+      
+      # Creates an returns a new User object.  A User object encapsulates a
+      # user account on the operating system.
+      #
+      # Yields +self+ if a block is provided.
+      #
+      def initialize
+         yield self if block_given?
+      end
+      
+      # Sets the account type for the account.  Possible values are:
+      # 
+      # * User::TEMP_DUPLICATE
+      # * User::NORMAL
+      # * User::INTERDOMAIN_TRUST
+      # * User::WORKSTATION_TRUST
+      # * User::SERVER_TRUST
+      # 
+      def account_type=(type)
+         case type
+            when TEMP_DUPLICATE
+               @account_type = 'duplicate'
+            when NORMAL
+               @account_type = 'normal'
+            when INTERDOMAIN_TRUST
+               @account_type = 'interdomain_trust'
+            when WORKSTATION_TRUST
+               @account_type = 'workstation_trust'
+            when SERVER_TRUST
+               @account_type = 'server_trust'
+            else
+               @account_type = 'unknown'
+         end
+      end
+     
+      # Returns the SID type as a human readable string.
+      # 
+      def sid_type
+         @sid_type
+      end
+     
+      # Sets the SID (Security Identifier) type to +stype+, which can be
+      # one of the following constant values:
+      #
+      # * Admin::SidTypeUser
+      # * Admin::SidTypeGroup
+      # * Admin::SidTypeDomain
+      # * Admin::SidTypeAlias
+      # * Admin::SidTypeWellKnownGroup
+      # * Admin::SidTypeDeletedAccount
+      # * Admin::SidTypeInvalid
+      # * Admin::SidTypeUnknown
+      # * Admin::SidTypeComputer
+      # 
+      def sid_type=(stype)
+         case stype
+            when Admin::SidTypeUser
+               @sid_type = 'user'
+            when Admin::SidTypeGroup
+               @sid_type = 'group'
+            when Admin::SidTypeDomain
+               @sid_type = 'domain'
+            when Admin::SidTypeAlias
+               @sid_type = 'alias'
+            when Admin::SidTypeWellKnownGroup
+               @sid_type = 'well_known_group'
+            when Admin::SidTypeDeletedAccount
+               @sid_type = 'deleted_account'
+            when Admin::SidTypeInvalid
+               @sid_type = 'invalid'
+            when Admin::SidTypeUnknown
+               @sid_type = 'unknown'
+            when Admin::SidTypeComputer
+               @sid_type = 'computer'
+            else
+               @sid_type = 'unknown'
+         end
+      end
+      
+      # Returns whether or not the account is disabled.
+      #
+      def disabled?
+         @disabled
+      end
+      
+      # Returns whether or not the account is local.
+      #
+      def local?
+         @local
+      end
+      
+      # Returns whether or not the account is locked out.
+      #
+      def lockout?
+         @lockout
+      end
+      
+      # Returns whether or not the password for the account is changeable.
+      #
+      def password_changeable?
+         @password_changeable
+      end
+      
+      # Returns whether or not the password for the account is changeable.
+      #
+      def password_expires?
+         @password_expires
+      end
+      
+      # Returns whether or not the a password is required for the account.
+      #
+      def password_required?
+         @password_required
+      end
+   end
+   
+   class Admin
+      # The version of the sys-admin library
+      VERSION = '1.5.3'
+
+      # This is the error raised in the majority of cases if anything goes wrong
+      # with any of the Sys::Admin methods.
+      #  
+      class Error < StandardError; end
+
+      SidTypeUser           = 1
+      SidTypeGroup          = 2
+      SidTypeDomain         = 3
+      SidTypeAlias          = 4
+      SidTypeWellKnownGroup = 5
+      SidTypeDeletedAccount = 6
+      SidTypeInvalid        = 7
+      SidTypeUnknown        = 8
+      SidTypeComputer       = 9
+
+      private
+
+      HKEY = "SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\ProfileList\\"
+
+      # Retrieves the user's home directory. For local accounts query the
+      # registry. For domain accounts use ADSI and use the HomeDirectory.
+      #
+      def self.get_home_dir(user, local = false, domain = nil)
+         if local
+            sec = Win32::Security::SID.open(user)
+            key = HKEY + sec.to_s
+            dir = nil
+
+            begin
+               Win32::Registry::HKEY_LOCAL_MACHINE.open(key) do |reg|
+                  dir = reg['ProfileImagePath']
+               end
+            rescue Win32::Registry::Error
+               # Not every local user has a home directory
+            end
+         else
+            domain ||= Socket.gethostname
+            adsi = WIN32OLE.connect("WinNT://#{domain}/#{user},user")
+            dir = adsi.get('HomeDirectory')
+         end
+         
+         dir
+      end
+
+      # A private method that lower cases all keys, and converts them
+      # all to symbols.
+      #
+      def self.munge_options(opts)
+         rhash = {}
+
+         opts.each{ |k, v|
+            k = k.to_s.downcase.to_sym
+            rhash[k] = v
+         }
+
+         rhash
+      end
+
+      # An internal, private method for getting a list of groups for
+      # a particular user.
+      #
+      def self.get_groups(domain, user)
+         array = []
+         adsi = WIN32OLE.connect("WinNT://#{domain}/#{user}")
+         adsi.groups.each{ |g| array << g.name }
+         array
+      end
+
+      # An internal, private method for getting a list of members for
+      # any particular group.
+      #
+      def self.get_members(domain, group)
+         array = []
+         adsi = WIN32OLE.connect("WinNT://#{domain}/#{group}")
+         adsi.members.each{ |g| array << g.name }
+         array
+      end
+      
+      # Used by the get_login method
+      GetUserName = Win32::API.new('GetUserName', 'PP', 'L', 'advapi32') # :nodoc:
+
+      public
+
+      # Creates the given +user+. If no domain option is specified,
+      # then it defaults to your local host, i.e. a local account is
+      # created.
+      #
+      # Any options provided are treated as IADsUser interface methods
+      # and are called before SetInfo is finally called.
+      #
+      # Examples:
+      #
+      #  # Create a local user with no options
+      #  Sys::Admin.add_user(:name => 'asmith')
+      #
+      #  # Create a local user with options
+      #  Sys::Admin.add_user(
+      #     :name        => 'asmith',
+      #     :description => 'Really cool guy',
+      #     :password    => 'abc123'
+      #  )
+      #
+      #  # Create a user on a specific domain
+      #  Sys::Admin.add_user(
+      #     :name     => 'asmith',
+      #     :domain   => 'XX',
+      #     :fullname => 'Al Smith'
+      #  )
+      #--
+      # Most options are passed to the 'put' method. However, we handle the
+      # password specially since it's a separate method, and some environments
+      # require that it be set up front.
+      #
+      def self.add_user(options = {})
+         options = munge_options(options)
+         
+         name   = options.delete(:name) or raise ArgumentError, 'No user given'
+         domain = options[:domain]
+
+         if domain.nil?
+            domain  = Socket.gethostname
+            moniker = "WinNT://#{domain},Computer"   
+         else
+            moniker = "WinNT://#{domain}"
+         end
+
+         begin   
+            adsi = WIN32OLE.connect(moniker)
+            user = adsi.create('user', name)  
+            options.each{ |option, value|
+               if option.to_s == 'password'
+                  user.setpassword(value)
+               else
+                  user.put(option.to_s, value)
+               end
+            }
+            user.setinfo
+         rescue WIN32OLERuntimeError => err
+            raise Error, err
+         end
+      end
+
+      # Configures the +user+ using +options+. If no domain option is
+      # specified then your local host is used, i.e. you are configuring
+      # a local user account.
+      #
+      # See http://tinyurl.com/3hjv9 for a list of valid options.
+      #
+      # In the case of a password change, pass a two element array as the
+      # old value and new value.
+      #
+      # Examples:
+      #
+      #  # Configure a local user
+      #  Sys::Admin.configure_user(
+      #     :name        => 'djberge',
+      #     :description => 'Awesome'
+      #  )
+      #
+      #  # Change the password
+      #  Sys::Admin.configure_user(
+      #     :name     => 'asmith',
+      #     :password => [old_pass, new_pass]
+      #  )
+      #
+      #  # Configure a user on a specific domain
+      #  Sys::Admin.configure_user(
+      #     :name      => 'jsmrz',
+      #     :domain    => 'XX',
+      #     :firstname => 'Jo'
+      #  )
+      #
+      def self.configure_user(options = {})
+         options = munge_options(options)
+
+         name   = options.delete(:name) or raise ArgumentError, 'No name given'
+         domain = options[:domain] || Socket.gethostname
+
+         begin     
+            adsi = WIN32OLE.connect("WinNT://#{domain}/#{name},user")
+            options.each{ |option, value|
+               if option.to_s == 'password'
+                  adsi.changepassword(value[0], value[1])
+               else
+                  adsi.put(option.to_s, value)
+               end
+            }
+            adsi.setinfo
+         rescue WIN32OLERuntimeError => err
+            raise Error, err
+         end
+      end
+
+      # Deletes the given +user+ on +domain+. If no domain is specified,
+      # then it defaults to your local host, i.e. a local account is
+      # deleted.
+      #
+      def self.delete_user(user, domain = nil)
+         if domain.nil?
+            domain  = Socket.gethostname
+            moniker = "WinNT://#{domain},Computer"   
+         else
+            moniker = "WinNT://#{domain}"
+         end
+
+         begin   
+            adsi = WIN32OLE.connect(moniker)
+            adsi.delete('user', user)  
+         rescue WIN32OLERuntimeError => err
+            raise Error, err
+         end
+      end
+
+      # Create a new +group+ using +options+. If no domain option is specified
+      # then a local group is created instead.
+      #
+      # Examples:
+      #
+      #  # Create a local group with no options
+      #  Sys::Admin.add_group(:name => 'Dudes')
+      #
+      #  # Create a local group with options
+      #  Sys::Admin.add_group(:name => 'Dudes', :description => 'Boys')
+      #
+      #  # Create a group on a specific domain
+      #  Sys::Admin.add_group(
+      #     :name        => 'Ladies',
+      #     :domain      => 'XYZ',
+      #     :description => 'Girls'
+      #  )
+      #
+      def self.add_group(options = {})
+         options = munge_options(options)
+
+         group  = options.delete(:name) or raise ArgumentError, 'No name given'
+         domain = options[:domain]
+
+         if domain.nil?
+            domain  = Socket.gethostname
+            moniker = "WinNT://#{domain},Computer"
+         else
+            moniker = "WinNT://#{domain}"
+         end
+
+         begin
+            adsi = WIN32OLE.connect(moniker)
+            group = adsi.create('group', group)
+            group.setinfo
+            configure_group(options) unless options.empty?
+         rescue WIN32OLERuntimeError => err
+            raise Error, err
+         end
+      end
+
+      # Configures the +group+ using +options+. If no domain option is
+      # specified then your local host is used, i.e. you are configuring
+      # a local group.
+      #
+      # See http://tinyurl.com/cjkzl for a list of valid options.
+      #
+      # Examples:
+      #
+      #  # Configure a local group.
+      #  Sys::Admin.configure_group(:name => 'Abba', :description => 'Swedish')
+      #
+      #  # Configure a group on a specific domain.
+      #  Sys::Admin.configure_group(
+      #     :name        => 'Web Team',
+      #     :domain      => 'Foo',
+      #     :description => 'Web programming cowboys'
+      #  )
+      #
+      def self.configure_group(options = {})
+         options = munge_options(options)
+
+         group  = options.delete(:name) or raise ArgumentError, 'No name given'
+         domain = options[:domain] || Socket.gethostname
+
+         begin                
+            adsi = WIN32OLE.connect("WinNT://#{domain}/#{group},group")
+            options.each{ |option, value| adsi.put(option.to_s, value) }
+            adsi.setinfo
+         rescue WIN32OLERuntimeError => err
+            raise Error, err
+         end
+      end
+
+      # Delete the +group+ from +domain+. If no domain is specified, then
+      # you are deleting a local group.
+      #
+      def self.delete_group(group, domain = nil)
+         if domain.nil?
+            domain = Socket.gethostname
+            moniker = "WinNT://#{domain},Computer"
+         else
+            moniker = "WinNT://#{domain}"
+         end
+
+         begin
+            adsi = WIN32OLE.connect(moniker)
+            obj = adsi.delete('group', group)
+         rescue WIN32OLERuntimeError => err
+            raise Error, err
+         end
+      end
+      
+      # Returns the user name (only) of the current login.
+      #
+      def self.get_login
+         buffer = 0.chr * 256
+         nsize  = [buffer.size].pack("L")
+
+         if GetUserName.call(buffer, nsize) == 0
+            raise Error, 'GetUserName() call failed in get_login'
+         end
+
+         length   = nsize.unpack('L')[0]
+         username = buffer[0 ... length].chop
+         username
+      end
+
+      # Returns a User object based on either +name+ or +uid+.
+      #
+      # call-seq:
+      #    Sys::Admin.get_user(name, options = {})
+      #    Sys::Admin.get_user(uid, options = {})
+      #
+      # Looks for +usr+ information based on the options you specify, where
+      # the +usr+ argument can be either a user name or a RID.
+      #
+      # If a 'host' option is specified, information is retrieved from that
+      # host. Otherwise, the local host is used.
+      #
+      # All other options are converted to WQL statements against the
+      # Win32_UserAccount WMI object. See http://tinyurl.com/by9nvn for a
+      # list of possible options.
+      #
+      # Examples:
+      #
+      #  # Get a user by name
+      #  Admin.get_user('djberge')
+      #
+      #  # Get a user by uid
+      #  Admin.get_user(100)
+      #
+      #  # Get a user on a specific domain
+      #  Admin.get_user('djberge', :domain => 'TEST')
+      #--
+      # The reason for keeping the +usr+ variable as a separate argument
+      # instead of rolling it into the options hash was to keep a unified
+      # API between the Windows and UNIX versions.
+      #
+      def self.get_user(usr, options = {})
+         options = munge_options(options)
+
+         host = options.delete(:host) || Socket.gethostname
+         cs = "winmgmts:{impersonationLevel=impersonate}!"
+         cs << "//#{host}/root/cimv2"
+         
+         begin
+            wmi = WIN32OLE.connect(cs)
+         rescue WIN32OLERuntimeError => err
+            raise Error, err
+         end
+         
+         query = "select * from win32_useraccount"
+
+         i = 0
+
+         options.each{ |opt, val|
+            if i == 0
+               query << " where #{opt} = '#{val}'"
+               i += 1
+            else
+               query << " and #{opt} = '#{val}'"
+            end
+         }
+
+         if usr.kind_of?(Fixnum)
+            query << " and sid like '%-#{usr}'"
+         else
+            query << " and name = '#{usr}'"
+         end
+
+         domain = options[:domain] || host
+         
+         wmi.execquery(query).each{ |user|
+            uid = user.sid.split('-').last.to_i
+
+            # Because our 'like' query isn't fulproof, let's parse
+            # the SID again to make sure
+            if usr.kind_of?(Fixnum)
+               next if usr != uid
+            end
+
+            user_object = User.new do |u|
+               u.account_type        = user.accounttype
+               u.caption             = user.caption
+               u.description         = user.description
+               u.disabled            = user.disabled
+               u.domain              = user.domain
+               u.full_name           = user.fullname
+               u.install_date        = user.installdate
+               u.local               = user.localaccount
+               u.lockout             = user.lockout
+               u.name                = user.name
+               u.password_changeable = user.passwordchangeable
+               u.password_expires    = user.passwordexpires
+               u.password_required   = user.passwordrequired
+               u.sid                 = user.sid
+               u.sid_type            = user.sidtype
+               u.status              = user.status
+               u.uid                 = uid
+               u.groups              = get_groups(domain, user.name)
+               u.dir                 = get_home_dir(user.name, options[:localaccount], domain)
+            end
+
+            return user_object
+         }
+
+         # If we're here, it means it wasn't found.
+         raise Error, "no user found for '#{usr}'"
+      end
+      
+      # In block form, yields a User object for each user on the system. In
+      # non-block form, returns an Array of User objects.
+      #
+      # call-seq:
+      #    Sys::Admin.users(options = {})
+      #    Sys::Admin.users(options = {}){ |user| ... }
+      #
+      # You may specify a host from which information is retrieved. The
+      # default is the local host.
+      #
+      # All other arguments are passed as WQL query parameters against
+      # the Win32_UserAccont WMI object.
+      #
+      # Examples:
+      #
+      #  # Get all local account users
+      #  Sys::Admin.users(:localaccount => true)
+      #
+      #  # Get all user accounts on a specific domain
+      #  Sys::Admin.users(:domain => 'FOO')
+      #
+      #  # Get a single user from a domain
+      #  Sys::Admin.users(:name => 'djberge', :domain => 'FOO')
+      #
+      def self.users(options = {})
+         options = munge_options(options)
+
+         host = options.delete(:host) || Socket.gethostname
+         cs = "winmgmts:{impersonationLevel=impersonate}!"
+         cs << "//#{host}/root/cimv2"
+         
+         begin
+            wmi = WIN32OLE.connect(cs)
+         rescue WIN32OLERuntimeError => e
+            raise Error, e
+         end
+         
+         query = "select * from win32_useraccount"
+
+         i = 0
+
+         options.each{ |opt, val|
+            if i == 0
+               query << " where #{opt} = '#{val}'"
+               i += 1
+            else
+               query << " and #{opt} = '#{val}'"
+            end
+         }
+
+         array = []
+         domain = options[:domain] || host
+         
+         wmi.execquery(query).each{ |user|
+            uid = user.sid.split('-').last.to_i
+
+            usr = User.new do |u|
+               u.account_type        = user.accounttype
+               u.caption             = user.caption
+               u.description         = user.description
+               u.disabled            = user.disabled
+               u.domain              = user.domain
+               u.full_name           = user.fullname
+               u.install_date        = user.installdate
+               u.local               = user.localaccount
+               u.lockout             = user.lockout
+               u.name                = user.name
+               u.password_changeable = user.passwordchangeable
+               u.password_expires    = user.passwordexpires
+               u.password_required   = user.passwordrequired
+               u.sid                 = user.sid
+               u.sid_type            = user.sidtype
+               u.status              = user.status
+               u.groups              = get_groups(domain, user.name)
+               u.uid                 = uid
+               u.dir                 = get_home_dir(user.name, options[:localaccount], host)
+            end
+            
+            if block_given?
+               yield usr
+            else
+               array.push(usr)
+            end
+         }
+
+         return array unless block_given?
+      end
+      
+      # Returns a Group object based on either +name+ or +gid+.
+      #
+      # call-seq:
+      #    Sys::Admin.get_group(name, options = {})
+      #    Sys::Admin.get_group(gid, options = {})
+      #
+      # If a numeric value is sent as the first parameter, it is treated
+      # as a RID and is checked against the SID for a match.
+      #
+      # You may specify a host as an option from which information is
+      # retrieved. The default is the local host.
+      #
+      # All other options are passed as WQL parameters to the Win32_Group
+      # WMI object. See http://tinyurl.com/bngc8s for a list of possible
+      # options.
+      #  
+      # Examples:
+      #
+      #  # Find a group by name
+      #  Sys::Admin.get_group('Web Team')
+      #
+      #  # Find a group by id
+      #  Sys::Admin.get_group(31667)
+      #
+      #  # Find a group on a specific domain
+      #  Sys::Admin.get_group('Web Team', :domain => 'FOO')
+      #
+      def self.get_group(grp, options = {})
+         options = munge_options(options)
+
+         host = options.delete(:host) || Socket.gethostname
+         cs = "winmgmts:{impersonationLevel=impersonate}!"
+         cs << "//#{host}/root/cimv2"
+
+         begin
+            wmi = WIN32OLE.connect(cs)
+         rescue WIN32OLERuntimeError => err
+            raise Error, err
+         end
+                  
+         query = "select * from win32_group"
+
+         i = 0
+
+         options.each{ |opt, val|
+            if i == 0
+               query << " where #{opt} = '#{val}'"
+               i += 1
+            else
+               query << " and #{opt} = '#{val}'"
+            end
+         }
+         
+         if grp.kind_of?(Fixnum)
+            query << " and sid like '%-#{grp}'"
+         else
+            query << " and name = '#{grp}'"
+         end
+
+         domain = options[:domain] || host
+         
+         wmi.execquery(query).each{ |group|
+            gid = group.sid.split("-").last.to_i
+            
+            # Because our 'like' query isn't fulproof, let's parse
+            # the SID again to make sure
+            if grp.kind_of?(Fixnum)              
+               next if grp != gid
+            end
+            
+            group_object = Group.new do |g|
+               g.caption      = group.caption
+               g.description  = group.description              
+               g.domain       = group.domain
+               g.gid          = gid
+               g.install_date = group.installdate
+               g.local        = group.localaccount
+               g.name         = group.name   
+               g.sid          = group.sid                         
+               g.sid_type     = group.sidtype
+               g.status       = group.status
+               g.members      = get_members(domain, group.name)
+            end
+
+            return group_object
+         }
+
+         # If we're here, it means it wasn't found.
+         raise Error, "no group found for '#{grp}'"
+      end
+   
+      # In block form, yields a Group object for each user on the system.  In
+      # non-block form, returns an Array of Group objects.
+      #
+      # call-seq:
+      #    groups(options = {})
+      #    groups(options = {}){ |group| ... }
+      #
+      # You may specify a host option from which information is retrieved.
+      # The default is the local host.
+      #
+      # All other options are passed as WQL parameters to the Win32_Group
+      # WMI object. See http://tinyurl.com/bngc8s for a list of possible
+      # options.
+      #
+      # Examples:
+      #
+      #  # Get local group information
+      #  Sys::Admin.groups(:localaccount => true)
+      #
+      #  # Get all groups on a specific domain
+      #  Sys::Admin.groups(:domain => 'FOO')
+      #
+      #  # Get a specific group on a domain
+      #  Sys::Admin.groups(:name => 'Some Group', :domain => 'FOO')
+      #
+      def self.groups(options = {})
+         options = munge_options(options)
+
+         host = options.delete(:host) || Socket.gethostname
+         cs = "winmgmts:{impersonationLevel=impersonate}!"
+         cs << "//#{host}/root/cimv2"
+         
+         begin
+            wmi = WIN32OLE.connect(cs)
+         rescue WIN32OLERuntimeError => err
+            raise Error, err
+         end
+         
+         query = "select * from win32_group"
+
+         i = 0
+
+         options.each{ |opt, val|
+            if i == 0
+               query << " where #{opt} = '#{val}'"
+               i += 1
+            else
+               query << " and #{opt} = '#{val}'"
+            end
+         }
+
+         array = []
+         domain = options[:domain] || host
+
+         wmi.execquery(query).each{ |group|
+            grp = Group.new do |g|
+               g.caption      = group.caption
+               g.description  = group.description              
+               g.domain       = group.domain
+               g.gid          = group.sid.split("-").last.to_i
+               g.install_date = group.installdate
+               g.local        = group.localaccount
+               g.name         = group.name   
+               g.sid          = group.sid                         
+               g.sid_type     = group.sidtype
+               g.status       = group.status
+               g.members      = get_members(domain, group.name)
+            end
+
+            if block_given?
+               yield grp
+            else
+               array.push(grp)
+            end
+         }
+
+         return array unless block_given?
+      end
+   end
+end