Method: OvirtSDK4::Connection#initialize

Defined in:
lib/ovirtsdk4/connection.rb

#initialize(opts = {}) ⇒ Connection

Creates a new connection to the API server.

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.

  • :username (String) —

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

  • :password (String) —

    The password of the user.

  • :token (String) —

    The token used to authenticate. Optionally the caller can explicitly provide the token, instead of the user name and password. If the token isn’t provided then it will be automatically created.

  • :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 neither this nor the ca_certs options are provided, then the system wide CA certificates store is used. If both options are provided, then the certificates from both options will be trusted.

  • :ca_certs (Array<String>) —

    An array of strings containing the trusted CA certificates, in PEM format. The certificate presented by the server will be verified using these CA certificates. If neither this nor the ca_file options are provided, then the system wide CA certificates store is used. If both options are provided, then the certificates from both options will be trusted.

  • :debug (Boolean) — default: false —

    A boolean flag indicating if debug output should be generated. If the values is true and the log parameter isn’t nil then the data sent to and received from the server will be written to the log. Be aware that user names and passwords will also be written, so handle with care.

  • :log (Logger) —

    The logger where the log messages will be written.

  • :kerberos (Boolean) — default: false —

    A boolean flag indicating if Kerberos authentication should be used instead of user name and password to obtain the OAuth token.

  • :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 a TimeoutError exception will be raised.

  • :connect_timeout (Integer) — default: 300 —

    The maximun time to wait for connection establishment, in seconds. If the timeout expires before the connection is established a TimeoutError exception will be raised.

  • :compress (Boolean) — default: true —

    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. Also, compression will be automatically disabled when the debug parameter is set to true, as otherwise the debug output will be compressed as well, and then it isn’t useful.

  • :proxy_url (String) —

    A string containing the protocol, address and port number of the proxy server to use to connect to the server. For example, in order to use the HTTP proxy proxy.example.com that is listening on port 3128 the value should be http://proxy.example.com:3128. This is optional, and if not given the connection will go directly to the server specified in the url parameter.

  • :proxy_username (String) —

    The name of the user to authenticate to the proxy server.

  • :proxy_password (String) —

    The password of the user to authenticate to the proxy server.

  • :headers (Hash) —

    Custom HTTP headers to send with all requests. The keys of the hash can be strings of symbols, and they will be used as the names of the headers. The values of the hash will be used as the names of the headers. If the same header is provided here and in the headers parameter of a specific method call, then the headers parameter of the specific method call will have precedence.

  • :connections (Integer) — default: 1 —

    The maximum number of connections to open to the host. The value must be greater than 0.

  • :pipeline (Integer) — default: 0 —

    The maximum number of request to put in an HTTP pipeline without waiting for the response. If the value is 0 (the default) then pipelining is disabled.

Raises:

  • (ArgumentError) 


109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
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
 
# File 'lib/ovirtsdk4/connection.rb', line 109

def initialize(opts = {})
  # Get the values of the parameters and assign default values:
  @url = opts[:url]
  @username = opts[:username]
  @password = opts[:password]
  @token = opts[:token]
  @insecure = opts[:insecure] || false
  @ca_file = opts[:ca_file]
  @ca_certs = opts[:ca_certs]
  @debug = opts[:debug] || false
  @log = opts[:log]
  @kerberos = opts[:kerberos] || false
  @timeout = opts[:timeout] || 0
  @connect_timeout = opts[:connect_timeout] || 0
  @compress = opts[:compress] || true
  @proxy_url = opts[:proxy_url]
  @proxy_username = opts[:proxy_username]
  @proxy_password = opts[:proxy_password]
  @headers = opts[:headers]
  @connections = opts[:connections] || 1
  @pipeline = opts[:pipeline] || 0

  # Check that the URL has been provided:
  raise ArgumentError, "The 'url' option is mandatory" unless @url

  # Automatically disable compression when debug is enabled, as otherwise the debug output generated by
  # libcurl is also compressed, and that isn't useful for debugging:
  @compress = false if @debug

  # Create a temporary file to store the CA certificates, and populate it with the contents of the 'ca_file' and
  # 'ca_certs' options. The file will be removed when the connection is closed.
  @ca_store = nil
  if @ca_file || @ca_certs
    @ca_store = Tempfile.new('ca_store')
    @ca_store.write(::File.read(@ca_file)) if @ca_file
    if @ca_certs
      @ca_certs.each do |ca_cert|
        @ca_store.write(ca_cert)
      end
    end
    @ca_store.close
  end

  # Create the mutex that will be used to prevents simultaneous access to the same HTTP client by multiple threads:
  @mutex = Mutex.new

  # Create the HTTP client:
  @client = HttpClient.new(
    insecure:        @insecure,
    ca_file:         @ca_store ? @ca_store.path : nil,
    debug:           @debug,
    log:             @log,
    timeout:         @timeout,
    connect_timeout: @connect_timeout,
    compress:        @compress,
    proxy_url:       @proxy_url,
    proxy_username:  @proxy_username,
    proxy_password:  @proxy_password,
    connections:     @connections,
    pipeline:        @pipeline
  )
end