15. Licensing¶

15.1. Machine Identification ¶

The FORCESPRO licensing system works by receiving unique identifiers from the machines the software runs on and enabling the machines by activating the corresponding unique identifiers. Activation of machines can be done by receiving the unique identifiers of the machines using fingerprinting executables provided in the portal and adding those unique identifiers on the portal.

For more information on machine activation see: https://my.embotech.com/readme

15.1.1. Client Identification ¶

Machines running FORCESPRO clients are licensed using the machine’s username and the machine’s unique identifier.

15.1.2. Solver Identification ¶

Machines running FORCESPRO solvers are licensed using the machine’s unique identifier.

15.2. Static License ¶

When generating a solver the license’s state on the portal (enabled machines and expiration) is saved in the solver so that the solver can run on the enabled machines.

15.2.1. System requirements for static license ¶

The requirement for static license checking is to have correct system clock settings (accurately showing current time, compliant to UTC time).

15.2.2. Generating solvers with static license ¶

Static license checking is automatically enabled on a generated solver.

15.2.3. Running solvers with static license ¶

After generating a solver, you can move it to the running platform and build it with the rest of your project.

15.3. License Files ¶

License Files are used in order to enable solvers to run in machines that were not enabled during the time of code generation or to enable solvers to run after a license renewal (that happened after solver code generation).

15.3.1. System requirements for license files ¶

The requirements for using license files are:

A platform supporting I/O operations
A platform with access to file system
Correct system clock settings (accurately showing current time, compliant to UTC time)
Using the MATLAB interface of FORCESPRO

15.3.2. Generating solvers with license files ¶

License file checking is automatically enabled on a generated solver (supposing the platform supports it). The user has the option to select the name of the license file using the following codeoption:

% MATLAB
codeoptions.license.static_license_file_name = '<filename_without_extension>'; % no paths, only filename

% Python
codeoptions.license.static_license_file_name = '<filename_without_extension>' # no paths, only filename

Important

The license file name must be a valid variable name

Note

Until FORCESPRO 5.0.0, the name of the license file could be set using the option codeoptions.license_file_name. This codeoption has been kept for backwards compatibility, however, setting the new option will override it.

15.3.3. Generating license files ¶

License files can be created by using the MATLAB function ForcesGetLicenseFile. This function can be called with the following (optional) arguments:

license file name: Name to be given to created license file (without extension). Default value: FORCESPRO
server: FORCESPRO server to use to generate the license file. Default value: default server used by client

For more information on function usage run: help ForcesGetLicenseFile in the MATLAB Command Window.

15.3.4. Running solvers with license files ¶

After generating a solver, you can move it to the running platform and build it with the rest of your project. After generating a license file, you can move it to your project folder.

When running a solver:

The solver will read the license file and validate the license
The license file needs to be in the working directory in which you execute your project (usually the directory that contains the executable)

15.4. Floating Licenses ¶

Floating Licenses are used when the system that is enabled for running solvers needs to frequently change or is a virtualized environment (such as Docker or Virtualbox). The licensing works by getting a temporary local lease from the floating license server in order to be able to run a solver on a machine. The connection to the floating license server is performed via a proxy server which receives the requests from the solvers, contacts the online floating license server to receive the floating license and provides it to the solver.

15.4.1. Floating Licenses Proxy ¶

The deployment scenarios running FORCESPRO solvers do not always include the provision of an internet connection to the deployment machines. Instead, the deployment machines are managed by a centralized mechanism. The Floating Licenses Proxy allows to use this functionality for the provision of the FORCESPRO floating licenses. The Proxy can be set up either as a standalone application or as a web server in a machine which has network access with the deployment machines which will run the FORCESPRO solvers (without the need of an internet connection). This machine will listen for requests from the FORCESPRO solvers running in the deployment machines, perform the request on the online floating license server and finally return the acquired license leases to the FORCESPRO solvers. This way, the only machine requiring an internet connection will be the one running the Proxy. The solvers can be configured during code generation to which machine to connect to, in order to access the Floating Licenses Proxy. The packages for the Floating Licenses Proxy can be acquired in the Customer Portal in the Engineering Nodes view.

