Client License File
A client program needs to be told how to reach a Remote
Services cluster. There are generally two ways to do this. The first
is through the programming language APIs. We'll discuss this option
in a later section on programming with Remote
Services. The second is
through a license file. You can create a client license file yourself
or edit an existing one, using your favorite text editor
(Notepad is a good choice on Windows). The license file should
be named gurobi.lic.
The license file contains a list of properties of the form
PROPERTY=value. Lines that begin with the # symbol are treated
as comments and are ignored. The license file must be placed
in one of the following locations:
- C:\gurobi\ on Windows
- /opt/gurobi/ on Linux
- /Library/gurobi/ on macOS
- The user's home directory
You can also set the environment variable GRB_LICENSE_FILE to
point to this file.
Connecting to a Cluster Manager
Here are the properties you can set to connect to a Cluster Manager:
- CSMANAGER
- The URL of the Cluster Manager, including the protocol scheme and port.
For example, use http://mymanager:61080 to access a Cluster Manager using HTTP on
port 61080, or https://mymanager:61443 to
access a cluster over HTTPS on port 61443.
- CSAPIACCESSID
- A unique identifier used to authenticate an application on a cluster.
- CSAPISECRET
- The secret password associated with an API access ID.
- USERNAME
- The username to access the cluster.
- PASSWORD
- The client password to access the cluster.
- CSAUTHTOKEN
- Used internally to store the JWT authentication token.
These don't all need to be set - you just set the properties that are
relevant for the authentication method you are using. If the license
file specifies several authentication methods to a Cluster Manager,
the following precedence order applies:
- API key defined with CSAPIACCESSID and CSAPISECRET
- JWT authentication token with CSAUTHTOKEN
- Username and password with USERNAME and PASSWORD
Connecting to a Cluster Node
Here are the properties you can set to connect to a cluster node in a
self-managed cluster:
- COMPUTESERVER
- The fully qualified name of the main node used to
access the cluster, plus the protocol scheme and port (if needed).
For example, you can just use server1 to access a
cluster using HTTP on the default port, or https://server1:61000 to access a cluster over HTTPS using port
61000. You can also specify a comma-separated list of names so that
other nodes can be used in case the first node can't be reached.
- ROUTER
- The router URL (if you are using a router).
- PASSWORD
- The client password to access the cluster.
Note that clients must provide the original password (not hashed) and it will
be exchanged encrypted if HTTPS is used.
Other Properties
You can also specify additional properties that affect job processing
(whether you use a Cluster Manager or not):
- CSAPPNAME
- Application name. Once defined, the application name will be assigned to
all jobs and batches created so that you can better track the activity of the cluster
by application.
- PRIORITY
- Job Priority. Higher priority jobs take precedence
over lower priority jobs.
- GROUP
- Job group. If your cluster has been set up with groups,
you can specify the group to submit the job to. The job will only be
executed on nodes that are members of this group if specified. The value of this
property can also be a list of groups, and you can also specify a priority for each
group. For example: group1:10,group2:50
- QUEUETIMEOUT
- Queuing timeout (in seconds). A job that has been sitting in the
queue for longer than the specified QUEUETIMEOUT value
will return with a JOB_REJECTED error.
- IDLETIMEOUT
- Idle job timeout (in seconds). This property allows you to set a limit
on how long a Compute Server job can sit idle before the server kills the job.
Examples
Here is an example of a client license file that would allow a client
to connect to a Cluster Manager with an API key, and submit all the
jobs under a specific application name:
CSMANAGER=http://mymanager:61080
CSAPIACCESSID=0e8c35d5-ff20-4e5d-a639-10105e56b264
CSAPISECRET=d588f010-ad47-4310-933e-1902057661c9
CSAPPNAME=app1
Here is another example that would allow you to connect a self-managed
Compute Server with a specific password, and submit all the jobs with
priority 10:
COMPUTESERVER=http://server1:61000
PASSWORD=abcd
PRIORITY=10
The gurobi_cl or grbcluster tools provide command-line
flags that allow you to set most of these properties. These tools
will read the license file, but values specified via these
command-line flags will override any values provided in the license
file.