Class: JSS::APIConnection

Inherits:
Object show all
Defined in:
lib/jss/api_connection.rb,
lib/jss.rb

Overview

Instances of this class represent a REST connection to a JSS API.

For most cases, a single connection to a single JSS is all you need, and this is ruby-jss’s default behavior.

If needed, multiple connections can be made and used sequentially or simultaneously.

Using the default connection

When ruby-jss is loaded, a not-yet-connected default instance of JSS::APIConnection is created and stored in the constant JSS::API. This connection is used as the initial ‘active connection’ (see below) so all methods that make API calls will use it by default. For most uses, where you’re only going to be working with one connection to one JSS, the default connection is all you need.

Before using it you must call its #connect method, passing in appropriate connection details and credentials.

Example:

require 'ruby-jss'
JSS.api.connect server: 'server.address.edu', user: 'jss-api-user', pw: :prompt
# (see {JSS::APIConnection#connect} for all the connection options)

a_phone = JSS::MobileDevice.fetch id: 8743

# the mobile device was fetched through the default connection

Using Multiple Simultaneous Connections

Sometimes you need to connect simultaneously to more than one JSS. or to the same JSS with different credentials. ruby-jss allows you to create as many connections as needed, and gives you three ways to use them:

  1. Making a connection ‘active’, after which API calls go thru it automatically

    Example:

    a_computer = JSS::Computer.fetch id: 1234

# the JSS::Computer with id 1234 is fetched from the active connection
# and stored in the variable 'a_computer'

    NOTE: When ruby-jss is first loaded, the default connection (see above) is the active connection.

  2. Passing an APIConnection instance to methods that use the API

    Example:

    a_computer = JSS::Computer.fetch id: 1234, api: production_api

# the JSS::Computer with id 1234 is fetched from the connection
# stored in the variable 'production_api'. The computer is
# then stored in the variable 'a_computer'

  3. Using the APIConnection instance itself to make API calls.

    Example:

    a_computer = production_api.fetch :Computer, id: 1234

# the JSS::Computer with id 1234 is fetched from the connection
# stored in the variable 'production_api'. The computer is
# then stored in the variable 'a_computer'

See below for more details about the ways to use multiple connections.

NOTE: Objects retrieved or created through an APIConnection store an internal reference to that APIConnection and use that when they make other API calls, thus ensuring data consistency when using multiple connections.

Similiarly, the data caches used by APIObject list methods (e.g. JSS::Computer.all, .all_names, and so on) are stored in the APIConnection instance through which they were read, so they won’t be incorrect when you use multiple connections.

Making new APIConnection instances

New connections can be created using the standard ruby ‘new’ method.

If you provide connection details when calling ‘new’, they will be passed to the #connect method immediately. Otherwise you can call #connect later.

production_api = JSS::APIConnection.new(
  name: 'prod',
  server: 'prodserver.address.org',
  user: 'produser',
  pw: :prompt
)

# the new connection is now stored in the variable 'production_api'.

Using the ‘Active’ Connection

While multiple connection instances can be created, only one at a time is ‘the active connection’ and all APIObject-based access methods in ruby-jss will use it automatically. When ruby-jss is loaded, the default connection (see above) is the active connection.

To use the active connection, just call a method on an APIObject subclass that uses the API.

For example, the various list methods:

all_computer_sns = JSS::Computer.all_serial_numbers

# the list of all computer serial numbers is read from the active
# connection and stored in all_computer_sns

Fetching an object from the API:

victim_md = JSS::MobileDevice.fetch id: 832

# the variable 'victim_md' now contains a JSS::MobileDevice queried
# through the active connection.

The currently-active connection instance is available from the ‘JSS.api` method.

Making a Connection Active

Only one connection is ‘active’ at a time and the currently active one is returned when you call ‘JSS.api` or its alias `JSS.active_connection`

To activate another connection just pass it to the JSS.use_api method like so:

JSS.use_api production_api
# the connection we stored in 'production_api' is now active

