Infrastructure management research project

dd0b2ea Update checksums

4 days ago

2b8a5bf Update to upstream 20240313-1

4 days ago


Anemos is an open source infrastructure management research project.

Its goals are:

  • To provide a method of server deployment that has almost zero dependencies on the environment:
    • Works on both bare-metal and virtual machines
    • Is agnostic of the type of meta-access to the machine (like hypervisor or IPMI), it is only needed for recovery if something goes wrong
    • Works without any supporting infrastructure (such as PXE-boot), but is modular enough to fit into an existing one if so desired
  • To promote (but not enforce) a declarative approach to reproducible, immutable deployments
  • Provide extensibility into a full-blown asset management platform (at some point)

In its current state, Anemos is a set of tools that allow you to deploy a system image described in code (e.g. a script that runs setup-alpine) to a host (bare-metal or virtual) without the need for external infrastructure (like PXE boot) or physical access (like booting a live system from USB).

One absolutely welcome side-effect of how Anemos works is that it makes it "easy" (some caveats apply, of course) to deploy a custom distribution to a VPS where the provider only offers a limited choice of distributions. See the demo below.

Attention: Anemos is very young and work in progress. It performs actions that can potentially leave your server in a broken or unexpected state.

When using it for the first time on a server, make sure you:

  1. Understand the actions it will perform, and
  2. have the means to recover (physical access, serial console access, remote re-imaging, etc)

#How it works

A deployment with Anemos makes use of the following components:

  • A user-supplied payload: this is the codified description of what to deploy
  • An initramfs, which performs the deployment
  • A CLI tool, which - on the host to be deployed - generates the initramfs and boots it, thereby triggering the deployment

The components are described in more detail below. The deployment process works as follows:

  • The user creates a payload describing the desired deployment
  • The host to be deployed to must have:
    • The Anemos CLI
    • Access to the kernel, base initramfs, and payload - either locally or via network
    • A proper Anemos configuration file (see comments in the example)
  • The Anemos CLI is used on the host to:
    • Generate the final initramfs to be used
    • Boot the generated initramfs
  • The initramfs, once booted, will automatically perform the deployment as specified in the payload



The final initramfs is generated on the host to include the deployment payload, network configuration, and firmware. But the deployment mechanics are implemented in the base initramfs.

#CLI tool

The CLI tool is a simple shell script with a single configuration file. There are no packages yet, so it needs to be installed manually for now.


The payload is a gzipped tarball of one of two things:

  • An IMGBUILD - like e.g. the demo payload
  • A custom executable file called deploy, along with whatever other files are needed

A simple example of a custom payload could be a script that simply runs setup-alpine with some predefined answers.


Anemos is now being used to deploy the nameservers responsible for anemos.io and a few other zones. The full code used to do this is available here. You can also see this in action here. I hope to also provide CI for this soon.

More recently, bot the main (i.e. web) server for anemos.io as well as the bitfehler.net mail server have also been ported to Anemos. The full IMGBUILDs are available here: bitfehler-www, bitfehler-mx.

#Previous demo

If you'd rather see it in action on someone else's machine, here is a screencast where you can observe the following:

  • I use the serial console of a LeaseWeb VPS running a freshly provisioned Debian
  • After installing zstd I perform the steps outlined above
  • The machine reboots, initially seemingly back into Debian
  • After loading the initramfs, an Alpine system boots
  • Once OpenRC is done, the deploy starts (pacstrap via makeimg)
  • The machine reboots again
  • A fully functional Arch Linux comes up (LeaseWeb does not offer Arch Linux images for their VPS)