Client Configuration¶
In this section, we assume that you already have installed the Gurobi
Optimizer package on your client machine. After this, you will need to
understand the role of the client license file
and how grbcluster
can help in generating it. Finally, we will
review the
load balancing and priority management that can
be controlled with some of the configuration properties.
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 macOSThe 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, orhttps://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
andCSAPISECRET
JWT authentication token with
CSAUTHTOKEN
Username and password with
USERNAME
andPASSWORD
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, orhttps://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 aJOB_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.
Generating a Client License with grbcluster¶
Your primary tool for issuing cluster commands is a command-line program
called grbcluster
. The format of the command-line tool is as follows
(see the reference section for more
information):
grbcluster --help Display usage
grbcluster command [flags] Execute a top-level command
grbcluster command --help Display help about a top-level command
grbcluster group command [flags] Execute a command from a group
grbcluster group command --help Display help about a command
from a group
The first important command is the login
command, which accepts
various flags to allow you to configure your connection. Once your
connection is validated, it will save these parameters into the license
file. If the license file does not exist, it will create one. If you
want to store the license file in a custom location, you can use the
environment variable GRB_LICENSE_FILE
. The command tools
grbcluster
, gurobi_cl
, and grbtune
will first read the
client license file so that you do not need to specify connection
parameters each time.
Here are some examples of the login
command :
Log in to a Cluster Manager with a username and password:
grbcluster login --manager=http://mymanager:61080 --username=gurobi
Note that if a password is necessary, you will be prompted for it. This is more secure than providing one on the command line, but that is an option too (using the
—-password
flag).Refresh login to a Cluster Manager to extend an expired session:
grbcluster login
Log in to a Cluster Manager with an API key:
grbcluster login --manager=http://mymanager:61080 --access=... --secret=...
Log in to a Compute Server in a self-managed cluster:
grbcluster login --server=http://server1:61000
Log in to a Compute Server that uses a router:
grbcluster login --server=http://server1:61001 --router=http://myrouter:61000
Queueing, Load Balancing, and Job Priorities¶
As noted earlier, Gurobi Compute Servers support job priorities. You can
assign an integer priority between -100 and 100 to each job (the default
is 0). When choosing among queued jobs, the Compute Server will run the
highest priority job first. Note that servers will never preempt running
jobs. You can set the priority in the client license file, or using the
PRIORITY
parameter in the programming language APIs.
We have chosen to give priority 100 a special meaning. A priority 100
job will start immediately, even if this means that a server will exceed
its job limit. You should be cautious with priority 100 jobs, since
submitting too many at once could lead to very high server loads, which
could lead to poor performance and even crashes in extreme cases. Note
that this feature must be enabled by the system administrator using the
HARDJOBLIMIT
configuration property.
With the Remote Services grouping feature, the system administrator may have assigned groups to the cluster nodes. This can be quite useful when some nodes in the cluster are different from others. For example, some nodes may have more memory or faster CPUs. Using this feature, you can force jobs to only run on the appropriate type of machines. If all nodes of the requested group are at capacity, jobs will be queued until a member of that group is available.
You can submit an optimization job to a given group by using the
GROUP
property of the client license file. You can also set the
CSGROUP
parameter in the programming interface.
You can use this parameter to target a single group or a list of groups, and you can specify a priority for each group. Here is an example that shows how you would use this parameter to submit a job to group1 with priority 10 and to group2 with priority 50.
group1:10,group2:50
Note that if no group specified for the submitted job, the job can run on any node.