To re-activate to the default connection, just call

JSS.use_default_connection

Connection Names:

As seen in the example above, you can provide a ‘name:’ parameter (a String or a Symbol) when creating a new connection. The name can be used later to identify connection objects.

If you don’t provide one, the name is ‘:disconnected’ until you connect, and then ‘user@server:port’ after connecting.

The name of the default connection is always :default

To see the name of the currently active connection, just use ‘JSS.api.name`

JSS.use_api production_api
JSS.api.name  # => 'prod'

JSS.use_default_connection
JSS.api.name  # => :default

Creating, Storing and Activating a connection in one step

Both of the above steps (creating/storing a connection, and making it active) can be performed in one step using the ‘JSS.new_api_connection` method, which creates a new APIConnection, makes it the active connection, and returns it.

 production_api2 = JSS.new_api_connection(
   name: 'prod2',
   server: 'prodserver.address.org',
   user: 'produser',
   pw: :prompt
 )

JSS.api.name  # => 'prod2'

Passing an APIConnection object to API-related methods

All methods that use the API can take an ‘api:’ parameter which contains an APIConnection object. When provided, that APIconnection is used rather than the active connection.

For example:

prod2_computer_sns = JSS::Computer.all_serial_numbers, api: production_api2

# the list of all computer serial numbers is read from the connection in
# the variable 'production_api2' and stored in 'prod2_computer_sns'

prod2_victim_md = JSS::MobileDevice.fetch id: 832, api: production_api2

# the variable 'prod2_victim_md' now contains a JSS::MobileDevice queried
# through the connection 'production_api2'.

Using the APIConnection itself to make API calls.

Rather than passing an APIConnection into another method, you can call similar methods on the connection itself. For example, these two calls have the same result as the two examples above:

prod2_computer_sns = production_api2.all :Computer, only: :serial_numbers
prod2_victim_md = production_api2.fetch :MobileDevice, id: 832

Here are the API calls you can make directly from an APIConnection object. They behave practically identically to the same methods in the APIObject subclasses, since they just call those methods, passing themselves in as the APIConnection to use.

Low-level use of APIConnection instances.

For most cases, using APIConnection instances as mentioned above is all you’ll need. However to access API resources that aren’t yet implemented in other parts of ruby-jss, you can use the methods #get_rsrc, #put_rsrc, #post_rsrc, & #delete_rsrc documented below.

For even lower-level work, you can access the underlying RestClient::Resource inside the APIConnection via the connection’s #cnx attribute.

APIConnection instances also have a #server attribute which contains an instance of Server q.v., representing the JSS to which it’s connected.

Constant Summary collapse

RSRC_BASE =

The base API path in the jss URL

'JSSResource'.freeze
TEST_PATH =

A url path to load to see if there’s an API available at a host. This just loads the API resource docs page

"#{RSRC_BASE}/accounts".freeze
TEST_CONTENT =

If the test path loads correctly from a casper server, it’ll contain this text (this is what we get when we make an unauthenticated API call.)

'<p>The request requires user authentication</p>'.freeze
HTTP_PORT =

The Default port

9006
SSL_PORT =

The Jamf default SSL port, default for locally-hosted servers

8443
HTTPS_SSL_PORT =

The https default SSL port, default for Jamf Cloud servers

443
SSL_PORTS =

if either of these is specified, we’ll default to SSL

[SSL_PORT, HTTPS_SSL_PORT].freeze
JAMFCLOUD_DOMAIN =

Recognize Jamf Cloud servers

'jamfcloud.com'.freeze
JAMFCLOUD_PORT =

JamfCloud connections default to 443, not 8443

HTTPS_SSL_PORT
XML_HEADER =

The top line of an XML doc for submitting data via API

'<?xml version="1.0" encoding="UTF-8" standalone="no"?>'.freeze
DFT_OPEN_TIMEOUT =

Default timeouts in seconds

60
DFT_TIMEOUT = 
60
DFT_SSL_VERSION =