15.4.2. System requirements for floating licenses ¶

The requirements for running the floating licenses proxy:

A x86/x86_64 Windows or Linux platform
An internet connection
Correct system clock settings (accurately showing current time, compliant to UTC time)
OS specific system or packages requirements can be found in the manual of the Floating Licenses Proxy

The requirements for enabling solvers with floating licenses are:

A x86/x86_64 Linux platform
A network connection of the running platform to the machine running the floating licenses proxy
Correct system clock settings (accurately showing current time, compliant to UTC time)

15.4.3. Using the Floating Licenses Proxy ¶

The Floating Licenses Proxy can be run as a standalone application or as a web server. Once run, no further actions are required on the Proxy’s side. The FORCESPRO solvers will connect to it and receive the license leases to be validated for execution.

15.4.4. Floating License Attributes ¶

Floating licenses are defined by the following two fields:

Number of Licenses: The number of machines that can run solvers concurrently using a floating license for a FORCESPRO user.
Lease Time: The time for which a local lease is valid after it has been granted. Default lease time is 10 minutes. Please contact support@embotech.com to change this.

15.4.5. Generating solvers with floating licenses ¶

To enable floating licenses on a generated solver use the following codeoption:

% MATLAB
codeoptions.license.use_floating_license = 1;

# Python
codeoptions.license.use_floating_license = 1

And select the platform to use

% MATLAB
codeoptions.platform = 'platform_name';

# Python
codeoptions.platform = "platform_name"

Available platform options are:

Gnu-x86
Gnu-x86_64
Docker-Gnu-x86
Docker-Gnu-x86_64

Note

Until FORCESPRO 5.0.0, enabling floating licenses was done using the codeoption codeoptions.useFloatingLicense. This codeoption has been kept for backwards compatibility, however, setting the new option will override it.

15.4.6. Configure floating licenses during code generation ¶

During code generation, the following codeoptions are available to configure the floating license check:

codeoptions.license.floating_license_server: Selects the hostname or ip address of the machine which is running the floating license proxy for the solver to connect to. The floating license server must be a valid uri. Default value is localhost
codeoptions.license.floating_license_port: Selects the port of the machine which is running the floating license proxy for the solver to connect to. The floating license server must be a valid port number. Default value is 5000
codeoptions.license.floating_license_file_name: Sets the name for the local file created for the floating license. The floating license file name must be a valid variable name. Default value is the solvername
codeoptions.license.floating_license_retries: Sets the number of retries to connect to the floating license server in case a connection fails. Default value is 3

Note

If the FORCESPRO solver is run in a docker container and the Floating Licenses Proxy is run in the host of the same machine, in order for the solver to access the proxy codeoptions.license.floating_license_server should be set as ‘host.docker.internal’. In a Linux host, the docker container needs to provide access to the host for host.docker.internal by using the runtime option –add-host=. Depending on the docker version and the setup, the option value would be: host.docker.internal:host-gateway (i.e. –add-host=host.docker.internal:host-gateway), host.docker.internal:172.17.0.1 or host.docker.internal:<bridge-gateway-ip> where <bridge-gateway-ip> is the IP of the gateway of the bridge network to the host. In a Dockerfile, the value for host.docker.internal can be added under the entry extra_hosts:.

15.4.7. Running solvers with floating licenses ¶

After generating a solver, you can move it to the running platform and build it with the rest of your project.

When running a solver:

The solver will communicate with the Floating Licenses Proxy
The Proxy will perform the request on the online floating license server
If the number of enabled machines has not exceeded the license limits, a license lease will be returned
If a lease had already been granted for a machine (and is still valid) the license will be extended to match the set lease time and will be returned
The Proxy will return the accepted license lease to the FORCESPRO solver
The solver will save the lease locally and run
If a valid local lease already exists the solver will run without communicating with the server

When the floating license check is enabled, the run-time parameter receive_floating_license is available. Setting it to 1 will cause the solver to run only the license check, acquire the floating license and return. This can be used to acquire the floating license early and avoid connecting to the floating license server in subsequent executions when running the solver initialized with the problem.