VPN Management & Access

Overview

VPN management is restricted to administrative users. By default, the ARROW platform automatically assigns users, devices, and virtual machines to their appropriate groups, with predefined policies in place to govern traffic and access. There are two primary methods for connecting to the VPN:

1. Identity Provider (IDP) Authentication: Reserved for end-user workstations.
2. Setup Token: Reserved for ARROW devices, virtual machines, and servers (e.g., shadowsocks-proxy). These systems are placed under restrictive firewall policies and cannot communicate with other devices.

DO NOT USE SETUP TOKENS ON USER DEVICES Doing so will isolate the host under a restrictive policy, and you WILL NOT be able to access any other systems on the VPN.

Technical Architecture

The Arrow VPN system uses Netbird as the VPN orchestration platform, providing a zero-trust network architecture with automated peer management. The integration between Arrow and Netbird enables seamless device provisioning, user authentication, and access control enforcement.

Netbird Integration Architecture

The Arrow backend integrates with Netbird through a dedicated API layer:

graph TD
    A[Arrow Backend] -->|Manages| B[Netbird Management API]
    B -->|Orchestrates| C[VPN Network]
    C -->|Contains| D[User Peers]
    C -->|Contains| E[Device Peers - pve]
    C -->|Contains| F[Device Peers - pvm]
    C -->|Contains| G[Device Peers - vm]
    C -->|Contains| H[SOCKS Proxy]

    I[Cloudflare DNS] -->|DNS-01 Challenge| J[Let's Encrypt]
    J -->|Issues Certificates| K[*.subdomain.arrowvpn.io]
    K -->|Secures| B

    L[Zitadel IDP] -->|Authenticates| D
    M[Setup Keys] -->|Provision| E
    M -->|Provision| F
    M -->|Provision| G
    M -->|Provision| H

Key Components:

• backend/api/netbird/netbird.go - Registers VPN API endpoints via AddNetbirdHandlers function
• backend/api/netbird/client.go - NetBirdClient class that wraps Netbird Management API calls
• Integration Configuration - Stored in system_integrations collection with type "netbird"

Automatic Device Group Assignment

When devices connect to the VPN, Arrow automatically assigns them to groups based on device type:

Device Type	Group Assignment	Description
Physical ARROW devices	pve	Proxmox Virtual Environment hosts
ARROW virtual machines	pvm	VMs running on physical ARROW hardware
External virtual machines	vm	VMs on client infrastructure (VMware, VirtualBox)
SOCKS proxy servers	socks	Shadowsocks proxy instances

Additionally, for access control purposes, Arrow creates device-specific groups:

• device-{identifier} - Contains only the specific device peer
• consultants-{identifier} - Contains NetBird users assigned to the device

User Authentication Flow

Users authenticate through Zitadel IDP, which federates with the organization’s identity provider:

sequenceDiagram
    participant User
    participant NetbirdClient
    participant Arrow
    participant Zitadel
    participant OrgIDP

    User->>NetbirdClient: netbird up --management-url
    NetbirdClient->>Arrow: Initiate auth
    Arrow->>Zitadel: Redirect to IDP
    Zitadel->>OrgIDP: Federation
    OrgIDP-->>Zitadel: Auth response
    Zitadel-->>Arrow: Token
    Arrow-->>NetbirdClient: Session established
    NetbirdClient-->>User: Connected

VPN API Endpoints

Arrow proxies the following Netbird API endpoints through the NetBirdClient:

• Peers - List, get, and manage VPN peers
• Users - Manage Netbird user accounts
• Routes - Configure network routes
• Groups - Manage peer groups
• Policies - Configure access control policies
• Health Checks - VPN connectivity testing

---

VPN Access - Users (GUI)

To connect to the VPN for the first time, log in to the ARROW Portal using your organization’s IDP. Once logged in, navigate to the VPN page and open the displayed VPN API address in a new browser tab. Since you are already authenticated in the ARROW Portal, the page will provide download and setup instructions.

Identifying the VPN Orchestrator URL

Installing the Netbird VPN Client

Once Netbird is installed, right click the Netbird try icon and select Advanced Settings and set the Management URL.

• Management URL: https://{your-domain}:443/

Management URL Configuration

VPN Access - Users (CLI)

To log into a user account from a Linux system using the command line, follow these instructions. First, capture your organization’s Management URL, which is stored in the ARROW Portal on the VPN page as the API URL. Navigate to this URL to view installation instructions (see reference illustrations above). Full Linux installation instructions can also be found here. For a quick one-liner:

# Install Netbird via the CLI one-liner
curl -fsSL https://pkgs.netbird.io/install.sh | sh

To bring Netbird online as a user, run the following command.

netbird up --management-url https://{your-domain}:443/

This should automatically launch your browser if you have a GUI. If you’re remotely accessing the Linux system, copy and paste the provided URL to authenticate.

VPN User Connection CLI

VPN Access - Servers

Adding custom devices (e.g., password recovery servers) to your VPN is straightforward, but requires administrator access within your organization. Log in to the Management URL (see sections above), navigate to the Setup Keys page, and click Create Setup Key. This will open the Create New Setup Key window. Provide the required information, then click Create Setup Key. In the example below, we’re adding a password recovery server.

Netbird Setup Key Request

To add the server to the VPN, we recommend running the following command. Optionally, you can add the --disable-dns flag to prevent Netbird from overwriting your /etc/resolv.conf file:

netbird up --management-url https://{your-domain}:443/     --setup-key XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX     --hostname {uniquename} --allow-server-ssh

Once you see the Connected message, you must add Access Control Policies to enable access to your device(s).

Groups & Access Control Policies

Groups

VTEM Labs configures the following groups in each client’s VPN console. These groups must not be modified, though you may add additional groups if needed.

Group	Description
users	This group is defined for users that are on-boarded in the system. This applies to all user workstations and local testing environments that will have access to ARROW devices and virtual machines.
pve	This group consists of physical ARROW devices (Proxmox Virtual Environment).
pvm	This group consists of ARROW virtual machines that run on physical hardware (Proxmox Virtual Machine).
vm	This group consists of virtual appliances that run on client environments (e.g., VMware, VirtualBox, etc.)
socks	This group is reserved for your shadowsocks proxy server.

Access Control Policies

Access Control Policies define network traffic rules and specify which groups can communicate within your VPN infrastructure. These policies regulate the flow of data between device types and user groups. ARROW includes several pre-configured policies to enforce secure communication.

Policy Name	Sources	Direction	Destination	Protocol	Ports	Purpose
users-to-infrastructure-udp	users	→	pve, pvm, vm	UDP	ALL	Allow users UDP access to infrastructure devices
users-to-infrastructure-tcp	users	→	pve, pvm, vm	TCP	ALL	Allow users TCP access to infrastructure devices
Socks ICMP	users, pve, pvm, vm	↔	socks	ICMP	ALL	Enable ICMP connectivity for SOCKS proxy services
socks-udp	pve, pvm, vm	→	socks	UDP	8388	Allow UDP access to SOCKS servers on port 8388
socks-tcp	pve, pvm, vm	→	socks	TCP	8388	Allow TCP access to SOCKS servers on port 8388
VPN Health Check	users, pve, pvm, vm	→	socks	TCP	443	Enable VPN connectivity health monitoring

NOTE Altering the above policies will break your VPN and negatively impact users and devices. Reconfiguration and troubleshooting will require a Change Order based on the time and effort needed to diagnose and repair any user-induced issues. Self-induced outages are not covered under the standard SLA and will be addressed at our earliest availability.

Managing Policies

If you plan to add additional infrastructure to your VPN, you must first complete an internal planning and approval process. We recommend using the Netbird application directly to generate setup tokens, create new groups, and configure corresponding policies. Note that adding additional services is not supported in the ARROW platform (e.g., newly added devices will not appear as cards in the dashboard). However, these devices will be visible in the View Details → Peers section of the VPN page within the ARROW Portal.

VPN Peers View

Adding New Policies

To add a new Access Control Policy, navigate to the Policies page under Access Control and click the Add Policy button. This opens the Create New Access Control Policy dialog window. In the example below, a new group called gpuservers has been created and a server added to the VPN. The policy provides one-way SSH access from the users, pvm, and vm groups to the gpuservers, enabling the transfer of recovered hashed credentials and execution of password recovery operations.

Create an Access Control Policy

Certificate Management

Arrow automates SSL certificate provisioning for VPN management interfaces using Let’s Encrypt with Cloudflare DNS-01 challenges. This ensures each organization’s Netbird instance has valid wildcard certificates without manual intervention.

Certificate Architecture

Certificates are issued for the pattern *.{subdomain}.arrowvpn.io, where each organization receives a unique subdomain. The certificate management system consists of:

• backend/api/vpn/certificates.go - CertificateManager class handling certificate generation and storage
• backend/api/vpn/cloudflare.go - Cloudflare DNS integration for DNS-01 challenges
• backend/api/vpn/renewal.go - Daily renewal cron job via StartCertificateRenewalCron

Certificate Lifecycle

flowchart TD
    Start[Daily Cron Job] --> Query[Query all Netbird integrations]
    Query --> Loop{For each integration}
    Loop --> CheckCert{Certificate exists?}
    CheckCert -->|No| Generate[Generate new certificate]
    CheckCert -->|Yes| CheckExpiry{Expires in < 30 days?}
    CheckExpiry -->|Yes| Generate
    CheckExpiry -->|No| Skip[Skip - certificate valid]
    Generate --> DNS[Create Cloudflare TXT record]
    DNS --> Challenge[Complete DNS-01 challenge]
    Challenge --> Issue[Let's Encrypt issues certificate]
    Issue --> Save[Save to vpn_certificates]
    Save --> Delay[Wait 30 seconds]
    Delay --> Loop
    Skip --> Loop
    Loop -->|Done| End[Complete]

Certificate Generation Process

1. DNS-01 Challenge Initiation - Arrow creates a TXT record in Cloudflare DNS for _acme-challenge.{subdomain}.arrowvpn.io
2. Let’s Encrypt Validation - Let’s Encrypt verifies domain ownership via DNS lookup
3. Certificate Issuance - Wildcard certificate is issued for *.{subdomain}.arrowvpn.io
4. Storage - Certificate and private key are stored in the vpn_certificates collection
5. Cleanup - DNS challenge record is removed from Cloudflare

Renewal Process

The StartCertificateRenewalCron function runs every 24 hours and performs:

1. Queries all Netbird integrations from system_integrations
2. For each integration, checks if a certificate exists
3. If no certificate exists, generates a new one
4. If certificate expires within 30 days, renews it
5. Waits 30 seconds between generations to avoid Let’s Encrypt rate limits

Required Environment Variables

Variable	Description
CLOUDFLARE_API_TOKEN	API token with Zone:DNS:Edit and Zone:Zone:Read permissions
CLOUDFLARE_ZONE_ID	Zone ID for the arrowvpn.io domain
LETSENCRYPT_EMAIL	Email address for Let’s Encrypt account registration

Certificate Storage

Certificates are stored in the vpn_certificates collection with the following fields:

• organization - Reference to the organization
• domain - The wildcard domain (e.g., *.subdomain.arrowvpn.io)
• cert - PEM-encoded certificate chain
• key - PEM-encoded private key
• expires_at - Certificate expiration timestamp
• last_renewed - Timestamp of when the certificate was last renewed

Netbird Integration Details

NetBirdClient

The NetBirdClient class (backend/api/netbird/client.go) provides a Go interface for the Netbird Management API. It handles authentication, request formatting, and response parsing.

Supported Operations:

Resource	Operations
Peers	List, Get, Delete, Update
Users	List, Get, Create, Update, Delete
Groups	List, Get, Create, Update, Delete
Policies	List, Get, Create, Update, Delete
Routes	List, Get, Create, Update, Delete
Setup Keys	List, Get, Create, Revoke

Device Group Naming Convention

Arrow uses consistent naming patterns for Netbird groups:

Pattern	Purpose	Example
device-{identifier}	Contains only the device peer	device-arrow-001
consultants-{identifier}	Contains users assigned to the device	consultants-arrow-001

Integration Configuration

Netbird integrations are stored in the system_integrations collection with:

{
  "type": "netbird",
  "management_url": "https://subdomain.arrowvpn.io",
  "api_key": "encrypted-api-key",
  "user_access_control_default": true
}

Health Checks

Arrow provides VPN connectivity testing through dedicated endpoints that verify:

• Netbird Management API reachability
• Peer connectivity status
• SOCKS proxy availability
• Certificate validity

VM VPN Integration

Virtual machines provisioned through ARROW are automatically integrated with the VPN. This integration is handled by backend/api/vm_complete/handlers.go and the build monitor system.

Automatic Peer Registration

When a VM is deployed, it is automatically registered as a NetBird peer:

1. Peer Creation: VM registered with unique identifier stored in device_settings.nb_device_name
2. Group Assignment: VM added to appropriate group (pvm or vm) based on device type
3. DNS Setup: Hostname registered for DNS resolution via NetBird
4. Policy Application: One-way access policies automatically applied
5. Consultant Access: Users assigned to device added to consultants-{id} group

VM Access Groups

VMs are assigned to specific groups based on deployment type:

Group	Description
pvm	VMs on ARROW’s Proxmox infrastructure
vm	VMs on external/client infrastructure
device-{id}	Device-specific group for access control
consultants-{id}	Users assigned to access the VM

VM Access Policies

One-way access policies are created for VM access:

• Consultants can connect TO VMs
• VMs cannot initiate connections to users
• Policies use TCP/UDP on all ports by default

VM Completion Cleanup

When VMs are completed via POST /api/vm/complete, VPN resources are automatically cleaned up:

flowchart TD
    A[VM Completion Request] --> B[Get device_settings]
    B --> C[Retrieve nb_device_name]
    C --> D[Get NetBird Integration Config]
    D --> E[Create NetBirdClient]
    E --> F[Fetch All Peers]
    F --> G[Match Peer by Name/Hostname]
    G --> H{Peer Found?}
    H -->|Yes| I[client.DeletePeer]
    H -->|No| J[Log Warning - Continue]
    I --> K[Delete device-{id} Group]
    J --> K
    K --> L[Remove Users from consultants-{id}]
    L --> M[Delete Associated Policies]
    M --> N[Update device_request status]

Cleanup Operations:

1. Peer Removal: VM peer deleted from NetBird via API
2. Group Cleanup: device-{id} and consultants-{id} groups removed
3. Policy Deletion: Associated one-way access policies deleted
4. Graceful Handling: Continues even if NetBird operations fail

For detailed VM management, see:

• ARROW Virtual Machines - VM system architecture
• VM Requests - Requesting and managing VMs
• Build Monitoring - Real-time build tracking
• VM Imaging Workflow - Image customization process