holo - minimal configuration management
holo apply [-f|--force] [selector ...]
holo diff [selector ...]
holo scan [-s|--short|-p|--porcelain] [selector ...]
holo selectors
holo help
holo version
Holo adds a few sprinkles on top of package management to make it suitable for basic configuration management tasks. Its prime directive is to have all configuration statically declared and defined within packages, which can be installed to add new configuration, or uninstalled to remove configuration from a system.
Package management already offers 99% of the needed tools: Metapackages (usually called "holograms" or "holodecks" in Holo) can pull in other packages as dependencies, thus installing the software required for a certain task, and contain their own files to configure the software installed. Holo adds tools that work around shortcomings (from the configuration management perspective) of the package management.
The holo binary is only a frontend to find and run Holo plugins. Each Holo plugin adds logic to provision a certain type of thing that package management cannot do by itself. Please refer to holorc(5) for how to discover and enable plugins.
Included with Holo is the holo-files(8) plugin that allows holograms to replace or modify the default configuration files installed by application packages, the holo-ssh-keys(8) plugin for provisioning .ssh/authorized_keys, and the holo-users-groups(8) plugin which provisions user accounts and groups to the standard passwd(5) and group(5) databases.
Holo calls the things that it works on entities. Each entity belongs to a certain plugin, since plugins contain all the logic for discovering and working on entities.
Entities are defined in source or resource files which configuration packages install into the resource directory of the corresponding plugin (at /usr/share/holo/$PLUGIN_ID). Depending on how the plugin works, a single entity may have multiple resource files, or a single resource file might define multiple entities.
Each entity is identified by a name, usually of the form type:identifier. Refer to the manpage of each plugin for the format for its entities' names.
An entity that was created and still exists, but for which all source files have been removed, is said to be orphaned or an orphan. Orphaned entities are removed the next time an apply operation is performed on them.
Sometimes, resource files cannot be supplied in a package because their existence or contents depend on state not known at package build time, e.g. the set of devices present on the final system or the system's network environment. In this case, the configuration package can supply a generator that produces the correct set of resource files when Holo runs.
The interface for generators is described in holo-generators(7).
All operations act on all entities by default, but can be restricted to certain entities by giving selectors on the command line. A selector can be either an entity name (such as file:/etc/sddm/sddm.conf), or the path to a resource file that defines this entity (such as /usr/share/holo/files/40-desktop/etc/sddm/sddm.conf), or a plugin ID (such as files). A plugin ID as selector matches all entities known to that plugin.
For resource files produced by a generator, additional valid selectors include the path to the generator (such as /usr/share/holo/generators/foo.sh), or a pseudo-path of the form $GENERATOR_PATH::$RESOURCE_REL_PATH (such as /usr/share/holo/generators/foo.sh::files/40-desktop/etc/sddm/sddm.conf).
- scan [-s|--short|-p|--porcelain] [selector ...]
-
Prompt all plugins to scan for entities and list all known entities (or, if selectors are given, all entities matching these selectors) including the information returned from plugins about these entities.
With
-sor--short, only list the entity names.With
-por--porcelain, show the raw scan report as received from the plugins. The format is documented in holo-plugin-interface(7). The format is more machine-readable and stable, and thus the preferred choice for parsing in scripts. - selectors
-
Lists all valid selector strings that match at least one entity. This exists purely to make the implementation of shell completion functions easier.
- apply [-f|--force] [selector ...]
-
Apply the selected (or all) entities. Refer to the manpage of each plugin for what "applying" entails.
By default, Holo plugins will refuse to provision entities that have been changed by the user or by other programs. Apply
-for--forceto overwrite such changes or perform otherwise dangerous activities.If you want to check what will be done, use
holo scanas a dry run beforeholo apply. - diff [selector ...]
-
Print a diff(1) between the last provisioned version of each selected entity and the actual contents of that entity.
For entities that are not files, refer to the plugin's manpage for what the diff contains. When a plugin is not able to produce a meaningful textual representation of the entity, no output will be produced for its entities.
- help
-
Print out usage information.
- version
-
Print out Holo's version string including the release name.
$TMPDIR(default: /tmp)-
Where to place temporary files.
For each plugin:
- /usr/lib/holo/holo-$PLUGIN_ID (can be overridden in holorc(5))
- /var/lib/holo/$PLUGIN_ID/ (will be created if does not exist)
holo-build(8) can optionally be used in conjunction with Holo to simplify the package build process.
Stefan Majewsky
Further documentation is available at the project homepage: https://holocm.org
Please report any issues and feature requests at GitHub: https://github.com/holocm/holo/issues