class Jamf::Configuration

A class for working with pre-defined settings & preferences for the JSS Gem

This is a singleton class, only one instance can exist at a time.

When the JSS module loads, that instance is created, and can then be used via Jamf.config in applications to avoid always having to pass in server names, API user names and so on.

When the Jamf::Configuration instance is created, the {GLOBAL_CONF} file (/etc/jss_gem.conf) is examined if it exists, and the items in it are loaded into the attributes.

Then the user-specific {USER_CONF} file (~/.jss_gem.conf) is examined if it exists, and any attributes defined there will override those values from the {GLOBAL_CONF}.

The file format is one attribute per line, thus:

attr_name: value

Lines that don’t start with a known attribute name followed by a colon are ignored. If an attribute is defined more than once, the last one wins.

The known attributes are:

The {APIConnection#connect} method will first use any values given as method arguments. For any not given, it will look at the Preferences instance for any values there, and if still none, will use default values or raise an exception.

At any point, the attributes can read or changed using standard Ruby getter/setter methods matching the name of the attribute, e.g.

Jamf.config.api_server_name  # => 'myjss.mycompany.com'
Jamf.config.api_server_name = 'otherjss.mycompany.com'  # sets the api_server_name to a new value

The current settings may be saved to the GLOBAL_CONF file, the USER_CONF file, or an arbitrary file using {#save}. The argument to {#save} should be either :user, :global, or a String or Pathname file path. NOTE: This overwrites any existing file.

To re-load the settings use {#reload}. This clears the current settings, and re-reads both the global and user files. If a pathname is provided, e.g.

Jamf::CONFIG.reload '/path/to/other/file'

the current settings are cleared and reloaded from that other file.

To view the current settings, use {#print}.

@note Passwords are not saved in prefs files. Your application will have to acquire them using the :prompt or :stdin options to

{APIConnection#connect}, or by custom means.

Constants

CONF_FILES

The filename for storing the config, globally or user-level. The first matching file is used - the array provides backward compatibility with earlier versions. Saving will always happen to the first filename

CONF_KEYS

The attribute keys we maintain, and the type they should be stored as

GLOBAL_CONFS

The Pathname to the machine-wide preferences plist

USER_CONFS

The Pathname to the user-specific preferences plist

Public Class Methods

new() click to toggle source

Initialize!

    # File lib/jamf/configuration.rb
142 def initialize
143   read_global
144   read_user
145 end

Public Instance Methods

clear_all() click to toggle source

Clear all values

@return [void]

    # File lib/jamf/configuration.rb
156 def clear_all
157   CONF_KEYS.keys.each { |k| send "#{k}=".to_sym, nil }
158 end
print() click to toggle source

Print out the current settings to stdout

@return [void]

read_global() click to toggle source

(Re)read the global prefs, if it exists.

@return [void]

    # File lib/jamf/configuration.rb
165 def read_global
166   GLOBAL_CONFS.each do |gcf|
167     if gcf.file? and gcf.readable?
168       read gcf
169       return
170     end
171   end
172 end
read_user() click to toggle source

(Re)read the user prefs, if it exists.

@return [void]

    # File lib/jamf/configuration.rb
179 def read_user
180   USER_CONFS.each do |ucf|
181     if ucf.file? and ucf.readable?
182       read ucf
183       return
184     end
185   end
186 end
reload(file = nil) click to toggle source

Clear the settings and reload the prefs files, or another file if provided

@param file a non-standard prefs file to load

@return [void]

    # File lib/jamf/configuration.rb
195 def reload(file = nil)
196   clear_all
197   if file
198     read file
199     return true
200   end
201   read_global
202   read_user
203   true
204 end
save(file) click to toggle source

Save the prefs into a file

@param file either :user, :global, or an arbitrary file to save.

@return [void]

    # File lib/jamf/configuration.rb
213 def save(file)
214   path = case file
215          when :global then GLOBAL_CONFS.first
216          when :user then USER_CONFS.first
217          else Pathname.new(file)
218          end
219 
220   raise Jamf::MissingDataError, "No HOME environment variable, can't write to user conf file." if path.nil?
221 
222   # file already exists? read it in and update the values.
223   if path.readable?
224     data = path.read
225 
226     # go thru the known attributes/keys
227     CONF_KEYS.keys.sort.each do |k|
228       # if the key exists, update it.
229       if data =~ /^#{k}:/
230         data.sub!(/^#{k}:.*$/, "#{k}: #{send k}")
231 
232       # if not, add it to the end unless it's nil
233       else
234         data += "\n#{k}: #{send k}" unless send(k).nil?
235       end # if data =~ /^#{k}:/
236     end # each do |k|
237 
238   else # not readable, make a new file
239     data = ''
240     CONF_KEYS.keys.sort.each do |k|
241       data << "#{k}: #{send k}\n" unless send(k).nil?
242     end
243   end # if path readable
244 
245   # make sure we end with a newline, the save it.
246   data << "\n" unless data.end_with?("\n")
247   path.jss_save data
248 end

Private Instance Methods

read(file) click to toggle source

Read in any prefs file

@param file the file to read

@return [void]

    # File lib/jamf/configuration.rb
271 def read(file)
272   Pathname.new(file).read.each_line do |line|
273     # skip blank lines and those starting with #
274     next if line =~ /^\s*(#|$)/
275 
276     line.strip =~ /^(\w+?):\s*(\S.*)$/
277     next unless Regexp.last_match(1)
278 
279     attr = Regexp.last_match(1).to_sym
280     setter = "#{attr}=".to_sym
281     value = Regexp.last_match(2).strip
282 
283     next unless CONF_KEYS.keys.include? attr
284 
285     if value
286       # convert the value to the correct class
287       value = value.send(CONF_KEYS[attr])
288     end
289     send(setter, value)
290     # if
291   end # do line
292 end