The Default SSL Version As of Casper 9.61 we can’t use SSL, must use TLS, since SSLv3 was susceptible to poodles. NOTE - this requires rest-client v 1.7.0 or higher which requires mime-types 2.0 or higher, which requires ruby 1.9.2 or higher! That means that support for ruby 1.8.7 stops with Casper 9.6

'TLSv1'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ APIConnection

If name: is provided (as a String or Symbol) that will be stored as the APIConnection’s name attribute.

For other available parameters, see #connect.

If they are provided, they will be used to establish the connection immediately.

If not, you must call #connect before accessing the API.



388
389
390
391
392
393
394
 
# File 'lib/jss/api_connection.rb', line 388

def initialize(args = {})
  @name = args.delete :name
  @name ||= :disconnected
  @connected = false
  @object_list_cache = {}
  connect args unless args.empty?
end

Instance Attribute Details

#cnx ⇒ RestClient::Resource (readonly)

Returns the underlying connection resource.

Returns:

  • (RestClient::Resource) —

    the underlying connection resource



336
337
338
 
# File 'lib/jss/api_connection.rb', line 336

def cnx
  @cnx
end

#connected ⇒ Boolean (readonly) Also known as: connected?

Returns are we connected right now?.

Returns:

  • (Boolean) —

    are we connected right now?



339
340
341
 
# File 'lib/jss/api_connection.rb', line 339

def connected
  @connected
end

#jss_user ⇒ String (readonly)

Returns the username who’s connected to the JSS API.

Returns:

  • (String) —

    the username who’s connected to the JSS API



333
334
335
 
# File 'lib/jss/api_connection.rb', line 333

def jss_user
  @jss_user
end

#last_http_response ⇒ RestClient::Response (readonly)

Returns The response from the most recent API call.

Returns:

  • (RestClient::Response) —

    The response from the most recent API call



354
355
356
 
# File 'lib/jss/api_connection.rb', line 354

def last_http_response
  @last_http_response
end

#name ⇒ String, Symbol (readonly)

connection during initialization, using the name: parameter. defaults to user@hostname:port

Returns:

  • (String, Symbol) —

    an arbitrary name that can be given to this



362
363
364
 
# File 'lib/jss/api_connection.rb', line 362

def name
  @name
end

#object_list_cache ⇒ Hash (readonly)

This Hash holds the most recent API query for a list of all items in any APIObject subclass, keyed by the subclass’s RSRC_LIST_KEY. See the APIObject.all class method.

When the APIObject.all method is called without an argument, and this hash has a matching value, the value is returned, rather than requerying the API. The first time a class calls .all, or whnever refresh is not false, the API is queried and the value in this hash is updated.

Returns:



373
374
375
 
# File 'lib/jss/api_connection.rb', line 373

def object_list_cache
  @object_list_cache
end

#port ⇒ Integer (readonly)

Returns the port used for the connection.

Returns:

  • (Integer) —

    the port used for the connection



348
349
350
 
# File 'lib/jss/api_connection.rb', line 348

def port
  @port
end

#protocol ⇒ String (readonly)

Returns the protocol being used: http or https.

Returns:

  • (String) —

    the protocol being used: http or https



351
352
353
 
# File 'lib/jss/api_connection.rb', line 351

def protocol
  @protocol
end

#rest_url ⇒ String (readonly)

Returns The base URL to to the current REST API.

Returns:

  • (String) —

    The base URL to to the current REST API



357
358
359
 
# File 'lib/jss/api_connection.rb', line 357

def rest_url
  @rest_url
end

#server ⇒ JSS::Server (readonly)

Returns the details of the JSS to which we’re connected.

Returns:

  • (JSS::Server) —

    the details of the JSS to which we’re connected.



342
343
344
 
# File 'lib/jss/api_connection.rb', line 342

def server
  @server
end

#server_host ⇒ String (readonly)

Returns the hostname of the JSS to which we’re connected.

Returns:

  • (String) —

    the hostname of the JSS to which we’re connected.



