Configuration Reference

Section: Reference | Article 51
Audience: System Administrators
Last Updated: 2026-04-06

---

Overview

RP-PAM is configured through a single JSON file called rppam.config. This file controls all aspects of the application: node identity, database connections, authentication, clustering, AI features, and more.

File location:

Platform	Path
Windows	C:\ProgramData\Ravenphyre\RP-PAM\rppam.config
Linux	/etc/rppam/rppam.config
Docker	/app/config/rppam.config (mounted volume)

After changing rppam.config, restart the RP-PAM service for the changes to take effect:

# Windows
Restart-Service RpPam

# Linux
sudo systemctl restart rppam

Security note: rppam.config contains sensitive values (connection strings, API keys). Restrict file permissions so only the RP-PAM service account and administrators can read it. Never commit this file to source control with real credentials.

---

Complete Configuration Structure

Below is a fully annotated rppam.config with every section and every setting. Default values are shown where applicable. You do not need to include every section — RP-PAM uses sensible defaults for any setting you omit.

{
  "node": { },
  "database": { },
  "databaseSync": { },
  "auth": { },
  "redis": { },
  "lvs": { },
  "logging": { },
  "modules": { },
  "recordings": { },
  "notif": { },
  "cluster": { },
  "siem": { },
  "ai": { },
  "breakGlass": { }
}

---

node — Node Identity

Identifies this RP-PAM instance within a cluster. Every node must have a unique name.

{
  "node": {
    "nodeName": "node1",
    "grpcPortBase": 7001
  }
}

Setting	Type	Default	Description
nodeName	string	"default"	Unique name for this node. Used in cluster communication, audit logs, and health endpoints. Must be unique across all nodes in a cluster. Use lowercase alphanumeric characters and hyphens only (e.g., "node1", "pam-prod-01").
grpcPortBase	integer	7001	The starting port number for internal gRPC services. Services are assigned ports sequentially from this base: VaultService on grpcPortBase, AuthService on grpcPortBase + 1, and so on through port grpcPortBase + 11. See Network Requirements for the full port map.

---

database — Database Connection

Configures the connection to the RP-PAM database.

{
  "database": {
    "globalConnectionString": "Server=db-server.corp.local,1433;Database=RpPam_Global;User Id=rppam_svc;Password=YOUR_PASSWORD;Encrypt=True;TrustServerCertificate=False",
    "dbType": "mssql"
  }
}

Setting	Type	Default	Description
globalConnectionString	string	(required)	ADO.NET connection string to the global database. This database stores node registrations, tenant mappings, license data, and schema migration history. For MSSQL, use the standard SqlClient format. For PostgreSQL, use the Npgsql format.
dbType	string	"mssql"	Database engine type. Supported values: "mssql" (Microsoft SQL Server), "postgresql" (PostgreSQL).

Connection string examples:

MSSQL:

Server=db-server.corp.local,1433;Database=RpPam_Global;User Id=rppam_svc;Password=YOUR_PASSWORD;Encrypt=True;TrustServerCertificate=False

PostgreSQL:

Host=db-server.corp.local;Port=5432;Database=rppam_global;Username=rppam_svc;Password=YOUR_PASSWORD;SSL Mode=Require;Trust Server Certificate=false

Note: Connection string encryption is available in Phase 3. For now, protect the rppam.config file with filesystem permissions.

---

databaseSync — Database Synchronisation (HA Only)

Controls how the database is synchronised across cluster nodes. Only relevant for multi-node HA deployments.

{
  "databaseSync": {
    "mode": "external-shared",
    "nodeRole": "primary",
    "peerEndpoints": [
      "https://10.0.1.11:5201",
      "https://10.0.1.12:5201"
    ],
    "writeQuorum": 1,
    "backup": {
      "enabled": true,
      "schedule": "0 2 * * *",
      "retentionDays": 30
    }
  }
}

