sys-admin 1.7.0 → 1.7.5

data/{MANIFEST → MANIFEST.md}

@@ -1,18 +1,19 @@
-* sys-admin.gemspec
-* CHANGES
-* MANIFEST
-* Rakefile
-* README
-* certs/djberg96_pub.pem
-* examples/groups.rb
-* examples/users.rb
-* lib/sys/admin.rb
-* lib/darwin/sys/admin.rb
-* lib/linux/sys/admin.rb
-* lib/bsd/sys/admin.rb
-* lib/sunos/sys/admin.rb
-* lib/sys/admin/common.rb
-* lib/sys/admin/custom.rb
-* test/test_sys_admin.rb
-* test/test_sys_admin_unix.rb
-* test/test_sys_admin_windows.rb
+* sys-admin.gemspec
+* CHANGES.rdoc
+* LICENSE
+* MANIFEST.rdoc
+* Rakefile
+* README.rdoc
+* certs/djberg96_pub.pem
+* examples/groups.rb
+* examples/users.rb
+* lib/sys/admin.rb
+* lib/darwin/sys/admin.rb
+* lib/linux/sys/admin.rb
+* lib/bsd/sys/admin.rb
+* lib/sunos/sys/admin.rb
+* lib/sys/admin/common.rb
+* lib/sys/admin/custom.rb
+* test/test_sys_admin.rb
+* test/test_sys_admin_unix.rb
+* test/test_sys_admin_windows.rb

data/README.md

@@ -0,0 +1,159 @@
+## Description
+The sys-admin library is a unified, cross platform replacement for the Etc module.
+   
+## Installation
+`gem install sys-admin`
+
+## Synopsis
+```ruby
+require 'sys/admin' # or sys-admin
+include Sys
+
+# Returns an Array of User objects
+a = Admin.users
+
+# Returns an Array of Group objects
+g = Admin.groups
+
+# Get information about a particular user
+p Admin.get_user("nobody")
+p Admin.get_user("nobody", :localaccount => true)
+
+# Get information about a particular group
+p Admin.get_group("adm")
+p Admin.get_group("adm", :localaccount => true)
+```
+
+## Admin
+  `Admin.get_login`
+
+Returns the user name (only) of the current login.
+
+```
+Admin.get_user(name, options = {})
+Admin.get_user(uid, options = {})
+```
+
+Returns a User object based on `name` or `uid`. The `options` hash is
+for MS Windows only, and allows you to restrict the search based on the
+options you provide, e.g. 'domain' or 'localaccount'.
+   
+```
+Admin.get_group(name, options = {})
+Admin.get_group(gid, options = {})
+```
+
+Returns a Group object based on `name` or `uid`. The `options` hash is
+for MS Windows only, and allows you to restrict the search based on the
+options you provide, e.g. 'domain' or 'localaccount'.
+
+`Admin.groups(options = {})`
+
+Returns an Array of Group objects.
+
+The `options` hash is for MS Windows only, and allows you to restrict the
+search based on the options you provide, e.g. 'domain' or 'localaccount'.
+
+`Admin.users(options = {})`
+
+Returns an Array of User objects.
+   
+The `options` hash is for MS Windows only, and allows you to restrict the
+search based on the options you provide, e.g. 'domain' or 'localaccount'.
+   
+## User class
+### User (Windows)
+The User class has the following attributes on MS Windows systems:
+	
+  * account_type
+  * caption
+  * description
+  * domain
+  * password
+  * full_name
+  * gid
+  * install_date
+  * name
+  * sid
+  * status
+  * disabled?
+  * local?
+  * lockout?
+  * password_changeable?
+  * password_expires?
+  * password_required?
+  * uid
+     
+### User (Unix)
+The User class has the following attributes on Unix systems:
+	
+  * name
+  * passwd
+  * uid
+  * gid
+  * dir
+  * shell
+  * gecos
+  * quota
+  * age
+  * class
+  * comment
+  * change
+  * expire
+
+## Group Classes
+### Group (Windows)
+The Group class has the following attributes on MS Windows systems:
+	
+  * caption
+  * description
+  * domain
+  * install_date
+  * name
+  * sid
+  * status
+  * gid
+  * local?
+	
+### Group (Unix)
+The Group class has the following attributes on Unix systems:
+	
+  * name
+  * gid
+  * members
+  * passwd
+
+## Error Classes
+`Admin::Error < StandardError`
+
+Raised if anything goes wrong with any of the above methods.
+
+## Developer's Notes
+### MS Windows
+The Windows version now uses a win32ole + WMI approach to getting
+information.  This means that the WMI service must be running on the
+target machine in order to work (which it is, by default).
+	
+### UNIX
+The underlying implementation is similar to core Ruby's Etc implementation.
+But, in addition to the different interface, I use the re-entrant version
+of the appropriate functions when available.
+
+## Future Plans
+* Make the User and Group objects comparable.
+* Add ability to add, configure and delete users on Unix platforms.
+
+## Known Bugs
+None that I'm aware of. If you find any, please log them on the project page at:
+
+  https://github.com/djberg96/sys-admin
+
+## License
+Apache-2.0
+
+## Copyright
+(C) 2005-2020, Daniel J. Berger
+All Rights Reserved
+
+## Author
+Daniel J. Berger

