propellor(1)

📦 version 5.18, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ propellor — like, the manual page, but make it make sense ✨

okay bestie, so this is propellor(1) from the General Commands Manual, and it's genuinely one of the most iconic tools out there. Let me walk you through it 💅

🌸 NAME 🌸

propellor — property-based host configuration management, written in haskell, configured in haskell. yes. it's giving "I manage your hosts by describing what they should be, not what to do to them." main character energy fr fr 🫶

🦋 SYNOPSIS 🦋

propellor [options]

that's it. that's the whole vibe. options go in, magic comes out ✨

💖 DESCRIPTION 💖

propellor is a property-based host configuration management program. It's written and configured in haskell — so the whole thing is literally just haskell all the way down, no cap. 🌈

👑 MODES OF OPERATION 👑

okay so this is the big one, there's a LOT of ways to run it and they're all serving a different purpose. buckle up 🎀

💫 propellor --init

Get started bestie!! This initializes a ~/.propellor/ repository for you. 🐣

After this, you'll be editing ~/.propellor/config.hs to configure propellor. that's your new home. your canvas. your little config baby.

💫 propellor

Once propellor is configured, running it with no options at all will take action as needed to satisfy the configured properties of the local host. lowkey self-care for your machine 💅

If there's a central git repository, it will first:

  • fetch from it
  • check the gpg signature
  • merge
  • and rebuild propellor

…so that any configuration changes will immediately take effect. iconic. no waiting. ⚡

heads up: if propellor is run by a non-root user without any options, this is the same as running propellor --spin with the hostname of the local host. iykyk 🫶

💫 propellor --spin targethost [targethost ...] [--via relayhost]

Causes propellor to automatically install itself on the specified target host — or, if it's already installed there, push any updates. Propellor is then run on the target host, to satisfy its configured properties. 🌱

A signed git commit is made by --spin, so that any changes you have made get propagated to the target host. 🔐

Multiple target hosts can be specified; propellor will run on each of them in sequence. one by one, bestie. no cutting the line. 🚶♀️

When run with --via, propellor sshes to the relay host and runs propellor --spin hostname from there. This can be useful when propellor is installing itself, since most of the data transfer is done between relay host and target host. ✈️

⚠️ note that propellor uses ssh agent forwarding to make this work, and the relay host sees any privdata belonging to the target host. so like. know that. 🙈

Propellor configuration typically uses the FQDN of hosts. The hostname given to --spin can be a short name, which is then looked up in the DNS to find the FQDN. 🔍

💫 propellor --build

Causes propellor to build itself, checking that your config.hs, etc are valid. ✅

you do not need to run this as a separate step; propellor automatically builds itself when using things like --spin. it just does it. it's proactive like that 💅

💫 propellor --add-key keyid

Adds a gpg key, which is used to encrypt the privdata. 🔑

Multiple gpg keys can be added; the privdata will be encrypted so that all of them can decrypt it. the more the merrier 🫂

If the gpg secret key is present, git is configured to sign commits using this key. Propellor requires signed commits when pulling from a central git repository. no signature, no entry. 🚫

💫 propellor --rm-key keyid

Stops encrypting the privdata to a gpg key. bye bestie 👋

💫 propellor --list-fields

Lists all privdata fields that are used by your propellor configuration. The first 2 columns are the field name and context, and are followed by a list of the hosts that use that privdata value. 📋

💫 propellor --set field context

Sets a field of privdata. The content is read in from stdin. 📥

💫 propellor --unset field context

Removes a value from the privdata store. 🗑️

💫 propellor --unset-unused

Removes all values from the privdata store that are not currently in use. declutter queen 🧹✨

💫 propellor --dump field context

Outputs the privdata value to stdout. 📤

💫 propellor --edit field context

Opens $EDITOR on the privdata value. 📝

💫 propellor --merge

Combine multiple --spin commits into a single, more useful commit. 🧬

okay so when you're using propellor, you may find yourself repeatedly running propellor --spin until you get things working the way you like. This results in a lot of git commits being made, with incremental changes. 😭

To clean that up to a single commit, use propellor --merge. A normal interactive git commit will then be made, consisting of all changes that have been previously committed by --spin, since the last time a normal git commit was made. 😌

(this will result in a trapezoid pattern in gitk.) 📐 iconic geometry tbh

💫 propellor --check

If propellor is able to run, this simply exits successfully. that's it. vibe check passed ✅

💫 propellor hostname

When run with a hostname and no other options, propellor will provision the local host with the configuration of that hostname. This is useful when the local host doesn't yet have its hostname set correctly. 🏷️

🎀 FILES 🎀

  • ~/.propellor/config.hs — This is the default config file used by propellor. your main squeeze 💖
  • ./config.hs — If propellor is run in a directory containing a config.hs, it assumes that the current directory is a propellor repository, and uses the configuration from the current directory, rather than ~/.propellor/. local overrides, we love to see it 🌟

🌈 ENVIRONMENT 🌈

  • Set PROPELLOR_DEBUG=1 to make propellor output each command it runs and other debugging information. 🔍✨

💜 GIT CONFIGURATION 💜

  • git config propellor.debug 1 — will configure propellor to output debugging information. 🐛
  • git config propellor.spin-branch foo — will configure propellor to refuse to spin when the foo branch is not checked out. 🚧
  • git config propellor.forbid-dirty-spin true — will configure propellor to refuse to spin when there are uncommitted changes in the ~/.propellor repository. 🧼
  • git config propellor.buildsystem stack — makes propellor use stack for building itself, rather than the default cabal. This only controls the local build of propellor; Hosts can have properties set to control how propellor is built on them. 🏗️
  • The usual git configuration controls which centralized repository (if any) propellor pushes and pulls from. 📡
  • Additionally, the url of a remote named "deploy", if it exists in your ~/.propellor/ repository, is used as the origin url for the other repositories. 🚀

🌟 AUTHOR 🌟

Joey Hess <id@joeyh.name>

<https://propellor.branchable.com/> 🫶

and that's the whole page, bestie!! 💖 this was propellor(1) from the General Commands Manual — go configure some hosts, slay, and remember: signed commits only. periodt. 👑✨🦋

📦 where this page comes from