Augeas: editing Linux config files as a tree

The problem Augeas names: editing real files, in a controlled manner

Augeas is a library and command line tool that focuses on the most basic problem in handling Linux configurations programmatically: editing actual configuration files in a controlled manner.

That phrase does the work. Augeas is not a configuration management system, and the README is explicit that it is as much defined by the things it does not try to accomplish as by its goals. It is a transformation layer that sits between a program and a file on disk.

The mechanism is a tree. Augeas exposes a tree of all configuration settings, well, all the ones it knows about, and a simple local API for manipulating the tree. Augeas then modifies underlying configuration files according to the changes that have been made to the tree. The stated philosophy is that it does as little modeling of configurations as possible, and focuses exclusively on transforming the tree oriented syntax of its public API into the many different syntaxes of individual configuration files.

Why that matters is the failure mode of the usual approach. A shell script that edits a config file with sed or awk works until the file has a comment in an unusual place, a value spanning lines, or a syntax the script did not anticipate, and then it corrupts something quietly. Augeas's premise is that a parse of the file, followed by a change to the tree, followed by a write back, preserves everything the tool did not understand. The tree mirrors the file closely enough that what the parser did not model is simply carried through.

The README puts the ambition in terms of a foundation. Hopefully, Augeas will form a more solid foundation on which these tools can be built; with a clean, simple API these tools should be able to focus more on their core concerns and less on the mechanics of running sed, grep, awk to tweak a config file. The project is under the hercules-team organisation, the homepage is augeas.net, the licence is LGPL-2.1, and the last push to the tree was on 2026-09-29 with release-1.15.0 tagged the same day.

The four non-goals that define what Augeas will not do

The non-goals section is the most useful part of the README for anyone deciding whether to adopt this, and it is unusually direct.

There is no abstraction from the native config format. The organization of the tree mirrors closely how the native config files are organized. So there is no canonical, portable name for a setting that is the same idea in two different files.

There is no cross-platform abstraction. What is logically the same value may live in different places in the tree on different distributions, and dealing with that should be left to a higher-level tool. That is a real constraint for anyone running a fleet across distributions, and the project hands the problem upward rather than solving it.

There is no remote management support. Augeas is a local API, and other ways of access to Augeas should be built on top of it. So Augeas is a component you embed, not something you point at a fleet of hosts.

And there is no, or very little, modelling. Augeas is focused on syntax transformation, not on any higher-level understanding of configuration.

The README then justifies the narrowness with a historical argument that is worth taking seriously. Historically, too many config mgmt projects have failed because they set their sights too high and tried to address syntax transformation, modelling, remote support, and scalable management all in one. That leads to a lack of focus, and to addressing each of those goals unsatisfactorily.

For an engineer, this is the design brief in four lines. If your problem is editing a file on the host you are already logged into, Augeas is aimed at you. If your problem is fleet-wide policy, you need a different layer, and Augeas expects to be the bottom of your stack rather than the whole of it.

Lenses: teaching Augeas a new file format in a subset of ML

The tree only knows about the settings it has been taught. The teaching mechanism is a lens, and the language lenses are written in is a very small subset of ML.

The README is unusually open about what contributing one costs. If you want to teach Augeas about a new file format, you need to describe that file format in Augeas's domain specific language, and the documentation for that language is on the Augeas website at augeas.net. The instruction to contributors is explicit: if you do that, please contribute the description if at all possible, or include it in the distribution of your software. All you need to do for that is add a couple of text files, and there is no need to change existing code.

That is the extension model in one sentence, and it is a genuinely unusual design. A new file format is a text file, not a patch to a C library. The `lenses/` directory at the repository root is where those descriptions live, and the `examples/` directory holds a worked example, including `examples/cont.aug`, which is a lens file itself, along with `examples/dump.c` and `examples/fadot.c` as C sources and `examples/examples.sh` to drive them.

The intended end state is stated too. Ultimately, Augeas should describe all config files commonly found on a Linux system. That is a long road, and the reason the project exists as a foundation rather than a finished catalogue is that the catalogue is meant to be built by the people who need each format.

The cost to a user is therefore in proportion to how unusual their files are. If a lens for the format you care about already exists, Augeas gives you the tree API for free. If it does not, you write a lens, which is a self-contained piece of work in a small ML dialect rather than a change to the core.

Building from source

The build instructions in the README apply to building a released tarball, and for a git checkout the project points you at the HACKING file instead. The generic instructions live in the INSTALL file in the repository root.

The build itself is a standard autotools sequence.

      ./configure
      make && make install

