CFENGINE 3 ENTERPRISE 2.2.3 CFEngine has renamed CFEngine 3 Nova to CFEngine 3 Enterprise RELEASE DATE: September 2012 SCOPE: Installation and upgrade instructions for CFEngine 3 Enterprise 2.2.x (successor to CFEngine Nova 2.1.x) ----------------------------------------------------------- TABLE OF CONTENTS: REQUIREMENTS INSTALLATION INSTRUCTIONS (CLEAN INSTALL) UPGRADE PROCEDURE SOFTWARE DEPENDENCIES ----------------------------------------------------------- For information about supported platforms, compatible hub/client configurations for this release and an overview of changes, please see the "Release Notes CFEngine 3 Enterprise.txt" file that comes with this package. As always, test thoroughly in your lab before upgrading production environments! REQUIREMENTS: CFEngine recommends that your hub machine should have at least 2 GB of memory and a modern processor. CFEngine recommends to have 256 MB available memory on the clients. For machines under CFEngine’s management (clients), a full installation of CFEngine 3 Enterprise requires about 25 MB of disk storage. Otherwise disk usage depends on your specific policies, especially those that concern reporting. Verify that the machine’s network connection is working and that port 5308 (used by CFEngine) and port 80 (used for the Mission Portal) is open for both incoming and outgoing connections. A working package manager is required on the hub/policy server to install an Apache Web Server, php module, MongoDB, subversion, etc. You should start from a blank system (i.e. with none of these components installed) to avoid potential interference with the installation process. No special software is otherwise required on machines in your network, CFEngine bundles all critical dependencies in the CFEngine 3 Enterprise package (see also SOFTWARE DEPENDENCIES below). Requirements specific to MongoDB: 1. Filesystem type: - ext4 ( kernel version >= 2.6.23 ) - xfs ( kernel version >= 2.6.25 ) 2. Memory: Approximately 8 GB per 500 hosts 3. Turn off NUMA if running on numa hardware. http://www.mongodb.org/display/DOCS/NUMA 4. Do not use large VM pages with Linux (info about large pages: http://linuxgazette.net/155/krishnakumar.html) 5. Set file descriptor limit and user process limit to 4k+ (see etc/limits and ulimit) For those running databases on ext4 filesystems, a 2.6.23 kernel is required for efficient filesystem preallocation, 2.6.25 is required for XFS support of the same feature. High filesystem I/O following the allocation of new database files is one symptom of this problem. INSTALLATION INSTRUCTIONS (CLEAN INSTALL): * Clean install is tested, upgrade from previous versions of CFEngine 3 Nova tested (see previous section) * As always, install HUB first, then client(s). * For large systems (> 1000 hosts) we recommend increasing the memory limit in php.conf on the HUB (for instance to 128 MB) CFEngine 3 Enterprise is provided in two packages, cfengine-nova_2.2.x and cfengine-nova-expansion_2.2.x (the nova name remains in the packages to ensure backwards compatibility with package managers). The main software package must be installed on every host (including the hub). The expansion package is only installed on the policy hub. You should install and set up the hub first. The general installation steps are as follows: 1. Copy the CFEngine 3 Enterprise packages to the system. 2. Unpack the cfengine-nova and cfengine-nova-expansion packages (in that order or simultaneously as below): [RedHat/CentOS/SUSE] $ rpm -Uvh cfengine-nova-2.2.x-y.x86_64.rpm cfengine-nova-expansion-2.2.x-y.x86_64.rpm [Debian/Ubuntu] $ dpkg --install cfengine-nova_2.2.x-y_x86_64.deb cfengine-nova-expansion_2.2.x-y_x86_64.deb 3. (Skip for CFEngine 3 Free Enterprise): Send the hub's public key (/var/cfengine/ppkeys/localhost.pub) to CFEngine support to obtain a license 4. (Skip for CFEngine 3 Free Enterprise): Copy the obtained license file to /var/cfengine/masterfiles/license.dat 5. Bootstrap the machines to the hub (starting with bootstrapping the hub to itself): $ /var/cfengine/bin/cf-agent --bootstrap --policy-server 6. CFEngine should now be up and running on your system. The Mission Portal will not be immediately accessible, you should wait 10-15 minutes for the system to converge before attempting to connect to the hub IP-address through your web browser. See Enterprise 2.2 Owner's Manual for more detailed installation instructions and troubleshooting tips. If you wish to manually install cfmod to the machine, you'll need to do the following: 1. Make a symlink from php library directory (typically something like /usr/lib/php5/20100525) to $installdir/lib/php/cfmod.so 2. Put a configuration file (with .ini extension) to php configuration directory (typically something like /etc/php5/conf.d): extension=cfmod.so UPGRADE PROCEDURE: The following is a general procedure to upgrade from CFEngine 3 Nova 2.1.x to CFEngine 3 Enterprise, see Enterprise 2.2 Owner's Manual for upgrading from other versions. Start with the hub (policy server): 1. Stop all CFE processes (/etc/init.d/cfengine3 stop) 2. Upgrade the cfengine-nova and cfengine-nova-expansion packages (in that order or simultaneously as below): [RedHat/CentOS/SUSE] $ rpm -Uvh cfengine-nova-2.2.x-y.x86_64.rpm cfengine-nova-expansion-2.2.x-y.x86_64.rpm [Debian/Ubuntu] $ dpkg --install cfengine-nova_2.2.x-y_x86_64.deb cfengine-nova-expansion_2.2.x-y_x86_64.deb 3. Remove Mongodb lock if present: $ rm -f /var/cfengine/state/mongod.lock 4. CFEngine 3 Enterprise's dependencies have changed so we have to correct cf-twin (libgnutls and libmongo.c were updated): $ cp /var/cfengine/bin/cf-agent /var/cfengine/bin/cf-twin 5. Copy the new CFE_ prefixed policy files to $(sys.workdir)/masterfiles (the files with a prefix "CFE_" are maintained by CFEngine, do not make changes to these, they are there to ensure that the Mission Portal works properly). $ cd /var/cfengine/share/NovaBase $ cp CFE_cfengine.cf CFE_knowledge.cf CFE_hub_specific.cf /var/cfengine/masterfiles 6. If you run any Windows machines under CFEngine management, replace the packages promises in /var/cfengine/masterfiles/update.cf to ensure automatic upgrade of CFEngine clients. The modified version should look like this (modified package_version number and added separate section for windows): packages: # update packages after all CFEngine have been killed stopped_cfprocs.!windows:: "$(novapkg)" comment => "Update Nova package to a newer version", handle => "update_bins_packages_nova_update_all", package_policy => "update", package_select => ">=", # picks the newest Nova available package_architectures => { "$(pkgarch)" }, package_version => "9.9.9", # Install new Nova anyway package_method => u_generic( "$(local_software_dir)" ), ifvarclass => "nova_edition", classes => u_if_else("bin_update_success", "bin_update_fail"); stopped_cfprocs.windows:: "$(novapkg)" comment => "Update Nova package to a newer version", handle => "update_bins_packages_nova_update_all", package_policy => "update", package_select => ">=", # picks the newest Nova available package_architectures => { "$(pkgarch)" }, package_version => "9.9.9.9", # Install new Nova anyway package_method => u_generic( "$(local_software_dir)" ), ifvarclass => "nova_edition", classes => u_if_else("bin_update_success", "bin_update_fail"); 7. Modify one line in /var/cfengine/masterfiles/update.cf (line 298; approximate location, please verify that you change the corresponding content) Change to run mongod without journaling (replace line with the following) "/var/cfengine/bin/mongod --fork --logpath /var/log/mongod.log --dbpath $(sys.workdir)/state --bind_ip 127.0.0.1 --nohttpinterface --nojournal --logappend > /dev/null < /dev/null 2>&1" 8. Copy the modified update.cf to the inputs directory: $ cp /var/cfengine/masterfiles/update.cf /var/cfengine/inputs/update.cf 9. Tidy up $(sys.doc_root) directory (example for Debian/Ubuntu): $ rm -rf /var/www/* 10. Restart CFEngine processes $ /etc/init.d/cfengine3 start For client upgrades there are 2 approaches: manual or automatic upgrade. * Manual: Update cfengine-nova on each client by rpm, dpkg or corresponding Windows command. For Linux/UNIX systems, update cf-twin as described in step 4 in the upgrade procedure for the hub (i.e. overwrite the old cf-twin). For Windows systems copy/overwrite the content of C:\Program Files\Cfengine\bin to C:\Program Files\Cfengine\bin-twin * Automatic: On the hub, copy the cfengine-nova packages to the operating system specific distribution directories in /var/cfengine/master_software_updates and CFEngine 3 Enterprise will take care of the rest. CFEngine should now be up and running on your system. See Enterprise 2.2 Owner's Manual for more detailed installation instructions and troubleshooting tips. SOFTWARE DEPENDENCIES (specific to CFEngine 3 Enterprise) The CFEngine 3 Enterprise agents on client hosts do not require any additional packages for operation and/or install. The following section is for the hub only. CFEngine 3 Enterprise will automatically detect if the necessary packages are already installed on the hub. If new package installation is required, CFEngine 3 Enterprise will install all of them from its default software repository (if configured properly). If the system does not have a default software repository configured, manual installation of these packages will be required. Note that these mandatory packages may have additional dependencies on their own, and hence additional packages may be installed during the installation process. This process will be handled automatically by CFEngine bootstrap. We do not recommend configuring every component on your own, please contact your CFEngine sales representative in case you cannot use CFEngine's bootstrap procedure. RHEL 5: - Apache HTTP Server (httpd, version 2.2.3-45.el5) - PHP5 Core Files (php, version 5.1.6-27.el5) - PHP5 Extension Module (php-bcmath, version 5.1.6-27.el5) (php-pear, version 5.1.6-27.el5) - A Concurrent Versioning system (subversion, version 1.5.7-0.1.1) RHEL 6: - Apache HTTP Server (httpd, version 2.2.15-9.el6) - PHP5 Core Files (php, version 5.3.2-6.el6) - PHP5 Extension Module (php-bcmath, version 5.3.2-6.el6) (php-pear, version 1:1.9.0-2.el6) - A Concurrent Versioning system (subversion, version 1.6.11-2.el6_1.4) CentOS 5: - Apache HTTP Server (httpd, version 2.2.3-45) - PHP5 Core Files (php, version 5.1.6-27) - PHP5 Extension Module (php-bcmath, version 5.1.6-27) (php-pear, version 5.1.6-27) (php-mcrypt, version 5.1.6-27) - A Concurrent Versioning system (subversion, version 1.6.11-7) DEBIAN 5: - The Apache Web Server Version 2.0 (apache2, version 2.2.9-10+lenny9) - PHP5 Core Files (php5, version 5.2.6.dfsg.1-1+lenny13) - PHP5 Extension Module (php5-cli, version 5.2.6.dfsg.1-1+lenny13) (php5-mcrypt, version 5.2.6.dfsg.1-1+lenny13) (php-pear, version 5.2.6.dfsg.1-1+lenny13) - A Concurrent Versioning system (subversion, version 1.5.1dfsg1-7) DEBIAN 6: - The Apache Web Server Version 2.0 (apache2, version 2.2.16-6+squeeze1) - PHP5 Core Files (php5, version 5.3.3-7+squeeze3) - PHP5 Extension Module (php5-cli, version 5.3.3-7+squeeze3) (php5-mcrypt, version 5.3.3-7+squeeze3) (php-pear, version 5.3.3-7+squeeze3) - A Concurrent Versioning system (subversion, version 1.6.12dfsg-6) UBUNTU 8: - The Apache Web Server Version 2.0 (apache2, version 2.2.8-1) - PHP5 Core Files (php5, version 5.2.4-2ubuntu5.17) - PHP5 Extension Module (php5-cli, version 5.2.4-2ubuntu5.17) (php5-mcrypt, version 5.2.3-0ubuntu1) (php-pear, version version 5.2.4-2ubuntu5.17) - A Concurrent Versioning system (subversion, version 1.4.6dfsg1-2ubuntu1.3) UBUNTU 10: - The Apache Web Server Version 2.0 (apache2, version 2.2.14-5ubuntu8.4) - PHP5 Core Files (php5, version 5.3.2-1ubuntu4.9) - PHP5 Extension Module (php5-cli, version 5.3.2-1ubuntu4.9) (php5-mcrypt, version 5.3.2-0ubuntu1) (php-pear, version version 5.3.2-1ubuntu4.9) - A Concurrent Versioning system (subversion, version 1.6.6dfsg-2ubuntu1)