diff options
Diffstat (limited to 'doc')
38 files changed, 1032 insertions, 436 deletions
diff --git a/doc/appendix/files/mysql.txt b/doc/appendix/files/mysql.txt index 81104ec17..5adf2e27f 100644 --- a/doc/appendix/files/mysql.txt +++ b/doc/appendix/files/mysql.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _appendix-files-mysql: @@ -17,7 +18,7 @@ I added a new bundle: <Bundle name="mysql-server" version="3.0"> <Path name="/root/bcfg2-install/mysql/users.sh"/> <Path name="/root/bcfg2-install/mysql/users.sql"/> - <PostInstall name="/root/bcfg2-install/mysql/users.sh"/> + <Action name="users.sh"/> <Package name="mysql-server-4.1"/> <Service name="mysql"/> </Bundle> diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt index febdf5769..19354b709 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -231,10 +231,11 @@ file should look something like this When editing your xml files by hand, it is useful to occasionally run `bcfg2-lint` to ensure that your xml validates properly. -The final thing we need is for the client to have the proper -arch group membership. For this, we will make use of the -:ref:`unsorted-dynamic_groups` capabilities of the Probes plugin. Add -Probes to your plugins line in ``bcfg2.conf`` and create the Probe.:: +The final thing we need is for the client to have the proper arch +group membership. For this, we will make use of the +:ref:`server-plugins-probes-dynamic-groups` capabilities of the Probes +plugin. Add Probes to your plugins line in ``bcfg2.conf`` and create +the Probe.:: [root@centos ~]# grep plugins /etc/bcfg2.conf plugins = Base,Bundler,Cfg,...,Probes diff --git a/doc/appendix/guides/fedora.txt b/doc/appendix/guides/fedora.txt index 1e49084ef..f89daaf0b 100644 --- a/doc/appendix/guides/fedora.txt +++ b/doc/appendix/guides/fedora.txt @@ -256,10 +256,11 @@ file should look something like this Add a probe +++++++++++ -The next step for the client will be to have the proper -arch group membership. For this, we will make use of the -:ref:`unsorted-dynamic_groups` capabilities of the Probes plugin. Add -**Probes** to your plugins line in ``bcfg2.conf`` and create the Probe: +The next step for the client will be 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 diff --git a/doc/appendix/guides/ubuntu.txt b/doc/appendix/guides/ubuntu.txt index 5a67d0a37..9bf851632 100644 --- a/doc/appendix/guides/ubuntu.txt +++ b/doc/appendix/guides/ubuntu.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _appendix-guides-ubuntu: @@ -8,7 +9,7 @@ Ubuntu .. note:: - This particular how to was done on lucid, but should apply to any + This particular how to was done on saucy, but should apply to any other `stable`__ version of Ubuntu. __ ubuntu-releases_ @@ -23,11 +24,6 @@ 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 -------------------- :: @@ -36,7 +32,7 @@ Install bcfg2-server Remove the default configuration preseeded by the ubuntu package:: - root@lucid:~# rm -rf /etc/bcfg2* /var/lib/bcfg2 + root@saucy:~# rm -rf /etc/bcfg2* /etc/ssl/bcfg2* /var/lib/bcfg2 Initialize your repository ========================== @@ -45,63 +41,95 @@ 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]: + 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: [lucid] - Input the server location [https://lucid:6789]: + 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 + 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/bcfg2.key' + ....................................................................................................................+++ + ..............................+++ + writing new private key to '/etc/ssl/bcfg2.key' ----- Signature ok - subject=/C=US/ST=Illinois/L=Argonne/CN=lucid + subject=/C=US/ST=Illinois/L=Argonne/CN=saucy Getting Private key - Repository created successfuly in /var/lib/bcfg2 - 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@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 + 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@lucid:~# bcfg2 -vqn + root@saucy:~# bcfg2 -vqn + Starting Bcfg2 client run at 1374188552.53 Loaded tool drivers: - APT Action DebInit POSIX - + 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: 382 - - + Unmanaged entries: 590 Phase: final Correct entries: 0 Incorrect entries: 0 Total managed entries: 0 - Unmanaged entries: 382 + Unmanaged entries: 590 + Finished Bcfg2 client run at 1374188563.26 Bring your first machine under Bcfg2 control ============================================ @@ -114,92 +142,101 @@ Setup the :ref:`server-plugins-generators-packages` plugin Replace Pkgmgr with Packages in the plugins line of ``bcfg2.conf``:: - root@lucid:~# cat /etc/bcfg2.conf + root@saucy:~# cat /etc/bcfg2.conf [server] repository = /var/lib/bcfg2 - plugins = SSHbase,Cfg,Packages,Rules,Metadata,Base,Bundler + 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 + #engine = sqlite3 # 'postgresql', 'mysql', 'mysql_old', 'sqlite3' or 'ado_mssql'. - name = + #name = # Or path to database file if using sqlite3. - #<repository>/etc/brpt.sqlite is default path if left empty - user = + #<repository>/bcfg2.sqlite is default path if left empty + #user = # Not used with sqlite3. - password = + #password = # Not used with sqlite3. - host = + #host = # Not used with sqlite3. - port = + #port = + + [reporting] + transport = LocalFilesystem [communication] protocol = xmlrpc/ssl password = secret - certificate = /etc/bcfg2.crt - key = /etc/bcfg2.key - ca = /etc/bcfg2.crt + certificate = /etc/ssl/bcfg2.crt + key = /etc/ssl/bcfg2.key + ca = /etc/ssl/bcfg2.crt [components] - bcfg2 = https://lucid:6789 + bcfg2 = https://saucy: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/packages.conf + root@saucy:~# mkdir /var/lib/bcfg2/Packages + root@saucy:~# cat /var/lib/bcfg2/Packages/packages.conf [global] - root@lucid:~# cat /var/lib/bcfg2/Packages/sources.xml + root@saucy:~# cat /var/lib/bcfg2/Packages/sources.xml <Sources> - <Group name="ubuntu-lucid"> - <Source type="apt" url="http://archive.ubuntu.com/ubuntu" version="lucid"> + <Group name="ubuntu-saucy"> + <Source type="apt" debsrc="true" recommended="true" url="http://archive.ubuntu.com/ubuntu" version="saucy"> <Component>main</Component> <Component>multiverse</Component> <Component>restricted</Component> <Component>universe</Component> <Arch>amd64</Arch> + <Blacklist>bcfg2</Blacklist> + <Blacklist>bcfg2-server</Blacklist> </Source> - <Source type="apt" url="http://archive.ubuntu.com/ubuntu" version="lucid-updates"> + <Source type="apt" debsrc="true" recommended="true" url="http://archive.ubuntu.com/ubuntu" version="saucy-updates"> <Component>main</Component> <Component>multiverse</Component> <Component>restricted</Component> <Component>universe</Component> <Arch>amd64</Arch> + <Blacklist>bcfg2</Blacklist> + <Blacklist>bcfg2-server</Blacklist> </Source> - <Source type="apt" url="http://security.ubuntu.com/ubuntu" version="lucid-security"> + <Source type="apt" debsrc="true" recommended="true" url="http://security.ubuntu.com/ubuntu" version="saucy-security"> <Component>main</Component> <Component>multiverse</Component> <Component>restricted</Component> <Component>universe</Component> <Arch>amd64</Arch> + <Blacklist>bcfg2</Blacklist> + <Blacklist>bcfg2-server</Blacklist> + </Source> + <Source type="apt" debsrc="true" recommended="true" url="http://ppa.launchpad.net/bcfg2/ppa/ubuntu" version="saucy"> + <Component>main</Component> + <Arch>amd64</Arch> </Source> </Group> </Sources> -Due to the :ref:`server-plugins-generators-packages-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 - -.. note:: - - The reason we are creating a release-specific group in this case is - that the APTSource above is specific to the lucid release of ubuntu. - That is, it should not apply to other releases (hardy, maverick, etc). +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 <Groups version='3.0'> <Group profile='true' public='true' default='true' name='basic'> - <Group name='ubuntu-lucid'/> + <Group name='ubuntu-saucy'/> </Group> - <Group name='ubuntu-lucid'> + <Group name='ubuntu-saucy'> <Group name='ubuntu'/> </Group> <Group name='ubuntu'/> @@ -214,22 +251,23 @@ something like this .. note:: When editing your xml files by hand, it is useful to occasionally run - `bcfg2-lint` to ensure that your xml validates properly. + ``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:`unsorted-dynamic_groups` capabilities of the Probes plugin. Add -Probes to your plugins line in ``bcfg2.conf`` and create the Probe. +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@lucid:~# grep plugins /etc/bcfg2.conf - plugins = Base,Bundler,Cfg,...,Probes - root@lucid:~# mkdir /var/lib/bcfg2/Probes - root@lucid:~# cat /var/lib/bcfg2/Probes/groups + 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` + ARCH=$(uname -m) case "$ARCH" in "x86_64") echo "group:amd64" @@ -241,33 +279,36 @@ Probes to your plugins line in ``bcfg2.conf`` and create the Probe. Now we restart the bcfg2-server:: - root@lucid:~# /etc/init.d/bcfg2-server restart + root@saucy:~# /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 + 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-packages bundle. Let's see what happens when we just populate -it with the ubuntu-standard package. +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@lucid:~# cat /var/lib/bcfg2/Bundler/base-packages.xml - <Bundle name='base-packages'> + root@saucy:~# cat /var/lib/bcfg2/Bundler/base-saucy.xml + <Bundle name='base-saucy'> <Package name='ubuntu-standard'/> </Bundle> @@ -277,218 +318,473 @@ 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'/> + <Bundle name='base-saucy'/> + <Group name='ubuntu-saucy'/> </Group> Now if we run the client in debug mode (-d), we can see what this has done for us.:: - root@lucid:~# bcfg2 -vqdn + 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', 'servicemode': '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: - amd64 + group:amd64 + + POSIX: Handlers loaded: nonexistent, directory, hardlink, symlink, file, device, permissions Loaded tool drivers: - APT Action DebInit POSIX + 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: - 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 - + 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: 101 + Correct entries: 280 Incorrect entries: 0 - Total managed entries: 101 - Unmanaged entries: 281 - - + 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: 101 + Correct entries: 280 Incorrect entries: 0 - Total managed entries: 101 - Unmanaged entries: 281 + 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?:: +those Unmanaged entries? + +:: - root@lucid:~# bcfg2 -vqen + Starting Bcfg2 client run at 1374192077.76 Running probe groups Probe groups has result: - amd64 - Loaded tool drivers: - APT Action DebInit POSIX + group:amd64 + Loaded tool drivers: + APT Action DebInit POSIX POSIXUsers Upstart VCS + Loaded experimental tool drivers: + POSIXUsers Phase: initial - Correct entries: 101 + Correct entries: 280 Incorrect entries: 0 - Total managed entries: 101 - Unmanaged entries: 281 - - + Total managed entries: 280 + Unmanaged entries: 313 Phase: final - Correct entries: 101 + Correct entries: 280 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 + 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 - <Bundle name='base-packages'> - <Package name='bash-completion'/> + <Bundle name='base-saucy'> + <!-- packages --> <Package name='bcfg2-server'/> - <Package name='debconf-i18n'/> + <!-- or dependencies --> + <Package name='python-pyinotify'/> + <Package name='ttf-dejavu-core'/> + <Package name='bind9-host'/> + <Package name='crda'/> <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='language-pack-en'/> <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='systemd-shim'/> + <Package name='tasksel'/> <Package name='ubuntu-minimal'/> <Package name='ubuntu-standard'/> + <!-- or dependencies --> + <Package name='python3-gi'/> + <Package name='wamerican'/> + <Package name='wbritish'/> <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. :: +Once your ``bcfg2 -vqen`` output no longer shows Package entries, you +can move on to the next section. - root@lucid:~# bcfg2 -vqen - Running probe groups - Probe groups has result: - amd64 - Loaded tool drivers: - APT Action DebInit POSIX +Manage users +------------ - Phase: initial - Correct entries: 247 - Incorrect entries: 0 - Total managed entries: 247 - Unmanaged entries: 10 +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). - 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 +:: + + [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 <server-plugins-generators-rules-posixuser-tag>` entry +and :ref:`POSIXGroup <server-plugins-generators-rules-posixgroup-tag>` +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 + + <BoundPOSIXUser name='username' uid='1000' gecos="Your Name"> + <MemberOf>adm</MemberOf> + <MemberOf>cdrom</MemberOf> + <MemberOf>dip</MemberOf> + <MemberOf>lpadmin</MemberOf> + <MemberOf>plugdev</MemberOf> + <MemberOf>sambashare</MemberOf> + <MemberOf>sudo</MemberOf> + </BoundPOSIXUser> Manage services --------------- -Now let's clear up the unmanaged service entries by adding the following -entries to our bundle... +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 - <!-- basic services --> + <!-- services --> <Service name='bcfg2'/> + <Service name='bcfg2-report-collector'/> <Service name='bcfg2-server'/> - <Service name='fam'/> + <Service name='bootmisc.sh'/> + <Service name='checkfs.sh'/> + <Service name='checkroot-bootclean.sh'/> + <Service name='checkroot.sh'/> + <Service name='console'/> + <Service name='console-font'/> + <Service name='console-setup'/> + <Service name='container-detect'/> + <Service name='control-alt-delete'/> + <Service name='cron'/> + <Service name='dbus'/> + <Service name='dmesg'/> + <Service name='dns-clean'/> + <Service name='failsafe'/> + <Service name='flush-early-job-log'/> + <Service name='friendly-recovery'/> <Service name='grub-common'/> + <Service name='hostname'/> + <Service name='hwclock'/> + <Service name='hwclock-save'/> + <Service name='irqbalance'/> <Service name='killprocs'/> + <Service name='kmod'/> + <Service name='mountall'/> + <Service name='mountall.sh'/> + <Service name='mountall-bootclean.sh'/> + <Service name='mountall-net'/> + <Service name='mountall-reboot'/> + <Service name='mountall-shell'/> + <Service name='mountdevsubfs.sh'/> + <Service name='mounted-debugfs'/> + <Service name='mounted-dev'/> + <Service name='mounted-proc'/> + <Service name='mounted-run'/> + <Service name='mounted-tmp'/> + <Service name='mounted-var'/> + <Service name='mountkernfs.sh'/> + <Service name='mountnfs-bootclean.sh'/> + <Service name='mountnfs.sh'/> + <Service name='mtab.sh'/> + <Service name='network-interface'/> + <Service name='network-interface-container'/> + <Service name='network-interface-security'/> + <Service name='networking'/> <Service name='ondemand'/> + <Service name='passwd'/> + <Service name='plymouth'/> + <Service name='plymouth-log'/> + <Service name='plymouth-ready'/> + <Service name='plymouth-splash'/> + <Service name='plymouth-stop'/> + <Service name='plymouth-upstart-bridge'/> + <Service name='pppd-dns'/> + <Service name='procps'/> + <Service name='rc'/> <Service name='rc.local'/> + <Service name='rc-sysinit'/> + <Service name='rcS'/> + <Service name='resolvconf'/> <Service name='rsync'/> + <Service name='rsyslog'/> + <Service name='setvtrgb'/> + <Service name='shutdown'/> <Service name='single'/> - <Service name='ssh'/> - - -...and bind them in Rules + <Service name='startpar-bridge'/> + <Service name='sudo'/> + <Service name='systemd-logind'/> + <Service name='tty1'/> + <Service name='tty2'/> + <Service name='tty3'/> + <Service name='tty4'/> + <Service name='tty5'/> + <Service name='tty6'/> + <Service name='udev'/> + <Service name='udev-fallback-graphics'/> + <Service name='udev-finish'/> + <Service name='udevmonitor'/> + <Service name='udevtrigger'/> + <Service name='ufw'/> + <Service name='upstart-file-bridge'/> + <Service name='upstart-socket-bridge'/> + <Service name='upstart-udev-bridge'/> + <Service name='ureadahead'/> + <Service name='ureadahead-other'/> + <Service name='wait-for-state'/> + +Add the literal entries in Rules to bind the Service entries from above. .. code-block:: xml - root@lucid:~# cat /var/lib/bcfg2/Rules/services.xml + root@saucy:~# 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'/> + <!-- sysv services --> + <Service name='bcfg2' type='deb' status='on'/> + <Service name='bcfg2-server' type='deb' status='on'/> + <Service name='dns-clean' type='deb' status='on'/> + <Service name='grub-common' type='deb' status='on'/> + <Service name='sudo' type='deb' status='on'/> + + <Service name='killprocs' type='deb' bootstatus='on' status='ignore'/> + <Service name='ondemand' type='deb' bootstatus='on' status='ignore'/> + <Service name='pppd-dns' type='deb' bootstatus='on' status='ignore'/> + <Service name='rc.local' type='deb' bootstatus='on' status='ignore'/> + <Service name='rsync' type='deb' bootstatus='on' status='ignore'/> + <Service name='single' type='deb' bootstatus='on' status='ignore'/> + + <Service name='bcfg2-report-collector' type='deb' status='off'/> + + <!-- upstart services --> + <Service name='bootmisc.sh' type='upstart' status='on'/> + <Service name='checkfs.sh' type='upstart' status='on'/> + <Service name='checkroot-bootclean.sh' type='upstart' status='on'/> + <Service name='checkroot.sh' type='upstart' status='on'/> + <Service name='cron' type='upstart' status='on'/> + <Service name='dbus' type='upstart' status='on'/> + <Service name='mountall.sh' type='upstart' status='on'/> + <Service name='mountall-bootclean.sh' type='upstart' status='on'/> + <Service name='mountdevsubfs.sh' type='upstart' status='on'/> + <Service name='mountkernfs.sh' type='upstart' status='on'/> + <Service name='mountnfs-bootclean.sh' type='upstart' status='on'/> + <Service name='mountnfs.sh' type='upstart' status='on'/> + <Service name='mtab.sh' type='upstart' status='on'/> + <Service name='network-interface' type='upstart' status='on' parameters='INTERFACE=eth0'/> + <Service name='network-interface-security' type='upstart' status='on' parameters='JOB=network-interface/eth0'/> + <Service name='networking' type='upstart' status='on'/> + <Service name='plymouth-ready' type='upstart' status='ignore'/> + <Service name='resolvconf' type='upstart' status='on'/> + <Service name='rsyslog' type='upstart' status='on'/> + <Service name='startpar-bridge' type='upstart' status='ignore'/> + <Service name='systemd-logind' type='upstart' status='on'/> + <Service name='tty1' type='upstart' status='on'/> + <Service name='tty2' type='upstart' status='on'/> + <Service name='tty3' type='upstart' status='on'/> + <Service name='tty4' type='upstart' status='on'/> + <Service name='tty5' type='upstart' status='on'/> + <Service name='tty6' type='upstart' status='on'/> + <Service name='udev' type='upstart' status='on'/> + <Service name='ufw' type='upstart' status='on'/> + <Service name='upstart-file-bridge' type='upstart' status='on'/> + <Service name='upstart-socket-bridge' type='upstart' status='on'/> + <Service name='upstart-udev-bridge' type='upstart' status='on'/> + <Service name='wait-for-state' type='upstart' status='ignore'/> + + <Service name='console' type='upstart' status='off'/> + <Service name='console-font' type='upstart' status='off'/> + <Service name='console-setup' type='upstart' status='off'/> + <Service name='container-detect' type='upstart' status='off'/> + <Service name='control-alt-delete' type='upstart' status='off'/> + <Service name='dmesg' type='upstart' status='off'/> + <Service name='failsafe' type='upstart' status='off'/> + <Service name='flush-early-job-log' type='upstart' status='off'/> + <Service name='friendly-recovery' type='upstart' status='off'/> + <Service name='hostname' type='upstart' status='off'/> + <Service name='hwclock' type='upstart' status='off'/> + <Service name='hwclock-save' type='upstart' status='off'/> + <Service name='irqbalance' type='upstart' status='off'/> + <Service name='kmod' type='upstart' status='off'/> + <Service name='mountall' type='upstart' status='off'/> + <Service name='mountall-net' type='upstart' status='off'/> + <Service name='mountall-reboot' type='upstart' status='off'/> + <Service name='mountall-shell' type='upstart' status='off'/> + <Service name='mounted-debugfs' type='upstart' status='off'/> + <Service name='mounted-dev' type='upstart' status='off'/> + <Service name='mounted-proc' type='upstart' status='off'/> + <Service name='mounted-run' type='upstart' status='off'/> + <Service name='mounted-tmp' type='upstart' status='off'/> + <Service name='mounted-var' type='upstart' status='off'/> + <Service name='network-interface-container' type='upstart' status='off'/> + <Service name='passwd' type='upstart' status='off'/> + <Service name='plymouth' type='upstart' status='off'/> + <Service name='plymouth-log' type='upstart' status='off'/> + <Service name='plymouth-splash' type='upstart' status='off'/> + <Service name='plymouth-stop' type='upstart' status='off'/> + <Service name='plymouth-upstart-bridge' type='upstart' status='off'/> + <Service name='procps' type='upstart' status='off'/> + <Service name='rc' type='upstart' status='off'/> + <Service name='rc-sysinit' type='upstart' status='off'/> + <Service name='rcS' type='upstart' status='off'/> + <Service name='setvtrgb' type='upstart' status='off'/> + <Service name='shutdown' type='upstart' status='off'/> + <Service name='udev-fallback-graphics' type='upstart' status='off'/> + <Service name='udev-finish' type='upstart' status='off'/> + <Service name='udevmonitor' type='upstart' status='off'/> + <Service name='udevtrigger' type='upstart' status='off'/> + <Service name='ureadahead' type='upstart' status='off'/> + <Service name='ureadahead-other' type='upstart' status='off'/> </Rules> -Now we run the client and see there are no more unmanaged entries! :: +Now we run the client and see there are no more unmanaged entries! - root@lucid:~# bcfg2 -vqn +:: + + root@saucy:~# bcfg2 -vqn + Starting Bcfg2 client run at 1374271524.83 Running probe groups Probe groups has result: - amd64 - Loaded tool drivers: - APT Action DebInit POSIX + group:amd64 + Loaded tool drivers: + APT Action DebInit POSIX POSIXUsers Upstart VCS + Loaded experimental tool drivers: + POSIXUsers Phase: initial - Correct entries: 257 + Correct entries: 519 Incorrect entries: 0 - Total managed entries: 257 + Total managed entries: 519 Unmanaged entries: 0 - - All entries correct. - Phase: final - Correct entries: 257 + Correct entries: 519 Incorrect entries: 0 - Total managed entries: 257 + Total managed entries: 519 Unmanaged entries: 0 - All entries correct. + Finished Bcfg2 client run at 1374271541.56 .. warning:: diff --git a/doc/appendix/tools.txt b/doc/appendix/tools.txt index 1d7a8dd90..92bde683b 100644 --- a/doc/appendix/tools.txt +++ b/doc/appendix/tools.txt @@ -11,4 +11,4 @@ can help you to maintain your Bcfg2 configuration, to make the initial setup easier, or to do some other tasks. -http://trac.mcs.anl.gov/projects/bcfg2/browser/tools +https://github.com/Bcfg2/bcfg2/tree/maint/tools diff --git a/doc/client/tools/actions.txt b/doc/client/tools/actions.txt index 81486ecd1..e5fdb1f39 100644 --- a/doc/client/tools/actions.txt +++ b/doc/client/tools/actions.txt @@ -31,10 +31,11 @@ central reporting of action failure is desired, set this attribute to 'check'. Also note that Action entries included in Base will not be executed. -Actions cannot be completely defined inside of a bundle; they are a bound -entry, much like Packages, Services or Paths. The Rules plugin can bind -these entries. For example to include the above action in a bundle, -first the Action entry must be included in the bundle: +Actions may be completely defined inside of a bundle with the use of +:ref:`server-configurationentries`, much like Packages, Services or Paths. +The Rules plugin can also bind these entries. For example to include the +above action in a bundle, first the Action entry must be included in the +bundle: .. code-block:: xml @@ -70,3 +71,18 @@ requires this key. <Action timing='post' name='apt-key-update' command='apt-key adv --recv-keys --keyserver hkp://pgp.mit.edu 0C5A2783' when='modified' status='check'/> </Group> </Rules> + +Example BoundAction (add RPM GPG keys) +====================================== + +This example will add the RPM-GPG-KEY-redhat-release key to the RPM +GPG keyring **before** Package entries are handled on the client run. + +.. code-block:: xml + + <Bundle name="rpm-gpg-keys"> + <Group name='rhel'> + <Path name="/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release"/> + <BoundAction timing="pre" name="install rpm key" command="rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release" when="modified" status="check"/> + </Group> + </Bundle> diff --git a/doc/client/tools/augeas.txt b/doc/client/tools/augeas.txt new file mode 100644 index 000000000..6fed5f5ce --- /dev/null +++ b/doc/client/tools/augeas.txt @@ -0,0 +1,95 @@ +.. -*- mode: rst -*- + +.. _client-tools-augeas: + +======== + Augeas +======== + +The Augeas tool provides a way to use `Augeas +<http://www.augeas.net>`_ to edit files that may not be completely +managed. + +In the simplest case, you simply tell Augeas which path to edit, and +give it a sequence of commands: + +.. code-block:: xml + + <Path type="augeas" name="/etc/hosts" owner="root" group="root" + mode="0644"> + <Set path="01/ipaddr" value="192.168.0.1"/> + <Set path="01/canonical" value="pigiron.example.com"/> + <Set path="01/alias[1]" value="pigiron"/> + <Set path="01/alias[2]" value="piggy"/> + </Path> + +The commands are run in document order. There's no need to do an +explicit ``save`` at the end. + +These commands will be run if any of the paths do not already +have the given setting. In other words, if any command has not +already been run, they will all be run. + +So, if the first host already has all of the specified settings, then +that Path will verify successfully and nothing will be changed. But +suppose the first host looks like this:: + + 192.168.0.1 pigiron.example.com pigiron + +All that is missing is the second alias, ``piggy``. The entire Augeas +script will be run in this case. It's important, then, to ensure that +all commands you use are idempotent. (For instance, the ``Move`` and +``Insert`` commands are unlikely to be useful.) + +The Augeas paths are all relative to ``/files/etc/hosts``. + +The Augeas tool understands a subset of ``augtool`` commands. Valid +tags are: ``Remove``, ``Move``, ``Set``, ``Clear``, ``SetMulti``, and +``Insert``. Refer to the official Augeas docs or the `Schema`_ below +for details on the commands. + +The Augeas tool also supports one additional directive, ``Initial``, +for setting initial file content when a file does not exist. For +instance, the ``Xml`` lens fails to parse a file that does not exist, +and, as a result, you cannot add content to it. You can use +``Initial`` to circumvent this issue: + +.. code-block:: xml + + <Path type="augeas" name="/etc/test.xml" lens="Xml" + owner="root" group="root" mode="0640"> + <Initial><Test/></Initial> + <Set path="Test/#text" value="text content"/> + </Path> + +Editing files outside the default load path +=========================================== + +If you're using Augeas to edit files outside of its default load path, +you must manually specify the lens. For instance: + +.. code-block:: xml + + <Path type="augeas" name="/opt/jenkins/home/config.xml" lens="Xml" + owner="jenkins" group="jenkins" mode="0640"> + <Set path="hudson/systemMessage/#text" + value="This is a Jenkins server."/> + </Path> + +Note that there's no need to manually modify the load path by setting +``/augeas/load/<lens>/incl``, nor do you have to call ``load`` +explicitly. + +Schema +====== + +.. xml:group:: augeasCommands + + +Performance +=========== + +The Augeas tool is quite slow to initialize. For each ``<Path +type="augeas" ... >`` entry you have, it creates a new Augeas object +internally, which can take several seconds. It's thus important to +use this tool sparingly. diff --git a/doc/conf.py b/doc/conf.py index d3d30687b..0e4009cd3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -66,7 +66,7 @@ else: # The short X.Y version. version = '1.3' # The full version, including alpha/beta/rc tags. -release = '1.3.1' +release = '1.3.3' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -254,6 +254,8 @@ man_pages = [ [], 8), ('man/bcfg2-lint.conf', 'bcfg2-lint.conf', 'Configuration parameters for bcfg2-lint', [], 5), + ('man/bcfg2-report-collector', 'bcfg2-report-collector', + 'Reports collection daemon', [], 8), ('man/bcfg2-reports', 'bcfg2-reports', 'Query reporting system for client status', [], 8), ('man/bcfg2-server', 'bcfg2-server', diff --git a/doc/contents.txt b/doc/contents.txt index 8af0d808a..8220d0d1d 100644 --- a/doc/contents.txt +++ b/doc/contents.txt @@ -7,7 +7,7 @@ Bcfg2 documentation |release| ============================= .. toctree:: - :maxdepth: 2 + :maxdepth: 3 introduction/index installation/index diff --git a/doc/development/lint.txt b/doc/development/lint.txt index 6a4651f92..6c0be960d 100644 --- a/doc/development/lint.txt +++ b/doc/development/lint.txt @@ -106,6 +106,11 @@ Basics Existing ``bcfg2-lint`` Plugins =============================== +AWSTagsLint +----------- + +.. autoclass:: Bcfg2.Server.Plugins.AWSTags.AWSTagsLint + BundlerLint ----------- diff --git a/doc/getting_started/index.txt b/doc/getting_started/index.txt index a9e91e6b8..a9b1b847f 100644 --- a/doc/getting_started/index.txt +++ b/doc/getting_started/index.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _getting_started-index: @@ -115,7 +116,7 @@ files: ``clients.xml`` and ``groups.xml``. Your current .. code-block:: xml - <Clients version="3.0"> + <Clients> <Client profile="basic" pingable="Y" pingtime="0" name="bcfg-server.example.com"/> </Clients> @@ -132,7 +133,7 @@ Our simple ``groups.xml`` file looks like: .. code-block:: xml - <Groups version='3.0'> + <Groups> <Group profile='true' public='false' name='basic'> <Group name='suse'/> </Group> @@ -168,14 +169,14 @@ Next, we create a motd.xml file in the Bundler directory: .. code-block:: xml - <Bundle name='motd' version='2.0'> + <Bundle name='motd'> <Path name='/etc/motd' /> </Bundle> Now when we run the client, we get slightly different output:: Loaded tool drivers: - Chkconfig POSIX YUMng + Chkconfig POSIX YUM Incomplete information for entry Path:/etc/motd; cannot verify Phase: initial @@ -205,7 +206,7 @@ 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 + Chkconfig POSIX YUM Phase: initial Correct entries: 1 diff --git a/doc/installation/distributions.txt b/doc/installation/distributions.txt index 3dcfd7721..9db111682 100644 --- a/doc/installation/distributions.txt +++ b/doc/installation/distributions.txt @@ -66,19 +66,7 @@ This way is not recommended on production systems. Only for testing. Gentoo ====== -Early in July 2008, Bcfg2 was added to the Gentoo portage tree. So far -it's still keyworded for all architectures, but we are actively working -to get it marked as stable. - -If you don't use portage to install Bcfg2, you'll want to make sure you -have all the prerequisites installed first. For a server, you'll need: - -* ``app-admin/gamin`` or ``app-admin/fam`` -* ``dev-python/lxml`` - -Clients will need at least: - -* ``app-portage/gentoolkit`` +Bcfg2 can be installed via portage. OS X ==== diff --git a/doc/installation/prerequisites.txt b/doc/installation/prerequisites.txt index 0cb721bb9..e920f955b 100644 --- a/doc/installation/prerequisites.txt +++ b/doc/installation/prerequisites.txt @@ -21,7 +21,7 @@ Bcfg2 Client +----------------------------+------------------------+--------------------------------+ | libxslt (if lxml is used) | Any | libxml2 | +----------------------------+------------------------+--------------------------------+ -| python | 2.4 and greater [#f1] | | +| python | 2.4 and greater [#f1]_ | | +----------------------------+------------------------+--------------------------------+ | lxml or elementtree [#f2]_ | Any | lxml: libxml2, libxslt, python | +----------------------------+------------------------+--------------------------------+ @@ -50,12 +50,23 @@ Bcfg2 Server +-------------------------------+----------+--------------------------------+ | lxml | 0.9+ | lxml: libxml2, libxslt, python | +-------------------------------+----------+--------------------------------+ -| gamin or fam | Any | | +| gamin or inotify | Any | | +-------------------------------+----------+--------------------------------+ -| python-gamin or python-fam | Any | gamin or fam, python | +| python-gamin or pyinotify | Any | gamin or inotify, python | +-------------------------------+----------+--------------------------------+ -| M2crypto or python-ssl (note | Any | python, openssl | -| that the ssl module is | | | -| included in python versions | | | -| 2.6 and later | | | +| python-ssl (note | Any | python, backported ssl module | ++-------------------------------+----------+--------------------------------+ + +Bcfg2 Reporting +--------------- + +A webserver capabable of running wsgi applications is required for web +reporting, such as Apache + mod_wsgi or nginx. + ++-------------------------------+----------+--------------------------------+ +| Software | Version | Requires | ++===============================+==========+================================+ +| django | 1.2.0+ | | ++-------------------------------+----------+--------------------------------+ +| south | 0.7.0+ | | +-------------------------------+----------+--------------------------------+ diff --git a/doc/installation/source.txt b/doc/installation/source.txt index 1406a5ceb..064371e87 100644 --- a/doc/installation/source.txt +++ b/doc/installation/source.txt @@ -2,7 +2,7 @@ .. _GPG1: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x75BF2C177F7D197E .. _GPG2: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x80B8492FA88FFF4B -.. _Download: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Download +.. _Download: http://bcfg2.org/download/ .. _source: diff --git a/doc/man/bcfg2-report-collector.txt b/doc/man/bcfg2-report-collector.txt new file mode 100644 index 000000000..07c618537 --- /dev/null +++ b/doc/man/bcfg2-report-collector.txt @@ -0,0 +1,40 @@ +.. -*- mode: rst -*- +.. vim: ft=rst + + +bcfg2-report-collector +====================== + +.. program:: bcfg2-report-collector + +Synopsis +-------- + +**bcfg2-report-collector** [*options*] + +Description +----------- + +:program:`bcfg2-report-collector` runs a daemon to collect logs from the +LocalFilesystem :ref:`Bcfg2 Reports <reports-dynamic>` transport object +and add them to the Reporting storage backend. + +Options +------- + +-C configfile Specify alternate bcfg2.conf location. +-D pidfile Daemonize, placing the program pid in *pidfile*. +-E encoding Specify the encoding of config files. +-Q path Specify the path to the server repository. +-W configfile Specify the path to the web interface + configuration file. +-d Enable debugging output. +-h Print usage information. +-o path Set path of file log +-v Run in verbose mode. +--version Print the version and exit + +See Also +-------- + +:manpage:`bcfg2-server(8)`, :manpage:`bcfg2-reports(8)` diff --git a/doc/man/bcfg2-server.txt b/doc/man/bcfg2-server.txt index d5945cad6..3f8f3ea21 100644 --- a/doc/man/bcfg2-server.txt +++ b/doc/man/bcfg2-server.txt @@ -23,8 +23,7 @@ Options ------- -C configfile Specify alternate bcfg2.conf location. --D pidfile Daemonize, placing the program pid in the specified - pidfile. +-D pidfile Daemonize, placing the program pid in *pidfile*. -E encoding Specify the encoding of config files. -Q path Specify the path to the server repository. -S server Manually specify the server location (as opposed to diff --git a/doc/man/bcfg2.conf.txt b/doc/man/bcfg2.conf.txt index 3a0217aef..6faf48a1a 100644 --- a/doc/man/bcfg2.conf.txt +++ b/doc/man/bcfg2.conf.txt @@ -46,6 +46,12 @@ filemonitor fam pseudo +fam_blocking + Whether the server should block at startup until the file monitor + backend has processed all events. This can cause a slower startup, + but ensure that all files are recognized before the first client + is handled. + ignore_files A comma-separated list of globs that should be ignored by the file monitor. Default values are:: @@ -729,6 +735,11 @@ control the database connection of the server. port Port for database connections. Not used for sqlite3. + options + Various options for the database connection. The value is + expected as multiple key=value pairs, separated with commas. + The concrete value depends on the database engine. + Reporting options ----------------- diff --git a/doc/reports/dynamic.txt b/doc/reports/dynamic.txt index 9de3f868f..6b8a1f467 100644 --- a/doc/reports/dynamic.txt +++ b/doc/reports/dynamic.txt @@ -39,7 +39,7 @@ Prerequisites * sqlite3 * pysqlite2 (if using python 2.4) -* `Django <http://www.djangoproject.com>`_ >= 1.2 +* `Django <http://www.djangoproject.com>`_ >= 1.3 * mod-wsgi .. warning:: diff --git a/doc/server/admin/index.txt b/doc/server/admin/index.txt index ee03cedda..c563ead9c 100644 --- a/doc/server/admin/index.txt +++ b/doc/server/admin/index.txt @@ -23,7 +23,6 @@ functionality. Available modes are listed below. minestruct perf pull - query snapshots tidy viz diff --git a/doc/server/admin/query.txt b/doc/server/admin/query.txt deleted file mode 100644 index 65851a43d..000000000 --- a/doc/server/admin/query.txt +++ /dev/null @@ -1,15 +0,0 @@ -.. -*- mode: rst -*- - -.. _server-admin-query: - -query -===== - -Query clients. - -The default result format is suitable for consumption by `pdsh`_. -This example queries the server for all clients in the *ubuntu* group:: - - bcfg2-admin query g=ubuntu - -.. _pdsh: http://sourceforge.net/projects/pdsh/ diff --git a/doc/server/configuration.txt b/doc/server/configuration.txt index 7892c2612..383367a46 100644 --- a/doc/server/configuration.txt +++ b/doc/server/configuration.txt @@ -149,7 +149,7 @@ Consequently, you simply have to run: .. code-block:: bash chown bcfg2:bcfg2 /var/run/bcfg2-server - chmod 0644 /var/run/bcfg2-server + chmod 0755 /var/run/bcfg2-server Additionally, the server daemon itself supports dropping privileges natively in 1.3. Simply add the following lines to ``bcfg2.conf``:: @@ -218,3 +218,46 @@ To select which backend to use, set the ``backend`` option in the * ``best`` (the default; currently the same as ``builtin``) ``best`` may change in future releases. + +Multiprocessing core configuration +---------------------------------- + +If you use the multiprocessing core, there are other bits you may wish +to twiddle. + +By default, the server spawns as many children as the host has CPUs. +(This is determined by ``multiprocessing.cpu_count()``.) To change +this, set: + +.. code-block:: conf + + [server] + children = 4 + +The optimal number of children may vary depending on your workload. +For instance, if you are using :ref:`native yum +library support <native-yum-libraries>`, then a separate process is +spawned for each client to resolve its package dependencies, so +keeping the children at or below the CPU count is likely a good idea. +If you're not using native yum library support, though, you may wish +to oversubscribe the core slightly. It's recommended that you test +various configurations and use what works best for your workload. + +Secondly, if ``tmpwatch`` is enabled, you must either disable it or +exclude the pattern ``/tmp/pymp-\*``. For instance, on RHEL or CentOS +you may have a line like the following in +``/etc/cron.daily/tmpwatch``: + +.. code-block:: bash + + /usr/sbin/tmpwatch -x /tmp/.X11-unix -x /tmp/.XIM-unix -x /tmp/.font-unix \ + -x /tmp/.ICE-unix -x /tmp/.Test-unix 240 /tmp + +You would need to add ``-X /tmp/pymp-\*`` to it, like so: + +.. code-block:: bash + + /usr/sbin/tmpwatch -x /tmp/.X11-unix -x /tmp/.XIM-unix -x /tmp/.font-unix \ + -x /tmp/.ICE-unix -x /tmp/.Test-unix -X /tmp/pymp-\* 240 /tmp + +See https://bugzilla.redhat.com/show_bug.cgi?id=1058310 for more information. diff --git a/doc/server/database.txt b/doc/server/database.txt index 87d3e3afe..3c8970f68 100644 --- a/doc/server/database.txt +++ b/doc/server/database.txt @@ -34,9 +34,10 @@ of ``/etc/bcfg2.conf``. +-------------+------------------------------------------------------------+-------------------------------+ | Option name | Description | Default | +=============+============================================================+===============================+ -| engine | The full name of the Django database backend to use. See | "django.db.backends.sqlite3" | +| engine | The name of the Django database backend to use. See | "sqlite3" | | | https://docs.djangoproject.com/en/dev/ref/settings/#engine | | -| | for available options | | +| | for available options (note that django.db.backends is not | | +| | included in the engine name) | | +-------------+------------------------------------------------------------+-------------------------------+ | name | The name of the database | "/var/lib/bcfg2/bcfg2.sqlite" | +-------------+------------------------------------------------------------+-------------------------------+ @@ -48,6 +49,12 @@ of ``/etc/bcfg2.conf``. +-------------+------------------------------------------------------------+-------------------------------+ | port | The port to connect to | None | +-------------+------------------------------------------------------------+-------------------------------+ +| options | Extra parameters to use when connecting to the database. | None | +| | Available parameters vary depending on your database | | +| | backend. The parameters are supplied as comma separated | | +| | key=value pairs. | | ++-------------+------------------------------------------------------------+-------------------------------+ + Database Schema Sync ==================== diff --git a/doc/server/plugins/connectors/awstags.txt b/doc/server/plugins/connectors/awstags.txt new file mode 100644 index 000000000..b884ca065 --- /dev/null +++ b/doc/server/plugins/connectors/awstags.txt @@ -0,0 +1,124 @@ +.. -*- mode: rst -*- + +.. _server-plugins-connectors-awstags: + +========= + AWSTags +========= + +The AWSTags plugin is a connector that retrieves tags from instances +in EC2, and can assign optionally assign +group membership pased on patterns in the tags. See `Using Tags +<http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html>`_ +for details on using tags in EC2. + +AWSTags queries EC2 for instances whose ``private-dns-name`` property +matches the hostname of the client. + +Setup +===== + +#. Add ``AWSTags`` to the ``plugins`` option in ``/etc/bcfg2.conf`` +#. Configure AWS credentials in ``/etc/bcfg2.conf`` (See + `Configuration`_ below for details.) +#. Optionally, create ``AWSTags/config.xml`` (See `Assigning Groups`_ + below for details.) +#. Restart the Bcfg2 server. + +Using Tag Data +============== + +AWSTags exposes the data in templates as a dict available as +``metadata.AWSTags``. E.g., in a :ref:`Genshi template +<server-plugins-generators-cfg-genshi>`, you could do: + +.. code-block:: genshitext + + Known tags on ${metadata.hostname}: + {% for key, val in metadata.AWSTags.items() %}\ + ${key} ${val} + {% end %}\ + +This would produce something like:: + + Known tags on foo.example.com: + Name foo.example.com + some random tag the value + +Assigning Groups +================ + +AWSTags can assign groups based on the tag data. This functionality +is configured in ``AWSTags/config.xml``. + +Example +------- + +.. code-block:: xml + + <AWSTags> + <Tag name="^foo$"> + <Group>foo</Group> + </Tag> + <Tag name="^bar$" value="^bar$"> + <Group>bar</Group> + </Tag> + <Tag name="^bcfg2 group$" value="(.*)"> + <Group>$1</Group> + </Tag> + </AWSTags> + +In this example, any machine with a tag named ``foo`` would be added +to the ``foo`` group. Any machine with a tag named ``bar`` whose +value was also ``bar`` would be added to the ``bar`` group. Finally, +any machine with a tag named ``bcfg2 group`` would be added to the +group named in the value of that tag. + +Note that both the ``name`` and ``value`` attributes are *always* +regular expressions. + +If a ``<Tag/>`` element has only a ``name`` attribute, then it only +checks for existence of a matching tag. If it has both ``name`` and +``value``, then it checks for a matching tag with a matching value. + +You can use backreferences (``$1``, ``$2``, etc.) in the group names. +If only ``name`` is specified, then the backreferences will refer to +groups in the ``name`` regex. If ``name`` and ``value`` are both +specified, then backreferences will refer to groups in the ``value`` +regex. If you specify both ``name`` and ``value``, it is not possible +to refer to groups in the ``name`` regex. + +Schema Reference +---------------- + +.. xml:schema:: awstags.xsd + +Configuration +============= + +AWSTags recognizes several options in ``/etc/bcfg2.conf``; at a +minimum, you must configure an AWS access key ID and secret key. All +of the following options are in the ``[awstags]`` section: + ++-----------------------+-----------------------------------------------------+ +| Option | Description | ++=======================+=====================================================+ +| ``access_key_id`` | The AWS access key ID | ++-----------------------+-----------------------------------------------------+ +| ``secret_access_key`` | The AWS secret access key | ++-----------------------+-----------------------------------------------------+ +| ``cache`` | Whether or not to cache tag lookups. See `Caching`_ | +| | for details. Default is to cache. | ++-----------------------+-----------------------------------------------------+ + +Caching +======= + +Since the AWS API isn't always very quick to respond, AWSTags caches +its results by default. The cache is fairly short-lived: the cache +for each host is expired when it starts a client run, so it will start +the run with fresh data. + +If you frequently update tags on your instances, you may wish to +disable caching. That's probably a bad idea, and would tend to +suggest that updating tags frequently is perhaps the Wrong Thing. diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index da511736d..47e82fdbf 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -181,6 +181,8 @@ XML tag should be ``<Properties>``. JSON Property Files ------------------- +.. versionadded:: 1.3.0 + The data in a JSON property file can be accessed with the ``json`` attribute, which is the loaded JSON data. The JSON properties interface does not provide any additional functionality beyond the @@ -189,6 +191,8 @@ interface does not provide any additional functionality beyond the YAML Property Files ------------------- +.. versionadded:: 1.3.0 + The data in a YAML property file can be accessed with the ``yaml`` attribute, which is the loaded YAML data. Only a single YAML document may be included in a file. @@ -229,10 +233,10 @@ simply:: %} You can also enable automatch for individual Property files by setting -the attribute ``automatch="true"`` on the top-level ``<Property>`` +the attribute ``automatch="true"`` on the top-level ``<Properties>`` tag. Conversely, if automatch is enabled by default in ``bcfg2.conf``, you can disable it for an individual Property file by -setting ``automatch="false"`` on the top-level ``<Property>`` tag. +setting ``automatch="false"`` on the top-level ``<Properties>`` tag. If you want to see what ``XMLMatch()``/automatch would produce for a given client on a given Properties file, you can use :ref:`bcfg2-info diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index f31923866..0f0601105 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -541,7 +541,8 @@ Example </Group> <Allow from="/root/.ssh/id_rsa.pub" host="foo.example.com"/> <Allow from="/home/foo_user/.ssh/id_rsa.pub"> - <Params command="/home/foo_user/.ssh/ssh_command_filter"/> + <Option name="command" value="/home/foo_user/.ssh/ssh_command_filter"/> + <Option name="no-X11-forwarding"/> </Allow> <Allow> ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDw/rgKQeARRAHK5bQQhAAe1b+gzdtqBXWrZIQ6cIaLgxqj76TwZ3DY4A6aW9RgC4zzd0p4a9MfsScUIB4+UeZsx9GopUj4U6H8Vz7S3pXxrr4E9logVLuSfOLFbI/wMWNRuOANqquLYQ+JYWKeP4kagkVp0aAWp7mH5IOI0rp0A6qE2you4ep9N/nKvHDrtypwhYBWprsgTUXXMHnAWGmyuHGYWxNYBV9AARPdAvZfb8ggtuwibcOULlyK4DdVNbDTAN1/BDBE1ve6WZDcrc386KhqUGj/yoRyPjNZ46uZiOjRr3cdY6yUZoCwzzxvm5vle6mEbLjHgjGEMQMArzM9 vendor@example.com @@ -596,6 +597,11 @@ Deltas cat file functionality. ``bcfg2-lint`` checks for deltas and warns about them. +.. warning:: + + In Bcfg2 1.3, deltas **do not** work with `SSH key or + authorized_keys generation <SSH Keys>`_. + Bcfg2 has finer grained control over how to deliver configuration files to a host. Let's say we have a Group named file-server. Members of this group need the exact same ``/etc/motd`` as all other hosts except @@ -632,23 +638,35 @@ server and we have the following configuration files:: motd.G01_web-server motd.G01_mail-server.cat motd.G02_file-server.cat + motd.H_bar.example.com motd.H_foo.example.com.cat -If our machine **isn't** *foo.example.com* then here's what would happen: - -Bcfg2 would choose ``motd.G01_web-server`` as the base file. It is -the most specific base file for this host. Bcfg2 would apply the -``motd.G01_mail-server.cat`` delta to the ``motd.G01_web-server`` -base file. It is the least specific delta. Bcfg2 would then apply the -``motd.G02_file-server.cat`` delta to the result of the delta before -it. If our machine **is** *foo.example.com* then here's what would happen: - -Bcfg2 would choose ``motd.G01_web-server`` as the base file. It -is the most specific base file for this host. Bcfg2 would apply the -``motd.H_foo.example.com.cat`` delta to the ``motd.G01_web-server`` base -file. The reason the other deltas aren't applied to *foo.example.com* -is because a **.H_** delta is more specific than a **.G##_** delta. Bcfg2 -applies all the deltas at the most specific level. +If our machine isn't *foo.example.com* or *bar.example.com*, but +is a web server, then Bcfg2 would choose ``motd.G01_web-server`` as +the base file. It is the most specific base file for this host. Bcfg2 +would apply the ``motd.G01_mail-server.cat`` delta to the +``motd.G01_web-server`` base file. It is the least specific +delta. Bcfg2 would then apply the ``motd.G02_file-server.cat`` delta +to the result of the delta before it. + +If our machine is *foo.example.com* and a web server, then Bcfg2 would +choose ``motd.G01_web-server`` as the base file. It is the most +specific base file for this host. Bcfg2 would apply the +``motd.H_foo.example.com.cat`` delta to the ``motd.G01_web-server`` +base file. The reason the other deltas aren't applied to +*foo.example.com* is because a **.H_** delta is more specific than a +**.G##_** delta. Bcfg2 applies all the deltas at the most specific +level. + +If our machine is *bar.example.com*, then Bcfg2 would chose +``motd.H_foo.example.com`` as the base file because it is the most +specific base file for this host. Regardless of the groups +*bar.example.com* is a member of, **no cat files** would be applied, +because only cat files as specific or more specific than the base file +are applied. (In other words, if a group-specific base file is +selected, only group- or host-specific cat files can be applied; if a +host-specific base file is selected, only host-specific cat files can +be applied.) .. _server-plugins-generators-cfg-validation: diff --git a/doc/server/plugins/generators/nagiosgen.txt b/doc/server/plugins/generators/nagiosgen.txt index ee99b2dc1..0ae922fa3 100644 --- a/doc/server/plugins/generators/nagiosgen.txt +++ b/doc/server/plugins/generators/nagiosgen.txt @@ -8,7 +8,7 @@ NagiosGen This page describes the installation and use of the `NagiosGen`_ plugin. -.. _NagiosGen: http://trac.mcs.anl.gov/projects/bcfg2/browser/src/lib/Server/Plugins/NagiosGen.py +.. _NagiosGen: https://github.com/Bcfg2/bcfg2/blob/maint/src/lib/Bcfg2/Server/Plugins/NagiosGen.py Update ``/etc/bcfg2.conf``, adding NagiosGen to plugins:: diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index cdc4f7282..31f3ccf22 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -490,17 +490,18 @@ Benefits to this include: * Much lower memory usage by the ``bcfg2-server`` process. * Much faster ``Packages.Refresh`` behavior. * More accurate dependency resolution. +* Better use of multiple processors/cores. Drawbacks include: -* More disk I/O. In some cases, you may have to raise the open file +* Resolution of package dependencies is slower and more + resource-intensive. At times it can be much slower, particularly + after running ``Packages.Refresh``. +* More disk I/O. This can be alleviated by putting + ``/var/lib/bcfg2/Packages/cache`` on tmpfs, but that offsets the + lower memory usage. In some cases, you may have to raise the open file limit for the user who runs your Bcfg2 server process, particularly if you have a lot of repositories. -* Resolution of package dependencies is slower in some cases, - particularly after running ``Packages.Refresh``. -* If you have a very large number of clients using a very small number - of repositories, using native yum libraries may actually increase - memory usage. Configuring the Yum Helper -------------------------- diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 2493be53f..a21dd217f 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _server-plugins-generators-rules: @@ -59,7 +60,7 @@ Rules Tag .. xml:element:: Rules :linktotype: :noautodep: - :inlinetypes: PostInstall,RContainerType + :inlinetypes: RContainerType Package Tag ----------- @@ -135,6 +136,20 @@ Attributes common to all Path tags: :onlyattrs: name,type +augeas +^^^^^^ + +Run `Augeas <http://www.augeas.net>`_ commands. See +:ref:`client-tools-augeas` for more details. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: owner,group,mode,secontext,lens + :requiredattrs: owner,group,mode + device ^^^^^^ @@ -376,6 +391,8 @@ SEModule Tag See also :ref:`server-plugins-generators-semodules`. +.. _server-plugins-generators-rules-posixuser-tag: + POSIXUser Tag ------------- @@ -411,6 +428,8 @@ Defaults plugin <server-plugins-structures-defaults>`. See :ref:`client-tools-posixusers` for more information on managing users and groups. +.. _server-plugins-generators-rules-posixgroup-tag: + POSIXGroup Tag -------------- diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt index ab147ce56..c79a8ced5 100644 --- a/doc/server/plugins/generators/tcheetah.txt +++ b/doc/server/plugins/generators/tcheetah.txt @@ -99,7 +99,7 @@ Simple Example ============== TCheetah works similar to Cfg in that you define all literal information -about a particular file in a directory rooted at TGenshi/path_to_file. +about a particular file in a directory rooted at TCheetah/path_to_file. The actual file contents are placed in a file named `template` in that directory. Below is a simple example a file ``/foo``. diff --git a/doc/server/plugins/index.txt b/doc/server/plugins/index.txt index 4f2b484ac..f3d6daa73 100644 --- a/doc/server/plugins/index.txt +++ b/doc/server/plugins/index.txt @@ -31,7 +31,7 @@ Default Plugins The `Bcfg2 repository`_ contains the all plugins currently distributed with Bcfg2. -.. _Bcfg2 repository: http://trac.mcs.anl.gov/projects/bcfg2/browser/src/lib/Server/Plugins +.. _Bcfg2 repository: https://github.com/Bcfg2/bcfg2/tree/maint/src/lib/Bcfg2/Server/Plugins Metadata (Grouping) ------------------- diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index 306a752b6..2e23c31d5 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -13,6 +13,9 @@ the system disk, you would want to know this information to correctly generate an `/etc/auto.master` autofs config file for each type. Here we will look at how to do this. +Probes also allow dynamic group assignment for clients, see +:ref:`_server-plugins-probes-dynamic-groups`. + First, create a ``Probes`` directory in our toplevel repository location:: @@ -119,6 +122,45 @@ is to add the ``/etc/auto.master`` to a Bundle: <Path name='/etc/auto.master'/> +.. _server-plugins-probes-dynamic-groups: + +Dynamic Group Assignment +======================== + +The output lines of the probe matching "group:" are used to +dynamically assign hosts to groups. These dynamic groups need not already +exist in ``Metadata/groups.xml``. If a dynamic group is defined in +``Metadata/groups.xml``, clients that include this group will also get +all included groups and bundles. + +Consider the following output of a probe:: + + group:debian-wheezy + group:amd64 + +This assigns the client to the groups debian-wheezy and amd64. + +To prevent clients from manipulating the probe output and choosing +unexpected groups (and receiving their potential sensitive files) you +can use the ``allowed_groups`` option in the ``[probes]`` section of +``bcfg2.conf`` on the server. This whitespace-separated list of +anchored regular expressions (must match the complete group name) +controls dynamic group assignments. Only matching groups are +allowed. The default allows all groups. + +.. versionadded:: 1.3.4 + +Example: + +.. code-block:: ini + + [probes] + allowed_groups = debian-(squeeze|wheezy|sid) i386 + +This allows the groups `debian-squeeze`, `debian-wheezy`, `debian-sid` +and `i386`. With the probe output from above, this setting would +disallow the group `amd64`. + Handling Probe Output ===================== diff --git a/doc/server/plugins/structures/bundler/kernel.txt b/doc/server/plugins/structures/bundler/kernel.txt index 2e3d84e93..d83679683 100644 --- a/doc/server/plugins/structures/bundler/kernel.txt +++ b/doc/server/plugins/structures/bundler/kernel.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _server-plugins-structures-bundler-kernel: @@ -21,7 +22,7 @@ some of which might be better than this one. Feel free to hack as needed. .. code-block:: xml - <Bundle name='kernel' version='2.0'> + <Bundle name='kernel'> <Group name='sles8'> <!-- =================== ia32 ==================== --> <Group name='ia32'> @@ -30,7 +31,7 @@ some of which might be better than this one. Feel free to hack as needed. <Path name='/boot/initrd'/> <Path name='/boot/vmlinuz.old'/> <Path name='/boot/initrd.old'/> - <PostInstall name='/sbin/lilo'/> + <BoundAction name='lilo' command='/sbin/lilo' timing='post' when='modified'/> <!-- Current kernel --> <Package name='linux-2.4.21-314.tg1'/> <Package name='linux-2.4.21-314.tg1-source'/> diff --git a/doc/unsorted/bcfg2.conf-options.txt b/doc/unsorted/bcfg2.conf-options.txt deleted file mode 100644 index 57e26cbd2..000000000 --- a/doc/unsorted/bcfg2.conf-options.txt +++ /dev/null @@ -1,19 +0,0 @@ -.. -*- mode: rst -*- - -.. _unsorted-bcfg2.conf-options: - -========== -bcfg2.conf -========== - -This page documents the various options available in bcfg2.conf. The -various sections correspond to the sections in the file itself. - -components -========== - -logging -------- - -Specify an alternate path for the lockfile used by the bcfg2 client. -Default value is ``/var/lock/bcfg2.run`` diff --git a/doc/unsorted/dynamic_groups.txt b/doc/unsorted/dynamic_groups.txt deleted file mode 100644 index 11535dc8b..000000000 --- a/doc/unsorted/dynamic_groups.txt +++ /dev/null @@ -1,27 +0,0 @@ -.. -*- mode: rst -*- - -.. _unsorted-dynamic_groups: - -============== -Dynamic Groups -============== - -Bcfg2 supports the use of dynamic groups. These groups are not included -in a client's profile group, but instead are derived from the results -of probes executed on the client. These dynamic groups need not already -exist in ``Metadata/groups.xml``. If a dynamic group is defined in -``Metadata/groups.xml``, clients that include this group will also get -all included groups and bundles. - -Setting up dynamic groups -========================= - -In order to define a dynamic group, setup a probe that outputs the text -based on system properties:: - - group:groupname - -This output is processed by the Bcfg2 server, and results in dynamic -group membership in groupname for the client. See the :ref:`Probes -<server-plugins-probes-index>` page for a more thorough description -of probes. diff --git a/doc/unsorted/howtos.txt b/doc/unsorted/howtos.txt index 0c5b482d9..cef64a394 100644 --- a/doc/unsorted/howtos.txt +++ b/doc/unsorted/howtos.txt @@ -14,5 +14,5 @@ Here are several howtos that describe different aspects of Bcfg2 deployment * :ref:`appendix-guides-gentoo` - Issues specific to running Bcfg2 on Gentoo * :ref:`server-plugins-probes-index` - How to use Probes to gather information from a client machine. * :ref:`client-tools-actions` - How to use Actions -* :ref:`unsorted-dynamic_groups` - Using dynamic groups +* :ref:`server-plugins-probes-dynamic-groups` - Using dynamic groups * :ref:`client-modes-paranoid` - How to run an update in paranoid mode diff --git a/doc/unsorted/python-ssl_1.14-1_amd64.deb b/doc/unsorted/python-ssl_1.14-1_amd64.deb Binary files differdeleted file mode 100644 index e6c8ad137..000000000 --- a/doc/unsorted/python-ssl_1.14-1_amd64.deb +++ /dev/null diff --git a/doc/unsorted/python-stdeb_0.3-1_all.deb b/doc/unsorted/python-stdeb_0.3-1_all.deb Binary files differdeleted file mode 100644 index 5cee96e3c..000000000 --- a/doc/unsorted/python-stdeb_0.3-1_all.deb +++ /dev/null diff --git a/doc/unsorted/ssl.txt b/doc/unsorted/ssl.txt deleted file mode 100644 index 91b62ca59..000000000 --- a/doc/unsorted/ssl.txt +++ /dev/null @@ -1,68 +0,0 @@ -.. -*- mode: rst -*- - -.. _unsorted-ssl: - -========== -Python SSL -========== - -The ssl module can be found `here <http://pypi.python.org/pypi/ssl>`_. - -With this change, SSL certificate based client authentication is -supported. In order to use this, based CA-type capabilities are -required. A central CA needs to be created, with each server and all -clients getting a signed cert. See [wiki:Authentication] for details. - -Setting up keys is accomplished with three settings, each in the -"`[communication]`" section of ``bcfg2.conf``:: - - key = /path/to/ssl private key - certificate = /path/to/signed cert for that key - ca = /path/to/cacert.pem - - -Python SSL Backport Packaging -============================= - -Both the Bcfg2 server and client are able to use the in-tree ssl module -included with python 2.6. The client is also able to still use M2Crypto. A -python ssl backport exists for 2.3, 2.4, and 2.5. With this, M2Crypto -is not needed, and tlslite is no longer included with Bcfg2 sources. See -[wiki:Authentication] for details. - -To build a package of the ssl backport for .deb based distributions -that don't ship with python 2.6, you can follow these instructions, -which use `stdeb`_. Alternatively if you happen to have .deb packaging -skills, it would be great to get policy-complaint .debs into the major -deb-based distributions. - -.. _stdeb: http://github.com/astraw/stdeb/tree/master - -The following commands were used to generate :download:`this -<python-ssl_1.14-1_amd64.deb>` debian package The ``easy_install`` command -can be found in the `python-setuptools` package.:: - - sudo aptitude install python-all-dev fakeroot - sudo easy_install stdeb - wget http://pypi.python.org/packages/source/s/ssl/ssl-1.14.tar.gz#md5=4e08aae0cd2c7388d1b4bbb7f374b14a - tar xvfz ssl-1.14.tar.gz - cd ssl-1.14 - stdeb_run_setup - cd deb_dist/ssl-1.14 - dpkg-buildpackage -rfakeroot -uc -us - sudo dpkg -i ../python-ssl_1.14-1_amd64.deb - -.. note:: Version numbers for the SSL module have changed. - -For complete Bcfg2 goodness, you'll also want to package stdeb using stdeb. -The completed debian package can be grabbed from :download:`here -<python-stdeb_0.3-1_all.deb>`, which was generated using the following:: - - sudo aptitude install apt-file - wget http://pypi.python.org/packages/source/s/stdeb/stdeb-0.3.tar.gz#md5=e692f745597dcdd9343ce133e3b910d0 - tar xvfz stdeb-0.3.tar.gz - cd stdeb-0.3 - stdeb_run_setup - cd deb_dist/stdeb-0.3 - dpkg-buildpackage -rfakeroot -uc -us - sudo dpkg -i ../python-stdeb_0.3-1_all.deb |