Shared Private Network (SPN)

Concept

The Shared Private Network (SPN) is a secure infrastructure for creating a unified interaction space between servers, services, and developers. It is implemented using VPN technologies, providing secure and convenient data exchange as well as centralized access management.

Key principles

Security: all data is transmitted over an encrypted channel.
Ease of connection: employees and services connect via a single access point in accordance with company policies.
Management flexibility: support for changing gateways, subnets, and DNS.
Integration: ability to link user and node management with existing internal systems.

Benefits

A unified network map including nodes, gateways, and subnets. Allows viewing the current state of the infrastructure and managing connection parameters.
A visual network map showing active connections, node status, and routes. Useful for monitoring and quickly identifying issues.
A network management module via the SPN API, which enables integration with internal personnel and infrastructure management systems.
Ability to switch a node gateway (e.g., for load balancing or failover) and reconfigure subnets.

DNS

An internal DNS record system accessible only to employees when connected to the private network. Used for:

convenient access to services and nodes by name
configuring unified routing and name resolution rules for employees (developers)

SPN Client

The SPN client (github.com/cloudnetip/netip-spn) is a WireGuard-based tool for connecting to the Shared Private Network. It provides a CLI for macOS and Linux, plus a native menubar GUI app for macOS.

Installation

macOS

Install via Homebrew (recommended):

bash

# Add the tap
brew tap cloudnetip/tap

# Install CLI only
brew install cloudnetip-spn

# Install GUI + CLI (recommended)
brew install --cask cloudnetip-spn

# Updating GUI + CLI
brew update && brew upgrade --cask --greedy cloudnetip-spn && brew link cloudnetip-spn

The cask installs Cloudnetip SPN.app in /Applications and adds the netip-spn CLI to your PATH. The app is ad-hoc signed and works without additional security prompts.

Linux

Build from source:

bash

# Install dependencies
sudo apt install wireguard-tools zenity   # Debian/Ubuntu
# or equivalent for your distribution

# Clone and build
git clone https://github.com/cloudnetip/netip-spn.git
cd netip-spn
make build && sudo make install

The GUI is macOS-only. On Linux, use the CLI directly or create a .desktop launcher.

Other Systems

For Windows, Android, iOS, and other platforms, use the official WireGuard client.

Download your SPN configuration file from cloudnetip.com/app/shared and import it into the WireGuard application:

Install WireGuard for your platform
Download the .conf file from the SPN portal
Import the configuration:
- Windows: Click "Import tunnel(s) from file"
- Android/iOS: Scan QR code or import file
- Other: Follow platform-specific import instructions

CLI Usage

The fastest way to get configured is the browser-based sign-in. It uses an OAuth 2.0 authorization-code flow with PKCE over a loopback redirect (RFC 7636 + RFC 8252):

bash

# Open the browser, pick your SPN account, config is saved automatically
netip-spn auth login

What happens:

The CLI launches your browser at cloudnetip.com/app/shared/authorize.
You choose which SPN to connect to in the web UI.
The config is written to ~/.cloudnetip/spn.conf (mode 600).

There is no persistent auth token: the WireGuard config itself is the credential. Re-run auth login at any time to rotate credentials or switch to a different SPN.

bash

# Remove saved config and the deployed wg-quick copy
netip-spn auth logout

Initial Setup (manual config)

If you'd rather skip the browser flow, download the config file from cloudnetip.com/app/shared and install it manually:

bash

# Install config with file picker
netip-spn config

# Or specify path directly
netip-spn config ~/Downloads/spn.conf

The config is validated and stored in ~/.cloudnetip/spn.conf (mode 600).

Connect to SPN

bash

# Bring tunnel up (requires sudo)
netip-spn connect

The command will prompt for your sudo password to configure the WireGuard interface.

Check Connection Status

bash

# Check tunnel state (no sudo needed)
netip-spn status

Disconnect

bash

# Bring tunnel down
netip-spn disconnect

GUI Usage (macOS only)

The menubar app provides the same functionality as the CLI with a native macOS interface.

Features

Menubar Icon: Shows connection status at a glance
Sign In / Sign Out: Browser-based OAuth login that saves the SPN config automatically (same PKCE flow as the CLI)
Quick Actions: Connect/Disconnect with one click
Auto-refresh Status: Real-time tunnel state updates
Config Management: Load WireGuard configs via native file picker (alternative to Sign In)
Terminal Integration: Connect/Disconnect actions open Terminal for sudo password entry

First-time Setup

Launch Cloudnetip SPN.app from Applications
Click the menubar icon
Choose Sign In — the browser opens at the SPN portal, you pick the SPN account, and the config is written to ~/.cloudnetip/spn.conf automatically. (Alternatively, use Load Config to import an existing WireGuard file.)
Click Connect (Terminal window opens for sudo password)
Enter your password to bring the tunnel up

Use Sign Out in the menubar to remove the saved config.

Configuration Files

Path	Purpose
`~/.cloudnetip/spn.conf`	Your saved WireGuard config (mode 600)
`~/.cloudnetip/wg-netip.conf`	Deployed copy used by `wg-quick`
`/var/run/wireguard/wg-netip.name`	Created by wg-quick when tunnel is up

The client uses standard WireGuard configuration format. Example:

ini

[Interface]
PrivateKey = your-private-key
Address = 10.11.0.2/24
DNS = 10.11.0.1

[Peer]
PublicKey = server-public-key
Endpoint = internal.example.ltd:51820
AllowedIPs = 10.11.0.0/16
PersistentKeepalive = 25

Every connect re-deploys the saved config from ~/.cloudnetip/spn.conf, so you can edit it directly without re-running config.

Troubleshooting

Connection Issues

bash

# Check WireGuard interface status
sudo wg show

# Verify config is valid
cat ~/.cloudnetip/spn.conf

# Check system logs
sudo dmesg | grep wireguard

Permission Issues

The connect and disconnect commands require sudo to configure network interfaces. If you get permission errors:

bash

# Ensure WireGuard tools are installed
which wg-quick

# On macOS
brew install wireguard-tools

# On Linux
sudo apt install wireguard-tools

Config Not Found

If you see "config not found" errors:

bash

# Verify config exists
ls -la ~/.cloudnetip/spn.conf

# Re-save your config
netip-spn config ~/path/to/your/spn.conf

Force Stop Connection

If netip-spn disconnect hangs, or a wireguard-go process is left running after a crash, you can forcibly stop the current connection by killing the process and removing the marker file left by wg-quick:

bash

sudo ps aux | grep -i '[w]ireguard-go' | awk '{print $2}' | xargs sudo kill -9 \
  && sudo rm /var/run/wireguard/wg-netip.name

After that you can run netip-spn connect again.

The concept

Using