345
346
347
 
# File 'lib/jss/api_connection.rb', line 345

def server_host
  @server_host
end

Instance Method Details

#all(class_name, refresh = false, only: nil) ⇒ Array

Call one of the ‘all*’ methods on a JSS::APIObject subclass using this APIConnection.

Parameters:

  • class_name (String, Symbol) —

    The name of a JSS::APIObject subclass see JSS.api_object_class

  • refresh (Boolean) (defaults to: false) —

    Should the data be re-read from the API?

  • only (String, Symbol) (defaults to: nil) —

    Limit the output to subset or data. All APIObject subclasses can take :ids or :names, which calls the .all_ids and .all_names methods. Some subclasses can take other options, e.g. MobileDevice can take :udids

Returns:

  • (Array) —

    The list of items for the class

Raises:

  • (ArgumentError) 


644
645
646
647
648
649
650
651
652
 
# File 'lib/jss/api_connection.rb', line 644

def all(class_name, refresh = false, only: nil )
  the_class = JSS.api_object_class(class_name)
  list_method = only ? :"all_#{only}" : :all

  raise ArgumentError, "Unknown identifier: #{only} for #{the_class}" unless
    the_class.respond_to? list_method

  the_class.send list_method, refresh, api: self
end

#computer_application_usage(ident, start_date, end_date = nil) ⇒ Object

Call Computer.application_usage q.v., passing this API connection



767
768
769
 
# File 'lib/jss/api_connection.rb', line 767

def computer_application_usage(ident, start_date, end_date = nil)
  JSS::Computer.application_usage ident, start_date, end_date, api: self
end

#computer_checkin_settings ⇒ Object

Call Computer.checkin_settings q.v., passing this API connection



753
754
755
 
# File 'lib/jss/api_connection.rb', line 753

def computer_checkin_settings
  JSS::Computer.checkin_settings api: self
end

#computer_history(ident, subset: nil) ⇒ Object

Deprecated.

Please use JSS::Computer.management_history or its convenience methods. @see JSS::ManagementHistory

Call Computer.history q.v., passing this API connection



784
785
786
 
# File 'lib/jss/api_connection.rb', line 784

def computer_history(ident, subset: nil)
  JSS::Computer.history ident, subset, api: self
end

#computer_inventory_collection_settings ⇒ Object

Call Computer.inventory_collection_settings q.v., passing this API connection



760
761
762
 
# File 'lib/jss/api_connection.rb', line 760

def computer_inventory_collection_settings
  JSS::Computer.inventory_collection_settings api: self
end

#computer_management_data(ident, subset: nil, only: nil) ⇒ Object

Call Computer.management_data q.v., passing this API connection



774
775
776
 
# File 'lib/jss/api_connection.rb', line 774

def computer_management_data(ident, subset: nil, only: nil)
  JSS::Computer.management_data ident, subset: subset, only: only, api: self
end

#connect(args = {}) ⇒ true

Connect to the JSS API.

Parameters:

  • args (Hash) (defaults to: {}) —

    the keyed arguments for connection.

Options Hash (args):

  • :server (String) —

    the hostname of the JSS API server, required if not defined in JSS::CONFIG

  • :port (Integer) —

    the port number to connect with, defaults to 8443

  • :use_ssl (Boolean) —

    should the connection be made over SSL? Defaults to true.

  • :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.

  • :user (String) —

    a JSS user who has API privs, required if not defined in JSS::CONFIG

  • :pw (String, Symbol) —

    Required, the password for that user, or :prompt, or :stdin 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 1, if no digit is supplied. see JSS.stdin

  • :open_timeout (Integer) —

    the number of seconds to wait for an initial response, defaults to 60

  • :timeout (Integer) —

    the number of seconds before an API call times out, defaults to 60

Returns:

  • (true) 


427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/jss/api_connection.rb', line 427

