Getting Started

- Modular Infrastructure Orchestrator -

                   _
         _ __ ___ (_) ___
        | '_ ` _ \| |/ _ \
        | | | | | | | (_) |
        |_| |_| |_|_|\___/

MIO stands for Modular/Managed Infrastructure Orchestrator/Operator. It is a low-level infrastructure toolkit that packages software applications, services, and components into ready-to-run systems. The result is a managed, single-purpose server distribution that focuses on maintaining multiple server instances with minimal effort.
Utilities and dependencies are handpicked to align with the Unix philosophy, ensuring comprehensive control and data separation while emphasizing automation.

Speak plainly. You developed or found an application or service that runs on a server. You want to run it on multiple servers, for friends or on-premises, but you lack the time or resources to maintain them.
Maybe you want to plain fileize your application management or enhance and protect your applications with additional features while keeping tight control.

Either way, start with a brief introduction, jump right in, TL;DR - our copy & paste demo, or explore our documentation!

---

Our development is happening quickly. Be prepared for sudden changes.

---

---

Introduction - 101

First, the mio's file-system-centric design allows interaction with Unix commands and provides full version control. The toolkit comes with preconfigured modules and tools, as well as a Makefile. You need to set up one super project per application / distribution.

Let's go over the main components and terms in a nutshell.

Identity

Our Identity is a GnuPG (GPG) key pair. This is mio first core component, an unique identifier for an individual or server instance. This bakes modern encryption right from the beginning.

The identity consists of:

1. Fingerprint: A unique numerical value representing the user's public key.
2. Username or Primary Key ID: A string used to identify the user, often chosen by the user themselves.
3. Email Address: The email address associated with the identity.
4. Sub-Keys: Sub-keys for Encryption, Authentication and Signing.
5. Expiration Date: A time stamp on which our identity expires.

Indeed it comes with a price, but our [mio-wizard] will take care of that.

Super project

This is our workspace which consists of the configuration overlay, our identities, our secrets and the mio distribution itself. The state of all components are tracked in a woo manifest file.

Module

A module is a feature that expands the capabilities of your system. Examples include the Secure Shell Daemon (SSHD), a firewall, and a web server. mio comes with a growing list of modules, and you can [add your own].

Configuration overlay

This is where our main configuration lives. It's a subdirectory inside our super project named conf. It contains a mio.mk file that is used for module selection, as well as our project-specific module configurations.
These configurations can be overwritten or patched on a class or instance basis. Class configurations are shared across all instances, while instance configurations are applied to the instance only.

Exemplary workspace directory structure to show overlay

Let's use the sshd module as an example.
The default configuration is located in mio/sshd/files/PORT, which sets the SSH listing port to 22.
We are patching on a class-by-class basis in the file conf/sshd/files/PORT. For our specific instance, with the hostname vfs-project-host-a, the file conf/sshd/files-<HOSTNAME>/PORT.

workspace
├── conf
│   └── sshd
│       ├── files
│       │   └── PORT
│       └── files-vfns-project-host-a
│           └── PORT
└── mio
    └── sshd
        └── files
            └── PORT

No Patches — No Maintenance

Use the module defaults to omit your module configuration (conf/<MODULE>) and let mio handle everything.

Secrets

Mio uses pass as a secret store because it is built on top of GnuPG identities. While it has its limitations and calls for extra tooling, it aligns seamlessly with our file- and identity-centric world.

The main sections are:

• ctl: Stores API credentials.
• eyes-only: Stores private instance-related secrets to limit instance capabilities.
• id: Stores all known identities and public keys with owner trust information.
• instance: Stores instance secrets.
• instances: Stores shared secrets across instances. This violates the ADR rule of "No Shared Secrets."

mio-pass

This shows a secret store with two identities: one named ci and one named achird

Password Store
├── ctl
│   ├── api
│   │   ├── dns
│   │   └── hcloud
│   └── backup
│       ├── api
│       ├── api.ro
│       ├── rc
│       └── storagebox
├── eyes-only
│   └── achird
│       ├── app
│       │   └── superuser
│       ├── backup
│       │   ├── repokey
│       │   └── repokey.paper
│       ├── keys
│       ├── pw
│       └── subkeys
├── id
│   ├── ci
│   │   ├── gpg
│   │   └── ownertrust
│   └── achird
│       ├── gpg
│       └── ownertrust
├── instance
│   └── achird
│       ├── app
│       │   └── pgpass
│       └── backup
│           └── repokey.pw
└── instances
    └── app
        └── default.pw

