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
 - upon package install, no system configuration changes are made.
   xs-setup must be executed to apply configuration changes to the system
   if/when the user wishes to convert a base OS install into an XS.



Strategies
==========

Files that can be harmlessly installed by the RPM are found in altfiles/ in the
source. These files must not affect system behaviour until some other action
is taken (such as the enabling of an init script).

Files which cannot be put in place on the real filesystem without modifying
system behaviour are installed into /usr/share/xs-config/cfg and are
put in place by xs-setup when the user wishes to activate the XS capabilities
on the system.

It is advised to put as much in altfiles/ as possible, since RPM will handle
version control aspects such as removing the file if it is later removed from
a new version of this package.


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 in cfg, and use xs-setup to put it in place on the real
system.

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 into cfg, and use xs-setup
to put it in place on the real system.

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-setup, xs-setup-network or domain_config.d
so that the template is translated into the desired output file.

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.




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 

After editing the templates, do

# xs-setup

And if using the XS custom network layout:

# xs-setup-network

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@lists.laptop.org list or in a bug at dev.laptop.org



Build chain
===========

make RPM



Credits and blame
=================

- Maintainer: Martin Langhoff <martin@laptop.org>
- John Watlington <wad@laptop.org>
- Based on an original - but very different - package by Daniel Margo