Skip to content

Networking

PteroCloud's networking layer maps provider bridges to panel networks and gives each instance interfaces and addresses from managed pools.

Networks

The instance network model

An instance owns network interfaces (net0, net1, …):

  • net0 is the primary NIC — created by the provisioning pipeline right after the provider network stage. It carries the instance's primary addresses.
  • Extra NICs are private-network attachments — one per attached private network, each with its own address from the network's auto-pool. The plan's max_network_interfaces caps them.

Every address row carries an assignment_type: primary, secondary, floating, nat_public, infrastructure or reserved.

Network types

Networks are typed: public_bridged, public_routed, private, nat, vlan, floating. Provider mappings pin each panel network onto a provider connection's bridge (vmbr0, …) with an optional VLAN tag; the sync imports provider bridges into these rows.

Feature map

Feature Page
Address allocation & lifecycle IPAM
Extra IPs (attach/detach/promote) IPAM
Floating IPs VPS networking
Private networks (customer) VPS networking
Firewall & security groups VPS networking
Reverse DNS VPS networking
Bandwidth metering VPS networking

Guest configuration honesty

For a bridged network an extra address needs no provider-side change — the provider stage is a no-op success — but the guest must configure the address itself. The image's network_management_mode decides what the panel records:

  • initial_cloud_init_only / manual_after_boot → guest_config_required plus an activity note;
  • managed_reboot → reboot_required;
  • guest_agent → a verify-only agent read; an unanswered agent degrades to the manual note, never a task failure.

Nothing pretends traffic flows when it does not: NAT forwards carry gateway_sync_pending, and unmapped private networks are flagged provider_config_pending.

IP history and audit

The IP history table is append-only (assigned, reserved, released, quarantined, promoted, demoted, moved). The admin IP view and quarantine page reconstruct provenance from it.

php artisan pterocloud:ipam:audit
php artisan pterocloud:network:inspect <instance_uuid>
php artisan pterocloud:network:dry-run <instance_uuid>