diff options
Diffstat (limited to 'doc/unsorted/annotated_examples.txt')
| -rw-r--r-- | doc/unsorted/annotated_examples.txt | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/doc/unsorted/annotated_examples.txt b/doc/unsorted/annotated_examples.txt new file mode 100644 index 000000000..99c6f774c --- /dev/null +++ b/doc/unsorted/annotated_examples.txt @@ -0,0 +1,186 @@ +.. -*- mode: rst -*- + +.. _unsorted-annotated_examples: + +================== +Annotated Examples +================== + +ntp example +=========== + +Author: Jason Pepas + +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. + +:: + + # cat Metadata/clients.xml + <Clients version='3.0'> + <Client profile='fedora' pingable='N' pingtime='0' name='foo.bar.com'/> + </Clients> + + # cat Metadata/groups.xml + <Groups version='3.0'> + <Group profile='true' name='fedora' toolset='rh'/> + </Groups> + + # cat Base/base.xml + <Base> + <Group name='fedora'> + <Package name='ntp'/> + </Group> + </Base> + + # 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.:: + + # cat Svcmgr/services.xml + <Services priority='0'> + <Service name='ntpd' status='on'/> + </Services> + + # 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.:: + + # cat Cfg/etc/ntp.conf/ntp.conf + server ntp1.utexas.edu + + # 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.:: + + # 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.:: + + + # 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. + +mysql example +============= + +Author: Patrick Ruckstuhl + +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:: + + [client] + host = localhost + user = debian-sys-maint + password = XXXXXXXXXX + +The `users.sql` looks like this:: + + 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; |