[Server-devel] [PATCH] xs-config: README now explains how the package works

[Martin Langhoff]

---
 README |  194 ++++++++++++++++++++++++++++++++++++++++++++++++----------------
 1 files changed, 146 insertions(+), 48 deletions(-)

diff --git a/README b/README
index 21c9765..8b3eef8 100644
--- a/README
+++ b/README
@@ -1,49 +1,147 @@
-I am the author.   I am the maintainer.
-- Daniel Margo     ~ Martin Langhoff
-
-This is the default configuration for the OLPC XS/XSX school server,
-described in greater detail below. 
-***Don't ever install this if you don't understand what it is!***
-
-v0.1.3 - based on a configuration tree root snapshot of schoolserver.laptop.org
-on 7/23/07, with pruning and additions (see changelog).
-
-to rpmbuild:
-
-1.) Never rpmbuild as root.
-2.) The version information will be based on the output of
-    git describe. If you are on a tag, it will use that tag.
-    If you are X commits past that tag, it will count the commits
-    and add that as a suffix minor version.
-3.) make rpm
-4.) your rpms will be there in build/RPMS/
-
-*What Is This?*
-   This package installs OLPC-default configurations for an XS/XSX school
-server over existing configurations. It will bash RPM-default configurations,
-but not user-modified configurations. It tries to make backups wherever
-possible. Backups are named *.olpcsave or *.olpcnew, and follow the same logic
-as RPM backups.
-
-   The directory fsroot.olpc.img contains the configuration tree root image to
-install. You can easily generate a configuration tree root image on an existing
-machine by running the script get-configtree.py . You can also edit the tree
-by hand.
-
-   When the package is installed, fsroot.olpc.img is copied into the root
-directory of the target machine. It then recursively symlinks the image to the
-root directory, using the script symlink-tree.py . On uninstall, the package
-recursively unlinks the image and root directory using the script
-unlink-tree.py .
-
-   Obviously, installing this package can potentially be dangerous and
-*very destructive* to existing configurations.
-
-*So Why?*
-
-   The intention of this package is to be installed on OLPC XS/XSX live CD
-builds, as an "alternative default" configuration. It is *much* easier to
-maintain and experiment with the configuration tree than it is with
-postscripts. It is also much easier to locate OLPC-specific configuration files
-post-install when they are contained in a centralized directory.
+XS-config
+=========
 
+This package provides an initial configuration for the XS and tools
+to maintain and update the configuration as sanely and correctly as
+possible.
+
+This package uses various techniques to provide configuration to the XS
+so that 
+
+ - it does not conflict with the vanilla upstream packages
+ - it respects and incorporates local changes
+
+
+
+Strategies
+==========
+
+These are the strategies - from best to worst -
+
+conf.d
+------
+
+If the tool/daemon with its vanilla configuration supports a conf.d
+directory, *use it*. Any trick in the book is OK if it allows you to
+just drop a file in place without conflict.
+
+Install the file normally and mark it as a conffile.
+
+Example: httpd
+
+Alternative conf from sysconfig
+-------------------------------
+
+Init scripts for most system daemons (and for some system tools)
+read a file from /etc/sysconfig/ which can contain parameters to
+pass in the cmdline to the daemon (or equivcalent overrides).
+
+Use that opportunity to point the daemon to a different config
+file.
+
+Install the alternative config file normally and mark it as a conffile.
+
+Note however that the file in /etc/sysconfig/<servicename> _will_
+conflict, use the 'make a replacement' strategy for that.
+
+Example: named
+
+Make a replacement
+------------------
+
+This trick is good for two cases (that sometimes combine):
+
+ - Some tools and daemons cannot be diverted easily - some have hardcoded
+   paths, others have a hardcoded init script (file a bug against those!).
+
+ - We want to do search/replace in some conffiles, or add/remove things
+   conditionally.
+
+In such cases, install a "template" file with a .in extension and the correct
+owner/modes and add a rule to xs-config.make so that
+
+   cd /etc
+   make foobar.conf
+
+translates from foobar.conf.in to the desired foobar.conf . Follow the style
+in xs-config.make to get the file versioned safely, and add it to the 'all'
+target. 
+
+See below "My local edit was overwritten" for notes on the versioning.
+
+Install the template file normally and mark it as a conffile.
+
+This is not a trick to be proud of - the step of using make to copy or
+generate the file in %post means that we avoid the conflict over the
+actual config file.
+
+If you are planning on using this strategy, consider the 'Make a conf.d
+replacement'.
+
+Example: rssh.conf
+
+Make a conf.d replacement
+-------------------------
+
+If it is likely that other packages want to add bits of configuration to
+the conffile you are 'making' and the conffile format is not brittle or
+heavily dependent on ordering, consider creating a conf.d directory
+and using the cat-parts utility to concatenate "parts" provided by 
+potentially different packages. This is also a sane way to include local
+mods.
+
+Example: sudoers
+
+
+
+My local edit was overwritten! Or I want to make a local edit
+=============================================================
+
+The install scripts in xs-config ovewrite some configuration files
+based on templates. If you see the file you have edited or are planning to
+edit has a ".in" file in the same directory, or a ".d" directory
+with the same root name, you will want to edit the template (.in)
+file or add/edit something in the ".d" directory.
+
+For example
+
+ - edit /etc/resolv.conf.in instead of /etc/resolv.conf 
+ - add a new file in /etc/sudoers.d instead of /etc/sudoers
+
+After editing the templates, do
+
+ cd /etc 
+ make -f xs-config.make sudoers
+
+If you had made a local change (and it has been clobbered) you
+can retrieve it from the git repository in /etc -- try
+
+  $ cd /etc
+  $ git log    # look for lines that say 'Dirty' - they indicate
+               # that the script saved a local change before
+               # overwriting it
+  $ git log -p # this will show the diffs too.
+
+
+
+What about fsroot.olpc.img?
+===========================
+
+The /fsroot.olpc.img directory is deprecated. Report any remaining link to it
+on the server-devel at lists.laptop.org list or in a bug at dev.laptop.org
+
+
+
+Build chain
+===========
+
+make RPM
+
+
+
+Credits and blame
+=================
+
+- Maintainer: Martin Langhoff <martin at laptop.org>
+- John Watlington <wad at laptop.org>
+- Based on an original - but very different - package by Daniel Margo
\ No newline at end of file
-- 
1.5.5.1