Setting	Type	Default	Description
mode	string	"standalone"	Database mode. "standalone" — single node, no replication. "external-shared" — all nodes connect to the same external database; RP-PAM does not manage replication. "local-sync" — each node has its own local database; RP-PAM replicates writes to N/2+1 nodes before acknowledging.
nodeRole	string	"primary"	This node's role in the cluster. "primary" — leader node, accepts writes. "standby" — receives replicated data, promotes automatically if primary fails. "dr" — disaster recovery node, receives asynchronous replication, does not participate in quorum or leader election, must be promoted manually.
peerEndpoints	string[]	[]	List of heartbeat/sync endpoints for other nodes in the cluster. Each entry is a URL in the format https://IP_OR_HOSTNAME:5201. Do not include this node's own address.
writeQuorum	integer	1	Number of nodes that must acknowledge a write before it is considered committed. For external-shared, this is typically 1 (the external DB handles consistency). For local-sync, set to N/2+1 where N is the total number of non-DR nodes.
backup.enabled	boolean	false	Enable automatic database backups on this node (only applies to local-sync mode).
backup.schedule	string	"0 2 * * *"	Cron expression for the backup schedule. Default is daily at 2:00 AM.
backup.retentionDays	integer	30	Number of days to retain automatic backups before deletion.

---

auth — Authentication and Sessions

Controls authentication token lifetimes, JWT issuer identity, and key rotation.

{
  "auth": {
    "sessionTokenExpiryMinutes": 60,
    "jwtIssuer": "rppam",
    "preAuthTokenExpiryMinutes": 5,
    "keyRotationOverlapMinutes": 30
  }
}

Setting	Type	Default	Description
sessionTokenExpiryMinutes	integer	60	How long a JWT session token is valid after issuance, in minutes. After expiry, the user must re-authenticate or use a refresh token. Lower values are more secure but require more frequent re-authentication.
jwtIssuer	string	"rppam"	The iss (issuer) claim embedded in all JWT tokens. Change this if you run multiple RP-PAM instances and need to distinguish their tokens (e.g., "rppam-prod", "rppam-staging").
preAuthTokenExpiryMinutes	integer	5	How long the pre-authentication token (issued after password verification but before MFA) remains valid. The user must complete MFA within this window. Keep this short.
keyRotationOverlapMinutes	integer	30	When the JWT signing key is rotated, the old key remains valid for this many additional minutes. This prevents active sessions from being immediately invalidated when the key rotates. During the overlap period, both the old and new signing keys are accepted.

---

redis — Redis Cache (HA Only)

Configures the Redis connection used for distributed caching and leader election in HA deployments.

{
  "redis": {
    "enabled": true,
    "connectionString": "redis-server.corp.local:6379,password=YOUR_REDIS_PASSWORD,ssl=false",
    "keyPrefix": "rppam:",
    "tlsEnabled": false
  }
}

Setting	Type	Default	Description
enabled	boolean	false	Enable Redis integration. Must be true for HA deployments. In single-node deployments, Redis is not needed and this should remain false.
connectionString	string	""	StackExchange.Redis connection string. Format: hostname:port,password=YOUR_PASSWORD,ssl=true/false. For Redis Sentinel: sentinel-host:26379,serviceName=mymaster,password=YOUR_PASSWORD.
keyPrefix	string	"rppam:"	Prefix applied to all Redis keys. Change this if multiple RP-PAM installations share the same Redis instance (e.g., "rppam-prod:", "rppam-staging:").
tlsEnabled	boolean	false	Enable TLS encryption for the Redis connection. When true, ensure ssl=true is also set in the connectionString. Your Redis server must be configured with TLS certificates.

---

lvs — License Verification Service

Controls how RP-PAM communicates with the Ravenphyre License Verification Service for license check-ins.

{
  "lvs": {
    "hostedEndpoint": "https://lvs.ravenphyre.net",
    "mirrorEndpoint": "",
    "checkInIntervalDays": 1,
    "offlineMode": false
  }
}