data/Rakefile

@@ -1,47 +1,47 @@
-require 'rake'
-require 'rake/clean'
-require 'rake/testtask'
-require 'rbconfig'
-
-CLEAN.include("**/*.gem", "**/*.rbx", "**/*.rbc", "ruby.core")
-
-namespace :gem do
-  desc "Create the sys-uname gem"
-  task :create => [:clean] do
-    require 'rubygems/package'
-    spec = eval(IO.read('sys-admin.gemspec'))
-    spec.signing_key = File.join(Dir.home, '.ssh', 'gem-private_key.pem')
-    Gem::Package.build(spec, true)
-  end
-
-  desc "Install the sys-uname gem"
-  task :install => [:create] do
-    file = Dir["*.gem"].first
-    sh "gem install -l #{file}"
-  end
-end
-
-Rake::TestTask.new('test') do |t|
-  case RbConfig::CONFIG['host_os']
-  when /darwin|osx/i
-    t.libs << 'lib/darwin'
-  when /linux/i
-    t.libs << 'lib/linux'
-  when /sunos|solaris/i
-    t.libs << 'lib/sunos'
-  when /bsd/i
-    t.libs << 'lib/bsd'
-  when /windows|win32|mingw|cygwin|dos/i
-    t.libs << 'lib/windows'
-  else
-    t.libs << 'lib/unix'
-  end
-
-  t.warning = true
-  t.verbose = true
-
-  t.libs << 'test'
-  t.test_files = FileList['test/test_sys_admin.rb']
-end
-
-task :default => :test
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rbconfig'
+
+CLEAN.include("**/*.gem", "**/*.rbx", "**/*.rbc", "ruby.core")
+
+namespace :gem do
+  desc "Create the sys-uname gem"
+  task :create => [:clean] do
+    require 'rubygems/package'
+    spec = eval(IO.read('sys-admin.gemspec'))
+    spec.signing_key = File.join(Dir.home, '.ssh', 'gem-private_key.pem')
+    Gem::Package.build(spec, true)
+  end
+
+  desc "Install the sys-uname gem"
+  task :install => [:create] do
+    file = Dir["*.gem"].first
+    sh "gem install -l #{file}"
+  end
+end
+
+Rake::TestTask.new('test') do |t|
+  case RbConfig::CONFIG['host_os']
+  when /darwin|osx/i
+    t.libs << 'lib/darwin'
+  when /linux/i
+    t.libs << 'lib/linux'
+  when /sunos|solaris/i
+    t.libs << 'lib/sunos'
+  when /bsd/i
+    t.libs << 'lib/bsd'
+  when /windows|win32|mingw|cygwin|dos/i
+    t.libs << 'lib/windows'
+  else
+    t.libs << 'lib/unix'
+  end
+
+  t.warning = true
+  t.verbose = true
+
+  t.libs << 'test'
+  t.test_files = FileList['test/test_sys_admin.rb']
+end
+
+task :default => :test

data/certs/djberg96_pub.pem

@@ -1,26 +1,26 @@
 -----BEGIN CERTIFICATE-----
 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
-MB4XDTE4MDIxOTIzMjIxMloXDTI4MDIxNzIzMjIxMlowPzERMA8GA1UEAwwIZGpi
+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
-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
+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
 -----END CERTIFICATE-----

