License Activation

The first step in activating a Gurobi license is to capture a few pieces of information about your system, including the Host Name, the Host ID, and the User Name for your account. This is done using the grbprobe command. As mentioned in the previous section, grbprobe will produce output that looks like the following:

HOSTNAME=mymachine
HOSTID=3e03ab3c
USERNAME=Jones

Once you have this information, you can then request a license. For trial or academic licenses, you can generate a license yourself by entering this information into the License Request page within the Gurobi Account area at www.gurobi.com. You will receive a gurobi.lic file in response (via email). For paid licenses, you should send the output of grbprobe to license@gurobi.com. Once payment is received, you will receive your license file via email.

We recommend that you place gurobi.lic in one of the default locations (c:\gurobi200 or c:\ gurobi20 for Gurobi version 2.0.0 on Windows, /opt/gurobi200 or /opt/gurobi20 on Linux, and /Library/gurobi200 or /Library/gurobi20 on Mac), where it will be found automatically by the Gurobi optimizer. Your other option is to set environment variable GRB_LICENSE_FILE to point to the file.

On Windows systems, environment variables are created and modified through the Control Panel. In Windows Vista®, searching for Environment Variables in the Control Panel search box will lead you to the appropriate screen. In Windows XP®, the Environment Variables screen is accessed through the Environment Variables button on the Advanced tab of the System screen of the Control Panel. You should add a new System variable named GRB_LICENSE_FILE, and set it to the location of your license file.

On Linux or Mac OS systems, you should add the following to your .bashrc file:

  export GRB_LICENSE_FILE=/usr/home/jones/gurobi.lic

For Linux csh shell users, you should add the following to your .cshrc file:

  setenv GRB_LICENSE_FILE /usr/home/jones/gurobi.lic

The next license activation step depends on the type of license you have received.

For node licenses (look for TYPE=NODE in your gurobi.lic file), no additional steps are required. You can proceed directly to Testing the license.
For academic licenses (look for TYPE=ACADEMIC in your gurobi.lic file), you will need to verify that your computer is connected to an academic domain by running grbvalidate. If the domain is recognized, this command will retrieve a validation key that allows you to use the Gurobi optimizer for 14 days (refer to Validation troubleshooting if you run into trouble). The validation key can be refreshed in the future by running grbvalidate again. Once your computer has been validated, you can proceed to Testing the license.
If you are setting up a token license server (look for TYPE=TOKEN in your gurobi.lic file), the next step depends on your platform. You should consult Activating a Windows token server, or Activating a Linux token server, as appropriate. Note that Mac OS systems cannot currently be used as token servers.

Activating a Windows token server

If your token server is a Windows system, you will need to start the token service by selecting the Gurobi Token Server menu item in the Gurobi Optimization folder of the Start menu. You should only do this after you have installed the Gurobi license file.

The next step after starting the Gurobi token server depends on your anti-virus software and firewall settings. Most anti-virus software will immediately ask you to confirm that you are allowing program grbd.exe to receive network traffic. Once you confirm this, the token server should be configured and serving tokens. If you don't receive such a prompt, you will need to add grbd.exe to the firewall exceptions list. In Windows Vista, you do this by selecting Allow a program through Windows firewall under the Security area of the Control Panel. In Windows XP, you do this from the Windows Firewall selection under the Control Panel. You should add grbd.exe to the list of exceptions.

Once the token service has been started, you should see the grbd service listed in the Services tab of the Task Manager. To start or stop the service, click on the Services button at the bottom-right of the Services tab, and then right-click on the Gurobi License Manager item on this screen.

You can also start or stop the Gurobi License Manager service from the command line. Running grbd -h lists command-line options. Issuing a grbd -s command stops a running license service. Issuing a grbd -v command starts the license service in verbose mode.

All output from the Gurobi License Manager goes to the Windows Event Log. You can access this in Windows Vista through the Event Viewer. Type Event in the search box under the Start menu to launch the viewer.

