jss-api 0.5.8 → 0.6.1

data/lib/jss-api/api_connection.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in
@@ -63,8 +63,16 @@ module JSS
     #####################################
 
     ### The base API path in the jss URL
-    RSRC = "JSSResource"
-
+    RSRC_BASE = "JSSResource"
+    
+    ### A url path to load to see if there's an API available at a host.
+    ### This just loads the API resource docs page
+    TEST_PATH = "api"
+    
+    ### If the test path loads correctly from a casper server, it'll contain
+    ### this text
+    TEST_CONTENT = "<title>JSS REST API Resource Documentation</title>"
+    
     ### The Default port
     HTTP_PORT = 9006
 
@@ -97,6 +105,9 @@ module JSS
     ### @return [JSS::Server] the details of the JSS to which we're connected.
     attr_reader :server
 
+    ### @return [String] the hostname of the JSS to which we're connected.
+    attr_reader :server_host
+    
     #####################################
     ### Constructor
     #####################################
@@ -122,6 +133,8 @@ module JSS
     ###
     ### @option args :port[Integer] the port number to connect with, defaults to 8443
     ###
+    ### @option args :use_ssl[Boolean] should the connection be made over SSL? Defaults to true.
+    ###
     ### @option args :verify_cert[Boolean] should HTTPS SSL certificates be verified. Defaults to true.
     ###   If your connection raises RestClient::SSLCertificateNotVerified, and you don't care about the
     ###   validity of the SSL cert. just set this explicitly to false.
@@ -141,7 +154,11 @@ module JSS
     ### @return [true]
     ###
     def connect (args = {})
-
+      
+      # the server, if not specified, might come from a couple places.
+      # see #hostname
+      args[:server] ||= hostname
+      
       # settings from config if they aren't in the args
       args[:server] ||= JSS::CONFIG.api_server_name
       args[:port] ||= JSS::CONFIG.api_server_port
@@ -155,7 +172,10 @@ module JSS
         # set it from the prefs
         args[:verify_cert] = JSS::CONFIG.api_verify_cert
       end
-
+      
+      # settings from client jamf plist if needed
+      args[:port] ||=  JSS::Client.jss_port
+      
       # default settings if needed
       args[:port] ||= SSL_PORT
       args[:timeout] ||= DFT_TIMEOUT
@@ -173,13 +193,18 @@ module JSS
       raise JSS::MissingDataError, "No JSS :user specified, or in configuration." unless args[:user]
       raise JSS::MissingDataError, "Missing :pw for user '#{args[:user]}'" unless args[:pw]
       
-      # ssl or not?
-      ssl = SSL_PORT == args[:port].to_i ? "s" : ''
-      @rest_url = URI::encode "http#{ssl}://#{args[:server]}:#{args[:port]}/#{RSRC}"
+      # we're using ssl if 1) args[:use_ssl] is anything but false
+      # or 2) the port is the default casper ssl port.
+      args[:use_ssl] = (not args[:use_ssl] == false) or (args[:port] == SSL_PORT)
+      
+      # and here's the URL
+      ssl = args[:use_ssl] ? "s" : ''
+      @rest_url = URI::encode "http#{ssl}://#{args[:server]}:#{args[:port]}/#{RSRC_BASE}"
+
 
       # prep the args for passing to RestClient::Resource
-      # if verify_cert is nil (unset) or non-false, then we will verify
-      args[:verify_ssl] =  (args[:verify_cert].nil? or args[:verify_cert]) ? OpenSSL::SSL::VERIFY_PEER :  OpenSSL::SSL::VERIFY_NONE
+      # if verify_cert is anything but false, we will verify
+      args[:verify_ssl] =  (args[:verify_cert] == false) ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER
       
       args[:password] = if args[:pw] == :prompt
         JSS.prompt_for_password "Enter the password for JSS user #{args[:user]}@#{args[:server]}:"
@@ -192,12 +217,11 @@ module JSS
         args[:pw]
       end
       
