diff options
Diffstat (limited to 'doc/quickstart/ubuntu.txt')
| -rw-r--r-- | doc/quickstart/ubuntu.txt | 517 |
1 files changed, 517 insertions, 0 deletions
diff --git a/doc/quickstart/ubuntu.txt b/doc/quickstart/ubuntu.txt new file mode 100644 index 000000000..7ca873c48 --- /dev/null +++ b/doc/quickstart/ubuntu.txt @@ -0,0 +1,517 @@ +.. -*- mode: rst -*- + +This is a complete getting started guide for Ubuntu +=================================================== + +.. note:: + This particular how to was done on lucid, but should apply to any other `recent`_ version of Ubuntu. + +.. _recent: http://www.ubuntu.com/products/ubuntu/release-cycle + +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 [wiki:Plugins/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 [wiki:DynamicGroups] 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 "amd64" + ;; + "i686") + echo "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 +--------------------- + +First, `aptitude install python-django apache2 libapache2-mod-python`. + * Now we need to create the sqlite database:: + + root@lucid:~# python /usr/share/pyshared/Bcfg2/Server/Reports/manage.py syncdb + Creating table auth_permission + Creating table auth_group + Creating table auth_user + Creating table auth_message + Creating table django_content_type + Creating table django_session + Creating table django_site + Creating table django_admin_log + Creating table reports_client + Creating table reports_ping + Creating table reports_interaction + Creating table reports_reason + Creating table reports_entries + Creating table reports_entries_interactions + Creating table reports_performance + Creating table reports_internaldatabaseversion + + You just installed Django's auth system, which means you don't have any superusers defined. + Would you like to create one now? (yes/no): no + Installing index for auth.Permission model + Installing index for auth.Message model + Installing index for admin.LogEntry model + Installing index for reports.Client model + Installing index for reports.Ping model + Installing index for reports.Interaction model + Installing index for reports.Entries model + Installing index for reports.Entries_interactions model + + * Add DBStats to the plugins line of bcfg2.conf. The resulting [server] section should look something like this:: + + [server] + repository = /var/lib/bcfg2 + plugins = Base,Bundler,Cfg,DBStats,Metadata,Packages,Probes,Rules,SSHbase + + * Start/restart the bcfg2 server + * Run the bcfg2 client in order to populate the statistics database (this run should take a bit longer since you are uploading the client statistics to the database). + * Download the static reports content:: + + root@lucid:~# cd /var/www/ + root@lucid:/var/www# svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2/reports + + * Configure Apache using [wiki:Reports/Dynamic/Installation#ConfigureApache] as a guide + * Copy server/statistics sections of bcfg2.conf to /etc/bcfg2-web.conf (make sure it is world-readable). You should then have something like this:: + + [server] + repository = /var/lib/bcfg2 + plugins = Base,Bundler,Cfg,DBStats,Metadata,Packages,Probes,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 + + * Restart apache and point a browser to your bcfg2 server |