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 Dedicated IP 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. When you add more addresses, smaller configurations become available again, subject to free capacity and your rental-pause setting.

Before you start

In addition to the shared requirements, it helps to confirm that:

Nested virtualization is supported if the server itself is virtual.
Your server provider lets guest VMs use the additional public addresses.
You know the provider’s address limits and routing method.
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).

Configuring cloud mode

You add the mode to /etc/gigahost/hypervisor.toml:
```
mode = "cloud_routed"
```
The shared settings’ cloud_uplink = "auto" is best left as it is: with it, the agent reads the uplink and gateway from the current default IPv4 route.

The beginning of the configuration then looks like this:
```
backend_url = "https://api.gigahost.cloud"
host_label = "cloud-eu-1"
location = "de-frankfurt"
mode = "cloud_routed"
```
Enrollment and service setup come next; they are described in Setting up a host.
After enrollment, you register the public addresses.

You only need to set cloud_uplink to an explicit Linux interface name 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.

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.

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, and boots the catalog’s Debian 12 image.
It installs and updates its software from Gigahost’s signed release channel, so the host needs outbound HTTPS access.

What the router does

The router VM is the guests’ only way in or out. While it is down, the host’s guests have no network.

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 counts every guest’s traffic. Guest traffic is billed from the router’s counters, never from the hypervisor’s.

Bandwidth limits

Each guest’s bandwidth is limited on its interface by the hypervisor agent, both directions alike:

Guest	Limit
Fewer than 16 vCPUs	50 Mbit/s per vCPU
16 vCPUs or more	None
Sharing the host’s address	No more than 20 Mbit/s

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.

Keeping the management uplink unchanged

Placing the physical management interface inside a guest bridge is best avoided. 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;
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 a Dedicated IP. 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.

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.

The host’s firewall

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.

Shared IP: the host’s own address

Every cloud host also offers VMs a Shared IP 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 a Dedicated IP. Such a VM takes no address of your pools, so a host with no address left still rents VMs that share its address.
The renter pays nothing for the Shared IP, and you have no price to set for it (see Addresses). The VM pays your other prices and counts against your host’s capacity as any VM does, and twice your traffic rate: you earn twice your traffic earnings for its traffic.

To make this work:

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. It is best left unchanged, so that the host’s own connections stay out of the ports Gigahost forwards.
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). To clear the condition, you can 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.

Registering public addresses

After enrollment, you register the eligible public IPv4 addresses that the host’s guests may use.

To find the enrolled host, run:
```
ghost provider hosts
```

To create a pool for its addresses, with the scope that matches your upstream network, run:

ghost provider ip-pool create \
  --label cloud-eu-1 \
  --scope host \
  --host <HOST_UUID>

To add one or more addresses with the route settings your server provider supplies, run:

ghost provider ip add \
  --pool <POOL_UUID> \
  --address 203.0.113.10 \
  --address 203.0.113.11 \
  --prefix-length 32 \
  --gateway 203.0.113.1

To list the pools and follow each address until it passes its check, run:
```
ghost provider ip-pools
```

On the website the pools are under Provider › IP pools.

Adding the host’s management address or an address reserved for another service is best avoided. It also helps to keep enough addresses unallocated for provider maintenance.

Pool scope

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

Scope	When
`--scope host`	The addresses can be used only on this server
`--scope account`, repeating `--host`	The upstream network lets the same addresses move between those hosts

Address settings

Repeat --address to add several addresses with the same settings.
Give the prefix and the optional --gateway and --mac-address values that the upstream network needs. Pass --mac-address <MAC> when the server provider assigns a virtual MAC to the address.
Addresses whose gateway, prefix, or MAC values differ go in separate commands.
Without --gateway, traffic from the address leaves through the gateway of the host’s default IPv4 route.

Within your own account an address is live in only one of your pools at a time, but another provider may register the same address. Gigahost cannot tell who routes an address upstream, so it checks every address before a rental can get it, as described below.

An address rests after a rental

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. It rests only from other customers: the customer whose VM it served may take it again at once, with a new VM on a host the pool serves.

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).
Removing it and adding it again, to its pool or another, or handing its pool over, keeps its rest.
A resting address does not count as free. A host that keeps its last free address for the largest size that fits may not offer its smaller sizes for up to an hour after VMs were deleted, so registering enough addresses for the VMs that come and go avoids this.

Removing an address

ghost provider ip remove \
  --pool <POOL_UUID> \
  --address 203.0.113.10 \
  --yes

This removes an address that no rental holds.

Gigahost does not accept the removal while an address is reserved or assigned to a rental, or while a check is using it, and the message says which.
An address that no rental ever held is deleted; one that a rental held stays in the pool, disabled, for that rental’s history.
ghost provider ip add re-enables a disabled address in its pool, or adds it to another of your pools.

Deleting a pool

ghost provider ip-pool delete <POOL_UUID> --yes

Once every host of a pool is retired and no rental holds one of its addresses, you can delete the pool so that its addresses can be added to another pool. As with removing one address, addresses that no rental used are deleted and the others stay disabled with the deleted pool for their history. That history does not hold the addresses back: every one of them, those that served a rental included, can be added to another pool right after.

Handing a pool to a new host identity

ghost provider ip-pool hand-over <POOL_UUID> --host <NEW_HOST_UUID>

A host’s mode, location, and capacity settings are fixed, so changing one means retiring the host and enrolling the machine again (Retiring or re-enrolling an empty host). A cloud host keeps its public addresses across this: handing the retired host’s pool to the new identity avoids deleting it and typing its addresses again.

The new host gets a pool with the same label and every address of the old one, with their gateways, prefixes, and MAC addresses, and the old pool is deleted as above. The rentals the addresses served stay on record with the old pool.
Each address is checked again through the new host before a rental can get it.
A hand-over takes the pool of one host, and only to a cloud-routed host of yours in the same location.

Address and host checks

ghost provider ip check --pool <POOL_UUID> --address <PUBLIC_IPV4>
ghost provider host check-path <HOST_UUID>

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. For the checks to pass, your upstream network needs to let inbound SSH, TCP port 22, reach the addresses.

How an address is checked

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 asks for a random value that only this VM knows, so an 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.

An address’s verification

ghost provider ip-pools shows each address’s allocation status and its verification:

Verification	Meaning
`pending`	It waits for its check
`checking`	Its check runs
`verified`	It answered, through the host it names
`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. After you correct the upstream routing, ghost provider ip check asks for another check.
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.

The host’s public path

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, and you have corrected the upstream routing, ghost provider host check-path checks the path again.

When a check cannot finish

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.
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

The checks you can run before and after resuming new rentals are under Checking a new host.