.. -*- mode: rst -*- .. vim: ft=rst .. _appendix-guides-ubuntu: ====== Ubuntu ====== .. note:: This particular how to was done on saucy, 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 Install bcfg2-server -------------------- :: aptitude install bcfg2-server Remove the default configuration preseeded by the ubuntu package:: root@saucy:~# rm -rf /etc/bcfg2* /etc/ssl/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@saucy:~# 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: [saucy] Input the server location (the server listens on a single interface by default) [https://saucy: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 8: Arch : 5 Path where Bcfg2 server private key will be created [/etc/ssl/bcfg2.key]: Path where Bcfg2 server cert will be created [/etc/ssl/bcfg2.crt]: The following questions affect SSL certificate generation. If no data is provided, the default values are used. Country name (2 letter code) for certificate: US State or Province Name (full name) for certificate: Illinois Locality Name (eg, city) for certificate: Argonne Repository created successfuly in /var/lib/bcfg2 Generating a 2048 bit RSA private key ....................................................................................................................+++ ..............................+++ writing new private key to '/etc/ssl/bcfg2.key' ----- Signature ok subject=/C=US/ST=Illinois/L=Argonne/CN=saucy Getting Private key Of course, change responses as necessary. Start the server ================ Before you start the server, you need to fix your network resolution for this host. The short and easy way is to remove the 127.0.1.1 line in ``/etc/hosts`` and move your hostname to the 127.0.0.1 line. :: 127.0.0.1 saucy localhost # The following lines are desirable for IPv6 capable hosts ... .. _Debian Manual: http://www.debian.org/doc/manuals/debian-reference/ch05.en.html#_the_hostname_resolution .. note:: This configuration is not recommended except as a quick hack to get you through this guide. Ideally you'd add a line containing the host's actual IP address. More information on why this is broken can be found in the `Debian Manual`_. You are now ready to start your bcfg2 server for the first time.:: root@saucy:~# /etc/init.d/bcfg2-server start Starting Configuration Management Server: * bcfg2-server root@saucy:~# tail /var/log/syslog Jul 18 17:50:48 saucy bcfg2-server[5872]: Reconnected to syslog Jul 18 17:50:48 saucy bcfg2-server[5872]: bcfg2-server daemonized Jul 18 17:50:48 saucy bcfg2-server[5872]: service available at https://saucy:6789 Jul 18 17:50:48 saucy bcfg2-server[5872]: serving bcfg2-server at https://saucy:6789 Jul 18 17:50:48 saucy bcfg2-server[5872]: serve_forever() [start] Jul 18 17:50:48 saucy bcfg2-server[5872]: Handled 13 events in 0.006s Run bcfg2 to be sure you are able to communicate with the server:: root@saucy:~# bcfg2 -vqn Starting Bcfg2 client run at 1374188552.53 Loaded tool drivers: APT Action DebInit POSIX POSIXUsers Upstart VCS Loaded experimental tool drivers: POSIXUsers Phase: initial Correct entries: 0 Incorrect entries: 0 Total managed entries: 0 Unmanaged entries: 590 Phase: final Correct entries: 0 Incorrect entries: 0 Total managed entries: 0 Unmanaged entries: 590 Finished Bcfg2 client run at 1374188563.26 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 :ref:`server-plugins-generators-packages` plugin ---------------------------------------------------------- Replace Pkgmgr with Packages in the plugins line of ``bcfg2.conf``:: root@saucy:~# cat /etc/bcfg2.conf [server] repository = /var/lib/bcfg2 plugins = Bundler,Cfg,Metadata,Packages,Rules,SSHbase # Uncomment the following to listen on all interfaces #listen_all = true [statistics] sendmailpath = /usr/lib/sendmail #web_debug = False #time_zone = [database] #engine = sqlite3 # 'postgresql', 'mysql', 'mysql_old', 'sqlite3' or 'ado_mssql'. #name = # Or path to database file if using sqlite3. #/bcfg2.sqlite is default path if left empty #user = # Not used with sqlite3. #password = # Not used with sqlite3. #host = # Not used with sqlite3. #port = [reporting] transport = LocalFilesystem [communication] password = secret certificate = /etc/ssl/bcfg2.crt key = /etc/ssl/bcfg2.key ca = /etc/ssl/bcfg2.crt [components] bcfg2 = https://saucy:6789 Create Packages layout (as per :ref:`packages-exampleusage`) in ``/var/lib/bcfg2`` .. code-block:: xml root@saucy:~# mkdir /var/lib/bcfg2/Packages root@saucy:~# cat /var/lib/bcfg2/Packages/packages.conf [global] root@saucy:~# cat /var/lib/bcfg2/Packages/sources.xml main multiverse restricted universe amd64 bcfg2 bcfg2-server main multiverse restricted universe amd64 bcfg2 bcfg2-server main multiverse restricted universe amd64 bcfg2 bcfg2-server main amd64 Above, we have grouped our package sources under **ubuntu-saucy**. We need to add this group to our ``/var/lib/bcfg2/Metadata/groups.xml`` so that our client is able to obtain these sources. .. code-block:: xml .. note:: When editing your xml files by hand, it is useful to occasionally run ``bcfg2-lint -v`` 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-probes-dynamic-groups` capabilities of the Probes plugin. Add Probes to your plugins line in ``bcfg2.conf`` and create the Probe. .. code-block:: sh root@saucy:~# grep plugins /etc/bcfg2.conf plugins = Bundler,Cfg,Metadata,...,Probes root@saucy:~# mkdir /var/lib/bcfg2/Probes root@saucy:~# 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@saucy:~# /etc/init.d/bcfg2-server restart Stopping Configuration Management Server: * bcfg2-server Starting Configuration Management Server: * bcfg2-server root@saucy:~# tail /var/log/syslog Jul 18 18:43:22 saucy bcfg2-server[6215]: Reconnected to syslog Jul 18 18:43:22 saucy bcfg2-server[6215]: bcfg2-server daemonized Jul 18 18:43:22 saucy bcfg2-server[6215]: service available at https://saucy:6789 Jul 18 18:43:22 saucy bcfg2-server[6215]: Failed to read file probed.xml: Error reading file '/var/lib/bcfg2/Probes/probed.xml': failed to load external entity "/var/lib/bcfg2/Probes/probed.xml" Jul 18 18:43:22 saucy bcfg2-server[6215]: serving bcfg2-server at https://saucy:6789 Jul 18 18:43:22 saucy bcfg2-server[6215]: serve_forever() [start] Jul 18 18:43:22 saucy bcfg2-server[6215]: Reloading Packages plugin Jul 18 18:43:22 saucy bcfg2-server[6215]: Handled 15 events in 0.205s .. note:: The error regarding *probed.xml* is non-fatal and just telling you that the file doesn't yet exist. It will be populated once you have run a client with the Probes plugin enabled. Start managing packages ----------------------- Add a base-saucy (or whatever release you happen to be using) bundle. Let's see what happens when we just populate it with the ubuntu-standard package. .. code-block:: xml root@saucy:~# cat /var/lib/bcfg2/Bundler/base-saucy.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@saucy:/var/lib/bcfg2# bcfg2 -vqdn Configured logging: DEBUG to console; DEBUG to syslog {'help': False, 'extra': False, 'ppath': '/var/cache/bcfg2', 'ca': '/etc/ssl/bcfg2.crt', 'rpm_version_fail_action': 'upgrade', 'yum_version_fail_action': 'upgrade', 'retry_delay': '1', 'posix_uid_whitelist': [], 'rpm_erase_flags': ['allmatches'], 'verbose': True, 'certificate': '/etc/ssl/bcfg2.crt', 'paranoid': False, 'rpm_installonly': ['kernel', 'kernel-bigmem', 'kernel-enterprise', 'kernel-smp', 'kernel-modules', 'kernel-debug', 'kernel-unsupported', 'kernel-devel', 'kernel-source', 'kernel-default', 'kernel-largesmp-devel', 'kernel-largesmp', 'kernel-xen', 'gpg-pubkey'], 'cache': None, 'yum24_autodep': True, 'yum_pkg_verify': True, 'probe_timeout': None, 'yum_installed_action': 'install', 'rpm_verify_fail_action': 'reinstall', 'dryrun': True, 'retries': '3', 'apt_install_path': '/usr', 'quick': True, 'password': 'secret', 'yum24_installed_action': 'install', 'kevlar': False, 'max_copies': 1, 'syslog': True, 'decision_list': False, 'configfile': '/etc/bcfg2.conf', 'remove': None, 'server': 'https://saucy:6789', 'encoding': 'UTF-8', 'timeout': 90, 'debug': True, 'yum24_installonly': ['kernel', 'kernel-bigmem', 'kernel-enterprise', 'kernel-smp', 'kernel-modules', 'kernel-debug', 'kernel-unsupported', 'kernel-devel', 'kernel-source', 'kernel-default', 'kernel-largesmp-devel', 'kernel-largesmp', 'kernel-xen', 'gpg-pubkey'], 'yum24_erase_flags': ['allmatches'], 'yum24_pkg_checks': True, 'interactive': False, 'apt_etc_path': '/etc', 'rpm_installed_action': 'install', 'yum24_verify_fail_action': 'reinstall', 'omit_lock_check': False, 'yum24_pkg_verify': True, 'serverCN': None, 'file': None, 'apt_var_path': '/var', 'posix_gid_whitelist': [], 'posix_gid_blacklist': [], 'indep': False, 'decision': 'none', 'service_mode': 'default', 'version': False, 'rpm_pkg_checks': True, 'profile': None, 'yum_pkg_checks': True, 'args': [], 'bundle': [], 'posix_uid_blacklist': [], 'user': 'root', 'key': '/etc/ssl/bcfg2.key', 'command_timeout': None, 'probe_exit': True, 'lockfile': '/var/lock/bcfg2.run', 'yum_verify_fail_action': 'reinstall', 'yum24_version_fail_action': 'upgrade', 'yum_verify_flags': [], 'logging': None, 'rpm_pkg_verify': True, 'bundle_quick': False, 'rpm_verify_flags': [], 'yum24_verify_flags': [], 'skipindep': False, 'skipbundle': [], 'portage_binpkgonly': False, 'drivers': ['APK', 'APT', 'Action', 'Blast', 'Chkconfig', 'DebInit', 'Encap', 'FreeBSDInit', 'FreeBSDPackage', 'IPS', 'MacPorts', 'OpenCSW', 'POSIX', 'POSIXUsers', 'Pacman', 'Portage', 'RPM', 'RPMng', 'RcUpdate', 'SELinux', 'SMF', 'SYSV', 'Systemd', 'Upstart', 'VCS', 'YUM', 'YUM24', 'YUMng', 'launchd']} Starting Bcfg2 client run at 1374191628.88 Running probe groups Running: /tmp/tmpEtgdwo < group:amd64 Probe groups has result: group:amd64 POSIX: Handlers loaded: nonexistent, directory, hardlink, symlink, file, device, permissions Loaded tool drivers: APT Action DebInit POSIX POSIXUsers Upstart VCS Loaded experimental tool drivers: POSIXUsers The following packages are specified in bcfg2: ubuntu-standard The following packages are prereqs added by Packages: accountsservice libdrm2 libusb-1.0-0 adduser libedit2 libustr-1.0-1 apparmor libelf1 libuuid1 apt libexpat1 libwind0-heimdal apt-transport-https libffi6 libx11-6 apt-utils libfribidi0 libx11-data base-files libfuse2 libxau6 base-passwd libgcc1 libxcb1 bash libgck-1-0 libxdmcp6 bash-completion libgcr-3-common libxext6 bsdmainutils libgcr-base-3-1 libxml2 bsdutils libgcrypt11 libxmuu1 busybox-initramfs libgdbm3 libxtables10 busybox-static libgeoip1 locales ca-certificates libglib2.0-0 login command-not-found libglib2.0-data logrotate command-not-found-data libgnutls26 lsb-base coreutils libgpg-error0 lsb-release cpio libgpm2 lshw cron libgssapi-krb5-2 lsof dash libgssapi3-heimdal ltrace dbus libhcrypto4-heimdal makedev debconf libheimbase1-heimdal man-db debconf-i18n libheimntlm0-heimdal manpages debianutils libhx509-5-heimdal memtest86+ diffutils libidn11 mime-support dmidecode libisc92 mlocate dmsetup libisccc90 module-init-tools dnsutils libisccfg90 mount dosfstools libjson-c2 mountall dpkg libjson0 mtr-tiny e2fslibs libk5crypto3 multiarch-support e2fsprogs libkeyutils1 nano ed libklibc ncurses-base file libkmod2 ncurses-bin findutils libkrb5-26-heimdal netbase friendly-recovery libkrb5-3 ntfs-3g ftp libkrb5support0 openssh-client fuse libldap-2.4-2 openssl gcc-4.8-base liblocale-gettext-perl parted geoip-database liblwres90 passwd gettext-base liblzma5 pciutils gnupg libmagic1 perl-base gpgv libmount1 plymouth grep libncurses5 plymouth-theme-ubuntu-text groff-base libncursesw5 popularity-contest gzip libnewt0.52 powermgmt-base hdparm libnfnetlink0 ppp hostname libnih-dbus1 pppconfig ifupdown libnih1 pppoeconf info libnuma1 procps initramfs-tools libp11-kit0 psmisc initramfs-tools-bin libpam-modules python-apt-common initscripts libpam-modules-bin python3 insserv libpam-runtime python3-apt install-info libpam-systemd python3-commandnotfound iproute libpam0g python3-dbus iproute2 libparted0debian1 python3-distupgrade iptables libpcap0.8 python3-gdbm iputils-tracepath libpci3 python3-minimal irqbalance libpcre3 python3-update-manager iso-codes libpipeline1 python3.3 klibc-utils libplymouth2 python3.3-minimal kmod libpng12-0 readline-common krb5-locales libpolkit-gobject-1-0 rsync language-selector-common libpopt0 sed libaccountsservice0 libprocps0 sensible-utils libacl1 libpython3-stdlib sgml-base libapparmor-perl libpython3.3-minimal shared-mime-info libapparmor1 libpython3.3-stdlib strace libapt-inst1.5 libreadline6 systemd-services libapt-pkg4.12 libroken18-heimdal sysv-rc libasn1-8-heimdal librtmp0 sysvinit-utils libasprintf0c2 libsasl2-2 tar libatm1 libsasl2-modules tcpdump libattr1 libselinux1 telnet libaudit-common libsemanage-common time libaudit1 libsemanage1 tzdata libbind9-90 libsepol1 ubuntu-keyring libblkid1 libslang2 ubuntu-release-upgrader-core libbsd0 libsqlite3-0 ucf libbz2-1.0 libss2 udev libc-bin libssl1.0.0 ufw libc6 libstdc++6 update-manager-core libcap-ng0 libsystemd-daemon0 upstart libcap2 libsystemd-login0 usbutils libcomerr2 libtasn1-3 util-linux libcurl3-gnutls libtext-charwidth-perl uuid-runtime libdb5.1 libtext-iconv-perl wget libdbus-1-3 libtext-wrapi18n-perl whiptail libdbus-glib-1-2 libtinfo5 xauth libdevmapper1.02.1 libudev1 xml-core libdns95 libusb-0.1-4 zlib1g Phase: initial Correct entries: 280 Incorrect entries: 0 Total managed entries: 280 Unmanaged entries: 313 Installing entries in the following bundle(s): base-saucy Bundle base-saucy was not modified Phase: final Correct entries: 280 Incorrect entries: 0 Total managed entries: 280 Unmanaged entries: 313 Finished Bcfg2 client run at 1374191642.69 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? :: Starting Bcfg2 client run at 1374192077.76 Running probe groups Probe groups has result: group:amd64 Loaded tool drivers: APT Action DebInit POSIX POSIXUsers Upstart VCS Loaded experimental tool drivers: POSIXUsers Phase: initial Correct entries: 280 Incorrect entries: 0 Total managed entries: 280 Unmanaged entries: 313 Phase: final Correct entries: 280 Incorrect entries: 0 Total managed entries: 280 Unmanaged entries: 313 POSIXGroup:adm POSIXGroup:audio POSIXGroup:backup ... Package:deb:apt-xapian-index Package:deb:aptitude Package:deb:aptitude-common ... 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 Once your ``bcfg2 -vqen`` output no longer shows Package entries, you can move on to the next section. Manage users ------------ The default setting in ``login.defs`` is for system accounts to be UIDs < 1000. We will ignore those accounts for now (you can manage them if you like at a later time). To ignore system UID/GIDs, add the following lines to ``bcfg2.conf`` (we will also ignore the nobody uid and nogroup gid--65534). :: [POSIXUsers] uid_blacklist = 0-999,65534 gid_blacklist = 0-999,65534 If you run the client again with ``bcfg2 -vqen``, you should now see a :ref:`POSIXUser ` entry and :ref:`POSIXGroup ` entry for your user account (assuming this is a fresh install with a regular user). You can manage this user by adding the following to your bundle. .. code-block:: xml adm cdrom dip lpadmin plugdev sambashare sudo Manage services --------------- To clear up the unmanaged service entries, you will need to add the entries to your bundle. Here's an example of what that might look like. .. code-block:: xml Add the literal entries in Rules to bind the Service entries from above. .. code-block:: xml root@saucy:~# cat /var/lib/bcfg2/Rules/services.xml Now we run the client and see there are no more unmanaged entries! :: root@saucy:~# bcfg2 -vqn Starting Bcfg2 client run at 1374271524.83 Running probe groups Probe groups has result: group:amd64 Loaded tool drivers: APT Action DebInit POSIX POSIXUsers Upstart VCS Loaded experimental tool drivers: POSIXUsers Phase: initial Correct entries: 519 Incorrect entries: 0 Total managed entries: 519 Unmanaged entries: 0 Phase: final Correct entries: 519 Incorrect entries: 0 Total managed entries: 519 Unmanaged entries: 0 All entries correct. Finished Bcfg2 client run at 1374271541.56 .. warning:: This basic bundle is created mainly for the purposes of getting you to a completely managed client. It is recommended that you create bundles for appropriate services due to the way bundle updates are managed. Please see :ref:`unsorted-writing_specification` for more details. Upstart ^^^^^^^ Upstart services are defined like this: .. code-block:: xml Some Upstart services require additional parameters, like network-interface and bridge-network-interface: .. code-block:: xml Dynamic (web) reports ===================== See installation instructions at :ref:`appendix-guides-web-reports-install` Next Steps ========== :ref:`getting_started-index-next-steps`