doc: Massive update

2 files changed, 214 insertions, 0 deletions

diff --git a/doc/appendix/files/mysql.txt b/doc/appendix/files/mysql.txt
new file mode 100644
index 000000000..ae4a1450b
--- /dev/null
+++ b/doc/appendix/files/mysql.txt
@@ -0,0 +1,63 @@
+.. -*- mode: rst -*-
+
+.. _getting_started-mysql:
+
+.. Author: Patrick Ruckstuhl
+
+Mysql example
+=============
+
+I had some time ago to continue with putting my configuration into 
+Bcfg2 and maybe this helps someone else.
+
+I added a new bundle:
+
+.. code-block:: xml
+
+    <Bundle name="mysql-server" version="3.0">
+       <ConfigFile name="/root/bcfg2-install/mysql/users.sh"/>
+       <ConfigFile name="/root/bcfg2-install/mysql/users.sql"/>
+       <PostInstall name="/root/bcfg2-install/mysql/users.sh"/>
+       <Package name="mysql-server-4.1"/>
+       <Service name="mysql"/>
+    </Bundle>
+
+The ``users.sh`` script looks like this:
+
+.. code-block:: sh
+
+    #!/bin/sh
+
+    mysql --defaults-extra-file=/etc/mysql/debian.cnf mysql \
+        < /root/bcfg2-install/mysql/users.sql
+
+On debian there is a user account in ``/etc/mysql/debian.cnf`` 
+automatically created, but you could also (manually) create a 
+user in the database that has enough permissions and add the 
+login information in a file yourself. This file looks like this:
+
+.. code-block:: sh
+
+    [client]
+    host     = localhost
+    user     = debian-sys-maint
+    password = XXXXXXXXXX
+
+The ``users.sql`` looks like this:
+
+.. code-block:: sh
+
+    DELETE FROM db;
+    INSERT INTO db VALUES ('localhost', 'phpmyadmin', 'pma', 'Y', 'Y',
+    'Y', 'Y', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N');
+
+    DELETE FROM user WHERE User <> 'debian-sys-maint';
+    INSERT INTO user VALUES ('localhost', 'root', 'XXXXXXXXXXX', 'Y', 'Y',
+    'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y',
+    'Y', 'Y', 'Y', 'Y', 'Y', '', '', '', '', 0, 0, 0);
+    INSERT INTO user VALUES ('localhost', 'pma', '', 'N', 'N', 'N', 'N',
+    'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N', 'N',
+    'N', 'N', 'N', '', '', '', '', 0, 0, 0);
+
+    FLUSH PRIVILEGES;
+
diff --git a/doc/appendix/files/ntp.txt b/doc/appendix/files/ntp.txt
new file mode 100644
index 000000000..33cb3bfbb
--- /dev/null
+++ b/doc/appendix/files/ntp.txt
@@ -0,0 +1,151 @@
+.. -*- mode: rst -*-
+
+.. _appendix-files-ntp:
+
+.. Author: Jason Pepas
+
+ntp example
+===========
+
+Here is a series of example configurations for Bcfg2, each introducing
+another layer of functionality.
+
+* After each change, run ``bcfg-repo-validate -v``
+* Run the server with ``bcfg2-server -v``
+* Update the client with ``bcfg2 -v -d -n`` (will not actually make
+  client changes) 
+
+Package only
+------------
+
+Our example starts with the bare minimum configuration setup. We have
+a client, a profile group, a list of packages, and a base configuration.
+
+.. code-block:: sh
+
+     # cat Metadata/clients.xml 
+     <Clients version='3.0'>
+     <Client profile='fedora' pingable='N' pingtime='0' name='foo.bar.com'/>
+     </Clients>
+
+.. code-block:: sh
+
+     # cat Metadata/groups.xml 
+     <Groups version='3.0'>
+     <Group profile='true' name='fedora' toolset='rh'/>
+     </Groups>
+
+.. code-block:: sh
+
+     # cat Base/base.xml 
+     <Base>
+     <Group name='fedora'>
+     <Package name='ntp'/>
+     </Group>
+     </Base>
+
+.. code-block:: sh
+
+     # cat Pkgmgr/packages.xml
+     <PackageList type='rpm' priority='0'>
+     <Package name='ntp' version='4.2.0.a.20050816-11.FC5'/>
+     </PackageList>
+
+Add service
+-----------
+
+Configure the service, and add it to the base.
+
+.. code-block:: sh
+
+     # cat Svcmgr/services.xml 
+     <Services priority='0'>
+     <Service name='ntpd' status='on'/>
+     </Services>
+
+.. code-block:: sh
+
+     # cat Base/base.xml 
+     <Base>
+     <Group name='fedora'>
+     <Package name='ntp'/>
+     <Service name='ntpd'/>
+     </Group>
+     </Base>
+
+Add config file
+---------------
+
+Setup an ``etc/`` directory structure, and add it to the base.
+
+.. code-block:: sh
+
+     # cat Cfg/etc/ntp.conf/ntp.conf 
+     server ntp1.utexas.edu
+
+.. code-block:: sh
+
+     # cat Base/base.xml 
+     <Base>
+     <Group name='fedora'>
+     <Package name='ntp'/>
+     <Service name='ntpd'/>
+     <ConfigFile name='/etc/ntp.conf'/>
+     </Group>
+    </Base>
+
+Create a bundle
+---------------
+
+The above configuration layout works fine for a single service, but
+that method of organization would quickly become a nightmare as you
+approach the number of packages, services, and config files required
+to represent a fully configured host. Bundles allow the grouping of
+related configuration entries that are used to provide a single
+service. This is done for several reasons:
+
+* Grouping related things in one place makes it easier to add those
+  entries for a multiple groups of clients
+* Grouping entries into bundles makes their validation occur
+  collectively. This means that config files can override the
+  contents of packages. Also, config files are rechecked after
+  packages are upgraded, so that they can be repaired if the
+  package install clobbered them.
+* Services associated with a bundle get restarted whenever any entity
+  in that bundle is modified. This ensures that new configuration 
+  files and software are used after installation. 
+
+The config file, package, and service are really all related
+components describing the idea of an ntp client, so they should be 
+logically grouped together. We use a bundle to accomplish this.
+
+.. code-block:: sh
+
+     # cat Bundler/ntp.xml
+     <Bundle name='ntp' version='2.0'>
+     <Package name='ntp'/>
+     <Service name='ntpd'/>
+     <ConfigFile name='/etc/ntp.conf'/>
+     </Bundle>
+
+After this bundle is created, it must be associated with a group
+(or groups). Add a bundle child element to the group(s) which should
+install this bundle.
+
+.. code-block:: sh
+
+     # cat Metadata/groups.xml
+     <Groups>
+    ...
+     <Group name='fedora'>
+       <Bundle name='ntp'/>
+     </Group>
+    ...
+     </Groups>
+
+Once this bundle is created, a client reconfigure will install these 
+entries. If any are modified, then the ``ntpd`` service will be
+restarted. If you only want ntp configurations to be updated
+(and nothing else), the bcfg2 client can be run with a 
+``-b <bundle name>`` option that will only update entries in
+the specified bundle.