PanelDOCSv1.0.0

Servers and cluster

How a main HF Panel manages joined servers with signed commands on /v1/node/agent, and how the DNS cluster copies zones.

One HF Panel can manage several servers. The main panel keeps the accounts, DNS, billing and logins; each hosting account's websites, email, databases and files live on the server it was created on. This page explains how the servers talk to each other, for administrators who want to understand or check the set-up.

Join a server

Where: Server Admin › Accounts › Servers

  1. Install HF Panel on the new server with its own name, for example s2.yourdomain.com. DNS stays on the main server, so install it with --no-dns.

  2. On the new server, run the command shown on the Servers screen, with the main server's IP address:

    bash
    hf-agent node-enable 198.51.100.10

    It prints a join code. Keep it secret: it lets that panel manage this server.

  3. On the main panel, click Create on the Add a server card and type a Name (for example London 2), paste the Join code and click Add server.

Run hf-agent node-enable <IP> --new to make a new secret and join code. Run hf-agent node-disable on a server to stop it accepting commands from a main panel.

The join code holds the joined server's host name, its panel port and a shared secret of 64 hexadecimal characters. node-enable accepts several main-panel IP addresses, separated by spaces or commas.

How commands are sent: /v1/node/agent

The main panel sends each command for a joined server as a signed POST to the joined server's API address: <its API address>/node/agent, for example https://api.s2.example.com/v1/node/agent. The join code that hf-agent node-enable prints carries that address, so the joined server needs the API's own address (hf-agent api-portal on) before it is joined. It also checks the joined server's certificate against the one it saw when the server was added.

The joined server checks every request:

  1. The caller's IP address must be one of the main-panel addresses given to node-enable. Otherwise: 403 "not allowed from ".

  2. Only POST is accepted (405 otherwise).

  3. These headers must be present and valid:

    Header What it holds
    X-HF-Time the Unix time the request was made
    X-HF-Nonce 24 random hexadecimal characters, used only once
    X-HF-Cmd the command name
    X-HF-Args the command's arguments: a JSON list, base64-encoded
    X-HF-Body the SHA-256 of the body, in hexadecimal
    X-HF-Sig the signature (below)

  4. X-HF-Sig must equal the hexadecimal HMAC-SHA256, made with the shared secret, of these five values joined by new lines: X-HF-Time, X-HF-Nonce, X-HF-Cmd, X-HF-Args, X-HF-Body.

  5. The clocks may differ by at most 5 minutes (401 "the clocks of the two servers differ by more than 5 minutes").

  6. The body must match X-HF-Body (401 "body does not match its signature").

  7. A nonce seen in the last 15 minutes is refused (401 "replayed request").

  8. At most 12 arguments of up to 4 KB each, without control characters (400 "bad arguments").

  9. The command must be one a main panel may send to a joined server (403 "command not allowed here").

The command runs on the joined server with the body as its input, and its output is the answer (500 with the error output when it fails). The joined server also answers 402 while its paid-edition licence needs attention.

Important: keep the servers' clocks right (for example with NTP). A clock more than 5 minutes out stops every command.

The Servers screen

The Servers screen lists the main server and every joined server, asking each one live:

Column What it shows
Server the server's name; the main server is marked this panel
Address its host name
IP its IP address
Accounts how many hosting accounts live there
Status Online, Not answering or No new accounts

For each joined server you can Check it again, and from its menu choose Stop placing new accounts here (or Place new accounts here again), set the Public IP used in DNS, or Remove server. The main server's name can be changed with Rename.

When you create an account through the API with an administrator's token, "server": "auto" (the default) puts it on the server with the fewest accounts that takes new ones. Send a server's id to choose it yourself. See API: accounts.

DNS cluster

Secondary nameservers copy every DNS zone from the main server and keep answering when it is down.

Where: Server Admin › Hosting › DNS cluster

  • List the secondaries' IP addresses under Secondary nameservers and click Save. Only those addresses may copy the zones (AXFR), and each is told about every change straight away (NOTIFY).
  • Click Make secondary next to one of your joined servers to set up BIND on it as a secondary in one step.
  • Any other server with BIND 9.18 or later can be a secondary. It follows a catalog zone, catalog.hostfog.invalid, so new and removed domains appear on it automatically. The screen shows the exact configuration to add.
  • The table shows each secondary as In sync (with its catalog serial) or Not answering yet.

Then point ns2 at the secondary's IP address at your domain registrar (glue records).

For the full screen, see DNS cluster.