SIP VAULT Installation Guide

This guide covers the complete installation of SIP VAULT, including the server components (sipvault-server, FastAPI, nginx, dashboard) and the agent component deployed on customer OpenSIPS servers.

System Requirements

Server (Digital Ocean / Ubuntu 24)

Requirement	Specification
OS	Ubuntu 24.04 LTS
CPU	2+ vCPUs (recommended: 4 vCPUs for 10,000+ concurrent calls)
RAM	16 GB
Disk	40 GB SSD (no local call storage; all data goes to S3)
Network	Public IP, ports 80/443 (HTTPS), 9060/tcp (agent), 9060/udp (HEP)
Software	nginx, Python 3.10+, certbot

Agent (Customer OpenSIPS Servers)

The agent supports two capture modes depending on the kernel version:

Mode	Kernel Requirement	Dependencies	Capabilities
eBPF (default on modern kernels)	Linux >= 4.18	None (static binary, no CGO)	CAP_BPF + CAP_NET_ADMIN + CAP_SYS_PTRACE
pcap (legacy systems)	Any Linux (CentOS 6+, Debian 7+, Ubuntu 14.04+)	libpcap	root or CAP_NET_RAW

Requirement	Specification
Architecture	x86_64 (amd64) or aarch64 (arm64)
Disk	100 MB for buffer storage (configurable)
Network	Outbound TCP to server on port 9060

Dashboard

Requirement	Specification
Type	Static SPA (React + TypeScript + Tailwind)
Build tool	Vite
Served by	nginx on the server host
Browser	Any modern browser (Chrome, Firefox, Safari, Edge)

Architecture Overview

Customer site:
  sipvault-agent (eBPF or libpcap) --TCP:9060--> sipvault-server --> S3 (per-customer bucket)
  acct_rtcp_hep (RTPProxy) --HEP/UDP:9060--> sipvault-server

User access:
  CDR Viewer --HMAC link--> Dashboard SPA <--> FastAPI <--> S3

All components run on a single server VM, except the agent which runs on each customer's OpenSIPS server. When RTPProxy runs on a separate machine from OpenSIPS, the acct_rtcp_hep module sends RTCP data directly to the server via HEP over UDP -- no agent is needed on the media server.

S3 Storage Setup (Cloudflare R2)

SIP VAULT uses Cloudflare R2 as its S3-compatible object storage. Each customer gets a dedicated bucket for tenant isolation.

Step 1: Create a Cloudflare R2 Bucket

Log into the Cloudflare dashboard at https://dash.cloudflare.com
Navigate to R2 Object Storage
Click Create bucket
Name the bucket using the convention: sipvault-{customer_id}-{region}
Example: sipvault-acme-us
Select the appropriate storage location
Repeat for each customer

Step 2: Create R2 API Tokens

You need two sets of credentials:

Server credentials (used by sipvault-server to write call data):

Go to R2 > Manage R2 API Tokens
Click Create API Token
Set permissions: Object Read & Write
Scope to the specific customer buckets
Save the Access Key ID and Secret Access Key

API credentials (used by the FastAPI service to generate pre-signed URLs):

Create another API Token
Set permissions: Object Read only
Scope to all customer buckets
Save the Access Key ID and Secret Access Key

Step 3: Note Your Account ID

Your R2 endpoint URL follows this pattern:

https://<ACCOUNT_ID>.r2.cloudflarestorage.com

Find your Account ID in the Cloudflare dashboard under R2 > Overview. You will need this for both server.env and api.env.

Server Installation

The setup script (deploy/setup-server.sh) automates the full server installation. It is idempotent and safe to re-run.

Prerequisites

Before running the setup script, build the components:

# Build the sipvault-server binary
cd server
go build -o /tmp/sipvault-deploy/sipvault-server ./cmd/sipvault-server/

# Copy the API source
cp -r api /tmp/sipvault-deploy/api

# Build the dashboard
cd dashboard
npm install
npm run build
cp -r dist /tmp/sipvault-deploy/dashboard

Step 1: Configure the Setup Script

Edit the top of deploy/setup-server.sh to set your domain and file paths:

DOMAIN="sipvault.sippulse.com.br"
EMAIL="flavio@sippulse.com"
SIPVAULT_SERVER_BIN="/tmp/sipvault-deploy/sipvault-server"
SIPVAULT_API_DIR="/tmp/sipvault-deploy/api"
SIPVAULT_DASHBOARD_DIR="/tmp/sipvault-deploy/dashboard"

Step 2: Run the Setup Script

sudo bash deploy/setup-server.sh

The script performs the following steps:

