Class: JSS::DistributionPoint
- Defined in:
- lib/jss/api_object/distribution_point.rb,
lib/jss.rb
Overview
A 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 JSS::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 JSS::DistributionPoint object for your local IP address.
Once you have an instance of JSS::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.
Constant Summary collapse
- RSRC_BASE =
The base for REST resources of this class
"distributionpoints"
- 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
- VALID_DATA_KEYS =
these keys, as well as :id and :name, are present in valid API JSON data for this class
[:read_only_username, :ssh_username, :is_master ]
- MOUNT_OPTIONS =
what are the mount options? these are comma-separated, and are passed with -o
'nobrowse'
- EMPTY_PW_256 =
An empty SHA256 digest
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
- DEFAULT_MOUNTPOINT_DIR =
Set default local mount for distribution point
Pathname.new "/tmp"
- DEFAULT_MOUNTPOINT_PREFIX =
"CasperDistribution-id"
- 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
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, api: JSS.api) ⇒ JSS::DistributionPoint
Get the DistributionPoint instance for the master distribution point in the JSS.
-
.my_distribution_point(refresh = false, api: JSS.api) ⇒ JSS::DistributionPoint
Get the DistributionPoint instance for the machine running this code, based on its IP address.
Instance Method Summary collapse
-
#check_pw(user, pw) ⇒ Boolean, Nil
Check the validity of a password.
-
#initialize(args = {}) ⇒ DistributionPoint
constructor
As well as the standard :id, :name, and :data, you can instantiate this class with :id => :master, in which case you’ll get the Master Distribution Point as defined in the JSS.
-
#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
As well as the standard :id, :name, and :data, you can instantiate this class with :id => :master, in which case you’ll get the Master Distribution Point as defined in the JSS. An error will be raised if one hasn’t been defined.
You can also do this more easily by calling JSS.master_distribution_point
222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 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 291 292 293 294 295 296 297 |
# File 'lib/jss/api_object/distribution_point.rb', line 222 def initialize(args = {}) args[:api] ||= JSS.api @api = args[:api] @init_data = nil ### looking for master? if args[:id] == :master self.class.all_ids(api: @api).each do |id| @init_data = @api.get_rsrc("#{RSRC_BASE}/id/#{id}")[RSRC_OBJECT_KEY] if @init_data[:is_master] @id = @init_data[:id] @name = @init_data[:name] break end # if data is master @init_data = nil end # each id end # if args is master if @init_data.nil? super(args) end @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] ### Note, as of Casper 9.3: ### :management_password_md5=>"xxxxx" ### and ### :management_password_sha256=> "xxxxxxxxxx" ### Are the read/write password ### ### An empty passwd is ### MD5 = d41d8cd98f00b204e9800998ecf8427e ### SHA256 = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ### ### Seemms the read-only pw isn't available in the API ### if we mount for fileservice, where's the mountpoint? @mountpoint = Pathname.new "/#{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.
199 200 201 |
# File 'lib/jss/api_object/distribution_point.rb', line 199 def certificate @certificate end |
#certificate_required ⇒ Boolean (readonly)
Returns do http downloads use cert. authentication?.
187 188 189 |
# File 'lib/jss/api_object/distribution_point.rb', line 187 def certificate_required @certificate_required end |
#connection_type ⇒ String (readonly)
Returns Protocol for fileservice access (e.g. AFP, SMB).
146 147 148 |
# File 'lib/jss/api_object/distribution_point.rb', line 146 def connection_type @connection_type end |
#context ⇒ String (readonly)
Returns the “context” for http downloads (what goes after the hostname part of the URL).
181 182 183 |
# File 'lib/jss/api_object/distribution_point.rb', line 181 def context @context end |
#enable_load_balancing ⇒ String (readonly)
Returns load balanacing enabled?.
135 136 137 |
# File 'lib/jss/api_object/distribution_point.rb', line 135 def enable_load_balancing @enable_load_balancing end |
#failover_point ⇒ Integer (readonly)
Returns the id of the DP to use for failover.
138 139 140 |
# File 'lib/jss/api_object/distribution_point.rb', line 138 def failover_point @failover_point end |
#failover_point_url ⇒ String (readonly)
Returns the URL to use if this one doesn’t work.
205 206 207 |
# File 'lib/jss/api_object/distribution_point.rb', line 205 def failover_point_url @failover_point_url end |
#http_downloads_enabled ⇒ Boolean (readonly)
Returns are http downloads available from this DP?.
172 173 174 |
# File 'lib/jss/api_object/distribution_point.rb', line 172 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.
196 197 198 |
# File 'lib/jss/api_object/distribution_point.rb', line 196 def http_password_sha256 @http_password_sha256 end |
#http_url ⇒ String (readonly)
Returns the URL for http downloads.
202 203 204 |
# File 'lib/jss/api_object/distribution_point.rb', line 202 def http_url @http_url end |
#http_username ⇒ String (readonly)
Returns the username to use for http downloads if needed for user/pw auth.
193 194 195 |
# File 'lib/jss/api_object/distribution_point.rb', line 193 def http_username @http_username end |
#ip_address ⇒ String (readonly) Also known as: hostname
Returns the hostname of this DP.
129 130 131 |
# File 'lib/jss/api_object/distribution_point.rb', line 129 def ip_address @ip_address end |
#is_master ⇒ Boolean (readonly)
Returns is this the master DP?.
141 142 143 |
# File 'lib/jss/api_object/distribution_point.rb', line 141 def is_master @is_master end |
#local_path ⇒ String (readonly)
Returns the local path on the server to the distribution point directory.
132 133 134 |
# File 'lib/jss/api_object/distribution_point.rb', line 132 def local_path @local_path end |
#no_authentication_required ⇒ Boolean (readonly)
Returns do http downloads work without auth?.
184 185 186 |
# File 'lib/jss/api_object/distribution_point.rb', line 184 def no_authentication_required @no_authentication_required end |
#port ⇒ Integer (readonly)
Returns the port for http access.
178 179 180 |
# File 'lib/jss/api_object/distribution_point.rb', line 178 def port @port end |
#protocol ⇒ String (readonly)
Returns the protocol to use for http downloads (http/https).
175 176 177 |
# File 'lib/jss/api_object/distribution_point.rb', line 175 def protocol @protocol end |
#read_only_password_sha256 ⇒ String (readonly)
Returns read-only password as a SHA256 digest.
164 165 166 |
# File 'lib/jss/api_object/distribution_point.rb', line 164 def read_only_password_sha256 @read_only_password_sha256 end |
#read_only_username ⇒ String (readonly)
Returns read-only username for fileservice.
161 162 163 |
# File 'lib/jss/api_object/distribution_point.rb', line 161 def read_only_username @read_only_username end |
#read_write_password_sha256 ⇒ String (readonly)
Returns the read-write password as a SHA256 digest.
158 159 160 |
# File 'lib/jss/api_object/distribution_point.rb', line 158 def read_write_password_sha256 @read_write_password_sha256 end |
#read_write_username ⇒ String (readonly)
Returns the read-write username for fileservice access.
155 156 157 |
# File 'lib/jss/api_object/distribution_point.rb', line 155 def read_write_username @read_write_username end |
#share_name ⇒ String (readonly)
Returns the name of the fileservice sharepoint.
152 153 154 |
# File 'lib/jss/api_object/distribution_point.rb', line 152 def share_name @share_name end |
#share_port ⇒ Integer (readonly)
Returns the port for fileservice access.
149 150 151 |
# File 'lib/jss/api_object/distribution_point.rb', line 149 def share_port @share_port end |
#ssh_password_sha256 ⇒ String (readonly)
Returns the ssh password as a SHA256 digest.
213 214 215 |
# File 'lib/jss/api_object/distribution_point.rb', line 213 def ssh_password_sha256 @ssh_password_sha256 end |
#ssh_username ⇒ String (readonly)
Returns ssh username.
210 211 212 |
# File 'lib/jss/api_object/distribution_point.rb', line 210 def ssh_username @ssh_username end |
#username_password_required ⇒ Boolean (readonly)
Returns do http downloads use user/pw auth?.
190 191 192 |
# File 'lib/jss/api_object/distribution_point.rb', line 190 def username_password_required @username_password_required end |
#workgroup_or_domain ⇒ String (readonly)
Returns work group or domain for SMB.
167 168 169 |
# File 'lib/jss/api_object/distribution_point.rb', line 167 def workgroup_or_domain @workgroup_or_domain end |
Class Method Details
.master_distribution_point(refresh = false, api: JSS.api) ⇒ JSS::DistributionPoint
Get the DistributionPoint instance for the master distribution point in the JSS. If there’s only one in the JSS, return it even if not marked as master.
106 107 108 |
# File 'lib/jss/api_object/distribution_point.rb', line 106 def self.master_distribution_point(refresh = false, api: JSS.api) api.master_distribution_point refresh end |
.my_distribution_point(refresh = false, api: JSS.api) ⇒ JSS::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 result of master_distribution_point
120 121 122 |
# File 'lib/jss/api_object/distribution_point.rb', line 120 def self.my_distribution_point(refresh = false, api: JSS.api) api.my_distribution_point refresh end |
Instance Method Details
#check_pw(user, pw) ⇒ Boolean, Nil
Check the validity of a password.
309 310 311 312 313 314 315 316 317 318 319 320 321 |
# File 'lib/jss/api_object/distribution_point.rb', line 309 def check_pw(user, pw) raise JSS::InvalidDataError, "The first parameter must be one of :ro, :rw, :ssh, :http" unless [:ro, :rw, :ssh, :http].include? user sha256 = case user when :rw then @read_write_password_sha256 when :ro then @read_only_password_sha256 when :http then @http_password_sha256 when :ssh then @ssh_password_sha256 end # case return nil if sha256 == EMPTY_PW_256 sha256 == Digest::SHA2.new(256).update(pw).to_s end |
#mount(pw = nil, access = :ro) ⇒ Pathname
Mount this distribution point locally.
410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 |
# File 'lib/jss/api_object/distribution_point.rb', line 410 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) and pw.to_s.start_with?('stdin') pw.to_s =~ /^stdin(\d+)$/ line = $1 line ||= 2 JSS.stdin line else pw end pwok = check_pw(access, password) unless pwok msg = pwok.nil? ? "No #{access} password set in the JSS" : "Incorrect password for #{access} account" raise JSS::InvalidDataError, msg end username = access == :ro ? @read_only_username : @read_write_username safe_pw = CGI.escape password @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 $?.exitstatus == 0 and @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 JSS::FileServiceError, "Can't mount #{@ip_address}: #{mount_out}" end return @mountpoint end |
#mounted? ⇒ Boolean
Is this thing mounted right now?
481 482 483 |
# File 'lib/jss/api_object/distribution_point.rb', line 481 def mounted? @mountpoint.directory? and @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.
336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 |
# File 'lib/jss/api_object/distribution_point.rb', line 336 def reachable_for_download? (pw = '', check_http = true) pw ||= '' http_checked = "" if check_http && http_downloads_enabled if @username_password_required # we don't check the pw here, because if the connection fails, we'll # drop down below to try the password for mounting. # we'll escape all the chars that aren't unreserved #reserved_chars = Regexp.new("[^#{URI::REGEXP::PATTERN::UNRESERVED}]") user_pass = "#{CGI.escape @http_username}:#{CGI.escape ro_pw}@" url = @http_url.sub "://#{@ip_address}", "://#{user_pass}#{@ip_address}" else url = @http_url end begin open(url).read return :http rescue http_checked = "http and " end end # if check_http && http_downloads_enabled return :mountable if mounted? return false unless check_pw :ro , pw begin mount pw, :ro return :mountable rescue return 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.
380 381 382 383 384 385 386 387 388 389 390 391 |
# File 'lib/jss/api_object/distribution_point.rb', line 380 def reachable_for_upload? (pw) return :mountable if mounted? return false unless check_pw :rw , pw begin mount pw, :rw return :mountable rescue return 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.
463 464 465 466 467 468 469 470 471 472 473 |
# File 'lib/jss/api_object/distribution_point.rb', line 463 def unmount return nil unless mounted? if system "/sbin/umount '#{@mountpoint}'" sleep 1 # the umount takes time. @mountpoint.rmdir if @mountpoint.directory? and (not @mountpoint.mountpoint?) @mounted = false else raise JSS::FileServiceError ,"There was a problem unmounting #{@mountpoint}" end nil end |