LVS Relay Setup¶

Section: Licensing | Article 14
Audience: IT Administrators
Last Updated: 2026-04-07

Overview¶

The LVS Relay is a lightweight proxy service that sits between your RP-PAM server and the Ravenphyre License Verification Service (LVS). It caches license check-in responses locally, so your RP-PAM deployment continues operating normally even during internet outages or Ravenphyre service disruptions.

The relay is deployed as a Docker container on a network segment that has outbound internet access.

When to Use an LVS Relay¶

Scenario	Recommended Approach
RP-PAM server has direct, reliable internet access	No relay needed — use Online Activation directly
RP-PAM server has no internet, but another host on the network does	Deploy the LVS Relay on the internet-connected host
Internet access is intermittent or unreliable	Deploy the LVS Relay to extend the effective grace period indefinitely
Multiple RP-PAM nodes in an HA cluster	Deploy a single LVS Relay that all nodes check in through
Fully air-gapped with no internet anywhere	Use Offline Activation instead

How the LVS Relay Works¶

  RP-PAM Server(s)           LVS Relay                  Ravenphyre LVS
  (secure zone)              (DMZ / internet-facing)     (lvs.ravenphyre.net)
       |                          |                          |
       |--- check-in request ---->|                          |
       |                          |--- forward to LVS ------>|
       |                          |<-- LVS response ---------|
       |                          |   (cache response)       |
       |<-- cached response ------|                          |
       |                          |                          |

Normal operation: The relay forwards check-in requests to lvs.ravenphyre.net and caches the response. It returns the cached response to RP-PAM.

During an internet outage: The relay returns the most recent cached response. RP-PAM sees a successful check-in and continues operating normally.

During a Ravenphyre outage: Same behaviour — the relay serves the cached response.

Relay Behaviour	Details
Cache duration	30 days (configurable)
Cache persistence	Written to disk — survives container restarts
Check-in frequency	Mirrors the RP-PAM check-in (every 24 hours)
Protocol (RP-PAM to relay)	HTTPS on port 7150 (configurable)
Protocol (relay to LVS)	HTTPS on port 443 to `lvs.ravenphyre.net`

Prerequisites¶

Requirement	Details
Docker	24.0 or later on the relay host
Network (relay host)	Outbound HTTPS (443) to `lvs.ravenphyre.net`
Network (RP-PAM to relay)	TCP connectivity from the RP-PAM server to the relay host on port 7150
Registry credentials	Access to `registry.ravenphyre.net` to pull the relay image

Step 1 — Deploy the LVS Relay¶

Pull the Image¶

Bash:

docker login registry.ravenphyre.net
docker pull registry.ravenphyre.net/rppam/lvs-relay:latest

PowerShell:

docker login registry.ravenphyre.net
docker pull registry.ravenphyre.net/rppam/lvs-relay:latest

Run the Container¶

Bash:

docker run -d \
    --name lvs-relay \
    --restart unless-stopped \
    -p 7150:7150 \
    -v lvs-relay-cache:/var/lib/lvs-relay \
    -e LVS_UPSTREAM_URL="https://lvs.ravenphyre.net" \
    -e LVS_LISTEN_PORT="7150" \
    -e LVS_CACHE_DAYS="30" \
    registry.ravenphyre.net/rppam/lvs-relay:latest

PowerShell:

docker run -d `
    --name lvs-relay `
    --restart unless-stopped `
    -p 7150:7150 `
    -v lvs-relay-cache:/var/lib/lvs-relay `
    -e LVS_UPSTREAM_URL="https://lvs.ravenphyre.net" `
    -e LVS_LISTEN_PORT="7150" `
    -e LVS_CACHE_DAYS="30" `
    registry.ravenphyre.net/rppam/lvs-relay:latest

Environment Variables¶

Variable	Default	Description
`LVS_UPSTREAM_URL`	`https://lvs.ravenphyre.net`	The upstream Ravenphyre LVS endpoint
`LVS_LISTEN_PORT`	`7150`	Port the relay listens on
`LVS_CACHE_DAYS`	`30`	Number of days to cache a successful check-in response
`LVS_TLS_CERT`	(auto-generated self-signed)	Path to a custom TLS certificate for the relay's HTTPS listener
`LVS_TLS_KEY`	(auto-generated self-signed)	Path to the corresponding private key

Step 2 — Verify the Relay Is Running¶

Bash:

# Check container status
docker ps --filter "name=lvs-relay"

# Check the relay health endpoint
curl -sk https://localhost:7150/health | python3 -m json.tool

PowerShell:

docker ps --filter "name=lvs-relay"
Invoke-RestMethod -Uri "https://localhost:7150/health" -SkipCertificateCheck

Expected response:

{
    "status": "healthy",
    "upstreamReachable": true,
    "cacheEntries": 0,
    "cacheMaxAgeDays": 30
}

Note: upstreamReachable indicates whether the relay can currently reach lvs.ravenphyre.net. If false, the relay will still serve cached responses.

Step 3 — Configure RP-PAM to Use the Relay¶

Edit the RP-PAM configuration file to point license check-ins at the relay instead of directly at lvs.ravenphyre.net.

Locate the Configuration File¶

Platform	Path
Windows	`C:\ProgramData\Ravenphyre\RP-PAM\config\rppam.config`
Linux	`/etc/rppam/rppam.config`
Docker	`/etc/rppam/rppam.config` (on the mapped volume)

