jss-api 0.5.8 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. data/CHANGES.md +55 -7
  2. data/README.md +2 -1
  3. data/bin/cgrouper +1 -1
  4. data/bin/subnet-update +1 -1
  5. data/lib/jss-api.rb +2 -363
  6. data/lib/jss-api/api_connection.rb +78 -15
  7. data/lib/jss-api/api_object.rb +1 -1
  8. data/lib/jss-api/api_object/advanced_search.rb +1 -1
  9. data/lib/jss-api/api_object/advanced_search/advanced_computer_search.rb +1 -1
  10. data/lib/jss-api/api_object/advanced_search/advanced_mobile_device_search.rb +1 -1
  11. data/lib/jss-api/api_object/advanced_search/advanced_user_search.rb +1 -1
  12. data/lib/jss-api/api_object/building.rb +1 -1
  13. data/lib/jss-api/api_object/category.rb +1 -1
  14. data/lib/jss-api/api_object/computer.rb +1 -1
  15. data/lib/jss-api/api_object/creatable.rb +1 -1
  16. data/lib/jss-api/api_object/criteriable.rb +1 -1
  17. data/lib/jss-api/api_object/criteriable/criteria.rb +1 -1
  18. data/lib/jss-api/api_object/criteriable/criterion.rb +1 -1
  19. data/lib/jss-api/api_object/department.rb +1 -1
  20. data/lib/jss-api/api_object/distribution_point.rb +92 -22
  21. data/lib/jss-api/api_object/extendable.rb +1 -1
  22. data/lib/jss-api/api_object/extension_attribute.rb +1 -1
  23. data/lib/jss-api/api_object/extension_attribute/computer_extension_attribute.rb +1 -1
  24. data/lib/jss-api/api_object/extension_attribute/mobile_device_extension_attribute.rb +1 -1
  25. data/lib/jss-api/api_object/extension_attribute/user_extension_attribute.rb +1 -1
  26. data/lib/jss-api/api_object/group.rb +1 -1
  27. data/lib/jss-api/api_object/group/computer_group.rb +1 -1
  28. data/lib/jss-api/api_object/group/mobile_device_group.rb +1 -1
  29. data/lib/jss-api/api_object/group/user_group.rb +1 -1
  30. data/lib/jss-api/api_object/ldap_server.rb +1 -1
  31. data/lib/jss-api/api_object/locatable.rb +1 -1
  32. data/lib/jss-api/api_object/matchable.rb +1 -1
  33. data/lib/jss-api/api_object/mobile_device.rb +1 -1
  34. data/lib/jss-api/api_object/netboot_server.rb +1 -1
  35. data/lib/jss-api/api_object/network_segment.rb +1 -1
  36. data/lib/jss-api/api_object/osx_configuration_profile.rb +1 -1
  37. data/lib/jss-api/api_object/package.rb +117 -64
  38. data/lib/jss-api/api_object/peripheral.rb +1 -1
  39. data/lib/jss-api/api_object/peripheral_type.rb +1 -1
  40. data/lib/jss-api/api_object/policy.rb +1 -1
  41. data/lib/jss-api/api_object/purchasable.rb +1 -1
  42. data/lib/jss-api/api_object/removable_macaddr.rb +1 -1
  43. data/lib/jss-api/api_object/scopable.rb +1 -1
  44. data/lib/jss-api/api_object/scopable/scope.rb +1 -1
  45. data/lib/jss-api/api_object/script.rb +1 -1
  46. data/lib/jss-api/api_object/self_servable.rb +1 -1
  47. data/lib/jss-api/api_object/site.rb +1 -1
  48. data/lib/jss-api/api_object/software_update_server.rb +1 -1
  49. data/lib/jss-api/api_object/updatable.rb +1 -1
  50. data/lib/jss-api/api_object/uploadable.rb +1 -1
  51. data/lib/jss-api/api_object/user.rb +1 -1
  52. data/lib/jss-api/client.rb +22 -21
  53. data/lib/jss-api/compatibility.rb +1 -1
  54. data/lib/jss-api/composer.rb +2 -2
  55. data/lib/jss-api/configuration.rb +1 -1
  56. data/lib/jss-api/db_connection.rb +63 -12
  57. data/lib/jss-api/exceptions.rb +1 -1
  58. data/lib/jss-api/ruby_extensions.rb +1 -1
  59. data/lib/jss-api/ruby_extensions/filetest.rb +1 -1
  60. data/lib/jss-api/ruby_extensions/hash.rb +1 -1
  61. data/lib/jss-api/ruby_extensions/ipaddr.rb +1 -1
  62. data/lib/jss-api/ruby_extensions/pathname.rb +1 -1
  63. data/lib/jss-api/ruby_extensions/string.rb +17 -1
  64. data/lib/jss-api/ruby_extensions/time.rb +1 -1
  65. data/lib/jss-api/server.rb +1 -1
  66. data/lib/jss-api/utility.rb +416 -0
  67. data/lib/jss-api/version.rb +8 -8
  68. metadata +3 -2