To set up client licenses, you should install the gurobi.lic file on every machine that will be using the token server (using the license installation instructions given above). Alternatively, you can use a simpler client license file that only contains the name or IP address of the token server machine:

TOKENSERVER=mymachine.mydomain.com

TOKENSERVER=192.168.1.100

You would of course substitute the name or IP address of your token server.

You can now try Testing the license.

Activating a Linux token server

If your token server is a Linux system, you will need to start the token server daemon by running program grbd (with no arguments) on your license server machine. You only need to do this once -- the token server will keep running until you stop it (or until the machine is shut down). Be sure that the license file has been installed before running this program. Note that the token server runs as a user process, so you do not need root priviledges to start it.

Note that if you would like the license server to restart when the machine is rebooted, you should ask your system administrator to start it from /etc/rc.local. If your Gurobi installation and license file are in their default locations, then adding the following should suffice:

/opt/gurobi200/linux64/bin/grbd

Output from the token server goes to the system log (/var/log/syslog). You should see a message similar to the following when you start the server:

Mar  7 12:37:21 mymachine grbd[7917]: Daemon started: Sat Mar  7 12:37:21 2009

By default, the token server only produces logging output when it starts. To obtain more detailed logging information, start the token server with the -v switch. This will produce a log message each time a token is checked in or out.

TOKENSERVER=mymachine.mydomain.com

TOKENSERVER=192.168.1.100

You would of course substitute the name or IP address of your token server.

If you run into trouble accessing the token server, check to see if the server machine is running firewall software (like Bastille or ipfilter) that is blocking access to some ports . The Gurobi token server uses port number 41954 by default, so you'll need to open access to that port on the server. Please consult the documentation for your firewall software to determine how to do this. If there's a conflict on the default port, you can choose a different one by adding a PORT line to both the server and the client license files:

PORT=46325

You can choose any available port number.

Testing the license

Once you have installed the license, you are ready to launch the Gurobi shell. On Windows systems, double-click on the Gurobi icon on your desktop (or type gurobi.bat from a cmd window). On Linux or Mac OS systems, type gurobi.sh in a Terminal window. The shell should produce the following output:

Gurobi Interactive Shell, Version 2.0.0
Copyright (c) 2009, Gurobi Optimization, Inc.
Type "help()" for help

gurobi>

You are now ready to use the Gurobi interactive interface.

Validation troubleshooting

While most academic domain validations proceed without issue, we've run into a few validation issues that may require some action on your end.

If grbvalidate produces the following message...

  Unable to contact academic validation server 'validate.gurobi.com'

...you are most likely running into a firewall issue. You will need to ask your network administrator to open port 40000 on your firewall to allow validation to proceed.

If grbvalidate produces a message that looks like this...

  ERROR: Unable to determine hostname for IP address 234.28.234.12.

...it means that your machine has no reverse DNS information. This usually happens when you are connecting to the Internet through a DHCP server that does NAT (network address translation) or PAT (port address translation), but does not provide DNS information for its clients. The simplest way to resolve this issue is to ask your network administrator to add a DNS entry (a PTR record, to be more specific) for the DHCP device itself.

If grbvalidate produces a message that looks like this...

  ERROR: your hostname (mymachine.mydomain)
  was not recognized as belonging to an academic domain.

...it means that your domain isn't on our academic domain list. If it is a valid university address, please send the reported host name to support@gurobi.com and we'll add your domain.

Connecting to your academic domain through a VPN will typically not present a problem for validation, since the request will appear to originate from inside your academic domain. However, some VPNs are configured to use split tunneling, where traffic to public internet sites is routed through your ISP. Split tunneling introduces a major security hole into the private network, so it is not that common. If you find that your validation request is rejected when you are connected to your VPN, you should ask your network administrator whether the VPN can be configured to route traffic to gurobi.com through the private network.