Edit the Configuration¶

Windows (PowerShell):

notepad "C:\ProgramData\Ravenphyre\RP-PAM\config\rppam.config"

Linux (Bash):

sudo nano /etc/rppam/rppam.config

Find the license section and add or update the lvsUrl setting:

{
  "license": {
    "lvsUrl": "https://relay-host.example.com:7150",
    "offlineMode": false
  }
}

Replace relay-host.example.com with the hostname or IP address of the machine running the LVS Relay container.

Important: Do not set offlineMode to true when using a relay. The relay handles check-ins on behalf of RP-PAM, so online mode must remain enabled.

Restart RP-PAM¶

Windows (PowerShell):

Restart-Service -Name "RavenphyreRpPam"

Linux (Bash):

sudo systemctl restart rppam

Docker:

docker restart rppam

Step 4 — Verify End-to-End¶

After restarting RP-PAM, verify that check-ins are flowing through the relay.

Check RP-PAM License Status¶

PowerShell:

Invoke-RestMethod -Uri "https://localhost:7101/api/v1/license/status" `
    -Headers @{ Authorization = "Bearer $apiToken" } `
    -SkipCertificateCheck

Bash:

curl -sk "https://localhost:7101/api/v1/license/status" \
    -H "Authorization: Bearer $API_TOKEN" | python3 -m json.tool

Verify that lastCheckIn shows a recent timestamp and status is active.

Check the Relay Cache¶

Bash:

curl -sk https://relay-host.example.com:7150/health | python3 -m json.tool

After the first successful check-in, cacheEntries should be 1 or more.

Benefits of the LVS Relay¶

Benefit	Description
Internet outage resilience	RP-PAM continues to operate using cached check-in responses for up to 30 days (configurable) after the last successful upstream check-in
Ravenphyre outage resilience	If `lvs.ravenphyre.net` is temporarily unavailable, the relay serves the cache. Your deployment is not affected
Reduced attack surface	Only the relay host needs outbound internet access. The RP-PAM server can be on a fully restricted network segment
Centralised for HA	In a multi-node HA deployment, all RP-PAM nodes can point to a single relay, simplifying firewall rules
Audit visibility	The relay logs every check-in attempt, showing whether it was served from cache or forwarded upstream

Docker Compose Example¶

For deployments that run the relay alongside other infrastructure:

version: "3.8"

services:
  lvs-relay:
    image: registry.ravenphyre.net/rppam/lvs-relay:latest
    container_name: lvs-relay
    restart: unless-stopped
    ports:
      - "7150:7150"
    volumes:
      - lvs-relay-cache:/var/lib/lvs-relay
    environment:
      - LVS_UPSTREAM_URL=https://lvs.ravenphyre.net
      - LVS_LISTEN_PORT=7150
      - LVS_CACHE_DAYS=30

volumes:
  lvs-relay-cache:

Relay Management¶

View Relay Logs¶

docker logs lvs-relay --tail 50
docker logs lvs-relay -f    # follow in real time

Restart the Relay¶

docker restart lvs-relay

Clear the Cache¶

If you need to force a fresh check-in (for example, after importing a new license):

Bash:

docker exec lvs-relay rm -rf /var/lib/lvs-relay/cache/*
docker restart lvs-relay

PowerShell:

docker exec lvs-relay rm -rf /var/lib/lvs-relay/cache/*
docker restart lvs-relay

After clearing the cache, the next RP-PAM check-in will be forwarded upstream to lvs.ravenphyre.net.

Update the Relay¶

docker pull registry.ravenphyre.net/rppam/lvs-relay:latest
docker stop lvs-relay
docker rm lvs-relay
# Re-run the docker run command from Step 1 (the volume preserves the cache)

High Availability Considerations¶

For production HA deployments, consider running two LVS Relay instances behind a load balancer:

  RP-PAM Nodes ---> Load Balancer (port 7150) ---> LVS Relay 1
                                                ---> LVS Relay 2

Each relay maintains its own cache, so either one can serve requests independently. Configure the lvsUrl in rppam.config to point at the load balancer address.

Troubleshooting¶

Symptom	Cause	Resolution
Relay health shows `upstreamReachable: false`	Firewall blocking outbound HTTPS to `lvs.ravenphyre.net`	Open port 443 outbound from the relay host to `lvs.ravenphyre.net`
RP-PAM cannot reach the relay	Firewall between RP-PAM and relay, or wrong URL in config	Verify TCP connectivity: `nc -zv relay-host 7150` (bash) or `Test-NetConnection relay-host -Port 7150` (PowerShell)
Certificate error when RP-PAM connects to relay	Relay using self-signed certificate	Either install a trusted certificate on the relay (via `LVS_TLS_CERT`) or add the relay's CA to the RP-PAM trust store
`cacheEntries: 0` after RP-PAM check-in	Check-in failed before reaching the relay	Check RP-PAM logs for license check-in errors
Cache expired (check-in overdue warnings)	Internet has been down longer than `LVS_CACHE_DAYS`	Restore internet connectivity, or increase `LVS_CACHE_DAYS` and clear/re-populate the cache
Relay container exits immediately	Port conflict or permission error	Check `docker logs lvs-relay` for the startup error

Next Steps¶

Online License Activation — Activate your license before setting up the relay
Offline License Activation — For fully air-gapped environments where even a relay is not possible
High Availability Setup — Configure RP-PAM for multi-node HA