COPT Floating Licensing service¶
The Cardinal Optimizer provides COPT Floating Token Server on all supported platforms, who serve license tokens to COPT client applications over local network.
Once you have floating license properly installed, server owns a set of license tokens up to number described in the license file. Any properly configured COPT client of the same version can request a token from server and release it whenever quit.
Server Setup¶
The application of COPT Floating Token server includes copt_flserver executable
and a configuration file fls.ini. The very first thing to do when server starts
is to verify floating license locally, whose location is specified in fls.ini.
If local validation passes, server connects to remote COPT licensing server for further
validation, including machine IP, which is supposed to match IP range that user provided
during registration. This means the machine running COPT Floating Token Server
should have internet access in specified area.
For details, please see descriptions below or refer to
How to obtain and setup license.
Installation¶
The Cardinal Optimizer provides a separate package for remote services, which include COPT floating token server. Users may apply for remote package from customer service. Afterwards, unzip the remote package and move to any folder on your computer. The software is portable and does not change anything in the system it runs on. Below are details of installation.
Windows
Please unzip the remote package and move to any folder. Though, it is common
to move to folder under C:\Program Files.
Linux
To unzip the remote package, enter the following command in terminal:
tar -xzf CardinalOptimizer-Remote-7.1.1-lnx64.tar.gz
Then, the following command moves folder copt_remote71 in current
directory to other path. For an example, admin user may move it to folder
under /opt and standard user may move it to $HOME.
sudo mv copt_remote71 /opt
Note that it requires root privilege to execute this command.
MacOS
To unzip the remote package, enter the following command in terminal:
tar -xzf CardinalOptimizer-Remote-7.1.1-universal_mac.tar.gz
Then, the following command moves folder copt_remote71 in current
directory to other path. For an example, admin user may move it to folder
under /Applications and standard user may move it to $HOME.
mv copt_remote71 /Applications
Floating License¶
After installing COPT remote package, it requirs floating license to run.
It is prefered to save floating license files, license.dat and
license.key, to floating folder in path of remote package.
The following explains how to obtain the license file
via the copt_licgen tool and the license credential information key under different systems.
Note
If the user has already obtained the two license files license.dat and license.key, there is no need to obtain them again.
You can skip the following steps to obtain the license file and refer to Configuration directly.
Windows
If the COPT remote package is installed under "C:\Program Files",
execute the following command to enter floating folder in path of
remote package.
cd "C:\Program Files\copt_remote71\floating"
Note that the tool copt_licgen creating license files exists
under tools folder in path of remote package. The following command
creates floating license files in current directory, given a floating
license key, such as 7483dff0863ffdae9fff697d3573e8bc .
..\tools\copt_licgen -key 7483dff0863ffdae9fff697d3573e8bc
Linux and MacOS
If the COPT remote package is installed under "/Applications",
execute the following command to enter floating folder in path of
remote package on MacOS system.
cd /Applications/copt_remote71/floating
The following command creates floating license files in current directory,
given a floating license key, such as 7483dff0863ffdae9fff697d3573e8bc .
../tools/copt_licgen -key 7483dff0863ffdae9fff697d3573e8bc
In addition, if users run the above command when current directory is
different than floating folder in path of remote package, it is prefered
to move them to floating. The following command does so.
mv license.* /Application/copt_remote71/floating
Configuration¶
Below is a typical configuration file, fls.ini, of COPT Floating Token Server.
[Main]
Port=7979
[Licensing]
# if empty or default license name, it is from binary folder
# to get license files from cwd, add prefix "./"
# full path is supported as well
LicenseFile = license.dat
PubkeyFile = license.key
[WLS]
# WebServer have a default host and no need to edit in most scenarios
# Must specify WebLicenseId and WebAccesskey to trigger web licensing
WebServer =
WebLicenseId =
WebAccessKey =
WebTokenDuration = 300
[Filter]
# default policy 0 indicates accepting all connections, except for ones in blacklist
# otherwise, denying all connections except for ones in whitelist
DefaultPolicy = 0
UseBlackList = true
UseWhiteList = true
FilterListFile = flsfilters.ini
The Main section specifies port number, through which COPT clients connect to server
and then obtain the license token. The Licensing section specifies location of
floating license. As described in comments above, if emtpy string or default license file name
is specified, floating license files are read from the binary folder where
the server executable reside.
It is possible to run COPT Floating Token server, even if
floating license files do not exist in the same folder as the server executive.
One solution is to set LicenseFile = ./license.dat and PubkeyFile = ./license.key.
By doing so, server read floating license from the current working directory.
That is, user could execute server application at the path where floating license files exist.
The other solution is to set full path of license files in configuration.
As mentioned before, Cardinal Optimizer allows users to set
environment variable COPT_LICENSE_DIR for license files. For details,
please refer to How to install Cardinal Optimizer.
If user prefers the way of environment variable, the configuration file should have
the full path to floating license.
In the Filter section, DefaultPolicy has default value 0, meaning
all connections are accepted except for those in black lists; if it is set
to non-zero value, then all connection are blocked except for those in white
lists. In addition, black list is enabled if UseBlackList is true and white list
is enabled if UseWhiteList is true. The filter configuration file is specified by
FilterListFile. Below is an example of the filter configuration file.
[BlackList]
# 127.0.*.* + user@machine*
[WhiteList]
# 127.0.1.2/16 - user@machine*
[ToolList]
# only tool client at server side can access by default
127.0.0.1/32
It has three sections and each section has its own rules. In section of BlackList,
one may add rules to block others from connection. In section of WhiteList,
one may add rules to grant others for connection, even if the default policy is to block
all connections. Only users listed in section of ToolList are able to connect to
floating token server by Floating Token Server Managing Tool (see below for details).
Specifically, rules in filter configuration have format of starting with IP address.
To specify IP range, you may include wildcard (*) in IP address, or use CIDR notation,
that is, a IPv4 address and its associated network prefix.
In addtion, a rule may include (+) or exclude (-) given user at given machine, such as
127.0.1.2/16 - user@machine. Here, user refers to username, which can be queried
by whoami on Linux/MacOS platform; machine refers to computer name, which can
be queried by hostname on Linux/MacOS platform.
Web License for Floating Server¶
Besides local floating license above, users may use web license for floating server to run floating service. This requires that the machine running floating server must have internet access. However, hardware info are not required any more. That is, users are free to deploy floating server to any cloud machine or container, as long as they have internet access. Please refer to COPT Web Licenses for details.
Below are brief steps:
Follow steps to register an account and apply for trial of web license for floating server.
Once approved, Web License ID is generated for users
On page of API Keys, create Web Access Key using given Web License ID
Afterwards, users edit configuration file fls.ini and add values of both Web License ID and Web Access Key to related keywords in section of WLS. For instance,
[Main]
Port=7979
[Licensing]
# if empty or default license name, it is from binary folder
# to get license files from cwd, add prefix "./"
# full path is supported as well
LicenseFile = license.dat
PubkeyFile = license.key
[WLS]
# WebServer have a default host and no need to edit in most scenarios
# Must specify WebLicenseId and WebAccesskey to trigger web licensing
WebServer =
WebLicenseId = d2d00f9d740c99e83509ef2ab49f2e99
WebAccessKey = 55508eeaacf249c68f479ec087fa7780
WebTokenDuration = 300
As of now, floating server talks to COPT Web Licenses for licensing. Users are able to monitor its token usage and other informations online.
Example Usage¶
Suppose that floating license exists in the same folder where the server executable reside. To start the COPT Floating Token Server, just execute the following command at any directory in Windows console, or Linux/Mac terminal.
copt_flserver
If you see log information as follows, the Floating Token Server has been
successfully started. Server monitors any connction from COPT clients,
manages approved clients as well as requests in queue. User can stop
Floating Token Server anytime when entering q or Q.
> copt_flserver [ Info] Floating Token Server, COPT v7.1.1 20240304 [ Info] server started at port 7979
If failed to verify local floating license, or something is wrong on remote COPT license server, you might see error logs as follows.
> copt_flserver [ Info] Floating Token Server, COPT v7.1.1 20240304 [Error] Invalid signature in public key file [Error] Fail to verify local license
and
> copt_flserver [ Info] Floating Token Server, COPT v7.1.1 20240304 [Error] Error to connect license server [Error] Fail to verify floating license by server
Client Setup¶
COPT Clients can be COPT command-line tool, or any application which solve problems using COPT api, such as COPT python interface. Floating licensing is a better approach in terms of flexibility and efficiency. Different from stand-alone license, any machine having properly configured COPT client can legally run Cardingal Optimizer, as long as peak number of connected clients does not exceed the token number.
Configuration¶
Before running COPT as floating client, please make sure that you have
installed COPT locally. For details, please refer to
How to install Cardinal Optimizer.
Users can skip obtaining local licenses by adding a floating configuration
file client.ini.
Below is a typical configuration file, client.ini, of COPT floating clients.
Host = 192.168.1.11
Port = 7979
QueueTime = 600
As configured above, COPT floating client tries to connect to 192.168.1.11 at port 7979
with wait time in queue up to 600 seconds. Here, Host is set to localhost if empty
or not specified; QueueTime is set to 0 if empty or not specified. Specifically,
empty QueueTime means client does not wait and should quit immediately, if COPT Floating
Token Server have no tokens available. Port number must be great than zero and should be
the same as that specified in server configuration file.
Note that keywords in the client configuration file are case insensitive.
Without local license files, a COPT application still works if client configuration
file, client.ini, exists in one of the following three locations in order, that is,
current working directory, environment directory by COPT_LICENSE_DIR and binary
directory where COPT executable is located.
By design, COPT application reads local license files instead of client configuration file,
if they both exist in the same location. On the other hand, if local license files are under
the environment directory, to activate approach of floating licensing, user can simply
add a configuration file, client.ini, under the current working directory (different from
the environment directory).
If a COPT application calls COPT api to solve problems, such as COPT python interface,
license is checked as soon as COPT environment object is created. If there exists proper client
configuration file, client.ini, a license token is granted to COPT client. This license
token is released and sent back to token server, as soon as last COPT environment object in the
same process destroys.
Example Usage¶
Suppose that we’ve set client configuration file client.ini properly and have no local
license, below is an example of obtaining a floating token by COPT command-line tool
copt_cmd. Execute the following command in Windows console, or Linux/Mac terminal.
copt_cmd
If you see log information as follows, the COPT client, copt_cmd, has obtained the
floating token successfully. COPT command-line tool is ready to solve optimization problems.
> copt_cmd Cardinal Optimizer v7.1.1. Build date Mar 04 2024 Copyright Cardinal Operations 2024. All Rights Reserved [ Info] initialize floating client: ./client.ini [ Info] connecting to server ... [ Info] connection established COPT>
If you see log information as follows, the COPT client, copt_cmd, has connected to COPT
Floating Token Server. But due to limited number of tokens, client waits in queue of size 1.
> copt_cmd Cardinal Optimizer v7.1.1. Build date Mar 04 2024 Copyright Cardinal Operations 2024. All Rights Reserved [ Info] Initialize floating client: ./client.ini [ Info] connecting to server ... [Error] empty license and queue size 1 [ Info] Wait for license in 2 / 39 secs [ Info] Wait for license in 4 / 39 secs [ Info] Wait for license in 6 / 39 secs [ Info] Wait for license in 8 / 39 secs [ Info] Wait for license in 10 / 39 secs [ Info] Wait for license in 20 / 39 secs [ Info] Wait for license in 30 / 39 secs
If you see log information as follows, the COPT client, copt_cmd, has connected to COPT
Floating Token Server. But client refused to wait in queue, as Queuetime is 0.
> copt_cmd Cardinal Optimizer v7.1.1. Build date Mar 04 2024 Copyright Cardinal Operations 2024. All Rights Reserved [ Info] Initialize floating client: ./client.ini [ Info] connecting to server ... [Error] Server error: "no more token available", code = 2 [Error] Fail to open: ./license.dat [Error] Fail to initialize cmdline
If you see log information as follows, the COPT client, copt_cmd, fails to connect to COPT
Floating Token Server. Finally, client quits after time limit.
> copt_cmd Cardinal Optimizer v7.1.1. Build date Mar 04 2024 Copyright Cardinal Operations 2024. All Rights Reserved [ Info] initialize floating client: ./client.ini [ Info] connecting to server ... [ Info] wait for license in 2 / 10 secs [ Info] wait for license in 4 / 10 secs [ Info] wait for license in 6 / 10 secs [ Info] wait for license in 8 / 10 secs [ Info] wait for license in 10 / 10 secs [Error] timeout at waiting for license [Error] fail to open: ./license.dat [Error] Fail to initialize cmdline
Floating Token Server Managing Tool¶
COPT floating token service ships with a tool copt_flstool, for retrieving information
and tune parameters of floating token server on fly.
Tool Usage¶
Execute the following command in Windows console, Linux or MacOS terminal:
> copt_flstool
Below displays help messages of this tool:
> copt_flstool
COPT Floating Token Server Managing Tool
copt_flstool [-s server ip] [-p port] [-x passwd] command <param>
commands are: addblackrule <127.0.0.1/20[-user@machine]>
addwhiterule <127.0.*.*[+user@machine]>
getfilters
getinfo
resetfilters
setpasswd <xxx>
toggleblackrule <n-th>
togglewhiterule <n-th>
writefilters
If the -s and -p option are present, tool connects to floating token server
with given server IP and port. Otherwise, tool connections to localhost and
default port 7878. If floating token server sets a password, tool must provide
password string after the -x option.
This tool provides the following commands:
AddBlackRule: Add a new rule in black filters. each rule has format starting with non-empty IP address, which may have wildcard to match IPs in the scope. In addition, it is optional to be followed by including (+) or excluding (-) user name at machine name.AddWhiteRule: Add a new rule in white filters. Note that a white rule has the same format as a black rule.GetFilters: Get all rules of black filters, white filters and tool filters, along with relative sequence numbers, which are parameters for command ToggleBlackRule and ToggleWhiteRule.GetInfo: Get general information of floating token server, including token usage, connected clients, and all COPT versions in support.ResetFilters: Reset filter lists in memory to those on filter config file.SetPasswd: Update password of target floating token server on fly.ToggleBlackRule: Toggle between enabling and disabling a black rule, given its sequence number by GetFilters.ToggleWhiteRule: Toggle between enabling and disabling a white rule, given its sequence number by GetFilters.WriteFilters: Write filter lists in memory to filter config file.
Example Usage¶
The following command lists general information on local machine.
> copt_flstool GetInfo [ Info] COPT Floating Token Server Managing Tool, COPT v7.1.1 20240304 [ Info] connecting to localhost:7979 [ Info] [command] wait for connecting to floating token server [ Info] [floating] general info # of available tokens is 3 / 3, queue size is 0 # of active clients is 0
To run managing tool on other machine, its IP should be added to
a rule in ToolList section in filter configuration file flsfilters.ini.
The following command from other machine lists information of server 192.168.1.11.
> copt_flstool -s 192.168.1.11 GetInfo [ Info] COPT Floating Token Server Managing Tool, COPT v7.1.1 20240304 [ Info] connecting to 192.168.1.11:7979 [ Info] [command] wait for connecting to floating token server [ Info] [floating] general info # of available tokens is 3 / 3, queue size is 0 # of active clients is 0
The following command shows all filter lists of server 192.168.1.11, including those in BlackList section, WhiteList section and ToolList section.
> copt_flstool -s 192.168.1.11 GetFilters [ Info] COPT Floating Token Server Managing Tool, COPT v7.1.1 20240304 [ Info] connecting to 192.168.1.11:7979 [ Info] [command] wait for connecting to floating token server [ Info] [floating] filters info [BlackList] [WhiteList] [ToolList] [1] 127.0.0.1
The following command added user of IP 192.168.3.13 to black list.
> copt_flstool -s 192.168.1.11 AddBlackRule 192.168.3.133 [ Info] COPT Floating Token Server Managing Tool, COPT v7.1.1 20240304 [ Info] connecting to 192.168.1.11:7979 [ Info] [command] wait for connecting to floating token server [ Info] [floating] server added new black rule (succeeded)
The follwing command shows that a new rule in BlackList section is added.
> copt_flstool -s 192.168.1.11 GetFilters [ Info] COPT Floating Token Server Managing Tool, COPT v7.1.1 20240304 [ Info] connecting to 192.168.1.11:7979 [ Info] [command] wait for connecting to floating token server [ Info] [floating] filters info [BlackList] [1] 192.168.3.133 [WhiteList] [ToolList] [1] 127.0.0.1
The following command disable a rule in BlackList section.
> copt_flstool -s 192.168.1.11 ToggleBlackRule 1 [ Info] COPT Floating Token Server Managing Tool, COPT v7.1.1 20240304 [ Info] connecting to 192.168.1.11:7979 [ Info] [command] wait for connecting to floating token server [ Info] [floating] server toggle black rule [1] (succeeded)
Running as service¶
To run COPT floating token server as a system service, follow steps described
in readme.txt under floating folder, and set config file
copt_flserver.service properly.
Below is readme.txt, which lists installing steps in both Linux and MacOS
platforms.
[Linux] To run copt_flserver as a service with systemd
Add a systemd file
copy copt_flserver.service to /lib/systemd/system/
sudo systemctl daemon-reload
Enable new service
sudo systemctl start copt_flserver.service
or
sudo systemctl enable copt_flserver.service
Restart service
sudo systemctl restart copt_flserver.service
Stop service
sudo systemctl stop copt_flserver.service
or
sudo systemctl disable copt_flserver.service
Verify service is running
sudo systemctl status copt_flserver.service
[MacOS] To run copt_flserver as a service with launchctrl
Add a plist file
copy copt_flserver.plist to /Library/LaunchAgents as current user
or
copy copt_flserver.plist to /Library/LaunchDaemons with the key 'UserName'
Enable new service
sudo launchctl load -w /Library/LaunchAgents/copt_flserver.plist
or
sudo launchctl load -w /Library/LaunchDaemons/copt_flserver.plist
Stop service
sudo launchctl unload -w /Library/LaunchAgents/copt_flserver.plist
or
sudo launchctl unload -w /Library/LaunchDaemons/copt_flserver.plist
Verify service is running
sudo launchctl list shanshu.copt.flserver
Linux¶
Below are steps in details of how to run COPT floating token server as a system service in Linux platform.
For instance, assume that COPT remote service is installed under '/home/eleven'.
In your terminal, type the following command to enter the root directory of
floating service.
cd /home/eleven/copt_remote71/floating
modify template of the service config file copt_flserver.service in text format:
[Unit]
Description=COPT Floating Token Server
[Service]
WorkingDirectory=/path/to/service
ExecStart=/path/to/service/copt_flserver
Restart=always
RestartSec=1
[Install]
WantedBy=multi-user.target
That is, update template path in keyword WorkingDirectory and ExecStart to
actual path where the floating service exits.
[Unit] Description=COPT Floating Token Server [Service] WorkingDirectory=/home/eleven/copt_remote71/floating ExecStart=/home/eleven/copt_remote71/floating/copt_flserver Restart=always RestartSec=1 [Install] WantedBy=multi-user.target
Afterwards, copy copt_flserver.service to system service folder
/lib/systemd/system/ (see below).
sudo cp copt_flserver.service /lib/systemd/system/
The following command may be needed if you add or update service config file. It is not needed if service unit has been loaded before.
sudo systemctl daemon-reload
The following command starts the new floating service.
sudo systemctl start copt_flserver.service
To verify the floating service is actually running, type the following command
sudo systemctl status copt_flserver.service
If you see logs similar to below, COPT floating server is running successfully as a system service.
copt_flserver.service - COPT Floating Token Server
Loaded: loaded (/lib/systemd/system/copt_flserver.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2021-06-29 11:46:10 CST; 3s ago
Main PID: 3054 (copt_flserver)
Tasks: 6 (limit: 4915)
CGroup: /system.slice/copt_flserver.service
└─3054 /home/eleven/copt_remote71/floating/copt_flserver
eleven-ubuntu systemd[1]: Started COPT Floating Token Server.
eleven-ubuntu COPTCLS[3054]: LWS: 4.1.4-b2011a00, loglevel 1039
eleven-ubuntu COPTCLS[3054]: NET CLI SRV H1 H2 WS IPv6-absent
eleven-ubuntu COPTCLS[3054]: server started at port 7979
To stop the floating service, type the following command
sudo systemctl stop copt_flserver.service
MacOS¶
Below are steps in details of how to run COPT floating token server as a system service in MacOS platform.
For instance, assume that COPT remote service is installed under '/Applications'.
In your terminal, type the following command to enter the root directory of
floating service.
cd /Applications/copt_remote71/floating
modify template of the service config file copt_flserver.plist in xml format:
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
<key>Label</key>
<string>shanshu.copt.flserver</string>
<key>Program</key>
<string>/path/to/service/copt_flserver</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
</dict>
</plist>
That is, update template path in Program tag to
actual path where the floating service exits.
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
<key>Label</key>
<string>shanshu.copt.flserver</string>
<key>Program</key>
<string>/Applications/copt_remote71/floating/copt_flserver</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
</dict>
</plist>
Afterwards, copy copt_flserver.plist to system service folder
/Library/LaunchAgents (see below).
sudo cp copt_flserver.plist /Library/LaunchAgents
The following command starts the new floating service.
sudo launchctl load -w /Library/LaunchAgents/copt_flserver.plist
To verify the floating service is actually running, type the following command
sudo launchctl list shanshu.copt.flserver
If you see logs similar to below, COPT floating server is running successfully as a system service.
{
"LimitLoadToSessionType" = "System";
"Label" = "shanshu.copt.flserver";
"OnDemand" = false;
"LastExitStatus" = 0;
"PID" = 16406;
"Program" = "/Applications/copt_remote71/floating/copt_flserver";
};
To stop the floating service, type the following command
sudo launchctl unload -w /Library/LaunchAgents/copt_flserver.plist
If the floating service should be run by a specific user, add UserName tag to conifg file.
Below adds a user eleven, who has priviledge to run the floating service.
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
<key>Label</key>
<string>shanshu.copt.flserver</string>
<key>Program</key>
<string>/Applications/copt_remote71/floating/copt_flserver</string>
<key>UserName</key>
<string>eleven</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
</dict>
</plist>
Then copy new copt_flserver.plist to system service folder
/Library/LaunchDaemons (see below).
sudo cp copt_flserver.plist /Library/LaunchDaemons
The following command starts the new floating service.
sudo launchctl load -w /Library/LaunchDaemons/copt_flserver.plist
To stop the floating service, type the following command
sudo launchctl unload -w /Library/LaunchDaemons/copt_flserver.plist