Class: Jamf::Configuration

Inherits:
Object show all
Includes:
Singleton
Defined in:
lib/jamf/configuration.rb

Overview

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.

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:

  • api_server_name [String] the hostname of the JSS API server

  • api_server_port [Integer] the port number for the API connection

  • api_ssl_version [String] the SSL version (from the open_ssl module) to use for the connection.

  • api_verify_cert [Boolean] if SSL is used, should the SSL certificate be verified (usually false for a self-signed cert)

  • api_username [String] the JSS username for connecting to the API

  • api_timeout_open [Integer] the number of seconds for the open-connection timeout

  • api_timeout [Integer] the number of seconds for the response timeout

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.

Constant Summary collapse

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

[ "ruby-jss.conf", "jss_gem.conf"]
GLOBAL_CONFS =

The Pathname to the machine-wide preferences plist

CONF_FILES.map{|cf| Pathname.new "/etc/#{cf}"}
USER_CONFS =

The Pathname to the user-specific preferences plist

CONF_FILES.map{|cf| ENV["HOME"] ? Pathname.new("~/.#{cf}").expand_path : nil }.compact
CONF_KEYS =

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

{
  :api_server_name => :to_s,
  :api_server_port => :to_i,
  :api_ssl_version => :to_s,
  :api_verify_cert => :jss_to_bool,
  :api_username => :to_s,
  :api_timeout_open => :to_i,
  :api_timeout => :to_i,
  :db_server_name => :to_s,
  :db_server_port => :to_i,
  :db_server_socket => :to_s,
  :db_username => :to_s,
  :db_name => :to_s,
  :db_connect_timeout => :to_i,
  :db_read_timeout => :to_i,
  :db_write_timeout => :to_i
}

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Initialize!



142
143
144
145
146
147
 
# File 'lib/jamf/configuration.rb', line 142

def initialize

  read_global
  read_user

end

Instance Method Details

#clear_all ⇒ void

This method returns an undefined value.

Clear all values



158
159
160
 
# File 'lib/jamf/configuration.rb', line 158

def clear_all
  CONF_KEYS.keys.each {|k| self.send "#{k}=".to_sym, nil}
end

#print ⇒ void

This method returns an undefined value.

Print out the current settings to stdout



261
262
263
 
# File 'lib/jamf/configuration.rb', line 261

def print
  CONF_KEYS.keys.sort.each{|k| puts "#{k}: #{self.send k}"}
end

#read_global ⇒ void

This method returns an undefined value.

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



167
168
169
170
171
172
173
174
 
# File 'lib/jamf/configuration.rb', line 167

def read_global
  GLOBAL_CONFS.each { |gcf|
    if gcf.file? and gcf.readable?
      read gcf
      return
    end
  }
end

#read_user ⇒ void

This method returns an undefined value.

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



181
182
183
184
185
186
187
188
 
# File 'lib/jamf/configuration.rb', line 181

def read_user
  USER_CONFS.each { |ucf|
    if ucf.file? and ucf.readable?
      read ucf
      return
    end
  }
end

#reload(file = nil) ⇒ void

This method returns an undefined value.

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

Parameters:

  • file (String, Pathname) (defaults to: nil) —

    a non-standard prefs file to load



198
199
200
201
202
203
204
205
206
207
 
# File 'lib/jamf/configuration.rb', line 198

def reload(file = nil)
  clear_all
  if file
    read file
    return true
  end
  read_global
  read_user
  return true
end

#save(file) ⇒ void

This method returns an undefined value.

Save the prefs into a file

Parameters:

  • file (Symbol, String, Pathname) —

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

Raises:



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/jamf/configuration.rb', line 217

def save(file)
  path = case file
    when :global then GLOBAL_CONFS.first
    when :user then USER_CONFS.first
    else Pathname.new(file)
  end

  raise Jamf::MissingDataError, "No HOME environment variable, can't write to user conf file." if path.nil?

  # file already exists? read it in and update the values.
  if path.readable?
    data = path.read

    # go thru the known attributes/keys
    CONF_KEYS.keys.sort.each do |k|

      # if the key exists, update it.
      if data =~ /^#{k}:/
        data.sub!(/^#{k}:.*$/, "#{k}: #{self.send k}")

      # if not, add it to the end unless it's nil
      else
        data += "\n#{k}: #{self.send k}" unless self.send(k).nil?
      end # if data =~ /^#{k}:/
    end #each do |k|

  else # not readable, make a new file
    data = ""
    CONF_KEYS.keys.sort.each do |k|
      data << "#{k}: #{self.send k}\n" unless self.send(k).nil?
    end
  end # if path readable

  # make sure we end with a newline, the save it.
  data << "\n" unless data.end_with?("\n")
  path.jss_save data
end