def connect(args = {})
  args = apply_connection_defaults args

  # confirm we know basics
  verify_basic_args args

  # parse our ssl situation
  verify_ssl args

  @jss_user = args[:user]

  @rest_url = build_rest_url args

  # figure out :password from :pw
  args[:password] = acquire_password args

  # heres our connection
  @cnx = RestClient::Resource.new(@rest_url.to_s, args)

  verify_server_version

  @name = "#{@jss_user}@#{@server_host}:#{@port}" if @name.nil? || @name == :disconnected
  @connected ? hostname : nil
end

#delete_rsrc(rsrc, xml = nil) ⇒ String

Delete a resource from the JSS

Parameters:

  • rsrc (String) —

    the resource to create, the URL part after ‘JSSResource/’

Returns:

  • (String) —

    the xml response from the server.

Raises:



564
565
566
567
568
569
570
571
572
573
 
# File 'lib/jss/api_connection.rb', line 564

def delete_rsrc(rsrc, xml = nil)
  raise JSS::InvalidConnectionError, 'Not Connected. Use .connect first.' unless @connected
  raise MissingDataError, 'Missing :rsrc' if rsrc.nil?

  # payload?
  return delete_with_payload rsrc, xml if xml

  # delete the resource
  @last_http_response = @cnx[rsrc].delete
end

#disconnect ⇒ void

This method returns an undefined value.

With a REST connection, there isn’t any real “connection” to disconnect from So to disconnect, we just unset all our credentials.



485
486
487
488
489
490
491
 
# File 'lib/jss/api_connection.rb', line 485

def disconnect
  @jss_user = nil
  @rest_url = nil
  @server_host = nil
  @cnx = nil
  @connected = false
end

#exist?(class_name, identifier, refresh = false) ⇒ Boolean

Call the ‘exist?’ method on a JSS::APIObject subclass using this APIConnection. See JSS::APIObject.exist?

Parameters:

  • class_name (String, Symbol) —

    The name of a JSS::APIObject subclass see JSS.api_object_class

  • identifier (String, Symbol) —

    the value to which the ids should be mapped

  • refresh (Boolean) (defaults to: false) —

    Should the data be re-read from the API?

Returns:

  • (Boolean) —

    Is there an object of this class in the JSS matching this indentifier?



703
704
705
 
# File 'lib/jss/api_connection.rb', line 703

def exist?(class_name, identifier, refresh = false)
  !valid_id(class_name, identifier, refresh).nil?
end

#fetch(class_name, arg) ⇒ APIObject

Retrieve an object of a given class from the API See JSS::APIObject.fetch

Parameters:

Returns:

  • (APIObject) —

    The ruby-instance of the object.



730
731
732
733
 
# File 'lib/jss/api_connection.rb', line 730

def fetch(class_name, arg)
  the_class = JSS.api_object_class(class_name)
  the_class.fetch arg, api: self
end

#get_rsrc(rsrc, format = :json) ⇒ Hash, String

Get an arbitrary JSS resource

The first argument is the resource to get (the part of the API url after the ‘JSSResource/’ )

By default we get the data in JSON, and parse it into a ruby data structure (arrays, hashes, strings, etc) with symbolized Hash keys.

Parameters:

  • rsrc (String) —

    the resource to get (the part of the API url after the ‘JSSResource/’ )

  • format (Symbol) (defaults to: :json) —

    either ;json or :xml If the second argument is :xml, the XML data is returned as a String.

Returns:

Raises:



510
511
512
513
514
515
516
 
# File 'lib/jss/api_connection.rb', line 510

def get_rsrc(rsrc, format = :json)
  # puts object_id
  raise JSS::InvalidConnectionError, 'Not Connected. Use .connect first.' unless @connected
  rsrc = URI.encode rsrc
  @last_http_response = @cnx[rsrc].get(accept: format)
  return JSON.parse(@last_http_response, symbolize_names: true) if format == :json
end

#hostname ⇒ String Also known as: host

The server to which we are connected, or will try connecting to if none is specified with the call to #connect

Returns:

  • (String) —

    the hostname of the server



