Installing a Cluster Manager¶

Setting up the optional Cluster Manager involves a few steps. You first need to install the MongoDB database, which the Cluster Manager uses to store its data. Then, the Cluster Manager server must be configured and started (as a standard process or as a service). Finally, you will need to verify your installation.

Installing the Database¶

The Cluster Manager uses a database to store the data associated with several important features: user profiles, API keys, job history, batch definitions, and batch data.

The Cluster Manager can be connected to three types of database servers (see the release notes for the supported versions):

MongoDB, deployed on-premise, on the Cloud, or hosted by a SaaS provider.
Amazon Web Services (AWS) DocumentDB, when deployed to AWS.
Azure CosmosDB, when deployed to Microsoft Azure.

MongoDB offers various configuration options, including clustering and encryption over the wire and at rest. Please follow the steps as explained in the official MongoDB documentation. The installation steps are well explained for each platform. When the installation is complete, the MongoDB daemon mongod should be running and ready for connections on port 27017 (the default). One other option, if you want to avoid installing the database yourself, would be to sign up for a hosted solution in the Cloud.

You can also set up an AWS DocumentDB database if you are deploying the Cluster Manager on the AWS platform (please, refer to their developer guide). DocumentDB offers various configuration options, including clustering and encryption over the wire and at rest. Note that AWS DocumentDB cannot be installed on-premises.

If you are deploying the Cluster Manager on the Microsoft Azure platform, you can also use an Azure CosmosDB database (as explained in their documentation).

Once the database is installed or provisioned in the Cloud, please make a note of the connection string (which is a URL that will be provided to you during installation). We will need this URL to connect the Cluster Manager to the database. The URL has the following form. You should of course substitute the MongoDB username and password that you chose when installing the database:

mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[database][?options]]

If you have installed MongoDB on your personal machine for testing purposes, the connection string URL should be the following:

mongodb://localhost:27017

You can check that your connection string is correct by using the mongo shell and providing the connection string as the first argument:

> mongosh mongodb://localhost:27017
Connecting to:       mongodb://localhost:27017
Using MongoDB:          6.0.18
Using Mongosh:          2.3.1

Cluster Manager Server (grb_rsm)¶

You will need to choose one or more machines to act as your Cluster Manager(s). The primary tasks of the Cluster Manager are to provide an API gateway to the cluster and to manage cluster nodes. The Cluster Manager also acts as a web server for the Web User Interface. The cluster manager must be reachable on your network from all client machines and from all cluster nodes.

You will need to run the Cluster Manager executable (grb_rsm) on your Cluster Manager(s). If you wish to set up a scalable and high-available deployment, you can install and start several instances of the server and place a load balancer such as Nginx in front of these servers.

The grb_rsm executable provides several commands and flags to help with configuration and execution. We will review these commands step by step in the following sections. You can see the full list of commands in the reference section or by using the command-line help:

> grb_rsm --help

Configuring the Cluster Manager¶

The Cluster Manager server has a number of configuration properties that affect its behavior. These can be controlled using a grb_rsm.cnf configuration file. The installation package includes a predefined configuration file that can be used as a starting point (<installdir>/bin/grb_rsm.cnf).

The simplest way to modify the parameters is to edit the default configuration file. Other options are available, though. The grb_rsm process uses the following precedence rules:

First priority: properties set with a command-line flag (using —-config)
Second priority: a configuration file in the current directory
Third priority: a configuration file in a fixed, shared directory (C:\gurobi, /opt/gurobi, /Library/gurobi for Windows, Linux, and macOS platforms, respectively)
Fourth priority: a configuration file in the directory where grb_rsm is located

Most of the properties that are configured through this file are related to communication options or the database connection. The configuration file is read once, when grb_rsm first starts. Subsequent changes to the file won’t affect parameter values on a running server.

Configuration file format¶

The configuration file contains a list of properties of the form PROPERTY=value. Lines that begin with the # symbol are treated as comments and are ignored. Here is an example:

# grb_rsm.cnf configuration file
PORT=61080
CLUSTER_TOKEN=GRBTK-BzlUTKg9M/+HUvOpy/EPebc1CsttzOfdrfQshL4QkLm1FA==
DB_URI=mongodb://127.0.0.1:27017

While you could create this file from scratch, we recommend you start with the version that is included with the product and modify it instead.

The grb_rsm properties command lists all of the available properties, their default values, and provides documentation for each. Some can be overridden on the grb_rsm command line; the grb_rsm properties command shows the name of the command-line flag you would use. Here are some of the more important ones:

CLUSTER_TOKEN: The token is a private key that enables different nodes to join the same cluster. All nodes of a cluster and the Cluster Manager must have the same token. We recommended that you generate a brand new token when you set up your cluster. The grb_rs token command will generate a random token, which you can copy into the configuration file.
DB_URI: This is the connection string to your database.
PORT: This property indicates what port to use for HTTP or HTTPS communication between the clients and the Cluster Manager. By default, it will use the port 61080.

These properties let you configure some system-level options. You will find additional configuration properties in the settings page of the Cluster Manager. The settings are stored in the database and shared between the different Cluster Manager instances.

Starting the Cluster Manager as a Process¶