Setting	Type	Default	Description
hostedEndpoint	string	"https://lvs.ravenphyre.net"	URL of the Ravenphyre License Verification Service. Do not change this unless directed by Ravenphyre support.
mirrorEndpoint	string	""	URL of an LVS relay/mirror hosted on your network. Used in environments where direct internet access is restricted but an internal relay is available. See LVS Relay Setup.
checkInIntervalDays	integer	1	How often RP-PAM checks in with LVS, in days. The default of 1 means a daily check-in. RP-PAM continues to operate for up to 30 days without a successful check-in before entering grace mode.
offlineMode	boolean	false	Set to true for air-gapped environments with no internet access. When enabled, RP-PAM does not attempt LVS check-ins. You must use offline license activation (see License Activation — Offline).

---

logging — Log Output

Controls where RP-PAM writes logs and the minimum severity level.

{
  "logging": {
    "logBasePath": "C:\\ProgramData\\Ravenphyre\\RP-PAM\\Logs",
    "minLevel": "Information",
    "consoleOutput": false
  }
}

Setting	Type	Default	Description
logBasePath	string	"C:\ProgramData\Ravenphyre\RP-PAM\Logs" (Windows) or "/var/log/rppam" (Linux)	Directory where log files are written. RP-PAM creates daily rolling log files in this directory (e.g., rppam-2026-04-06.log). Ensure the RP-PAM service account has write permissions to this directory.
minLevel	string	"Information"	Minimum log severity level. Supported values (in order): "Verbose", "Debug", "Information", "Warning", "Error", "Fatal". For production, use "Information". For troubleshooting, temporarily set to "Debug".
consoleOutput	boolean	false	Also write log output to the console (stdout). Useful for Docker deployments where logs are collected from stdout. In Windows Service mode, this has no effect.

Log format is Serilog CLEF (Compact Log Event Format) — a structured JSON format. Each line is a self-contained JSON object.

---

modules — Module Loading

Controls where RP-PAM looks for installed modules.

{
  "modules": {
    "modulePath": "C:\\Program Files\\Ravenphyre\\RP-PAM\\Modules"
  }
}

Setting	Type	Default	Description
modulePath	string	"C:\Program Files\Ravenphyre\RP-PAM\Modules" (Windows) or "/opt/rppam/modules" (Linux)	Directory where RP-PAM module packages (.rmod files) are installed. Each module runs as a separate child process communicating over named pipes. The rppam-module tool installs modules to this directory.

---

recordings — Session Recordings

Controls storage and retention of privileged session recordings.

{
  "recordings": {
    "storagePath": "C:\\ProgramData\\Ravenphyre\\RP-PAM\\Recordings",
    "retentionDays": 90
  }
}

Setting	Type	Default	Description
storagePath	string	"C:\ProgramData\Ravenphyre\RP-PAM\Recordings" (Windows) or "/var/lib/rppam/recordings" (Linux)	Directory where session recording files are stored. Each recording is encrypted at rest. Ensure sufficient disk space — recordings can be large depending on session length and activity.
retentionDays	integer	90	Number of days to retain session recordings before automatic deletion. Set based on your compliance requirements (e.g., SOX may require 365 days). Deleted recordings are permanently removed and cannot be recovered.

---

notif — Notification Service

Controls notification delivery behaviour.

{
  "notif": {
    "httpTimeoutSeconds": 10
  }
}

Setting	Type	Default	Description
httpTimeoutSeconds	integer	10	Timeout in seconds for outbound HTTP calls when delivering notifications to webhook and Slack channels. If a notification endpoint does not respond within this time, the delivery is marked as failed and will be retried.

Notification channels (Slack, email, webhook) and subscriptions are configured through the web portal or REST API, not in rppam.config. This section only controls global delivery behaviour.

---

cluster — Cluster Coordination

Controls leader election, heartbeat frequency, and virtual IP failover for HA deployments.

{
  "cluster": {
    "leaderLockTtlSeconds": 30,
    "leaderRenewalIntervalSeconds": 10,
    "outboxPollIntervalSeconds": 5,
    "heartbeatIntervalSeconds": 5,
    "virtualIp": "",
    "vipInterface": ""
  }
}