-      
-      
       # heres our connection
       @cnx = RestClient::Resource.new("#{@rest_url}", args)
 
       @jss_user = args[:user]
+      @server_host = args[:server]
       @connected = true
       @server = JSS::Server.new
 
@@ -205,7 +229,7 @@ module JSS
         raise JSS::UnsupportedError, "Your JSS Server version, #{@server.raw_version}, is to low. Must be #{JSS::MINIMUM_SERVER_VERSION} or higher."
       end
 
-      return true
+      return @connected ? @server_host : nil
     end # connect
 
     ###
@@ -240,6 +264,7 @@ module JSS
     def disconnect
       @jss_user = nil
       @rest_url = nil
+      @server_host = nil
       @cnx = nil
       @connected = false
     end # disconnect
@@ -308,7 +333,6 @@ module JSS
       @cnx[rsrc].post xml, :content_type => 'text/xml', :accept => :json
     end #post_rsrc
 
-    ###
     ### Delete a resource from the JSS
     ###
     ### @param rsrc[String] the resource to create, the URL part after 'JSSResource/'
@@ -323,7 +347,46 @@ module JSS
       @cnx[rsrc].delete
 
     end #delete_rsrc
-
+    
+    
+    ### Test that a given hostname & port is a JSS API server
+    ###
+    ### @param server[String] The hostname to test, 
+    ###
+    ### @param port[Integer] The port to try connecting on
+    ###
+    ### @return [Boolean] does the server host a JSS API?
+    ###
+    def valid_server? (server, port = SSL_PORT)
+      # try ssl first
+      begin
+        return true if open("https://#{server}:#{port}/#{TEST_PATH}", ssl_verify_mode: OpenSSL::SSL::VERIFY_NONE).read.include? TEST_CONTENT
+      rescue
+        # then regular http
+        begin 
+          return true if open("http://#{server}:#{port}/#{TEST_PATH}").read.include? TEST_CONTENT
+        rescue
+          # any errors = no API
+          return false
+        end # begin
+      end #begin
+      # if we're here, no API
+      return false
+    end
+    
+    ### The server to which we are connected, or will 
+    ### try connecting to if none is specified with the
+    ### call to #connect
+    ###
+    ### @return [String] the hostname of the server
+    ###
+    def hostname
+      return @server_host if @server_host
+      srvr = JSS::CONFIG.api_server_name
+      srvr ||= JSS::Client.jss_server
+      return srvr
+    end
+    
     ### aliases
     alias connected? connected
 

data/lib/jss-api/api_object.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/advanced_search.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/advanced_search/advanced_computer_search.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/advanced_search/advanced_mobile_device_search.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/advanced_search/advanced_user_search.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/building.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/category.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/computer.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/creatable.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/criteriable.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/criteriable/criteria.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/criteriable/criterion.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/department.rb

@@ -1,4 +1,4 @@
-### Copyright 2014 Pixar
+### Copyright 2016 Pixar
 ###  
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in

data/lib/jss-api/api_object/distribution_point.rb

@@ -1,25 +1,25 @@
-### Copyright 2014 Pixar
-###  
+### Copyright 2016 Pixar
+###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
 ###    with the following modification; you may not use this file except in
 ###    compliance with the Apache License and the following modification to it:
 ###    Section 6. Trademarks. is deleted and replaced with:
-###  
+###
 ###    6. Trademarks. This License does not grant permission to use the trade
 ###       names, trademarks, service marks, or product names of the Licensor
 ###       and its affiliates, except as required to comply with Section 4(c) of
 ###       the License and to reproduce the content of the NOTICE file.
-###  
+###
 ###    You may obtain a copy of the Apache License at
-###  
+###
 ###        http://www.apache.org/licenses/LICENSE-2.0
-###  
+###
 ###    Unless required by applicable law or agreed to in writing, software
 ###    distributed under the Apache License with the above modification is
 ###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ###    KIND, either express or implied. See the Apache License for the specific
 ###    language governing permissions and limitations under the Apache License.
