diff options
Diffstat (limited to 'doc/getting_started/index.txt')
| -rw-r--r-- | doc/getting_started/index.txt | 116 |
1 files changed, 62 insertions, 54 deletions
diff --git a/doc/getting_started/index.txt b/doc/getting_started/index.txt index 786c70290..9661fcb89 100644 --- a/doc/getting_started/index.txt +++ b/doc/getting_started/index.txt @@ -6,10 +6,13 @@ Getting started =============== -The steps below should get you from just thinking about a -configuration management system to an operational installation of -Bcfg2. If you get stuck, be sure to check the :ref:`mailinglist` -or to drop in on our :ref:`ircchannel`. +The steps below should get you from just thinking about a configuration +management system to an operational installation of Bcfg2. If you get +stuck, be sure to check the :ref:`help-mailinglist` or to drop in on +our :ref:`help-irc`. + +See the `Platform-specific Quickstart Notes`_ at the end of this page +if you happen to be using one of the more common operating systems. Get and Install Bcfg2 Server ============================ @@ -18,7 +21,7 @@ We recommend running the server on a Linux machine for ease of deployment due to the availability of packages for the dependencies. First, you need to download and install Bcfg2. The section -:ref:`installation-index` in this manual describes the steps to take. +:ref:`installation-index` in this manual describes the steps to take. To start, you will need to install the server on one machine and the client on one or more machines. Yes, your server can also be a client (and should be by the time your environment is fully managed). @@ -50,26 +53,25 @@ acting like it is your first client. .. note:: - The following command will tell the client to run in no-op mode, - meaning it will only check the client against the repository and - report any changes it sees. It won't make any changes (partially - because you haven't populated the repository with any - yet). However, nobody is perfect - you can make a typo, our - software can have bugs, monkeys can break in and hit enter before - you are done. Don't run this command on a production system if you - don't know what it does and aren't prepared for the - consequences. We don't know of anybody having problems with it - before, but it is better to be safe than sorry. + The following command will tell the client to run in no-op mode, + meaning it will only check the client against the repository and + report any differences it sees. It won't make any changes (partially + because you haven't populated the repository with any yet). However, + nobody is perfect. You can make a typo, our software can have bugs, + monkeys can break in and hit enter before you are done. Don't run + this command on a production system if you don't know what it does + and aren't prepared for the consequences. We don't know of anybody + having problems with it before, but it is better to be safe than sorry. And now for the command:: - bcfg2 -q -v -n + bcfg2 -q -v -n That can be translated as "bcfg2 quick verbose no-op". The output should be something similar to:: Loaded tool drivers: - Chkconfig POSIX PostInstall RPM + Chkconfig POSIX YUMng Phase: initial Correct entries: 0 @@ -87,9 +89,10 @@ should be something similar to:: Perfect! We have started out with an empty configuration, and none of our configuration elements are correct. It doesn't get much cleaner than that. But what about those unmanaged entries? Those are the extra -configuration elements (probably all packages at the moment) that -still aren't managed. Your goal now is to migrate each of those plus -any it can't see up to the "Correct entries" line. +configuration elements (probably all packages and services at the +moment) that still aren't managed, but have been detected by the client +tools. Your goal now is to migrate each of those plus any it can't see +up to the "Correct entries" line. Populate Repository =================== @@ -105,7 +108,7 @@ After the above steps, you should have a toplevel repository structure that looks like:: bcfg-server:~ # ls /var/lib/bcfg2 - Bundler/ Cfg/ Metadata/ Pkgmgr/ Rules/ SSHbase/ etc/ + Base/ Bundler/ Cfg/ Metadata/ Pkgmgr/ Rules/ SSHbase/ etc/ The place to start is the Metadata directory, which contains two files: ``clients.xml`` and ``groups.xml``. Your current @@ -113,9 +116,9 @@ files: ``clients.xml`` and ``groups.xml``. Your current .. code-block:: xml - <Clients version="3.0"> - <Client profile="basic" pingable="Y" pingtime="0" name="bcfg-server.example.com"/> - </Clients> + <Clients version="3.0"> + <Client profile="basic" pingable="Y" pingtime="0" name="bcfg-server.example.com"/> + </Clients> The ``clients.xml`` file is just a series of ``<Client />`` tags, each of which describe one host you manage. Right now we only manage one @@ -130,27 +133,26 @@ Our simple ``groups.xml`` file looks like: .. code-block:: xml - <Groups version='3.0'> - <Group profile='true' public='false' name='basic'> - <Group name='suse'/> - </Group> - <Group name='ubuntu' toolset='debian'/> - <Group name='debian' toolset='debian'/> - <Group name='redhat' toolset='rh'/> - <Group name='suse' toolset='rh'/> - <Group name='mandrake' toolset='rh'/> - <Group name='solaris' toolset='solaris'/> - </Groups> - -There are two types of groups in Bcfg: profile groups -(``profile='true'``) and non-profile groups -(``profile='false'``). Profile groups can act as top-level groups to -which clients can bind, while non-profile groups only exist as members -of other groups. In our simple starter case, we have a profile group -named ``basic``, and that is the group that our first client bound -to. Our first client is a SuSE machine, so it contains the ``suse`` -group. Of course, ``bcfg2-admin`` isn't smart enough to fill out the -rest of your config, so the ``suse`` group further down is empty. + <Groups version='3.0'> + <Group profile='true' public='false' name='basic'> + <Group name='suse'/> + </Group> + <Group name='ubuntu' /> + <Group name='debian' /> + <Group name='redhat' /> + <Group name='suse' /> + <Group name='mandrake' /> + <Group name='solaris' /> + </Groups> + +There are two types of groups in Bcfg: profile groups (``profile='true'``) +and non-profile groups (``profile='false'``). Profile groups can act as +top-level groups to which clients can bind, while non-profile groups only +exist as members of other groups. In our simple starter case, we have +a profile group named ``basic``, and that is the group that our first +client bound to. Our first client is a SuSE machine, so it contains the +``suse`` group. Of course, ``bcfg2-admin`` isn't smart enough to fill +out the rest of your config, so the ``suse`` group further down is empty. Let's say the first thing we want to set up on our machine is the message of the day. To do this, we simply need to create a Bundle and @@ -159,7 +161,7 @@ start out by adding .. code-block:: xml - <Bundle name='motd'/> + <Bundle name='motd'/> to the ``basic`` group. @@ -167,14 +169,14 @@ Next, we create a motd.xml file in the Bundler directory: .. code-block:: xml - <Bundle name='motd' version='2.0'> - <Path name='/etc/motd' /> - </Bundle> + <Bundle name='motd' version='2.0'> + <Path name='/etc/motd' /> + </Bundle> Now when we run the client, we get slightly different output:: Loaded tool drivers: - Chkconfig POSIX PostInstall RPM + Chkconfig POSIX YUMng Incomplete information for entry Path:/etc/motd; cannot verify Phase: initial @@ -225,16 +227,16 @@ Done! Now we just have 242 (or more) entries to take care of! directory to populate. You can find many samples of Bundles in the `Bundle Repository`_, many of which can be used without editing. -.. _Bundle Repository: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Bundler/examples +.. _Bundle Repository: http://docs.bcfg2.org/server/plugins/structures/bundler/index.html#other-examples Next Steps ========== Several other utilities can help from this point on: -``bcfg2-info`` is a utility that instantiates a copy of the Bcfg2 server -core (minus the networking code) for examination. From this, you can -directly query: +:ref:`bcfg2-info <appendix-guides-using_bcfg2_info>` is a utility that +instantiates a copy of the bcfg2 server core (minus the networking code) +for examination. From this, you can directly query: * Client Metadata * Which entries are provided by particular plugins @@ -244,3 +246,9 @@ Run ``bcfg2-info``, and type help and the prompt when it comes up. ``bcfg2-admin`` can perform a variety of repository maintenance tasks. Run ``bcfg2-admin`` help for details. + +Platform-specific Quickstart Notes +================================== + +* :ref:`appendix-guides-centos` +* :ref:`appendix-guides-ubuntu` |