CloudVpn -- User Guide v1.0.0

This guide is the reference for running CloudVpn in Cloud Spectra Gateway 1.0.0. If you have not deployed a relay yet, start with the Quick Start. Command examples use the project acme, the relay team, the OCI region us-ashburn-1 and the documentation address 203.0.113.40 for the relay's public IPv4.

1. Concepts

2. Deploying a CloudVpn relay

There are two supported ways to get a CloudVpn relay in 1.0.0.

Create one with the client (recommended)

cloudspectra_relay_client create --provider oci --region us-ashburn-1 \
    --project acme --name team --mode cloud_vpn

--mode cloud_vpn is what makes the relay a CloudVpn relay: the client tells the relay at first boot to run shared egress. The default mode is cloud_address. --provider oci is the default and the only cloud on which customers can create CloudVpn relays in 1.0.0. Every option is listed in the create reference.

Switch an existing relay on the dashboard

A relay you already run can be switched to CloudVpn:

1. If the relay has port ranges under Firewall → Inbound to your phone, remove them first. A CloudVpn relay refuses inbound port ranges and will not bring the mode up while any are configured.
2. On Access, under Relay mode, select Cloud VPN and press Apply mode. You need the admin or owner role.
3. Restart the relay (see Restart, pause and upgrades). The new mode takes effect at the restart.
4. Enrol every device again. A configuration issued in one mode does not carry traffic in the other.

The mode you choose on the dashboard overrides the mode the relay was created with. The relay's cloud tags, and therefore describe, keep showing the mode it was created with.

3. create reference

The options that matter for a CloudVpn relay. Run cloudspectra_relay_client create --help for the complete list; options not listed here belong to other relay modes or to features outside CloudVpn.

create refuses --tunnel-members above 1 and --compression. The relay's device pool (10.99.0.0/16) has no create option.

4. connect, status and disconnect

connect

# first time on this device: needs a token
sudo cloudspectra_relay_client connect --project acme --name team \
    --relay 203.0.113.40 --token <token> --full-tunnel

# afterwards: no token, no dashboard, no cloud credentials
sudo cloudspectra_relay_client connect --project acme --name team

connect --help lists further options -- --takeover, --share-with, --forward, --dmz and others -- that belong to CloudAddress, where one device wears the relay's address. A CloudVpn relay does not evict a device when another one joins, so --takeover is never needed.

status

cloudspectra_relay_client status --project acme --name team

Reports this machine's enrolment and tunnel address from local state; it contacts neither the relay nor the cloud. Omit --name to list every enrolment in the project.

disconnect

sudo cloudspectra_relay_client disconnect --project acme --name team
sudo cloudspectra_relay_client disconnect --project acme --name team --vacate

A plain disconnect brings the tunnel down and keeps the enrolment, so the next connect needs no token. --vacate also removes the device from the relay and forgets the local key; the next join is a fresh enrolment with a new token.

5. Clients by platform

Downloads and install commands are in the Quick Start. The packages also install a menu-bar app (macOS), a tray app (Windows) or a desktop indicator (Linux); cloudspectra_relay_client gui opens it. This guide uses the command line throughout.

A device can be enrolled with several relays: each enrolment is kept separately under its relay's project and name.

6. Devices and enrolment tokens

Minting tokens

Tokens are minted on the dashboard's Generate Token page by an operator with the admin or owner role.

