Skip to content

Host Creation and Enrollment

Before it can be used with Muppy, a Host must first be created (its connection details are recorded) and then enrolled (Muppy configures it so it is ready to be managed).

The primary way to do both at once is the Enrollment Wizard.

Tip

Hosts can also be imported automatically from a supported Cloud Provider (for example OVH). When a Host comes from a provider, the connection details are filled in for you and the wizard is essentially pre-completed.

The Enrollment Wizard

Open the wizard from Muppy ▸ Hosts ▸ Provisionning ▸ Enroll Host.

The wizard walks you through three steps: Connectivity, Control user, and Host metadata. At each step you click Check to validate before moving on with Next; the final step launches enrollment with the Enroll button.

Step 1 — Connectivity

In this step you tell Muppy how to reach the host and verify that the connection works.

  • IP Adress — the IP address Muppy should connect to.
  • SSH Port — the SSH port (default 22).
  • Sytem Username — the username provided by your hosting provider. This account must have full access to the system.
  • Connection method — choose SSH Key or Password:
    • SSH Key — select an mpy.ssh_key that has a private key. The Muppy key is pre-selected by default.
    • Password — enter the account password instead.
  • Is the server publicly accessible ? — toggle that controls whether the server is reachable from outside the internal network (for example over the Internet).

When you click Check, Muppy opens an SSH connection to confirm it can reach the host. The check also reads /etc/*-release and enforces the supported Ubuntu matrix — only the following versions are accepted:

Supported Ubuntu versions

Muppy supports Ubuntu 22.04, 24.04 and 26.04 only. If the host runs any other version, the connectivity check fails with an explicit error and you cannot continue.

Private hosts (Tailscale)

If you turn Is the server publicly accessible ? off, the host is treated as private and Muppy uses Tailscale to reach it. The wizard then shows two helper commands:

  • a Tailscale install helper — run it on the host (with a sudo-enabled account) to install Tailscale and bring it up;
  • a Tailscale IP helper (sudo tailscale ip) — run it to obtain the host's Tailscale IPv4 address.

You then enter the host's Tailscale IPv4 address in IP Adress. Muppy and the host must be on the same tailnet. You can optionally supply a Tailscale Authkey and enable Tailscale SSH.

Danger

Enabling Tailscale SSH bypasses the standard SSH service: SSH connections will only be possible via the Tailscale network. A misconfiguration can lock you out of the host.

Step 2 — Control user

Muppy manages a host through a Control User, which must be a non-root user with passwordless sudo privileges.

When you arrive at this step, Muppy tests the username you provided and reports the result:

  • ✅ The user connects and has passwordless sudo → it can be used as the Muppy Control User. (If you connected with a password, Muppy will configure SSH key authentication for future access.)
  • ⚠️ The user connects and has sudo, but sudo requires a password → not sufficient; Muppy needs passwordless sudo.
  • ⚠️ The user connects but lacks sudo → not sufficient.
  • ❌ The user fails to connect → check the credentials.

Warning

The root user is rejected: "Muppy does not allow the use of the 'root' user for host management." You must provide (or create) a dedicated non-root control user.

If the tested user is not a suitable control user, the wizard offers a Create User helper command. Choose a name for the Muppy Control User (the wizard suggests mpyadm), connect to the host with the root account, paste and run the generated command, then click Check again to confirm the new user.

Step 3 — Host metadata

The final step records the Host's metadata before enrollment:

  • Host Name (required) — the name of the Host (usually the Linux hostname).
  • Server Type (required) — parameterizes the enrollment process. See Server Types.
  • Availability Zone (required) — used to track the physical location of your servers.
  • Qualifier (required) — qualifies the host's role (production, staging, …). Defaults to production.
  • SSH Port (required) — the SSH port Muppy uses to control the Host.
  • Control User — the validated control user name (read-only at this step).
  • Launch Enroll Task — when on, enrollment runs immediately after the Host is created.

Click Enroll to create the Host. If Launch Enroll Task is enabled, Muppy creates the mpy.host record and immediately runs the enrollment sequence; the Host then moves to the ==Managed== state.

Enrolling an existing Host directly

If a Host record already exists (for example one imported from a Cloud Provider, or created manually), you can enroll it without the wizard. Open the Host form and click the Enroll Server button in the header. The button is hidden once the Host is in the ==Managed== state.

The same header also exposes:

  • Update Facts — re-collect all facts on the Host.
  • Reset as 'New' server — reset the Host's state as if it had been reinstalled (clears firewall state and is_enrolled, re-adds default rules). Used for development / re-provisioning.
  • a connectivity button (the wifi icon) — check SSH connectivity to the Host.

What enrollment does

Enrollment is driven by the Host's Server Type: each step below runs only when the corresponding do_* flag is enabled on the Server Type (see Server Types). In order:

  1. OS update / upgrade (do_update_upgrade) — apt-get update, upgrade, then autoremove (after waiting for cloud-init to finish).
  2. Install Muppy required packages (do_install_muppy_required_packages) — removes needrestart, then installs daemontools software-properties-common, htop iotop fio, python3-pip python3-dev python3-venv, and jq. When the Host has unattended upgrades enabled, unattended-upgrades is also installed.
  3. Activate UFW Firewall (do_activate_ufw) — conditional. The firewall is only enabled when the global setting setup_firewall_automatically_during_enrollment is on and the Host's "Don't activate FW at Enroll" flag is off. See Firewall UFW.
  4. Collect Facts (do_collect_all_facts) — gather all facts about the Host.
  5. Add Default SSH Keys (do_add_default_keys) — push the default SSH keys to the control user's authorized_keys.
  6. Reboot Host (do_reboot) — reboot at the end of enrollment, then wait for the host to come back (controlled by wait_for_restart_max_attempts).

Enroll Callback Tasks defined on the Server Type are invoked between these steps, letting you inject custom configuration. See Server Types.

When the sequence completes, Muppy marks the Host as enrolled and sets its state to ==Managed==.

Firewall during creation

When a Host is created, Muppy automatically attaches a set of default firewall rules — the rules that keep Muppy able to reach the Host once the firewall is enabled. The Firewall UFW documentation describes how to set up the firewall and customize your default rules.