Class: OvirtSDK4::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/ovirtsdk4/http.rb

Overview

This class is responsible for managing an HTTP connection to the engine server. It is intended as the entry point for the SDK, and it provides access to the system service and, from there, to the rest of the services provided by the API.

Instance Method Summary (collapse)

Constructor Details

- (Connection) initialize(opts = {})

Creates a new connection to the API server.

Note that all the parameters with names starting with sso are intended for use with external authentication services, using the OAuth2 protocol. But the typical usage doesn’t require them, as they are automatically calculated to use the authentication service that is part of the engine. A typical connection can be created specifying just the url, username, password and ca_file parameters:

connection = OvirtSDK4::Connection.new(
  :url => 'https://engine.example.com/ovirt-engine/api',
  :username => 'admin@internal',
  :password => '...',
  :ca_file => '/etc/pki/ovirt-engine/ca.pem',
)

Parameters:

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

    The options used to create the connection.

Options Hash (opts):

  • :url (String) —

    A string containing the base URL of the server, usually something like https://server.example.com/ovirt-engine/api.

  • :user (String) —

    The name of the user, something like admin@internal.

  • :password (String) —

    The password of the user.

  • :insecure (Boolean) — default: false —

    A boolean flag that indicates if the server TLS certificate and host name should be checked.

  • :ca_file (String) —

    The name of a PEM file containing the trusted CA certificates. The certificate presented by the server will be verified using these CA certificates. If not set then the system wide CA certificates store is used.

  • :debug (Boolean) — default: false —

    A boolean flag indicating if debug output should be generated. If the values is true all the data sent to and received from the server will be written to $stdout. Be aware that user names and passwords will also be written, so handle it with care.

  • :log (String, IO) —

    The log file where the debug output will be written. The value can be an string containing a file name or an IO object. If it is a file name then the file will be created if it doesn’t exist, and the debug output will be added to the end. The file will be closed when the connection is closed. If it is an IO object then the debug output will be written directly, and it won’t be closed.

  • :kerberos (Boolean) — default: false —

    A boolean flag indicating if Kerberos uthentication should be used instead of the default basic authentication.

  • :timeout (Integer) — default: 0 —

    The maximun total time to wait for the response, in seconds. A value of zero (the default) means wait for ever. If the timeout expires before the response is received an exception will be raised.

  • :compress (Boolean) — default: false —

    A boolean flag indicating if the SDK should ask the server to send compressed responses. Note that this is a hint for the server, and that it may return uncompressed data even when this parameter is set to true.

  • :sso_url (String) —

    A string containing the base URL of the authentication service. This needs to be specified only when using an external authentication service. By default this URL is automatically calculated from the value of the url parameter, so that authentication will be performed using the authentication service that is part of the engine.

  • :sso_revoke_url (String) —

    A string containing the base URL of the SSO revoke service. This needs to be specified only when using an external authentication service. By default this URL is automatically calculated from the value of the url parameter, so that SSO token revoke will be performed using the SSO service that is part of the engine.

  • :sso_insecure (Boolean) —

    A boolean flag that indicates if the SSO server TLS certificate and host name should be checked. Default is value of insecure.

  • :sso_ca_file (String) —

    The name of a PEM file containing the trusted CA certificates. The certificate presented by the SSO server will be verified using these CA certificates. Default is value of ca_file.

  • :sso_debug (Boolean) —

    A boolean flag indicating if SSO debug output should be generated. If the values is true all the data sent to and received from the SSO server will be written to $stdout. Be aware that user names and passwords will also be written, so handle it with care. Default is value of debug.

  • :sso_log (String, IO) —

    The log file where the SSO debug output will be written. The value can be a string containing a file name or an IO object. If it is a file name then the file will be created if it doesn’t exist, and the SSO debug output will be added to the end. The file will be closed when the connection is closed. If it is an IO object then the SSO debug output will be written directly, and it won’t be closed. Default is value of log.

  • :sso_timeout (Boolean) —

    The maximun total time to wait for the SSO response, in seconds. A value of zero means wait for ever. If the timeout expires before the SSO response is received an exception will be raised. Default is value of timeout.

  • :sso_token_name (String) — default: access_token —

    The token name in the JSON SSO response returned from the SSO server. Default value is access_token



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
210
211
212
213
214
215
216
217
218
219
220
221
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
 
# File 'lib/ovirtsdk4/http.rb', line 165