615
616
617
618
619
620
 
# File 'lib/jss/api_connection.rb', line 615

def hostname
  return @server_host if @server_host
  srvr = JSS::CONFIG.api_server_name
  srvr ||= JSS::Client.jss_server
  srvr
end

#make(class_name, **args) ⇒ APIObject

Make a ruby instance of a not-yet-existing APIObject of the given class See JSS::APIObject.make

Parameters:

Returns:

  • (APIObject) —

    The un-created ruby-instance of the object.



744
745
746
747
748
 
# File 'lib/jss/api_connection.rb', line 744

def make(class_name, **args)
  the_class = JSS.api_object_class(class_name)
  args[:api] = self
  the_class.make args
end

#map_all_ids(class_name, refresh = false, to: nil) ⇒ Hash

Call the ‘map_all_ids_to’ method on a JSS::APIObject subclass using this APIConnection.

Parameters:

  • class_name (String, Symbol) —

    The name of a JSS::APIObject subclass see JSS.api_object_class

  • refresh (Boolean) (defaults to: false) —

    Should the data be re-read from the API?

  • to (String, Symbol) (defaults to: nil) —

    the value to which the ids should be mapped

Returns:

  • (Hash) —

    The ids for the class keyed to the requested identifier



666
667
668
669
670
 
# File 'lib/jss/api_connection.rb', line 666

def map_all_ids(class_name, refresh = false, to: nil)
  raise "'to:' value must be provided for mapping ids." unless to
  the_class = JSS.api_object_class(class_name)
  the_class.map_all_ids_to to, refresh, api: self
end

#master_distribution_point(refresh = false) ⇒ 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.

Parameters:

  • refresh (Boolean) (defaults to: false) —

    re-read from the API?

Returns:



807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
 
# File 'lib/jss/api_connection.rb', line 807

def master_distribution_point(refresh = false)
  @master_distribution_point = nil if refresh
  return @master_distribution_point if @master_distribution_point

  all_dps = JSS::DistributionPoint.all refresh, api: self

  @master_distribution_point =
    case all_dps.size
    when 0
      raise JSS::NoSuchItemError, "No distribution points defined"
    when 1
      JSS::DistributionPoint.fetch id: all_dps.first[:id], api: self
    else
      JSS::DistributionPoint.fetch id: :master, api: self
    end
end

#match(class_name, term) ⇒ Array<Hash>

Call Matchable#match for the given class.

See Matchable#match

Parameters:

Returns:

Raises:



716
717
718
719
720
 
# File 'lib/jss/api_connection.rb', line 716

def match(class_name, term)
  the_class = JSS.api_object_class(class_name)
  raise JSS::UnsupportedError, "Class #{the_class} is not matchable" unless the_class.respond_to? :match
  the_class.match term, api: self
end

#my_distribution_point(refresh = false) ⇒ 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

Parameters:

  • refresh (Boolean) (defaults to: false) —

    should the distribution point be re-queried?

Returns:



832
833
834
835
836
837
838
839
840
 
# File 'lib/jss/api_connection.rb', line 832

def my_distribution_point(refresh = false)
  @my_distribution_point = nil if refresh
  return @my_distribution_point if @my_distribution_point

  my_net_seg = my_network_segments[0]
  @my_distribution_point = JSS::NetworkSegment.fetch(id: my_net_seg, api: self).distribution_point if my_net_seg
  @my_distribution_point ||= master_distribution_point refresh
  @my_distribution_point
end

#my_network_segments ⇒ Array<Integer>

Find the current network segment ids for the machine running this code

Returns:

  • (Array<Integer>) —

    the NetworkSegment ids for this machine right now.



886
887
888
 
# File 'lib/jss/api_connection.rb', line 886

def my_network_segments
  network_segments_for_ip JSS::Client.my_ip_address
end

#network_ranges(refresh = false) ⇒ Hash{Integer => Range}

All NetworkSegments in this jss as IPAddr object Ranges representing the Segment, e.g. with starting = 10.24.9.1 and ending = 10.24.15.254 the range looks like:

