---
title: Configure OpenLM Router
description: Connect OpenLM Router to OpenLM Platform, define failover pairs in OpenLM Platform, and point FlexLM clients at the Router.
product: OpenLM Platform
---

To put a license server behind OpenLM Router, connect the Router to OpenLM Platform, define a failover pair in OpenLM Platform, then move your clients onto the Router port. Do the steps in this order. Server health, the server list, and the Router configuration all come from OpenLM Platform, so nothing else works until the connection succeeds.

## Before you begin

Confirm these prerequisites:

- The Router is deployed and answers on port `8100`. See [Deploy OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/deployment).
- You can create a client in **Identity** and open **LicOps Configuration** in OpenLM Platform.
- Each license server in a pair is monitored by OpenLM through the OpenLM Broker. See [System requirements](https://www.openlm.com/documentation/cloud/deployment-operations/router/system-requirements#openlm-platform-prerequisites).
- You know which clients use each license server, and you can change their license variable.

## Connect the Router to OpenLM Platform

The Router signs in to OpenLM Platform with a client ID and secret and stores the secret encrypted. All three values it needs come from an identity client whose **Client Type** is `Router`.

### Get the Router authorization file

To get the Router authorization file:

1. In OpenLM Platform, select **Navigation**, then **Identity** under **Platform Administration**.
2. Select **Authorization**, then **Add Client**.
3. In **Select Client Type**, select **Router**. Enter a description, leave **Encrypted authorization client** cleared, and select **Save**.

   *Select **Router** as the client type. A client of another type can sign in, but OpenLM Platform refuses the queries the Router makes.*

4. Download the authorization file, a JSON file such as `router-authorization.json`.

The file holds the three values the Router needs, as the following table shows:

| Value | What it is |
| --- | --- |
| Base URL | The root address of your OpenLM Platform: the address you sign in to, with nothing after the host. It is not a token URL or an API path, because the Router appends those itself. |
| Client ID | The **Client ID** of the Router client. |
| Client Secret | The **Client Secret** of the same client. If you no longer hold it, select the client on the **Authorization** page and select **Reset Secret**. The previous secret stops working. |

Use a client whose type is `Router`. A credential of another type can authenticate, and OpenLM Platform still refuses the queries the Router makes. The problem appears later as a missing server list rather than as a sign-in failure. For more about authorization files, see [Identity](https://www.openlm.com/documentation/cloud/openlm-administration/identity/#generate-an-authorization-file).

### Connect in the Router UI

To connect the Router to OpenLM Platform in the Router UI:

1. Open `http://<router-host>:8101/router-management/` in a browser.
2. Select **Import Auth File**, then select the authorization file.

   Instead of importing the file, you can enter **Base URL**, **Client ID (Optional)**, and **Client Secret (Optional)** by hand. Always fill in all three fields. Leave **Request Timeout (seconds)** at `30` unless your network is slow.
3. Select **Check Connection**.
4. Select **Save**.

*Platform Connection is where the Router learns how to reach OpenLM Platform. Until the connection works, a notice under the form says why the Router cannot sync.*

**Check Connection** makes a real call, so a pass confirms that the address resolves, the certificate is accepted, and the credentials are honored, not merely that the URL is well formed. It stays unavailable until you enter a base URL.

When you open the page again later, the form shows the stored secret masked as `***`. Saving the form with the masked value keeps the stored secret, so you can change the other fields without entering the secret again.

Within about 10 seconds of saving, the notice under the form disappears. There is no separate success message. No notice means the Router is syncing its configuration with OpenLM Platform. If the notice stays, it gives the reason, as described in [Troubleshooting](https://www.openlm.com/documentation/cloud/deployment-operations/router/troubleshooting). The notice does not cover server health, so also run the checks in [Confirm the connection works](#confirm-the-connection-works).

### Connect with the REST API

To script the connection instead of using the Router UI, run this command:

```bash
curl -X PUT http://localhost:8100/api/v1/admission-controller/platform-credentials \
  -H "Content-Type: application/json" \
  -d '{
    "baseUrl": "https://platform.example.com",
    "clientId": "<client-id>",
    "clientSecret": "<client-secret>",
    "requestTimeoutSeconds": 30
  }'
```

`requestTimeoutSeconds` defaults to 30 and accepts a minimum of 1.

### Confirm the connection works

Run these commands in order. Each one depends on the one before it:

```bash
# 1. The credentials are stored. The secret reads back masked.
curl http://localhost:8100/api/v1/admission-controller/platform-credentials

# 2. The Router is syncing with the Platform: lastSuccessfulSync has a time,
#    and lastFailure is null.
curl http://localhost:8100/api/v1/status

# 3. The Router has the Platform's server list. Allow about ten seconds after saving.
curl http://localhost:8100/api/v1/platform/servers
```

Step 3 returns the license servers OpenLM Platform monitors:

```json
[
  { "id": 615, "hostName": "lic-primary.example.net", "port": 27005, "lmType": "FLEXlm", "isHealthy": true },
  { "id": 845, "hostName": "lic-backup.example.net",  "port": 27005, "lmType": "FLEXlm", "isHealthy": true }
]
```

Until the Router has that list, the request answers `503` with an explanation rather than an empty list:

```json
{
  "statusCode": 503,
  "message": "The Router has not collected any Platform license-server data yet. Check the snapshot sync job and Platform credentials, then retry once a snapshot exists."
}
```

On a new deployment that usually means the connection is not working yet. Recheck the three values and confirm the host has outbound access to OpenLM Platform. If steps 1 and 2 pass and step 3 still answers `503` a minute after you connect the Router, the Router is syncing its configuration but not receiving server data. See [Troubleshooting](https://www.openlm.com/documentation/cloud/deployment-operations/router/troubleshooting#why-is-the-router-not-syncing-with-openlm-platform).

To test a credential before you save it, send it to the connection check. This endpoint checks the credential in the request body. If `clientSecret` is empty or `***`, it checks the stored credential instead:

```bash
curl -X POST http://localhost:8100/api/v1/admission-controller/platform-credentials/check-connection \
  -H "Content-Type: application/json" \
  -d '{
    "baseUrl": "https://platform.example.com",
    "clientId": "<client-id>",
    "clientSecret": "<client-secret>",
    "requestTimeoutSeconds": 30
  }'
```

A working credential answers:

```json
{
  "status": "Ok",
  "message": "Connection successful: a Platform access token was acquired."
}
```

Read the result from the response body, not the status code. A rejected credential still answers `200`:

```json
{
  "status": "Failed",
  "message": "Connection failed: the Platform rejected the supplied credentials. Platform token request rejected with HTTP 400: invalid_client"
}
```

## Define a failover pair

To define a failover pair, work in OpenLM Platform, not on the Router. The Router registers itself with OpenLM Platform on its first sync, so you don't need to pre-register it.

1. In OpenLM Platform, select **Navigation**, then **LicOps Configuration** under **Licenses and Features**. LicOps Configuration is the app that configures both OpenLM Router and OpenLM LicOps. For a failover Router, it opens on **Port Mappings**.

   If the page says that no Router has reported itself yet, the Router has not synced with OpenLM Platform. Wait about 10 seconds after you connect the Router, then reload the page. The page does not refresh by itself.

   *Port Mappings lists your failover pairs. Select a pair to see its servers and policy, and to edit or delete it.*

2. Select **Add Port Mapping**.
3. Fill in the form, which opens with these starting values:

   | Field | Starting value |
   | --- | --- |
   | **Name** | `Mapping 1`. Replace it with a name you recognize in the failover history. |
   | **Failback mode** | **Auto**. To inspect a recovered primary before clients return to it, select **Manual**. |
   | **Router listen port** | The next free port, starting at `27000`. Give each pair its own port, one that is free on the Router host and open to clients. |
   | **Failure threshold** | `3`. Accepts 1 to 10. |

   *The Add Port Mapping form. It proposes the next free listen port. Here, 27000 and 27001 are already taken.*

4. For **Primary server**, select **Choose server**.
5. Select the server, then select **Select**.

   The list includes every license server OpenLM Platform monitors, with its host, port, LM type, and current health. OpenLM tests the Router with FlexLM servers only, as described in [Current limitations](https://www.openlm.com/documentation/cloud/deployment-operations/router/index#current-limitations).

   *Choose server lists the license servers OpenLM Platform monitors. A server appears here only if the OpenLM Broker on it reports to OpenLM Platform.*

   If a server you expect is missing, OpenLM Platform does not monitor it: the OpenLM Broker is not installed on it, not approved in **Broker Hub**, or the server is not approved under **License Servers**. See [System requirements](https://www.openlm.com/documentation/cloud/deployment-operations/router/system-requirements#openlm-platform-prerequisites).

6. (Optional) For **Backup server**, select **Choose server**, then select a server that serves the same vendor daemon and features as the primary, from its own license file. Leave it empty for a pair you want monitored but not failed over.
7. Select **Save**.

The Router collects the change on its next sync, within about 10 seconds, and opens the listen port with no restart. OpenLM Platform does not show whether the Router applied the pair, so confirm it on the Router, as described in [Confirm the Router applied the pair](#confirm-the-router-applied-the-pair). To edit or delete a pair later, select it in **Port Mappings**, then select **Edit** or **Delete**.

When you choose the policy, keep these points in mind:

- **Failback mode**: **Manual** is the safer mode. **Auto** returns clients to the primary as soon as one healthy reading arrives, which can move them back and forth if the primary is unstable.
- **Failure threshold**: the threshold counts 30-second health checks. A threshold of 2 reacts within about 1 minute and doesn't move clients on a single reading. A threshold of 1 moves clients on a single reading, which makes the pair sensitive to a momentary blip.

### Confirm the Router applied the pair

Nothing is pushed to the Router. It polls OpenLM Platform every 10 seconds or so, pulls what changed, applies it, and reports back what it applied. To check that the Router applied the pair, run this command:

```bash
curl http://localhost:8100/api/v1/status
```

```json
"configurationManagement": {
  "shape": "serviceManaged",
  "routerId": "3f6c…",
  "lastSync": {
    "lastSuccessfulSync": "2026-09-07T09:14:22Z",
    "lastAppliedConfigVersion": 4,
    "lastFailure": null
  }
}
```

`lastSuccessfulSync` that stops advancing means the Router is no longer talking to OpenLM Platform. `lastFailure` shows the current problem and is cleared by the next success, so anything there is live rather than history.

If the Router cannot apply the pair, it keeps its previous configuration and does not open the listen port. `lastFailure` gives the reason, and the Router UI shows the same reason in its notice. The pair still appears in OpenLM Platform.

Then confirm the listen port is open by running this command:

```bash
curl http://localhost:8100/readyz
```

`boundPorts` lists the listen port of every pair the Router applied. When it matches `desiredPorts`, the Router is ready for clients.

## Point clients at the Router

To cut over, change what the clients point at. Nothing about the license servers changes.

FlexLM clients read their server from an environment variable or a `licpath.lic` file, in `port@host` form. Change the server address to the host of the Router and the listen port of the pair:

```bash
LM_LICENSE_FILE=27005@lic-primary.example.net   # before: straight at the server
LM_LICENSE_FILE=27000@router.example.net        # after: at the Router's listen port
```

On Windows workstations, set it as a system environment variable, for example from an elevated command prompt:

```bat
setx /M LM_LICENSE_FILE 27000@router.example.net
```

### Change many workstations at once

To change the variable on every workstation, push it with the deployment tool your organization already uses, such as Group Policy, Microsoft Intune, or Microsoft Configuration Manager. Set `LM_LICENSE_FILE` as a system environment variable with the value `<listen-port>@<router-host>`, and see the documentation of your tool for how it targets and schedules a change. These steps apply to any tool:

1. Change a small test group first. Run `lmutil lmstat -a -c <listen-port>@<router-host>` on a test workstation, and open the application.
2. Include every vendor-specific variable and registry value that the application reads, not only `LM_LICENSE_FILE`. The warning about vendor-specific variables in this section explains why.
3. Keep the old value, so that you can push it again to roll back.
4. Consider a [direct fallback entry](#keep-a-direct-fallback) during the roll-out.
5. Extend the change to the remaining workstations in stages.

:::warning[Check for vendor-specific variables first]
Many applications read their own variable in preference to `LM_LICENSE_FILE`, such as `MLM_LICENSE_FILE` for MATLAB and `ADSKFLEX_LICENSE_FILE` for Autodesk. If one of those is set, it wins, and the application keeps going straight to the old server while everything looks correctly configured.
:::

To check for vendor-specific variables, run this command:

```bash
env | grep -i LICENSE_FILE
```

On Windows, also check the values FlexLM keeps in the registry, where many installers write the vendor variables. Run these commands:

```bat
set | findstr /i LICENSE_FILE
reg query "HKLM\SOFTWARE\FLEXlm License Manager"
reg query "HKCU\Software\FLEXlm License Manager"
```

To confirm a client reaches the Router, run this command:

```bash
lmutil lmstat -a -c 27000@router.example.net
```

The output matches what the same command returns against the license server directly. Run it from a test workstation, not from the Router host.

`lmstat` only proves the first leg of a checkout, the connection to `lmgrd`, which the Router carries. The checkout itself then goes from the workstation straight to the vendor daemon on the active server. If `lmstat` through the Router works but the application cannot check out, the workstation cannot reach that vendor-daemon port. See [System requirements](https://www.openlm.com/documentation/cloud/deployment-operations/router/system-requirements#network-requirements).

### Keep a direct fallback

To send clients to the license server if the Router is unreachable, list both addresses. FlexLM tries the entries from left to right. Separate the entries with `:` on Linux and macOS, and with `;` on Windows:

```bash
LM_LICENSE_FILE=27000@router.example.net:27005@lic-primary.example.net
```

The trade-off is that it also hides a Router misconfiguration: checkouts keep succeeding, so nothing looks wrong, while no traffic goes through the Router at all. Use it for a cautious roll-out and remove it once you have confirmed the Router path works.

## Rehearse a failover

Test the failover before you depend on it, as described in [Operate OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/operations#rehearse-a-failover).

:::note[Next step]
Continue to [Operate OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/operations) to rehearse a failover and to see which server each pair serves from.
:::

## Related

- [Deploy OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/deployment)
- [Change, upgrade, or remove OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/manage)
- [Troubleshoot OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/troubleshooting)