ruby-jss 2.1.1 → 3.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGES.md +16 -0
- data/README.md +14 -23
- data/lib/jamf/api/classic/api_objects/computer.rb +20 -6
- data/lib/jamf/api/classic/api_objects/mdm.rb +9 -9
- data/lib/jamf/api/classic/api_objects/mobile_device_application.rb +1 -0
- data/lib/jamf/api/classic/api_objects/policy.rb +96 -37
- data/lib/jamf/api/classic/api_objects/scopable/scope.rb +5 -2
- data/lib/jamf/api/jamf_pro/mixins/macos_managed_updates.rb +46 -37
- data/lib/jamf/validate.rb +3 -1
- data/lib/jamf/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: ed31b6de65dd9f753522997db8bee3030036d7b7f3064c9a1586ecda06c2e593
|
4
|
+
data.tar.gz: 7c6e77eb322d52934729b7f5a26283a46921f0b52c8f6046d8bee57f0dd8cc5b
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 82fbcfb1a88e333ed07d04e37878ec3f9c4fa9c5aa6705a5860285222e52d9b9adeb5ad329520868ce223e68338eac576888eb387774abe4b066804ee9c5b921
|
7
|
+
data.tar.gz: 65095fd093104fd752a9c4294ff1cd0e41e570f9b928a1c8497cada0c56b2990a87f432f84f6a4332d400e3ac90cbd4852776d0ba9e9a85198580816e5dac731
|
data/CHANGES.md
CHANGED
@@ -16,6 +16,22 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
|
|
16
16
|
|
17
17
|
--------
|
18
18
|
|
19
|
+
## \[3.0.0] - 2023-05-22
|
20
|
+
Major version bump because changes to policy log flushing are not backward compatible.
|
21
|
+
|
22
|
+
### Added
|
23
|
+
- Jamf::Policy.flush_logs_for_computers: formerly private class method, now public and used for flushing policy logs for specific computers.
|
24
|
+
|
25
|
+
### Fixed
|
26
|
+
- Fix bug in MDM enable_lost_mode instance method, and make the default behavior match the API
|
27
|
+
- Specify the connection instance when validating ids in MacOSManagedUpdates
|
28
|
+
- Send mandatory field 'name' with a MobileDeviceApplication request (Thanks @yanniks!)
|
29
|
+
- Policy Log Flushing now reflects API limitation: You can flush logs for a policy for all computers, or for a computer for all policies, but not specific policies for specific computers. See Jamf::Policy.flush_logs and Jamf::Policy.flush_logs_for_computers
|
30
|
+
- A validation method wasn't passing cnx param correctly.
|
31
|
+
|
32
|
+
### Changed
|
33
|
+
- MacOSManagedUpdates.send_managed_os_update takes symbols or strings as the updateAction, a key or a value from the UPDATE_ACTIONS constant
|
34
|
+
|
19
35
|
## \[2.1.1] - 2022-11-07
|
20
36
|
|
21
37
|
### Fixed & Deprecated
|
data/README.md
CHANGED
@@ -6,7 +6,7 @@
|
|
6
6
|
Version 2.0.0 has major changes! While we've strived for _mostly_ being backward compatible, and have done lots of testing, YMMV. Please report any issues.
|
7
7
|
|
8
8
|
_NOTE_: ruby-jss 2.0 is not completely backward compatible, please see [README-2.0.0.md](README-2.0.0.md) for more info
|
9
|
-
|
9
|
+
|
10
10
|
### Highlights
|
11
11
|
|
12
12
|
- Support for Ruby 3.x
|
@@ -57,7 +57,6 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
|
|
57
57
|
- [BEYOND THE API](#beyond-the-api)
|
58
58
|
- [INSTALL](#install)
|
59
59
|
- [REQUIREMENTS](#requirements)
|
60
|
-
- [Contact](#contact)
|
61
60
|
- [HELP & CONTACT INFO](#help--contact-info)
|
62
61
|
- [LICENSE](#license)
|
63
62
|
|
@@ -65,13 +64,13 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
|
|
65
64
|
|
66
65
|
## DESCRIPTION
|
67
66
|
|
68
|
-
ruby-jss defines a Ruby module called `Jamf`, which is used for accessing the 'Classic' and
|
67
|
+
ruby-jss defines a Ruby module called `Jamf`, which is used for accessing the 'Classic' and
|
69
68
|
'Jamf Pro' APIs of a Jamf Pro server. Jamf Pro is an enterprise-level management tool for Apple
|
70
69
|
devices from [Jamf.com](http://www.jamf.com/). It is available as a[ruby gem](https://rubygems.org/gems/ruby-jss), and the
|
71
70
|
[source is on github](https://github.com/PixarAnimationStudios/ruby-jss).
|
72
71
|
|
73
72
|
The Jamf module maintains connections to both APIs simultaneously, and uses which ever is appropriate as needed.
|
74
|
-
Details like authentication tokens, token refreshing, JSON and XML parsing, and even knowing which resources use
|
73
|
+
Details like authentication tokens, token refreshing, JSON and XML parsing, and even knowing which resources use
|
75
74
|
which API are all handled under-the-hood.
|
76
75
|
|
77
76
|
The Jamf module abstracts many API resources as Ruby objects, and provides methods for interacting with those
|
@@ -79,8 +78,8 @@ resources. It also provides some features that aren't a part of the API itself,
|
|
79
78
|
Jamf-related tools, such as uploading {Jamf::Package} files to the master distribution
|
80
79
|
point, and the installation of those objects on client machines. (See [BEYOND THE API](#beyond-the-api))
|
81
80
|
|
82
|
-
The Jamf module is not a complete implementation of the Jamf Pro APIs. Only some objects are modeled,
|
83
|
-
some only minimally. Of those, some are read-only, some partially writable, some fully read-write.
|
81
|
+
The Jamf module is not a complete implementation of the Jamf Pro APIs. Only some objects are modeled,
|
82
|
+
some only minimally. Of those, some are read-only, some partially writable, some fully read-write.
|
84
83
|
We've implemented the things we need in our environment, and as our needs grow, we'll add more.
|
85
84
|
Hopefully others will find it useful, and add more to it as well.
|
86
85
|
|
@@ -138,14 +137,14 @@ ns.save
|
|
138
137
|
|
139
138
|
Before you can work with Jamf Pros Objects via the APIs, you have to connect to the server.
|
140
139
|
|
141
|
-
The method `Jamf.cnx` returns the 'default' connection object (an instance of a {Jamf::APIConnection}, q.v.).
|
140
|
+
The method `Jamf.cnx` returns the 'default' connection object (an instance of a {Jamf::APIConnection}, q.v.).
|
142
141
|
A connection object holds all the data needed to communicate with the server to which it's connected, as well as
|
143
|
-
any data cached from that server.
|
142
|
+
any data cached from that server.
|
144
143
|
The default connection object is used for all communication unless a different one is explicitly passed to methods
|
145
144
|
that can accept one. See 'Using multiple connections' below.
|
146
145
|
|
147
146
|
When the Jamf Module is first loaded, the default connection isn't connected a server. To remedy that, use `Jamf.cnx.connect`,
|
148
|
-
passing it parameters for the connection. In this example, those parameters are stored in the local variables jss_user,
|
147
|
+
passing it parameters for the connection. In this example, those parameters are stored in the local variables jss_user,
|
149
148
|
jss_user_pw, and jss_server_hostname, and others are left as default.
|
150
149
|
|
151
150
|
```ruby
|
@@ -170,8 +169,8 @@ server connection parameters in a simple config file.
|
|
170
169
|
|
171
170
|
#### Using multiple connections
|
172
171
|
|
173
|
-
Most of the time, you'll only need a single connection to a single server, and the default connection will be sufficient. However
|
174
|
-
you can also create multiple Connection objects, to different servers, or perhaps the same server with different credentials and
|
172
|
+
Most of the time, you'll only need a single connection to a single server, and the default connection will be sufficient. However
|
173
|
+
you can also create multiple Connection objects, to different servers, or perhaps the same server with different credentials and
|
175
174
|
access, and pass those connection objects into methods using the `cnx:` parameter as appropriate.
|
176
175
|
|
177
176
|
```ruby
|
@@ -194,13 +193,13 @@ common_ipr_sns = ipr_sns_1 & ipr_sns_2
|
|
194
193
|
|
195
194
|
### Working with Jamf Objects
|
196
195
|
|
197
|
-
All of the ruby classes representing objects in Jamf Pro have common methods for creating, listing, retrieving, updating, and deleting via the API.
|
196
|
+
All of the ruby classes representing objects in Jamf Pro have common methods for creating, listing, retrieving, updating, and deleting via the API.
|
198
197
|
All supported objects can be listed, retrieved and deleted, but only some can be updated or created, mostly becase we haven't needed to do that ourselves
|
199
198
|
yet and haven't implemented that functionality. If you need additional features implemented, please get in touch (see 'Contact' above) or feel free to
|
200
199
|
try implementing it yourself and send us a merge request.
|
201
200
|
|
202
|
-
Some of the implemented objects also provide access to more 'functional' API resources. For example, the API resources for
|
203
|
-
sending MDM commands to computers and mobile devices are available as class and instance methods of Jamf::Computer and Jamf::MobileDevice,
|
201
|
+
Some of the implemented objects also provide access to more 'functional' API resources. For example, the API resources for
|
202
|
+
sending MDM commands to computers and mobile devices are available as class and instance methods of Jamf::Computer and Jamf::MobileDevice,
|
204
203
|
as are the API resources for accessing management history.
|
205
204
|
|
206
205
|
--------
|
@@ -474,21 +473,13 @@ It also requires other ruby gems, which will be installed automatically if you i
|
|
474
473
|
See the .gemspec file for details
|
475
474
|
|
476
475
|
|
477
|
-
### Contact
|
478
|
-
|
479
|
-
If you have questions or feedback about ruby-jss, please reach out to us via:
|
480
|
-
- The [#ruby-jss channel of Macadmins Slack](https://macadmins.slack.com/archives/C03C7F563MK)
|
481
|
-
- Open an issue on GitHub
|
482
|
-
- Email ruby-jss@pixar.com
|
483
|
-
|
484
|
-
|
485
476
|
## HELP & CONTACT INFO
|
486
477
|
|
487
478
|
Full documentation is available at [rubydoc.info](http://www.rubydoc.info/gems/ruby-jss/).
|
488
479
|
|
489
480
|
There's a [wiki on the github page](https://github.com/PixarAnimationStudios/ruby-jss/wiki), feel free to contribute examples and tidbits.
|
490
481
|
|
491
|
-
|
482
|
+
If you have questions or feedback about ruby-jss, please reach out to us via:
|
492
483
|
- [Open an issue on github](https://github.com/PixarAnimationStudios/ruby-jss/issues)
|
493
484
|
- [Email the developers at ruby-jss@pixar.com](mailto:ruby-jss@pixar.com)
|
494
485
|
- Join the conversation in the [#ruby-jss Macadmins Slack Channel](https://macadmins.slack.com/archives/C03C7F563MK)
|
@@ -1158,15 +1158,29 @@ module Jamf
|
|
1158
1158
|
@need_to_update = true
|
1159
1159
|
end
|
1160
1160
|
|
1161
|
-
#
|
1162
|
-
# @see Jamf::Policy.flush_logs
|
1161
|
+
# Flush all policy logs for this computer older than a given time period.
|
1163
1162
|
#
|
1164
|
-
|
1165
|
-
|
1166
|
-
|
1163
|
+
# IMPORTANT: from the Jamf Developer Site:
|
1164
|
+
# The ability to flush logs is currently only supported for flushing all logs
|
1165
|
+
# for a given policy or all logs for a given computer. There is no support for
|
1166
|
+
# flushing logs for a given policy and computer combination.
|
1167
|
+
#
|
1168
|
+
# With no parameters, will flush all logs for the computer
|
1169
|
+
#
|
1170
|
+
# NOTE: Currently the API doesn't have a way to flush only failed policies.
|
1171
|
+
#
|
1172
|
+
# @param older_than[Integer] 0, 1, 2, 3, or 6
|
1173
|
+
#
|
1174
|
+
# @param period[Symbol] :days, :weeks, :months, or :years
|
1175
|
+
#
|
1176
|
+
# @see Jamf::Policy.flush_logs_for_computers
|
1177
|
+
#
|
1178
|
+
def flush_policy_logs(older_than: 0, period: :days)
|
1179
|
+
Jamf::Policy.flush_logs_for_computers(
|
1180
|
+
[@id],
|
1167
1181
|
older_than: older_than,
|
1168
1182
|
period: period,
|
1169
|
-
|
1183
|
+
cnx: @cnx
|
1170
1184
|
)
|
1171
1185
|
end
|
1172
1186
|
|
@@ -476,7 +476,7 @@ module Jamf
|
|
476
476
|
raise Jamf::UnmanagedError, "#{self} with id #{target_id} is not managed. Cannot send command." unless all_mgd.include? target_id
|
477
477
|
end
|
478
478
|
end # unles
|
479
|
-
|
479
|
+
|
480
480
|
targets
|
481
481
|
end
|
482
482
|
|
@@ -860,7 +860,7 @@ module Jamf
|
|
860
860
|
cnx = api if api
|
861
861
|
|
862
862
|
unless WALLPAPER_LOCATIONS.keys.include? wallpaper_setting
|
863
|
-
raise ArgumentError,
|
863
|
+
raise ArgumentError,
|
864
864
|
"wallpaper_setting must be one of: :#{WALLPAPER_LOCATIONS.keys.join ', :'}"
|
865
865
|
end
|
866
866
|
|
@@ -999,7 +999,7 @@ module Jamf
|
|
999
999
|
#
|
1000
1000
|
# @param play_sound[Boolean] Play a sound when entering lost mode
|
1001
1001
|
#
|
1002
|
-
# @param enforce_lost_mode[Boolean] Re-
|
1002
|
+
# @param enforce_lost_mode[Boolean] Re-enable lost mode when re-enrolled after wipe. Default is false
|
1003
1003
|
#
|
1004
1004
|
# @param cnx [Jamf::Connection] the API thru which to send the command
|
1005
1005
|
#
|
@@ -1011,7 +1011,7 @@ module Jamf
|
|
1011
1011
|
phone: nil,
|
1012
1012
|
footnote: nil,
|
1013
1013
|
play_sound: false,
|
1014
|
-
enforce_lost_mode:
|
1014
|
+
enforce_lost_mode: false,
|
1015
1015
|
api: nil,
|
1016
1016
|
cnx: Jamf.cnx
|
1017
1017
|
)
|
@@ -1081,7 +1081,7 @@ module Jamf
|
|
1081
1081
|
|
1082
1082
|
status = FLUSHABLE_STATUSES[status]
|
1083
1083
|
|
1084
|
-
# TODO: add 'unmanaged_ok:' param to raw_targets_to_ids method, so that we can
|
1084
|
+
# TODO: add 'unmanaged_ok:' param to raw_targets_to_ids method, so that we can
|
1085
1085
|
# use this to flush commands for unmanaged machines.
|
1086
1086
|
target_ids = raw_targets_to_ids targets, cnx: cnx, expand_groups: false, unmanaged_ok: true
|
1087
1087
|
|
@@ -1378,21 +1378,21 @@ module Jamf
|
|
1378
1378
|
#
|
1379
1379
|
# @param play_sound[Boolean] Play a sound when entering lost mode
|
1380
1380
|
#
|
1381
|
-
# @param enforce_lost_mode[Boolean] Re-
|
1381
|
+
# @param enforce_lost_mode[Boolean] Re-enable lost mode when re-enrolled after wipe. Default is false
|
1382
1382
|
#
|
1383
1383
|
# @return (see .send_mdm_command)
|
1384
1384
|
#
|
1385
1385
|
def enable_lost_mode(
|
1386
1386
|
message: nil,
|
1387
|
-
|
1387
|
+
phone: nil,
|
1388
1388
|
footnote: nil,
|
1389
|
-
enforce_lost_mode:
|
1389
|
+
enforce_lost_mode: false,
|
1390
1390
|
play_sound: false
|
1391
1391
|
)
|
1392
1392
|
self.class.enable_lost_mode(
|
1393
1393
|
@id,
|
1394
1394
|
message: message,
|
1395
|
-
|
1395
|
+
phone: phone,
|
1396
1396
|
footnote: footnote,
|
1397
1397
|
play_sound: play_sound,
|
1398
1398
|
enforce_lost_mode: enforce_lost_mode, cnx: @cnx
|
@@ -544,6 +544,7 @@ module Jamf
|
|
544
544
|
doc = REXML::Document.new Jamf::Connection::XML_HEADER
|
545
545
|
obj = doc.add_element self.class::RSRC_OBJECT_KEY.to_s
|
546
546
|
gen = obj.add_element 'general'
|
547
|
+
gen.add_element('name').text = @display_name
|
547
548
|
gen.add_element('display_name').text = @display_name
|
548
549
|
gen.add_element('description').text = @description
|
549
550
|
gen.add_element('os_type').text = @os_type
|
@@ -293,10 +293,19 @@ module Jamf
|
|
293
293
|
# Class Methods
|
294
294
|
######################
|
295
295
|
|
296
|
-
# Flush logs for a given policy older than
|
297
|
-
#
|
296
|
+
# Flush logs for a given policy older than a given time period.
|
297
|
+
# This flushes the logs of the given policy for all computers.
|
298
298
|
#
|
299
|
-
#
|
299
|
+
# IMPORTANT: from the Jamf Developer Site:
|
300
|
+
# The ability to flush logs is currently only supported for flushing all logs
|
301
|
+
# for a given policy or all logs for a given computer. There is no support for
|
302
|
+
# flushing logs for a given policy and computer combination.
|
303
|
+
#
|
304
|
+
# (See .flush_logs_for_computers to to flush all logs for given computers)
|
305
|
+
#
|
306
|
+
# With no parameters, flushes all logs for the policy.
|
307
|
+
#
|
308
|
+
# Without older_than: and period:, will flush all logs for the policy
|
300
309
|
#
|
301
310
|
# NOTE: Currently the API doesn't have a way to flush only failed policies.
|
302
311
|
#
|
@@ -306,52 +315,74 @@ module Jamf
|
|
306
315
|
#
|
307
316
|
# @param policy[Integer,String] The id or name of the policy to flush
|
308
317
|
#
|
309
|
-
# @param older_than[Integer] 0, 1, 2, 3, or 6
|
310
|
-
#
|
311
|
-
# @param period[Symbol] :days, :weeks, :months, or :years
|
318
|
+
# @param older_than[Integer] 0, 1, 2, 3, or 6, defaults to 0
|
312
319
|
#
|
313
|
-
# @param
|
314
|
-
# either ids, names, SNs, macaddrs, or UDIDs. If omitted, flushes logs for
|
315
|
-
# all computers
|
320
|
+
# @param period[Symbol] :days, :weeks, :months, or :years, defaults to :days
|
316
321
|
#
|
317
322
|
# @param cnx [Jamf::Connection] the API connection to use.
|
318
323
|
#
|
319
324
|
# @return [void]
|
320
325
|
#
|
321
|
-
def self.flush_logs(policy, older_than: 0, period: :days,
|
326
|
+
def self.flush_logs(policy, older_than: 0, period: :days, api: nil, cnx: Jamf.cnx)
|
322
327
|
cnx = api if api
|
323
328
|
|
324
|
-
orig_timeout = cnx.timeout
|
325
329
|
pol_id = valid_id policy, cnx: cnx
|
326
330
|
raise Jamf::NoSuchItemError, "No Policy identified by '#{policy}'." unless pol_id
|
327
331
|
|
328
|
-
older_than =
|
329
|
-
raise Jamf::InvalidDataError, "older_than must be one of these integers: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}" unless older_than
|
330
|
-
|
331
|
-
period = LOG_FLUSH_INTERVAL_PERIODS[period]
|
332
|
-
raise Jamf::InvalidDataError, "period must be one of these symbols: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}" unless period
|
333
|
-
|
334
|
-
computers = [computers] unless computers.is_a? Array
|
332
|
+
older_than, period = validate_log_flush_params(older_than, period)
|
335
333
|
|
336
334
|
# log flushes can be really slow
|
335
|
+
orig_timeout = cnx.timeout
|
337
336
|
cnx.timeout = 1800 unless orig_timeout && orig_timeout > 1800
|
338
337
|
|
339
|
-
|
340
|
-
|
341
|
-
flush_logs_for_specific_computers pol_id, older_than, period, computers, cnx
|
338
|
+
cnx.c_delete "#{LOG_FLUSH_RSRC}/policy/id/#{pol_id}/interval/#{older_than}+#{period}"
|
342
339
|
ensure
|
343
340
|
cnx.timeout = orig_timeout
|
344
341
|
end
|
345
342
|
|
346
|
-
#
|
347
|
-
#
|
348
|
-
|
343
|
+
# Flush policy logs for specific computers older than a given time period.
|
344
|
+
# This flushes the logs for all policies for these computers.
|
345
|
+
#
|
346
|
+
# IMPORTANT: from the Jamf Developer Site:
|
347
|
+
# The ability to flush logs is currently only supported for flushing all logs
|
348
|
+
# for a given policy or all logs for a given computer. There is no support for
|
349
|
+
# flushing logs for a given policy and computer combination.
|
350
|
+
#
|
351
|
+
# (See .flush_logs to to flush all logs for a given policy)
|
352
|
+
#
|
353
|
+
# Without older_than: and period:, will flush all logs for the computers
|
354
|
+
#
|
355
|
+
# NOTE: Currently the API doesn't have a way to flush only failed policies.
|
356
|
+
#
|
357
|
+
# WARNING: Log flushing can take a long time, and the API call doesnt return
|
358
|
+
# until its finished. The connection timeout will be temporarily raised to
|
359
|
+
# 30 minutes, unless it's already higher.
|
360
|
+
#
|
361
|
+
# @param computers[Array<Integer,String>] Identifiers of the target computers
|
362
|
+
# either ids, names, SNs, macaddrs, or UDIDs.
|
363
|
+
#
|
364
|
+
# @param older_than[Integer] 0, 1, 2, 3, or 6, defaults to 0
|
365
|
+
#
|
366
|
+
# @param period[Symbol] :days, :weeks, :months, or :years, defaults to :days
|
367
|
+
#
|
368
|
+
# @param cnx [Jamf::Connection] the API connection to use.
|
369
|
+
#
|
370
|
+
# @return [void]
|
371
|
+
#
|
372
|
+
def self.flush_logs_for_computers(computers = [], older_than: 0, period: :days, api: nil, cnx: Jamf.cnx)
|
373
|
+
cnx = api if api
|
374
|
+
|
375
|
+
computers = [computers] unless computers.is_a? Array
|
376
|
+
raise JSS::InvalidDataError, 'One or more computers must be specified' if computers.empty?
|
377
|
+
|
378
|
+
older_than, period = validate_log_flush_params(older_than, period)
|
379
|
+
|
349
380
|
# build the xml body for a DELETE request
|
350
381
|
xml_doc = REXML::Document.new Jamf::Connection::XML_HEADER
|
351
382
|
lf = xml_doc.add_element 'logflush'
|
352
383
|
lf.add_element('log').text = 'policy'
|
353
|
-
lf.add_element('log_id').text = pol_id.to_s
|
354
384
|
lf.add_element('interval').text = "#{older_than} #{period}"
|
385
|
+
|
355
386
|
comps_elem = lf.add_element 'computers'
|
356
387
|
computers.each do |c|
|
357
388
|
id = Jamf::Computer.valid_id c, cnx: cnx
|
@@ -361,13 +392,41 @@ module Jamf
|
|
361
392
|
ce.add_element('id').text = id.to_s
|
362
393
|
end
|
363
394
|
|
395
|
+
# for debugging the xml...
|
396
|
+
#
|
397
|
+
# formatter = REXML::Formatters::Pretty.new(2)
|
398
|
+
# formatter.compact = true
|
399
|
+
# formatter.write(xml_doc, $stdout)
|
400
|
+
# puts
|
401
|
+
# return
|
402
|
+
|
403
|
+
# log flushes can be really slow
|
404
|
+
orig_timeout = cnx.timeout
|
405
|
+
cnx.timeout = 1800 unless orig_timeout && orig_timeout > 1800
|
406
|
+
|
364
407
|
# Do a DELETE request with a body.
|
365
|
-
cnx.delete(LOG_FLUSH_RSRC) do |req|
|
408
|
+
resp = cnx.c_cnx.delete(LOG_FLUSH_RSRC) do |req|
|
366
409
|
req.headers[Jamf::Connection::HTTP_CONTENT_TYPE_HEADER] = Jamf::Connection::MIME_XML
|
367
410
|
req.body = xml_doc.to_s
|
368
411
|
end
|
412
|
+
|
413
|
+
resp.body
|
414
|
+
ensure
|
415
|
+
cnx.timeout = orig_timeout
|
369
416
|
end
|
370
|
-
|
417
|
+
|
418
|
+
# validate the logflush params
|
419
|
+
# @return [Array<String>]
|
420
|
+
def self.validate_log_flush_params(older_than, period)
|
421
|
+
older_than = LOG_FLUSH_INTERVAL_INTEGERS[older_than]
|
422
|
+
raise Jamf::InvalidDataError, "older_than must be one of these integers: #{LOG_FLUSH_INTERVAL_INTEGERS.keys.join ', '}" unless older_than
|
423
|
+
|
424
|
+
period = LOG_FLUSH_INTERVAL_PERIODS[period]
|
425
|
+
raise Jamf::InvalidDataError, "period must be one of these symbols: :#{LOG_FLUSH_INTERVAL_PERIODS.keys.join ', :'}" unless period
|
426
|
+
|
427
|
+
[older_than, period]
|
428
|
+
end
|
429
|
+
private_class_method :validate_log_flush_params
|
371
430
|
|
372
431
|
# Attributes
|
373
432
|
######################
|
@@ -1852,11 +1911,14 @@ module Jamf
|
|
1852
1911
|
end
|
1853
1912
|
alias execute run
|
1854
1913
|
|
1855
|
-
# Flush logs for this policy older than
|
1856
|
-
# some number of days, weeks, months or years, possibly limited to
|
1857
|
-
# one or more computers
|
1914
|
+
# Flush logs for this policy older than a given time period.
|
1858
1915
|
#
|
1859
|
-
#
|
1916
|
+
# IMPORTANT: from the Jamf Developer Site:
|
1917
|
+
# The ability to flush logs is currently only supported for flushing all logs
|
1918
|
+
# for a given policy or all logs for a given computer. There is no support for
|
1919
|
+
# flushing logs for a given policy and computer combination.
|
1920
|
+
#
|
1921
|
+
# With no parameters, will flush all logs for the policy
|
1860
1922
|
#
|
1861
1923
|
# NOTE: Currently the API doesn't have a way to flush only failed policies.
|
1862
1924
|
#
|
@@ -1868,19 +1930,16 @@ module Jamf
|
|
1868
1930
|
#
|
1869
1931
|
# @param period[Symbol] :days, :weeks, :months, or :years
|
1870
1932
|
#
|
1871
|
-
# @param computers[Array<Integer,String>] Identifiers of the target computers
|
1872
|
-
# either ids, names, SNs, macaddrs, or UDIDs
|
1873
|
-
#
|
1874
1933
|
# @return [void]
|
1875
1934
|
#
|
1876
|
-
def flush_logs(older_than: 0, period: :days
|
1877
|
-
raise Jamf::NoSuchItemError, "Policy doesn't exist in the JSS. Use #
|
1935
|
+
def flush_logs(older_than: 0, period: :days)
|
1936
|
+
raise Jamf::NoSuchItemError, "Policy doesn't exist in the JSS. Use #save first." unless @in_jss
|
1878
1937
|
|
1879
1938
|
Jamf::Policy.flush_logs(
|
1880
1939
|
@id,
|
1881
1940
|
older_than: older_than,
|
1882
1941
|
period: period,
|
1883
|
-
|
1942
|
+
cnx: @cnx
|
1884
1943
|
)
|
1885
1944
|
end
|
1886
1945
|
|
@@ -476,7 +476,10 @@ module Jamf
|
|
476
476
|
item_id = validate_item(:target, key, item)
|
477
477
|
return if @targets[key]&.include?(item_id)
|
478
478
|
|
479
|
-
|
479
|
+
if @exclusions[key]&.include?(item_id)
|
480
|
+
raise Jamf::AlreadyExistsError,
|
481
|
+
"Can't set #{key} target to '#{item}' because it's already an explicit exclusion."
|
482
|
+
end
|
480
483
|
|
481
484
|
@targets[key] << item_id
|
482
485
|
@all_targets = false
|
@@ -775,7 +778,7 @@ module Jamf
|
|
775
778
|
################
|
776
779
|
def scoped_machines
|
777
780
|
scoped_machines = {}
|
778
|
-
@target_class.all_objects(cnx: container.cnx).each do |machine|
|
781
|
+
@target_class.all_objects(:refresh, cnx: container.cnx).each do |machine|
|
779
782
|
scoped_machines[machine.id] = machine.name if in_scope? machine
|
780
783
|
end
|
781
784
|
scoped_machines
|
@@ -19,14 +19,14 @@
|
|
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
|
-
|
23
|
-
#
|
22
|
+
|
23
|
+
# frozen_string_literal: true
|
24
24
|
|
25
25
|
module Jamf
|
26
26
|
|
27
27
|
# This module should be mixed in to Jamf::Computer and Jamf::ComputerGroup
|
28
28
|
#
|
29
|
-
# It provides access to the macos-managed-software-updates JPAPI resource for
|
29
|
+
# It provides access to the macos-managed-software-updates JPAPI resource for
|
30
30
|
# managed OS update commands to managed macs running Big Sur or higher.
|
31
31
|
#
|
32
32
|
module MacOSManagedUpdates
|
@@ -37,7 +37,7 @@ module Jamf
|
|
37
37
|
includer.extend(ClassMethods)
|
38
38
|
end
|
39
39
|
|
40
|
-
# These resources in the Jamf Pro API can be used to send Managed macOS
|
40
|
+
# These resources in the Jamf Pro API can be used to send Managed macOS
|
41
41
|
# updates to clients running Big Sur or higher
|
42
42
|
MANAGED_SW_UPDATES_RSRC = 'v1/macos-managed-software-updates'
|
43
43
|
|
@@ -45,7 +45,7 @@ module Jamf
|
|
45
45
|
MANAGED_SW_UPDATES_AVAILABLE_VERSIONS_RSRC = "#{MANAGED_SW_UPDATES_RSRC}/available-updates"
|
46
46
|
|
47
47
|
# POSTing JSON data to this resource will send the MDM commands to install os updates
|
48
|
-
# For details about the data to send, see
|
48
|
+
# For details about the data to send, see
|
49
49
|
# https://developer.jamf.com/jamf-pro/reference/post_v1-macos-managed-software-updates-send-updates
|
50
50
|
MANAGED_SW_UPDATES_SEND_UPDATES_RSRC = "#{MANAGED_SW_UPDATES_RSRC}/send-updates"
|
51
51
|
|
@@ -53,6 +53,12 @@ module Jamf
|
|
53
53
|
DOWNLOAD_AND_INSTALL = 'DOWNLOAD_AND_INSTALL'
|
54
54
|
DOWNLOAD_ONLY = 'DOWNLOAD_ONLY'
|
55
55
|
|
56
|
+
# for easier use of these values as the updateAction
|
57
|
+
UPDATE_ACTIONS = {
|
58
|
+
install: DOWNLOAD_AND_INSTALL,
|
59
|
+
download: DOWNLOAD_ONLY
|
60
|
+
}
|
61
|
+
|
56
62
|
# Class Methods
|
57
63
|
#####################################
|
58
64
|
module ClassMethods
|
@@ -73,48 +79,51 @@ module Jamf
|
|
73
79
|
|
74
80
|
# Send the os update command to target Computers or a ComputerGroup
|
75
81
|
#
|
76
|
-
# @param updateAction [
|
82
|
+
# @param updateAction [Symbol, Symbol] Required. One of the keys or values from UPDATE_ACTIONS
|
77
83
|
#
|
78
|
-
# @param deviceIds [String, Integer, Array<String, Integer>] Identifiers for the
|
84
|
+
# @param deviceIds [String, Integer, Array<String, Integer>] Identifiers for the
|
79
85
|
# computer targets. Required if no groupId is given.
|
80
86
|
#
|
81
87
|
# @param groupId [String, Integer] Identifier for the computer group target.
|
82
|
-
# Requied if no
|
88
|
+
# Requied if no deviceIds are given.
|
83
89
|
#
|
84
|
-
# @param maxDeferrals [Integer] Allow users to defer the update the provided number
|
85
|
-
# of times before macOS forces the update. If a value is provided, the Software
|
86
|
-
# Update will use the InstallLater install action. MaxDeferral is ignored if using the
|
87
|
-
#
|
90
|
+
# @param maxDeferrals [Integer] Allow users to defer the update the provided number
|
91
|
+
# of times before macOS forces the update. If a value is provided, the Software
|
92
|
+
# Update will use the InstallLater install action. MaxDeferral is ignored if using the
|
93
|
+
# :download updateAction.
|
88
94
|
#
|
89
|
-
# @param version [String] The OS version to install. If no value is provided, the
|
95
|
+
# @param version [String] The OS version to install. If no value is provided, the
|
90
96
|
# version will default to latest version based on device eligibility.
|
91
97
|
#
|
92
98
|
# @param skipVersionVerification [Boolean] Should the specified version be installed
|
93
99
|
# even it it isn't applicable to this machine? If no value is provided, will default to false.
|
94
|
-
# If true, the specified version will be forced to complete
|
95
|
-
# install action.
|
100
|
+
# If true, the specified version will be forced to complete the :install updateAction.
|
96
101
|
#
|
97
102
|
# @param applyMajorUpdate [Boolean] Available only when updating to the latest version
|
98
103
|
# based on device eligibility. Defaults to false. If false the calculated latest version
|
99
104
|
# will only include minor version updates. If a value is provided, the calculated latest
|
100
105
|
# version will include minor and major version updates.
|
101
106
|
#
|
102
|
-
# @param forceRestart [Boolean] Will default to false. Can only be true if updateAction
|
103
|
-
# is
|
104
|
-
# If true, the DownloadAndInstall action is performed, a restart will be forced.
|
105
|
-
# MaxDeferral will be ignored if true.
|
107
|
+
# @param forceRestart [Boolean] Will default to false. Can only be true if updateAction
|
108
|
+
# is :install and the target devices are on macOs 11 or higher.
|
109
|
+
# If true, the DownloadAndInstall action is performed, a restart will be forced.
|
110
|
+
# MaxDeferral will be ignored if true.
|
106
111
|
#
|
107
|
-
# @param cnx [Jamf::Connection] The API connection to use. Defaults to Jamf.cnx
|
112
|
+
# @param cnx [Jamf::Connection] The API connection to use. Defaults to Jamf.cnx
|
108
113
|
#
|
109
|
-
# @return [Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse]
|
114
|
+
# @return [Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse]
|
110
115
|
########################
|
111
116
|
def send_managed_os_update(updateAction:, deviceIds: nil, groupId: nil, maxDeferrals: nil, version: nil, skipVersionVerification: false, applyMajorUpdate: false, forceRestart: false, cnx: Jamf.cnx)
|
112
|
-
|
117
|
+
action_to_send = UPDATE_ACTIONS.value?(updateAction) ? updateAction : UPDATE_ACTIONS[updateAction]
|
118
|
+
|
119
|
+
raise ArgumentError, "Unknown updateAction, must be one of: #{UPDATE_ACTIONS.keys.join ', '}" unless action_to_send
|
120
|
+
|
121
|
+
if self == Jamf::Computer
|
113
122
|
raise ArgumentError, 'Must provide one or more deviceIds' unless deviceIds
|
114
123
|
elsif self == Jamf::ComputerGroup
|
115
124
|
raise ArgumentError, 'Must provide a groupId' unless groupId
|
116
125
|
else
|
117
|
-
raise Jamf::UnsupportedError, 'This method is only available for Jamf::Computer and Jamf::ComputerGroup'
|
126
|
+
raise Jamf::UnsupportedError, 'This method is only available for Jamf::Computer and Jamf::ComputerGroup'
|
118
127
|
end
|
119
128
|
|
120
129
|
if version
|
@@ -124,9 +133,9 @@ module Jamf
|
|
124
133
|
|
125
134
|
if deviceIds
|
126
135
|
deviceIds = [deviceIds] unless deviceIds.is_a?(Array)
|
127
|
-
deviceIds.map! { |id| valid_id id }
|
136
|
+
deviceIds.map! { |id| valid_id id, cnx: cnx }
|
128
137
|
end
|
129
|
-
groupId = valid_id
|
138
|
+
groupId = valid_id(groupId, cnx: cnx) if groupId
|
130
139
|
|
131
140
|
data = {}
|
132
141
|
# ids in the JPAPI are string containing integers
|
@@ -137,11 +146,11 @@ module Jamf
|
|
137
146
|
data[:version] = version if version
|
138
147
|
data[:skipVersionVerification] = skipVersionVerification if skipVersionVerification
|
139
148
|
data[:applyMajorUpdate] = applyMajorUpdate if applyMajorUpdate
|
140
|
-
data[:updateAction] =
|
141
|
-
data[:forceRestart] = forceRestart if forceRestart
|
142
|
-
|
149
|
+
data[:updateAction] = action_to_send
|
150
|
+
data[:forceRestart] = forceRestart if forceRestart
|
151
|
+
|
143
152
|
payload = Jamf::OAPISchemas::MacOsManagedSoftwareUpdate.new(data).to_json
|
144
|
-
|
153
|
+
|
145
154
|
result = cnx.jp_post MANAGED_SW_UPDATES_SEND_UPDATES_RSRC, payload
|
146
155
|
Jamf::OAPISchemas::MacOsManagedSoftwareUpdateResponse.new result
|
147
156
|
end
|
@@ -161,14 +170,14 @@ module Jamf
|
|
161
170
|
groupId = is_a?(Jamf::Computer) ? nil : @id
|
162
171
|
|
163
172
|
self.class.send_managed_os_update(
|
164
|
-
deviceIds: deviceIds,
|
165
|
-
groupId: groupId,
|
166
|
-
maxDeferrals: maxDeferrals,
|
167
|
-
version: version,
|
168
|
-
skipVersionVerification: skipVersionVerification,
|
169
|
-
applyMajorUpdate: applyMajorUpdate,
|
170
|
-
forceRestart: forceRestart,
|
171
|
-
updateAction: updateAction,
|
173
|
+
deviceIds: deviceIds,
|
174
|
+
groupId: groupId,
|
175
|
+
maxDeferrals: maxDeferrals,
|
176
|
+
version: version,
|
177
|
+
skipVersionVerification: skipVersionVerification,
|
178
|
+
applyMajorUpdate: applyMajorUpdate,
|
179
|
+
forceRestart: forceRestart,
|
180
|
+
updateAction: updateAction,
|
172
181
|
cnx: @cnx
|
173
182
|
)
|
174
183
|
end
|
data/lib/jamf/validate.rb
CHANGED
@@ -98,7 +98,9 @@ module Jamf
|
|
98
98
|
#
|
99
99
|
# @return [Object] the validated unique value
|
100
100
|
#
|
101
|
-
def self.doesnt_already_exist(klass, identifier, val, msg: nil, api: Jamf.cnx)
|
101
|
+
def self.doesnt_already_exist(klass, identifier, val, msg: nil, api: nil, cnx: Jamf.cnx)
|
102
|
+
cnx = api if api
|
103
|
+
|
102
104
|
return val unless klass.all(:refresh, cnx: cnx).map { |i| i[identifier] }.include? val
|
103
105
|
|
104
106
|
key = klass.real_lookup_key identifier
|
data/lib/jamf/version.rb
CHANGED
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: ruby-jss
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version:
|
4
|
+
version: 3.0.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Chris Lasell
|
@@ -10,7 +10,7 @@ authors:
|
|
10
10
|
autorequire:
|
11
11
|
bindir: bin
|
12
12
|
cert_chain: []
|
13
|
-
date:
|
13
|
+
date: 2023-05-22 00:00:00.000000000 Z
|
14
14
|
dependencies:
|
15
15
|
- !ruby/object:Gem::Dependency
|
16
16
|
name: CFPropertyList
|