<IPAddr: IPv4:10.24.9.1/255.255.255.255>..#<IPAddr: IPv4:10.24.15.254/255.255.255.255>

Using the #include? method on those Ranges is very useful.

Parameters:

  • refresh (Boolean) (defaults to: false) —

    should the data be re-queried?

Returns:

  • (Hash{Integer => Range}) —

    the network segments as IPv4 address Ranges



853
854
855
856
857
858
859
860
861
 
# File 'lib/jss/api_connection.rb', line 853

def network_ranges(refresh = false)
  @network_ranges = nil if refresh
  return @network_ranges if @network_ranges
  @network_ranges = {}
  JSS::NetworkSegment.all(refresh, api: self).each do |ns|
    @network_ranges[ns[:id]] = IPAddr.new(ns[:starting_address])..IPAddr.new(ns[:ending_address])
  end
  @network_ranges
end

#network_segments_for_ip(ip) ⇒ Array<Integer>

Find the ids of the network segments that contain a given IP address.

Even tho IPAddr.include? will take a String or an IPAddr I convert the ip to an IPAddr so that an exception will be raised if the ip isn’t a valid ip.

Parameters:

  • ip (String, IPAddr) —

    the IP address to locate

  • refresh (Boolean) —

    should the data be re-queried?

Returns:

  • (Array<Integer>) —

    the ids of the NetworkSegments containing the given ip



875
876
877
878
879
880
 
# File 'lib/jss/api_connection.rb', line 875

def network_segments_for_ip(ip)
  ok_ip = IPAddr.new(ip)
  matches = []
  network_ranges.each { |id, subnet| matches << id if subnet.include?(ok_ip) }
  matches
end

#open_timeout=(timeout) ⇒ void

This method returns an undefined value.

Reset the open-connection timeout for the rest connection

Parameters:

  • timeout (Integer) —

    the new timeout in seconds



476
477
478
 
# File 'lib/jss/api_connection.rb', line 476

def open_timeout=(timeout)
  @cnx.options[:open_timeout] = timeout
end

#post_rsrc(rsrc, xml = '') ⇒ String

Create a new JSS resource

Parameters:

  • rsrc (String) —

    the API resource being created, the URL part after ‘JSSResource/’

  • xml (String) (defaults to: '') —

    the xml specifying the new object.

Returns:

  • (String) —

    the xml response from the server.



546
547
548
549
550
551
552
553
554
555
556
 
# File 'lib/jss/api_connection.rb', line 546

def post_rsrc(rsrc, xml = '')
  raise JSS::InvalidConnectionError, 'Not Connected. Use .connect first.' unless @connected

  # convert CRs & to &#13;
  xml.gsub!(/\r/, '&#13;') if xml

  # send the data
  @last_http_response = @cnx[rsrc].post xml, content_type: 'text/xml', accept: :json
rescue RestClient::Conflict => exception
  raise_conflict_error(exception)
end

#pretty_print_instance_variables ⇒ Array

Remove the various cached data from the instance_variables used to create pretty-print (pp) output.

Returns:

  • (Array) —

    the desired instance_variables



908
909
910
911
912
913
914
915
916
 
# File 'lib/jss/api_connection.rb', line 908

def pretty_print_instance_variables
  vars = instance_variables.sort
  vars.delete :@object_list_cache
  vars.delete :@last_http_response
  vars.delete :@network_ranges
  vars.delete :@my_distribution_point
  vars.delete :@master_distribution_point
  vars
end

#put_rsrc(rsrc, xml) ⇒ String

Change an existing JSS resource

Parameters:

  • rsrc (String) —

    the API resource being changed, the URL part after ‘JSSResource/’

  • xml (String) —

    the xml specifying the changes.

Returns:

  • (String) —

    the xml response from the server.



526
527
528
529
530
531
532
533
534
535
536
 
# File 'lib/jss/api_connection.rb', line 526

