Cloud mode

Cloud mode is for servers whose provider routes or attaches additional public IPv4 addresses to the server. Each rented VM gets one of those addresses as its own and uses the host’s network capacity, without a separate gateway.

When your host has only one available public IPv4 address left, it accepts only the largest VM configuration that currently fits its remaining resources on one NUMA node. Adding more addresses makes smaller configurations available again, subject to free capacity and your rental-pause setting.

Before you start

In addition to the shared hypervisor requirements, confirm that:

Nested virtualization is supported if the server itself is virtual.
Additional public addresses may be used by guest VMs.
The provider’s address limits and routing method are understood.
The host has a stable public uplink and enough included or affordable transfer for the capacity you advertise.
The root pool has 8 GiB free on top of the root storage your capacity profile advertises: 4 GiB for the router VM and 4 GiB for the VM that checks your addresses. Enrollment checks this.
Nothing on the host listens publicly on ports 1000 to 60999 of its own address: those ports are Gigahost’s for VMs that share the host’s address (see Shared IP).

Some providers assign public address pools to one physical host; others make a pool available across an account. Gigahost supports both. Register the pool with the matching scope in your provider account so an address is never assigned where it cannot be routed.

The router VM

Every cloud host runs one platform-owned router VM, gigahost-router. The running agent creates it once the host is enrolled and checks every minute that it is running; it is not a rental, and you do not configure it. It has 1 vCPU, 1 GiB of RAM, and a 4 GiB root volume on the root pool, boots the catalog’s Debian 12 image, and installs and updates its software from Gigahost’s signed release channel, so the host needs outbound HTTPS access.

The router VM is the guests’ only way in or out. It holds the route to each guest’s public address, forwards only traffic a guest sends from its own address and MAC toward public destinations, and forwards no IPv6. It drops a guest’s outgoing mail, TCP connections to ports 25 and 465, unless Gigahost lifted the block for the guest’s account on its owner’s request: a guest that sent spam would put your addresses, and soon your whole range, on blocklists. Submission with a login (587) and receiving mail stay open. It also counts every guest’s traffic: guest traffic is billed from the router’s counters, never from the hypervisor’s. While the router VM is down, the host’s guests have no network.

Each guest’s bandwidth is limited on its interface by the hypervisor agent, both directions alike: 50 Mbit/s per vCPU, none from 16 vCPUs on, and no more than 20 Mbit/s for a guest that shares the host’s address. The limit is in the guest’s libvirt definition from its creation, and the agent changes it on a running guest without a restart (virsh domiftune) when Gigahost changes the limits or the guest is upgraded. An agent that does not know the limits leaves its guests unlimited until it is updated.

Keep the management uplink unchanged

Do not place the physical management interface inside a guest bridge. Neither the dependency installer nor the agent moves the host’s management address, default route, or uplink. The agent adds two bridges of its own: ghrouter, a private link between the host and the router VM, and ghguest, which the router VM and every guest attach to. Guest ports on ghguest are isolated from each other, so a guest can reach only the router. The host has no address on ghguest and neither accepts nor routes traffic from it.

For each rented address, the host routes the address to the router VM over ghrouter, answers the upstream network’s ARP requests for it, and sends traffic from the address toward the provider’s gateway through a routing table of its own. The host performs no NAT for a guest with an address of its own; only the router VM’s traffic leaves behind the host’s address: its own, such as its software updates, and that of the VMs that share the host’s address. The agent enables IPv4 forwarding on the host.

Shared IP: the host’s own address

Every cloud host also offers VMs a share of its own public address, the primary IPv4 address of its uplink: each such VM gets a slice of the address’s ports, some forwarded to it and some its outgoing connections leave from. Renters choose it instead of an address of the VM’s own; such a VM takes no address of your pools, so a host with no address left still rents VMs that share its address, and it pays nothing for the shared IP: your fixed price per rental covers it, and you have no price to set for it (see pricing). It pays your other prices and counts against your host’s capacity as any VM does. For that:

Ports 1000 to 60999 of the host’s address, TCP and UDP, are Gigahost’s. The agent forwards what arrives there to the router VM, which passes each VM its ports. Ports below 1000, such as SSH on 22, and above 60999 stay the host’s, and nothing sent to another address of the host, such as a rented address, is affected.
The host’s own outgoing connections move to source ports 61000 to 65535. The agent sets net.ipv4.ip_local_port_range to 61000 65535 and keeps it for every boot in /etc/sysctl.d/60-gigahost-ports.conf. Do not change it.
A service on the host that listens publicly in that range, on every address or on the host’s own, stops shared IP on the host: the agent checks every minute, forwards nothing while such a service listens, and reports the condition shared IP port in use, which names the service (such as tcp 8080 nginx). Move the service to a port below 1000 or above 60999, or bind it to 127.0.0.1 or a private address. Services on loopback and private addresses are not affected.
Once the host carries such VMs, their ports stay theirs: a service that starts listening in the range later is reported, but no longer receives what is sent to it there.
A host whose uplink address is not public, such as one behind the provider’s NAT, offers no shared IP.

When an address has a provider-issued MAC, the host answers for it from a separate macvlan interface with that MAC on the uplink. Otherwise the uplink answers with its own MAC. Whenever the agent sets up an address (when a guest is created or started, when an address is checked, and when the agent starts), it announces the address with ARP, so an upstream router that asked for it earlier learns the answer at once.

Configure cloud mode

Add the mode to /etc/gigahost/hypervisor.toml. By default, the agent reads the uplink and gateway from the current default IPv4 route:

mode = "cloud_routed"
cloud_uplink = "auto"

Set cloud_uplink to an explicit Linux interface name only when the registered public addresses use a different uplink. The agent reads this interface but never changes its addresses, master, link state, or default route.

The complete beginning of the configuration should now resemble:

backend_url = "https://api.gigahost.cloud"
host_label = "cloud-eu-1"
location = "de-frankfurt"
mode = "cloud_routed"

dns_servers sets the IPv4 resolvers written into the network configuration of the router VM and of every guest. Guests installed from an image also get them through cloud-init’s resolv_conf setting, which Alpine needs, since its network configuration ignores resolvers. Continue with enrollment and service setup.

Guest networking is IPv4-only: IPv6 autoconfiguration, router advertisements, and IPv6 itself are disabled on the agent’s bridges before they come up. The host firewall around the router VM is validated with nft --check and installed as one transaction. It lets the router VM reach the host only with ICMP and keeps the traffic the router VM forwards away from private address ranges, in addition to the router’s own rules.

Register public addresses

After enrollment, add the eligible public IP pool in your provider account:

Select host scope if addresses can be used only on this server.
Select account scope if the upstream network permits the same pool to be assigned across several enrolled servers.

Do not add the host management address or an address reserved for another service. Keep enough addresses unallocated for provider maintenance.

Use the CLI to find the enrolled host and register its addresses:

ghost provider hosts
ghost provider ip-pool create --label cloud-eu-1 --scope host --host <HOST_UUID>
ghost provider ip add --pool <POOL_UUID> --address <PUBLIC_IPV4> --prefix-length 32
ghost provider ip-pools

Repeat --address to add several addresses with the same settings. Use the prefix and optional --gateway and --mac-address values required by the upstream network, and add addresses separately when those values differ. Without --gateway, traffic from the address leaves through the gateway of the host’s default IPv4 route. ghost provider ip remove --pool <POOL_UUID> --address <PUBLIC_IPV4> --yes removes an address that no rental currently holds; one that a rental held before stays in the pool, disabled, for that rental’s history.

An address that a rental was reached at rests for an hour after the rental ends before another rental gets it, so that what is still meant for the old VM, such as traffic its customer’s DNS records send there, does not reach the next customer. An address that was only set aside for a creation that failed is free at once. ghost provider ip-pools and the pool’s page under Provider › IP pools (/provider/ip-pools/POOL_ID) show until when an address rests (available_at; “Reusable from” on the website), and adding it again, to its pool or another, does not end the rest. A resting address does not count as free: a host that keeps its last free address for its largest size may refuse its smaller sizes for up to an hour after VMs were deleted, so register enough addresses for the VMs that come and go.