Creates the sipvault system user -- a non-login user under /opt/sipvault
Installs system dependencies -- nginx, python3-pip, python3-venv, certbot
Creates directory structure:
/opt/sipvault/api -- FastAPI application
/opt/sipvault/dashboard -- Built SPA files
/etc/sipvault -- Configuration files
/var/log/sipvault -- Log files
Copies binaries and application files:
sipvault-server binary to /usr/local/bin/sipvault-server
API files to /opt/sipvault/api/ with a Python virtual environment
Dashboard files to /opt/sipvault/dashboard/
Creates environment files from templates (if they don't already exist):
/etc/sipvault/server.env (permissions: 640, owned by root:sipvault)
/etc/sipvault/api.env (permissions: 640, owned by root:sipvault)
Installs systemd services:
sipvault-server.service
sipvault-api.service
Configures nginx with your domain and enables the site
Obtains an SSL certificate via certbot (Let's Encrypt)
Opens firewall ports via ufw: 80/tcp, 443/tcp, 9060/tcp, 9060/udp

Step 3: Configure Environment Files

Edit the server environment file:

sudo nano /etc/sipvault/server.env

SIPVAULT_LISTEN_TCP=:9060
SIPVAULT_LISTEN_HEP=:9060
SIPVAULT_S3_ENDPOINT=https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
SIPVAULT_S3_REGION=auto
SIPVAULT_S3_ACCESS_KEY=your_r2_access_key
SIPVAULT_S3_SECRET_KEY=your_r2_secret_key
SIPVAULT_CUSTOMERS=[{"id":"customer1","token":"token1","bucket":"sipvault-customer1"}]
SIPVAULT_LOG_LEVEL=info

Edit the API environment file:

sudo nano /etc/sipvault/api.env

SIPVAULT_S3_ENDPOINT=https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
SIPVAULT_S3_REGION=auto
SIPVAULT_HMAC_SECRET=your_hmac_secret_here
ANTHROPIC_API_KEY=your_anthropic_key
AWS_ACCESS_KEY_ID=your_r2_access_key
AWS_SECRET_ACCESS_KEY=your_r2_secret_key

Generate a strong HMAC secret:

openssl rand -hex 32

Step 4: Start the Services

sudo systemctl start sipvault-server
sudo systemctl start sipvault-api

Step 5: Verify Services

sudo systemctl status sipvault-server
sudo systemctl status sipvault-api
sudo journalctl -u sipvault-server -f
sudo journalctl -u sipvault-api -f

Systemd Service Details

sipvault-server.service:

[Unit]
Description=SIP VAULT Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sipvault
Group=sipvault
EnvironmentFile=/etc/sipvault/server.env
ExecStart=/usr/local/bin/sipvault-server
Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

sipvault-api.service:

[Unit]
Description=SIP VAULT API
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sipvault
Group=sipvault
EnvironmentFile=/etc/sipvault/api.env
WorkingDirectory=/opt/sipvault/api
ExecStart=/opt/sipvault/api/venv/bin/python3 -m uvicorn sipvault_api.main:app --host 127.0.0.1 --port 8000 --workers 4
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

The API runs on 127.0.0.1:8000 and is reverse-proxied by nginx at /api/.

Agent Installation

The agent installer (install/install.sh) supports both modern and legacy Linux systems. It auto-detects the kernel version to choose the appropriate capture mode.

Quick Install (One-Liner)

curl -sSL https://install.sipvault.io | bash -s -- \
  --server 10.0.0.1:9060 \
  --customer acme \
  --token SECRET

Full Install with Options

sudo bash install/install.sh \
  --server 10.0.0.1:9060 \
  --customer acme \
  --token SECRET \
  --sip-ports 5060 \
  --interface eth0 \
  --log-file /var/log/opensips.log \
  --mode auto

Installer Options

Option	Required	Default	Description
`--server`	Yes	--	Server address as `HOST:PORT`
`--customer`	Yes	--	Customer identifier (must match server config)
`--token`	Yes	--	Authentication token (must match server config)
`--sip-ports`	No	`5060`	Comma-separated SIP ports to capture
`--interface`	No	Auto-detected	Network interface for packet capture
`--log-file`	No	`/var/log/opensips.log`	OpenSIPS log file path (used in pcap mode)
`--mode`	No	`auto`	Capture mode: `auto`, `ebpf`, or `pcap`

What the Installer Does

Detects architecture (amd64 or arm64)
Detects kernel version to select the capture mode:
Kernel >= 4.18: eBPF mode (binary: sipvault-agent-linux-{arch})
Kernel < 4.18: pcap mode (binary: sipvault-agent-pcap-linux-{arch})
Installs libpcap if pcap mode is selected (via yum or apt-get)
Auto-detects the default network interface if --interface is not specified
Creates directories:
/etc/sipvault -- Configuration
/var/lib/sipvault -- Disk buffer
Downloads the agent binary to /usr/local/bin/sipvault-agent
Writes the configuration to /etc/sipvault/agent.conf
Creates a service file:
systemd (modern systems): /etc/systemd/system/sipvault-agent.service
SysV init (CentOS 6): /etc/init.d/sipvault-agent

Generated Configuration File

The installer writes /etc/sipvault/agent.conf in INI format:

[server]
address = 10.0.0.1:9060
customer_id = acme
token = SECRET

[capture]
mode = ebpf
sip_ports = 5060
interface = eth0
log_file = /var/log/opensips.log
rtp_port_min = 10000
rtp_port_max = 30000

[buffer]
path = /var/lib/sipvault/buffer.dat
max_size = 104857600

[logging]
level = info

Starting the Agent

On systemd systems:

sudo systemctl start sipvault-agent
sudo systemctl enable sipvault-agent
sudo systemctl status sipvault-agent

On SysV init systems (CentOS 6):

sudo service sipvault-agent start
sudo chkconfig sipvault-agent on

Building the Agent from Source

eBPF mode (no CGO, static binary):

cd agent
go build -o sipvault-agent ./cmd/sipvault-agent/

pcap mode (requires libpcap-dev):

# Install build dependency
sudo apt-get install -y libpcap-dev   # Debian/Ubuntu
sudo yum install -y libpcap-devel     # CentOS/RHEL

cd agent
go build -tags pcap -o sipvault-agent-pcap ./cmd/sipvault-agent/

Verifying the Installation

Server Verification

Check that both services are running:

systemctl status sipvault-server
systemctl status sipvault-api

Check that nginx is serving the dashboard:

curl -sI https://your-domain.com/
# Should return HTTP 200 with content-type text/html

Check that the API is accessible:

curl -s https://your-domain.com/api/health

Check the server logs for startup messages:

journalctl -u sipvault-server --no-pager -n 20
journalctl -u sipvault-api --no-pager -n 20

Verify TCP listener (agent connections):

ss -tlnp | grep 9060
# Should show sipvault-server listening on TCP :9060

Verify UDP listener (HEP):

ss -ulnp | grep 9060
# Should show sipvault-server listening on UDP :9060

Agent Verification

Check that the service is running:

systemctl status sipvault-agent

Check agent logs:

journalctl -u sipvault-agent --no-pager -n 20

Verify connectivity to the server:

nc -zv SERVER_IP 9060

Verify capture is active (check logs for captured INVITE messages after a test call):

journalctl -u sipvault-agent -f

End-to-End Test

Place a test call through the OpenSIPS server where the agent is running
Wait for the call to complete (hang up both sides)
Check the server logs for the call session being written to S3:

journalctl -u sipvault-server -f | grep "session complete"

Verify the data in S3 using the Cloudflare R2 dashboard or the AWS CLI:

aws s3 ls s3://sipvault-customer1/calls/ \
  --endpoint-url https://ACCOUNT_ID.r2.cloudflarestorage.com

Troubleshooting

Server Issues

sipvault-server fails to start with "SIPVAULT_S3_ENDPOINT is required"

The environment file /etc/sipvault/server.env has not been configured. Edit it with your Cloudflare R2 credentials.

sipvault-server fails with "at least one customer must be configured"

The SIPVAULT_CUSTOMERS variable must contain a valid JSON array. Ensure proper formatting:

SIPVAULT_CUSTOMERS=[{"id":"customer1","token":"token1","bucket":"sipvault-customer1"}]

API returns 502 Bad Gateway

The FastAPI process is not running or not bound to port 8000. Check:

systemctl status sipvault-api
journalctl -u sipvault-api -n 50

certbot fails during setup

Ensure your domain's DNS A record points to the server's public IP. Run certbot manually:

sudo certbot --nginx -d your-domain.com --email your@email.com

nginx config test fails

If SSL certificates don't exist yet, nginx will fail to start. Obtain the certificate first, then reload nginx.

Agent Issues

Agent fails with "permission denied" or capability errors

eBPF mode requires: CAP_BPF, CAP_NET_ADMIN, CAP_SYS_PTRACE (or run as root)
pcap mode requires: root or CAP_NET_RAW

Grant capabilities to the binary:

# For eBPF mode
sudo setcap cap_bpf,cap_net_admin,cap_sys_ptrace=eip /usr/local/bin/sipvault-agent

# For pcap mode
sudo setcap cap_net_raw=eip /usr/local/bin/sipvault-agent

Agent cannot connect to server

Check network connectivity and firewall rules:

nc -zv SERVER_IP 9060

Ensure port 9060/tcp is open on the server's firewall (ufw, iptables, or cloud security groups).

Agent falls back to pcap mode unexpectedly

The auto-detection checks the kernel version. If the kernel is < 4.18, eBPF is not available. Check your kernel version:

uname -r

To force eBPF mode (not recommended on older kernels), set mode = ebpf in /etc/sipvault/agent.conf.

No SIP traffic captured

Verify the sip_ports setting matches your OpenSIPS listen ports
Verify the interface setting is correct: ip route show default
In pcap mode, ensure log_file points to the actual OpenSIPS log file
Check that the agent binary variant matches the mode (pcap binary for pcap mode)

Disk buffer grows continuously

The agent buffers data locally (up to 100 MB by default) when the TCP connection to the server is lost. Check server connectivity. The buffer is at /var/lib/sipvault/buffer.dat.

Dashboard Issues

Dashboard shows a blank page

Check that the built SPA files are in /opt/sipvault/dashboard/ and that index.html exists:

ls -la /opt/sipvault/dashboard/

API requests fail with CORS errors

The nginx configuration proxies /api/ to the FastAPI backend. Ensure the nginx config is correct and the site is enabled:

ls -la /etc/nginx/sites-enabled/
nginx -t