Setting	Type	Default	Description
leaderLockTtlSeconds	integer	30	Time-to-live for the leader lock in Redis, in seconds. If the leader fails to renew its lock within this period, a standby node can claim leadership. Set this to at least 3x leaderRenewalIntervalSeconds to avoid false failovers during brief network hiccups.
leaderRenewalIntervalSeconds	integer	10	How often the leader renews its lock in Redis, in seconds. The leader sends a renewal heartbeat at this interval. If the renewal fails, the leader will attempt to re-acquire the lock.
outboxPollIntervalSeconds	integer	5	How often the outbox processor checks for pending events (e.g., notifications, replication batches) in seconds. Lower values reduce event delivery latency but increase database polling load.
heartbeatIntervalSeconds	integer	5	How often each node sends a heartbeat to its peers, in seconds. Peers that miss 3 consecutive heartbeats are marked as unhealthy.
virtualIp	string	""	Virtual IP (VIP) address for automatic client failover. When configured, the current leader node binds this IP to its network interface. If the leader fails, the new leader takes over the VIP. Clients connect to the VIP and are automatically routed to the active leader. Leave empty to use a load balancer instead. Example: "10.0.1.100".
vipInterface	string	""	Network interface name where the VIP should be bound. Required when virtualIp is set. On Windows, use the interface alias (e.g., "Ethernet0"). On Linux, use the interface name (e.g., "eth0", "ens192").

---

siem — SIEM Integration

Forwards audit events to an external Security Information and Event Management system.

{
  "siem": {
    "enabled": false,
    "targetType": "splunk",
    "endpoint": "https://splunk.corp.local:8088/services/collector",
    "authToken": "YOUR_HEC_TOKEN",
    "sentinelWorkspaceId": "",
    "httpTimeoutSeconds": 10,
    "batchSize": 100
  }
}

