Class: JSS::APIConnection

Inherits:
Object
  • Object
show all
Includes:
Singleton
Defined in:
lib/jss-api/api_connection.rb,
lib/jss-api.rb

Overview

An API connection to the JSS.

This is a singleton class, only one can exist at a time. Its one instance is created automatically when the module loads, but it isn’t connected to anything at that time.

Use it via the API constant to call the #connect method, and the #get_rsrc, #put_rsrc, #post_rsrc, & #delete_rsrc methods, q.v. below.

To access the underlying RestClient::Resource instance, use JSS::API.cnx

Constant Summary collapse

RSRC =

The base API path in the jss URL

"JSSResource"
HTTP_PORT =

The Default port

9006
SSL_PORT =

The SSL port

8443
XML_HEADER =

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

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

Default timeouts in seconds

60
DFT_TIMEOUT = 
60
DFT_SSL_VERSION =

The Default SSL Version

'TLSv1'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ APIConnection

To connect, use JSS::APIConnection.instance.connect or a shortcut, JSS::API.connect



108
109
110
 
# File 'lib/jss-api/api_connection.rb', line 108

def initialize ()
  @connected = false
end

Instance Attribute Details

#cnx ⇒ RestClient::Resource (readonly)

Returns the underlying connection resource.

Returns:

  • (RestClient::Resource) —

    the underlying connection resource



92
93
94
 
# File 'lib/jss-api/api_connection.rb', line 92

def cnx
  @cnx
end

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

Returns are we connected right now?.

Returns:

  • (Boolean) —

    are we connected right now?



95
96
97
 
# File 'lib/jss-api/api_connection.rb', line 95

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



89
90
91
 
# File 'lib/jss-api/api_connection.rb', line 89

def jss_user
  @jss_user
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.



98
99
100
 
# File 'lib/jss-api/api_connection.rb', line 98

def server
  @server
end

Instance Method Details

#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

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

Raises:



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
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/jss-api/api_connection.rb', line 143

def connect (args = {})

  # settings from config if they aren't in the args
  args[:server] ||= JSS::CONFIG.api_server_name
  args[:port] ||= JSS::CONFIG.api_server_port
  args[:user] ||= JSS::CONFIG.api_username
  args[:timeout] ||= JSS::CONFIG.api_timeout
  args[:open_timeout] ||= JSS::CONFIG.api_timeout_open
  args[:ssl_version] ||= JSS::CONFIG.api_ssl_version

  # if verify cert given was NOT in the args....
  if args[:verify_cert].nil?
    # set it from the prefs
    args[:verify_cert] = JSS::CONFIG.api_verify_cert
  end

  # default settings if needed
  args[:port] ||= SSL_PORT
  args[:timeout] ||= DFT_TIMEOUT
  args[:open_timeout] ||= DFT_OPEN_TIMEOUT
  
  # 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
  args[:ssl_version] ||= DFT_SSL_VERSION
  
  
  # must have server, user, and pw
  raise JSS::MissingDataError, "No JSS :server specified, or in configuration." unless args[:server]
  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}"

  # 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
  
  args[:password] = if args[:pw] == :prompt
    JSS.prompt_for_password "Enter the password for JSS user #{args[:user]}@#{args[:server]}:"
  elsif args[:pw].is_a?(Symbol) and args[:pw].to_s.start_with?('stdin')
    args[:pw].to_s =~ /^stdin(\d+)$/
    line = $1
    line ||= 1
    JSS.stdin line
  else
    args[:pw]
  end
  
  
  
  # heres our connection
  @cnx = RestClient::Resource.new("#{@rest_url}", args)

  @jss_user = args[:user]
  @connected = true
  @server = JSS::Server.new

  if @server.version < JSS.parse_jss_version(JSS::MINIMUM_SERVER_VERSION)[:version]
    raise JSS::UnsupportedError, "Your JSS Server version, #{@server.raw_version}, is to low. Must be #{JSS::MINIMUM_SERVER_VERSION} or higher."
  end

  return true
end

#delete_rsrc(rsrc) ⇒ 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:



318
319
320
321
322
323
324
325
 
# File 'lib/jss-api/api_connection.rb', line 318

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

  ### delete the resource
  @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.



240
241
242
243
244
245
 
# File 'lib/jss-api/api_connection.rb', line 240

def disconnect
  @jss_user = nil
  @rest_url = nil
  @cnx = nil
  @connected = false
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:



265
266
267
268
269
270
271
 
# File 'lib/jss-api/api_connection.rb', line 265

def get_rsrc (rsrc, format = :json)
  raise JSS::InvalidConnectionError, "Not Connected. Use JSS::API.connect first." unless @connected
  rsrc = URI::encode rsrc
  data = @cnx[rsrc].get(:accept => format)
  return JSON.parse(data, :symbolize_names => true) if format == :json
  data
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



229
230
231
 
# File 'lib/jss-api/api_connection.rb', line 229

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) —

    the xml specifying the new object.

Returns:

  • (String) —

    the xml response from the server.

Raises:



301
302
303
304
305
306
307
308
309
 
# File 'lib/jss-api/api_connection.rb', line 301

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

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

  ### send the data
  @cnx[rsrc].post xml, :content_type => 'text/xml', :accept => :json
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.

Raises:



282
283
284
285
286
287
288
289
290
 
# File 'lib/jss-api/api_connection.rb', line 282

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

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

  ### send the data
  @cnx[rsrc].put(xml, :content_type => 'text/xml')
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



218
219
220
 
# File 'lib/jss-api/api_connection.rb', line 218

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