Augeas: a Configuration API
Total Page:16
File Type:pdf, Size:1020Kb
Augeas: A Configuration API Raphaël Pinson March 4, 2013 Augeas: A configuration API Copyright © 2011 Raphaël Pinson Permission is granted to copy, distribute and/or modify this doc- ument under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foun- dation; with the Invariant Sections being just ”GNU Manifesto”, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ”GNU Free Documentation License”. This book would not be what it is without the help of many. In particular, I wish to thank David Lutterkort for writing Augeas and providing great insights about Augeas internals. Doing proper typesetting with LATEX can be tricky, and Damien Wyart deserves a big thanks for providing his expertise on the subject. iii Contents Introduction xi Configuration Data Editing Approaches .......... xi Keyhole Approaches ................. xii Greenfield approaches ................. xiii Templating ....................... xiii A Unified Configuration API ................ xiii What Augeas is not ..................... xiv Not an abstraction layer ................ xiv Not a cross-platform abstraction layer ........ xv No remote management support ........... xvi Very little modelling .................. xvi Conventions ...................... xvii How to read this book ................. xvii Prerequisites ...................... xviii 1 Installing Augeas 1 Installing from source .................... 1 Installing from binary packages .............. 2 Installing from the development head ........... 2 Building documentation ................... 3 Building the PDF documentation .............. 3 Building the NaturalDocs documentation ......... 4 Installing the bindings .................... 5 Installing bindings from binary packages ...... 5 Installing bindings from source ............ 5 v Contents 2 Exploring augtool 7 Parsing your System Configuration Files ......... 8 Using a Fakeroot ....................... 11 Modifying Files ........................ 12 Preserving existing files ................... 13 Locating nodes in files .................... 13 Dumping the tree as XML .................. 14 Scripting with augtool .................... 15 Using augtool as an interpreter ............ 15 Dropping into an interactive session ......... 15 3 Bidirectional transformations 21 The Need for Bidirectional Transformations ........ 21 A Bit of Theory ........................ 22 What is a bidirectional transormation ........ 22 Lenses ......................... 22 Identity and conditions of bidirectionality ...... 22 Bidirectional transformations in Augeas .......... 22 Augeas lenses ..................... 22 Lenses typechecking ................. 22 The case of recursive lenses .............. 22 4 Path Expressions 23 Generalities on XPath expressions ............. 23 Using globs .......................... 23 Conditionals ......................... 24 Union of paths ........................ 25 Functions ........................... 25 The last() function ................... 26 The position() function ................ 26 The label() function .................. 26 The count() function .................. 26 The regexp() function ................. 26 Node references ....................... 26 vi Contents Using variables in paths ................... 26 defvar .......................... 26 defnode ......................... 26 Using variables to express conditionals ....... 26 Ensuring idempotence .................... 26 5 Using the C API and Bindings 27 Using the C API ....................... 28 API Flags ........................... 28 Using Bindings ........................ 28 Haskell bindings .................... 28 Java bindings ...................... 28 Perl Bindings ...................... 28 PHP bindings ..................... 28 Python Bindings .................... 28 Ruby Bindings ..................... 29 6 Augeas metadata 31 The /augeas/root node ................... 31 The /augeas/version tree .................. 32 The /augeas/save node ................... 33 The /augeas/load tree .................... 33 Using only one lens .................. 33 Parsing a specific file ................. 35 The /augeas/files tree ................... 36 The path node ..................... 36 The mtime node ..................... 36 The lens tree ...................... 37 The error tree ..................... 37 Example ........................ 37 The /augeas/variables tree ................. 38 The /augeas/span node ................... 39 vii Contents 7 Using Augeas in Puppet 41 The Augeas type ....................... 42 Setting a context ....................... 42 Proper quoting ........................ 42 Puppet and idempotence .................. 43 8 Writing Your Own Lenses 45 A simple example ...................... 45 Unit Test ........................ 46 Module ......................... 46 Regular expressions ..................... 46 Special keywords ....................... 46 key ........................... 47 label ........................... 47 store .......................... 47 value .......................... 47 seq ........................... 47 rec ........................... 47 square ......................... 47 Combination Operators ................... 47 Concatenation Operator ............... 47 Union Operator .................... 47 Filters and Autoload ..................... 47 Typechecking lenses ..................... 48 Typechecking recursive lenses ............ 48 Unit tests ........................... 48 Using Generic Modules ................... 49 The Util module .................... 49 The Sep module .................... 49 The Rx module ..................... 49 The Build module ................... 50 The IniFile module ................... 50 Using your lens ....................... 50 Ignoring the stock modules .............. 50 viii Contents Adding your own directory of lenses ........ 51 Documenting your modules ............. 51 Lens optimization ...................... 51 Use standard constructions .............. 51 Avoid regexp ”substractions” ............. 51 Group keys in blocks ................. 52 9 Troubleshooting Augeas 53 Files don’t appear in the tree ................ 54 No lens for the file ................... 54 UID has no rights to read ............... 54 Parsing failed ..................... 54 Save failed .......................... 55 Turning on debug ...................... 56 10 Contacting the Augeas team 57 Contributing ......................... 57 Forking the git repository ............... 58 Coding style ...................... 58 Sending patches .................... 58 Getting support ....................... 58 Reporting bugs ........................ 58 GNU Free Documentation License I 1. APPLICABILITY AND DEFINITIONS .......... II 2. VERBATIM COPYING .................. IV 3. COPYING IN QUANTITY ................ V 4. MODIFICATIONS ..................... VI 5. COMBINING DOCUMENTS ............... IX 6. COLLECTIONS OF DOCUMENTS ............ IX 7. AGGREGATION WITH INDEPENDENT WORKS ... X 8. TRANSLATION ...................... X 9. TERMINATION ...................... XI 10. FUTURE REVISIONS OF THIS LICENSE ....... XII ix Contents 11. RELICENSING ...................... XII ADDENDUM: How to use this License for your documentsXIII x Introduction Augeias was king of Elis, in some accounts a son of Helios, in others of Poseidon, and in still others of Phorbas. The Library 2.88 Apollodorus In the world of Unix systems, there is no standard way to store configuration. Countless formats can be found, from simple shell variable files to complex, specific, multi-level formats, making the infamous /etc directory a sort of digital Augean stable. Augeas provides a way to cleanly and safely manage these configu- ration files through a unified API. Configuration Data Editing Approaches While system administrators are well aware of the heterogenous state of the configuration data on Unix systems, these configurations have to be edited automatically in many situations. There are three main approaches to the issue of automating config- uration data editing on Unix systems. xi Contents Configuration file Format /etc/default/* shell variables /etc/fstab fstab format /etc/mtab /etc/hosts hosts format /etc/passwd passwd format /etc/shadow php.ini my.cnf INI file gdm.conf puppet.conf ntp.conf NTP format Some common configuration files and their format Keyhole Approaches Most programming languages provide modules to edit at least the most common formats, but a lot of system administrators and de- velopers manipulate these files using string editing tools such as sed, awk or cut, or even write scripts dedicated to a specific parsing job. In the majority of these cases, the results are not guaranteed, and you are likely to ruin the configuration files if your parsing expressions are wrong or the file layout changes between different versions of the program. Configuration management tools such as Cfengine1 provide tools to achieve keyhole approaches, but the problems are similar to using string editing tools: you have no guarantee that the result will be a valid configuration file, and you have to write the regexps yourself. Augeas is particularly useful to ease and secure this kind of approach. 1http://www.cfengine.com xii A Unified Configuration API Greenfield approaches When you are the main system administrator of a machine and you wish to control all the parameters of the machine, you may want to provide the configuration files entirely. In this case, it is common to set up a repository