There are two stated dependencies. You need to have readline-devel installed, and on systems that support SELinux, you should also install libselinux-devel. The readline dependency is what gives the command line tool its line editing, and the SELinux one is what lets Augeas work with the security context of the files it touches.

The repository layout shows the shape of the project. There is `src/` for the C sources, `lenses/` for the format descriptions, `man/` for the manual pages, `doc/` for documentation, `tests/` for the test suite, `examples/` for the worked examples, and `docker/` for container builds. The build system is autotools: `configure.ac`, `acinclude.m4`, `Makefile.am`, `Makefile.inc`, `Makefile.maint`, `autogen.sh` and `bootstrap`, with `augeas.pc.in` producing a pkg-config file and `augeas.spec.in` for RPM packaging. A `NEWS` file, `AUTHORS`, `HACKING.md` and `COPYING` complete the tree, and `.gnulib` and `.gitmodules` indicate vendored submodule dependencies.

The release history shows a slow but real cadence. release-1.15.0 was tagged on 2026-09-29, and before it release-1.14.1 dates from 2023-07-15 and release-1.14.0 from 2022-12-07. So the current release is recent, but the previous one is three years old, which tells you the project moves in bursts rather than on a schedule.

Using the API and the tool, and the split between them

The README makes a point about the two ways in. If all you need is a tool to edit configuration files, you only need to concern yourself with the handful of public API calls that Augeas exposes, or their equivalent language bindings.

So the surface is deliberately small, and it is the same surface whether you use the command line tool or the library. The tool is a driver for the library rather than a separate product with different behaviour, and the same applies to the language bindings, which are the form in which most people would embed it.

The workflow implied by the design is: load a file into a tree, address a path in the tree, change the value at that path, and save the tree back out. Each of those steps is a call on the API, and the save step is where the value of the approach shows, because the file is rewritten from the tree and the parts of it the lens did not model are carried over.

What you get in return for the modelling Augeas does not do is worth being explicit about. You get paths that mean something in the file you are editing, on the system you are editing it, with the syntax that system's format uses. You do not get a setting called something portable, and you do not get a schema that tells you what the value should be. Validation, defaults and policy are somebody else's job, and the README's non-goals say so.

That makes Augeas a good fit for a narrower set of problems than the word configuration management suggests. Provisioning scripts that toggle a value in a known file, a tool that has to edit several formats in one pass, a system that needs to change a setting without destroying the file's comments, and higher-level tools that want a clean tree API to build on.

Where Augeas is the wrong choice

Three limitations follow directly from the design, and it is better to find them now than during an incident.

The first is that there is no cross-platform abstraction. The tree mirrors the native config format, and the same logical value may live in different places on different distributions. A script that works on one distribution can silently target the wrong path on another, and Augeas will not warn you, because from its point of view there is nothing wrong with the path. The README is explicit that dealing with that should be left to a higher-level tool, so if you are writing something that has to run everywhere, you need that layer and Augeas is only its bottom half.

The second is that Augeas is a local API with no remote management support. There is no agent, no server, and no way to reach a host. If your requirement is to change a configuration on forty machines from your laptop, Augeas is not the tool and never was, and the README says so plainly.

The third is the dependency on lens coverage. Augeas only knows about the formats it has been taught. For a common format there is probably a lens, and for an unusual one there may not be, and in that case you either write one yourself in the ML subset or you are back to editing the file by hand. The upside of the extension model is that adding one costs a couple of text files and no code change, and the downside is that it is still work you have to do.

The alternative approach, and it is a real one, is to use a configuration management tool that models the intent. Such a tool knows what a web server should be configured to do, expresses that as a declarative resource, and figures out the file format for you, so the same declaration produces an Apache config on one host and an nginx config on another. The difference in approach is direct and it is the same one the README argues about. Augeas does syntax transformation, a modelling tool does transformation plus meaning, and the modelling tool consequently has to keep up with every format it supports while Augeas delegates that to lens files.

Editorial conclusion

Adopt Augeas when you have to change configuration files programmatically on a Linux host and you need the edit to survive with the file's comments, ordering and formatting intact, which sed and grep cannot promise. Do not adopt it as a configuration management platform, because remote management support and modelling are listed as non-goals and it is a local API only. Before writing your first lens, read the lens documentation at augeas.net and check the `lenses/` directory for an existing one, since adding a couple of text files is usually enough and does not require changing any code.

Frequently asked questions

Official sources

1. hercules-team/augeas on GitHub
2. License: LGPL-2.1
3. Project website
4. README
5. Releases