Skip to main content

Run the PDP in offline mode

Configure a self-hosted policy decision point (PDP) to keep serving permission checks when it can't reach the Permit control plane. This page is for operators who run the PDP container in production, in air-gapped networks, or in CI.

The PDP fetches its configuration and policy from the Permit control plane and receives updates from it. If a network problem blocks that connection, a PDP without offline mode can't start. In offline mode, the PDP saves its configuration, policy, and data to a local backup and loads from that backup when the control plane is unreachable.

Prerequisites​

Enable offline mode​

  1. Set PDP_ENABLE_OFFLINE_MODE to true.
  2. Mount a volume or host directory at the backup path. The path is set by PDP_OFFLINE_MODE_BACKUP_DIR and defaults to /app/backup.

When PDP_ENABLE_OFFLINE_MODE is true, the PDP turns on offline mode in its Open Policy Administration Layer (OPAL) client and writes the backup files to the mounted directory.

docker run -it -p 7766:7000 -p 8181:8181 \
  --env PDP_API_KEY=<YOUR_API_KEY> \
  --env PDP_ENABLE_OFFLINE_MODE=true \
  -v <HOST_BACKUP_DIR_OR_NAMED_VOLUME>:/app/backup \
  permitio/pdp-v2:latest

Replace <YOUR_API_KEY> with your environment API key, and <HOST_BACKUP_DIR_OR_NAMED_VOLUME> with a host directory path or a Docker volume name.

Backup directory permissions

If the user inside the container can't write to the host directory, the PDP can't save its backup files, and a later offline start has nothing to load. Give the container's UID and GID ownership of the directory with chown. Avoid chmod 777, which lets any local user read or change the backup.

Verify the backup files exist​

After the PDP starts and connects, list the backup directory on the host. It contains two files:

  • pdp_cloud_config_backup.json: the PDP configuration, written at startup.
  • policy_store_backup.json: the policy and data, written every minute by default and on graceful shutdown.

Run the PDP with static offline data​

To run the PDP with fixed data on purpose, for example in CI:

  1. Run the PDP in an environment that can reach Permit, with offline mode on, until both backup files exist.
  2. Copy both files into the directory or volume mounted at PDP_OFFLINE_MODE_BACKUP_DIR in the offline environment.
  3. Start the PDP in the offline environment with the same configuration, including the same PDP_API_KEY. The PDP decrypts the configuration backup with a key derived from the API key.

How offline mode works​

At startup, the PDP tries to fetch its configuration from the control plane. If PDP_CONFIG_FETCH_MAX_RETRIES attempts fail and PDP_ENABLE_OFFLINE_MODE is true, the PDP loads its configuration from the backup file, if one exists. The PDP runs this startup flow once per container start. To resume policy and data synchronization later without a restart, use the runtime connectivity endpoints.

The PDP backs up its policy store (policy code and data) with OPAL's offline mode. You don't set any OPAL variable to enable the backup. The OPAL client loads the policy store from the backup file, if one exists, and keeps trying to connect to the control plane. When the control plane is reachable, the OPAL client fetches the latest policy and data.

The PDP writes the policy store backup at the interval set by OPAL_STORE_BACKUP_INTERVAL and on graceful shutdown. The file goes in the same directory as the configuration backup. See Offline mode configuration variables.

Start the PDP disconnected from the control plane​

note

Control plane connectivity control requires PDP version 0.9.11 or later.

Start the PDP without connecting to the control plane when you run it in an air-gapped network or during planned maintenance, and reconnect later.

Set both PDP_ENABLE_OFFLINE_MODE and PDP_CONTROL_PLANE_CONNECTIVITY_DISABLED to true. If valid backup files exist in the directory mounted at PDP_OFFLINE_MODE_BACKUP_DIR, the PDP loads its configuration and policy from them and doesn't connect to the control plane at startup.

docker run -it -p 7766:7000 \
  --env PDP_API_KEY=<YOUR_API_KEY> \
  --env PDP_ENABLE_OFFLINE_MODE=true \
  --env PDP_CONTROL_PLANE_CONNECTIVITY_DISABLED=true \
  -v <HOST_BACKUP_DIR_OR_NAMED_VOLUME>:/app/backup \
  permitio/pdp-v2:latest
note

PDP_CONTROL_PLANE_CONNECTIVITY_DISABLED has an effect only when PDP_ENABLE_OFFLINE_MODE is true and valid backup files exist. Without a valid backup, the PDP connects to the control plane.

To reconnect a PDP that started disconnected, call the enable connectivity endpoint.

Control connectivity at runtime​

When offline mode is on, the PDP exposes HTTP endpoints that connect it to or disconnect it from the control plane without a container restart.