• Valid for: 1 minute, 2 minutes (the default, or the relay's --token-ttl), 5 minutes, 15 minutes, 1 hour, 24 hours or 7 days. Short is safer: an intercepted token is useless once it expires.
• One at a time: only one unused token exists. Generating a new token cancels the outstanding one.
• Reusable until it expires: by default a token enrols one device. Ticking this lets the same token enrol devices until it expires -- intended for unattended automation. For that window the token is a bearer credential for the relay, so keep the lifetime short.

A token is spent only when the device is attached. If the relay refuses a join for its own reasons -- for example, it is not ready yet -- the error says the token has not been used and is still valid.

Enrolling a phone

Phones use the official WireGuard app; nothing of ours is installed on them. On Generate Token, under Enrol a phone, enter a name, choose Full tunnel (to share the relay's address) or Split tunnel, and press Enrol a phone. The relay generates the phone's key and shows the configuration as a QR code once; scan it immediately. To enrol the phone again, repeat the step.

The device list

Access lists every enrolled device with its name, its address in the device pool and when it was enrolled, and shows how many of the relay's 65,533 device addresses are in use. Retire detaches a device from the tunnel immediately; its address returns to the pool. A retired device needs a new token to join again.

Enrolled devices are stored on the relay and survive restarts, pause and resume. They do not survive destroy: a re-created relay has a new WireGuard key and an empty device list, so every device enrols again.

7. Split and full tunnel

• Full tunnel (connect --full-tunnel, or Full tunnel for a phone) routes all of the device's IPv4 traffic through the relay. This is how a device gets CloudVpn's shared address: everything it sends to the internet leaves as the relay's public IPv4.
• Split tunnel (the default) routes only the private ranges the relay hands the device when it enrols. The device's internet traffic keeps using its own connection.

With the client, a device's choice is fixed when it enrols. To change it, mint a new token and run connect again with or without --full-tunnel. A phone's split tunnel can also be widened by editing its tunnel in the WireGuard app.

Full tunnel needs a relay that wears a public IPv4. A relay created with --addr ipv6 wears none and refuses full-tunnel enrolments; the refusal does not spend the token.

8. Restricting destinations

The dashboard's Policy page (Where devices may go) filters the destinations devices may reach through the relay. It is enforced only while the relay runs CloudVpn; on a relay in another mode the page warns that the policy is not enforced.

• Filter destinations turns filtering on. Off means no filtering at all.
• When no rule matches sets the default action: allow or deny.
• Each rule has an action (allow or deny), a destination (a network in CIDR form, or a bare address meaning that one host), an optional protocol (tcp or udp), an optional port or port range (which needs a protocol) and a note.
• The most specific rule wins, whatever order the rules were added in: a deny on 10.0.0.0/8 with an allow on 10.1.2.0/24 permits that one network and blocks the rest. Where an allow and a deny cover exactly the same network, the deny wins.
• A network must have its host bits clear: 10.1.2.3/24 is refused rather than widened.
• A policy holds up to 256 rules.
• Changes apply when the relay restarts.

The policy applies to every device on the relay alike; 1.0.0 has no per-user or per-group policy.

9. VPC peering

The relay dashboard has a page labelled Cloud VPN for AWS VPC peering: on a relay running on AWS it peers the relay's VPC with other VPCs you select and routes their private ranges to devices. It works only on AWS relays, and AWS relays are not available to customers in 1.0.0, so VPC peering is not available in this release. An OCI relay does not run the peering service, so settings saved on that page have no effect.

10. Dashboard and monitoring

The dashboard is at https://<relay public address>:28300. Its pages:

Settings worth knowing

• Dashboard certificate: enter a DNS name you own that points at the relay's public address, and the relay obtains a Let's Encrypt certificate for its dashboard. Leave it empty to use the self-signed certificate.
• Flow visibility feeds Top talkers. It takes effect when the relay restarts and keeps no flow data on disk.
• Alerts: a webhook URL (HTTPS) that receives JSON when the disk passes its threshold, when an egress allowance passes its threshold, or when the relay restarts -- at most one alert of each kind per day.
• Send the activity log to a SIEM: a URL that receives every activity-log line as JSON, in order and in batches. Delivery is best-effort; the count of dropped entries is shown if the collector stays unreachable.
• Backup & restore: download a configuration file (the password hash, the relay mode, the monitoring and flow toggles and the alert webhook) and paste it into a rebuilt relay. It does not include enrolled devices or the destination policy.
• Change password: at least 8 characters with upper case, lower case, a digit and a symbol. Every session is signed out.

11. Restart, pause and upgrades

Restarting the relay

Changing the mode, the destination policy or flow visibility takes effect when the relay restarts. The relay never restarts on its own. Restart it by rebooting its instance from your cloud console, or by pausing and resuming it with the client. Enrolled devices, settings and the mode are kept across a restart; connections in progress are interrupted.

Pause and resume

cloudspectra_relay_client pause --provider oci --region us-ashburn-1 --project acme --name team --yes
cloudspectra_relay_client resume --provider oci --region us-ashburn-1 --project acme --name team

pause stops the relay's VM without deleting it: its addresses, disk, enrolled devices and settings are kept, and the Cloud Spectra charge stops until you resume. Your cloud provider may keep charging for the disk and the reserved address; pause says what when it runs. Every connected device loses its tunnel, which is why a relay created with --mode cloud_vpn is paused only with --yes. pause refuses relays created with --ephemeral-ip or --spot.

resume starts the VM, waits until the relay serves again and checks that it came back on the same addresses. Devices keep their enrolments; if a device's tunnel was dropped, run connect --project acme --name team on it -- no token is needed.

Upgrades

A relay runs the release of the client that created it (or the one named with --package-version). Each time the relay boots it checks that it is running that release, and installs the release's signed package if it is not. To move a relay to a newer release:

1. Install the newer client on your admin machine.
2. Destroy the relay: cloudspectra_relay_client destroy --provider oci --region us-ashburn-1 --project acme --name team. Its public IPv4 is kept for its instance index.
3. Create it again with the same project, name, region and --instance-index, and --mode cloud_vpn. It comes back on the same public address, so allow-lists keep working.
4. Enrol every device again with a new token: the new relay has a new key and an empty device list. Restore the dashboard settings from a Backup & restore file saved beforehand, and re-enter the destination policy, which the file does not carry.

To update the client on a device, install the newer package over the old one.

12. Security model

What runs where

• The relay runs in your cloud account. Device traffic flows only between your devices, your relay and the destinations the devices use.
• The relay contacts Cloud Spectra's services to validate its licence, download its datapath and report vCPU-hours for billing. It needs outbound internet access to start forwarding.
• Your cloud credentials stay on the machine that runs create; they are not copied to the relay.

Devices

• Each device's WireGuard key pair is generated on the device; only the public key is sent to the relay. A phone enrolled by QR code is the exception: the relay generates its key, shows it once and keeps only the public half.
• Each device's WireGuard peer accepts exactly its own /32 address, so a device cannot send as another device.
• Nothing on the internet can open a connection to a device through the relay, and the relay has no port forwarding in this mode.
• Devices cannot reach each other through the relay.
• The destination policy limits where devices may go.

The relay's exposure

• By default the relay's cloud firewall admits TCP 22, TCP 28300 (dashboard and enrolment API), TCP 28301 (recovery SSH) and UDP 28302-28349 (WireGuard) from anywhere. Remove TCP 22 with --open-port -tcp/22 if you do not need it. Without --ssh-key, no SSH key is authorised.
• The dashboard is reachable from the internet on TCP 28300. Protect it with a strong password, add operators with the least role they need, and review the activity log. Use --source-cidr to restrict access only if every device connects from known networks, because devices use the same ports.
• Enrolment tokens are bearer credentials: keep them short-lived, and use reusable tokens only for automation.

Instance metadata

The relay does not block devices from the cloud's instance metadata address (169.254.169.254): an enrolled device can send to it through the tunnel like any other destination. Do not give the relay's instance cloud permissions that you would not give every enrolled device.

13. Troubleshooting

When you contact support@cloudspectra.ai, include the relay's provider, region, project and name, the output of cloudspectra_relay_client version on the affected device, and the dashboard's Build info.

14. Teardown

1. Disconnect devices: sudo cloudspectra_relay_client disconnect --project acme --name team --vacate.
2. Destroy the relay:

   cloudspectra_relay_client destroy --provider oci --region us-ashburn-1 --project acme --name team

Always pass --name: without it, destroy deletes every relay in the project. OCI does not charge for a kept reserved public IP, and the kept network costs nothing.