Tool

A tool interacts with your workspace and systems to make your work easier. Most tools are prefixed with mio- or accessed via the wrapper command mio. One of the tools we will use heavily is the [mio-wizard], which will help us bootstrap all the necessary parts.

Tooling beneath

• make
• coreutils
• gawk, grep, sed, tar
• git
• curl, rsync, sftp, ssh, sshpass, openssl
• gnupg and pass
• BorgBackup

Make

The Makefile serves as entry point to your project, which glues everything together.

mio-wizard

Our Wizard will show you your options along the way. It will guide you through the commands and point out your next steps.

mio-wizard help

             _
   _ __ ___ (_) ___      Modular Infrastructure Operator
  | '_ ` _ \| |/ _ \     Docs: https://docs.kosmonum.space/mio/
  | | | | | | | (_) |    License: BSD-2-Clause
  |_| |_| |_|_|\___/     Version: 0.1.0 One-Shot-Edition

USAGE:
  mio-wizard <CMD> <ARGS...>

COMMANDS:
  help
  readme
  install
  id [ <KEY.PASS> | ${MIO_ID_KEY} [${MIO_ID_KEY_PW}] | <E-MAIL> ]
  id-add <KEY.PUB> [OWNERTRUST]
  id-expire <ID|FPR>
  init [ <REPO> [ <PROJECT> <DOMAIN> ] ]
  add-backupctl
  add-instance <ID>
  add-instance-backup <ID>

ENVIRONMENT VARIABLES: MIO_<KEY>
  EXPIRE          Set an expiration date <DATE>  [1y]
                  Ns|Nd|Nw|Nm|Ny|YYYY-MM-DD|YYYYMMDDTHHmmss|never
  SCM_PUSH        1|0  [1]

Things to grok

• GnuPG
  • MiniHOWTO
  • especially subkeys
  • Manual
• pass
• BorgBackup

Get Your Hands Dirty

This brief introduction will show you how to quickly set up a project. It's all about instant gratification! It demonstrates how it works and explains why you should invest time in exploring the system.

The tour will result in a server instance that serves an application with some added features with minimal effort. You should be able to copy and paste each shell block directly into a terminal.

Now, we're going to create a super project: our own little, ready-to-run distribution that we can adjust to our needs.

The Wizard will handle all the heavy lifting, creating the file system structure and helping you bootstrap a fully Mio-driven project.

Fasten your seatbelts; We're starting from scratch, it boils down to this:

1. Install — mio-wizard install
2. Crate super project
3. Create your identity — mio-wizard id
4. Create remote repository
5. Initialize super project — mio-wizard init
6. Add a backup repository controller. For now, Hetzner-Storage-Box — mio-wizard add-backupctl.
7. You are then ready to configure the modules and build the payload (manual steps).
8. Spawning / preparing an instance (manual steps).
9. Add this instance to your project — mio-wizard add-instance.
10. Allocate and connect a backup repository to an instance — mio-wizard add-instance-backup
11. Finally, you can leave the wizard and start managing and rolling out your configuration with make install.

Install

Get the mio-wizard One-Shot-Edition binary from our documentation page. Depending on your Debian 12 base image, you will need to install some additional packages.

wget -O - https://docs.kosmonum.space/mio/install/mio-wizard | sudo tee /usr/local/bin/mio-wizard >/dev/null
sudo chmod 755 /usr/local/bin/mio-wizard
mio-wizard install

Create super project

This will be our main workspace directory. Pick a location that works for you.

We will use ~/hello-mio as our starting point!

