HF 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-panel 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, under Add a server, type a Name (for example London 2), paste the Join code and click Add server.

Run hf-panel node-enable <IP> --new to make a new secret and join code. Run hf-panel 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 server's own address:

Address Notes
<the joined server's API address>/node/agent, for example https://api.s2.example.com:2087/v1/node/agent tried first, when the joined server has the API's own address
https://s2.yourdomain.com:8443/node/agent the old address on the joined server's panel port; the main panel uses it when the first address cannot be reached or answers 404, 421, 502, 503 or 504

The main panel learns the joined server's API address when it asks the server for its details. 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.