Skip to content

VIP Failover Configuration

Section: High Availability | Article 17
Audience: System Administrators, Network Engineers
Last Updated: 2026-04-07

Overview

A Virtual IP (VIP) is a floating IP address that is not permanently assigned to any single server. In an RP-PAM HA cluster, the VIP is held by the current leader node. If the leader fails, the VIP automatically moves to the new leader, so clients continue connecting to the same address without reconfiguration.

When to Use a VIP

Scenario Recommendation
You have a load balancer (nginx, HAProxy, cloud LB) VIP is optional -- the load balancer handles failover
No load balancer; clients connect directly to a node VIP is recommended -- provides seamless failover
Air-gapped or isolated network without load balancer VIP is strongly recommended
Cloud deployment (AWS, Azure, GCP) Use the cloud provider's elastic/floating IP instead of a gratuitous ARP VIP

Prerequisites

Requirement Detail
HA cluster At least 2 RP-PAM nodes configured per HA Multi-Node Setup
Redis Running and connected (see Redis Setup)
Available IP A spare IP address on the same subnet as your RP-PAM nodes, not assigned to any device
Linux: root access VIP management requires ip commands with elevated privileges
Windows: DNS admin access Windows VIP uses DNS-based failover (see below)

How VIP Works in RP-PAM

  1. The leader node acquires the VIP by adding it as a secondary IP address to its network interface.
  2. On Linux, the leader sends a gratuitous ARP packet to update all devices on the subnet about the new MAC address for the VIP.
  3. If the leader fails, a standby node wins the leader election (via Redis) and immediately claims the VIP.
  4. The entire process completes within the leader lock TTL (default: 30 seconds, with promotion typically under 15 seconds).

Step 1: Choose a VIP Address

Select an IP address on the same subnet as your RP-PAM nodes that is: - Not assigned to any server, printer, or other device - Not in your DHCP range (or is reserved/excluded in DHCP) - Documented in your IP address management (IPAM) system

Example:

Node IP Address
node1 (primary) 10.0.1.10
node2 (standby) 10.0.1.11
VIP 10.0.1.50

Step 2: Configure rppam.config

Update the cluster section on every RP-PAM node.

Windows path: C:\ProgramData\Ravenphyre\RP-PAM\rppam.config
Linux path: /etc/rppam/rppam.config

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

Configuration Fields

Field Description Example
virtualIp The floating IP address "10.0.1.50"
vipInterface The network interface on which to bind the VIP "eth0" (Linux), "Ethernet" (Windows)

Important: The vipInterface must be the same interface that carries traffic on the VIP's subnet. Use ip addr (Linux) or Get-NetAdapter (PowerShell) to find the correct interface name.

Find Your Interface Name

Linux: 

ip -br addr show
# Example output:
# lo        UNKNOWN  127.0.0.1/8
# eth0      UP       10.0.1.10/24
# Use "eth0" as your vipInterface

PowerShell: 

Get-NetAdapter | Format-Table Name, InterfaceDescription, Status, LinkSpeed
# Example output:
# Name      InterfaceDescription                  Status  LinkSpeed
# ----      --------------------                  ------  ---------
# Ethernet  Intel(R) Ethernet Connection I219-LM  Up      1 Gbps
# Use "Ethernet" as your vipInterface

Step 3: Linux -- Grant RP-PAM VIP Permissions

On Linux, RP-PAM needs permission to add/remove IP addresses and send gratuitous ARP packets. Rather than running the entire service as root, grant specific capabilities:

# Allow the rppam binary to manage network interfaces
sudo setcap 'cap_net_admin+ep' /opt/rppam/rppam

# Install arping if not present (for gratuitous ARP)
# Ubuntu/Debian:
sudo apt install -y iputils-arping

# RHEL/CentOS:
sudo dnf install -y iputils

Alternatively, if your organisation uses sudoers rules:

# /etc/sudoers.d/rppam-vip
rppam ALL=(root) NOPASSWD: /sbin/ip addr add *, /sbin/ip addr del *, /usr/sbin/arping *

Step 4: Linux -- Gratuitous ARP

When RP-PAM claims the VIP on Linux, it runs:

# Add the VIP to the interface
sudo ip addr add 10.0.1.50/24 dev eth0

# Send gratuitous ARP to update the network
sudo arping -c 3 -A -I eth0 10.0.1.50

When RP-PAM releases the VIP (during graceful shutdown or demotion):

sudo ip addr del 10.0.1.50/24 dev eth0

You do not need to run these commands manually. RP-PAM executes them automatically. They are shown here for understanding and troubleshooting.

Step 5: Windows -- DNS-Based Failover