def put_rsrc(rsrc, xml)
  raise JSS::InvalidConnectionError, 'Not Connected. Use .connect first.' unless @connected

  # convert CRs & to &#13;
  xml.gsub!(/\r/, '&#13;')

  # send the data
  @last_http_response = @cnx[rsrc].put(xml, content_type: 'text/xml')
rescue RestClient::Conflict => exception
  raise_conflict_error(exception)
end

#send_computer_mdm_command(targets, command, passcode = nil) ⇒ Object

Deprecated.

Please use JSS::Computer.send_mdm_command or its convenience methods. @see JSS::MDM

Call Computer.send_mdm_command q.v., passing this API connection



794
795
796
797
 
# File 'lib/jss/api_connection.rb', line 794

def send_computer_mdm_command(targets, command, passcode = nil)
  opts = passcode ? { passcode: passcode } : {}
  JSS::Computer.send_mdm_command targets, command, opts: opts, api: self
end

#send_mobiledevice_mdm_command(targets, command, data = {}) ⇒ Object

Deprecated.

Please use JSS::MobileDevice.send_mdm_command or its convenience methods. @see JSS::MDM

Send an MDM command to one or more mobile devices managed by this JSS

see MobileDevice.send_mdm_command



898
899
900
 
# File 'lib/jss/api_connection.rb', line 898

def send_mobiledevice_mdm_command(targets, command, data = {})
  JSS::MobileDevice.send_mdm_command(targets, command, opts: data, api: self)
end

#timeout=(timeout) ⇒ void

This method returns an undefined value.

Reset the response timeout for the rest connection

Parameters:

  • timeout (Integer) —

    the new timeout in seconds



466
467
468
 
# File 'lib/jss/api_connection.rb', line 466

def timeout=(timeout)
  @cnx.options[:timeout] = timeout
end

#to_s ⇒ String

A useful string about this connection

Returns:



456
457
458
 
# File 'lib/jss/api_connection.rb', line 456

def to_s
  @connected ? "Using #{@rest_url} as user #{@jss_user}" : 'not connected'
end

#valid_id(class_name, identifier, refresh = true) ⇒ Integer?

Call the ‘valid_id’ method on a JSS::APIObject subclass using this APIConnection. See JSS::APIObject.valid_id

Parameters:

  • class_name (String, Symbol) —

    The name of a JSS::APIObject subclass, see JSS.api_object_class

  • identifier (String, Symbol) —

    the value to which the ids should be mapped

  • refresh (Boolean) (defaults to: true) —

    Should the data be re-read from the API?

Returns:

  • (Integer, nil) —

    the id of the matching object of the class, or nil if there isn’t one



685
686
687
688
 
# File 'lib/jss/api_connection.rb', line 685

def valid_id(class_name, identifier, refresh = true)
  the_class = JSS.api_object_class(class_name)
  the_class.valid_id identifier, refresh, api: self
end

#valid_server?(server, port = SSL_PORT) ⇒ Boolean

Test that a given hostname & port is a JSS API server

Parameters:

  • server (String) —

    The hostname to test,

  • port (Integer) (defaults to: SSL_PORT) —

    The port to try connecting on

Returns:

  • (Boolean) —

    does the server host a JSS API?



583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
 
# File 'lib/jss/api_connection.rb', line 583

def valid_server?(server, port = SSL_PORT)
  # cheating by shelling out to curl, because getting open-uri, or even net/http to use
  # ssl_options like :OP_NO_SSLv2 and :OP_NO_SSLv3 will take time to figure out..
  return true if `/usr/bin/curl -s 'https://#{server}:#{port}/#{TEST_PATH}'`.include? TEST_CONTENT
  return true if `/usr/bin/curl -s 'http://#{server}:#{port}/#{TEST_PATH}'`.include? TEST_CONTENT
  false

  # # try ssl first
  # # NOTE:  doesn't work if we can't disallow SSLv3 or force TLSv1
  # # See cheat above.
  # 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
  # false
end