diff options
Diffstat (limited to 'doc/appendix/guides/ubuntu.txt')
-rw-r--r-- | doc/appendix/guides/ubuntu.txt | 479 |
1 files changed, 479 insertions, 0 deletions
diff --git a/doc/appendix/guides/ubuntu.txt b/doc/appendix/guides/ubuntu.txt new file mode 100644 index 000000000..a4790ffed --- /dev/null +++ b/doc/appendix/guides/ubuntu.txt @@ -0,0 +1,479 @@ +.. -*- mode: rst -*- + +.. _guide-ubuntu: + +====== +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 1024 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. + #<repository>/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 + <Sources> + <APTSource> + <Group>ubuntu-lucid</Group> + <URL>http://us.archive.ubuntu.com/ubuntu</URL> + <Version>lucid</Version> + <Component>main</Component> + <Component>multiverse</Component> + <Component>restricted</Component> + <Component>universe</Component> + <Arch>amd64</Arch> + <Arch>i386</Arch> + </APTSource> + </Sources> + +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 + + <Groups version='3.0'> + <Group profile='true' public='true' default='true' name='basic'> + <Group name='ubuntu-lucid'/> + </Group> + <Group name='ubuntu-lucid'> + <Group name='ubuntu'/> + </Group> + <Group name='ubuntu'/> + <Group name='debian'/> + <Group name='freebsd'/> + <Group name='gentoo'/> + <Group name='redhat'/> + <Group name='suse'/> + <Group name='mandrake'/> + <Group name='solaris'/> + </Groups> + +.. 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:`server-plugins-grouping-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 + <Bundle name='base-packages'> + <Package name='ubuntu-standard'/> + </Bundle> + +You need to reference the bundle from your Metadata. The resulting +profile group might look something like this + +.. code-block:: xml + + <Group profile='true' public='true' default='true' name='basic'> + <Bundle name='base-packages'/> + <Group name='ubuntu-lucid'/> + </Group> + +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 + + <Bundle name='base-packages'> + <Package name='bash-completion'/> + <Package name='bcfg2-server'/> + <Package name='debconf-i18n'/> + <Package name='deborphan'/> + <Package name='diffutils'/> + <Package name='e2fsprogs'/> + <Package name='fam'/> + <Package name='grep'/> + <Package name='grub-pc'/> + <Package name='gzip'/> + <Package name='hostname'/> + <Package name='krb5-config'/> + <Package name='krb5-user'/> + <Package name='language-pack-en-base'/> + <Package name='linux-generic'/> + <Package name='linux-headers-generic'/> + <Package name='login'/> + <Package name='manpages'/> + <Package name='mlocate'/> + <Package name='ncurses-base'/> + <Package name='openssh-server'/> + <Package name='python-fam'/> + <Package name='tar'/> + <Package name='ubuntu-minimal'/> + <Package name='ubuntu-standard'/> + <Package name='vim'/> + <Package name='vim-runtime'/> + + <!-- PreDepends --> + <Package name='dash'/> + <Package name='initscripts'/> + <Package name='libdbus-1-3'/> + <Package name='libnih-dbus1'/> + <Package name='lzma'/> + <Package name='mountall'/> + <Package name='sysvinit-utils'/> + <Package name='sysv-rc'/> + + <!-- vim dependencies --> + <Package name='libgpm2'/> + <Package name='libpython2.6'/> + </Bundle> + +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 + + <!-- basic services --> + <Service name='bcfg2'/> + <Service name='bcfg2-server'/> + <Service name='fam'/> + <Service name='grub-common'/> + <Service name='killprocs'/> + <Service name='ondemand'/> + <Service name='rc.local'/> + <Service name='rsync'/> + <Service name='single'/> + <Service name='ssh'/> + + +...and bind them in Rules + +.. code-block:: xml + + root@lucid:~# cat /var/lib/bcfg2/Rules/services.xml + <Rules priority='1'> + <!-- basic services --> + <Service type='deb' status='on' name='bcfg2'/> + <Service type='deb' status='on' name='bcfg2-server'/> + <Service type='deb' status='on' name='fam'/> + <Service type='deb' status='on' name='grub-common'/> + <Service type='deb' status='on' name='killprocs'/> + <Service type='deb' status='on' name='ondemand'/> + <Service type='deb' status='on' name='rc.local'/> + <Service type='deb' status='on' name='rsync'/> + <Service type='deb' status='on' name='single'/> + <Service type='deb' status='on' name='ssh'/> + </Rules> + +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` |