Parent

Sys::Admin

The Admin class provides a unified, cross platform replacement for the Etc module.

Public Class Methods

add_group(options = {}) click to toggle source

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'
)
# File lib/windows/sys/admin.rb, line 539
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
add_user(options = {}) click to toggle source

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'
)
# File lib/windows/sys/admin.rb, line 417
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
configure_group(options = {}) click to toggle source

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 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'
)
# File lib/windows/sys/admin.rb, line 580
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
configure_user(options = {}) click to toggle source

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 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'
)
# File lib/windows/sys/admin.rb, line 478
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
delete_group(group, domain = nil) click to toggle source

Delete the group from domain. If no domain is specified, then you are deleting a local group.

# File lib/windows/sys/admin.rb, line 598
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)
    adsi.delete('group', group)
  rescue WIN32OLERuntimeError => err
    raise Error, err
  end
end
delete_user(user, domain = nil) click to toggle source

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.

# File lib/windows/sys/admin.rb, line 505
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
Sys::Admin.get_group(name, options = {}) click to toggle source
Sys::Admin.get_group(gid, options = {})

Returns a Group object based on either name or gid.

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 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')
# File lib/windows/sys/admin.rb, line 837
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
get_login() click to toggle source

Returns the user name (only) of the current login.

# File lib/windows/sys/admin.rb, line 616
def self.get_login
  buffer = 0.chr * 256
  nsize  = FFI::MemoryPointer.new(:ulong)
  nsize.write_ulong(buffer.size)

  unless GetUserNameW(buffer, nsize)
    raise Error, 'GetUserName() call failed in get_login'
  end

  buffer.strip.tr(0.chr, '')
end
Sys::Admin.get_user(name, options = {}) click to toggle source
Sys::Admin.get_user(uid, options = {})

Returns a User object based on either name or uid.

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 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')
# File lib/windows/sys/admin.rb, line 659
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
groups(options = {}) click to toggle source

Returns an array of Group objects for each user on the system.

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 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')
# File lib/windows/sys/admin.rb, line 921
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

    array.push(grp)
  }

  array
end
users(options = {}) click to toggle source

Returns an array of User objects for each user on the system.

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')
# File lib/windows/sys/admin.rb, line 750
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

    array.push(usr)
  }

  array
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.