data/doc/sys-admin-unix.txt

@@ -1,162 +1,162 @@
-= Description
-A unified, cross-platform replacement for the Etc module that allows you to
-get information about users and groups.
-
-= Synopsis
-   require 'sys/admin'
-   include Sys
-
-   Admin.get_login           # -> 'djberge'
-   Admin.get_user('djberge') # -> Admin::User object
-   Admin.get_group(501)      # -> Admin::Group object
-
-   # Iterate over all users
-   Admin.users do |usr|
-      p usr
-   end
-
-   # Iterate over all groups
-   Admin.groups do |grp|
-      p grp
-   end
-
-= Constants
-
-= Class Methods
-== Sys::Admin
-Admin.get_group(name)
-Admin.get_group(gid)
-   Returns a Group object for the given name or gid. Raises an Admin::Error
-   if a group cannot be found for that name or GID.
-
-Admin.get_login
-   Returns the login for the process. If this is called from a process that
-   has no controlling terminal, then it resorts to returning the "LOGNAME"
-   or "USER" environment variable. If neither of those is defined, then nil
-   is returned.
-
-   Note that this method will probably return the real user login, but may
-   return the effective user login. YMMV depending on your platform and how
-   the program is run.
-
-Admin.get_user(name)
-Admin.get_user(uid)
-   Returns a User object for the given name or uid. Raises an Admin::Error if
-   a user cannot be found for that name or user ID.
-
-Admin.groups
-Admin.groups{ |grp| ... }
-   In block form, yields a Group object for each group on the system. In
-   non-block form, returns an Array of Group objects.
-
-Admin.users
-Admin.users{ |grp| ... }
-   In block form, yields a User object for each group on the system. In
-   non-block form, returns an Array of User objects.
-
-== Sys::Admin::Group
-Group.new
-Group.new{ |grp| ... }
-   Creates and returns a Group object, which encapsulates the information
-   typically found within an /etc/group entry, i.e. a struct group. If a
-   block is provided, yields the object back to the block.
-
-   At the moment this is only useful for MS Windows.
-
-== Sys::Admin::User
-User.new
-User.new{ |usr| ... }
-   Creates and returns a User object, which encapsulates the information
-   typically found within an /etc/passwd entry, i.e. a struct passwd. If a
-   block is provided, yields the object back to the block.
-
-   At the moment this is only useful for MS Windows.
-
-= Instance Methods
-== Sys::Admin::Group
-Group#gid
-   The group id.
-
-Group#members
-   An array of users that are members of the group.
-
-Group#name
-   The name of the group.
-
-Group#passwd
-   The group password, if any.
-
-== Sys::Admin::User
-User#age
-   Used in the past for password aging. Deprecated in favor of /etc/shadow.
-
-User#change
-   Next date a password change will be needed.
-
-User#class
-   The user's access class.
-
-User#comment
-   Another comment field. Rarely used.
-
-User#dir
-   The absolute pathname of the user's home directory.
-
-User#expire
-   Account expiration date.
-
-User#gecos
-   A comment field. Rarely used.
-
-User#gid
-   The user's primary group id.
-
-User#login_device
-   The name of the terminal device the user last logged on with.
-
-User#login_host
-   The hostname from which the user last logged in.
-
-User#login_time
-   The last time the user logged in.
-
-User#name
-   The user name associated with the account.
-
-User#passwd
-   The user's encrypted password. Deprecated in favor of /etc/shadow.
-
-User#quota
-   The user's alloted amount of disk space.
-
-User#shell
-   The user's login shell.
-
-User#uid
-   The user's user id.
-
-== Notes
-   Not all platforms support all of the User members. The only ones that are
-   supported on all platforms are name, uid, gid, dir and shell. The rest
-   will simply return nil if they aren't supported.
-   
-== Known Bugs
-   None that I am aware of. Please log any bugs you find on the project
-   website at http://www.rubyforge.org/projects/sysutils.
-
-== License
-   Artistic 2.0
-
-== Copyright
-   Copyright 2002-2014, Daniel J. Berger
-
-   All Rights Reserved. This module is free software. It may be used,
-   redistributed and/or modified under the same terms as Ruby itself.
-
-== Warranty
-   This library is provided "as is" and without any express or
-   implied warranties, including, without limitation, the implied
-   warranties of merchantability and fitness for a particular purpose.
-
-== Author
-   Daniel J. Berger
+= Description
+A unified, cross-platform replacement for the Etc module that allows you to
+get information about users and groups.
+
+= Synopsis
+   require 'sys/admin'
+   include Sys
+
+   Admin.get_login           # -> 'djberge'
+   Admin.get_user('djberge') # -> Admin::User object
+   Admin.get_group(501)      # -> Admin::Group object
+
+   # Iterate over all users
+   Admin.users do |usr|
+      p usr
+   end
+
+   # Iterate over all groups
+   Admin.groups do |grp|
+      p grp
+   end
+
+= Constants
+
+= Class Methods
+== Sys::Admin
+Admin.get_group(name)
+Admin.get_group(gid)
+   Returns a Group object for the given name or gid. Raises an Admin::Error
+   if a group cannot be found for that name or GID.
+
+Admin.get_login
+   Returns the login for the process. If this is called from a process that
+   has no controlling terminal, then it resorts to returning the "LOGNAME"
+   or "USER" environment variable. If neither of those is defined, then nil
+   is returned.
+
+   Note that this method will probably return the real user login, but may
+   return the effective user login. YMMV depending on your platform and how
+   the program is run.
+
+Admin.get_user(name)
+Admin.get_user(uid)
+   Returns a User object for the given name or uid. Raises an Admin::Error if
+   a user cannot be found for that name or user ID.
+
+Admin.groups
+Admin.groups{ |grp| ... }
+   In block form, yields a Group object for each group on the system. In
+   non-block form, returns an Array of Group objects.
+
+Admin.users
+Admin.users{ |grp| ... }
+   In block form, yields a User object for each group on the system. In
+   non-block form, returns an Array of User objects.
+
+== Sys::Admin::Group
+Group.new
+Group.new{ |grp| ... }
+   Creates and returns a Group object, which encapsulates the information
+   typically found within an /etc/group entry, i.e. a struct group. If a
+   block is provided, yields the object back to the block.
+
+   At the moment this is only useful for MS Windows.
+
+== Sys::Admin::User
+User.new
+User.new{ |usr| ... }
+   Creates and returns a User object, which encapsulates the information
+   typically found within an /etc/passwd entry, i.e. a struct passwd. If a
+   block is provided, yields the object back to the block.
+
+   At the moment this is only useful for MS Windows.
+
+= Instance Methods
+== Sys::Admin::Group
+Group#gid
+   The group id.
+
+Group#members
+   An array of users that are members of the group.
+
+Group#name
+   The name of the group.
+
+Group#passwd
+   The group password, if any.
+
+== Sys::Admin::User
+User#age
+   Used in the past for password aging. Deprecated in favor of /etc/shadow.
+
+User#change
+   Next date a password change will be needed.
+
+User#class
+   The user's access class.
+
+User#comment
+   Another comment field. Rarely used.
+
+User#dir
+   The absolute pathname of the user's home directory.
+
+User#expire
+   Account expiration date.
+
+User#gecos
+   A comment field. Rarely used.
+
+User#gid
+   The user's primary group id.
+
+User#login_device
+   The name of the terminal device the user last logged on with.
+
+User#login_host
+   The hostname from which the user last logged in.
+
+User#login_time
+   The last time the user logged in.
+
+User#name
+   The user name associated with the account.
+
+User#passwd
+   The user's encrypted password. Deprecated in favor of /etc/shadow.
+
+User#quota
+   The user's alloted amount of disk space.
+
+User#shell
+   The user's login shell.
+
+User#uid
+   The user's user id.
+
+== Notes
+   Not all platforms support all of the User members. The only ones that are
+   supported on all platforms are name, uid, gid, dir and shell. The rest
+   will simply return nil if they aren't supported.
+   
+== Known Bugs
+   None that I am aware of. Please log any bugs you find on the project
+   website at http://www.rubyforge.org/projects/sysutils.
+
+== License
+   Artistic 2.0
+
+== Copyright
+   Copyright 2002-2014, Daniel J. Berger
+
+   All Rights Reserved. This module is free software. It may be used,
+   redistributed and/or modified under the same terms as Ruby itself.
+
+== Warranty
+   This library is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+
+== Author
+   Daniel J. Berger