Setting	Type	Default	Description
enabled	boolean	false	Enable SIEM event forwarding. When true, RP-PAM sends a copy of every audit event, authentication event, and security event to the configured SIEM target.
targetType	string	"splunk"	SIEM platform type. Supported values: "splunk" (Splunk HTTP Event Collector), "sentinel" (Microsoft Sentinel / Azure Monitor), "syslog" (RFC 5424 syslog over TCP/TLS).
endpoint	string	""	URL of the SIEM ingestion endpoint. For Splunk: the HEC endpoint (e.g., https://splunk:8088/services/collector). For Sentinel: the Data Collector API endpoint. For syslog: tcp://syslog-server:514 or tls://syslog-server:6514.
authToken	string	""	Authentication token for the SIEM endpoint. For Splunk: the HEC token. For Sentinel: the shared key. For syslog: leave empty (authentication is typically handled at the network level).
sentinelWorkspaceId	string	""	Microsoft Sentinel workspace ID. Required only when targetType is "sentinel". Found in Azure Portal under Log Analytics Workspace > Agents management.
httpTimeoutSeconds	integer	10	Timeout in seconds for SIEM delivery HTTP calls. If the SIEM endpoint does not respond within this time, the batch is queued for retry.
batchSize	integer	100	Number of events to send in each batch. Higher values reduce HTTP overhead but increase memory usage and the size of each request. For high-volume environments, increase to 500.

---

ai — AI Assistant

Configures the AI-powered natural language interface and RAG (Retrieval-Augmented Generation) features. Requires Enterprise or MSP license tier.

{
  "ai": {
    "enabled": false,
    "provider": "ollama",
    "apiKey": "",
    "ollamaBaseUrl": "http://localhost:11434",
    "embeddingModel": "nomic-embed-text",
    "completionModel": "llama3",
    "embeddingDimension": 768,
    "chunkSize": 512,
    "chunkOverlap": 50
  }
}

Setting	Type	Default	Description
enabled	boolean	false	Enable the AI assistant. When false, all AI endpoints return a "feature disabled" response.
provider	string	"ollama"	AI provider to use. Supported values: "ollama" (self-hosted, no data leaves your network), "openai" (OpenAI API), "anthropic" (Anthropic API), "xai" (xAI API).
apiKey	string	""	API key for the configured provider. Required for "openai", "anthropic", and "xai". Not required for "ollama".
ollamaBaseUrl	string	"http://localhost:11434"	Base URL of the Ollama instance. Only used when provider is "ollama". If Ollama runs on a different server, change this to its address.
embeddingModel	string	"nomic-embed-text"	Model used for generating text embeddings (for RAG document indexing and similarity search). For Ollama: any embedding-capable model (e.g., "nomic-embed-text", "mxbai-embed-large"). For OpenAI: "text-embedding-3-small" or "text-embedding-3-large".
completionModel	string	"llama3"	Model used for generating natural language responses (chat completions). For Ollama: any chat model (e.g., "llama3", "mistral", "phi3"). For OpenAI: "gpt-4o". For Anthropic: "claude-sonnet-4-20250514". For xAI: "grok-2".
embeddingDimension	integer	768	Dimensionality of the embedding vectors produced by the embedding model. Must match the model's output dimension. Common values: 768 (nomic-embed-text), 1024 (mxbai-embed-large), 1536 (text-embedding-3-small), 3072 (text-embedding-3-large).
chunkSize	integer	512	Maximum number of tokens per text chunk when indexing documents for RAG. Smaller chunks give more precise retrieval but require more storage and more embedding API calls.
chunkOverlap	integer	50	Number of overlapping tokens between adjacent chunks. Overlap ensures that information at chunk boundaries is not lost. Set to approximately 10% of chunkSize.

Data privacy: When using "ollama", all AI processing happens on your infrastructure. No data leaves your network. When using cloud providers ("openai", "anthropic", "xai"), access request descriptions, resource names, and user queries are sent to the provider's API. Review your organisation's data handling policies before enabling a cloud AI provider.

---

breakGlass — Break-Glass Emergency Access

Configures the emergency access accounts used for incident response when the normal web portal is unavailable. See Break-Glass Emergency Access for the full operational guide.

{
  "breakGlass": {
    "monitorAccountEnabled": true,
    "monitorPasswordRotationDays": 7,
    "monitorAllowedIps": "10.0.0.0/24,192.168.1.100",
    "emergencyAccountEnabled": true,
    "emergencySessionTimeoutMinutes": 60,
    "requireHardwareKey": false,
    "emergencyAllowedIps": "127.0.0.1",
    "vendorSupportEnabled": true,
    "vendorSupportMaxMinutes": 120
  }
}

Setting	Type	Default	Description
monitorAccountEnabled	boolean	true	Enable the Tier 2 rppam-monitor account. This account provides read-only access to system health and logs during incidents.
monitorPasswordRotationDays	integer	7	How often the monitor account password is automatically rotated, in days.
monitorAllowedIps	string	"127.0.0.1"	Comma-separated list of IP addresses or CIDR ranges allowed to log in as rppam-monitor. Logins from any other IP are rejected. Example: "10.0.0.0/24,192.168.1.100".
emergencyAccountEnabled	boolean	true	Enable the Tier 3 rppam-emergency break-glass account. This account provides full local troubleshooting access with time-limited sessions.
emergencySessionTimeoutMinutes	integer	60	Maximum duration of a break-glass session in minutes. The session is forcibly terminated when this timer expires. The account is locked after expiry and new credentials must be generated.
requireHardwareKey	boolean	false	Require a FIDO2 hardware security key (YubiKey, Google Titan, etc.) for break-glass login. Set to true for all production deployments. The default of false is intended only for lab and prototype environments.
emergencyAllowedIps	string	"127.0.0.1"	Comma-separated list of IP addresses or CIDR ranges allowed to use the emergency account. For maximum security, keep this as "127.0.0.1" (local access only).
vendorSupportEnabled	boolean	true	Enable Tier 4 vendor support sessions. When true, administrators can create time-limited support sessions that grant Ravenphyre support staff read-only diagnostic access. RP-PAM never initiates outbound connections to Ravenphyre — the customer must explicitly create the session.
vendorSupportMaxMinutes	integer	120	Maximum duration of a vendor support session in minutes.

---

Minimal Configuration Examples

Single-Node (Smallest Viable Config)

The minimum settings required to run RP-PAM on a single server:

{
  "node": {
    "nodeName": "pam-server"
  },
  "database": {
    "globalConnectionString": "Server=localhost,1433;Database=RpPam_Global;User Id=rppam_svc;Password=YOUR_PASSWORD;Encrypt=True;TrustServerCertificate=True",
    "dbType": "mssql"
  }
}

All other settings use their defaults. This is suitable for a small deployment or proof-of-concept.

Two-Node HA with External Database

{
  "node": {
    "nodeName": "node1",
    "grpcPortBase": 7001
  },
  "database": {
    "globalConnectionString": "Server=db-server.corp.local,1433;Database=RpPam_Global;User Id=rppam_svc;Password=YOUR_PASSWORD;Encrypt=True;TrustServerCertificate=False",
    "dbType": "mssql"
  },
  "databaseSync": {
    "mode": "external-shared",
    "nodeRole": "primary",
    "peerEndpoints": ["https://10.0.1.11:5201"],
    "writeQuorum": 1
  },
  "redis": {
    "enabled": true,
    "connectionString": "redis.corp.local:6379,password=YOUR_REDIS_PASSWORD",
    "keyPrefix": "rppam:",
    "tlsEnabled": false
  },
  "cluster": {
    "heartbeatIntervalSeconds": 5
  },
  "breakGlass": {
    "requireHardwareKey": true,
    "emergencyAllowedIps": "127.0.0.1"
  }
}

Air-Gapped with Self-Hosted AI

{
  "node": {
    "nodeName": "pam-airgap"
  },
  "database": {
    "globalConnectionString": "Host=localhost;Port=5432;Database=rppam_global;Username=rppam_svc;Password=YOUR_PASSWORD;SSL Mode=Prefer",
    "dbType": "postgresql"
  },
  "lvs": {
    "offlineMode": true
  },
  "ai": {
    "enabled": true,
    "provider": "ollama",
    "ollamaBaseUrl": "http://localhost:11434",
    "embeddingModel": "nomic-embed-text",
    "completionModel": "llama3",
    "embeddingDimension": 768,
    "chunkSize": 512,
    "chunkOverlap": 50
  },
  "breakGlass": {
    "requireHardwareKey": true
  }
}

---

Environment Variable Overrides

Any rppam.config setting can be overridden by an environment variable. This is useful for Docker and Kubernetes deployments where secrets are injected as environment variables.

The naming convention is: RPPAM__SECTION__SETTING (double underscores as separators, all uppercase).

Examples:

Config Path	Environment Variable
database.globalConnectionString	RPPAM__DATABASE__GLOBALCONNECTIONSTRING
redis.connectionString	RPPAM__REDIS__CONNECTIONSTRING
ai.apiKey	RPPAM__AI__APIKEY
siem.authToken	RPPAM__SIEM__AUTHTOKEN
lvs.offlineMode	RPPAM__LVS__OFFLINEMODE

Environment variables take precedence over values in rppam.config. The config file value is used as the fallback if the environment variable is not set.

---

Validating Your Configuration

RP-PAM validates the configuration at startup. If there are errors, the service will fail to start and log the validation errors.

You can also validate without starting the service:

Windows:

& "C:\Program Files\Ravenphyre\RP-PAM\rppam-host.exe" --validate-config

Linux:

sudo /opt/rppam/rppam-host --validate-config

Output:

Validating rppam.config...
  [OK] node.nodeName: "pam-server"
  [OK] database.globalConnectionString: present (not shown)
  [OK] database.dbType: "mssql"
  [OK] auth.sessionTokenExpiryMinutes: 60
  [WARN] redis.enabled: false — HA will not work without Redis
  [WARN] breakGlass.requireHardwareKey: false — set to true for production
  [OK] 14 sections validated, 0 errors, 2 warnings

---

Next Steps

• REST API Reference — API endpoints and authentication
• HA Multi-Node Setup — Apply configuration for multi-node clustering
• SIEM Integration — Configure audit event forwarding

---

RP-PAM v1.0.0 — Copyright 2026 Ravenphyre. All rights reserved.