def initialize(opts = {})
  # Get the values of the parameters and assign default values:
  url = opts[:url]
  username = opts[:username]
  password = opts[:password]
  insecure = opts[:insecure] || false
  ca_file = opts[:ca_file]
  debug = opts[:debug] || false
  log = opts[:log]
  kerberos = opts[:kerberos] || false
  timeout = opts[:timeout] || 0
  compress = opts[:compress] || false
  sso_url = opts[:sso_url]
  sso_revoke_url = opts[:sso_revoke_url]
  sso_insecure = opts[:sso_insecure] || insecure
  sso_ca_file = opts[:sso_ca_file] || ca_file
  sso_debug = opts[:sso_debug] || debug
  sso_log = opts[:sso_log] || log
  sso_timeout = opts[:sso_timeout] || timeout
  sso_token_name = opts[:sso_token_name] || 'access_token'

  # Check mandatory parameters:
  if url.nil?
     raise ArgumentError.new("The \"url\" parameter is mandatory.")
  end

  # Save the URL:
  @url = URI(url)

  # Save SSO parameters:
  @sso_url = sso_url
  @sso_revoke_url = sso_revoke_url
  @username = username
  @password = password
  @kerberos = kerberos
  @sso_insecure = sso_insecure
  @sso_ca_file = sso_ca_file
  @sso_log_file = sso_log
  @sso_debug = sso_debug
  @sso_timeout = sso_timeout
  @log_file = log
  @sso_token_name = sso_token_name

  # Create the cURL handle:
  @curl = Curl::Easy.new

  # Configure TLS parameters:
  if @url.scheme == 'https'
    if insecure
      @curl.ssl_verify_peer = false
      @curl.ssl_verify_host = false
    elsif !ca_file.nil?
      raise ArgumentError.new("The CA file \"#{ca_file}\" doesn't exist.") unless ::File.file?(ca_file)
      @curl.cacert = ca_file
    end
  end

  # Configure the timeout:
  @curl.timeout = timeout

  # Configure compression of responses (setting the value to a zero length string means accepting all the
  # compression types that libcurl supports):
  if compress
    @curl.encoding = ''
  end

  # Configure debug mode:
  @close_log = false
  if debug
    if log.nil?
      @log = STDOUT
    elsif log.is_a?(String)
      @log = ::File.open(log, 'a')
      @close_log = true
    else
      @log = log
    end
    @curl.verbose = true
    @curl.on_debug do |type, data|
      case type
      when Curl::CURLINFO_DATA_IN
        prefix = '< '
      when Curl::CURLINFO_DATA_OUT
        prefix = '> '
      when Curl::CURLINFO_HEADER_IN
        prefix = '< '
      when Curl::CURLINFO_HEADER_OUT
        prefix = '> '
      else
        prefix = '* '
      end
      lines = data.gsub("\r\n", "\n").strip.split("\n")
      lines.each do |line|
        @log.puts(prefix + line)
      end
      @log.flush
    end
  end

end

Instance Method Details

- (Object) close

Releases the resources used by this connection.



609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
 
# File 'lib/ovirtsdk4/http.rb', line 609

def close
  # Send the last request to indicate the server that the session should be closed:
  request = Request.new({
    :method => :HEAD,
  })
  send(request)

  # Revoke the SSO access token:
  revoke_access_token

  # Close the log file, if we did open it:
  if @close_log
    @log.close
  end

  # Release resources used by the cURL handle:
  @curl.close
end

- (Object) follow_link(object)

Follows the href attribute of the given object, retrieves the target object and returns it.

Parameters:

  • object (Type) —

    The object containing the href attribute.

Raises:

  • (Error) —

    If the href attribute has no value, or the link can’t be followed.



579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
 
# File 'lib/ovirtsdk4/http.rb', line 579

def follow_link(object)
  # Check that the "href" has a value, as it is needed in order to retrieve the representation of the object:
  href = object.href
  if href.nil?
    raise Error.new("Can't follow link because the 'href' attribute does't have a value")
  end

  # Check that the value of the "href" attribute is compatible with the base URL of the connection:
  prefix = @url.path
  if !prefix.end_with?('/')
    prefix += '/'
  end
  if !href.start_with?(prefix)
    raise Error.new("The URL '#{href}' isn't compatible with the base URL of the connection")
  end

  # Remove the prefix from the URL, follow the path to the relevant service and invoke the "get" or "list" method
  # to retrieve its representation:
  path = href[prefix.length..-1]
  service = service(path)
  if object.is_a?(Array)
    service.list
  else
    service.get
  end
end

- (Boolean) is_link?(object)

Indicates if the given object is a link. An object is a link if it has an href attribute.

Returns:

  • (Boolean) 


569
570
571
 
# File 'lib/ovirtsdk4/http.rb', line 569

def is_link?(object)
  return !object.href.nil?
end

- (Service) service(path)

Returns a reference to the service corresponding to the given path. For example, if the path parameter is vms/123/disks then it will return a reference to the service that manages the disks for the virtual machine with identifier 123.

Parameters:

  • path (String) —

    The path of the service, for example vms/123/disks.

Returns:

Raises:

  • (Error) —

    If there is no service corresponding to the given path.



294
295
296
 
# File 'lib/ovirtsdk4/http.rb', line 294

def service(path)
  return system_service.service(path)
end

- (SystemService) system_service

Returns a reference to the root of the services tree.

Returns:



280
281
282
283
 
# File 'lib/ovirtsdk4/http.rb', line 280

def system_service
  @system_service ||= SystemService.new(self, "")
  return @system_service
end

- (Boolean) test(raise_exception = false)

Tests the connectivity with the server. If connectivity works correctly it returns true. If there is any connectivity problem it will either return false or raise an exception if the raise_exception parameter is true.

Parameters:

  • raise_exception (Boolean) (defaults to: false)

Returns:

  • (Boolean) 


554
555
556
557
558
559
560
561
562
 
# File 'lib/ovirtsdk4/http.rb', line 554

def test(raise_exception = false)
  begin
    system_service.get
    return true
  rescue Exception
    raise if raise_exception
    return false
  end
end

- (String) url

Returns the base URL of this connection.

Returns:

  • (String) 


271
272
273
 
# File 'lib/ovirtsdk4/http.rb', line 271

def url
  return @url
end