@@ -0,0 +1,416 @@
1
+ ### Copyright 2016 Pixar
2
+ ###
3
+ ### Licensed under the Apache License, Version 2.0 (the "Apache License")
4
+ ### with the following modification; you may not use this file except in
5
+ ### compliance with the Apache License and the following modification to it:
6
+ ### Section 6. Trademarks. is deleted and replaced with:
7
+ ###
8
+ ### 6. Trademarks. This License does not grant permission to use the trade
9
+ ### names, trademarks, service marks, or product names of the Licensor
10
+ ### and its affiliates, except as required to comply with Section 4(c) of
11
+ ### the License and to reproduce the content of the NOTICE file.
12
+ ###
13
+ ### You may obtain a copy of the Apache License at
14
+ ###
15
+ ### http://www.apache.org/licenses/LICENSE-2.0
16
+ ###
17
+ ### Unless required by applicable law or agreed to in writing, software
18
+ ### distributed under the Apache License with the above modification is
19
+ ### distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20
+ ### KIND, either express or implied. See the Apache License for the specific
21
+ ### language governing permissions and limitations under the Apache License.
22
+ ###
23
+ ###
24
+
25
+ ###
26
+ module JSS
27
+
28
+ ### A collection of useful utility methods. Mostly for
29
+ ### converting values between formats, parsing data, and
30
+ ### user interaction.
31
+
32
+ ### Converts an OS Version into an Array of higher OS versions.
33
+ ###
34
+ ### It's unlikely that this library will still be in use as-is by the release of OS X 10.19.15.
35
+ ### Hopefully well before then JAMF will implement a "minimum OS" in the JSS itself.
36
+ ###
37
+ ### @param min_os [String] the mimimum OS version to expand, e.g. ">=10.6.7" or "10.6.7"
38
+ ###
39
+ ### @return [Array] Nearly all potential OS versions from the minimum to 10.19.x.
40
+ ###
41
+ ### @example
42
+ ### JSS.expand_min_os ">=10.6.7" # => returns this array
43
+ ### # ["10.6.7",
44
+ ### # "10.6.8",
45
+ ### # "10.6.9",
46
+ ### # "10.6.10",
47
+ ### # "10.6.11",
48
+ ### # "10.6.12",
49
+ ### # "10.6.13",
50
+ ### # "10.6.14",
51
+ ### # "10.6.15",
52
+ ### # "10.7.x",
53
+ ### # "10.8.x",
54
+ ### # "10.9.x",
55
+ ### # "10.10.x",
56
+ ### # "10.11.x",
57
+ ### # "10.12.x",
58
+ ### # "10.13.x",
59
+ ### # "10.14.x",
60
+ ### # "10.15.x",
61
+ ### # "10.16.x",
62
+ ### # "10.17.x",
63
+ ### # "10.18.x",
64
+ ### # "10.19.x"]
65
+ ###
66
+ ###
67
+ def self.expand_min_os (min_os)
68
+
69
+ min_os.delete! ">="
70
+
71
+ ### split the version into major, minor and maintenance release numbers
72
+ (maj,min,maint) = min_os.split(".")
73
+ maint = "x" if maint.nil? or maint == "0"
74
+
75
+ ### if the maint release number is an "x" just start the list of OK OS's with it
76
+ if maint == "x"
77
+ ok_oses = [maj + "." + min.to_s + ".x"]
78
+
79
+ ### otherwise, start with it and explicitly add all maint releases up to 15
80
+ ### (and hope apple doesn't do more than 15 maint releases for an OS)
81
+ else
82
+ ok_oses = []
83
+ (maint.to_i..15).each do |m|
84
+ ok_oses << maj + "." + min +"." + m.to_s
85
+ end # each m
86
+ end
87
+
88
+ ### now account for all OS X versions starting with 10.
89
+ ### up to at least 10.19.x
90
+ ((min.to_i + 1)..19).each do |v|
91
+ ok_oses << maj + "." + v.to_s + ".x"
92
+ end # each v
93
+ return ok_oses
94
+ end
95
+
96
+ ### Given a list of data as a comma-separated string, or an Array of strings,
97
+ ### return a Hash with both versions.
98
+ ###
99
+ ### Some parts of the JSS require lists as comma-separated strings, while
100
+ ### often those data are easier work with as arrays. This method is a handy way
101
+ ### to get either form when given either form.
102
+ ###
103
+ ### @param somedata [String, Array] the data to parse, of either class,
104
+ ###
105
+ ### @return [Hash{:stringform => String, :arrayform => Array}] the data as both comma-separated String and Array
106
+ ###
107
+ ### @example
108
+ ### JSS.to_s_and_a "foo, bar, baz" # Hash => {:stringform => "foo, bar, baz", :arrayform => ["foo", "bar", "baz"]}
109
+ ###
110
+ ### JSS.to_s_and_a ["foo", "bar", "baz"] # Hash => {:stringform => "foo, bar, baz", :arrayform => ["foo", "bar", "baz"]}
111
+ ###
112
+ def self.to_s_and_a (somedata)
113
+ case somedata
114
+ when nil
115
+ valstr = ""
116
+ valarr = []
117
+ when String
118
+ valstr = somedata
119
+ valarr = somedata.split(/,\s*/)
120
+ when Array
121
+ valstr = somedata.join ", "
122
+ valarr = somedata
123
+ else
124
+ raise JSS::InvalidDataError, "Input must be a comma-separated String or an Array of Strings"
125
+ end # case
126
+ return {:stringform => valstr, :arrayform => valarr}
127
+ end # to_s_and_a
128
+
129
+ ### Parse a plist into a Ruby data structure.
130
+ ### This enhances Plist::parse_xml taking file paths, as well as XML Strings
131
+ ### and reading the files regardless of binary/XML format.
132
+ ###
133
+ ### @param plist[Pathname, String] the plist XML, or the path to a plist file
134
+ ###
135
+ ### @return [Object] the parsed plist as a ruby hash,array, etc.
136
+ ###
137
+ def self.parse_plist (plist)
138
+
139
+ # did we get a string of xml, or a string pathname?
140
+ case plist
141
+ when String
142
+ if plist.include? "</plist>"
143
+ return Plist.parse_xml plist
144
+ else
145
+ plist = Pathname.new plist
146
+ end
147
+ when Pathname
148
+ true
149
+ else
150
+ raise ArgumentError, "Argument must be a path (as a Pathname or String) or a String of XML"
151
+ end # case plist
152
+
153
+ # if we're here, its a Pathname
154
+ raise JSS::MissingDataError, "No such file: #{plist}" unless plist.file?
155
+
156
+ return Plist.parse_xml `/usr/libexec/PlistBuddy -x -c print #{Shellwords.escape(plist.to_s)}`
157
+
158
+ end # parse_plist
159
+
160
+
161
+ ### Converts anything that responds to #to_s to a Time, or nil
162
+ ###
163
+ ### Return nil if the item is nil, 0 or an empty String.
164
+ ###
165
+ ### Otherwise the item converted to a string, and parsed with DateTime.parse.
166
+ ### It is then examined to see if it has a UTC offset. If not, the local offset
167
+ ### is applied, then the DateTime is converted to a Time.
168
+ ###
169
+ ### @param a_datetime [#to_s] The thing to convert to a time.
170
+ ###
171
+ ### @return [Time, nil] nil is returned if a_datetime is nil, 0 or an empty String.
172
+ ###
173
+ def self.parse_time(a_datetime)
174
+ return nil if NIL_DATES.include? a_datetime
175
+
176
+ the_dt = DateTime.parse(a_datetime.to_s)
177
+
178
+ ### The microseconds in DateTimes are stored as a fraction of a day.
179
+ ### Convert them to an integer of microseconds
180
+ usec = (the_dt.sec_fraction * 60 * 60 * 24 * (10**6)).to_i
181
+
182
+ ### if the UTC offset of the datetime is zero, make a new one with the correct local offset
183
+ ### (which might also be zero if we happen to be in GMT)
184
+ if the_dt.offset == 0
185
+ the_dt = DateTime.new(the_dt.year, the_dt.month, the_dt.day, the_dt.hour, the_dt.min, the_dt.sec, JSS::TIME_ZONE_OFFSET)
186
+ end
187
+ # now convert it to a Time and return it
188
+ Time.at the_dt.strftime('%s').to_i, usec
189
+
190
+ end #parse_time
191
+
192
+ ### Deprecated - to be eventually removed in favor of
193
+ ### the more-appropriately named JSS::parse_time
194
+ ###
195
+ ### @see JSS::parse_time
196
+ ###
197
+ def self.parse_datetime(a_datetime) ; self.parse_time(a_datetime) ; end
198
+
199
+ ### Converts JSS epoch (unix epoch + milliseconds) to a Ruby Time object
200
+ ###
201
+ ### @param epoch[String, Integer, nil]
202
+ ###
203
+ ### @return [Time, nil] nil is returned if epoch is nil, 0 or an empty String.
204
+ ###
205
+ def self.epoch_to_time(epoch)
206
+ return nil if NIL_DATES.include? epoch
207
+ Time.at(epoch.to_i / 1000.0)
208
+ end #parse_date
209
+
210
+ ### Given a string of xml element text, escape any characters that would make XML unhappy.
211
+ ### * & => &amp;
212
+ ### * " => &quot;
213
+ ### * < => &lt;
214
+ ### * > => &gt;
215
+ ### * ' => &apos;
216
+ ###
217
+ ### @param string [String] the string to make xml-compliant.
218
+ ###
219
+ ### @return [String] the xml-compliant string
220
+ ###
221
+ def self.escape_xml(string)
222
+ string.gsub(/&/, '&amp;').gsub(/\"/, '&quot;').gsub(/>/, '&gt;').gsub(/</, '&lt;').gsub(/'/, '&apos;')
223
+ end
224
+
225
+ ### Given an element name and an array of content, generate an Array of
226
+ ### REXML::Element objects with that name, and matching content.
227
+ ### The array of REXML elements would render thus:
228
+ ### <foo>bar</foo>
229
+ ### <foo>morefoo</foo>
230
+ ###
231
+ ### @param element [#to_s] an element_name like :foo
232
+ ###
233
+ ### @param list [Array<#to_s>] an Array of element content such as ["bar", :morefoo]
234
+ ###
235
+ ### @return [Array<REXML::Element>]
236
+ ###
237
+ def self.array_to_rexml_array(element,list)
238
+ raise JSS::InvalidDataError, "Arg. must be an Array." unless list.kind_of? Array
239
+ element = element.to_s
240
+ list.map do |v|
241
+ e = REXML::Element.new(element)
242
+ e.text = v
243
+ e
244
+ end
245
+ end
246
+
247
+ ### Given a simple Hash, convert it to an array of REXML Elements such that each
248
+ ### key becomes an element, and its value becomes the text content of
249
+ ### that element
250
+ ###
251
+ ### @example
252
+ ### my_hash = {:foo => "bar", :baz => :morefoo}
253
+ ### xml = JSS.hash_to_rexml_array(my_hash)
254
+ ### xml.each{|x| puts x }
255
+ ###
256
+ ### <foo>bar</foo>
257
+ ### <baz>morefoo</baz>
258
+ ###
259
+ ### @param hash [Hash{#to_s => #to_s}] the Hash to convert
260
+ ###
261
+ ### @return [Array<REXML::Element>] the Array of REXML elements.
262
+ ###
263
+ def self.hash_to_rexml_array(hash)
264
+ raise InvalidDataError, "Arg. must be a Hash." unless hash.kind_of? Hash
265
+ ary = []
266
+ hash.each_pair do |k,v|
267
+ el = REXML::Element.new k.to_s
268
+ el.text = v
269
+ ary << el
270
+ end
271
+ ary
272
+ end
273
+
274
+ ### Given an Array of Hashes with :id and/or :name keys, return
275
+ ### a single REXML element with a sub-element for each item,
276
+ ### each of which contains a :name or :id element.
277
+ ###
278
+ ### @param list_element [#to_s] the name of the XML element that contains the list.
279
+ ### e.g. :computers
280
+ ###
281
+ ### @param item_element [#to_s] the name of each XML element in the list,
282
+ ### e.g. :computer
283
+ ###
284
+ ### @param item_list [Array<Hash>] an Array of Hashes each with a :name or :id key.
285
+ ###
286
+ ### @param content [Symbol] which hash key should be used as the content of if list item? Defaults to :name
287
+ ###
288
+ ### @return [REXML::Element] the item list as REXML
289
+ ###
290
+ ### @example
291
+ ### comps = [{:id=>2,:name=>'kimchi'},{:id=>5,:name=>'mantis'}]
292
+ ### xml = JSS.item_list_to_rexml_list(:computers, :computer , comps, :name)
293
+ ### puts xml
294
+ ### # output manually formatted for clarity. No newlines in the real xml string
295
+ ### <computers>
296
+ ### <computer>
297
+ ### <name>kimchi</name>
298
+ ### </computer>
299
+ ### <computer>
300
+ ### <name>mantis</name>
301
+ ### </computer>
302
+ ### </computers>
303
+ ###
304
+ ### # if content is :id, then, eg. <name>kimchi</name> would be <id>2</id>
305
+ ###
306
+ def self.item_list_to_rexml_list(list_element, item_element , item_list, content = :name)
307
+ xml_list = REXML::Element.new list_element.to_s
308
+ item_list.each do |i|
309
+ xml_list.add_element(item_element.to_s).add_element(content.to_s).text = i[content]
310
+ end
311
+ xml_list
312
+ end
313
+
314
+ ### Parse a JSS Version number into something comparable
315
+ ###
316
+ ### Unfortunately, the JSS version numbering is inconsistant and improper at the moment.
317
+ ### Version 9.32 should be version 9.3.2, so that it
318
+ ### will be recognizable as being less than 9.4
319
+ ###
320
+ ### To work around this until JAMF standardizes version numbering,
321
+ ### we will assume any digits before the first dot is the major version
322
+ ### and the first digit after the first dot is the minor version
323
+ ### and anything else, including other dots, is the revision
324
+ ###
325
+ ### If that revision starts with a dot, it is removed.
326
+ ### so 9.32 becomes major-9, minor-3, rev-2
327
+ ### and 9.32.3764 becomes major-9, minor-3, rev-2.3764
328
+ ### and 9.3.2.3764 becomes major-9, minor-3, rev-2.3764
329
+ ###
330
+ ### This method of parsing will break if the minor revision
331
+ ### ever gets above 9.
332
+ ###
333
+ ### Returns a hash with these keys:
334
+ ### * :major => the major version, Integer
335
+ ### * :minor => the minor version, Integor
336
+ ### * :revision => the revision, String
337
+ ### * :version => a Gem::Version object built from the above keys, which is easily compared to others.
338
+ ###
339
+ ### @param version[String] a JSS version number from the API
340
+ ###
341
+ ### @return [Hash{Symbol => String, Gem::Version}] the parsed version data.
342
+ ###
343
+ def self.parse_jss_version(version)
344
+ spl = version.split('.')
345
+
346
+ case spl.count
347
+ when 1
348
+ major = spl[0].to_i
349
+ minor = 0
350
+ revision = '0'
351
+ when 2
352
+ major = spl[0].to_i
353
+ minor = spl[1][0,1].to_i
354
+ revision = spl[1][1..-1]
355
+ revision = '0' if revision.empty?
356
+ else
357
+ major = spl[0].to_i
358
+ minor = spl[1][0,1].to_i
359
+ revision = spl[1..-1].join('.')[1..-1]
360
+ revision = revision[1..-1] if revision.start_with? '.'
361
+ end
362
+
363
+ ###revision = revision[1..-1] if revision.start_with? '.'
364
+ { :major => major,
365
+ :minor => minor,
366
+ :revision => revision,
367
+ :version => Gem::Version.new("#{major}.#{minor}.#{revision}")
368
+ }
369
+ end
370
+
371
+ ### @return [Boolean] is this code running as root?
372
+ ###
373
+ def self.superuser?
374
+ Process.euid == 0
375
+ end
376
+
377
+ ### Retrive one or all lines from whatever was piped to standard input.
378
+ ###
379
+ ### Standard input is read completely when the module loads
380
+ ### and the lines are stored as an Array in the constant {STDIN_LINES}
381
+ ###
382
+ ### @param line[Integer] which line of stdin is being retrieved.
383
+ ### The default is zero (0) which returns all of stdin as a single string.
384
+ ###
385
+ ### @return [String, nil] the requested ling of stdin, or nil if it doesn't exist.
386
+ ###
387
+ def self.stdin(line = 0)
388
+
389
+ return STDIN_LINES.join("\n") if line <= 0
390
+
391
+ idx = line - 1
392
+ return STDIN_LINES[idx]
393
+ end
394
+
395
+ ### Prompt for a password in a terminal.
396
+ ###
397
+ ### @param message [String] the prompt message to display
398
+ ###
399
+ ### @return [String] the text typed by the user
400
+ ###
401
+ def self.prompt_for_password(message)
402
+
403
+ begin
404
+ $stdin.reopen '/dev/tty' unless $stdin.tty?
405
+ $stderr.print "#{message} "
406
+ system "/bin/stty -echo"
407
+ pw = $stdin.gets.chomp("\n")
408
+ puts
409
+ ensure
410
+ system "/bin/stty echo"
411
+ end # begin
412
+ return pw
413
+ end
414
+
415
+
416
+ end # module
@@ -1,31 +1,31 @@
1
- ### Copyright 2014 Pixar
2
- ###
1
+ ### Copyright 2016 Pixar
2
+ ###
3
3
  ### Licensed under the Apache License, Version 2.0 (the "Apache License")
4
4
  ### with the following modification; you may not use this file except in
5
5
  ### compliance with the Apache License and the following modification to it:
6
6
  ### Section 6. Trademarks. is deleted and replaced with:
7
- ###
7
+ ###
8
8
  ### 6. Trademarks. This License does not grant permission to use the trade
9
9
  ### names, trademarks, service marks, or product names of the Licensor
10
10
  ### and its affiliates, except as required to comply with Section 4(c) of
11
11
  ### the License and to reproduce the content of the NOTICE file.
12
- ###
12
+ ###
13
13
  ### You may obtain a copy of the Apache License at
14
- ###
14
+ ###
15
15
  ### http://www.apache.org/licenses/LICENSE-2.0
16
- ###
16
+ ###
17
17
  ### Unless required by applicable law or agreed to in writing, software
18
18
  ### distributed under the Apache License with the above modification is
19
19
  ### distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20
20
  ### KIND, either express or implied. See the Apache License for the specific
21
21
  ### language governing permissions and limitations under the Apache License.
22
- ###
22
+ ###
23
23
  ###
24
24
 
25
25
  ###
26
26
  module JSS
27
27
 
28
28
  ### The version of the JSS ruby gem
29
- VERSION = "0.5.8"
29
+ VERSION = "0.6.1"
30
30
 
31
31
  end # module