Skip to main content

Key rotation

All commands run in /opt/entrosity/deploy with docker compose -f docker-compose.prod.yml --env-file .env, abbreviated dc below.

JWT secret​

RMM_JWT_SECRET signs only Axis's event stream tokens, which live one minute; users' tokens come from Entrosity Hub (Hub keys).

  1. Set RMM_JWT_SECRET_OLD to the current RMM_JWT_SECRET, and RMM_JWT_SECRET to a new value (openssl rand -base64 32).
  2. dc up -d backend. Tokens signed with either key are accepted; new ones use the new key.
  3. After a few minutes, remove RMM_JWT_SECRET_OLD and dc up -d backend again.

Nobody is signed out: open event streams reconnect with a new token.

Master key​

  1. Set RMM_MASTER_KEY_OLD to the current key and RMM_MASTER_KEY to a new one. dc up -d backend: the backends decrypt with both keys and encrypt with the new one.
  2. Re-encrypt the stored secrets: 
    dc run --rm backend rotate-master-key --dry-run
    dc run --rm backend rotate-master-key
    It re-seals the AD sync credentials and reports what it re-sealed. Run it again if it reports concurrent changes.
  3. Wait until the mail queue is empty (queued e-mails are sealed too; usually minutes). Then remove RMM_MASTER_KEY_OLD and dc up -d backend.
  4. Take a new backup. Older backups need the old key.

Entrosity Hub keys​

  • Signing key (PLATFORM_JWT_SIGNING_KEY, signs every Hub token): set PLATFORM_JWT_SIGNING_KEY_OLD to the current key and PLATFORM_JWT_SIGNING_KEY to a new one, then dc up -d platform. Both public keys are published; Axis fetches the new one when it first sees its kid. After 15 minutes (the lifetime of the Hub's longest-lived tokens), remove the old key and dc up -d platform.
  • Master key (PLATFORM_MASTER_KEY, TOTP secrets and queued e-mails): set PLATFORM_MASTER_KEY_OLD to the current key and PLATFORM_MASTER_KEY to a new one, dc up -d platform, then dc run --rm platform rotate-master-key --dry-run and without --dry-run. Once the mail queue is empty, remove the old key, restart the Hub and take a new backup.
  • Axis's product token (PLATFORM_PRODUCT_TOKEN_RMM): change it in .env and dc up -d platform backend (compose passes it to both).

Database passwords​

  • Owner (rmm): change it in PostgreSQL (ALTER ROLE), update POSTGRES_PASSWORD in .env, then dc up -d.
  • Application (rmm_app): change RMM_APP_DATABASE_PASSWORD and run dc run --rm migrate, which sets it; then dc up -d backend.

MinIO​

Change MINIO_ROOT_PASSWORD and restart minio and the backends.

Agent and connector keys​

Re-enrolling a machine rotates its key. Decommissioning a device (or deleting a connector) revokes its key everywhere immediately.

Release signing key​

Agents trust the public key built into their MSI. Before you replace RMM_RELEASE_SIGNING_KEY:

  1. build a release with the new public key (RELEASE_PUBLIC_KEY);
  2. publish it while the server still signs with the old key, and let it roll out;
  3. then switch the server to the new signing key.

Agents that miss the transitional release must be reinstalled.

Release token​

Set a new RMM_RELEASE_TOKEN on the server and in the repository secret of the same name, then dc up -d backend.