Operate OpenLM Router

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.
• 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:

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:

# 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.

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.
• 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.
• 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.
• Run one Router: A standby Router that reports to the same OpenLM account makes LicOps Configuration switch between the two Routers. See Current limitations.

Next step

To upgrade, move, or retire the Router, continue to Change, upgrade, or remove OpenLM Router.

Related

• Troubleshoot OpenLM Router
• OpenLM Router API reference