From 6748674b04b321e3cc8aa2dad22a62a1405c4937 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Mon, 28 Dec 2009 00:55:34 +0000 Subject: doc: Add quickstart layout from Thorsten Lockert Signed-off-by: Sol Jerome git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@5634 ce84e21b-d406-0410-9b95-82705330c041 --- doc/quickstart/centos.txt | 557 ++++++++++++++++++++++++++++++++++++++++++++++ doc/quickstart/index.txt | 260 ++++++++++++++++++++++ doc/quickstart/ubuntu.txt | 517 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1334 insertions(+) create mode 100644 doc/quickstart/centos.txt create mode 100644 doc/quickstart/index.txt create mode 100644 doc/quickstart/ubuntu.txt (limited to 'doc/quickstart') diff --git a/doc/quickstart/centos.txt b/doc/quickstart/centos.txt new file mode 100644 index 000000000..b48f0cbb7 --- /dev/null +++ b/doc/quickstart/centos.txt @@ -0,0 +1,557 @@ +.. -*- mode: rst -*- + +This is a complete getting started guide for CentOS +=================================================== + +Install Bcfg2 +------------- + +From Source ++++++++++++ + +Install Prerequisities +###################### + +While you can go about building all these things from source, this how +to will try and meet the dependencies using packages from +rpmforge. The el5 package should be compatible with centos5. :: + + [root@centos ~]# wget http://dag.wieers.com/rpm/packages/rpmforge-release/rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm + --09:51:43-- http://dag.wieers.com/rpm/packages/rpmforge-release/rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm + Resolving dag.wieers.com... 62.213.193.164 + Connecting to dag.wieers.com|62.213.193.164|:80... connected. + HTTP request sent, awaiting response... 302 Found + Location: http://rpmforge.sw.be/redhat/el5/en/x86_64/rpmforge/RPMS/rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm [following] + --09:51:44-- http://rpmforge.sw.be/redhat/el5/en/x86_64/rpmforge/RPMS/rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm + Resolving rpmforge.sw.be... 130.133.35.16 + Connecting to rpmforge.sw.be|130.133.35.16|:80... connected. + HTTP request sent, awaiting response... 200 OK + Length: 16697 (16K) [application/x-rpm] + Saving to: `rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm' + + 100%[====================================================================================================================================================================================================>] 16,697 51.6K/s in 0.3s + + 09:51:45 (51.6 KB/s) - `rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm' saved [16697/16697] + + [root@centos ~]# rpm -Uvh rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm + warning: rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm: Header V3 DSA signature: NOKEY, key ID 6b8d79e6 + Preparing... ########################################### [100%] + 1:rpmforge-release ########################################### [100%] + +Now you can install the rest of the prerequisites:: + + [root@centos ~]# yum install python-genshi python-cheetah python-lxml + Loading "fastestmirror" plugin + Loading mirror speeds from cached hostfile + * rpmforge: ftp-stud.fht-esslingen.de + * base: mirrors.tummy.com + * updates: mirror.unl.edu + * addons: mirror.unl.edu + * extras: mirror.hmc.edu + Setting up Install Process + Parsing package install arguments + Resolving Dependencies + --> Running transaction check + ---> Package python-cheetah.x86_64 0:2.0.1-1.el5.rf set to be updated + ---> Package python-genshi.x86_64 0:0.5.1-2.el5.rf set to be updated + --> Processing Dependency: python-setuptools >= 0.6 for package: python-genshi + ---> Package python-lxml.x86_64 0:1.3.4-1.el5.rf set to be updated + --> Running transaction check + ---> Package python-setuptools.noarch 0:0.6c5-2.el5 set to be updated + --> Finished Dependency Resolution + + Dependencies Resolved + + ============================================================================= + Package Arch Version Repository Size + ============================================================================= + Installing: + python-cheetah x86_64 2.0.1-1.el5.rf rpmforge 424 k + python-genshi x86_64 0.5.1-2.el5.rf rpmforge 521 k + python-lxml x86_64 1.3.4-1.el5.rf rpmforge 1.4 M + Installing for dependencies: + python-setuptools noarch 0.6c5-2.el5 base 479 k + + Transaction Summary + ============================================================================= + Install 4 Package(s) + Update 0 Package(s) + Remove 0 Package(s) + + Total download size: 2.8 M + Is this ok [y/N]: y + Downloading Packages: + (1/4): python-setuptools- 100% |=========================| 479 kB 00:00 + (2/4): python-lxml-1.3.4- 100% |=========================| 1.4 MB 00:09 + (3/4): python-genshi-0.5. 100% |=========================| 521 kB 00:01 + (4/4): python-cheetah-2.0 100% |=========================| 424 kB 00:01 + Running rpm_check_debug + Running Transaction Test + Finished Transaction Test + Transaction Test Succeeded + Running Transaction + Installing: python-lxml ######################### [1/4] + Installing: python-cheetah ######################### [2/4] + Installing: python-setuptools ######################### [3/4] + Installing: python-genshi ######################### [4/4] + + Installed: python-cheetah.x86_64 0:2.0.1-1.el5.rf python-genshi.x86_64 0:0.5.1-2.el5.rf python-lxml.x86_64 0:1.3.4-1.el5.rf + Dependency Installed: python-setuptools.noarch 0:0.6c5-2.el5 + Complete! + +Build Packages from source +########################## + + * After installing subversion, check out a copy of trunk :: + + [root@centos redhat]# svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2 + Install rpm-build + [root@centos redhat]# yum install yum install rpm-build + Loading "fastestmirror" plugin + Loading mirror speeds from cached hostfile + * rpmforge: ftp-stud.fht-esslingen.de + * base: mirrors.tummy.com + * updates: mirror.unl.edu + * addons: mirror.unl.edu + * extras: mirror.hmc.edu + Setting up Install Process + Parsing package install arguments + Resolving Dependencies + --> Running transaction check + ---> Package rpm-build.x86_64 0:4.4.2-48.el5 set to be updated + --> Finished Dependency Resolution + + Dependencies Resolved + + ============================================================================= + Package Arch Version Repository Size + ============================================================================= + Installing: + rpm-build x86_64 4.4.2-48.el5 base 565 k + + Transaction Summary + ============================================================================= + Install 1 Package(s) + Update 0 Package(s) + Remove 0 Package(s) + + Total download size: 565 k + Is this ok [y/N]: y + Downloading Packages: + (1/1): rpm-build-4.4.2-48 100% |=========================| 565 kB 00:00 + Running rpm_check_debug + Running Transaction Test + Finished Transaction Test + Transaction Test Succeeded + Running Transaction + Installing: rpm-build ######################### [1/1] + + Installed: rpm-build.x86_64 0:4.4.2-48.el5 + Complete! + + * Change to the redhat directory of the checked out bcfg2 source:: + + [root@centos ~]# cd bcfg2/redhat/ + [root@centos redhat]# + + * FIXME + +Using prebuilt rpm packages +########################### + + * Install the bcfg2-server and bcfg2 RPMs :: + + [root@centos ~]# rpm -Uvh ftp://fr.rpmfind.net/linux/EPEL/5Server/x86_64/bcfg2-server-0.9.6-1.el5.noarch.rpm ftp://fr.rpmfind.net/linux/EPEL/5Server/x86_64/bcfg2-0.9.6-1.el5.noarch.rpm + Retrieving ftp://fr.rpmfind.net/linux/EPEL/5Server/x86_64/bcfg2-server-0.9.6-1.el5.noarch.rpm + Retrieving ftp://fr.rpmfind.net/linux/EPEL/5Server/x86_64/bcfg2-0.9.6-1.el5.noarch.rpm + warning: /var/tmp/rpm-xfer.xHWepA: Header V3 DSA signature: NOKEY, key ID 217521f6 + Preparing... ########################################### [100%] + 1:bcfg2 ########################################### [ 50%] + 2:bcfg2-server ########################################### [100%] + +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:: + + [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): + Input the server location [https://localhost.localdomain:6789]: 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 1024 bit RSA private key + ........++++++ + .....................................++++++ + writing new private key to '/etc/bcfg2.key' + ----- + You are about to be asked to enter information that will be incorporated + into your certificate request. + What you are about to enter is what is called a Distinguished Name or a DN. + There are quite a few fields but you can leave some blank + For some fields there will be a default value, + If you enter '.', the field will be left blank. + ----- + Country Name (2 letter code) [GB]: + State or Province Name (full name) [Berkshire]: + Locality Name (eg, city) [Newbury]: + Organization Name (eg, company) [My Company Ltd]: + Organizational Unit Name (eg, section) []: + Common Name (eg, your name or your server's hostname) []: + Email Address []: + 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 ~]# /etc/init.d/bcfg2-server start + Starting Configuration Management Server: bcfg2-server [ OK ] + [root@centos ~]# tail /var/log/messages + Mar 3 12:42:26 centos bcfg2-server[24818]: Failed to read file probed.xml + Mar 3 12:42:26 centos bcfg2-server[24818]: Creating new statistics file /var/lib/bcfg2/etc/statistics.xml + Mar 3 12:42:26 centos bcfg2-server[24818]: Processed 16 gamin events in 0.103 seconds. 0 collapsed + Mar 3 12:42:41 centos bcfg2-server[24818]: Bound to port 6789 + +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. + Loaded tool drivers: + Action Chkconfig FreeBSDInit POSIX YUMng + Extra Package flac 1.1.2-28.el5_0.1.x86_64. + Extra Package iputils 20020927-43.el5.x86_64. + Extra Package xorg-x11-fonts-base 7.1-2.1.el5.noarch. + + .... + + Extra Package nash 5.1.19.6-28.x86_64. + Extra Package audiofile 1:0.2.6-5.i386. + Extra Package audiofile 1:0.2.6-5.x86_64. + + Phase: initial + Correct entries: 0 + Incorrect entries: 0 + Total managed entries: 0 + Unmanaged entries: 774 + + + Phase: final + Correct entries: 0 + Incorrect entries: 0 + Total managed entries: 0 + Unmanaged entries: 774 + +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-client ~]# 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 tool drivers: + Action Chkconfig FreeBSDInit POSIX YUMng + Extra Package flac 1.1.2-28.el5_0.1.x86_64. + Extra Package iputils 20020927-43.el5.x86_64. + Extra Package xorg-x11-fonts-base 7.1-2.1.el5.noarch. + + .... + + Extra Package nash 5.1.19.6-28.x86_64. + Extra Package audiofile 1:0.2.6-5.i386. + Extra Package audiofile 1:0.2.6-5.x86_64. + + Phase: initial + Correct entries: 0 + Incorrect entries: 0 + Total managed entries: 0 + Unmanaged entries: 774 + + + Phase: final + Correct entries: 0 + Incorrect entries: 0 + Total managed entries: 0 + Unmanaged entries: 774 + +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. + +Quick and Easy +++++++++++++++ + +First, create a base file containing all installed packages:: + + [root@centos ~]# cat create-base.sh + echo "" > /tmp/centos5.xml + rpm -qa --qf "\n" | sort | uniq >> /tmp/centos5.xml + echo "" >> /tmp/centos5.xml + [root@centos ~]# sh create-base.sh + [root@centos ~]# cp /tmp/centos5.xml /var/lib/bcfg2/Base/centos5.xml + +Add a new group centos5 and centos groups to groups.xml:: + + [root@centos ~]# cat /var/lib/bcfg2/Metadata/groups.xml + + + + + + + + + + + + + + + + + + + +As you can see, the centos5 group inherits the centos group. Now let's +get a Pkgmgr listing based on the installed package versions + +Generate Pkgmgr listing +####################### + +:: + + [root@centos ~]# cat create-pkgmgr.sh + echo "" > /tmp/pkgmgr-centos5.xml + rpm -qa --qf "\n" | sort | uniq >> /tmp/pkgmgr-centos5.xml + echo "" >> /tmp/pkgmgr-centos5.xml + [root@centos ~]# sh create-pkgmgr.sh + [root@centos ~]# cp /tmp/pkgmgr-centos5.xml /var/lib/bcfg2/Pkgmgr/pkgmgr-centos5.xml + +.. note:: + + This how to is being done on 64 bit CentOS. + +Now when we run bcfg2, we see Correct entries:: + + [root@centos ~]# bcfg2 -vqn + no server x509 fingerprint; no server verification performed! + Loaded tool drivers: + Action Chkconfig FreeBSDInit POSIX YUMng + + ... + + Package xml-common failed verification. + Package xulrunner failed verification. + Package xulrunner failed verification. + + Phase: initial + Correct entries: 716 + Incorrect entries: 176 + Total managed entries: 892 + Unmanaged entries: 43 + + In dryrun mode: suppressing entry installation for: + Package:GConf2 Package:evolution Package:gpg-pubkey Package:libgnomecups Package:libxml2 Package:pam_smb + Package:GConf2 Package:evolution Package:gpm Package:libgnomeprint22 Package:libxml2 Package:pango + Package:ImageMagick Package:evolution-data-server Package:gpm Package:libgnomeprint22 Package:mkinitrd Package:pango + Package:ImageMagick Package:evolution-data-server Package:gtk2 Package:libgnomeprintui22 Package:mkinitrd Package:parted + Package:alsa-lib Package:expat Package:gtk2 Package:libgnomeprintui22 Package:nautilus-cd-burner Package:parted + Package:alsa-lib Package:expat Package:gtkhtml3 Package:libgnomeui Package:nautilus-cd-burner Package:pilot-link + Package:aspell Package:fontconfig Package:gtkhtml3 Package:libgnomeui Package:nautilus-sendto Package:pilot-link + Package:aspell Package:fontconfig Package:hal Package:libgpg-error Package:ncurses Package:popt + Package:at-spi Package:gail Package:hal Package:libgpg-error Package:ncurses Package:popt + Package:at-spi Package:gail Package:initscripts Package:libgsf Package:nspluginwrapper Package:readline + Package:atk Package:ghostscript Package:iptables Package:libgsf Package:nspluginwrapper Package:readline + Package:atk Package:ghostscript Package:kernel Package:libgtop2 Package:nss_db Package:sane-backends + Package:audit Package:glib2 Package:krb5-libs Package:libgtop2 Package:nss_db Package:sendmail + Package:avahi Package:glib2 Package:krb5-libs Package:libjpeg Package:nss_ldap Package:setup + Package:avahi Package:gnome-desktop Package:lcms Package:libjpeg Package:nss_ldap Package:shadow-utils + Package:cracklib Package:gnome-desktop Package:lcms Package:libpng Package:numactl Package:sound-juicer + Package:cracklib Package:gnome-keyring Package:libX11 Package:libpng Package:numactl Package:system-config-securitylevel + Package:cryptsetup-luks Package:gnome-keyring Package:libX11 Package:librsvg2 Package:openldap Package:tcp_wrappers + Package:cryptsetup-luks Package:gnome-menus Package:libbonobo Package:librsvg2 Package:openldap Package:tcp_wrappers + Package:cups Package:gnome-menus Package:libbonobo Package:libselinux Package:openssl Package:totem + Package:dbus Package:gnome-panel Package:libbonoboui Package:libselinux Package:openssl Package:totem + Package:dbus Package:gnome-panel Package:libbonoboui Package:libtiff Package:pam Package:wireless-tools + Package:device-mapper Package:gnome-pilot Package:libgcj Package:libtiff Package:pam Package:wireless-tools + Package:device-mapper Package:gnome-pilot Package:libglade2 Package:libuser Package:pam_krb5 Package:xml-common + Package:ecryptfs-utils Package:gnome-utils Package:libglade2 Package:libwmf Package:pam_krb5 Package:xulrunner + Package:ecryptfs-utils Package:gnome-utils Package:libgnome Package:libwmf Package:pam_passwdqc Package:xulrunner + Package:eel2 Package:gnome-vfs2 Package:libgnome Package:libwnck Package:pam_passwdqc + Package:eel2 Package:gnome-vfs2 Package:libgnomecanvas Package:libwnck Package:pam_pkcs11 + Package:esound Package:gnutls Package:libgnomecanvas Package:libxklavier Package:pam_pkcs11 + Package:esound Package:gnutls Package:libgnomecups Package:libxklavier Package:pam_smb + + Phase: final + Correct entries: 716 + Incorrect entries: 176 + Package:GConf2 Package:evolution Package:gpg-pubkey Package:libgnomecups Package:libxml2 Package:pam_smb + Package:GConf2 Package:evolution Package:gpm Package:libgnomeprint22 Package:libxml2 Package:pango + Package:ImageMagick Package:evolution-data-server Package:gpm Package:libgnomeprint22 Package:mkinitrd Package:pango + Package:ImageMagick Package:evolution-data-server Package:gtk2 Package:libgnomeprintui22 Package:mkinitrd Package:parted + Package:alsa-lib Package:expat Package:gtk2 Package:libgnomeprintui22 Package:nautilus-cd-burner Package:parted + Package:alsa-lib Package:expat Package:gtkhtml3 Package:libgnomeui Package:nautilus-cd-burner Package:pilot-link + Package:aspell Package:fontconfig Package:gtkhtml3 Package:libgnomeui Package:nautilus-sendto Package:pilot-link + Package:aspell Package:fontconfig Package:hal Package:libgpg-error Package:ncurses Package:popt + Package:at-spi Package:gail Package:hal Package:libgpg-error Package:ncurses Package:popt + Package:at-spi Package:gail Package:initscripts Package:libgsf Package:nspluginwrapper Package:readline + Package:atk Package:ghostscript Package:iptables Package:libgsf Package:nspluginwrapper Package:readline + Package:atk Package:ghostscript Package:kernel Package:libgtop2 Package:nss_db Package:sane-backends + Package:audit Package:glib2 Package:krb5-libs Package:libgtop2 Package:nss_db Package:sendmail + Package:avahi Package:glib2 Package:krb5-libs Package:libjpeg Package:nss_ldap Package:setup + Package:avahi Package:gnome-desktop Package:lcms Package:libjpeg Package:nss_ldap Package:shadow-utils + Package:cracklib Package:gnome-desktop Package:lcms Package:libpng Package:numactl Package:sound-juicer + Package:cracklib Package:gnome-keyring Package:libX11 Package:libpng Package:numactl Package:system-config-securitylevel + Package:cryptsetup-luks Package:gnome-keyring Package:libX11 Package:librsvg2 Package:openldap Package:tcp_wrappers + Package:cryptsetup-luks Package:gnome-menus Package:libbonobo Package:librsvg2 Package:openldap Package:tcp_wrappers + Package:cups Package:gnome-menus Package:libbonobo Package:libselinux Package:openssl Package:totem + Package:dbus Package:gnome-panel Package:libbonoboui Package:libselinux Package:openssl Package:totem + Package:dbus Package:gnome-panel Package:libbonoboui Package:libtiff Package:pam Package:wireless-tools + Package:device-mapper Package:gnome-pilot Package:libgcj Package:libtiff Package:pam Package:wireless-tools + Package:device-mapper Package:gnome-pilot Package:libglade2 Package:libuser Package:pam_krb5 Package:xml-common + Package:ecryptfs-utils Package:gnome-utils Package:libglade2 Package:libwmf Package:pam_krb5 Package:xulrunner + Package:ecryptfs-utils Package:gnome-utils Package:libgnome Package:libwmf Package:pam_passwdqc Package:xulrunner + Package:eel2 Package:gnome-vfs2 Package:libgnome Package:libwnck Package:pam_passwdqc + Package:eel2 Package:gnome-vfs2 Package:libgnomecanvas Package:libwnck Package:pam_pkcs11 + Package:esound Package:gnutls Package:libgnomecanvas Package:libxklavier Package:pam_pkcs11 + Package:esound Package:gnutls Package:libgnomecups Package:libxklavier Package:pam_smb + Total managed entries: 892 + Unmanaged entries: 43 + +However, you should also see quite a few Incorrect entries as +well. This is due to some multiarch issues with RPM. The main problem +is that when both the 32 bit and 64 bit versions of a particular +package are installed, RPM is unable to verify the mtime on one or the +other (or both) of the packages. This is a problem because the +RPMng/YUMng drivers both attempt to verify installed packages. + +There are a couple ways to get around this problem: + + #. Turn off mtime verification globally (less time-consuming) + #. Remove 32 bit packages (may not be an option) + #. Turn off mtime verification per package instance (time-consuming) + +For now, we will simply turn off mtime verification globally. In order +to do so, you must add nomtime to the verify_flags in the YUMng +section of bcfg2.conf:: + + [root@centos ~]# cat /etc/bcfg2.conf + + [server] + repository = /var/lib/bcfg2 + structures = Bundler,Base + generators = SSHbase,Cfg,Pkgmgr,Rules + # Uncomment to use the DBStats plugin (0.9.6pre2 and later) + #plugins = DBStats + + [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 = N41lMNeW + key = /etc/bcfg2.key + # fingerprint of server (from bcfg2-admin fingerprint) + #fingerprint = [server fingerprint] + + [components] + bcfg2 = https://centos:6789 + + [YUMng] + verify_flags = nomtime + +Running the client again yields a much more manageable result:: + + [root@centos ~]# bcfg2 -vqn + Loaded tool drivers: + Action Chkconfig FreeBSDInit POSIX YUMng + WARNING: Package bcfg2 0.9.6-1.el5.noarch requires GPG Public key with ID 119cc036217521f6 + Disabling signature check. + WARNING: Package bcfg2-server 0.9.6-1.el5.noarch requires GPG Public key with ID 119cc036217521f6 + Disabling signature check. + Package cups failed verification. + WARNING: Multiple instances of package gpg-pubkey are installed. + Extra InstallOnlyPackage gpg-pubkey e42d547b-3960bdf1.None. + Extra InstallOnlyPackage gpg-pubkey 6b8d79e6-3f49313d.None. + Extra InstallOnlyPackage gpg-pubkey 1aa78495-3eb24301.None. + Package gpg-pubkey failed verification. + Package iptables failed verification. + WARNING: Multiple instances of package kernel are installed. + Extra InstallOnlyPackage kernel 2.6.18-92.1.22.el5.x86_64. + Package kernel failed verification. + Package nautilus-sendto failed verification. + Package pam failed verification. + Package pam failed verification. + Package xulrunner failed verification. + Package xulrunner failed verification. + + Phase: initial + Correct entries: 883 + Incorrect entries: 9 + Total managed entries: 892 + Unmanaged entries: 43 + + In dryrun mode: suppressing entry installation for: + Package:cups Package:gpg-pubkey Package:iptables Package:kernel Package:nautilus-sendto Package:pam Package:pam Package:xulrunner Package:xulrunner + + Phase: final + Correct entries: 883 + Incorrect entries: 9 + Package:cups Package:gpg-pubkey Package:iptables Package:kernel Package:nautilus-sendto Package:pam Package:pam Package:xulrunner Package:xulrunner + Total managed entries: 892 + Unmanaged entries: 43 + +Generate service listing +######################## + +DBStats +------- + +Setting up Django ++++++++++++++++++ diff --git a/doc/quickstart/index.txt b/doc/quickstart/index.txt new file mode 100644 index 000000000..64a8faae6 --- /dev/null +++ b/doc/quickstart/index.txt @@ -0,0 +1,260 @@ +.. -*- mode: rst -*- + +========== +Quickstart +========== + +The steps below should get you from just thinking about a +configuration management system to an operational installation of +:ref:`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 + +For distribution-specific guides, choose one of the following: + + * :doc:`centos` + * :doc:`ubuntu` + +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. Our :ref:`Download` has +both source and packages for common environments, while our +:ref:`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). Detailed installation instructions can be found on the +:ref:`Install` page. + +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 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. 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 PostInstall RPM + + 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 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. + +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 + 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 PostInstall RPM + 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:`Bundler` 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://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Bundler/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: + + * 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:: + :hidden: + + centos + ubuntu 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. + #/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 + + + 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 [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 + + + + +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 +--------------------- + +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. + #/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 -- cgit v1.2.3-1-g7c22