mkdir ~/hello-mio && cd ~/hello-mio`

Create your identity

We are going to create an identity consisting of a couple of private keys. It is highly recommended that you create an identity for each super-project to address the separation of concerns. You need to check if your source forge supports sub-addressing!

Select one of the available identity formats that suits your needs.

• ALIAS+COMMENT@DOMAIN.TLD
• ALIAS (COMMENT) <EMAIL>

We will use plus-sub addressing and set our key to expire after one day. The wizard will then ask for our passphrase to unlock the keys for the current session. It will output lots of information to your terminal.

Read them carefully and memorize your avatars.

You will be left with some instructions (TODO-NOW.md) on how to back up your keys and passphrases.

Split keys

There is a split keys section that will remove the master key from your identity. This will increase security, but prevent you from creating new identities/instances.

For now, skip this step until you are familiar with the concept and Mio comes with proper superuser support.

The examples are going to use pass, but you are free to use whichever vault store you prefer.

Take it seriously!

MIO_EXPIRE=1d mio-wizard id me+hellomio@foobar.lan

Create remote repository

Create a Git repository in your preferred forge to persist and share your workspace. Add/bind the identity authentication keys, which are in the workspace directory .ssh/id.pub.

A local bare repository is what we're going to use for this demo.

git init --bare ~/hello-mio.git

Initialize super project

We're initiating our super project and connecting it to our remote repository ~/hello-mio.git. The project name is hello under our top-level domain, foobar.lan. The last two arguments are optional when initiating an existing project. We're committing and auto-pushing all changes.

Once again, the wizard leaves you some notes detailing the next steps.

MIO_SCM_PUSH=1 mio-wizard init ~/hello-mio.git hello foobar.lan

Activate your project

As the wizard suggests, we need to activate the project each time we are going to use it. In general, you will need your passphrase to access your identity. For this session, it was already preset.

. ./activate

You're now in the environment and have new tools at your disposal, prefixed with mio-.

Deactivate your project

Always deactivate projects when you leave them. This clears the passphrase and shuts down the identity.

deactivate

Take on maintenance

...

TLDR

All right then. You're so hot, and I'm going to make you mine.
Spin up a fresh Debian 12 machine.
Go wild, become root, then copy and paste the following block into the terminal, either fully or line by line.
Lean back and enjoy Mio's installation show.

apt update && apt -y -qq install wget

wget -O ~/mio-wizard https://docs.kosmonum.space/mio/install/mio-wizard
chmod +x ~/mio-wizard
# install system dependencies (requires root)
~/mio-wizard install

git config --global user.email "me@foobar.lan"
git config --global user.name "me"
git config --global init.defaultBranch "master"


export LC_ALL=C.UTF-8 || :
# identities expire after 1 day
export MIO_EXPIRE=1d

mkdir ~/workspace && cd ~/workspace

# crate your identity with a passphrase
echo imahotspoon | ~/mio-wizard id me+hotspoon@foobar.lan

# initialize our fake remote repository
git init --bare ~/workspace.git

# initialize project and connect to remote repo
~/mio-wizard init file://${HOME}/workspace.git hotspoon foobar.lan

# source your project environment
. ./activate

# you going to provision localhost via ssh
printf --  '127.0.0.1 %s.hotspoon.foobar.lan' "$(hostname)" >> /etc/hosts
apt install -y openssh-server
install -m 700 -d ~/.ssh/
cat .ssh/id.pub >> ~/.ssh/authorized_keys
chmod 640 ~/.ssh/authorized_keys

# crate an instance identity
mio-wizard add-instance $(hostname)

# fetch host keys from instance
mio-ssh -o StrictHostKeyChecking=accept-new $(hostname) 'uname -a'
mio-git commit -a -m 'update known_hosts'

# reconfigure your overlay
sed -i 's/^# MODULES.*/MODULES := $(filter-out backup msmtp domain sysstat, $(MODULES))/' conf/mio.mk
sed -i 's/^# TASKS .*/TASKS := $(filter-out do-backup, $(TASKS))/' conf/mio.mk
mio-git commit -a -m 'disable some modules'
mio-git push --all

# let the show go on
make install

Security

If you find any security issue please ping us using one of following contact mediums:

• #kosmonum on libera IRC
• security@kosmonum.space

Contribution

Are warm Welcome.
Send bug reports and patches to miconoco.posaune@lists.sr.ht.

License

BSD License see LICENSE for details.

---