Gem to assist in performing common systems administration tasks in OSX
Ruby C
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Gem Version Code Climate


Gem to assist in performing common systems administration tasks in OS X


MacAdmin endeavors to provide an OO programming interface for constituent OS X system resources. It's comprised of classes with the ability to parse Apple Property Lists (CFPropertyList) and manipulate them as native Ruby objects. The classes work directly with the Property Lists used to abstract OS X system resources -- users, groups, computers, computergroups, etc. -- bypassing the common utilities and APIs normally reserved for this kind of work.

This approach has trade-offs, but it does result in a very powerful and simple model for managing these resources (See Notes).


Before forking/cloning/using/testing/etc MacAdmin, please read the license (LICENSE.txt).

One important trade-off worth mentioning when using this gem is that you must have root priviledge in order to access (read) any resources in the DSLocal domains or similarily protected directories and files. This is different from using utils like dscl, but not unlike using defaults. Naturally, as with any of these methods, you must also be root in order to make any changes. The code examples below will require root access when performing create operations.

Another important condition to mention is that it will often be necessary to restart OS X's directory service in order to see the changes you've made to any of the affected plists. This can be bothersome and susceptible to race conditions, but in general, it's a manageable issue.


  • Mac OS X 10.5 and up
  • Xcode Command Line Tools



RubyGems should install any dependencies:

$ sudo gem install macadmin


Install the bundler gem:

$ sudo gem install bundler

Clone this repo:

$ cd ~/Downloads
$ git clone

Install the gem dependencies:

$ cd macadmin
$ sudo bundle install

Run the tests:

$ rake

Install the gem:

$ sudo rake install

Test the installation:

Note the path parameter to #create -- use this for testing resource creation in arbitrary directories. Also works for #destroy.
$ cd ~/Downloads
$ irb -r 'macadmin'
>> foobar = 'foobar'
=> {"passwd"=>["********"], "gid"=>["20"], "uid"=>["501"], "shell"=>["/bin/bash"], "name"=>["foobar"], "realname"=>["foobar"], "generateduid"=>["4871DD7C-5C55-47DB-8A7B-B38CBD6DA5A9"], "comment"=>[""], "home"=>["/Users/foobar"]}
>> foobar.exists?
=> false
>> foobar.create "./foobar.plist"
>> foobar.destroy "./foobar.plist"
>> exit


Load the gems:

require 'rubygems'
require 'macadmin'

Create a new node:

# Here's something cool: 
# DSLocalNode will automatically add this custom node to OpenDirectory sandbox when running on 10.8 and up
my_custom_node = 'MCX'

Create a computer record on that node:

computer = :name => `hostname -s`.chomp, :node => 'MCX'

Create a computer group, add the computer record as a member, and apply some policy (on that node):

# Here's a bnuch of policy written as XML, but the mcximport method can also take a file path parameter and load it that way
raw_xml_policy = <<-RAW_XML_CONTENT
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

computer_group = :name => 'mcx', :realname => 'MCX', :node => 'MCX'
computer_group.add_user `hostname -s`.chomp
computer_group.mcximport raw_xml_policy

Create an administrator for your new node:

# Generate a platform appropriate password from a plaintext string
password = Password.apropos "secret_passphrase"
administrator = :name => 'mcxadmin', :password => password, :gid => 80, :node => 'MCX'

Restart the directory services to seal the deal:


Explore a bit...

require 'pp'

# Show the User object
admin = :name => 'mcxadmin', :node => 'MCX'
pp admin.record if admin.exists?

# Show the MCX policy attached to the ComputerGroup object
comp_grp = :name => 'mcx', :node => 'MCX'
puts "Does this local computer group have MCX policy?"
puts comp_grp.has_mcx? ? "Sweet!" : "Bummer..."
puts comp_grp.mcxexport

Tear it down...

# This will take down the entire node we just created and populated: user, computers, computer groups, etc.
mcx_node = 'MCX'



This gem would not be possible without ckuse's CFPropertyList. Thanks, Christian.