Once you have installed the Remote Services package, you can start grb_rsm as a standard process from a terminal window by simply typing grb_rsm. This will start the Cluster Manager server on the default port (port 61080):

> grb_rsm
info  : Gurobi Cluster Manager starting...
info  : Platform is linux
info  : Version is 12.0.0\ (build v12.0.0rc0)
info  : Connecting to database grb_rsm on 127.0.0.1:27017...
info  : Connected to database grb_rsm (version 4.0.4, host Server1)
info  : Checking 0 cluster nodes
info  : Creating proxy with MaxIdleConns=200 MaxIdleConnsPerHost=32 IdleConnTimeout=130
info  : Starting cluster manager server (HTTP) on port 61080...

If you’d like to run grb_rsm on a non-default port, use the —-port flag or set the PORT property in the configuration file. For example:

> grb_rsm --port=8080

Starting the Cluster Manager as a Service¶

While you always have the option of running grb_rsm from a terminal and leaving the process running in the background, we recommended that you start it as a service instead, especially in a production deployment. The advantage of a service is that it will automatically restart itself if the computer is restarted or if the process terminates unexpectedly.

grb_rsm provides several commands that help you to set it up as a service. These must be executed with administrator privileges:

grb_rsm install: Install the service. The details of exactly what this involves depend on the host operating system type and version: this uses systemd or upstart on Linux, launchd on macOS, and Windows services on Windows.
grb_rsm start: Start the service (and install it if it hasn’t already been installed).
grb_rsm stop: Stop the service.
grb_rsm restart: Stop and then start the service.
grb_rsm uninstall: Uninstall the service.

Note that the install command installs the service using default settings. If you don’t need to modify any of these, you can use the start command to both install and start the service. Otherwise, run install to register the service, then modify the configuration (the details are platform-dependent and are touched on below), and then run start the service.

Note that you only need to start the service once; grb_rsm will keep running until you execute the grb_rsm stop command. In particular, it will start again automatically if you restart the machine.

Note also that the start command does not accept any flags or additional parameters. All of the configuration properties must be set in the grb_rsm.cnf configuration file. If you need to make a change, edit the configuration file, then use the stop command followed by the start command to restart grb_rsm with the updated configuration.

The exact behavior of these commands varies depending on the host operating system and version:

Linux¶

On Linux, grb_rsm supports two major service managers: systemd and upstart. The install command will detect the service manager available on your system and will generate a service configuration file located in /etc/systemd/system/grb_rsm.service or /etc/init/grb_rsm.conf for systemd and upstart, respectively. Once the file is generated, you can edit it to set advanced properties. Please refer to the documentation of systemd or upstart to learn more about service configuration.

Use the start and stop commands to start and stop the service. When the service is running, log messages are sent to the Linux syslog and to a rotating log file, grbrsm-service.log, located in the same directory as grb_rsm.

The uninstall command will delete the generated file.

macOS¶

On macOS, the system manager is called launchd, and the install command will generate a service file in /Library/LaunchDaemons/com.gurobi.grb_rsm.plist. Once the file is generated, you can edit it to set advanced properties. Please refer to the launchd documentation to learn more about service configuration.

Use the start and stop commands to start and stop the service. When the service is running, log messages are sent to the macOS syslog and to a rotating log file, grbrsm-service.log, located in the same directory as grb_rsm.

The uninstall command will delete the generated file.

Windows¶

On Windows, the install command will declare the service to the operating system. If you wish to set advanced properties for the service configuration, you will need to start the Services configuration application. Please refer to the Windows Operating System documentation for more details.

Use the start and stop commands to start and stop the service. When the service is running, log messages are sent to the Windows event log and to a rotating log file, grbrsm-service.log, located in the same directory as grb_rsm. Note that the service must run as a user that has write permissions to this directory; otherwise, no log file will be generated.

The uninstall command will delete the service from the registry.

Verification¶

Once you have grb_rsm installed and running, your final step is to make sure that it is configured and running correctly. The Cluster Manager initially has three default users with predefined passwords:

standard user: gurobi / pass
administrator: admin / admin
system administrator: sysadmin / cluster

These default accounts are provided to simplify installation; you should change the passwords or delete the accounts before actually using the cluster.

You can check that you can log in using the sysadmin account with the grbcluster command-line tool:

> grbcluster login --manager=http://mymanager:61080 --username=sysadmin
info  : Using client license file '/home/jones/gurobi.lic'
Password for sysadmin:
info  : User gurobi connected to http://mymanager:61080, session will expire on...

Note that you can specify the password by using the —-password flag, but it is more secure to type the password when prompted. grbcluster will get an authentication token from the server, and will save it along with other connection parameters into a client license file. Once saved, you can use the other commands of grbcluster securely without having to type the password or other information again. The authentication token is valid for a certain period of time, as defined in the Cluster Manager settings (see the interactive session duration). The default is 8 hours. The —-help flag displays help for the login command.

> grbcluster login --help

Another important validation step is to make sure you can access the Web User Interface of the Cluster Manager. To do so, just open a Web browser using the server URL:

http://mymanager:61080

This should display the login page, where you can provide the credentials for the default accounts listed above.

Press `/` or click to search this documentation	Gurobi website	Gurobi community forum
Go to other Gurobi documentation	Gurobi download	Contact support