README.md

   1 [![Build Status](https://travis-ci.org/hercules-team/augeas.svg?branch=master)](https://travis-ci.org/hercules-team/augeas)
   2 [![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/augeas.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:augeas)
   3
   4 Introduction
   5 ------------
   6
   7   Augeas is a library and command line tool that focuses on the most basic
   8   problem in handling Linux configurations programmatically: editing actual
   9   configuration files in a controlled manner.
  10
  11   To that end, Augeas exposes a tree of all configuration settings (well,
  12   all the ones it knows about) and a simple local API for manipulating the
  13   tree. Augeas then modifies underlying configuration files according to
  14   the changes that have been made to the tree; it does as little modeling
  15   of configurations as possible, and focuses exclusively on transforming
  16   the tree-oriented syntax of its public API to the myriad syntaxes of
  17   individual configuration files.
  18
  19   This focus on editing sets Augeas apart from any other configuration tool
  20   I know of. Hopefully, Augeas will form a more solid foundation on which
  21   these tools can be built; with a clean, simple API these tools should
  22   be able to focus more on their core concerns and less on the mechanics
  23   of running sed, grep, awk, etc. to tweak a config file.
  24
  25   If all you need is a tool to edit configuration files, you only need to
  26   concern yourself with the handful of public API calls that Augeas exposes
  27   (or their equivalent language bindings). However, to teach Augeas about a
  28   new file format, you need to describe that file format in Augeas's domain
  29   specific language (a very small subset of ML) Documentation for that
  30   language can be found on the Augeas website at http://augeas.net/ If you
  31   do that, please contribute the description if at all possible, or include
  32   it in the distribution of your software - all you need to do for that is
  33   add a couple of text files, there is no need to change existing
  34   code. Ultimately, Augeas should describe all config files commonly found
  35   on a Linux system.
  36
  37 Non-goals
  38 ---------
  39
  40 Augeas is as much defined by the things it does _not_ try to accomplish
  41 as by its goals:
  42
  43 * No abstraction from native config format, i.e. the organization of
  44   the tree mirrors closely how the native config files are organized
  45 * No cross-platform abstraction - what is logically the same value may
  46   live in different places in the tree on different
  47   distributions. Dealing with that should be left to a higher-level
  48   tool
  49 * No remote management support. Augeas is a local API, other ways of
  50   access to Augeas should be built on top of it
  51 * No (or very little) modelling. Augeas is focused on syntax
  52   transformation, not on any higher-level understanding of
  53   configuration.
  54
  55 The above non-goals are of course important concerns in
  56 practice. Historically though, too many config mgmt projects have failed
  57 because they set their sights too high and tried to address syntax
  58 transformation, modelling, remote support, and scalable management all in
  59 one. That leads to a lack of focus, and to addressing each of those goals
  60 unsatisfactorily.
  61
  62 Building
  63 --------
  64
  65 These instructions apply to building a released tarball. If you want to
  66 build from a git checkout, see the file HACKING.
  67
  68 See the generic instructions in INSTALL. Generally,
  69
  70       ./configure
  71       make && make install
  72 should be all that is needed.
  73
  74 You need to have readline-devel installed. On systems that support
  75 SELinux, you should also install libselinux-devel.
  76
  77 Documentation
  78 -------------
  79
  80 Documentation can be found on Augeas' website http://augeas.net/ The site
  81 also contains information on how to get in touch, what you can do to help
  82 etc.
  83
  84 License
  85 -------
  86
  87 Augeas is released under the [Lesser General Public License, Version 2.1](http://www.gnu.org/licenses/lgpl-2.1.html)
  88 See the file COPYING for details.