-### 
+###
 ###
 
 ###
@@ -120,7 +120,7 @@ module JSS
         when 1
           self.new :id => self.all_ids[0]
         else
-          self.new :master
+          self.new :id => :master
         end
     end
 
@@ -244,7 +244,7 @@ module JSS
     ###
     ### You can also do this more easily by calling JSS.master_distribution_point
     ###
-    def initialize(args)
+    def initialize(args = {})
 
       @init_data = nil
 
@@ -343,6 +343,75 @@ module JSS
       sha256 == Digest::SHA2.new(256).update(pw).to_s
     end
 
+    ### Check to see if this dist point is reachable for downloads (read-only)
+    ### via either http, if available, or filesharing.
+    ###
+    ### @param pw[String] the read-only password to use for checking the connection
+    ###   If http downloads are enabled, and no http password is required
+    ###   this can be omitted.
+    ###
+    ### @param check_http[Boolean] should we try the http download first, if enabled?
+    ###   If you're intentionally using the ro password for filesharing, and want to check
+    ###   only filesharing, then set this to false.
+    ###
+    ### @return [FalseClass, Symbol] false if not reachable, otherwise :http or :mountable
+    ###
+    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 = "#{URI.escape @http_username,reserved_chars}:#{URI.escape ro_pw, reserved_chars}@"
+          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
+
+    ### Check to see if this dist point is reachable for uploads (read-write)
+    ### via filesharing.
+    ###
+    ### @param pw[String] the read-write password to use for checking the connection
+    ###
+    ### @return [FalseClass, Symbol] false if not reachable, otherwise :mountable
+    ###
+    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
 
 
     ###
@@ -350,19 +419,19 @@ module JSS
     ###
     ### @param pw[String,Symbol] the read-only or read-write password for this DistributionPoint
     ###   If :prompt, the user is promted on the commandline to enter the password for the :user.
-    ###   If :stdin#, the password is read from a line of std in represented by the digit at #, 
-    ###   so :stdin3 reads the passwd from the third line of standard input. defaults to line 2, 
+    ###   If :stdin#, the password is read from a line of std in represented by the digits at #,
+    ###   so :stdin3 reads the passwd from the third line of standard input. defaults to line 2,
     ###   if no digit is supplied. see {JSS.stdin}
     ###
     ### @param access[Symbol] how to mount the DistributionPoint, and which password to expect.
-    ###  :ro = read-only, :rw (or anything else) = read-write
+    ###  :ro (or anything else) = read-only, :rw = read-write
     ###
     ### @return [Pathname] the mountpoint.
     ###
-    def mount(pw = nil, access = :ro1)
+    def mount(pw = nil, access = :ro)
       return @mountpoint if mounted?
-      access = :rw unless access == :ro
-      
+      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')
@@ -373,7 +442,7 @@ module JSS
       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"
@@ -393,13 +462,14 @@ module JSS
 
       @mountpoint.mkpath
 
-      #if system "#{@mnt_cmd} -o '#{MOUNT_OPTIONS}' '#{@mount_url}' '#{@mountpoint}'"
-      if system @mnt_cmd.to_s, *['-o', MOUNT_OPTIONS, @mount_url, @mountpoint.to_s]
+      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, "There was a problem mounting #{@ip_address}"
+        raise JSS::FileServiceError, "Can't mount #{@ip_address}: #{mount_out}"
       end
       return @mountpoint
     end # mount
@@ -421,7 +491,7 @@ module JSS
       end
       nil
     end # unmount
-    
+
 
     ###
     ### Is this thing mounted right now?
@@ -431,8 +501,8 @@ module JSS
     def mounted?
       @mountpoint.directory? and  @mountpoint.mountpoint?
     end
-    
-    
+
+
     #### aliases
     alias hostname ip_address
     alias umount unmount