Table of Contents
- License Types
- Installation of a License
- Checkout of a Network License
- License Restrictions and Enforcement
- On-Premises License Server
- Command-Line Tools
- License Problems
-
Errors
- License File too old for this Version of GAMS
- License File has expired xx days ago
- Node ID in License File in Incorrect Format
- Node ID Does Not Match License Node ID
- User Name Does Not Match License User Name
- Number of Cores Exceeds Licensed Number of Cores
- Total Memory Exceeds Licensed total Memory
- Network License Without Interprocess Port Not Allowed at this Point
- Expired Network License
- Additional Solver Limits
This section deals with the installation of a GAMS license. Information on different license types and licensing in general can be found on our website.
GAMS licensing supports a variety of options (e.g. network licenses, on-premises license servers), providing users with great flexibility and powerful resource management capabilities. As part of this, GAMS relies on a modern delivery method for licenses. The core of this method is a 36-character access code that enables users to retrieve their GAMS license from a license server. The server provides an eight-line text-based license file that needs to be stored in one of several standard locations on the user's hard drive so GAMS can find it.
The public GAMS license server, available at https://license.gams.com
, is used automatically when an access code is provided. In environments with no access to license.gams.com
, the same access-code workflow can be directed to an on-premises GAMS license server hosted by the customer.
License Types
GAMS licenses are available in two types, each tailored to support different environments and usage scenarios. This section outlines the key differences between these license types to help users choose the option that best fits their needs.
Local Licenses
Local licenses are tailored for individual users or specific machines, making them well-suited for standalone, offline environments. These licenses may include usage restrictions, such as limitations on the number of concurrent uses, cores, memory, or users. Dynamic environments like Docker containers or virtual machines are unsuitable for local licenses. Once activated, a GAMS system with a local license functions independently of a network connection to a license server, ensuring straightforward and dependable offline access.
Network Licenses
Network licenses are designed for shared use across multiple users or machines with reliable network access, managed centrally via a license server. They offer greater flexibility in dynamic environments, as the central license server handles accounting for concurrent uses, nodes, cores, memory, users, and other resources. To maintain this flexibility, the GAMS system requires uninterrupted network access to the license server for the entire duration of a job - not just at startup. In other words, a GAMS job must be able to continuously communicate with the license server while it is running.
When a GAMS job starts under a network license, it first opens a license session on the server and requests/reserves the resources (e.g. cores, memory) it needs. For that it sends the access code, along with the computer name, username, number of cores, available memory, and the GAMS version to the GAMS license server. If the requested resources exceed those currently available, the license request is denied and the session ends. If not, the license is granted and the session proceeds as follows:
- Session renewal - GAMS renews the session periodically via a background thread. If a session is not renewed within 5 minutes, the license server assumes the job has terminated or disconnected and automatically frees the reservation. Thus, at each session renewal GAMS arranges to request the next session renewal after 2.5 minutes. If renewal fails (e.g. due to a disconnect), it continues retrying with progressively shorter delays until the renewal occurs or the session timeout is reached and the session is terminated.
- Session return - on normal termination the job closes the session so its share of the license becomes available immediately.
Network licenses can also be manually checked out for a specified period, during which the checked-out license functions like a local license and does not require access to the license server. This feature is particularly useful when planning to work offline, such as during travel. Note that when a license is checked out, it reserves part of the network's license capacity (e.g. cores or memory usage), making that portion unavailable to other users until the checkout period ends.
While highly flexible, network licenses come with a fixed start-up cost: every GAMS job must create a session on the license server before execution can begin. The time to establish this session is governed by network latency and typically takes under a second on a fast connection, but can take longer on slower or distant networks. For long-running jobs this overhead is usually negligible, but workflows that launch many short-lived GAMS jobs can accumulate noticeable delays. If running a large number of such jobs is part of your optimization pipeline, consider checking out the network license for a suitable period. While the license is checked out it behaves like a local license, eliminating per-job connection delays.
Installation of a License
The simplest way to install a license is through GAMS Studio. For detailed instructions, please refer to the GAMS Studio documentation. On Windows, the installer already helps you install a license automatically. For more details, see the installation notes for Windows.
Install a License Manually using an Access Code
You can also install the license manually. Licenses are delivered (usually via email) as a 36-character access code and are installed or activated using the command-line utility gamsgetkey that is located in the GAMS installation directory.
- Note
- In the uncommon case that you receive an 8-line license file by email, copy those lines into a new file named
gamslice.txt
and place that file in any location searched by GAMS. If you use GAMS on macOS, do not store thegamslice.txt
in the GAMS system directory. Read more about this here.
- Navigate to a directory that GAMS searches and where you have write permissions.
Activate your license by running
gamsgetkey
in the terminal, using the access code as an argument. For example:/path/to/GAMS/installation/directory/gamsgetkey xxyyzzxx-yyzz-xxyy-zzxx-yyzzxxyyzzxx -o gamslice.txt
The output option (
-o gamslice.txt
) will write directly to the license file. Alternatively, you can omit the-o
option. In this case the license file content is sent to stdout and must be manually copied to the license file.- Note
- License activation (whether via the
gamsgetkey
utility, the GAMS licensing dialog in GAMS Studio or the installer (Windows only)) requires network communication with the GAMS license server. If this communication is not possible, use thegamsprobe
utility as described in Install a License without Network Communication.
- If not already done, place the
gamslice.txt
in a location searched by GAMS.
Install a License without Network Communication
For machines that are not connected to the internet, you can collect relevant licensing data, copy it to a machine that is connected to the internet, and activate the license from the connected machine. Follow these steps:
On the target machine, navigate to a directory where you have write permissions and run
gamsprobe
to gather necessary device data:/path/to/GAMS/installation/directory/gamsprobe -o device_data.json
The output option (
-o device_data.json
) will write the command-line output directly to a file.- Obtain the license file in one of the following ways:
Transfer the
device_data.json
file and the access code to a machine with network access. There, rungamsgetkey
to activate the license:/path/to/GAMS/installation/directory/gamsgetkey xxyyzzxx-yyzz-xxyy-zzxx-yyzzxxyyzzxx -i device_data.json -o gamslice.txt
- Note
gamsgetkey
andgamsprobe
must come from the same GAMS release.
- Upload the
device_data.json
to https://license.gams.com/static/instantiate.html and download the license file produced by the web form. This service will work with JSON files produced bygamsprobe
in GAMS 50 and newer.
- Transfer the resulting
gamslice.txt
to the target machine and place it in a location searched by GAMS.
Although device_data.json
contains many additional data points, the GAMS license server only receives and stores a limited subset: the computer name, username, number of cores, available memory, and the GAMS version. This applies even when using Method 2b via the web page.
Checkout of a Network License
Network licenses provide great flexibility but normally demand a live connection to the license server - no interruption longer than ~5 minutes is tolerated. For users who work on unreliable or disconnected networks (e.g. laptop use on a flight) the command-line tool gamsgetkey offers the option --checkout-duration=<n>
to create a checked-out license that remains valid without server contact for the next n hours. Once the checkout period expires the checked-out license becomes unusable and a fresh checkout or a return to the standard network-connected license file is required.
- Note
- The checked-out license cannot be returned early: the resources it uses remain unavailable to other users of the network license for the duration of the checkout period.
- If the license expires while GAMS is running, the job fails with a license error.
- The file embeds a transient node ID; hardware reboots may invalidate it before the planned expiry.
License Checkout
To check out a network license for a specified duration, use the -c
or --checkout-duration
option (with the duration defined in full hours) along with the -o
or --output
option (to specify the path for saving the license file). The generated license file will be valid for the designated period.
Example: /path/to/GAMS/installation/directory/gamsgetkey xxyyzzxx-yyzz-xxyy-zzxx-yyzzxxyyzzxx -c 24 -o gamslice.txt
-c 24
: Specifies a license checkout duration of 24 hours.-o gamslice.txt
: Saves the license file togamslice.txt
.
To extend the duration of a checked-out license, run gamsgetkey
again with the same access code and specify -c | --checkout-duration
with a value equal to or greater than the remaining hours; the checkout will then be expanded to the new total expiry time. You can request an extension only after at least half of the original checkout period has elapsed - earlier requests are ignored and the license keeps its initial expiry. To return to the standard network-connected license file at the end of the checkout period, run gamsgetkey
again with the same access code but omit the -c
or --checkout-duration
option.
License Restrictions and Enforcement
A GAMS license can include one or more attributes that constrain how the software can be used.
Attributes for Local Licenses
- Maximum physical CPU cores allowed on the machine.
- Maximum physical RAM (GiB).
- Maximum number of concurrent GAMS jobs on the node*.
- Limit on how many distinct node IDs may instantiate the license.
- The stored user-ID must match the current user.
Attributes for Network Licenses
- Maximum number of concurrently active nodes.
- Total concurrent GAMS jobs across all nodes*.
- Total CPU cores across active nodes.
- Total RAM across active nodes.
- Maximum number of concurrent GAMS jobs on the node*.
- CPU-core limit per node.
- RAM limit per node.
- Number of active users allowed across all nodes.
- Number of named users allowed across all nodes.
- Maximum hours for a checked-out license.
*
Asynchronous solves using solver processes (solveLink=3,4
) trigger a license error when the number of concurrent GAMS jobs is restricted. Asynchronous solves using solver libraries (solveLink=6,7
) work properly. Moreover, network licenses with concurrent use restrictions cannot be checked-out.
Determining Cores and Memory
For local licenses, the enforcement checks physical resources. If the machine exceeds the licensed limits, the best approach is to exclude cores in the BIOS. Alternatively, running GAMS inside a virtual machine configured with fewer cores and/or less memory may also help overcome this situation.
For network and checked-out licenses on Linux, there is a cleaner approach: when GAMS runs inside a Cgroup-controlled environment - for example inside a Docker or any other container - the licensing engine observes the Cgroup's resource limits instead of the host's physical hardware. The following rules apply:
- The Cgroup must expose at least 1/16 CPU and 128 MB RAM. If lower limits are set, GAMS automatically reserves these minima.
- Cgroups constrain logical CPUs, while licenses are expressed in physical cores. GAMS therefore
- reads the host's physical-to-logical ratio
α = physical_cores / logical_CPUs
, - multiplies the logical CPUs available in the cgroup (
C_cgrp
) byα
to obtain the physical-core equivalentC_eq = α · C_cgrp
. Fractional values (e.g. 0.25 core) are accepted by the licence server.
- reads the host's physical-to-logical ratio
When GAMS detects that it runs on Linux and inside a resource-limited cgroup it prints an extra summary line in the log, for example:
System information: 4 physical cores and 16 Gb physical memory detected cgroup limits: 0.25 cores and 2 Gb memory
Cgroup resource limits are especially useful for Engine One installations: the administrator sets the worker's logical-CPU and memory budget directly in docker-compose.yml. Syntax varies between docker-compose versions; with compose 1.29.2 the limits can be specified in the deploy.resources
section as follows:
The worker now sees 1.5 logical CPUs and 8 Gb RAM. When it opens a licence-server session those 1.5 logical CPUs are converted to a physical-core equivalent using the ratio above. For example with 16 physical cores and 24 logical CPUs: C_eq = 16 / 24 * 1.5 = 1.0
, so the session occupies one core on the licence server. The calculated value appears in the GAMS log as:
All subsequent licence checks use C_eq
and the cgroup's memory limit.
Determining Node Identifiers
A node identifier (node ID) is a unique fingerprint of the hardware / OS on which GAMS runs. The fingerprint combines several hardware and OS properties. Two variants exist:
- Permanent node ID: A stable identifier used for local licenses. It remains constant unless there are significant hardware changes in the system.
- Transient node ID: A temporary identifier used for network license sessions and check-outs. It may change due to environmental factors such as network configuration changes or even system reboots.
During instantiation of a local license the software computes a permanent node ID and embeds it in the license file. When GAMS starts it recomputes the node ID; if the value differs from the one in the file, execution stops with a license error.
For network licenses, each client session sends the transient node ID to the license server. The server uses it to decide whether the session originates from a new node and updates its bookkeeping for limits such as the maximum number of concurrently active nodes.
- Note
- A change in key hardware components can alter the permanent node ID; in that case contact
license@gams.com
.
Determining Concurrent Jobs (local licenses)
A concurrent job represents one token from the limit Maximum number of concurrent GAMS jobs on the node. A token is consumed every time one of the following activities starts, and it is released when the activity ends:
Action | Tokens consumed |
---|---|
Launching a gams.exe process | 1 token |
Creating a GAMSPy Container | 1 token |
Solving a GamsModelInstance via the Control API | 1 token |
Solving a frozen model in GAMSPy | 1 token |
Starting an asynchronous solve with solveLink=6 or solveLink=7 | 1 token per async solve, in addition to the token of the parent job |
- Note
- When a local license uses concurrent-job counting, make sure the port range encoded in the license is reserved for GAMS job counting. Run gamsprobe -p to query the availability of a port range since other software might occupy these ports. The starting port for instantiating a license can be set via gamsprobe -u or gamsgetkey <access-code> -u.
On-Premises License Server
Network licenses are normally delivered by the public service license.gams.com
using encrypted communication via https over port 443. In environments without access to license.gams.com
, a self-hosted GAMS license server can take over. After the initial startup this server operates independently of license.gams.com
, yet it only serves network licenses; local licenses remain exclusively issued by license.gams.com
.
- Note
- The on-premises license server is currently supported on x86_64 / amd64 Linux distributions using docker technology, but it can provide network licenses for GAMS software installed on any operating system.
- Contact
license@gams.com
regarding questions about the on-premises license server.
Workflow in Brief
- Install the license-server.
- Generate a certificate signing request (CSR) and send it to GAMS.
- GAMS signs the CSR and returns a license bundle and the signed certificate.
- Import the certificate and initialize the server with the bundle.
- Client machines fetch their license and certificate with gamsgetkey, pointing to the on-premises server.
Docker Setup
To run an on-premises GAMS license server you simply deploy a small Docker stack: one container with Postgres for license data and one with the license service itself. Any host that can run Docker Compose and is reachable by all GAMS clients on the local network is sufficient.
- Install Docker. We further recommend to configure Docker to start on boot.
Copy the files
docker-compose.yml
andsettings.json
(see below) into a directory such asGAMSLicenseServer
.docker-compose.yml
:version: '3.8' services: db: image: postgres:15 container_name: postgres-db restart: always environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: mysecretpassword # match settings.json POSTGRES_DB: postgres ports: - "5432:5432" server: restart: always image: gams/license-server:25.05.23 # check newer tags container_name: gams-license-server depends_on: - db ports: - "40080:8080" # host-port:container-port (container port is always 8080); HTTP only volumes: - ./settings.json:/code/settings.json:ro # host:container:mode
Only three values usually need tweaking in
docker-compose.yml
, everything else can remain unchanged:services.db.environment.POSTGRES_PASSWORD
: Database password - the credential for the Postgres service that stores license data. Pick any strong password and put the same value insettings.json
(see below).server.ports
: Host → container port mapping for the license service. The number after the colon must stay8080
because the service inside the container listens only on that port. The number before the colon is the TCP port on the host and can be any free port you like (e.g.40080
).server.image
: Image tag - the version ofgams/license-server
you wish to deploy (see the available tags on Docker Hub).
The companion configuration file
settings.json
:{ "database_host": "db", "database_port": 5432, "database_user": "postgres", "database_password": "mysecretpassword", "database_dbname": "postgres", "host": "my-license-srv.example.com", "port": 8080, "session_duration": 300, "renewal_accepted_after": 150, "refresh_token_early_expire": 5, "initial_admin_password": "ChangeMeNow!", "password_policy": { "min_password_length": 8, "must_include_uppercase": true, "must_include_lowercase": true, "must_include_number": true, "must_include_special_char": true, "not_in_popular_passwords": true } }
Set
database_password
to match the entry indocker-compose.yml
. Additionally, specify the address of the license server (reachable fully-qualified domain name (FQDN) or IP address) in thehost
attribute. This address is embedded in the GAMS license files generated by the server, so GAMS running on client machines can find the server without additional configuration. The initial password for the admin user is specified in theinitial_admin_password
attribute.- Note
- Communication is plain HTTP inside the customer network; if HTTPS is required place a reverse proxy in front. The client machines running GAMS need to be able to connect to the license server via
http://host:port
- Open a shell in the containing directory and start the stack with
docker-compose up -d
. This starts the local GAMS license server in detached mode. - Verify the server with
curl http://<host>:<port> # → {"detail":"Not Found"}
If the server does not respond, first confirm that the container is actually running viadocker ps
. If the image is missing, restart the stack in the foreground to obtain verbose logs:docker-compose up
. The console output may reveal configuration errors that prevent the service from starting.
Configuration Step 1 - Create a Certificate-Signing Request
Next, the on-site administrator uses the local license server to generate a certificate-signing request (CSR). This CSR is sent to GAMS, who signs it and returns the signed certificate and a bundle containing the agreed network licenses - this payload will later be imported into the on-premises server.
- Browse to
http://host:port/docs
, click Authorize, log in with the initial admin password, then executePOST /certificate-request Create Certificate Request
. The following input must be provided:{ "country_letters": "US", "organization": "Your Company Ltd.", "email": "admin@example.com" }
The response of this call (when successful) is a certificate that needs to be sent (via email) to GAMS:
{ "CSR": "-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----\n" }
GAMS signs the CSR, generates the negotiated network licenses and sends back the license payload.
Configuration Step 2 - Import Bundle
Once the payload containing the signed certificate, license bundle, and access codes arrives from GAMS, the administrator simply imports the certificate into the on-premises server and initializes it with the bundle to activate the provided network licenses:
Import the signed certificate by using the API call
PUT /certificate Accept Certificate
with the input:{"cert_pem": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----"}
If the call was successful the response will be
{"message":"Updated the certificate"}
Initialize the server with the license bundle:
POST /initialize Initialize System
with the input:{ "bundle": "CAESuQU4KYDPhgJyWwC3jkIFtbc61Aew/ImOxz/XjM+Ehk/8p/utTkoksO4CBS//XB/qDgt9HxQJAVoKTLJceH01wdiXASWkU/90nTTvc5P74EtV1nNpgHj3b0rrO52BhqJoaoPJyfp6IOMGeSJ3xzWr1B9jjTQ5uNz2wjA4Fxq9vTSzXgNjYh1LB2O1df9XWMvCiDom9sx8msoHUmLXoVSfUDOA2N43TiKAEpwHoKQ5djJt90f80Z5jaXf2TxZY23+8CPvnrY2z91zfompEAVNL4QaGKqxWRBjGrGwCbPubDU8DsfGFUbzFrcFjqUYoGGzOemyiANMDuh8/ncHQqhPiUR1QSG7IHpQLK9j47eOHbBXZt+39heLCJpfr1Faj924XVDtijfWluJQhOvLq+UJb1G1YWK9fDk0xxUItgkCRAP7iwbKqpkI3fvaIki1pyVeUhoWk9X9IdNrVfkpoq6Uj0CGy690GQozKWTBXE/8QyN0d+s9l6Uf+9j/3y+nKFRQKpKtSV/G4bJaTDgs4I9RCwOKTdwG2vr9ZJQv49HjmBPeCNU+2P/brfcei14/shC+eBa8pTsEcCsqAbtWFge6W4y9N4sZbdv2GwiZJgqK4LhFTYrL+T7nE9V76wKi7eEUHFYQFH93qY1QaDs+71ruqY+o/yu39UoRlpr0ZS/MOH7evUYiLWUIrgZ5Qu6j+yCpyGUPt/dIe3kzDg01IPzpnqlz9bEKPl3pwWmEuS/O51bRfZ3izcradlGzhyxkIXD6DyDaZaRfgLJor1sdpINUS+az9hcl/Po0oNHuk61TdI3bOTj3Td7ObdEkpJ6M1r7kjSBSw40Pp0TDhbWCC7XDp+k4qW6HGz0RN9K174DfvhZid8hj8USJSxrY3IBrVO/025L8+tggFwW0Nce6/6UH8O7GQADI2FDb1aSfkGgyxNTheV5wsYzDx5aIiWzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABNmhbOyI+fAhcQfk8oY9L90mHVYlXOXJoTrv/M1xZOFtYq5jqRVCi0jgOSUgRqfGZh+ZuccAPdWS9DCfAuu4XfcqZzBlAjAreJrMx1LM9Xn7+c1XhyuJkAiQHG+57ePt7U2EJP59NpDeDopM8F0yOMZIn0zoMhcCMQC2dp8qrPmS652qtx+rJCjX5/Q2TL+801NDHorLYB2GfR+J5iOxG+PVbONYhVe44Fc=" }
If the call was successful the response will be
{"message":"System initialized"}
Now the on-premises local GAMS license server is ready to serve the network licenses from the bundle.
Using an On-Premises Network License
When the on-premises license server is up, the regular instantiation of licenses on the client machines running GAMS follows the usual way with gamsgetkey, but now pointing to the local server and requesting a certificate in addition to the license file:
gamsgetkey <access-code> \ -s <host> -p <port> \ -g ~/.config/GAMS/gamslice.crt \ -o ~/.local/share/GAMS/gamslice.txt
-s | --server
and-p | --port
Specify the host name/IP and port of the on-premises server (notlicense.gams.com
).-g | --get-certificate
Path to which the signed certificate (gamslice.crt
) is to be written. By default GAMS looks for this file in the standard data directories. Alternatively, set the environment variableGAMSLICECRT
to the full file path.-o | --output
Location for the generated license file (gamslice.txt
).
The log output from gamsgetkey
will confirm a successful license retrieval and explicitly show the full path where the certificate was written.
Engine One Workers with an On-Premises Licence Server
When Engine One workers obtain their network licences from an on-premises licence server the worker container must be able to read the server's certificate file. Mount the file into the GAMS system directory inside the container and enable external network access in the worker section of the docker-compose.yml
of Engine One:
Start Engine One with external connectivity switched on:
The worker now forwards the certificate to GAMS at start-up, allowing licence requests to succeed.
Securing the On-Premises Licence Server with HTTPS
The on-premises licence server itself speaks plain HTTP on its configured port (e.g. 8080). We recommend the use of a reverse-proxy, like nginx, for secure communication with the license server via https using the default port 443. This is especially convenient when Engine One and the licence server share the same machine.
- Install Engine One (e.g. port 8081) and the licence server (e.g. port 8080).
In settings.json give the external host/port that clients will use; the licence files embed this name, so pretend HTTPS already exists:
{"database_host": "db",…"host": "gamsserver.mycompany.com","port": 443,…}- Leave the container's port-mapping unchanged (
8080:8080
) in the server section of the license serverdocker-compose.yml
Engine One is URL-agnostic; the licence server is not. Configure nginx to redirect HTTP to HTTPS and forward the two back-end ports:
server {listen 80;server_name gamsserver.mycompany.com;# Redirect all HTTP to HTTPSreturn 301 https://$host$request_uri;}server {listen 443 ssl;server_name gamsserver.mycompany.com;ssl_certificate /etc/nginx/sites-available/mycompany.com.fullchain.pem;ssl_certificate_key /etc/nginx/sites-available/mycompany.com.key.pem;ssl_protocols TLSv1.2 TLSv1.3;ssl_ciphers HIGH:!aNULL:!MD5;# Engine One REST APIlocation /engine/ {proxy_pass http://localhost:8081/;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header X-Forwarded-Proto $scheme;}# Licence-server REST APIlocation / {proxy_pass http://localhost:8080/;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header X-Forwarded-Proto $scheme;}}
This requires valid certificate files mycompany.com.fullchain.pem
and mycompany.com.key.pem
issued by the appropriate authority. Do not forget to create a symbolic link to the file in the directory /etc/nginx/sites-enabled
. If Engine One is not installed on the same host simply remove the /engine/
location block.
User Management
Most API calls on the on-premises license server require authentication. A single admin account is created automatically when the server starts; its initial password is taken from the initial_admin_password
field in settings.json.
To add new users, open the server's API page http://<host>:<port>/docs
, click Authorize and sign in as admin. Then use the "Create User" endpoint to add further accounts. A new user is assigned a permission group. For local license servers the permission groups 0 (admin) and 3 (reporter) with read-only access exist. Other user-management endpoints allow you to list accounts, delete users, or reset passwords.
- Note
- After receiving your credentials you must:
- Authorize with your temporary password.
- Immediately call the Update Password endpoint to set a personal password.
- Log out and sign in again with the new password.
- Authorize with your temporary password.
- Only then will the API operations allowed by your permission group work correctly.
Command-Line Tools
Two helper programs ship with a GAMS distribution:
gamsgetkey - Obtain a License
gamsgetkey <access-code> [options]
Retrieves a local or network license (or checks one out) and writes the resulting file to disk.
Key options:
Option | Meaning |
---|---|
-h, --help | Print full option list |
-i, --input | Path to a device data JSON file to read |
-s, --server <url> | URL of the license server |
-p, --port <n> | TCP port of the license server |
-g, --get-certificate <path> | Path to which the server certificate (gamslice.crt ) is to be written. |
-u, --use-port <n> | Starting port for instantiating a use-limited license |
-c, --checkout-duration <h> | Hours to check out a network license |
-o, --output <file> | Path for the generated license file (gamslice.txt ) |
For examples see License Checkout.
The tool is shipped with every GAMS and GAMSPy distribution and talks to a GAMS license server. By default it connects to https://license.gams.com
on port 443
, but an on-premises server can be selected with --server
and --port
.
For licenses that count concurrent local uses you may set the starting port of the reserved range with --use-port
(default 33333
).
Many errors reported by gamsgetkey
are plain connectivity issues. Because the tool relies on the cURL library you can test the connection independently:
curl -X GET "https://license.gams.com/license-type?access_token=<code>"
cURL supports proxies and other tweaks (for example via the http_proxy
environment variable) that can help diagnose or work around network hurdles.
gamsprobe - Inspect Device Data
gamsprobe [options]
gamsprobe
generates the hardware/OS fingerprint ("device data") required for license instantiation and can be used to install a license without network communication. Besides generating device data, gamsprobe
can scan for a free port range that will be used when a license employs concurrent-job counting.
Useful options:
Option | Meaning |
---|---|
-h, --help | Print full option list |
-p, --ports <start> <count> | Scans & verifies that all ports in the range <start> … <start> + <count> - 1 are currently free. If the range is free, gamsprobe writes the port information into the JSON file; if any port is occupied it aborts with an error and no JSON is produced. |
-u, --use-port <n> | Specify a starting port for instantiating a use-limited license. Note that gamsprobe does not perform an availability check; it simply records the specified port <n> in the JSON file. |
-o, --output <file> | Write device data JSON to disk |
Port Range Scan Example:
gamsprobe -p 44444 10 # checks ports 44444-44453
Be aware that port availability may change when other software is installed or activated, so rerun the scan if you encounter unexpected "Too many (n) concurrent GAMS runs active" license errors.
License Problems
Below are some typical error and warning messages and instructions on how to overcome them.
No License File present
Without a license file, GAMS will not work. If you have received a license file or access code, follow the instructions from the previous section. Do not rename the license file or modify its contents. Without a license GAMS will give you an error message like the one below:
*** Error: No license file found.
Typically, this error does not occur because a demo license is provided with every GAMS installation.
License File Invalid or Corrupted
Running GAMS with an invalid license will give you an error message like the one below:
*** Error: The installed license C:\Users\username\Documents\GAMS\gamslice.txt is invalid.
Do not try to modify your license file, any change will break it. If you received the license via email but no longer have the original file, please contact license@gams.com and ask for a copy of your license file. Please attach the license file you are currently using. If your GAMS license was provided as a 36-character access code, you can re-install the license using the access code either through GAMS Studio or manually. Note that this must be done on the machine for which the license was issued.
This error also occurs if you are using a license file that was issued for a different platform.
License File expired
If you try to use an old license file with a newer GAMS distribution, you might encounter an error message stating:
*** License file too old for this version of GAMS. *** Maintenance expired 2840 days ago. *** More than 60 days since expiration, sorry... *** Run an older GAMS system or renew the license
Replace that GAMS system with the one you got together with your license file (use the Check for Update utility of GAMS Studio to find out the latest version you can use with the current license; old systems are available on request from sales@gams.com) or update your license to the current version.
No License (for a particular Solver) found
If a solver you are trying to use (or the default solver) is not included in your license file, and the model size exceeds the limits of the free demo or community version, you will get an error stating:
*** No license found *** To update your license, please contact your distributor.
Check whether the default solvers for a particular problem class are included in the license. Please note that some of the solvers call other solvers as a sub-solver. For example, GAMS/DICOPT requires an NLP and a MIP solver.
Errors
License File too old for this Version of GAMS
The complete message is:
*** License file too old for this version of GAMS. *** Maintenance expired xx days ago.
If GAMS continues working, you can ignore this warning. However, any forthcoming GAMS distribution will most likely not work, but downgrade to the limits of the free demo system.
License File has expired xx days ago
This warning (without further error messages) indicates that the time limited license (e.g. an evaluation license) will stop working soon.
Node ID in License File in Incorrect Format
The node ID specified in the license file does not follow the required format. This may result from a manual entry error or misconfiguration during license generation. Please verify the node ID format and ensure it complies with the expected structure.
Node ID Does Not Match License Node ID
The node ID of the system does not match the node ID registered in the license file. Ensure that the correct node ID is used when generating the license.
User Name Does Not Match License User Name
The user name of the system running GAMS does not correspond to the one registered in the license. Verify that the correct system user name is associated with the license to resolve this issue.
Number of Cores Exceeds Licensed Number of Cores
The current system configuration uses more CPU cores than permitted by the license. To resolve this, reduce the number of cores used, or obtain a license that supports the higher core count.
Total Memory Exceeds Licensed total Memory
The total memory available on the system exceeds the amount specified in the license. To comply with the licensing agreement, adjust the memory allocation or acquire a license that supports the system's memory capacity.
Network License Without Interprocess Port Not Allowed at this Point
The use of a network license without an interprocess communication port is prohibited at this point. Ensure that the necessary port is configured and available to maintain network license functionality.
Expired Network License
The network license has expired, preventing continued access to the software. To restore functionality, renew the license or apply an updated license file with a valid expiration date.
Additional Solver Limits
GAMS enforces specific model size limits for demo and community licenses.
Demo license:
- 2000 variables and 2000 constraints for linear models (LP, RMIP, and MIP)
- 1000 variables and 1000 constraints for all other model types
Community license:
- 5000 variables and 5000 constraints for linear models (LP, RMIP, and MIP)
- 2500 variables and 2500 constraints for all other model types
The solvers mentioned below impose stricter or additional limits when running with a demo or community license. We use m for the number constraints, n for the number variables, nd for the number of discrete variables, nz for the number nonzeros, and nlnz for the number nonlinear nonzeros:
- Antigone, Baron, and LindoGlobal require m≤50, n≤50, and nlnz≤50 with a demo license.
- Antigone, Baron, and LindoGlobal require m≤300, n≤300, and nlnz≤100 with a community license.
- Cplex and ODHCPLEX require m≤2000 and n≤2000 with a pro-bono community license.
- Decis and Knitro require m≤300, n≤300, nd≤50, nz≤2000, and nlnz≤1000 with a demo and community license.
- Xpress requires m+n≤5000 with a community license.
- In addition Gurobi requires a license file from the vendor to operate.