Connecting to Qaptiva Access

The class QLMaaSConnection is used to connect to a remote Qaptiva machine. This class requires some information to connect:

  • the IP address of the remote server

  • the port listened to by the server

  • the authentication method used to authenticate the user. The authentication could be based on a pair username / password or using a SSL certificate

A number of parameters are used to configure this connection, they can be provided in two ways with the following order of priority:

  1. Passed as parameters to the constructor of QLMaaSConnection.

  2. Set into a configuration_file (recommended)

Configuring the connection

The client configuration file of Qaptiva Access is located in the configuration folder of QLMaaS. By default, this configuration folder is $HOME/.qlmaas but this location can be overrided by using the environment variable QLMAAS_DIR.

In this folder, the configuration file shoud be named config.ini and looks like:

Example of configuration
[Server]
hostname=qlmaas.bull.com
port=443
check_host=True
authentication=password
proxy_port=
proxy_host=None
timeout=1000

# Here this section is ignored since "authentication" is set to "password"
[SSL]
certificate=/path/to/ssl_cert.crt
key=/path/to/ssl_key.key

[Scheduling]
scheduling_info_builder=module:function

[Server]
# URL of the server (str)
hostname = ...

# Port listen by the server (int)
port = ...

# Should the server certificate be checked (True or False)
check_host = ...

# Authentication method (if "ssl": authentication with SSL certificate, if "password":
# authentication with username / password)
authentication = ...

# Hostname and port of an optional HTTPS proxy (SSL authentication is incompatible with proxy)
proxy_host = ...
proxy_port = ...

# Duration before timeout of the client connection (int, value in seconds)
timeout = ...

# This part is only used if "authentication" is set to "ssl"
[SSL]
# SSL certificate and key used to connect to the server (path x2)
certificate = ...
key = ...

# This part is used to have global scheduling info
[Scheduling]
# Pass a function that return a dict
scheduling_info_builder = ...

Warning

If proxy_host is set to None, instead of leaving the field empty, then http_proxy and https_proxy environment variables will be ignored, effectively forcing a no proxy connection. For relying on the environment variables, please do not set a value to proxy_host (remove the line or just leave the value empty).

An easy way of creating a configuration file is by using create_config(). This method creates a squeleton configuration file $HOME/.qlmaas/config.ini, mostly filled in with the information from the instanciated QLMaaSConnection.

If a configuration file is set, myQLM will be able to automatically connect to the Qaptiva server. Having a configuration enables the qlmaas module. This module can be used to instanciate remote QPUs or Plugins without instancing any QLMaaSConnection objects. Please refer to the documentation of the qlmaas module for more information.

Authenticating to the server

QLMaaS supports 3 authentication methods to connect to a remote Qaptiva Access server, but it can also supports custom authentication methods added by your administrator:

  1. By using a pair username/password (default method)

  2. By using a known certificate

  3. By using a trusted certificate

  4. Through custom authentication method added by your administrator

Authenticating with username/password (default)

Connecting with credentials (username and password) is available as soon as your account has been created.

Parameters required for connecting with this authentication method:

  • authentication = password (default value)

Saving credentials

Typing the password for every connection could be painful. To avoid typing the credentials every time, you can use either of two methods, the first one having precedence over the second:

  1. a netrc file containing the credentials used to connect to the Qaptiva Access server

  2. two environment variables containing the username and the password used to connect to the Qaptiva Access server. These two environment variables are:

    • QLM_USER: this environment variable contains the username

    • QLM_PASSWD: this environment variable contains the password

Changing your password
from qat.qlmaas import QLMaaSConnection
connection = QLMaaSConnection(...)

# will trigger interactive inputs allowing to change one's password
connection.change_password()

Changing an account password can be done with the change_password() interactive method, which does not take any argument, allowing for setting a new password when prompted.

This method requires for the user to have a way of connecting to the Qaptiva Access server in the first place. If you forgot your password and do not have an alternative way to connect, please contact an admin.

Note

This authentication method can be disabled by your administrator. Please ensure this authentication method is enabled for your account before login with credentials.

Authenticating with a known certificate

