---
title: Operate OpenLM Router
description: Check which server an OpenLM Router failover pair is serving from, force a failover or failback, keep the Router available, and read the failover history.
product: OpenLM Platform
---

Day to day, OpenLM Router needs no attention. It watches the health OpenLM Platform reports and moves a pair to its backup when the primary fails. The following tasks are the ones you do by hand: rehearsing a failover before you depend on it, taking a server out of service for maintenance, and checking what happened after a move.

You do these tasks with the REST API of the Router on port `8100`, or in OpenLM Platform where noted. Run the commands from the Router host, or from a machine on your administration network.

## Before you begin

Confirm these prerequisites:

- The Router is connected to OpenLM Platform and has applied at least one failover pair. See [Configure OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/configuration).
- You can reach the Router host on port `8100`, or you can open **LicOps Configuration** in the Platform.

## Check what a pair is doing

To see which server each pair is serving from, and the health behind that decision, run this command:

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

The response has one entry per pair under `pairStatuses`. The following table lists what each entry contains:

| Item | What it shows |
| --- | --- |
| Active server | Which of the two is serving right now, `Primary` or `Backup`. |
| Server health | The health OpenLM Platform last reported for each server: `Healthy`, `Unhealthy`, or `Unknown`. |
| Recent failovers | The latest moves for the pair, with their timestamps and reasons. |

`Unknown` means the Router has had no reading for that server for 10 minutes. The Router holds the pair where it is rather than treating the gap as a failure, so a pair sitting on `Unknown` is not about to move.

## Rehearse a failover

To test a pair before you rely on it, force a failover during a quiet period. A forced move sends new connections to the backup, while connections already open stay on the primary until they close. Use the pair's **Name** from OpenLM Platform as `pairId`. Run these commands:

```bash
# Move the pair onto its backup.
curl -X POST http://localhost:8100/api/v1/failover/manual \
  -H "Content-Type: application/json" \
  -d '{"pairId": "matlab", "message": "Commissioning test"}'

# Confirm: the pair reports Backup, with a new history entry.
curl http://localhost:8100/api/v1/status

# Return it to the primary.
curl -X POST http://localhost:8100/api/v1/failback \
  -H "Content-Type: application/json" \
  -d '{"pairId": "matlab", "message": "Commissioning test complete"}'
```

`message` is optional. It is stored with the move in the failover history.

A pair in **Auto** failback mode returns to its primary on its own as soon as the primary is healthy, so a forced failover of a healthy **Auto** pair does not last. To keep a pair on its backup deliberately, set its failback mode to **Manual** first.

## Take a server out of service

To stop a server receiving traffic during maintenance, edit the pair in **LicOps Configuration** in OpenLM Platform. Swap the server out of the primary or backup position, then put it back when you finish the work. The Router collects the change within about 10 seconds and applies it live. The listen port stays open, and you don't need to stop or restart anything on the Router.

## Read the failover history

Every move is recorded on the pair with a reason:

| Reason | What happened |
| --- | --- |
| `HealthCheckFailed` | The failure threshold was reached and the Router moved the pair itself. |
| `Manual` | Someone forced a failover or a failback. |
| `FailbackRequested` | The pair returned to its primary automatically, in **Auto** mode. |

Read it in the pair's entry under `pairStatuses` in `GET /api/v1/status`. The history lives in MongoDB and survives a restart of the Router.

## Change a pair's policy

Failback mode and failure threshold are properties of the pair. To change them, select the pair in **Port Mappings** in **LicOps Configuration**, then select **Edit**. The Router applies the change on its next sync, with no restart.

The failure threshold counts health checks, which run every 30 seconds. The maximum is 10. For guidance on choosing a value, see [Define a failover pair](https://www.openlm.com/documentation/cloud/deployment-operations/router/configuration#define-a-failover-pair).

## Keep the Router available

The Router carries the first leg of every checkout. While it is down, clients that point only at the Router can't reach their license servers. To keep it available:

- **Monitor readiness:** `GET /readyz` answers `503` until the Router has collected its configuration, and its `boundPorts` and `desiredPorts` show whether every listen port is open. Check it from your monitoring tool and alert on a `503` or on a `boundPorts` list that differs from `desiredPorts`.
- **Monitor Redis separately:** Redis holds which server each pair serves from. A Redis outage doesn't make `/readyz` fail, so watch `failoverStateStoreReachable` in `GET /api/v1/status` as well. Run Redis with the persistence settings in [System requirements](https://www.openlm.com/documentation/cloud/deployment-operations/router/system-requirements#redis-persistence-is-required).
- **Back up MongoDB:** The MongoDB data volume, `mongo_data` in the Compose file, holds the Router identity, the encrypted Platform connection, and the failover history. Back it up with your usual backup tool. If you lose it, a Router you start in its place is a different Router. See [Change, upgrade, or remove OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/manage).
- **Decide on a direct fallback:** A client that lists the license server after the Router keeps working while the Router is down, and it also hides a Router that no traffic goes through. See [Keep a direct fallback](https://www.openlm.com/documentation/cloud/deployment-operations/router/configuration#keep-a-direct-fallback).
- **Run one Router:** A standby Router that reports to the same OpenLM account makes **LicOps Configuration** switch between the two Routers. See [Current limitations](https://www.openlm.com/documentation/cloud/deployment-operations/router/index#current-limitations).

:::note[Next step]
To upgrade, move, or retire the Router, continue to [Change, upgrade, or remove OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/manage).
:::

## Related

- [Troubleshoot OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/troubleshooting)
- [OpenLM Router API reference](https://www.openlm.com/documentation/cloud/deployment-operations/router/reference)