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:
-
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}.
@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
Initialize!
# File lib/jamf/configuration.rb 142 def initialize 143 read_global 144 read_user 145 end
Public Instance Methods
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 out the current settings to stdout
@return [void]
# File lib/jamf/configuration.rb 255 def print 256 CONF_KEYS.keys.sort.each { |k| puts "#{k}: #{send k}" } 257 end
(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
(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
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 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 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