A SSL certificate can be used by a user to login on a Qaptiva Access server, even if this certificate has not been signed by a Certificate Authority. For this method, the user certificate must be uploaded on the server.

Parameters required for connecting with this authentication method:

  • authentication = ssl

  • certificate = /path/to/ssl_cert.crt

  • key = /path/to/ssl_key.key

Uploading SSL certificate
from qat.qlmaas import QLMaaSConnection
connection = QLMaaSConnection(...)

connection.save_certificate("/path/to/certificate.cer")

The save_certificate() method can be used to save an SSL certificate into your account (requires to login with credentials beforehand) if this hasn’t already been done by your administrator. If another certificate is already saved for this account, it will be overrided by the new one.

Note

This authentication method can be disabled by your administrator. Please ensure this authentication method is enabled for your account before using this authentication method.

Authenticating with a trusted certificate

This authentication method requires you to possess a certificate trusted by the Qaptiva Access server. For this method, your certificate must have its SSL DN (Distinguished name) saved into your account.

Parameters required for connecting with this authentication method:

  • authentication = ssl

  • certificate = /path/to/ssl_cert.crt

  • key = /path/to/ssl_key.key

Uploading your DN
from qat.qlmaas import QLMaaSConnection
connection = QLMaaSConnection()

# save the DN of the provided certificate
connection.save_ssl_dn(certificate="/path/to/certificate.cer")

# change the DN value directly
connection.save_ssl_dn(dn="my DN text")

The save_ssl_dn() method allows you to save an SSL DN into your Qaptiva Access account, if this hasn’t already been done by your administrator. If another SSL DN is already saved for this account, it will be overrided by the new one.

This method can take one of two keywords arguments:

  • dn: used for providing the DN directly

  • certificate: path to a certificate, which DN will be used

It is recommended to use the certificate keyword, since this will make sure that the DN uses the correct name convention.

Note

This authentication method can be disabled by your administrator. Please ensure this authentication method is enabled for your account before using this authentication method.

Authenticating with custom authentication method

Your administrator can also configure custom authentication method to the remote Qaptiva Access server. In this case, please refer to your administrator for the authentication method’s name, and also the required parameters to establish the connection.

Scheduling Configuration

The [Scheduling] section supports a single optional option named scheduling_info_builder. The entire section is optional and may be omitted.

Note

This option can only be specified in the configuration (.ini) file and cannot be provided as an argument when creating a QLMaaSConnection.

The scheduling_info_builder can be used to automatically attach a default set of scheduling information to every submit request sent to the Qaptiva Access remote server.

The value of scheduling_info_builder must be a function specified using the format module:function, where:

  • The module must be importable from the Python environment (i.e. available in PYTHONPATH or sys.path).

  • The function must return a value of type dict.

If an error occurs when qlmaas is initialized, warnings are emitted depending of the error:

UserWarning: The module given for the global scheduling info builder:
'...' is not found. Continuing without global scheduling info

Scheduling Information Merging

The dictionary returned by scheduling_info_builder is merged with the scheduling_info dictionary provided when submitting a job.

Note

If the same key exists in both dictionaries, the value provided in scheduling_info takes precedence.

Example of usage

On HPC clusters using, jobs are often associated with an account (--account) used for resource accounting. In many environments, users are also associated with a default project.

A scheduling_info_builder can automatically populate this information for every submitted job, so users do not need to specify it explicitly.

For example, create a module named scheduling.py:

import os

def build_scheduling_info():
    return {
        # Account used for SLURM accounting
        "account": os.environ.get("USER_ACCOUNT", "default_account"),

        # Default project associated with the user
        "project": os.environ.get("USER_PROJECT", "default_project"),
    }

Then reference the builder in the configuration file:

[Scheduling]
scheduling_info_builder = scheduling:build_scheduling_info

Every submitted job will automatically include these scheduling informations.

Connecting to a Qaptiva Access server

The class QLMaaSConnection is used to connect, get information and submit requests to a Qaptiva Access server.

from qat.qlmaas import QLMaaSConnection

# if using a configuration file
connection = QLMaaSConnection()

# if not, provide the necessary arguments
connection = QLMaaSConnection(hostname="...", port=...)