ruby-jss 2.0.0b1 → 2.0.0rc1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGES.md +1 -0
- data/README-2.0.0.md +101 -64
- data/README.md +223 -173
- data/lib/jamf/api/classic/api_objects/distribution_point.rb +12 -50
- data/lib/jamf/api/classic/api_objects/mobile_device_application.rb +35 -6
- data/lib/jamf/api/classic/api_objects/patch_title.rb +14 -9
- data/lib/jamf/api/classic/base_classes/api_object.rb +69 -10
- data/lib/jamf/api/classic/base_classes/patch_source.rb +10 -5
- data/lib/jamf/api/connection/token.rb +1 -0
- data/lib/jamf/api/connection.rb +1 -5
- data/lib/jamf/api/jamf_pro/api_objects/inventory_preload_record.rb +0 -1
- data/lib/jamf/api/jamf_pro/mixins/collection_resource.rb +8 -12
- data/lib/jamf/api/jamf_pro/mixins/macos_managed_updates.rb +17 -7
- data/lib/jamf/deprecations/deprecated_api_connection_class.rb +29 -0
- data/lib/jamf/version.rb +1 -1
- data/lib/jamf/zeitwerk_config.rb +217 -0
- data/lib/jamf.rb +7 -39
- data/test/tests/policy.rb +1 -0
- metadata +20 -31
- data/lib/zeitwerk_config.rb +0 -163
data/README.md
CHANGED
@@ -1,37 +1,53 @@
|
|
1
|
-
# ruby-jss: Working with the Jamf Pro
|
1
|
+
# ruby-jss: Working with the Jamf Pro APIs in Ruby
|
2
2
|
[![Gem Version](https://badge.fury.io/rb/ruby-jss.svg)](http://badge.fury.io/rb/ruby-jss)
|
3
3
|
|
4
|
-
##
|
4
|
+
## Version 2.0.0 has been released
|
5
5
|
|
6
|
-
|
6
|
+
Version 2.0.0 has major changes! While we've strived for backward compatibility, and have done lots of testing, YMMV. Please report any issues.
|
7
|
+
|
8
|
+
### Highlights
|
9
|
+
|
10
|
+
- Support for Ruby 3.x
|
11
|
+
- tested in 3.0 and 3.1
|
12
|
+
- Combined access to both the Classic and Jamf Pro APIs
|
13
|
+
- A single namespace module
|
14
|
+
- Connection objects talk to both APIs & automatically handle details like bearer tokens
|
15
|
+
- Auto-generated code for Jamf Pro API objects
|
16
|
+
- Autoloading of code using [Zeitwerk](https://github.com/fxn/zeitwerk)
|
17
|
+
|
18
|
+
For details about the changes, the document [README-2.0.0.md](README-2.0.0.md).
|
19
|
+
|
20
|
+
## _IMPORTANT_: Known Security Issue in v1.5.3 and below
|
21
|
+
|
22
|
+
Versions of ruby-jss prior to 1.6.0 contain a known security issue due to how we were using the 'plist' gem.
|
7
23
|
|
8
24
|
This has been resolved in 1.6.0, which now uses the CFProperlyList gem.
|
9
25
|
|
10
|
-
|
26
|
+
__Please update all installations of ruby-jss to at least v1.6.0.__
|
11
27
|
|
12
28
|
Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue and providing examples of how it could be exploited.
|
13
29
|
|
14
|
-
|
30
|
+
------
|
31
|
+
|
32
|
+
# Table of contents
|
15
33
|
|
16
34
|
<!-- TOC -->
|
17
35
|
|
36
|
+
- [Version 2.0.0 has been released](#version-200-has-been-released)
|
37
|
+
- [Highlights](#highlights)
|
38
|
+
- [_IMPORTANT_: Known Security Issue in v1.5.3 and below](#_important_-known-security-issue-in-v153-and-below)
|
18
39
|
- [DESCRIPTION](#description)
|
19
|
-
- [Contact](#contact)
|
20
40
|
- [SYNOPSIS](#synopsis)
|
21
41
|
- [USAGE](#usage)
|
22
|
-
- [Connecting to the
|
23
|
-
|
42
|
+
- [Connecting to the Server](#connecting-to-the-server)
|
43
|
+
- [Using multiple connections](#using-multiple-connections)
|
44
|
+
- [Working with Jamf Objects](#working-with-jamf-objects)
|
24
45
|
- [Listing Objects](#listing-objects)
|
25
46
|
- [Retrieving Objects](#retrieving-objects)
|
26
47
|
- [Creating Objects](#creating-objects)
|
27
48
|
- [Updating Objects](#updating-objects)
|
28
49
|
- [Deleting Objects](#deleting-objects)
|
29
50
|
- [OBJECTS IMPLEMENTED](#objects-implemented)
|
30
|
-
- [Creatable and Updatable](#creatable-and-updatable)
|
31
|
-
- [Updatable, but must be created in the Web UI](#updatable-but-must-be-created-in-the-web-ui)
|
32
|
-
- [Creatable only](#creatable-only)
|
33
|
-
- [Read-Only](#read-only)
|
34
|
-
- [Deletable](#deletable)
|
35
51
|
- [Other useful classes & modules:](#other-useful-classes--modules)
|
36
52
|
- [Object-related API endpoints](#object-related-api-endpoints)
|
37
53
|
- [CONFIGURATION](#configuration)
|
@@ -39,38 +55,35 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
|
|
39
55
|
- [BEYOND THE API](#beyond-the-api)
|
40
56
|
- [INSTALL](#install)
|
41
57
|
- [REQUIREMENTS](#requirements)
|
42
|
-
- [
|
58
|
+
- [Contact](#contact)
|
59
|
+
- [HELP & CONTACT INFO](#help--contact-info)
|
43
60
|
- [LICENSE](#license)
|
44
61
|
|
45
62
|
<!-- /TOC -->
|
46
63
|
|
47
64
|
## DESCRIPTION
|
48
65
|
|
49
|
-
ruby-jss defines a Ruby module called
|
50
|
-
|
51
|
-
devices from [Jamf.com](http://www.jamf.com/).
|
52
|
-
[ruby gem](https://rubygems.org/gems/ruby-jss), and the
|
66
|
+
ruby-jss defines a Ruby module called `Jamf`, which is used for accessing the 'Classic' and
|
67
|
+
'Jamf Pro' APIs of a Jamf Pro server. Jamf Pro is an enterprise-level management tool for Apple
|
68
|
+
devices from [Jamf.com](http://www.jamf.com/). It is available as a[ruby gem](https://rubygems.org/gems/ruby-jss), and the
|
53
69
|
[source is on github](https://github.com/PixarAnimationStudios/ruby-jss).
|
54
70
|
|
55
|
-
The module
|
56
|
-
|
57
|
-
|
58
|
-
point, and the installation of {JSS::Package} objects on client machines. (See [BEYOND THE API](#beyond-the-api))
|
71
|
+
The Jamf module maintains connections to both APIs simultaneously, and uses which ever is appropriate as needed.
|
72
|
+
Details like authentication tokens, token refreshing, JSON and XML parsing, and even knowing which resources use
|
73
|
+
which API are all handled under-the-hood.
|
59
74
|
|
60
|
-
The module
|
75
|
+
The Jamf module abstracts many API resources as Ruby objects, and provides methods for interacting with those
|
76
|
+
resources. It also provides some features that aren't a part of the API itself, but come with other
|
77
|
+
Jamf-related tools, such as uploading {Jamf::Package} files to the master distribution
|
78
|
+
point, and the installation of those objects on client machines. (See [BEYOND THE API](#beyond-the-api))
|
61
79
|
|
80
|
+
The Jamf module is not a complete implementation of the Jamf Pro APIs. Only some objects are modeled,
|
81
|
+
some only minimally. Of those, some are read-only, some partially writable, some fully read-write.
|
62
82
|
We've implemented the things we need in our environment, and as our needs grow, we'll add more.
|
63
83
|
Hopefully others will find it useful, and add more to it as well.
|
64
84
|
|
65
85
|
[Full technical documentation can be found here.](http://www.rubydoc.info/gems/ruby-jss/)
|
66
86
|
|
67
|
-
NOTE: ruby-jss 2.0.0 is in testing, see [README-2.0.0.md](README-2.0.0.md) for more info.
|
68
|
-
|
69
|
-
### Contact
|
70
|
-
|
71
|
-
If you have questions or feedback about ruby-jss, please reach out in the [#ruby-jss channel of Macadmins Slack](https://macadmins.slack.com/archives/C03C7F563MK), or open an issue on GitHub, or email ruby-jss@pixar.com.
|
72
|
-
|
73
|
-
|
74
87
|
## SYNOPSIS
|
75
88
|
|
76
89
|
Here are some simple examples of using ruby-jss
|
@@ -79,97 +92,138 @@ Here are some simple examples of using ruby-jss
|
|
79
92
|
require 'ruby-jss'
|
80
93
|
|
81
94
|
# Connect to the API
|
82
|
-
Jamf.cnx.connect
|
95
|
+
Jamf.cnx.connect "https://#{jamf_user}:#{jamf_pw}@my.jamf.server.com/"
|
83
96
|
|
84
|
-
# get an array of basic data about all
|
85
|
-
pkgs =
|
97
|
+
# get an array of basic data about all Jamf::Package objects in Jamf Pro:
|
98
|
+
pkgs = Jamf::Package.all
|
86
99
|
|
87
|
-
# get an array of names of all
|
88
|
-
pkg_names =
|
100
|
+
# get an array of names of all Jamf::Package objects in the Jamf Pro:
|
101
|
+
pkg_names = Jamf::Package.all_names
|
89
102
|
|
90
103
|
# Get a static computer group. This creates a new Ruby object
|
91
|
-
# representing the existing
|
92
|
-
|
104
|
+
# representing the existing Jamf computer group.
|
105
|
+
mac_group = Jamf::ComputerGroup.fetch name: "Macs of interest"
|
93
106
|
|
94
107
|
# Add a computer to the group
|
95
|
-
|
108
|
+
mac_group.add_member "pricklepants"
|
96
109
|
|
97
|
-
# save changes back to the
|
98
|
-
|
110
|
+
# save changes back to the server
|
111
|
+
mac_group.save
|
99
112
|
|
100
|
-
# Create a new network segment to store
|
101
|
-
# This makes a new Ruby Object that doesn't yet exist in
|
102
|
-
ns =
|
113
|
+
# Create a new network segment to store on the server.
|
114
|
+
# This makes a new Ruby Object that doesn't yet exist in Jamf Pro.
|
115
|
+
ns = Jamf::NetworkSegment.create(
|
103
116
|
name: 'Private Class C',
|
104
117
|
starting_address: '192.168.0.0',
|
105
118
|
ending_address: '192.168.0.255'
|
106
119
|
)
|
107
120
|
|
108
121
|
# Associate this network segment with a specific building,
|
109
|
-
# which must exist in
|
122
|
+
# which must exist in Jamf Pro, and be listed in Jamf::Building.all_names
|
110
123
|
ns.building = "Main Office"
|
111
124
|
|
112
125
|
# Associate this network segment with a specific software update server,
|
113
|
-
#
|
126
|
+
# which must exist in Jamf Pro, and be listed in Jamf::SoftwareUpdateServer.all_names
|
114
127
|
ns.swu_server = "Main SWU Server"
|
115
128
|
|
116
|
-
# save the new network segment
|
129
|
+
# save the new network segment to the server
|
117
130
|
ns.save
|
118
131
|
```
|
119
132
|
|
120
133
|
## USAGE
|
121
134
|
|
122
|
-
### Connecting to the
|
135
|
+
### Connecting to the Server
|
123
136
|
|
124
|
-
Before you can work with
|
137
|
+
Before you can work with Jamf Pros Objects via the APIs, you have to connect to the server.
|
125
138
|
|
126
|
-
The method `Jamf.cnx` returns the
|
139
|
+
The method `Jamf.cnx` returns the 'default' connection object (an instance of a {Jamf::APIConnection}, q.v.).
|
140
|
+
A connection object holds all the data needed to communicate with the server to which it's connected, as well as
|
141
|
+
any data cached from that server.
|
142
|
+
The default connection object is used for all communication unless a different one is explicitly passed to methods
|
143
|
+
that can accept one. See 'Using multiple connections' below.
|
127
144
|
|
128
|
-
When the
|
145
|
+
When the Jamf Module is first loaded, the default connection isn't connected a server. To remedy that, use `Jamf.cnx.connect`,
|
146
|
+
passing it parameters for the connection. In this example, those parameters are stored in the local variables jss_user,
|
147
|
+
jss_user_pw, and jss_server_hostname, and others are left as default.
|
129
148
|
|
130
149
|
```ruby
|
131
150
|
Jamf.cnx.connect user: jss_user, pw: jss_user_pw, server: jss_server_hostname
|
132
151
|
```
|
133
152
|
|
134
|
-
|
153
|
+
You can also provide a URL, optionally including the credentials, and port number. Any value not available in the URL can be passed as a normal parameter.
|
135
154
|
|
136
|
-
|
155
|
+
```ruby
|
156
|
+
Jamf.cnx.connect "https://#{jamf_user}@my.jamf.server.com/", pw: jamf_user_pw, port: 8443
|
157
|
+
```
|
158
|
+
|
159
|
+
Make sure the user has privileges in the Jamf to do things with desired objects. Note that these might be more than you think, since some objects refer to other objects, like Sites and Categories.
|
160
|
+
|
161
|
+
If the server name given ends with 'jamfcloud.com' the port number will default to 443 via SSL. Otherwise, it defaults to 8443 with SSL (the default port for on-prem. servers). In other situations, you can specify it with the `port:` and `use_ssl:` parameters.
|
137
162
|
|
138
163
|
The connect method also accepts the symbols :stdin and :prompt as values for pw:, which will cause it to read the
|
139
|
-
password from stdin, or prompt for it in the shell. See the {
|
164
|
+
password from stdin, or prompt for it in the shell. See the {Jamf::Connection} class for more connection options and details about its methods.
|
140
165
|
|
141
|
-
Also see
|
166
|
+
Also see Jamf::Configuration, and the [CONFIGURATION](#configuration) section below, for how to store
|
142
167
|
server connection parameters in a simple config file.
|
143
168
|
|
144
|
-
|
169
|
+
#### Using multiple connections
|
170
|
+
|
171
|
+
Most of the time, you'll only need a single connection to a single server, and the default connection will be sufficient. However
|
172
|
+
you can also create multiple Connection objects, to different servers, or perhaps the same server with different credentials and
|
173
|
+
access, and pass those connection objects into methods using the `cnx:` parameter as appropriate.
|
145
174
|
|
146
|
-
|
175
|
+
```ruby
|
176
|
+
# Make connections to 2 different Jamf servers.
|
177
|
+
# The .new class method accepts the same parameters as the #connect instance method,
|
178
|
+
# and will automatically pass them to the #connect method when instantiating
|
179
|
+
# the new connection object.
|
180
|
+
connection_1 = Jamf::Connection.new user: jss_user, pw: jss_user_pw, server: jss_server_hostname
|
181
|
+
connection_2 = Jamf::Connection.new user: jss_user2, pw: jss_user_pw2, server: jss_server_hostname2
|
182
|
+
|
183
|
+
# Get an array of the serialNumbers from all InventoryPreloadRecords in server 1
|
184
|
+
ipr_sns_1 = Jamf::InventoryPreloadRecord.all_serialNumbers cnx: connection_1
|
185
|
+
|
186
|
+
# Get an array of the serialNumbers from all InventoryPreloadRecords in server 2
|
187
|
+
ipr_sns_2 = Jamf::InventoryPreloadRecord.all_serialNumbers cnx: connection_2
|
188
|
+
|
189
|
+
# Find the SNs that appear in both
|
190
|
+
common_ipr_sns = ipr_sns_1 & ipr_sns_2
|
191
|
+
```
|
192
|
+
|
193
|
+
### Working with Jamf Objects
|
147
194
|
|
148
|
-
|
195
|
+
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 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
|
197
|
+
yet and haven't implemented that functionality. If you need additional features implemented, please get in touch (see 'Contact' above) or feel free to
|
198
|
+
try implementing it yourself and send us a merge request.
|
199
|
+
|
200
|
+
Some of the implemented objects also provide access to more 'functional' API resources. For example, the API resources for
|
201
|
+
sending MDM commands to computers and mobile devices are available as class and instance methods of Jamf::Computer and Jamf::MobileDevice,
|
202
|
+
as are the API resources for accessing management history.
|
149
203
|
|
150
204
|
--------
|
151
205
|
|
152
206
|
#### Listing Objects
|
153
207
|
|
154
|
-
To get an Array with a summary of every object in the
|
208
|
+
To get an Array with a summary of every object in the Jamf of some Class, call that Class's .all method:
|
155
209
|
|
156
210
|
```ruby
|
157
|
-
|
211
|
+
Jamf::Computer.all # => [{:name=>"cephei", :id=>1122},{:name=>"peterparker", :id=>1218}, {:name=>"rowdy", :id=>931}, ...]
|
158
212
|
```
|
159
213
|
|
160
214
|
The Array will contain a Hash for each item, with at least a :name and an :id. Some classes provide more summary data for each item.
|
161
215
|
To get just the names or just the ids in an Array, use the .all\_names or .all\_ids Class method
|
162
216
|
|
163
217
|
```ruby
|
164
|
-
|
165
|
-
|
218
|
+
Jamf::Computer.all_names # => ["cephei", "peterparker", "rowdy", ...]
|
219
|
+
Jamf::Computer.all_ids # => [1122, 1218, 931, ...]
|
166
220
|
```
|
167
221
|
|
168
|
-
Some Classes provide other ways to list objects, or subsets of them, depending on the data available, e.g.
|
222
|
+
Some Classes provide other ways to list objects, or subsets of them, depending on the data available, e.g. Jamf::MobileDevice.all\_udids or Jamf::Computer.all\_laptops
|
169
223
|
|
170
|
-
You can also perform simple searches for
|
224
|
+
You can also perform simple searches for Jamf::Computer, Jamf::MobileDevice and Jamf::User with the `.match` class method. This is the API equivalent of using the simple search field at the top of the Computers, Devices, or Users pages in the Jamf Pro Web interface. This method will return an Array of Hashes for the matching items. Each Hash is a summary of info about a matching item, similar to the summaries returned by the `.all` methods for those items.
|
171
225
|
|
172
|
-
To create, modify, or perform advanced searches, use the classes
|
226
|
+
To create, modify, or perform advanced searches, use the classes Jamf::AdvancedComputerSearch, Jamf::AdvancedMobileDeviceSearch, and Jamf::AdvancedUserSearch.
|
173
227
|
|
174
228
|
--------
|
175
229
|
|
@@ -179,23 +233,23 @@ To retrieve a single object call the class's `.fetch` method and provide a name:
|
|
179
233
|
|
180
234
|
|
181
235
|
```ruby
|
182
|
-
a_dept =
|
236
|
+
a_dept = Jamf::Department.fetch name: 'Payroll'# => #<Jamf::Department:0x10b4c0818...
|
183
237
|
```
|
184
238
|
|
185
239
|
Some classes can use more than just the :id and name: keys for lookups, e.g. computers can be looked up with udid:, serial_number:, or mac_address:.
|
186
240
|
|
187
|
-
You can even fetch objects without specifying the kind of identifier, e.g. `
|
241
|
+
You can even fetch objects without specifying the kind of identifier, e.g. `Jamf::Computer.fetch 'VM3X9483HD78'`, but this will be slower, since ruby-jss searches by matching the given value with all available identifiers, returning the first match.
|
188
242
|
|
189
243
|
--------
|
190
244
|
|
191
245
|
#### Creating Objects
|
192
246
|
|
193
|
-
Some Objects can be created anew in the
|
247
|
+
Some Objects can be created anew in the Jamf via ruby. To do so, first make a Ruby object using the class's `.create` method and providing a unique :name:, e.g.
|
194
248
|
|
195
249
|
```ruby
|
196
|
-
new_pkg =
|
250
|
+
new_pkg = Jamf::Package.create name: "transmogrifier-2.3-1.pkg"
|
197
251
|
```
|
198
|
-
*NOTE*: some classes require more data than just a name: when created with .
|
252
|
+
*NOTE*: some classes require more data than just a name: when created with .create
|
199
253
|
|
200
254
|
Then set the attributes of the new object as needed
|
201
255
|
|
@@ -205,7 +259,7 @@ new_pkg.category = "CoolTools"
|
|
205
259
|
# etc..
|
206
260
|
```
|
207
261
|
|
208
|
-
Then use the #save method to
|
262
|
+
Then use the #save method to send the data to the API, creating it in Jamf Pro.
|
209
263
|
|
210
264
|
```ruby
|
211
265
|
new_pkg.save # returns 453, the id number of the object just created
|
@@ -215,14 +269,14 @@ new_pkg.save # returns 453, the id number of the object just created
|
|
215
269
|
|
216
270
|
#### Updating Objects
|
217
271
|
|
218
|
-
Some objects can be modified
|
272
|
+
Some objects can be modified.
|
219
273
|
|
220
274
|
```ruby
|
221
|
-
existing_script =
|
275
|
+
existing_script = Jamf::Script.fetch id: 321
|
222
276
|
existing_script.name = "transmogrifier-2.3-1.post-install"
|
223
277
|
```
|
224
278
|
|
225
|
-
After changing any attributes, use the #save method
|
279
|
+
After changing any attributes, use the #save method to push the changes to the sever.
|
226
280
|
|
227
281
|
```ruby
|
228
282
|
existing_script.save # => returns the id number of the object just saved
|
@@ -235,16 +289,19 @@ existing_script.save # => returns the id number of the object just saved
|
|
235
289
|
To delete an object, just call its #delete method
|
236
290
|
|
237
291
|
```ruby
|
238
|
-
existing_script =
|
292
|
+
existing_script = Jamf::Script.fetch id: 321
|
239
293
|
existing_script.delete # => true # the delete was successful
|
240
294
|
```
|
241
295
|
To delete an object without fetching it, use the class's .delete method and provide the id, or an array of ids.
|
242
296
|
|
243
297
|
```ruby
|
244
|
-
|
298
|
+
Jamf::Script.delete [321, 543, 374]
|
245
299
|
```
|
246
300
|
|
247
|
-
|
301
|
+
For more details see the docs for:
|
302
|
+
- [Jamf::APIObject](http://www.rubydoc.info/gems/ruby-jss/Jamf/APIObject), the parent class of all Classic API resources
|
303
|
+
- [Jamf::OAPIObject](http://www.rubydoc.info/gems/ruby-jss/Jamf/OAPIObject), the parent class of all Jamf Pro API objects
|
304
|
+
- [Jamf::CollectionResource](http://www.rubydoc.info/gems/ruby-jss/Jamf/CollectionResource), the parent class of all Jamf Pro API collection resources
|
248
305
|
|
249
306
|
See the individual subclasses for any details specific to them.
|
250
307
|
|
@@ -252,77 +309,64 @@ See the individual subclasses for any details specific to them.
|
|
252
309
|
|
253
310
|
While the API itself supports nearly full CRUD (Create,Read,Update,Delete) for all objects, ruby-jss doesn't yet do so. Why? Because implementing the data validation and other parts needed for creating & updating can be time-consuming and we've focused on what we needed. As we keep developing ruby-jss, this list changes. If you'd like to help implement some of these objects more fully, please fork the github project and reach out to us at ruby-jss@pixar.com.
|
254
311
|
|
255
|
-
Here's what we've implemented so far. See each Class's [documentation(http://www.rubydoc.info/gems/ruby-jss)] for details.
|
256
|
-
|
257
|
-
|
258
|
-
|
259
|
-
* {
|
260
|
-
* {
|
261
|
-
* {
|
262
|
-
* {
|
263
|
-
* {
|
264
|
-
* {
|
265
|
-
* {
|
266
|
-
* {
|
267
|
-
* {
|
268
|
-
* {
|
269
|
-
* {
|
270
|
-
* {
|
271
|
-
* {
|
272
|
-
* {
|
273
|
-
* {
|
274
|
-
* {
|
275
|
-
* {
|
276
|
-
* {
|
277
|
-
* {
|
278
|
-
* {
|
279
|
-
* {
|
280
|
-
* {
|
281
|
-
* {
|
282
|
-
* {
|
283
|
-
* {
|
284
|
-
* {
|
285
|
-
* {
|
286
|
-
* {
|
287
|
-
* {
|
288
|
-
* {
|
289
|
-
* {
|
290
|
-
|
312
|
+
Here's some of what we've implemented so far. See each Class's [documentation(http://www.rubydoc.info/gems/ruby-jss)] for details.
|
313
|
+
|
314
|
+
|
315
|
+
* {Jamf::AdvancedComputerSearch}
|
316
|
+
* {Jamf::AdvancedMobileDeviceSearch}
|
317
|
+
* {Jamf::AdvancedUserSearch}
|
318
|
+
* {Jamf::Building}
|
319
|
+
* {Jamf::Category}
|
320
|
+
* {Jamf::Computer}
|
321
|
+
* {Jamf::ComputerExtensionAttribute}
|
322
|
+
* {Jamf::ComputerGroup}
|
323
|
+
* {Jamf::ComputerInvitation}
|
324
|
+
* {Jamf::Department}
|
325
|
+
* {Jamf::DistributionPoint}
|
326
|
+
* {Jamf::DockItem}
|
327
|
+
* {Jamf::EBook}
|
328
|
+
* {Jamf::IBeacon}
|
329
|
+
* {Jamf::LdapServer}
|
330
|
+
* {Jamf::MobileDevice}
|
331
|
+
* {Jamf::MobileDeviceApplication}
|
332
|
+
* {Jamf::MobileDeviceConfigurationProfile}
|
333
|
+
* {Jamf::MobileDeviceExtensionAttribute}
|
334
|
+
* {Jamf::MobileDeviceGroup}
|
335
|
+
* {Jamf::NetBootServer}
|
336
|
+
* {Jamf::NetworkSegment}
|
337
|
+
* {Jamf::OSXConfigurationProfile}
|
338
|
+
* {Jamf::Package}
|
339
|
+
* {Jamf::PatchTitle}
|
340
|
+
* {Jamf::PatchTitle::Version}
|
341
|
+
* {Jamf::PatchExternalSource}
|
342
|
+
* {Jamf::PatchInternalSource}
|
343
|
+
* {Jamf::PatchPolicy}
|
344
|
+
* {Jamf::Peripheral}
|
345
|
+
* {Jamf::PeripheralType}
|
346
|
+
* {Jamf::Policy} (not fully implemented)
|
347
|
+
* {Jamf::RemovableMacAddress}
|
348
|
+
* {Jamf::RestrictedSoftware}
|
349
|
+
* {Jamf::Script}
|
350
|
+
* {Jamf::Site}
|
351
|
+
* {Jamf::SoftwareUpdateServer}
|
352
|
+
* {Jamf::User}
|
353
|
+
* {Jamf::UserExtensionAttribute}
|
354
|
+
* {Jamf::UserGroup}
|
355
|
+
* {Jamf::WebHook}
|
291
356
|
|
292
357
|
**NOTE** Most Computer and MobileDevice data gathered by an Inventory Upate (a.k.a. 'recon') is not editable.
|
293
358
|
|
294
|
-
|
295
|
-
|
296
|
-
* {JSS::OSXConfigurationProfile}
|
297
|
-
* {JSS::MobileDeviceConfigurationProfile}
|
298
|
-
* {JSS::PatchInternalSource}
|
299
|
-
|
300
|
-
### Creatable only
|
301
|
-
|
302
|
-
* {JSS::ComputerInvitation}
|
303
|
-
|
304
|
-
### Read-Only
|
359
|
+
#### Other useful classes & modules:
|
305
360
|
|
306
|
-
These
|
361
|
+
These modules either provide stand-alone methods, or are mixed in to other classes to extend their functionality. See their documentation for details
|
307
362
|
|
308
|
-
* {
|
309
|
-
* {JSS::LdapServer}
|
310
|
-
* {JSS::NetBootServer}
|
311
|
-
* {JSS::SoftwareUpdateServer}
|
363
|
+
* {Jamf::Client} - An object representing the local machine as a Jamf-managed client, and provifing Jamf-related info and methods
|
312
364
|
|
313
|
-
|
365
|
+
* {Jamf::ManagementHistory} - a module for handing the management history for Computers and Mobile Devices. It defines many read-only classes representing events in a machine's history. It is accessed via the Computer and MobileDevice classes and their instances.
|
314
366
|
|
315
|
-
|
367
|
+
* {Jamf::Scopable} - a module that handles Scope for those objects that can be scoped. It defines the Scope class used in those objects. Instances of Scope are where you change targets, limitations, and exclusions.
|
316
368
|
|
317
|
-
|
318
|
-
|
319
|
-
* {JSS::APIConnection} - An object representing a connection to the Classic API on some server. The 'default' connection object is available via `Jamf.cnx` but you can create others, and pass them into calls like `.fetch` as needed. This is useful when working with multiple servers at a time, such as a production and a test server. Objects retrieved from a connection know which connection they came from, and will only send changes via that connection.
|
320
|
-
* {JSS::DBConnection} - An object representing the connection to MySQL database, if used.
|
321
|
-
* {JSS::Server} - An object representing the Jamf Pro server being used by a connection. An instance is available in the #server attribute of a {JSS::APIConnection}.
|
322
|
-
* {JSS::Client} - An object representing the local machine as a Jamf-managed client, and provifing Jamf-related info and methods
|
323
|
-
* {JSS::ManagementHistory} - a module for handing the management history for Computers and Mobile Devices. It defines many read-only classes representing events in a machine's history. It is accessed via the Computer and MobileDevice classes and their instances.
|
324
|
-
* {JSS::Scopable} - a module that handles Scope for those objects that can be scoped. It defines the Scope class used in those objects.
|
325
|
-
* {JSS::MDM} - a module that handles sending MDM commands. It is accessed via the Computer and MobileDevice classes and their instances.
|
369
|
+
* {Jamf::MDM} - a module that handles sending MDM commands. It is accessed via the Computer and MobileDevice classes and their instances.
|
326
370
|
|
327
371
|
## Object-related API endpoints
|
328
372
|
|
@@ -331,19 +375,19 @@ The classic API provides many endpoints not just for objects stored in Jamf Pro,
|
|
331
375
|
For example:
|
332
376
|
|
333
377
|
* /computerapplications, /computerapplicationusage, /computerhardwaresoftwarereports, /computerhistory, etc.
|
334
|
-
- The data provided by these endpoints are accessible via class and instance methods for {
|
378
|
+
- The data provided by these endpoints are accessible via class and instance methods for {Jamf::Computer}
|
335
379
|
* /computercheckin, /computerinventorycollection
|
336
|
-
- These endpoints deal with server-wide settings regarding computer management, and are available via {
|
380
|
+
- These endpoints deal with server-wide settings regarding computer management, and are available via {Jamf::Computer} class methods
|
337
381
|
* /computercommands, /mobiledevicecommands, /commandflush, etc.
|
338
|
-
- These endpoints provide access to the MDM infrastructure, and can be used to send MDM commands. Ruby-jss provides these as class and instance methods in {
|
382
|
+
- These endpoints provide access to the MDM infrastructure, and can be used to send MDM commands. Ruby-jss provides these as class and instance methods in {Jamf::Computer}, {Jamf::ComputerGroup}, {Jamf::MobileDevice}, and {Jamf::MobileDeviceGroup}
|
339
383
|
|
340
384
|
## CONFIGURATION
|
341
385
|
|
342
|
-
The {
|
386
|
+
The {Jamf::Configuration} singleton class is used to read, write, and use site-specific defaults for the Jamf module. When ruby-jss is required, the single instance of {Jamf::Configuration} is created and accessible via the `Jamf.config` method. At that time the system-wide file /etc/ruby-jss.conf is examined if it exists, and the items in it are loaded into the attributes of Configuration instance. The user-specific file ~/.ruby-jss.conf then is examined if it exists, and any items defined there will override those values from the system-wide file.
|
343
387
|
|
344
|
-
The values defined in those files are used as defaults throughout the module. Currently, those values are only related to establishing the API connection. For example, if a server name is defined, then a :
|
388
|
+
The values defined in those files are used as defaults throughout the module. Currently, those values are only related to establishing the API connection. For example, if a server name is defined, then a server: does not have to be specified when calling {Jamf::Connection#connect}. Values provided explicitly when calling Jamf::Connection#connect will override the config values.
|
345
389
|
|
346
|
-
While the {
|
390
|
+
While the {Jamf::Configuration} class provides methods for changing the values, saving the files, and re-reading them, or reading an arbitrary file, the files are text files with a simple format, and can be created by any means desired. The file format is one attribute per line, thus:
|
347
391
|
|
348
392
|
attr_name: value
|
349
393
|
|
@@ -351,30 +395,30 @@ Lines that don’t start with a known attribute name followed by a colon are ign
|
|
351
395
|
|
352
396
|
The currently known attributes are:
|
353
397
|
|
354
|
-
* api_server_name [String] the hostname of the
|
398
|
+
* api_server_name [String] the hostname of the Jamf API server
|
355
399
|
* api_server_port [Integer] the port number for the API connection
|
356
400
|
* api_verify_cert [Boolean] 'true' or 'false' - if SSL is used, should the certificate be verified? (usually false for a self-signed cert)
|
357
|
-
* api_username [String] the
|
401
|
+
* api_username [String] the Jamf username for connecting to the API
|
358
402
|
* api_timeout_open [Integer] the number of seconds for the open-connection timeout
|
359
403
|
* api_timeout [Integer] the number of seconds for the response timeout
|
360
404
|
|
361
|
-
To put a standard server & username on all client machines, and auto-accept the
|
405
|
+
To put a standard server & username on all client machines, and auto-accept the Jamf's self-signed https certificate, create the file /etc/ruby-jss.conf containing three lines like this:
|
362
406
|
|
363
407
|
```
|
364
408
|
api_server_name: jamfpro.myschool.edu
|
365
409
|
api_username: readonly-api-user
|
366
|
-
|
410
|
+
api_timeout: 90
|
367
411
|
```
|
368
412
|
|
369
|
-
and then any calls to Jamf.cnx.connect will assume that server and username, and
|
413
|
+
and then any calls to Jamf.cnx.connect will assume that server and username, and use a timeout of 90 seconds.
|
370
414
|
|
371
415
|
### Passwords
|
372
416
|
|
373
|
-
The config files don't store passwords and the {
|
417
|
+
The config files don't store passwords and the {Jamf::Configuration} instance doesn't work with them. You'll have to use your own methods for acquiring the password for the Jamf.cnx.connect call.
|
374
418
|
|
375
|
-
The {
|
419
|
+
The {Jamf::APIConnection.connect} method also accepts the symbols :stdin# and :prompt as values for the :pw argument, which will cause it to read the password from a line of stdin, or prompt for it in the shell.
|
376
420
|
|
377
|
-
If you must store a password in a file, or retrieve it from the network, make sure it's stored securely, and that the
|
421
|
+
If you must store a password in a file, or retrieve it from the network, make sure it's stored securely, and that the Jamf user has limited permissions.
|
378
422
|
|
379
423
|
Here's an example of how to use a password stored in a file:
|
380
424
|
|
@@ -393,56 +437,62 @@ Jamf.cnx.connect pw: password # other arguments used from the config settings
|
|
393
437
|
|
394
438
|
## BEYOND THE API
|
395
439
|
|
396
|
-
While the Jamf Pro
|
440
|
+
While the Jamf Pro APIs provide access to object data in the Jamf, ruby-jss tries to use that data to provide more than just information exchange. Here are some examples of how ruby-jss uses the API to provide functionality found in various Jamf tools:
|
397
441
|
|
398
442
|
* Client Machine Access
|
399
|
-
* The {
|
443
|
+
* The {Jamf::Client} module provides the ability to run jamf binary commands, and access the local cache of package receipts
|
400
444
|
* Package Installation
|
401
|
-
* {
|
445
|
+
* {Jamf::Package} objects can be installed on the local machine, from the appropriate distribution point
|
402
446
|
* Script Execution
|
403
|
-
* {
|
447
|
+
* {Jamf::Script} objects can be executed locally on demand
|
404
448
|
* Package Creation
|
405
|
-
* The {
|
406
|
-
* {
|
449
|
+
* The {Jamf::Composer} module provides creation of very simple .pkg and .dmg packages
|
450
|
+
* {Jamf::Package} objects can upload their .pkg or .dmg files to the master distribution point
|
407
451
|
* Reporting/AdvancedSearch exporting
|
408
|
-
* {
|
452
|
+
* {Jamf::AdvancedSearch} subclasses can export their results to csv, tab, and xml files.
|
409
453
|
* MDM Commands
|
410
|
-
* {
|
454
|
+
* {Jamf::MobileDevice}s and {Jamf::Computer}s can be sent MDM commands
|
411
455
|
* Extension Attributes
|
412
|
-
* {
|
456
|
+
* {Jamf::ExtensionAttribute} work with {Jamf::AdvancedSearch} subclasses to provide extra reporting about Extension Attribute values.
|
413
457
|
|
414
458
|
## INSTALL
|
415
459
|
|
416
|
-
NOTE: You may need to install XCode, or it's CLI tools, in order to install the required gems.
|
417
|
-
|
418
460
|
In general, you can install ruby-jss with this command:
|
419
461
|
|
420
462
|
`gem install ruby-jss`
|
421
463
|
|
422
464
|
## REQUIREMENTS
|
423
465
|
|
424
|
-
ruby-jss
|
466
|
+
ruby-jss 2.0.0 requires:
|
425
467
|
|
426
|
-
*
|
427
|
-
*
|
428
|
-
* Casper Suite version 10.4 or higher
|
468
|
+
* Ruby 2.6.3 or higher (the OS-installed ruby version for macOS 10.15 Catalina)
|
469
|
+
* Jamf Pro server version 10.35 or higher
|
429
470
|
|
430
471
|
It also requires other ruby gems, which will be installed automatically if you install with `gem install ruby-jss`
|
431
472
|
See the .gemspec file for details
|
432
473
|
|
433
474
|
|
434
|
-
|
475
|
+
### Contact
|
476
|
+
|
477
|
+
If you have questions or feedback about ruby-jss, please reach out to us via:
|
478
|
+
- The [#ruby-jss channel of Macadmins Slack](https://macadmins.slack.com/archives/C03C7F563MK)
|
479
|
+
- Open an issue on GitHub
|
480
|
+
- Email ruby-jss@pixar.com
|
481
|
+
|
482
|
+
|
483
|
+
## HELP & CONTACT INFO
|
435
484
|
|
436
485
|
Full documentation is available at [rubydoc.info](http://www.rubydoc.info/gems/ruby-jss/).
|
437
486
|
|
438
487
|
There's a [wiki on the github page](https://github.com/PixarAnimationStudios/ruby-jss/wiki), feel free to contribute examples and tidbits.
|
439
488
|
|
440
|
-
|
441
|
-
|
442
|
-
[
|
489
|
+
You can report issues in several ways:
|
490
|
+
- [Open an issue on github](https://github.com/PixarAnimationStudios/ruby-jss/issues)
|
491
|
+
- [Email the developers at ruby-jss@pixar.com](mailto:ruby-jss@pixar.com)
|
492
|
+
- Join the conversation in the [#ruby-jss Macadmins Slack Channel](https://macadmins.slack.com/archives/C03C7F563MK)
|
443
493
|
|
444
494
|
## LICENSE
|
445
495
|
|
446
496
|
Copyright 2022 Pixar
|
447
497
|
|
448
|
-
Licensed under
|
498
|
+
Licensed under a modified Apache License, Version 2.0. See LICENSE.txt for details
|