From e73ac8768901cb52b8d1c345772df0ebd5dd86ba Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 9 Nov 2010 00:36:42 +0100 Subject: quickstart removed --- doc/introduction/os-support.txt | 2 +- doc/quickstart/centos.txt | 567 --------------------------- doc/quickstart/index.txt | 260 ------------ doc/quickstart/ubuntu.txt | 479 ---------------------- doc/server/plugins/connectors/properties.txt | 10 +- 5 files changed, 5 insertions(+), 1313 deletions(-) delete mode 100644 doc/quickstart/centos.txt delete mode 100644 doc/quickstart/index.txt delete mode 100644 doc/quickstart/ubuntu.txt (limited to 'doc') diff --git a/doc/introduction/os-support.txt b/doc/introduction/os-support.txt index efbc307cb..3e27019f2 100644 --- a/doc/introduction/os-support.txt +++ b/doc/introduction/os-support.txt @@ -20,7 +20,7 @@ Bcfg2 is fairly portable. It has been successfully run on: * Many `GNU/Linux`_ distributions, including `Archlinux`_, `Blag`_, `CentOS`_, `Debian`_, `Fedora`_, `Gentoo`_, `gNewSense`_, `Mandriva`_, `OpenSUSE`_, `Red Hat/RHEL`_, `Scientific Linux`_, `SuSE/SLES`_, `Trisquel`_, - and `Ubuntu`_. + and `Ubuntu`_. .. _GNU/Linux: http://www.gnu.org/gnu/Linux-and-gnu.html .. _Archlinux: http://www.archlinux.org diff --git a/doc/quickstart/centos.txt b/doc/quickstart/centos.txt deleted file mode 100644 index 4a702683e..000000000 --- a/doc/quickstart/centos.txt +++ /dev/null @@ -1,567 +0,0 @@ -.. -*- mode: rst -*- - -.. _EPEL: http://fedoraproject.org/wiki/EPEL - -.. _quickstart-centos: - -===================== -Quickstart for CentOS -===================== - -This is a complete getting started guide for CentOS. With this document -you should be able to install a Bcfg2 server and a Bcfg2 client. - -Install Bcfg2 -============= - -The fastest way to get Bcfg2 onto your system is to use Yum or -your preferred package management tool. We'll be using the ones -that are distributed through EPEL_, but depending on your aversion -to risk you could download an RPM from other places as well. See -:ref:`getting_started-using_bcfg2-with-centos` for information about -building Bcfg2 from source and making your own packages. - -Using EPEL ----------- - -Make sure EPEL_ is a valid repository on your server. The `instructions -`_ on how to do this -basically say:: - - [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/x86_64/epel-release-5-4.noarch.rpm - -.. note:: - - You will have to adjust this command to match your architecture and - the current EPEL release. - -Install the bcfg2-server and bcfg2 RPMs:: - - [root@centos ~]# yum install bcfg2-server bcfg2 - -Your system should now have the necessary software to use Bcfg2. The -next step is to set up your Bcfg2 :term:`repository`. - -Initialize your repository -========================== - -Now that you're done with the install, you need to initialize your -repository and setup your ``/etc/bcfg2.conf``. ``bcfg2-admin init`` -is a tool which allows you to automate this:: - - [root@centos ~]# bcfg2-admin init - Store bcfg2 configuration in [/etc/bcfg2.conf]: - Location of bcfg2 repository [/var/lib/bcfg2]: - Input password used for communication verification (without echoing; leave blank for a random): - What is the server's hostname: [centos] - Input the server location [https://centos:6789]: - Input base Operating System for clients: - 1: Redhat/Fedora/RHEL/RHAS/Centos - 2: SUSE/SLES - 3: Mandrake - 4: Debian - 5: Ubuntu - 6: Gentoo - 7: FreeBSD - : 1 - Generating a 2048 bit RSA private key - .........................+++ - ..................+++ - writing new private key to '/etc/bcfg2.key' - ----- - Signature ok - subject=/C=US=ST=Illinois/L=Argonne/CN=centos - Getting Private key - Repository created successfuly in /var/lib/bcfg2 - -Change responses as necessary. - -Start the server -================ - -You are now ready to start your bcfg2 server for the first time:: - - [root@centos ~]# /sbin/service bcfg2-server start - -To verify that everything started ok, look for the running daemon and check the logs:: - - [root@centos ~]# /etc/init.d/service bcfg2-server status - [root@centos ~]# tail /var/log/messages - Mar 29 12:42:26 centos bcfg2-server[5093]: service available at https://centos:6789 - Mar 29 12:42:26 centos bcfg2-server[5093]: serving bcfg2-server at https://centos:6789 - Mar 29 12:42:26 centos bcfg2-server[5093]: serve_forever() [start] - Mar 29 12:42:41 centos bcfg2-server[5093]: Handled 16 events in 0.007s - -Run bcfg2 to be sure you are able to communicate with the server:: - - [root@centos ~]# bcfg2 -vqn - No ca is specified. Cannot authenticate the server with SSL. - No ca is specified. Cannot authenticate the server with SSL. - Loaded plugins: fastestmirror - Loading mirror speeds from cached hostfile - Excluding Packages in global exclude list - Finished - Loaded tool drivers: - Action Chkconfig POSIX YUMng - - Phase: initial - Correct entries: 0 - Incorrect entries: 0 - Total managed entries: 0 - Unmanaged entries: 208 - - - Phase: final - Correct entries: 0 - Incorrect entries: 0 - Total managed entries: 0 - Unmanaged entries: 208 - - No ca is specified. Cannot authenticate the server with SSL. - -The ca message is just a warning, meaning that the client does not -have sufficient information to verify that it is talking to the -correct server. This can be fixed by distributing the ca certificate -from the server to all clients. By default, this file is available in -``/etc/bcfg2.crt`` on the server. Copy this file to the client (with a -bundle) and add the ca option to ``bcfg2.conf`` pointing at the file, -and the client will be able to verify it is talking to the correct server -upon connection:: - - [root@centos ~]# cat /etc/bcfg2.conf - - - [communication] - protocol = xmlrpc/ssl - password = N41lMNeW - ca = /etc/bcfg2.crt - - [components] - bcfg2 = https://centos:6789 - -Now if you run the client, no more warning:: - - [root@centos ~]# bcfg2 -vqn - Loaded plugins: fastestmirror - Loading mirror speeds from cached hostfile - Excluding Packages in global exclude list - Finished - Loaded tool drivers: - Action Chkconfig POSIX YUMng - - Phase: initial - Correct entries: 0 - Incorrect entries: 0 - Total managed entries: 0 - Unmanaged entries: 208 - - - Phase: final - Correct entries: 0 - Incorrect entries: 0 - Total managed entries: 0 - Unmanaged entries: 208 - -Bring your first machine under Bcfg2 control -============================================ - -Now it is time to get your first machine's configuration into your -Bcfg2 :term:`repository`. Let's start with the server itself. - - -Setup the `Packages`_ plugin ----------------------------- - -.. _Packages: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages - -First, replace **Pkgmgr** with **Packages** in the plugins -line of ``bcfg2.conf``. Then create Packages layout (as per -:ref:`packages-exampleusage`) in ``/var/lib/bcfg2`` - -.. note:: I am using the RawURL syntax here since we are using `mrepo`_ - to manage our yum mirrors. - -.. _mrepo: http://dag.wieers.com/home-made/mrepo/ - -.. code-block:: xml - - - - - centos5.4 - http://mrepo/centos5-x86_64/RPMS.os - x86_64 - - - centos5.4 - http://mrepo/centos5-x86_64/RPMS.updates - x86_64 - - - centos5.4 - http://mrepo/centos5-x86_64/RPMS.extras - x86_64 - - - -Due to the `Magic Groups`_, we need to modify our Metadata. Let's -add a **centos5.4** group which inherits a **centos** group -(this should replace the existing **redhat** group) present in -``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file should look -something like this - -.. _Magic Groups: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages#MagicGroups - -.. code-block:: xml - - - - - - - - - - - - - - - - - - -.. note:: - When editing your xml files by hand, it is useful to occasionally run - `bcfg2-repo-validate` to ensure that your xml validates properly. - -The final thing we need is for the client to have the proper -arch group membership. For this, we will make use of the -:ref:`unsorted-dynamic_groups` capabilities of the Probes plugin. Add -Probes to your plugins line in ``bcfg2.conf`` and create the Probe.:: - - [root@centos ~]# grep plugins /etc/bcfg2.conf - plugins = Base,Bundler,Cfg,Metadata,Packages,Probes,Rules,SSHbase - [root@centos ~]# mkdir /var/lib/bcfg2/Probes - [root@centos ~]# cat /var/lib/bcfg2/Probes/groups - #!/bin/sh - - echo "group:`uname -m`" - -Now we restart the bcfg2-server:: - - [root@centos ~]# /etc/init.d/bcfg2-server restart - -If you tail ``/var/log/syslog`` now, you will see the Packages plugin in -action, updating the cache. - -Start managing packages ------------------------ - -Add a base-packages bundle. Let's see what happens when we just populate -it with the *yum* package. - -.. code-block:: xml - - [root@centos ~]# cat /var/lib/bcfg2/Bundler/base-packages.xml - - - - -You need to reference the bundle from your Metadata. The resulting -profile group might look something like this - -.. code-block:: xml - - - - - - -Now if we run the client, we can see what this has done for us.:: - - [root@centos ~]# bcfg2 -vqn - Running probe groups - Probe groups has result: - x86_64 - Loaded plugins: fastestmirror - Loading mirror speeds from cached hostfile - Excluding Packages in global exclude list - Finished - Loaded tool drivers: - Action Chkconfig POSIX YUMng - Package pam failed verification. - - Phase: initial - Correct entries: 94 - Incorrect entries: 1 - Total managed entries: 95 - Unmanaged entries: 113 - - In dryrun mode: suppressing entry installation for: - Package:pam - - Phase: final - Correct entries: 94 - Incorrect entries: 1 - Package:pam - Total managed entries: 95 - Unmanaged entries: 113 - -Interesting, our **pam** package failed verification. What does this -mean? Let's have a look:: - - [root@centos ~]# rpm --verify pam - ....L... c /etc/pam.d/system-auth - -Sigh, it looks like the default RPM install for pam fails to verify -using its own verification process (trust me, it's not the only one). At -any rate, I was able to get rid of this particular issue by removing the -symlink and running ``yum reinstall pam``. - -As you can see, the Packages plugin has generated the dependencies -required for the yum package automatically. The ultimate goal should -be to move all the packages from the **Unmanaged** entries section to -the **Managed** entries section. So, what exactly *are* those Unmanaged -entries?:: - - [root@centos ~]# bcfg2 -veqn - Running probe groups - Probe groups has result: - x86_64 - Loaded plugins: fastestmirror - Loading mirror speeds from cached hostfile - Excluding Packages in global exclude list - Finished - Loaded tool drivers: - Action Chkconfig POSIX YUMng - Extra Package openssh-clients 4.3p2-36.el5_4.4.x86_64. - Extra Package libuser 0.54.7-2.1el5_4.1.x86_64. - ... - - Phase: initial - Correct entries: 95 - Incorrect entries: 0 - Total managed entries: 95 - Unmanaged entries: 113 - - - Phase: final - Correct entries: 95 - Incorrect entries: 0 - Total managed entries: 95 - Unmanaged entries: 113 - Package:at - Package:avahi - Package:avahi-compat-libdns_sd - ... - -Now you can go through these and continue adding the packages you want -to your Bundle. After a while, I ended up with a minimal bundle that -looks like this - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - -Now when I run the client, you can see I have only one unmanaged -package:: - - [root@centos ~]# bcfg2 -veqn - Running probe groups - Probe groups has result: - x86_64 - Loaded plugins: fastestmirror - Loading mirror speeds from cached hostfile - Excluding Packages in global exclude list - Finished - Loaded tool drivers: - Action Chkconfig POSIX YUMng - Extra Package gpg-pubkey e8562897-459f07a4.None. - Extra Package gpg-pubkey 217521f6-45e8a532.None. - - Phase: initial - Correct entries: 187 - Incorrect entries: 0 - Total managed entries: 187 - Unmanaged entries: 16 - - - Phase: final - Correct entries: 187 - Incorrect entries: 0 - Total managed entries: 187 - Unmanaged entries: 16 - Package:gpg-pubkey - Service:atd - Service:avahi-daemon - Service:bcfg2-server - ... - -The gpg-pubkey packages are special in that they are not really -packages. Currently, the way to manage them is using :ref:`BoundEntries -`. So, after adding them, our Bundle now looks like this - -.. note:: This does not actually control the contents of the files, - you will need to do this part separately (see below). - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - -.. note:: version="foo" is just a dummy attribute for the gpg-pubkey Package - -To actually push the gpg keys out via Bcfg2, you will need to manage the -files as well. This can be done by adding Path entries for each of the -gpg keys you want to manage - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - -Then add the files to Cfg:: - - mkdir -p Cfg/etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5 - cp /etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-5 !$/RPM-GPG-KEY-CentOS-5 - mkdir -p Cfg/etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL - cp /etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL !$/RPM-GPG-KEY-EPEL - -Now, running the client shows only unmanaged Service entries. Woohoo! - -Manage services ---------------- - -Now let's clear up the unmanaged service entries by adding the following -entries to our bundle. - -.. code-block:: xml - - - - - - - - - - - - - - - - - - -...and bind them in Rules - -.. code-block:: xml - - [root@centos ~]# cat /var/lib/bcfg2/Rules/services.xml - - - - - - - - - - - - - - - - - - - -Now we run the client and see there are no more unmanaged entries! :: - - [root@centos ~]# bcfg2 -veqn - Running probe groups - Probe groups has result: - x86_64 - Loaded plugins: fastestmirror - Loading mirror speeds from cached hostfile - Excluding Packages in global exclude list - Finished - Loaded tool drivers: - Action Chkconfig POSIX YUMng - - Phase: initial - Correct entries: 205 - Incorrect entries: 0 - Total managed entries: 205 - Unmanaged entries: 0 - - - Phase: final - Correct entries: 205 - Incorrect entries: 0 - Total managed entries: 205 - Unmanaged entries: 0 - -Dynamic (web) reports -===================== - -See installation instructions at :ref:`server-reports-install` diff --git a/doc/quickstart/index.txt b/doc/quickstart/index.txt deleted file mode 100644 index 37dbaa915..000000000 --- a/doc/quickstart/index.txt +++ /dev/null @@ -1,260 +0,0 @@ -.. -*- mode: rst -*- - -.. _quickstart-index: - -========== -Quickstart -========== - -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 `mailing list`_ -or to drop in on our `IRC channel`_. - -.. _mailing list: https://trac.mcs.anl.gov/projects/bcfg2/wiki/MailingList -.. _IRC channel: https://trac.mcs.anl.gov/projects/bcfg2/wiki/IRCChannel - -See the `Platform-specific Quickstart Notes`_ at the end of this page in case your operating systems has been favored with its own quickstart document. - -Get and Install Bcfg2 Server -============================ - -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 `Bcfg2 download -page`_ has both source and packages for common environments, while our -`Install page`_ describes what to do once you have the packages in hand. -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). - -.. _Bcfg2 download page: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Download -.. _Install page: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Install - -Set up Repository -================= - -The next step after installing the Bcfg2 packages is to configure the -server. You can easily set up a personalized default configuration by -running, on the server, :: - - bcfg2-admin init - -You will be presented with a series of questions that will build a -Bcfg2 configuration file in ``/etc/bcfg2.conf``, set up a skeleton -repository (in ``/var/lib/bcfg2`` by default), help you create ssl -certificates, and do any other similar tasks needed to get you -started. - -Once this process is done, you can start the Bcfg2 server:: - - /etc/init.d/bcfg2-server start - -You can try it out by running the Bcfg2 client on the same machine, -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 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 - -That can be translated as "bcfg2 quick verbose no-op". The output -should be something similar to:: - - Loaded tool drivers: - Chkconfig POSIX YUMng - - Phase: initial - Correct entries: 0 - Incorrect entries: 0 - Total managed entries: 0 - Unmanaged entries: 242 - - - Phase: final - Correct entries: 0 - Incorrect entries: 0 - Total managed entries: 0 - Unmanaged entries: 242 - -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 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 -=================== - -Finally, you need to populate your repository. Unfortunately, from -here on out we can't write up a simple recipe for you to follow to get -this done. It is very dependent on your local configuration, your -configuration management goals, the politics surrounding your -particular machines, and many other similar details. We can, however, -give you guidance. - -After the above steps, you should have a toplevel repository structure -that looks like:: - - bcfg-server:~ # ls /var/lib/bcfg2 - 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 -``clients.xml`` will look pretty close to: - -.. code-block:: xml - - - - - -The ``clients.xml`` file is just a series of ```` tags, each -of which describe one host you manage. Right now we only manage one -host, the server machine we just created. This machine is bound to the -``basic`` profile, is pingable, has a pingtime of ``0``, and has the -name ``bcfg-server.example.com``. The two "ping" parameters don't -matter to us at the moment, but the other two do. The name parameter -is the fully qualified domain name of your host, and the profile -parameter maps that host into the ``groups.xml`` file. - -Our simple ``groups.xml`` file looks like: - -.. code-block:: xml - - - - - - - - - - - - - -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 -add that Bundle to an appropriate group. In this simple example, we -start out by adding - -.. code-block:: xml - - - -to the ``basic`` group. - -Next, we create a motd.xml file in the Bundler directory: - -.. code-block:: xml - - - - - -Now when we run the client, we get slightly different output:: - - Loaded tool drivers: - Chkconfig POSIX YUMng - Incomplete information for entry Path:/etc/motd; cannot verify - - Phase: initial - Correct entries: 0 - Incorrect entries: 1 - Total managed entries: 1 - Unmanaged entries: 242 - - In dryrun mode: suppressing entry installation for: - Path:/etc/motd - - Phase: final - Correct entries: 0 - Incorrect entries: 1 - Total managed entries: 1 - Unmanaged entries: 242 - -We now have an extra unmanaged entry, bringing our total number of -managed entries up to one. To manage it we need to copy ``/etc/motd`` -to ``/var/lib/bcfg2/Cfg/etc/motd/``. Note the layout of that path: all -plain-text config files live in the Cfg directory. The directory -structure under that directory directly mimics your real filesystem -layout, making it easy to find and add new files. The last directory -is the name of the file itself, so in this case the full path to the -motd file would be ``/var/lib/bcfg2/Cfg/etc/motd/motd``. Copy your -real ``/etc/motd`` file to that location, run the client again, and -you will find that we now have a correct entry:: - - Loaded tool drivers: - Chkconfig POSIX PostInstall RPM - - Phase: initial - Correct entries: 1 - Incorrect entries: 0 - Total managed entries: 1 - Unmanaged entries: 242 - - - Phase: final - Correct entries: 1 - Incorrect entries: 0 - Total managed entries: 1 - Unmanaged entries: 242 - -Done! Now we just have 242 (or more) entries to take care of! - -:ref:`server-plugins-structures-bundler-index` is a relatively easy -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://docs.bcfg2.org/server/plugins/structures/bundler/index.html#other-examples - -Next Steps -========== - -Several other utilities can help from this point on: - -:ref:`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 -* Client Configurations - -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 -================================== - -.. toctree:: - :maxdepth: 2 - - centos - ubuntu diff --git a/doc/quickstart/ubuntu.txt b/doc/quickstart/ubuntu.txt deleted file mode 100644 index 41d69eb0c..000000000 --- a/doc/quickstart/ubuntu.txt +++ /dev/null @@ -1,479 +0,0 @@ -.. -*- mode: rst -*- - -.. _quickstart-ubuntu: - -===================== -Quickstart for Ubuntu -===================== - -.. note:: - - This particular how to was done on lucid, but should apply to any - other `stable`__ version of Ubuntu. - -__ ubuntu-releases_ -.. _ubuntu-releases: https://wiki.ubuntu.com/Releases - -Install Bcfg2 -============= - -We first need to install the server. For this example, we will use the -bcfg2 server package from the bcfg2 `PPA`_ (note that there is also a -version available in the ubuntu archives, but it is not as up to date). - -.. _PPA: https://launchpad.net/~bcfg2/+archive/ppa - -Add the Ubuntu PPA listing to your APT sources ----------------------------------------------- - -See http://trac.mcs.anl.gov/projects/bcfg2/wiki/PrecompiledPackages#UbuntuLucid - -Install bcfg2-server --------------------- -:: - - aptitude install bcfg2-server - -Remove the default configuration preseeded by the ubuntu package:: - - root@lucid:~# rm -rf /etc/bcfg2* /var/lib/bcfg2 - -Initialize your repository -========================== - -Now that you're done with the install, you need to intialize your -repository and setup your bcfg2.conf. bcfg2-admin init is a tool which -allows you to automate this process.:: - - root@lucid:~# bcfg2-admin init - Store bcfg2 configuration in [/etc/bcfg2.conf]: - Location of bcfg2 repository [/var/lib/bcfg2]: - Input password used for communication verification (without echoing; leave blank for a random): - What is the server's hostname: [lucid] - Input the server location [https://lucid:6789]: - Input base Operating System for clients: - 1: Redhat/Fedora/RHEL/RHAS/Centos - 2: SUSE/SLES - 3: Mandrake - 4: Debian - 5: Ubuntu - 6: Gentoo - 7: FreeBSD - : 5 - Generating a 2048 bit RSA private key - ......................................................................................+++ - ...+++ - writing new private key to '/etc/bcfg2.key' - ----- - Signature ok - subject=/C=US/ST=Illinois/L=Argonne/CN=lucid - Getting Private key - Repository created successfuly in /var/lib/bcfg2 - - -Of course, change responses as necessary. - -Start the server -================ - -You are now ready to start your bcfg2 server for the first time.:: - - root@lucid:~# /etc/init.d/bcfg2-server start - root@lucid:~# tail /var/log/syslog - Dec 17 22:07:02 lucid bcfg2-server[17523]: serving bcfg2-server at https://lucid:6789 - Dec 17 22:07:02 lucid bcfg2-server[17523]: serve_forever() [start] - Dec 17 22:07:02 lucid bcfg2-server[17523]: Processed 16 fam events in 0.502 seconds. 0 coalesced - -Run bcfg2 to be sure you are able to communicate with the server:: - - root@lucid:~# bcfg2 -vqn - Loaded tool drivers: - APT Action DebInit POSIX - - Phase: initial - Correct entries: 0 - Incorrect entries: 0 - Total managed entries: 0 - Unmanaged entries: 382 - - - Phase: final - Correct entries: 0 - Incorrect entries: 0 - Total managed entries: 0 - Unmanaged entries: 382 - -Bring your first machine under Bcfg2 control -============================================ - -Now it is time to get your first machine's configuration into your Bcfg2 -repository. Let's start with the server itself. - -Setup the `Packages`_ plugin ----------------------------- - -.. _Packages: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages - -Replace Pkgmgr with Packages in the plugins line of ``bcfg2.conf``:: - - root@lucid:~# cat /etc/bcfg2.conf - [server] - repository = /var/lib/bcfg2 - plugins = Base,Bundler,Cfg,Metadata,Packages,Rules,SSHbase - - [statistics] - sendmailpath = /usr/lib/sendmail - database_engine = sqlite3 - # 'postgresql', 'mysql', 'mysql_old', 'sqlite3' or 'ado_mssql'. - database_name = - # Or path to database file if using sqlite3. - #/etc/brpt.sqlite is default path if left empty - database_user = - # Not used with sqlite3. - database_password = - # Not used with sqlite3. - database_host = - # Not used with sqlite3. - database_port = - # Set to empty string for default. Not used with sqlite3. - web_debug = True - - [communication] - protocol = xmlrpc/ssl - password = secret - certificate = /etc/bcfg2.crt - key = /etc/bcfg2.key - ca = /etc/bcfg2.crt - - [components] - bcfg2 = https://lucid:6789 - -Create Packages layout (as per :ref:`packages-exampleusage`) in -``/var/lib/bcfg2`` - -.. code-block:: xml - - root@lucid:~# mkdir /var/lib/bcfg2/Packages - root@lucid:~# cat /var/lib/bcfg2/Packages/config.xml - - - ubuntu-lucid - http://us.archive.ubuntu.com/ubuntu - lucid - main - multiverse - restricted - universe - amd64 - i386 - - - -Due to the `Magic Groups`_, we need to modify our Metadata. Let's add -an **ubuntu-lucid** group which inherits the **ubuntu** group already -present in ``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file -should look something like this - -.. _Magic Groups: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages#MagicGroups - -.. code-block:: xml - - - - - - - - - - - - - - - - - - -.. note:: - When editing your xml files by hand, it is useful to occasionally run - `bcfg2-repo-validate` to ensure that your xml validates properly. - -The last thing we need is for the client to have the proper -arch group membership. For this, we will make use of the -:ref:`unsorted-dynamic_groups` capabilities of the Probes plugin. Add -Probes to your plugins line in ``bcfg2.conf`` and create the Probe. - -.. code-block:: sh - - root@lucid:~# grep plugins /etc/bcfg2.conf - plugins = Base,Bundler,Cfg,Metadata,Packages,Probes,Rules,SSHbase - root@lucid:~# mkdir /var/lib/bcfg2/Probes - root@lucid:~# cat /var/lib/bcfg2/Probes/groups - #!/bin/sh - - ARCH=`uname -m` - case "$ARCH" in - "x86_64") - echo "group:amd64" - ;; - "i686") - echo "group:i386" - ;; - esac - -Now we restart the bcfg2-server:: - - root@lucid:~# /etc/init.d/bcfg2-server restart - Stopping Configuration Management Server: * bcfg2-server - Starting Configuration Management Server: * bcfg2-server - root@lucid:~# tail /var/log/syslog - Dec 17 22:36:47 lucid bcfg2-server[17937]: Packages: File read failed; falling back to file download - Dec 17 22:36:47 lucid bcfg2-server[17937]: Packages: Updating http://us.archive.ubuntu.com/ubuntu//dists/lucid/main/binary-amd64/Packages.gz - Dec 17 22:36:54 lucid bcfg2-server[17937]: Packages: Updating http://us.archive.ubuntu.com/ubuntu//dists/lucid/multiverse/binary-amd64/Packages.gz - Dec 17 22:36:55 lucid bcfg2-server[17937]: Packages: Updating http://us.archive.ubuntu.com/ubuntu//dists/lucid/restricted/binary-amd64/Packages.gz - Dec 17 22:36:56 lucid bcfg2-server[17937]: Packages: Updating http://us.archive.ubuntu.com/ubuntu//dists/lucid/universe/binary-amd64/Packages.gz - Dec 17 22:37:27 lucid bcfg2-server[17937]: Failed to read file probed.xml - Dec 17 22:37:27 lucid bcfg2-server[17937]: Loading experimental plugin(s): Packages - Dec 17 22:37:27 lucid bcfg2-server[17937]: NOTE: Interfaces subject to change - Dec 17 22:37:27 lucid bcfg2-server[17937]: service available at https://lucid:6789 - Dec 17 22:37:27 lucid bcfg2-server[17937]: serving bcfg2-server at https://lucid:6789 - Dec 17 22:37:27 lucid bcfg2-server[17937]: serve_forever() [start] - Dec 17 22:37:28 lucid bcfg2-server[17937]: Processed 17 fam events in 0.502 seconds. 0 coalesced - -Start managing packages ------------------------ - -Add a base-packages bundle. Let's see what happens when we just populate -it with the ubuntu-standard package. - -.. code-block:: xml - - root@lucid:~# cat /var/lib/bcfg2/Bundler/base-packages.xml - - - - -You need to reference the bundle from your Metadata. The resulting -profile group might look something like this - -.. code-block:: xml - - - - - - -Now if we run the client in debug mode (-d), we can see what this has -done for us.:: - - root@lucid:~# bcfg2 -vqdn - Running probe groups - Probe groups has result: - amd64 - Loaded tool drivers: - APT Action DebInit POSIX - The following packages are specified in bcfg2: - ubuntu-standard - The following packages are prereqs added by Packages: - adduser debconf hdparm libdevmapper1.02.1 libk5crypto3 libparted1.8-12 libxml2 passwd upstart - apt debianutils info libdns53 libkeyutils1 libpci3 logrotate pciutils usbutils - aptitude dmidecode install-info libelf1 libkrb5-3 libpopt0 lsb-base perl-base wget - at dnsutils iptables libept0 libkrb5support0 libreadline5 lshw popularity-contest zlib1g - base-files dosfstools libacl1 libgcc1 liblwres50 libreadline6 lsof psmisc - base-passwd dpkg libattr1 libgdbm3 libmagic1 libselinux1 ltrace readline-common - bsdmainutils ed libbind9-50 libgeoip1 libmpfr1ldbl libsigc++-2.0-0c2a man-db rsync - bsdutils file libc-bin libgmp3c2 libncurses5 libssl0.9.8 memtest86+ sed - cpio findutils libc6 libgssapi-krb5-2 libncursesw5 libstdc++6 mime-support sensible-utils - cpp ftp libcap2 libisc50 libpam-modules libusb-0.1-4 ncurses-bin strace - cpp-4.4 gcc-4.4-base libcomerr2 libisccc50 libpam-runtime libuuid1 netbase time - cron groff-base libcwidget3 libisccfg50 libpam0g libxapian15 parted tzdata - - Phase: initial - Correct entries: 101 - Incorrect entries: 0 - Total managed entries: 101 - Unmanaged entries: 281 - - - Phase: final - Correct entries: 101 - Incorrect entries: 0 - Total managed entries: 101 - Unmanaged entries: 281 - -As you can see, the Packages plugin has generated the dependencies -required for the ubuntu-standard package for us automatically. The -ultimate goal should be to move all the packages from the **Unmanaged** -entries section to the **Managed** entries section. So, what exactly *are* -those Unmanaged entries?:: - - root@lucid:~# bcfg2 -vqen - Running probe groups - Probe groups has result: - amd64 - Loaded tool drivers: - APT Action DebInit POSIX - - Phase: initial - Correct entries: 101 - Incorrect entries: 0 - Total managed entries: 101 - Unmanaged entries: 281 - - - Phase: final - Correct entries: 101 - Incorrect entries: 0 - Total managed entries: 101 - Unmanaged entries: 281 - Package:apparmor - Package:apparmor-utils - Package:apport - ... - -Now you can go through these and continue adding the packages you want to -your Bundle. Note that ``aptitude why`` is useful when trying to figure -out the reason for a package being installed. Also, deborphan is helpful -for removing leftover dependencies which are no longer needed. After a -while, I ended up with a minimal bundle that looks like this - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -As you can see below, I no longer have any unmanaged packages. :: - - root@lucid:~# bcfg2 -vqen - Running probe groups - Probe groups has result: - amd64 - Loaded tool drivers: - APT Action DebInit POSIX - - Phase: initial - Correct entries: 247 - Incorrect entries: 0 - Total managed entries: 247 - Unmanaged entries: 10 - - - Phase: final - Correct entries: 247 - Incorrect entries: 0 - Total managed entries: 247 - Unmanaged entries: 10 - Service:bcfg2 Service:fam Service:killprocs Service:rc.local Service:single - Service:bcfg2-server Service:grub-common Service:ondemand Service:rsync Service:ssh - -Manage services ---------------- - -Now let's clear up the unmanaged service entries by adding the following -entries to our bundle... - -.. code-block:: xml - - - - - - - - - - - - - - -...and bind them in Rules - -.. code-block:: xml - - root@lucid:~# cat /var/lib/bcfg2/Rules/services.xml - - - - - - - - - - - - - - -Now we run the client and see there are no more unmanaged entries! :: - - root@lucid:~# bcfg2 -vqn - Running probe groups - Probe groups has result: - amd64 - Loaded tool drivers: - APT Action DebInit POSIX - - Phase: initial - Correct entries: 257 - Incorrect entries: 0 - Total managed entries: 257 - Unmanaged entries: 0 - - All entries correct. - - Phase: final - Correct entries: 257 - Incorrect entries: 0 - Total managed entries: 257 - Unmanaged entries: 0 - - All entries correct. - -Dynamic (web) reports -===================== - -See installation instructions at :ref:`server-reports-install` diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index fa8bfd884..4a3830a43 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -27,9 +27,9 @@ contain parsed XML data as the "data" attribute. Usage ===== -Specific property files can be referred to in -templates as metadata.Properties[]. The -data attribute is an LXML element object. (Documented +Specific property files can be referred to in templates as +metadata.Properties[]. The data attribute is an LXML element object. +(Documented `here `_) Currently, no access methods are defined for this data, but as we @@ -39,8 +39,6 @@ as methods. This will simplify templates. Accessing Properties contest from TGenshi ========================================= -Access contents of ``Properties/auth.xml`` - -:: +Access contents of ``Properties/auth.xml`` :: ${metadata.Properties['auth.xml'].data.find('file').find('bcfg2.key').text} -- cgit v1.2.3-1-g7c22