Networking

A virtual network reaches a server on one of the server's segments as a VLAN. IP blocks sit on a network and hold the addresses that are assigned to servers and carry reverse DNS. Networks live under /v1/networking/virtual-networks and blocks under /v1/networking/ip-blocks.

Virtual networks

A network's type is PUBLIC or PRIVATE:

• A public network carries IP blocks, and the addresses in them go on the internet through each block's gateway.
• A private network carries traffic between your own servers only, with no subnet and no gateway from us.

managedBy says who created the network: CUSTOMER for networks you made, SYSTEM for the internet access networks the platform sets up. List virtual networks leaves the system networks out unless you pass includeManaged=true, and type narrows it to one kind. Get virtual network returns one network with its ipBlocks. Update virtual network changes only name, and refuses a system network with 422 NETWORK_RENAME_BLOCKED.

A new server gets an internet access network of its own, named "Internet Access" and isolated from your other servers. It is the native network of the server's first segment and holds the server's IPv4 block of /30 or larger and its IPv6 /120. A server ordered with ipv4PrefixLength and ipv6PrefixLength both null (Billing) gets no network at all, and you attach networks of your own to it. The platform deletes an internet access network once it holds no IP block and no server is attached to it.

A private network joins servers in one datacenter; the network itself names no datacenter. Extending it between our datacenters, so that a server in one metro and a server in another sit on the same layer 2 network, is coming soon. Private networks carry jumbo frames, with the host's private interface set to an MTU of 9000. Frames carrying 802.1Q VLAN tags of your own cross the network too, so you can divide it into VLANs you define.

Nothing on a private network is encrypted. Traffic that needs encryption gets it from your own TLS, WireGuard or IPsec.

VLAN IDs

Every network you create has a localVlanId between 11 and 4094, unique within the organization: the VLAN tag the network carries on your servers' ports. Tags 2 to 10 are reserved for the platform. An internet access network has no VLAN ID (localVlanId is null), so it uses none of yours. Get VLAN availability returns the tags in use as usedVlanIds and the next free one as nextFreeVlanId, which is null once every tag is taken. It reserves nothing, so a create can still find its tag taken by then.

A network attached to a server also shows a provisioningVlanId: the tag it arrives with while the server's ports are on our provisioning network, during a network boot or an operation. It is the network's own localVlanId, or 10 for a network without one. Custom iPXE scripts covers what changes on the port in that mode.

Attaching a server

A server attaches to a network through a segment: one of its ports, or two bonded ports, which the host sees as one interface. The segment's id is segmentId wherever it appears: in Get network capabilities, on the entries of the service's interfaces, in the answer to Create segment, in the network lists and in every attach and address call.

Attach service takes the serviceId, the segmentId and isNative:

A segment carries one native network and several tagged ones, so a single server can sit on its internet access network and two private networks at once. A second native network on a segment is refused with 409 NATIVE_NETWORK_ALREADY_EXISTS, and a network with no VLAN ID can only be attached as native.

The change reaches the switches after the API answers, which is why an attach returns 202 Accepted, or 204 when that network is already attached on that segment. While it is applied, Get service status shows networkChange.status APPLYING. The attachment itself moves through ATTACHING to ATTACHED, or to ATTACH_FAILED, in List service virtual networks and in the network's List attached services. Detach service follows the same pattern with DETACHING and DETACH_FAILED. Setting up virtual networks walks through the calls.

A server can also run with no public network at all, reached over a private network only. It cannot be reinstalled that way: a deployment needs a primary IPv4 address on a native network and is otherwise refused with 422 PRIMARY_IPV4_REQUIRED. There is no NAT gateway either. Removing a server's public network covers both.

Addresses

Addresses live in IP blocks. A block is one range on one network in one datacenter, IPv4 or IPv6 (ipVersion V4 or V6), and gives its range as cidr along with its gateway, subnetMask and prefixLength. List IP blocks returns every block on your networks with how many addresses are used and free. Get IP block adds the addresses themselves, each in one of four states: FREE, RESERVED, GATEWAY or ASSIGNED. The gateway is the block's first usable address and is never handed out.

An address leaves the free pool in one of two ways. Reserving holds it back without binding it to a server. Assigning binds it to a server attached to the block's network, on the segment that attachment uses. A reserved address cannot be assigned until it is released. Both families use one set of calls, with the block's id and the address in the path; Managing IP addresses has them.

Reverse DNS is set on IPv4 addresses only and is checked forward first: the name you set must already resolve, through an A record, to the address you set it on. A name without that record is refused with 422 RDNS_A_RECORD_NOT_FOUND, one pointing elsewhere with 422 RDNS_A_RECORD_MISMATCH.

IP blocks

An IP block adds address space to a public network. List IP block plans has one plan per size, with its price for each billing cycle and its stock per datacenter; pass datacenter to see one location. Two calls add a block:

• On a term, it is an IP_BLOCK item of Create order, added to the network once the order's invoice is paid (Billing).
• On hourly billing, Create IP block adds it within the request and answers 201 with the block. It needs hourly billing enabled for the organization.

Both take the plan's id as plan, the datacenter as a code such as ams1 or an id, and the networkId to add the block to.

Delete IP block cancels the subscription behind a block ordered on its own and releases the block at once, provided none of its addresses is assigned to a server. The blocks a server came with are billed on the server's subscription: deleting one is refused with 422 BUNDLED_ITEM_CANCELLATION_BLOCKED, and they are released after the server is deleted.

Security scans

Our own scanner runs in production against the addresses in AS55285, yours included, and the API reports what it finds. Get security overview gives the scanner's status (lastScan, nextScan, isScanRunning) and a summary of findings by severity, with data set to null until the first scan has finished. List security findings lists each finding with filters for severity, plugin, ip and serviceId, and List scan targets gives the counts per address. Rescan target scans one address again, named in the path, and answers with its new summary. Get security scan returns one report per address assigned to a server, with its open ports and findings.

Opting out of the scans is coming soon.