Authenticate every connectivity request with the PDP's API key, the same value as PDP_API_KEY, in an Authorization: Bearer <PDP_API_KEY> header.

Method and pathAction
GET /control-plane/connectivityReturns the connectivity state.
POST /control-plane/connectivity/enableConnects the PDP to the control plane.
POST /control-plane/connectivity/disableDisconnects the PDP from the control plane.

Get connectivity status​

GET /control-plane/connectivity

Returns the connectivity state of the PDP.

Response:

{
  "control_plane_connectivity_disabled": true,
  "offline_mode_enabled": true
}
FieldDescription
control_plane_connectivity_disabledtrue when the PDP is disconnected from the control plane
offline_mode_enabledtrue when offline mode is enabled on this PDP

Enable connectivity (reconnect)​

POST /control-plane/connectivity/enable

Connects the PDP to the control plane. The PDP starts its policy and data updaters and fetches all policy and data from the control plane again.

Response:

{ "status": "enabled" }
ConditionResponse
Connectivity was disabled200 with { "status": "enabled" }
Connectivity is already enabled200 with { "status": "already_enabled" }
Offline mode is not enabled400 Bad Request

Disable connectivity (disconnect)​

POST /control-plane/connectivity/disable

Disconnects the PDP from the control plane. The PDP stops its policy and data updaters. The policy store keeps serving decisions from its in-memory state.

Response:

{ "status": "disabled" }
ConditionResponse
Connectivity was enabled200 with { "status": "disabled" }
Connectivity is already disabled200 with { "status": "already_disabled" }
Offline mode is not enabled400 Bad Request

Reconnect a disconnected PDP​

Check the status, then reconnect. Replace <YOUR_PDP_API_KEY> with the value of PDP_API_KEY. The first request returns "control_plane_connectivity_disabled": true, and the second returns { "status": "enabled" }.

# Check current status
curl -s http://localhost:7766/control-plane/connectivity \
  -H "Authorization: Bearer <YOUR_PDP_API_KEY>"

# Reconnect to the control plane
curl -s -X POST http://localhost:7766/control-plane/connectivity/enable \
  -H "Authorization: Bearer <YOUR_PDP_API_KEY>"

Back up and restore the backup directory​

Back up the volume or host directory mounted at PDP_OFFLINE_MODE_BACKUP_DIR on a regular schedule. A copy gives you a recovery point if the local backup files are corrupted or policy data is deleted by mistake. You can restore the PDP locally while you restore the matching state in the Permit control plane.

To restore the backup directory to an earlier point in time:

  1. Restore the directory from your copy.
  2. Start the PDP with PDP_CONTROL_PLANE_CONNECTIVITY_DISABLED=true. The PDP serves decisions from the restored snapshot and doesn't reconnect to the control plane. Without this variable, the PDP connects to the control plane and fetches the control plane's current policy and data.
  3. Restore the matching state in the Permit control plane.
  4. Reconnect the PDP with the enable connectivity endpoint, or restart the PDP without PDP_CONTROL_PLANE_CONNECTIVITY_DISABLED.

Offline mode configuration variables​

VariableDescriptionDefault
PDP_ENABLE_OFFLINE_MODEEnables offline mode with local backup and restorefalse
PDP_CONTROL_PLANE_CONNECTIVITY_DISABLEDWhen true (and offline mode is enabled), the PDP starts disconnected from the control plane and serves from local backup. Valid backup files are required; otherwise, the PDP falls back to connecting to the control plane. Can be toggled at runtime via the /control-plane/connectivity endpoints.false
PDP_OFFLINE_MODE_BACKUP_DIRDirectory used to store the PDP's offline-mode backup files/app/backup
PDP_OFFLINE_MODE_BACKUP_FILENAMEFile name of the PDP's configuration backup filepdp_cloud_config_backup.json
PDP_OFFLINE_MODE_POLICY_BACKUP_FILENAMEFile name of the policy store's backup (holds both data & code) within the PDP's backup dir. This replaces OPAL's OPAL_STORE_BACKUP_PATH.policy_store_backup.json
PDP_CONFIG_FETCH_MAX_RETRIESNumber of failed fetch attempts before the PDP switches to offline mode6
OPAL_STORE_BACKUP_INTERVALHow often the policy store backup is saved1m

Protect the backup files​

The PDP encrypts the configuration backup file on disk with a key derived from PDP_API_KEY.

The policy store backup is not encrypted

policy_store_backup.json holds your policy code and data in plain text. Anyone who can read the mounted directory or volume can read that data. Restrict access to the directory or volume. If your deployment requires an encrypted policy store backup, contact Permit support.

Next steps​

Contents

Edit this page

Need help?