Windows does not support gratuitous ARP in the same way as Linux. Instead, RP-PAM uses DNS-based failover on Windows:

  1. Create a DNS A record for the VIP hostname (e.g., pam.corp.local) pointing to the leader node's IP.
  2. RP-PAM automatically updates the DNS record when leadership changes, using the credentials of the computer account.
  3. Set a low TTL (30-60 seconds) on the DNS record so clients pick up changes quickly.

Create the Initial DNS Record

PowerShell (run on a DNS server or with RSAT DNS tools): 

# Create a DNS record with a 60-second TTL
Add-DnsServerResourceRecordA `
  -Name "pam" `
  -ZoneName "corp.local" `
  -IPv4Address "10.0.1.10" `
  -TimeToLive (New-TimeSpan -Seconds 60)

Configure rppam.config for DNS Failover (Windows)

{
  "cluster": {
    "leaderLockTtlSeconds": 30,
    "leaderRenewalIntervalSeconds": 10,
    "outboxPollIntervalSeconds": 5,
    "heartbeatIntervalSeconds": 5,
    "virtualIp": "pam.corp.local",
    "vipInterface": "",
    "vipMode": "dns",
    "vipDnsZone": "corp.local",
    "vipDnsTtlSeconds": 60
  }
}
Field Description
vipMode "arp" (default, Linux) or "dns" (Windows)
vipDnsZone The DNS zone containing the VIP hostname record
vipDnsTtlSeconds TTL for the DNS record; lower = faster failover but more DNS queries

Grant DNS Update Permissions

The RP-PAM service account (the Windows account running the service) needs permission to update the DNS record:

# Grant the RP-PAM computer account permission to update the specific DNS record
# Run on the DNS server:
$acl = Get-Acl "AD:DC=pam,DC=corp.local,CN=MicrosoftDNS,DC=DomainDNSZones,DC=corp,DC=local"
# Add write permission for the RP-PAM service computer accounts
# (Specific steps depend on your AD DNS security model)

Note: In many environments, computer accounts can update their own DNS records by default. If the RP-PAM service runs as NT AUTHORITY\SYSTEM, and the DNS zone allows secure dynamic updates, no additional configuration may be needed.

Step 6: Test VIP Transfer

Verify the VIP Is Active on the Leader

Linux: 

# Check which node holds the VIP
ip addr show eth0 | grep 10.0.1.50
# Expected: inet 10.0.1.50/24 scope global secondary eth0

# Ping the VIP from a client machine
ping -c 3 10.0.1.50

PowerShell: 

# Resolve the DNS name
Resolve-DnsName -Name pam.corp.local
# Expected: IP address of the current leader

# Ping the VIP
Test-NetConnection -ComputerName pam.corp.local -Port 7101

Simulate a Failover

  1. Stop the leader node:

Linux (on node1): 

sudo systemctl stop rppam

PowerShell (on node1): 

Stop-Service RpPam

  1. Wait for failover (up to 15 seconds).

  2. Verify the standby has taken the VIP:

Linux (on node2): 

ip addr show eth0 | grep 10.0.1.50
# Expected: inet 10.0.1.50/24 scope global secondary eth0

PowerShell (from a client): 

# Clear DNS cache to pick up the change
Clear-DnsClientCache
Resolve-DnsName -Name pam.corp.local
# Expected: IP address of node2

  1. Verify the API responds on the VIP:

Linux: 

curl -s http://10.0.1.50:7101/system/health/ping | jq .
# Expected: {"status":"healthy","node":"node2","role":"primary"}

PowerShell: 

Invoke-RestMethod -Uri "http://pam.corp.local:7101/system/health/ping"

  1. Restart the original leader (it will rejoin as standby):

Linux: 

sudo systemctl start rppam

PowerShell: 

Start-Service RpPam

DNS Considerations

If you use a VIP (either ARP or DNS mode), update your organisation's documentation so that all users and applications connect to the VIP address rather than individual node addresses:

  • Web portal URL: https://pam.corp.local:7101
  • API base URL: https://pam.corp.local:7101/api/v1
  • Certificate SANs: Include the VIP hostname and IP in the TLS certificate

Troubleshooting

Problem Cause Solution
VIP does not appear on the leader after startup virtualIp or vipInterface misconfigured Verify the interface name matches ip addr / Get-NetAdapter output
Gratuitous ARP not updating switches Some managed switches suppress gratuitous ARP Check switch configuration; ensure GARP is allowed
Clients still connect to old leader after failover DNS cache or ARP cache on client Flush ARP cache (ip neigh flush all or arp -d *); flush DNS cache
RTNETLINK answers: Operation not permitted RP-PAM lacks cap_net_admin Re-run setcap command or configure sudoers
DNS record not updating (Windows) Service account lacks DNS update permission Grant the computer account write access to the DNS record
Failover takes longer than 30 seconds leaderLockTtlSeconds too high or Redis latency Reduce leaderLockTtlSeconds (minimum 15); check Redis latency

Next Steps

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