Class: Jamf::DistributionPoint
- Defined in:
- lib/jamf/api/classic/api_objects/distribution_point.rb
Overview
A FileShare Distribution Point in the JSS
As well as the normal Class and Instance methods for APIObject subclasses, the DistributionPoint class provides more interaction with other parts of the API.
Beyond the standard listing methods DistributionPoint.all, .all_ids, etc, every JSS has a single “master” distribution point. The Class method DistributionPoint.master_distribution_point will return the Jamf::DistributionPoint object for that master.
Also, some network segments have specific DistributionPoints assigned to them. Calling the Class method DistributionPoint.my_distribution_point will return a Jamf::DistributionPoint object for your local IP address.
Once you have an instance of Jamf::DistributionPoint, you can mount it (on a Mac) by calling its #mount method and unmount it with #unmount. The Package and possibly Script classes use this to upload items to the master.
NOTE: This class only deals with FileShare Distribution Points. There is no access to the Cloud Distribution Point in the classic API. See the .master_distribution_point and .my_distribution_point class methods for how they handle things when the Cloud DP is the master.
Constant Summary collapse
- RSRC_BASE =
The base for REST resources of this class
'distributionpoints'.freeze
- RSRC_LIST_KEY =
the hash key used for the JSON list output of all objects in the JSS its also used in various error messages
:distribution_points
- RSRC_OBJECT_KEY =
The hash key used for the JSON object output. It’s also used in various error messages
:distribution_point
- MOUNT_OPTIONS =
what are the mount options? these are comma-separated, and are passed with -o
'nobrowse'.freeze
- EMPTY_PW_256 =
An empty SHA256 digest
'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'.freeze
- DEFAULT_MOUNTPOINT_DIR =
Set default local mount for distribution point
Pathname.new '/tmp'
- DEFAULT_MOUNTPOINT_PREFIX =
'CasperDistribution-id'.freeze
- OBJECT_HISTORY_OBJECT_TYPE =
the object type for this object in the object history table. See APIObject#add_object_history_entry
76
Instance Attribute Summary collapse
-
#certificate ⇒ String
readonly
The name of the cert.
-
#certificate_required ⇒ Boolean
readonly
Do http downloads use cert.
-
#connection_type ⇒ String
readonly
Protocol for fileservice access (e.g. AFP, SMB).
-
#context ⇒ String
readonly
The “context” for http downloads (what goes after the hostname part of the URL).
-
#enable_load_balancing ⇒ String
readonly
Load balanacing enabled?.
-
#failover_point ⇒ Integer
readonly
The id of the DP to use for failover.
-
#failover_point_url ⇒ String
readonly
The URL to use if this one doesn’t work.
-
#http_downloads_enabled ⇒ Boolean
readonly
Are http downloads available from this DP?.
-
#http_password_sha256 ⇒ String
readonly
The password for http downloads, if needed, as a SHA256 digest.
-
#http_url ⇒ String
readonly
The URL for http downloads.
-
#http_username ⇒ String
readonly
The username to use for http downloads if needed for user/pw auth.
-
#ip_address ⇒ String
(also: #hostname)
readonly
The hostname of this DP.
-
#is_master ⇒ Boolean
(also: #master?)
readonly
Is this the master DP?.
-
#local_path ⇒ String
readonly
The local path on the server to the distribution point directory.
-
#no_authentication_required ⇒ Boolean
readonly
Do http downloads work without auth?.
-
#port ⇒ Integer
readonly
The port for http access.
-
#protocol ⇒ String
readonly
The protocol to use for http downloads (http/https).
-
#read_only_password_sha256 ⇒ String
readonly
Read-only password as a SHA256 digest.
-
#read_only_username ⇒ String
readonly
Read-only username for fileservice.
-
#read_write_password_sha256 ⇒ String
readonly
The read-write password as a SHA256 digest.
-
#read_write_username ⇒ String
readonly
The read-write username for fileservice access.
-
#share_name ⇒ String
readonly
The name of the fileservice sharepoint.
-
#share_port ⇒ Integer
readonly
The port for fileservice access.
-
#ssh_password_sha256 ⇒ String
readonly
The ssh password as a SHA256 digest.
-
#ssh_username ⇒ String
readonly
Ssh username.
-
#username_password_required ⇒ Boolean
readonly
Do http downloads use user/pw auth?.
-
#workgroup_or_domain ⇒ String
readonly
Work group or domain for SMB.
Class Method Summary collapse
-
.master_distribution_point(refresh = false, default: nil, api: nil, cnx: Jamf.cnx) ⇒ Jamf::DistributionPoint
Get the DistributionPoint instance for the master distribution point.
-
.my_distribution_point(refresh = false, default: :master, api: nil, cnx: Jamf.cnx) ⇒ Jamf::DistributionPoint
Get the DistributionPoint instance for the machine running this code, based on its IP address.
Instance Method Summary collapse
-
#check_pw(_user = nil, _pw = nil) ⇒ TrueClass
deprecated
Deprecated.
The API no longer sends SHA256 hashed password data, and instead only has a string of asterisks, meaning we can no longer use it to validate passwords before attempting to use them. Instead, the processes that use them, e.g. mounting a Dist. Point, will fail on their own if the pw is not valid.
This method remains defined for backward-compatibility with any existing code that calls it. but it will always return true. It will be removed in a future version
-
#initialize(**args) ⇒ DistributionPoint
constructor
A new instance of DistributionPoint.
-
#mount(pw = nil, access = :ro) ⇒ Pathname
Mount this distribution point locally.
-
#mounted? ⇒ Boolean
Is this thing mounted right now?.
-
#reachable_for_download?(pw = '', check_http = true) ⇒ FalseClass, Symbol
Check to see if this dist point is reachable for downloads (read-only) via either http, if available, or filesharing.
-
#reachable_for_upload?(pw) ⇒ FalseClass, Symbol
Check to see if this dist point is reachable for uploads (read-write) via filesharing.
-
#unmount ⇒ void
(also: #umount)
Unmount the distribution point.
Constructor Details
#initialize(**args) ⇒ DistributionPoint
Returns a new instance of DistributionPoint.
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 291 292 293 294 295 296 297 298 299 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 261 def initialize(**args) super @ip_address = @init_data[:ip_address] @local_path = @init_data[:local_path] @enable_load_balancing = @init_data[:enable_load_balancing] @failover_point = @init_data[:failover_point] @is_master = @init_data[:is_master] @connection_type = @init_data[:connection_type] @share_port = @init_data[:share_port] @share_name = @init_data[:share_name] @workgroup_or_domain = @init_data[:workgroup_or_domain] @read_write_username = @init_data[:read_write_username] @read_write_password_sha256 = @init_data[:read_write_password_sha256] @read_only_username = @init_data[:read_only_username] @read_only_password_sha256 = @init_data[:read_only_password_sha256] @ssh_username = @init_data[:ssh_username] @ssh_password_sha256 = @init_data[:ssh_password_sha256] @http_username = @init_data[:http_username] @http_password_sha256 = @init_data[:http_password_sha256] @http_downloads_enabled = @init_data[:http_downloads_enabled] @protocol = @init_data[:protocol] @port = @init_data[:port] @context = @init_data[:context] @no_authentication_required = @init_data[:no_authentication_required] @certificate_required = @init_data[:certificate_required] @username_password_required = @init_data[:username_password_required] @certificate = @init_data[:certificate] @http_url = @init_data[:http_url] @failover_point_url = @init_data[:failover_point_url] @port = @init_data[:ssh_password] # if we mount for fileservice, where's the mountpoint? @mountpoint = DEFAULT_MOUNTPOINT_DIR + "#{DEFAULT_MOUNTPOINT_PREFIX}#{@id}" end |
Instance Attribute Details
#certificate ⇒ String (readonly)
Returns the name of the cert. used for http cert. auth.
245 246 247 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 245 def certificate @certificate end |
#certificate_required ⇒ Boolean (readonly)
Returns do http downloads use cert. authentication?.
233 234 235 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 233 def certificate_required @certificate_required end |
#connection_type ⇒ String (readonly)
Returns Protocol for fileservice access (e.g. AFP, SMB).
192 193 194 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 192 def connection_type @connection_type end |
#context ⇒ String (readonly)
Returns the “context” for http downloads (what goes after the hostname part of the URL).
227 228 229 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 227 def context @context end |
#enable_load_balancing ⇒ String (readonly)
Returns load balanacing enabled?.
181 182 183 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 181 def enable_load_balancing @enable_load_balancing end |
#failover_point ⇒ Integer (readonly)
Returns the id of the DP to use for failover.
184 185 186 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 184 def failover_point @failover_point end |
#failover_point_url ⇒ String (readonly)
Returns the URL to use if this one doesn’t work.
251 252 253 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 251 def failover_point_url @failover_point_url end |
#http_downloads_enabled ⇒ Boolean (readonly)
Returns are http downloads available from this DP?.
218 219 220 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 218 def http_downloads_enabled @http_downloads_enabled end |
#http_password_sha256 ⇒ String (readonly)
Returns the password for http downloads, if needed, as a SHA256 digest.
242 243 244 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 242 def http_password_sha256 @http_password_sha256 end |
#http_url ⇒ String (readonly)
Returns the URL for http downloads.
248 249 250 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 248 def http_url @http_url end |
#http_username ⇒ String (readonly)
Returns the username to use for http downloads if needed for user/pw auth.
239 240 241 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 239 def http_username @http_username end |
#ip_address ⇒ String (readonly) Also known as: hostname
Returns the hostname of this DP.
175 176 177 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 175 def ip_address @ip_address end |
#is_master ⇒ Boolean (readonly) Also known as: master?
Returns is this the master DP?.
187 188 189 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 187 def is_master @is_master end |
#local_path ⇒ String (readonly)
Returns the local path on the server to the distribution point directory.
178 179 180 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 178 def local_path @local_path end |
#no_authentication_required ⇒ Boolean (readonly)
Returns do http downloads work without auth?.
230 231 232 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 230 def no_authentication_required @no_authentication_required end |
#port ⇒ Integer (readonly)
Returns the port for http access.
224 225 226 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 224 def port @port end |
#protocol ⇒ String (readonly)
Returns the protocol to use for http downloads (http/https).
221 222 223 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 221 def protocol @protocol end |
#read_only_password_sha256 ⇒ String (readonly)
Returns read-only password as a SHA256 digest.
210 211 212 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 210 def read_only_password_sha256 @read_only_password_sha256 end |
#read_only_username ⇒ String (readonly)
Returns read-only username for fileservice.
207 208 209 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 207 def read_only_username @read_only_username end |
#read_write_password_sha256 ⇒ String (readonly)
Returns the read-write password as a SHA256 digest.
204 205 206 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 204 def read_write_password_sha256 @read_write_password_sha256 end |
#read_write_username ⇒ String (readonly)
Returns the read-write username for fileservice access.
201 202 203 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 201 def read_write_username @read_write_username end |
#share_name ⇒ String (readonly)
Returns the name of the fileservice sharepoint.
198 199 200 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 198 def share_name @share_name end |
#share_port ⇒ Integer (readonly)
Returns the port for fileservice access.
195 196 197 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 195 def share_port @share_port end |
#ssh_password_sha256 ⇒ String (readonly)
Returns the ssh password as a SHA256 digest.
259 260 261 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 259 def ssh_password_sha256 @ssh_password_sha256 end |
#ssh_username ⇒ String (readonly)
Returns ssh username.
256 257 258 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 256 def ssh_username @ssh_username end |
#username_password_required ⇒ Boolean (readonly)
Returns do http downloads use user/pw auth?.
236 237 238 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 236 def username_password_required @username_password_required end |
#workgroup_or_domain ⇒ String (readonly)
Returns work group or domain for SMB.
213 214 215 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 213 def workgroup_or_domain @workgroup_or_domain end |
Class Method Details
.master_distribution_point(refresh = false, default: nil, api: nil, cnx: Jamf.cnx) ⇒ Jamf::DistributionPoint
Get the DistributionPoint instance for the master distribution point.
If the Cloud Dist Point is master, then the classic API has no way to know that or access it. In that case you can provide the ‘default:’ parameter. Give it the name or id of any dist. point to be used instead, or give it :random to randomly choose one.
If there are no fileshare dist points defined (the cloud is the only one) then this whole class can’t really be used.
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 107 def self.master_distribution_point(refresh = false, default: nil, api: nil, cnx: Jamf.cnx) cnx = api if api all_ids(refresh, cnx: cnx).each do |dp_id| dp = fetch id: dp_id, cnx: cnx return dp if dp.master? end case default when :random fetch id: all_ids.sample, cnx: cnx when nil raise Jamf::NoSuchItemError, 'No Master FileShare Distribtion Point. Use the default: parameter if needed.' else fetch default, cnx: cnx end end |
.my_distribution_point(refresh = false, default: :master, api: nil, cnx: Jamf.cnx) ⇒ Jamf::DistributionPoint
Get the DistributionPoint instance for the machine running this code, based on its IP address. If none is defined for this IP address, use the name or id provided as default. If no default: is provided, the master dp is used. If no master dp available (meaning its the cloud dp) then use a randomly chosen dp.
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 142 def self.my_distribution_point(refresh = false, default: :master, api: nil, cnx: Jamf.cnx) cnx = api if api @my_distribution_point = nil if refresh return @my_distribution_point if @my_distribution_point my_net_seg_id = Jamf::NetworkSegment.my_network_segment refresh, cnx: cnx if my_net_seg_id my_net_seg = Jamf::NetworkSegment.fetch id: my_net_seg_id, cnx: cnx my_dp_name = my_net_seg.distribution_point @my_distribution_point = fetch name: my_dp_name, cnx: cnx if my_dp_name end # if my_net_seg_id return @my_distribution_point if @my_distribution_point @my_distribution_point = case default when String fetch name: default, cnx: cnx when Integer fetch id: default, cnx: cnx when :master master_distribution_point refresh, default: :random, cnx: cnx when :random fetch id: all_ids(refresh).sample, cnx: cnx end end |
Instance Method Details
#check_pw(_user = nil, _pw = nil) ⇒ TrueClass
The API no longer sends SHA256 hashed password data, and instead only has a string of asterisks, meaning we can no longer use it to validate passwords before attempting to use them. Instead, the processes that use them, e.g. mounting a Dist. Point, will fail on their own if the pw is not valid.
This method remains defined for backward-compatibility with any existing code that calls it. but it will always return true. It will be removed in a future version
Returns Allow the process calling this to continue.
317 318 319 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 317 def check_pw(_user = nil, _pw = nil) true end |
#mount(pw = nil, access = :ro) ⇒ Pathname
Mount this distribution point locally.
382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 382 def mount(pw = nil, access = :ro) return @mountpoint if mounted? access = :ro unless access == :rw password = if pw == :prompt JSS.prompt_for_password "Enter the password for the #{access} user '#{access == :ro ? @read_only_username : @read_write_username}':" elsif pw.is_a?(Symbol) && pw.to_s.start_with?('stdin') pw.to_s =~ /^stdin(\d+)$/ line = Regexp.last_match(1) line ||= 2 JSS.stdin line else pw end username = access == :ro ? @read_only_username : @read_write_username safe_pw = CGI.escape password.to_s @mount_url = "#{@connection_type.downcase}://#{username}:#{safe_pw}@#{@ip_address}/#{@share_name}" @mnt_cmd = case @connection_type.downcase when 'smb' then '/sbin/mount_smbfs' when 'afp' then '/sbin/mount_afp' else raise "Can't mount distribution point #{@name}: no known connection type." end @mountpoint.mkpath mount_out = `#{@mnt_cmd} -o '#{MOUNT_OPTIONS}' '#{@mount_url}' '#{@mountpoint}' 2>&1` if ($CHILD_STATUS.exitstatus == 0) && @mountpoint.mountpoint? # if system @mnt_cmd.to_s, *['-o', MOUNT_OPTIONS, @mount_url, @mountpoint.to_s] @mounted = access else @mountpoint.rmdir if @mountpoint.directory? @mounted = nil raise Jamf::FileServiceError, "Can't mount #{@ip_address}: #{mount_out}" end @mountpoint end |
#mounted? ⇒ Boolean
Is this thing mounted right now?
446 447 448 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 446 def mounted? @mountpoint.directory? && @mountpoint.mountpoint? end |
#reachable_for_download?(pw = '', check_http = true) ⇒ FalseClass, Symbol
Check to see if this dist point is reachable for downloads (read-only) via either http, if available, or filesharing.
334 335 336 337 338 339 340 341 342 343 344 345 346 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 334 def reachable_for_download?(pw = '', check_http = true) return :http if check_http && http_reachable?(pw) return :mountable if mounted? begin mount pw, :ro :mountable rescue false ensure unmount end end |
#reachable_for_upload?(pw) ⇒ FalseClass, Symbol
Check to see if this dist point is reachable for uploads (read-write) via filesharing.
355 356 357 358 359 360 361 362 363 364 365 366 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 355 def reachable_for_upload?(pw) return :mountable if mounted? begin mount pw, :rw :mountable rescue false ensure unmount end end |
#unmount ⇒ void Also known as: umount
This method returns an undefined value.
Unmount the distribution point.
Does nothing if it wasn’t mounted with #mount.
429 430 431 432 433 434 435 436 437 438 439 440 |
# File 'lib/jamf/api/classic/api_objects/distribution_point.rb', line 429 def unmount return nil unless mounted? if system "/sbin/umount '#{@mountpoint}'" sleep 1 # the umount takes time. @mountpoint.rmdir if @mountpoint.directory? && !@mountpoint.mountpoint? @mounted = false else raise Jamf::FileServiceError, "There was a problem unmounting #{@mountpoint}" end nil end |