Another provider may register an address that you also register: Gigahost cannot tell who routes an address upstream, so it checks every address before a rental may get it, as described below. Within your own account an address is live in one pool at a time.

Address and host checks

Gigahost checks your setup once instead of checking every new VM: each address when you add it, and each host’s public path before the host first accepts rentals. A new VM never waits for a check; it gets only an address that has passed its check.

An address is checked through an online host of its pool; the check starts within a minute or so of the address being added. The host boots a small temporary VM from the Ubuntu 24.04 image that enrollment uses, with 1 vCPU, 1 GiB of RAM, and the 4 GiB root volume kept free for it. The VM answers on up to 16 waiting addresses at once, set up exactly as a rental’s address would be: routed to the router VM, answered for on the uplink or from the address’s provider-MAC interface, and announced. Gigahost then logs in on each address over SSH from outside with a one-time key and requires a random value that only this VM knows, so a simple open SSH port, or another machine answering on the address, is not enough. It tries each address up to 18 times, about ten seconds apart, and then the host removes the VM, its disk, and its routes. Only then can a rental be assigned an address that answered. The VM uses none of the capacity you sell, and nobody is billed for it. A host runs one check at a time, so a large pool takes several checks. Your upstream network must let inbound SSH, TCP port 22, reach the addresses.

ghost provider ip-pools shows each address’s verification: pending while it waits for its check, checking, verified with the host it answered through, or failed with the reason, such as a refused or timed-out connection. A failed address is never assigned and is not checked again on its own. Correct the upstream routing, then ask for another check:

ghost provider ip check --pool <POOL_UUID> --address <PUBLIC_IPV4>

A verified address stays verified. Adding an address again after removing it, or with a different gateway, prefix, or MAC, makes it wait for a new check. An address that a check is using cannot be removed or changed until the check is over.

A host can resume rentals only once its public path is verified, that is, once one of its pools’ addresses has answered through it. Until then ghost provider host resume fails with public_path_unverified. ghost provider hosts shows public_path_verified_at, whether a check is running (public_path_checking), and, when no checked address answered through the host, why (public_path_error). Gigahost checks the path on its own, with the addresses of the host’s pools that wait for their check, or, when an account-scoped pool’s addresses were all verified through other hosts, with one of those. After a check through the host had no answer, correct the upstream routing and check the path again:

ghost provider host check-path <HOST_UUID>

Checks run only on an active, online host that is not being retired and runs a current agent. If a check cannot finish, because its VM could not boot, Gigahost could not log in on its own side, or the host went offline during the check, neither the addresses nor you are blamed: no incident is opened for you, and the addresses are checked again 15 minutes later. A check holds its addresses until the host has removed its VM, so a host cannot be retired while a check’s VM may still be on it; declaring a lost host an emergency releases them at once. On the website, a pool’s page shows each address’s check (Waiting, Checking, Verified or Check failed) with Check again for a failed one, and a cloud host’s Overview and Settings tabs have an IP addresses section with Check now; the host reads No verified address until one of its addresses has passed the check through it, and Checking addresses while a check runs. Both update in place while a check runs. The Overview’s section also lists the addresses of the host’s pools, each with its gateway, whether it is free, reserved or in use, and its check unless it is verified.

Operational checks

Before publishing paid capacity:

Confirm that sudo virsh list shows the gigahost-router domain running.
Confirm that ghost provider ip-pools shows your addresses verified and ghost provider hosts shows the host’s public path verified.
Create a small test VM and confirm it receives an address from the intended pool.
Test inbound SSH and outbound Internet access.
Confirm the address remains reachable after a guest and host reboot.
Check that guest traffic follows the expected upstream billing policy.
Confirm the host management address and route are byte-for-byte unchanged.

If the upstream provider changes its routing requirements, pause new rentals with ghost provider host pause <HOST_UUID> until the address-pool configuration has been updated and tested. Verified addresses stay verified: add an address again with its new gateway, prefix, or MAC, or remove it and add it again, to have it checked again.