EA Installgd5 4

ElectricAccelerator
Installation and Configuration Guide

version 5.4
Electric Cloud, Inc. 676 W. Maude Avenue Sunnyvale, CA 94085 www.electric-cloud.com
Copyright 2002 - 2011 Electric Cloud, Inc. All rights reserved.

Published March 2011 Electric Cloud believes the information in this publication is accurate as of its publication date. The information is subject to change without notice and does not represent a commitment from the vendor. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. ELECTRIC CLOUD, INCORPORATED MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any ELECTRIC CLOUD software described in this publication requires an applicable software license. Copyright protection includes all forms and matters of copyrightable material and information now allowed by statutory or judicial law or hereinafter granted, including without limitation, material generated from software programs displayed on the screen such as icons, screen display appearance, and so on. The software and/or databases described in this document are furnished under a license agreement or nondisclosure agreement. The software and/or databases may be used or copied only in accordance with terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the license or nondisclosure agreement.
Trademarks
Electric Cloud, ElectricAccelerator, ElectricCommander, ElectricInsight, Electric Make, and SparkBuild are registered trademarks or trademarks of Electric Cloud, Incorporated. Electric Cloud productsElectricAccelerator, ElectricCommander, ElectricInsight, and Electric Makeare commonly referred to by their short namesAccelerator, Commander, Insight, and eMakethroughout various types of Electric Cloud product-specific documentation. Other product names mentioned in this guide may be trademarks or registered trademarks of their respective owners and are hereby acknowledged.
ii
ElectricAccelerator Installation and Configuration Guide
Contents
Chapter 1
ElectricAccelerator Introduction
About ElectricAccelerator ....................................................................................................... Cluster Manager................................................................................................................ Electric File System (EFS)................................................................................................ ElectricAccelerator Agent (Agent) ................................................................................... Electric Make (eMake) ..................................................................................................... Electrify............................................................................................................................. Understanding Component Interactions .................................................................................. Electric Make and EFS ..................................................................................................... Electric Make and Cluster Manager ................................................................................. Cluster Manager and Other Components.......................................................................... When to Use the ElectricAccelerator Cluster .......................................................................... Grid Integration........................................................................................................................ 1-1 1-1 1-1 1-1 1-2 1-2 1-2 1-3 1-3 1-3 1-3 1-4
Chapter 2
System Requirements and Supported Platforms

System Requirements and Supported Platforms...................................................................... Known Limitations ........................................................................................................... Hardware Requirements.................................................................................................... Software Requirements ..................................................................................................... Third-party Supported Build Tools ................................................................................... Database Information........................................................................................................ Disk Usage ........................................................................................................................ Agent Memory Usage ....................................................................................................... The "checksum" utility...................................................................................................... Default Installation Directories......................................................................................... Installation Log Locations ................................................................................................ Agent Log Locations......................................................................................................... Disk Cache Directory and Agent Temporary Storage Location ....................................... Linux Kernel Performance Note ....................................................................................... Planning for Grid Use .............................................................................................................. 2-1 2-3 2-3 2-4 2-5 2-7 2-7 2-7 2-7 2-7 2-8 2-8 2-8 2-9 2-9
Chapter 3
Installing ElectricAccelerator
General Information................................................................................................................. 3-1 Installation Notes .............................................................................................................. 3-1 User Interface Installation Method .......................................................................................... 3-2 Cluster Manager................................................................................................................ 3-2 Electric Agent/EFS ........................................................................................................... 3-7 Electric Make .................................................................................................................. 3-11 Additional Install Options............................................................................................... 3-13 Interactive Command-line Installation Method ..................................................................... 3-14 Cluster Manager.............................................................................................................. 3-14 Electric Agent/EFS ......................................................................................................... 3-15
iii
Electric Make.................................................................................................................. Additional Install Options .............................................................................................. Path Settings ................................................................................................................... Silent Installation Method ..................................................................................................... Installer Command Line Options ................................................................................... Creating an Installer Properties File ............................................................................... Automating a Linux/Solaris Silent Install ...................................................................... Automating a Windows Silent Install............................................................................. Installed Tool Files ................................................................................................................ Post-Installation Activities .................................................................................................... Running eccheckenv....................................................................................................... Microsoft Visual Studio.................................................................................................. Installing an Apache Server Certificate.......................................................................... Testing the Cluster Manager Installation........................................................................ Uninstalling ElectricAccelerator ...........................................................................................
3-16 3-17 3-17 3-18 3-18 3-20 3-22 3-22 3-23 3-23 3-23 3-23 3-24 3-25 3-25
Chapter 4
Upgrading ElectricAccelerator Components

Upgrade Notes ......................................................................................................................... Upgrading Multiple Agents on Cluster Hosts ......................................................................... User Interface Upgrade Method .............................................................................................. Electric Agent/EFS ........................................................................................................... Cluster Manager ............................................................................................................... Electric Make.................................................................................................................... Interactive Command-line Upgrade Method ........................................................................... Electric Agent/EFS ........................................................................................................... Cluster Manager ............................................................................................................... Electric Make.................................................................................................................... ElectricAccelerator Version Compatibility Matrix.................................................................. 4-1 4-2 4-3 4-3 4-6 4-6 4-6 4-6 4-7 4-8 4-8
Chapter 5
Initial Configuration Tasks

Logging In and Licensing........................................................................................................ 5-2 ElectricAccelerator Home Page............................................................................................... 5-4 Server Information............................................................................................................ 5-5 Using Comments .............................................................................................................. 5-5 Enabling Resource Management ............................................................................................. 5-6 Changing Log Locations ......................................................................................................... 5-6 User Authentication ................................................................................................................. 5-7 Getting Started .................................................................................................................. 5-7 Configuring LDAP ........................................................................................................... 5-7 Determining LDAP Mapping ........................................................................................... 5-9 Additional information ................................................................................................... 5-10 Setting Up Email Notification ............................................................................................... 5-11 Configuring the Mail Policy ........................................................................................... 5-11 User Email Preferences .................................................................................................. 5-12 Solaris 10 configuration/debugging....................................................................................... 5-12 Using the Web Interface ........................................................................................................ 5-12 Accessing Other ElectricAccelerator Information ................................................................ 5-13
Chapter 6
Configuring Cluster Manager for the Grid

After Cluster Manager is installed........................................................................................... Setting Up LSF ................................................................................................................. Additional Information ..................................................................................................... Grid Host Manager ........................................................................................................... 6-1 6-3 6-4 6-4
iv
Chapter 7
Windows-Specific Information
Agent-Side Application Setup ................................................................................................. Visual Studio ..................................................................................................................... Microsoft Office................................................................................................................ WinZip .............................................................................................................................. MSBuild ............................................................................................................................ Antivirus Software ............................................................................................................ Cygwin .............................................................................................................................. Additional Information ............................................................................................................ Registry-Specific Information ................................................................................................. Registry Use Under Windows........................................................................................... Registry Underlay ............................................................................................................. ExcludeProcessList Registry Entry................................................................................... Windows Kernel Non-paged Pool Memory............................................................................. Support for Managed Code/.NET ............................................................................................ Glossary of Terms ............................................................................................................. 7-1 7-1 7-1 7-2 7-2 7-2 7-2 7-2 7-3 7-3 7-4 7-4 7-4 7-5 7-5
vi
1
nvisible Body Tag
ElectricAccelerator is a collection of software components that manage and accelerate the build process. This guide walks you through the ElectricAccelerator installation process for UNIX or Windows systems and is intended for administrators, build engineers, and software engineers.
About ElectricAccelerator
ElectricAccelerator is a software build accelerator that dramatically reduces software build times by distributing the build over a large cluster of inexpensive servers. Using a patented dependency management system, ElectricAccelerator identifies and fixes problems in real time that would break traditional parallel builds. ElectricAccelerator plugs into existing Make-based infrastructures seamlessly and includes web-based management and reporting tools. During ElectricAccelerator installation, the following components will be installed: Cluster Manager Electric File System (EFS) ElectricAccelerator Agents (Electric Agent or Agent) Electric Make (eMake) Electrify
For a complete list of runnable programs installed on your cluster, see the Installed Files/Tools help topic in ElectricAccelerator online help.
Cluster Manager
Cluster Manager machine is a server that contains two layers: 1) a service layer to allocate Agents to builds, collect build results, and monitor system activity, and 2) a web server layer for the web interface. Cluster Manager also allows users to view upcoming and past builds, view the status of Agents in the cluster, and run reports.
Electric File System (EFS)

Electric File System (EFS) is a special-purpose file system driver, monitoring every file access and providing Electric Make with complete usage information. This driver collects dependency information, which allows Electric Make to automatically detect and correct out-of-order build steps. Each EFS driver instance is paired with an ElectricAccelerator Agent. During the ElectricAccelerator installation process, the Agent and EFS are installed at the same time.
ElectricAccelerator Agent (Agent)

As the user-level component running on the hosts, the Agent and EFS are inseparablethe Agent is an intermediary between Electric Make and EFS. Depending on your system configuration requirements, you may have one EFS/Agent installed per virtual CPU.
1-1
Electric Make (eMake)

Electric Make, the main build application, is a new Make version invoked interactively or through build scripts. It reads makefiles in several different formats, including GNU Make and Microsoft NMAKE. Electric Make distributes commands to the cluster for remote execution and services file requests.
Electrify
The Electrify component accelerates builds by parallelizing the build process and distributing build steps across clustered resources. You can use one of two methods to monitor your tools: a wrapper application or automatic process interception. The ElectricAccelerator Electric Make Users Guide contains information about using Electrify.
Understanding Component Interactions

To a user, ElectricAccelerator may appear identical to other Make versionsreading makefiles in several different formats and producing identical results. Using a cluster for builds is transparent to the ElectricAccelerator user. Important differences in ElectricAccelerator build processing versus other distributed systems: ElectricAccelerator components work together to achieve faster, more efficient builds. Instead of running a sequential build on a single processor, ElectricAccelerator executes build steps in parallel on a cluster of hosts. For fault tolerance, job results are isolated until the job completes. If an Agent fails during a job, ElectricAccelerator discards any partial results it might have produced and reruns the job on a different Agent. Missing dependencies discovered at runtime are collected in a history file that updates each time a build is invoked. ElectricAccelerator uses this collected data to improve performance of subsequent builds.
1-2
Electric Make and EFS

High concurrency levels in ElectricAccelerator are enabled by the Electric File System (EFS). When a job such as a compilation runs on a host, it accesses files such as source files and headers through EFS. EFS records detailed file access data for the build and returns that data to Electric Make. Electric Make acts as a file server for Agents, reading the correct file version from file systems on its machine and passing that information back to the Agents. Agents retain different file version information and do not rely on Electric Makes file sequencing ability to provide the correct version for a job. The Agent receives file data, downloads it into the kernel, notifying EFS, which then completes the original request. At the end of a job, Electric Agent returns any file modifications to Electric Make so it can apply changes to its local file systems.
Electric Make and Cluster Manager

When Electric Make is invoked on the build machine, it communicates with Cluster Manager to acquire a set of Agents it can use for the build. When Electric Make finishes, it sends Cluster Manager the build results, and tells Cluster Manager that Agents are free now to work on other builds. If more than one build is invoked, Cluster Manager allocates agents using a priority-based algorithm. Builds with the same priority share Agents evenly, while higher priority builds are allocated more Agents than lower priority builds. By default, agents running on the same host machine are allocated to the same build. In real time, Cluster Manager dynamically adjusts the number of agents assigned to running builds as each builds needs change, which allows ElectricAccelerator to make the best use of cluster resources.
Cluster Manager and Other Components

Cluster Managers primary responsibility is Agent allocation. However, through Cluster Manager, users also create and maintain the build infrastructure: build classes, user access, build history details, and manage Agent activity.
When to Use the ElectricAccelerator Cluster

ElectricAccelerator is designed to be a complete replacement for GNU Make or Microsoft NMAKE. It has the same command-line switches, produces identical output, and (with a few exceptions) reads your existing makefiles without change. Wherever you are currently invoking gmake or nmakein a script, from a batch process, or interactivelyyou can run Electric Make to distribute the work to Cluster Manager and complete your build faster. In some cases, however, distributed builds are not always faster. In particular, if a build has very little work to do and/or has much higher I/O activity compared to computation, it can be faster to allow the build to execute locally. The best examples of these build types are: Clean targets often do little more than large recursive deletes. One touch build a build consisting of nothing more than zero or one compilations followed immediately by a large link.
When to Use the ElectricAccelerator Cluster
1-3
But then, depending on the build specifics, the cluster may outperform local builds for a large class of clean target or one touch buildsit is best to experiment with a few common configurations to determine which mode is more efficient. Typically, if a build has two or more jobs it can execute concurrently, running the build on the cluster is more efficient. If you find that some common clean or one touch builds are faster when run locally, you can run Electric Make in local mode. In local mode, Electric Make behaves exactly like your existing Make, running all jobs in series on the local system.
Grid Integration
If you plan to use a host grid with ElectricAccelerator, the following list shows the relationship between ElectricAccelerator components and the grid management software, such as LSF or Oracle Grid Engine. Electric Make does not interact directly with the grid management softwareElectric Make can run inside or outside of a grid. Electric Agent/EFS software is designed to run on grid execution hosts. While the Agent/EFS does not talk to the grid management software, the Agent/EFS can be activated by it, effectively creating a dynamically sized ElectricAccelerator cluster. Cluster Manager interfaces with the grid management software to add or subtract machines to/from the ElectricAccelerator cluster as build demands increase or decrease.
Note: Grid management client software must be installed on the designated Cluster Manager server before Cluster Manager is used in grid mode. The following diagram illustrates how ElectricAccelerator interacts with grid management software, using LSF as an example.
1-4
2
This chapter describes hardware and software requirements for installing and running ElectricAccelerator on Windows or UNIX systems.

Refer to the ElectricAccelerator Release Notes, for the latest updates to this information. ElectricAccelerator Cluster Manager, Electric Make, and Electric Agent/EFS currently run on: Linux
Operating System Notes
Red Hat Enterprise Linux 6 kernel 2.6.32-x (32- or 64-bit) Red Hat Enterprise Linux 5 kernel 2.6.18-x (32- or 64-bit) Red Hat Enterprise Linux 4 kernel 2.6.9-x (32- or 64-bit) SUSE 11 (32- or 64-bit) Ubuntu 10.10 (32- or 64-bit) Ubuntu 10.04 (32- or 64-bit) Ubuntu 9.10 (32- or 64-bit)
Linux Notes:
For agent hosts, the corresponding version of kernel-devel package required For agent hosts, you must install the following three RPM prerequisites: kernel-devel, gcc, and gcc-c++, before invoking the installer
For 64-bit Linux systems, you must install 32-bit libraries before invoking the installer. For example, on Ubuntu platforms, run sudo apt-get install ia32-libs to install the 32-bit libraries. On RHEL 6, run yum install glibc.i686. ElectricAccelerator does not support extended attributes (xattr). Attempting to query or set extended attributes for a file returns an ENOTSUPP (Operation not supported) error. For 32-bit, only x86 is supported. For 64-bit, only x86-64 is supported. IA-64 (Itanium) is not supported. RHEL 3 is no longer a supported platform.
2-1
Solaris
Solaris 10 (32- or 64-bit) Solaris 9 (32- or 64-bit)
SPARC and x86-64 supported Agents are 64-bit only SPARC only Agents are 64-bit only
Solaris Note:
Application is 32-bit for Cluster Manager and eMake, and 64-bit for agents.
Microsoft Windows
Windows 7 (32- or 64-bit) Windows Server 2008 R2 (64-bit) Windows Vista (32- or 64-bit) Windows Server 2003 R2 (32- or 64-bit) Windows XP SP3 (32-bit)
Windows Notes:
SP1 and SP2 required
NTFS is required for all Windows machines. For 32-bit, only x86 is supported. For 64-bit, only x86-64 is supported. IA-64 (Itanium) is not supported. 64-bit registry mirroring is supported only if you use a 64-bit Agent/EFS (running on 64-bit Windows Vista/Server 2008 R2) with 64-bit eMake (running on any 64-bit Windows platform). Registry mirroring does not work under 64-bit Windows Server 2003 because of an operating system limitation. To run Electric Make with Visual Studio on Windows, one of the following is required: Visual Studio 2005 SP1 Visual Studio 2005 SP1 Redistributable Package (if you use Visual Studio .NET 2002 or 2003). The following URLs are provided for your convenience: http://www.microsoft.com/downloads/details.aspx?familyid=200B2FD9-AE1A-4A14-984D-389C36F85647& displaylang=en (32-bit) http://www.microsoft.com/downloads/details.aspx?familyid=EB4EBE2D-33C0-4A47-9DD4-B9A6D7BD44D A&displaylang=en (64-bit)
Notes to ensure a consistent build environment: Electric Cloud recommends all hosts in a cluster have synchronized clocks, which is important particularly if you are running in the shared agent allocation policy. For UNIX machines, you can use ntpdate to sync clocks. For Windows machines, participation in a domain generally ensures synchronized clocks.
2-2
Notes regarding 64-bit vs. 32-bit usage: The installer for Windows and Linux provides both 32-bit and 64-bit versions of Electric Make. (For Solaris, only 32-bit is available.) The ElectricAccelerator installer automatically sets the path to 32-bit. To use 64-bit, you must edit the environment variable path to include the 64-bit bin location before the 32-bit location. 64-bit executables are installed in a new subdirectory of the install location, <installDir>/64/bin. For example: If you install into the Windows C:\ECLoud\i686_win32 directory, the 64-bit executables are in the C:\ECloud\i686_win32\64\bin directory. For Linux, the directory is /opt/ecloud/i686_Linux/64/bin. Though 32-bit Electric Make can be used with 32- or 64-bit cluster hosts, Electric Cloud recommends using 64-bit Windows Vista/Server 2008 R2 cluster hosts with 64-bit eMake only. This is because on Windows, eMake uses --emake-reg-roots by default, even if it is not set. Using 32-bit eMake with a 64-bit Windows Vista/Server 2008 R2 Agent/EFS causes registry mirroring issues. The agent installer automatically determines whether to install the 32-bit or 64-bit agent based on the machine architecture. No user action is required.
Known Limitations
Cluster Manager and Agent install locations Electric Cloud does not support installation of Cluster Manager or Agents on the following: NFS CIFS Samba shares
Database location Electric Cloud does not support storing your database on Network Appliance systems or NFS. Issues that you may encounter include the following: ElectricAccelerator is unable to start MySQL because MySQL attempts to lock files that are already locked. If MySQL starts, you may encounter issues related to MySQL UTF-8 support.
Database names The database name cannot contain a . (period). If the name contains a period, the Cluster Manager will not start.
Hardware Requirements
Electric Cloud recommends installing Cluster Manager, Electric Make, and Electric Agent components on independent machines so each component can run efficiently without competing for system resources. The following are minimum hardware requirements for each machine where ElectricAccelerator components are installed (Agent, Electric Make, Cluster Manager): Solaris machines require a SPARC or x86-64 processor and 2 GB RAM is recommended, particularly for the Cluster Manager machine. Linux machines require a Pentium 4 processor and 2 GB RAM is recommended, particularly for the Cluster Manager machine. Windows machines require at least a Pentium 4 processor and 2 GB RAM is recommended, particularly for the Cluster Manager machine.
See Agent Memory Usage on page 2-7 for additional Agent recommendations.
2-3
Software Requirements
To connect to Cluster Manager, your web browser must be Microsoft Internet Explorer 7.0 or later, or Mozilla Firefox 3.5 or later. If you have a web server (for example, Apache, IIS) or other application using port 80 on the Cluster Manager host, you have the following options: Uninstall the web server. Disable the web server. Reconfigure the web server to use another port. Choose a non-default port (not 80) for Apache during Cluster Manager installation. The default Apache SSL port is 443.
The Cluster Manager server must not contain a previous MySQL installation. For MySQL, the default port is 3306. If you plan to use an Oracle or MS SQL database, you must create it before installing ElectricAccelerator. Note: By default, the Cluster Manager server uses port 8030 and secure port 8031. Your tool chain should be installed on each agent host. You can virtualize the tool chain in some cases, but this can be tricky if the Windows registry is involved. Also, for performance reasons it is better to install the tool chain on each agent host. Many companies use Norton Ghost software to mirror all agent hosts. Cygwin If you run builds on Windows in Cygwin environments, ensure you have cygwin1.dll version 1.5.25 or 1.7.7 installed. You can get recent Cygwin versions from cygwin.com. Install the same version of Cygwin on all agent hosts and eMake machines. Mixing different Cygwin versions (for example, running v1.5 on an eMake machine and v1.7 on agents) is not supported. (In particular, Cygwin versions 1.5 and 1.7 default to incompatible representations for symbolic links.) Note: Cygwin version 1.7.x is supported for x = 7 only. There are known problems for x < 7. By default, Cygwin 1.7.7 applies overly restrictive permissions to most directories. The permissions prevent the Administrators group from creating new subdirectories and may prevent the agent software from creating new directories to serve as mount points in order to reflect eMake client mount points. On all agent hosts modify the permissions for the Cygwin installation directory and any other directories under which you want the agent software to dynamically create Cygwin mount points. For agent installations that use standard ECloudInternalUser* accounts, grant the Administrators group permission to create folders / append data. For custom agent users, grant permission for subdirectory creation to those agent users. Later versions of Cygwin If you choose to use Cygwin version 1.7.x for x > 7, then you may need to disable or modify a workaround that ElectricAccelerator provides for a crash bug in Cygwin 1.7.7. The workaround affects only the eMake program itself, and the majority of Cygwin programs should be unaffected by the bug. The workaround is tailored to Cygwin 1.7.7 in particular; it may or may not crash future Cygwin versions (not yet released at the time of publication). If eMake crashes under a later Cygwin version, then disable the workaround by setting ECLOUD_CYGWIN_PATHBUF_BUG_WORKAROUND=off in the environment. If that fails, use Cygwin 1.7.7 or contact Electric Cloud Technical Support to inquire if other settings are appropriate to later Cygwin versions. Be sure to mention which Cygwin versions are acceptable, and which you prefer. Notes to ensure a consistent build environment: Configure Electric Agent hosts identically across a cluster. Ideally, all Agent host machines should be the same, using the same operating system and hardware configuration. You may experience difficulties if you do not follow this recommendation. In addition, if any of your tool applications (compilers and so on) are installed locally, ensure they are all the same version and kept in sync. Note: Ghosting with the Electric Agent already installed is not recommended.
2-4
You may experience issues on Windows agent hosts depending on your firewall settings: the ports used to communicate with agents are dynamic. If you need to lock down communication with an agent host, exclude the following programs from the block list:
C:\Ecloud\i686_win32\bin\ecagent.exe C:\Ecloud\i686_win32\bin\erunnerd.exe
In addition, exclude the following programs during agent host installation:

C:\ecinst\ecinstconf.exe C:\ecinst\eclouduninst.exe C:\ecinst\fsize.exe C:\ecinst\Setup.exe C:\ecinst\SetupErunnerTmp.exe C:\ERunnerTmp\i686_win32\bin\erunnerdtmp.exe
These programs exist during ElectricAccelerator installation only. You might find it easier to disable communication restrictions with the agent host during agent installation. If you do not want to do this: Create folders C:\ecinst and C:\ErunnerTmp\i686_win32\bin Move files with those specified names into these directories. Exclude these programs from the blocked programs list. Delete the directories C:\ecinst and C:\ErunnerTmp
Agents can be installed now.
Third-party Supported Build Tools

GNU Make 3.80 and 3.81 Microsoft NMAKE 7.x and 8.x Symbian Make (Windows) Visual Studio .NET 2002, 2003, 2005, 2008, 2010 Running Visual Studio on Windows Vista Due to an operating system limitation, ElectricAccelerator does not support Visual Studio 2002 or Visual Studio 2003 on Windows Vista. Microsoft released Visual Studio 2005 Service Pack 1 and Visual Studio 2005 Service Pack 1 Update for Windows Vista that together address areas of Visual Studio impacted by Windows Vista enhancements. ElectricAccelerator supports Visual Studio 2005 on Windows Vista only with the recommended patch applied. The full text regarding running Visual Studio on Windows Vista is available from Microsoft at http://msdn.microsoft.com/en-us/vstudio/aa948853.aspx. Note: ElectricAccelerator can support Visual Studio 6 workspaces if they are exported to NMAKE files. However, every time something changes in the workspace, an export must be done again. Cygwin 1.5.25 and 1.7.7 Apache Ant 1.6.5 Note: For more information on Ant builds, see the ElectricAccelerator Electric Make Users Guide. Rational ClearCase ElectricAccelerator supports building within ClearCase dynamic views and provides the Ledger feature, which can track files that change as a result of a change to the views configuration specification. (See ElectricAccelerator Ledger File on page 7-5 in the ElectricAccelerator Electric Make Users Guide.) ClearCase 7 works inside a 64-bit eMake for Linux and Windows.
2-5
ClearCase was tested on the following ClearCase versions and patches: For Linux ClearCase ClearCase version 2003.06.00 (Tue Dec 16 21:15:58 EST 2003) clearcase_p2003.06.00-55 (Tue May 13 11:49:56 EDT 2008) clearcase_p2003.06.00-56 (Tue May 13 22:14:31 EDT 2008) @(#) MVFS version 2003.06.10+ (Wed Mar 5 21:25:36 2008) VNODE built $Date: 2008-04-11.18:51:42 (UTC) $ 2003.06.10+ (Fri May 2 00:28:18 EDT 2008) 2003.06.10+ (Fri May 2 00:22:30 EDT 2008) ClearCase version 7.1.1.1 (Tue Apr 13 15:53:39 EDT 2010) (7.1.1.01.00_2010A.FCS) ClearCase version 7.1.1.2 (Tue May 25 20:46:08 EDT 2010) (7.1.1.02.00_2010B.D100525) ClearCase version 7.1.1.3 (Wed Aug 04 03:03:51 EDT 2010) (7.1.1.03.00_2010C.D100803) @(#) MVFS version 7.1.1.3 (Thu Jun 24 03:49:46 2010) built at $Date: 2010-10-20.16:49:29 (UTC) $ 7.1.1.3 (Tue Jul 6 03:53:32 2010) 7.1.1.3 (Wed Jun 23 04:05:51 2010)
cleartool db_server ClearCase
cleartool db_server
For Windows ClearCase ClearCase version 2003.06.00 (Fri Apr 18 13:06:18 2003) clearcase patch p2003.06.01 (Fri Sep 5 11:59:28 2003) clearcase patch p2003.06.12 (Fri Nov 7 11:59:28 2003) clearcase patch p2003.06.14 (Fri Oct 8 11:59:28 2004) clearcase patch p2003.06.15 (Fri Jun 9 11:59:28 2005) clearcase patch p2003.06.15 (Fri Sep 9 11:59:28 2005 PATCH 2005C) clearcase patch p2003.06.15 (Fri Nov 9 11:59:28 2005 PATCH 2005D) clearcase patch p2003.06.15 (Fri Jan 6 11:59:28 2006 PATCH 2006A) clearcase patch p2003.06.15 (Fri Apr 7 11:59:28 2006 PATCH 2006B) @(#) MVFS version 2003.06.10+ (Thu Jan 27 04:26:46 2005) 2003.06.10+ (Mon Feb 27 08:26:52 2006) 2003.06.10+ (Fri May 6 22:12:48 2005) ClearCase version 7.1.1.1 (Tue Apr 13 15:53:39 EDT 2010) (7.1.1.01.00_2010A.FCS) ClearCase version 7.1.1.2 (Tue May 25 20:46:08 EDT 2010) (7.1.1.02.00_2010B.D100525) ClearCase version 7.1.1.3 (Wed Aug 04 03:03:51 EDT 2010) (7.1.1.03.00_2010C.D100803) @(#) MVFS version 7.1.1.3 (Tue Jun 29 04:03:33 2010) 7.1.1.3 (Tue Jul 6 05:54:49 2010) 7.1.1.3 (Wed Jun 23 11:45:39 2010)
cleartool db_server ClearCase
cleartool db_server
For Solaris ClearCase ClearCase version 2003.06.00 (Fri Apr 25 09:05:22 EDT 2003) clearcase_p2003.06.00-55 (Tue May 13 11:49:56 EDT 2008) @(#) MVFS version 2003.06.00 (Thu Jan 30 20:47:56 EST 2003) 2003.06.10+ (Fri May 2 00:01:35 EDT 2008) 2003.06.10+ (Thu May 1 23:56:35 EDT 2008) ClearCase version 7.0.1 (Wed May 30 16:29:44 EDT 2007) @(#) MVFS version 7.0.1.0 (Wed Apr 11 21:42:52 2007) 7.0.1.0 (Tue May 15 10:10:24 EDT 2007) 7.0.1.0 (Tue May 15 10:08:56 EDT 2007)
cleartool db_server ClearCase cleartool db_server
2-6
Database Information
ElectricAccelerator supports the following databases: MySQL 5.0 (ElectricAccelerator default) Oracle 11g Release 2 MS SQL Server 2008
Disk Usage
Disk space usage varies and depends on the size of your builds. The client build machinethe machine where Electric Make is installedrequires disk space at least equal to the size of your largest build. Actual installer disk space required is 300 MB. Allow the following disk space for each ElectricAccelerator component: Cluster Manager - 5 GB (to allow space for build log storage) Electric Make - 200 MB Electric Agent/EFS - free disk space should be at least 3-4 times the size of a complete build (input and output)
Agent Memory Usage

Memory requirements: Minimum - 1 GB per agent Recommended - 2 to 3 GB per agent (if your build contains very large build steps)
Agents use system memory to cache small or unmodified files. For optimal performance, each host in the cluster must have enough memory for your link step, which is typically the largest single build step, plus another 200 MB. If your builds have increased in size substantially since the system was originally delivered, and you have noticed a slowdown in build times, consider upgrading the host hardware.
The "checksum" utility

An MD5 checksum file is available on the Electric Cloud FTP site. If you choose to verify that ElectricAccelerator files are intact and unaltered from their original form and content after you download them, download the corresponding MD5 checksum file also. MD5 utilities are available for Windows, Linux, and Solaris operating systems. On Linux, verify with md5sum --check md5.txt Most Linux installations provide an md5sum command for calculating MD5 message digests. An MD5 utility for Windows can be downloaded at http://www.fourmilab.ch/md5/.
Default Installation Directories

Windows
C:\ECloud\i686_win32
Linux
/opt/ecloud/i686_Linux
Solaris
/opt/ecloud/sun4u_SunOS
2-7
Installation Log Locations

The installation log file is created in the install directorys root. The name is install_$timestamp.log. The default location: Windows
C:\ECloud
Linux and Solaris

/opt/ecloud
Agent Log Locations

Agent log files default location: Windows
<ECloud Install>\ecagent?.log
Linux and Solaris

/var/log/ecagent?.log
Disk Cache Directory and Agent Temporary Storage Location

The same location is used for the disk cache directory and agent temporary storage. By default, the location is: Windows
C:\WINDOWS\Temp
Linux and Solaris

/tmp
The most common reason to change this location is due to insufficient disk cache space. To change the disk cache directory or agent temporary storage location: Use the agents ecconfig command:
ecconfig -tempdir <newtempdir>
Note: You must specify a full PATH to the directory you want to use. Each agent on the host creates a unique subdirectory within the disk cache/temporary storage location, so they do not conflict with each other. Use the clusterexec command (run on either the Cluster Manager or the build server) to change all agents at once:
clusterexec --cm=<YOURCM> ecconfig -tempdir <newtempdir>
You must restart the agents for your changes to take effect:
clusterexec --cm=<YOURCM> restartAgent
Note: After specifying a different disk cache/temporary storage location, you may switch back to the default location listed at the top of this section. To do this, use ecconfig -tempdir with an empty string [""] as the location.
2-8
Linux Kernel Performance Note

Systems using kernel versions prior to 2.6.32-25 (particularly Ubuntu 10.04) may encounter reduced performance on both ext3 and ext4 filesystems. Affected kernels may encounter the following: widely variable agent availability (lots of going in and out of the penalty box) contention over the ecagent.state file hung_task_timeout_secs messages in system dmesg logs slower builds (with unexplained variances)
Upgrading the kernel may require you to reinstall various kernel modules such as video drivers, efs, and vm-tools. You can do so by running: apt-get dist-upgrade and then rebooting.
Planning for Grid Use

If you plan to use a host grid in conjunction with ElectricAccelerator, here is a planning checklist: Choose a machine for Cluster Manager. This machine will use the grid as any other client-only host. If you are upgrading an existing Cluster Manager, you must install the grid client-only productand ensure it is 32-bit only. Important: The Solaris x86-64 Cluster Manager cannot integrate with LSF. Choose hosts within the grid to run your builds. In general, these are machines you already use for software builds. ElectricAccelerator will use these machines in parallel to run builds, but machine availability is controlled by the grid management software. Electric Make allows you to select a subset of these machines using grid resource query strings. (See the ElectricAccelerator Electric Make Users Guide, Electric Make Command-line Options and Environment Variables chapter for information on the emake -emake-resource= parameter.) Choose machines for Electric Make. If you will be running Electric Make within the grid, you must install Electric Make on those hosts. Select or create a user ID to run Cluster Manager. Important: This user ID must be set up with appropriate permissions and able to execute grid commands. Note: If this is a UNIX user ID, you may need to run, for example, profile.lsf in your shell startup script. If this is a Windows user ID, you may need to go to Control Panel > Administrative Tools > Services. Right-click the ElectricAccelerator Cluster Manager service and go to Properties. Click the Log On tab. Change Local System Account to This account. Type-in the user ID and password for the user account. Select a queue for ElectricAccelerator. This queue must be allowed to submit jobs that request exclusive host use (bsub x option) or a queue that specifies HJOB_LIMIT=1. Set up the queue so jobs can be submitted on any platform where you intend to use Electric Make. For example, if your software builds are on Linux and Windows, the queue must allow jobs on either platform.
Planning for Grid Use
2-9
2-10
3
General Information
This chapter describes all versions of the ElectricAccelerator installation process. If you are upgrading a previously installed Accelerator version, follow the instructions in Chapter 4, Upgrading ElectricAccelerator Components. You can install the software using a graphical user interface or an interactive command-line interface (for Linux and Solaris), or by performing a non-interactive command-line installation. All methods are documented in this chapter. The three methods for installing Accelerator are: User Interface - This is a set of installation screens that provides click-through automation and prompts for information you need to supply. Command-line - Use this method if you prefer using an interactive command-line for the installation process. This method is available only on Linux machines. Silent - This is a non-interactive command-line installation. You may find this installation method preferable for installing multiple Electric Agents.
Read the procedures thoroughly before attempting to install, configure, or uninstall any component. Note: Installing any component completely replaces the current installation on that machine. Only one ElectricAccelerator installation can exist on a machine and it is whatever combination of components were chosen from the most recent install. For example, installing the Cluster Manager on a machine with the Electric Agent, results in a machine with Cluster Manager only, not a machine with the Electric Agent and Cluster Manager.
Installation Notes
Installing from the Cygwin shell If you choose to run the installer from the Cygwin shell, be advised of the following: Before running the installer, disable UAC, or start the Cygwin shell using the Run as Administrator menu item (right-click the Cygwin desktop icon). Running the installer with UAC enabled may result in a permission denied error. This is applicable for all Windows versions that use UAC (Windows 7, Windows Server 2008 R2, and Windows Vista). You may encounter issues when running the installer from the Cygwin /tmp directory. Electric Cloud recommends running the installer from a different directory. This is applicable for all Windows versions.
Antivirus software Some antivirus software may affect the installer. Turn antivirus software off during installation. If antivirus software is running when you start the installer, you may receive an error dialog. The antivirus software may have reported ElectricAccelerator files as a virus and removed them from the temp location. As a workaround, turn off the antivirus software and rerun the installer. Installing from a network drive On Windows, if you invoke the installer from a network drive, you may receive an Unknown Publisher security warning. You can disregard this warning and proceed with installation.
3-1
umask Electric Cloud recommends umask 0022. Do not set a different umask during installation. Absolute path for Solaris On Solaris systems, you must use an absolute path for the installation directory. mysqlcheck By default, mysqlcheck looks for my.cnf in /etc and ~/.my.cnf for configuration information. The installer does not currently copy my.cnf to /etc, causing mysqlcheck to fail. You must add the following to the mysqlcheck command line parameter: --defaults-file=<path to my.cnf> For example: mysqlcheck --defaults-file=/opt/ecloud/i686_Linux/mysql/my.cnf -o ecloud
User Interface Installation Method

Cluster Manager
Cluster Manager is a web server and can be installed on any networked machine with access to Electric Make and the cluster hosts, or on the main build machine where Electric Make is installed. Note: Install only one copy of Cluster Manager, regardless of the number of hosts in the cluster or the number of machines with Electric Make installed. Electric Make is installed by default when Cluster Manager is installed. If you are overwriting a previously installed ElectricAccelerator version, follow upgrading instructions in Chapter 4 of this document before attempting to install the new version.
IMPORTANT
On Windows Server 2008 R2, you may encounter a Not Responding error during install. Electric Cloud recommends waiting for up to 10 minutes for the install to continue normally. Installing Cluster Manager Make sure you log in as root or Administrator (You must be a member of the Administrator groupAdministrator privileges are not sufficient.) Note: On Windows, if you are running rdp on the target Cluster Manager server, ensure rdp is in installation mode: change user/install. 1. Double-click the ElectricAccelerator-<version> installer file to start installation. (For Windows systems running Vista or later, the administrator user must right-click the installer and select Run as administrator.) Note: It may take a few minutes to extract the installation packages to your machine before you see the installation wizard. Also, during installation, if you see a Windows security alert pop-up, click unblock and continue. 2. 3. For Windows, ElectricAccelerator requires the Microsoft Visual C++ 2005 Redistributable. If it is already installed, select the checkbox. Click Next to continue. When the Welcome screen appears, click Next to continue to the Setup Type screen.
3-2
4.
Select Cluster Manager (Electric Make also installs automatically with Cluster Manager).
Click Next after making your selection. 5. On the Choose Destination Location screen, accept the default installation directory (C:\ECloud for Windows or /opt/ecloud for Linux and Solaris) or browse to select an alternative directory. If you want to install Electric Make in a non-default location, use the same location on all agent hosts and on the Cluster Manager host. Note: Avoid selecting an alternative directory that includes spaces in the name. Spaces can create problems when configuring connections with other command-line-based components.
Click Next.
3-3
6.
If the installer cannot locate a PDF viewer, it will prompt you to browse for one. If you wish, browse for a PDF viewer to use.
Click Next. 7. On the Base Setup screen, choose whether you want to install Electric Runner client applications.
Click Next.
3-4
8.
On the Cluster Manager screen, enter Cluster Manager configuration options: Accept the default ports or type-in alternative port numbers if the defaults are already in use. For example, IIS and Apache also use port 80 by default. Accept the default to keep old log files or select the checkbox to remove old log files. Accept the default [checked checkbox] to leave web server log rotation turned on or clear the checkbox to turn off log rotation. Important - Log rotation may affect Cluster Manager performance Select the type of database to use. Note: If you do not use the default local MySQL database, the database must already exist and you must be able to connect to it. The installer does not validate database connections.
Click Next. 9. On the next Cluster Manager screen, continue to enter Cluster Manager configuration options: You can change the Cluster Manager admin password or accept the default password (changeme). You do not need to migrate the existing database or backup the local MySQL database if this is your first Cluster Manager installation. Fill-in the user name or choose a user that the Cluster Manager service should run as or leave blank. Choose a password for the Cluster Manager service user or leave blank.
Note: If you plan to use a host grid, the user selected for the Cluster Manager Service User must be fully enabled to start and stop grid jobs.
3-5
Click Next. 10. On the Cluster Manager Database screen, type-in the Cluster Manager database port number. For MS SQL, use port 1433. If you did not select MySQL-Local as your database type, the following additional fields are available:
Database Host/IP Address Database User Database Password Database Name (Do not use a . (period) in the name.)
Click Next. 11. When the Start Copying Files screen appears, click Next.
3-6
12. The Installing screen displays while installation is completing. When installation is finished, the Complete screen displays.
Click Finish. Installation is complete. The installation log file is in the install directorys root, C:\ECloud or /opt/ecloud, by default. If Apache fails to start properly after a fresh Cluster Manager install, reboot the system.
Electric Agent/EFS
Electric Agent/EFS software must be installed on each machine in the cluster. Electric File System (EFS) and Electric Agent (collectively, the Agent) are installed simultaneously on each host machine during Electric Agent/EFS installation. Multiple instances of Electric Agent/EFS pairings can be set up to run in parallel on a host. For example, if you have a multiprocessor machine, you may want to set up an Agent for each processor. More information on running multiple Agents is available in the ElectricAccelerator online help. Follow upgrading instructions in Chapter 4 of this document if you are upgrading a previous Electric Agent installation. Your tool chain should be installed on each agent host. You can virtualize the tool chain in some cases, but this can be tricky especially when the Windows registry is involved. For performance reasons, it is better to install the tool chain on each agent host. Many companies use a ghosting software for this purpose. Important: Ghosting with the Electric Agent already installed is not recommended. Additional information for Windows For Windows Vista and Windows Server 2008 R2, the installer automatically does the following: Disables the Windows error reporting service. Sets HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\NtfsDisableLastAccessUpdate to 0. The default value for Windows Vista and Windows Server 2008 R2 is 1. Disables User Account Control (UAC) for 64-bit versions. Disabling UAC avoids popup windows for applications that require administrator privileges. If UAC is enabled, application registry access is redirected to each users virtual store, even if it runs under the Administrator account.
Note: If Symantec AntiVirus software is installed on your intended agent machines, disable it before installing Electric Agent/EFS to avoid serious filesystem conflicts. If Symantec AntiVirus cannot be disabled, put C:\ECloud in an exclusion list or disable the AutoProtect feature. Electric Cloud generally considers agent machines safe because they are internal machines residing behind a firewall. If you need more information, contact Electric Cloud technical support.
3-7
Installing Electric Agent/EFS Make sure you log in as root or Administrator (You must be a member of the Administrator groupAdministrator privileges are not sufficient.) Note: On Windows, if you are running rdp on this host, ensure rdp is in installation mode: change user/install. 1. Double-click the ElectricAccelerator-<version> installer file to start installation. (For Windows systems running Vista or later, the administrator user must right-click the installer and select Run as administrator.) Note: It may take a few minutes to extract the installation packages to your machine before you see the installation wizard. Also, during installation, if you see a Windows security alert pop-up, click unblock and continue. 2. 3. 4. For Windows, ElectricAccelerator requires the Microsoft Visual C++ 2005 Redistributable. If it is already installed, select the checkbox. Click Next to continue. When the Welcome screen appears, click Next to continue to the Setup Type screen. On the Setup Type screen, select Electric Agent.
Click Next. 5. On the Choose Destination Location screen, accept the default installation directory (C:\ECloud for Windows or /opt/ecloud for Linux and Solaris) or browse to select an alternative directory. Note: Avoid selecting an alternative directory that includes spaces in the name. Spaces can create problems when configuring connections with other command-line-based components. Click Next.
3-8
6.
Click Next. 7. 8. On the Base Setup screen, choose whether you want to install Electric Runner client applications, and click Next. On the Electric Agent screen, enter options for the locally installed Electric Agent/EFS. Type-in the Cluster Manager host name or IP address. Accept the default Cluster Manager port 8030 or type-in the alternative port you supplied during the Cluster Manager server installation. Enter the number of Agents to runthe installer calculates the default number of Agents based on the effective number of CPUs on the machine. Default=1, if one CPU is present. If more than one CPU is present, the default value is the number of effective CPUs. Accept the default agent temporary directory, or choose an alternative. For the Secure Agent Console Port checkbox, accept the default if you do not plan to use the secure port, or select the checkbox if you want to use the secure port. If this agent machine is part of the grid, select the Host is part of Platform Computing LSF Grid checkbox. Accept the default to keep all existing log files or select the checkbox to Remove existing log files. Select the checkbox to Reboot host if needed. Accept the default to install the Electric Runner service, or clear the checkbox to not install this service. Note: eRunner is a helper service normally installed on all agent machines. This service listens for commands to execute on agents, facilitating administration tasks. For example, with eRunner you can upgrade all agents at the same time, remotely.
3-9
Click Next. 9. On Windows, select the user accounts you will use to run agents. Accept the default ECloud Internal User or select Existing User. If you select Existing User, click Add User to add a user account.
Click Next.
3-10
10. On the Electric Runner Server screen, enter options for the Electric Runner server. Accept the default Electric Runner Server port, or type-in an alternative. Accept the default to leave old Electric Runner logs, or select the checkbox to remove old logs.
Click Next. 11. When the Start Copying Files screen appears, click Next. 12. The Installing screen displays while installation is completing. When installation is finished, the Complete screen displays. Click Finish. Installation is complete. The installation log file is in the install directorys root, C:\ECloud or /opt/ecloud, by default. Note: Installing ElectricAccelerator on Windows systems may unset the environment variable JAVA_HOME. Reset JAVA_HOME manually.
Electric Make
Electric Make can be installed on a networked machine or on a shared file server accessible to other build machines. Wherever Electric Make is installed, it must have access to the Cluster Manager machine and Agents on the cluster host machines. After Electric Make is installed, configure Electric Make for your build environment and enable communication with Cluster Manager. For information on enabling communication with Cluster Manager, see Configuring ElectricAccelerator in the ElectricAccelerator Electric Make Users Guide. Follow upgrading instructions in Chapter 4 of this document if you are upgrading a previous Electric Make installation.
3-11
Installing Electric Make Make sure you log in as root or Administrator (You must be a member of the Administrator groupAdministrator privileges are not sufficient.) Note: On Windows, if you are running rdp on this host, ensure rdp is in installation mode: change user/install. 1. Double-click the ElectricAccelerator-<version> installer file to start installation. (For Windows systems running Vista or later, the administrator user must right-click the installer and select Run as administrator.) Note: It may take a few minutes to extract the installation packages to your machine before you see the installation wizard. Also, during installation, if you see a Windows security alert pop-up, click unblock and continue. 2. 3. 4. For Windows, ElectricAccelerator requires the Microsoft Visual C++ 2005 Redistributable. If it is already installed, select the checkbox. Click Next to continue. When the Welcome screen appears, click Next to continue to the Setup Type screen. On the Setup Type screen, select Electric Make.
Click Next. 5. On the Choose Destination Location screen, accept the default installation directory (C:\ECloud for Windows or /opt/ecloud for Linux and Solaris) or browse to select an alternative directory. Ensure the Electric Make path matches the path used for the installed Agent. Note: Avoid selecting an alternative directory that includes spaces in the name. Spaces can create problems when configuring connections with other command-line-based components. Click Next.
3-12
6.
Click Next 7. 8. 9. On the Base Setup screen, choose whether you want to install Electric Runner client applications, and click Next. When the Start Copying Files screen appears, click Next. The Installing screen displays while installation is completing. When installation is finished, the Complete screen displays. Click Finish. Installation is complete. The installation log file is in the install directorys root, C:\ECloud or /opt/ecloud, by default. Note: Installing ElectricAccelerator on Windows systems may unset the environment variable JAVA_HOME. Reset JAVA_HOME manually
Additional Install Options

The installer has the following additional install options: Electric Runner Client - The Electric Runner Client component installs platform-independent tools (clusterexec, clusterupload, and clusterdownload) that allow you to perform operations across all hosts simultaneously. The tools allow you to: Start and stop agents Reboot hosts Run commands on hosts Upload files Download files
3-13
Electric Runner Server - The Electric Runner Server component installs the server side (erunnerd) on agents to allow them to serve requests from tools. If you decided not to install eRunner during Cluster Manager installation, you do not have access to these tools. Custom - A custom install allows you to install multiple components at once.
Note: The online help system contains additional information about Electric Runner. Go to the Cluster Manager Administration Tools section in the ElectricAccelerator Installed Tools/Files topic.
The installation of all ElectricAccelerator components is now complete. If you do not plan to use the Grid Host Manager, skip to Chapter 5, Initial Configuration Tasks, to complete several tasks before you begin using the product. If you are planning to use the Grid Host Manager, go to Chapter 6, Configuring Cluster Manager for the Grid, before proceeding to Chapter 5.
Interactive Command-line Installation Method

Cluster Manager
Cluster Manager is a web server and can be installed on any networked machine with access to Electric Make machines and cluster hosts, or on the main build machine where Electric Make is installed. Note: Install only one copy of Cluster Manager, regardless of the number of hosts in the cluster or the number of machines with Electric Make installed. Electric Make is installed by default when Cluster Manager is installed. If you are overwriting a previously installed ElectricAccelerator version, follow upgrading instructions in Chapter 4 of this document before attempting to install the new version. Installing Cluster Manager 1. Obtain a copy of the installer (ElectricAccelerator-<version>). 2. 3. 4. 5. Log in as root. Run chmod +x on the installer to ensure it is executable. Run ./<installer filename> --mode console to start ElectricAccelerator installation. When the welcome message displays, enter 3 to select the Cluster Manager package. Press Enter. For example,
Please enter the appropriate number to choose the package: 1 - Electric Agent/EFS Installs Electric Agent/EFS on this machine. 2 - Electric Make Installs Electric Make on this machine. 3 - Cluster Manager Installs Cluster Manager and Electric Make on this machine. 4 - Electric Runner Client Installs Electric Runner Client component to run commands on the cluster. 5 - Electric Runner Server Installs Electric Runner Server to execute cluster commands on the local machine.
After choosing option 3, provide the following Cluster Manager configuration information. Accept the defaults or type-in alternatives. Notes: 1. Turning on log rotation may affect Cluster Manager performance. 2. If the installer cannot locate a PDF viewer, it will prompt you to provide a path to one.
3-14
Where do you want to install ElectricAccelerator? [opt/ecloud] Install Electric Runner client apps? [y/n] Cluster Manager HTTP port: [80] Cluster Manager HTTPS port: [443] Cluster Manager Accelerator Server port: [8030] Cluster Manager Secure Accelerator Server port: [8031] Remove old logs [y/N] Rotate Cluster Manager logs [y/N] Database Type: [MySQL-Local] Cluster Manager Service User: [eacmuser] Cluster Manager admin password: [changeme] Migrate existing database [y/N] Backup local MySQL database [y/N] Database port: [0] Database Host/IP address: [localhost] Database User: [ecloud] Database Password: [ecloud] Database Name: [ecloud]
Note: Do not use a . (period) in the database name. The installer installs Cluster Manager using the configuration details you entered, followed by Installation complete when the install completes. The installation log file is in the install directorys root, /opt/ecloud by default. Note: Linux operating systems contain a 1024 default file descriptor limit for each process. However, this does not mean 1024 builds can be run concurrently. Depending on the size of your builds, you may be able to run only 300-400 builds concurrently because of other file descriptor activity and the collection activity between eMake and the Cluster Manager. If you must run more than 300-400 builds simultaneously, increase the default file descriptor limit. If Apache fails to start properly after a fresh Cluster Manager install, reboot the system. Installing Cluster Manager for a grid environment Cluster Manager is the only ElectricAccelerator component that communicates directly with the host grid.
IMPORTANT
The user ID used to install Cluster Manager and the user ID selected for the Cluster Manager Service User must be fully enabled to start and stop grid jobs. The Cluster Manager installation process is the same whether or not you plan to use a host grid.
Electric Agent/EFS
Electric Agent/EFS software must be installed on each machine in the cluster. Electric File System (EFS) and Electric Agent (collectively, the Agent) are installed simultaneously on each host machine during Electric Agent/EFS installation. Multiple instances of Electric Agent/EFS pairings can be set up to run in parallel on a host. For example, if you have a multiprocessor machine, you may want to set up an Agent for each processor. More information on running multiple Agents is available in the ElectricAccelerator online help. Note: Agent/EFS builds a kernel module during installation, so you may need to take this into consideration. Follow upgrading instructions in Chapter 4 of this document if you are upgrading a previous Electric Agent installation.
IMPORTANT
For RHEL 5, you must install the kernel-devel package version that matches the Linux kernel into which the modules will be loaded.
3-15
Installing Electric Agent/EFS 1. Obtain a copy of the installer (ElectricAccelerator-<version>). 2. 3. 4. 5. Log in as root. Run chmod +x on the installer to ensure it is executable. Run ./<installer filename> --mode console to start ElectricAccelerator installation. When the welcome message displays, enter 1 to select the Electric Agent/EFS package. Press Enter. After choosing option 1, provide Electric Agent/EFS configuration information. Accept the defaults or type-in alternatives. Use the Cluster Manager default server listening port 8030, or type-in the alternative port if you did not accept the default when you installed Cluster Manager. Select the number of Agents to run. The installer calculates the default number of Agents based on the number of virtual CPUs on the machine. For example, you may have one Agent per virtual CPU, a single dual-core CPU supports two Agents, three dual-cores support six Agents. Specify the Agent temporary directory. The default is /tmp. If you specify a different directory, it must already exist, otherwise the temporary directory defaults to /tmp. Regarding host grid usage In a grid environment, such as LSF, Agents are not bound to a Cluster Manager during installation. Instead, the grid management software tells the agents which Cluster Manager to talk towhich means the Cluster Manager host name or port number you may have specified will not be used. Decide whether to install Electric Runner. eRunner is a helper daemon normally installed on all agent machines. This daemon listens for commands to execute on agents, facilitating administration tasks. For example, with eRunner you can upgrade all agents at the same time, remotely.
Note: If the installer cannot locate a PDF viewer, it will prompt you to provide a path to one. The installer installs Electric Agent/EFS using the configuration details you provided, followed by Installation complete when the install completes. The installation log file is in the install directorys root, /opt/ecloud by default. Installing Electric Agent/EFS in a grid environment You must install Electric Agent/EFS on each machine in the grid that ElectricAccelerator will use. The actual installation process for Electric Agent/EFS is the same whether or not you use a gridexcept, you must answer yes (y) to any prompt that asks whether or not you plan to use a grid environment, such as LSF. Note: After Agent/EFS is installed, it remains dormant until the grid management software schedules an agent connect script to run on that host.
Electric Make
Electric Make can be installed on a networked machine or on a shared file server accessible to other build machines. Wherever Electric Make is installed, it must have access to the Cluster Manager machine and Agents on cluster host machines. After Electric Make is installed, configure Electric Make for your build environment and enable communication with Cluster Manager. For information on enabling communication with Cluster Manager, see Configuring ElectricAccelerator in the ElectricAccelerator Electric Make Users Guide. Follow upgrading instructions in Chapter 4 of this document if you are upgrading a previous Electric Make installation.
3-16
Installing Electric Make 1. Obtain a copy of the installer (ElectricAccelerator-<version>). 2. 3. 4. 5. Log in as root. Run chmod +x on the installer to ensure it is executable. Run ./<installer filename> --mode console to start ElectricAccelerator installation. When the installer welcome message displays, enter 2 to select the Electric Make package. Press Enter. Notes: 1. If you install Electric Make in a non-default location, ensure the same location is used for all agent hosts and the Cluster Manager host. 2. If the installer cannot locate a PDF viewer, it will prompt you to provide a path to one. The installer installs Electric Make using the configuration details you provided, followed by Installation complete when the install completes. The installation log file is in the install directorys root, /opt/ecloud by default.
Additional Install Options

The installer has the following additional install options: Electric Runner Client - The Electric Runner Client component installs platform-independent tools (clusterexec, clusterupload, and clusterdownload) that allow you to perform operations across all hosts simultaneously. The tools allow you to: Start and stop agents (In a multi-operating system environment, start and stop apply the requested action only to agents that have the same operating system as the machine where you ran clusterexec, unless overridden by --platform.) Reboot hosts Run commands on hosts Upload files Download files
Electric Runner Server - The Electric Runner Server component installs the server side (erunnerd) on agents to allow them to serve requests from tools. If you decided not to install eRunner during Cluster Manager installation, you do not have access to these tools. Custom - A custom install allows you to install multiple components at once.
Note: The online help system contains additional information about Electric Runner. Go to the Cluster Manager Administration Tools section in the ElectricAccelerator Installed Tools/Files topic.
Path Settings
All ElectricAccelerator components are installed in the /opt/ecloud directory. Scripts to add the necessary environment variables are installed in /opt/ecloud/<arch>/conf. arch is either:
i686_Linux for Linux, or sun4u_SunOS for Solaris
The scripts are called ecloud.bash.profile (for bash shells) or ecloud.csh.profile (for csh). You can source the appropriate file in your shell to ensure your PATH includes ElectricAccelerator libraries. The installation of all ElectricAccelerator components is now complete. If you do not plan to use the Grid Host Manager, go to Chapter 5, Initial Configuration Tasks, to complete several tasks before you begin using the product. If you plan to use the Grid Host Manager, go to Chapter 6, Configuring Cluster Manager for the Grid before proceeding to Chapter 5.
3-17
Silent Installation Method

If you are installing ElectricAccelerator on a series of identical machines (such as a series of cluster hosts), you can use the silent install method, which installs components automatically, without user interaction. Note: On Windows, if you invoke the installer from the command line, you may receive an Unknown Publisher security warning. You can disregard this warning and proceed with installation.
Installer Command Line Options

Use the following command line options when performing a silent install. The options are the same values a user would normally set through the installer interface. Use this format: <installer filename> [options]
Option --adminuserpassword [ARG] --agentallowreboot <Yes or No> --agentcmhost [ARG] --agentcmport [ARG] --agentinstallerunnerd <Yes or No> --agentislsfhost <Yes or No> --agentnumber [ARG] --agentpassword [ARG] --agentremovelogs <Yes or No> --agentsecureconsole <Yes or No> --agenttempdir [ARG] --agentuserlist [ARG] Description
The password to use for the admin user. Allow the installer to reboot the local machine if needed. The Cluster Manager machine name to connect to. The Cluster Manager port to connect to. Install the eRunner server on an agent machine. The local agent machine is an LSF host. The number of agents to set up on the local machine. The password to use for ECloudInternalUser (Windows). Remove old agent logs during install. Lock down the agent console. The temporary directory for all agent files. List of user/password pairs to be used as login accounts for agents (Windows). Perform a database backup of the local MySQL setup only. Remote database configurations are not backed up. Install the eRunner client apps. The Accelerator server port for unencrypted traffic. The Accelerator server port for encrypted traffic. The host machine that runs the database server. The name of the database to create on the database server. If you do not use the default local MySQL database, you must provide the name of an existing database. The user password to use when connecting to the database server. The port that the database server listens on. Use 1433 for MS SQL. Database to use for the Cluster Manager. Available values: mysql, mysqllocal, oracle, or mssql. The user name to use when connecting to the database server.
--backupdb <Yes or No>
--baseinstallerunner <Yes or No> --cmaccelport [ARG] --cmaccelsport [ARG] --cmdbhost [ARG] --cmdbname [ARG]
--cmdbpassword [ARG]
--cmdbport [ARG]
--cmdbtype [ARG]
--cmdbuser [ARG]
3-18
Option --cmhttpport [ARG] --cmhttpsport [ARG] --cmlogrotate <Yes or No> --cmmigratedb <Yes or No> --cmremovelogs <Yes or No> --cmserviceuser --cmserviceuserpassword --debug --debugconsole --erunnerdport --erunnerdremovelogs <Yes or No> --help --ignoreoldconf <Yes or No> --mode [ARG]
Description
The HTTP server port for unencrypted traffic. The HTTP server port for encrypted traffic. Rotate Apache logs. Preserve/migrate the existing Cluster Manager database. Remove old Cluster Manager logs during install. The user to use to run the Apache server. The password to use for the service user (Windows). Run the installer in debug mode. Run the installer with a debug console open. The port for eRunnerd to listen on. Remove old eRunnerd logs during install. Display this information. Ignore the previous configuration. Set the mode in which to run the installer. Available values: console, silent, or standard. For a console login, standard and console are identical. For a GUI machine, standard brings up the UI. You can use console in a Unix X Window environment to force the use of console mode.
--noredist <Yes or No>
Does not install the Microsoft Visual C++ 2005 Redistributable (Windows). The PDF reader you use. Set the installation directory. The property file from which to read installer options. The file from which to read installer responses. The file to write installer responses to when the installer exits. Set the temporary directory used by this program. Run the installer without installing any files. Perform the selected type of install. Available values: agent, cm, emake, erunner, erunnerd, or upgrade. The hostname for the Cluster Manager machine to upgrade. The Accelerator port for the Cluster Manager machine to upgrade. Display installer version information.
--pdfreader [ARG] --prefix [ARG] --propertyfile [ARG] --response-file [ARG] --save-response-file [ARG] --temp [ARG] --test --type [ARG]
--upgradehost [ARG] --upgradeport [ARG]
--version
3-19
Creating an Installer Properties File

An installer properties file is a text file that defines installation parameters. These parameters are the same values a user would normally set through the installer interface or command line. To create an installer properties file: 1. Run an installation with your desired settings. This creates a properties file (install.props) in the top-level install directory. 2. Use the resulting properties file for subsequent silent installs of the same component type.
Components are installed individually so you must create an installer properties file for each ElectricAccelerator component you intend to install. The following tables detail the variables contained within properties files. The variables are in the form of
<name>=<value>.
Cluster Manager variables:

Variables EC_CM_ACCELPORT= EC_CM_ACCELSPORT= EC_CM_BACKUPDB= Possible Values 8030 (default) or type an alternative 8031 (default) or type an alternative n (default), y Description
Sets Cluster Manager server port number. Sets Cluster Manager server secure port number. Backs up the local MySQL database only. Remote databases are not backed up. Sets the Cluster Manager database host. Sets the name of the database. Sets the user to run the database. Sets the database password. Sets the user to run the Cluster Manager service. If not specified, the account Cluster Manager runs as is used. Sets the Cluster Manager admin user password. Sets the database listening port. Sets the type of database to use. Sets Cluster Manager web interface port number. Sets Cluster Manager web interface secure port number. Sets log rotation to on (y) or off (n). Migrates the database; this value is meaningful only if performing an upgrade. Removes Cluster Manager log files. If not, the install appends to them.
EC_CM_DBHOST= EC_CM_DBNAME= EC_CM_DBUSER= EC_CM_DBPASSWORD= EC_CM_SERVICEUSER= EC_CM_SERVICEUSER_PASSWORD= EC_CM_ADMINUSER_PASSWORD= EC_CM_DBPORT= EC_CM_DBTYPE= EC_CM_HTTPPORT= EC_CM_HTTPSPORT= EC_CM_LOGROTATE= EC_CM_MIGRATEDB=
Defaults to localhost Defaults to ecloud Defaults to root Defaults to ecloud Existing LDAP user or local user Password for the specified user name Password for the Cluster Manager admin user.
3306 (default) or type an alternative MySQL-Local (default), MySQL, Oracle, MSSQL 80 (default) or type an alternative 443 (default) or type an
alternative
y (default), n n (default), y
EC_CM_REMOVE_LOGS=
n (default), y
3-20
Agent variables:
Variables EC_AGENT_AGENT_NUMBER= EC_AGENT_CMHOST= Possible Values Description
Between 1 and 5, but could be higher Example, 192.205.2.19 or

winlong-cm
Sets the number of Agents to run on the cluster host. Sets the Cluster Manager hostname or IP address for this host. Not required if using LSF. Sets the Cluster Manager server port number for this host. Not required if using LSF.
y installs eRunnerd on agent machines.
EC_AGENT_CMPORT=
8030 (default) or type the known value y (default), or n n (default), or y n (default), or y
EC_AGENT_INSTALL_ERUNNERD= EC_AGENT_IS_LSF_HOST= EC_AGENT_REBOOT=
Indicates if the Agent is on the LSF grid. Determines whether or not to reboot after installing Agent/EFS. For Windows, if you use n, the installer does not restart the Agent service; reboot the host to ensure EFS works properly. Windows may prompt before the host is rebooted. For Solaris/Linux, the machine does not reboot unless required, even when you specify EC_AGENT_REBOOT=y. Removes agent log files. If not, the install appends to them.
y requires an agent-generated key to be
EC_AGENT_REMOVE_LOGS= EC_AGENT_SECURE_CONSOLE_PORT=
n (default), or y n (default), or y
entered before commands will run on the agent console port.

EC_AGENT_TEMPDIR=
Windows default:
C:\WINDOWS\temp UNIX default: /tmp
Sets the agent temporary directory.
EC_AGENT_WINUSER_PASSWORD=
Sets the password for ECloudInternalUser
Additional variables:
Variables EC_ERUNNERD_PORT= EC_ERUNNERD_REMOVE_LOGS= EC_BASE_INSTALL_ERUNNER= Possible Values 2411 (default) or type an alternative n (default), or y y (default), or n Description
Sets the eRunnerd server port. Removes eRunnerd logs. If not, the install appends to them. Installs eRunner client applications on Cluster Manager and Electric Make machines. Does not install the Microsoft Visual C++ 2005 Redistributable (Windows). Sets a list of username/password pairs to be used. The host name of the Cluster Manager machine to upgrade.
EC_BASE_NOREDIST= EC_WINDOWS_USER_LIST= EC_UPGRADE_CMHOST
n (default), or y
3-21
Variables EC_UPGRADE_CMPORT EC_PROPERTY_FILE EC_IGNORE_OLDCONF Debugging Testing ShowConsole InstallMode InstallDir InstallType
Possible Values
Description
The Accelerator port of the Cluster Manager machine to upgrade. Sets the property file from which to read installer options. Ignores the previous configuration. Runs the installer in debug mode. Runs the installer without installing any files. Runs the installer with the debug console open. Sets the mode for running the installer. Example: C:\ECloud or
/opt/ecloud Electric Make, Electric Agent, Cluster Manager, Electric Runner Client, Electric Runner Server, Custom
Sets the installation directory. Sets the type of installation to perform.
UnixPDFReader
Path to PDF reader
Sets the PDF reader to use.
Automating a Linux/Solaris Silent Install

Make sure you have a properties file (install.props) created by a successful installation. To perform a silent install: 1. Log in to the remote machine as root. 2. Invoke the installer:
# ./<installer filename> --mode silent --propertyfile <properties file>
Automating a Windows Silent Install

Make sure you have a properties file (install.props) created by a successful installation. To perform a silent install: 1. Log in to the remote machine as Administrator. 2. Invoke the installer in a DOS shell:
<installer filename> /mode silent /propertyfile <properties file>
Note: Supply the full path to the properties file. If you are performing a silent upgrade on an agent host by running the install on the host itself, you may be prompted before the machine is rebooted. This prompt occurs if others are logged in to the machine when you run the agent upgrade.
3-22
Installed Tool Files

ElectricAccelerator installs various tools on the Cluster Manager server, Agent/EFS hosts, and Electric Make machines. For a complete list of these files, their description/purpose, and location, see the ElectricAccelerator online help topic, Installed Tools/Files. Note: In addition, if any of your tool applications (compilers and so on) are installed locally, Electric Cloud recommends that you install the same version of each application on all machines and keep the version in sync.
Post-Installation Activities
Running eccheckenv
After installing Electric Make on a new machine, Electric Cloud recommends running eccheckenv to verify the environment is suitable. Also run eccheckenv after making significant changes to any machine running Electric Make.
Eccheckenv examines a number of features in the environment. If a problem is found, eccheckenv reports the problem and suggests a solution.
Microsoft Visual Studio

If you intend to use ElectricAccelerator to build Microsoft Visual Studio projects... Running eccheckvsinst Run eccheckvsinst to check agent installations that will be involved in Visual Studio-based builds. The utility is located in C:\ECloud\i686_win32\unsupported. Invoke the utility on the target installations and redirect the output to a text file. Repeat on all agents in the cluster. Then use a text diff tool to compare the various files. There should be no difference except the hostname (as noted in Notes to ensure a consistent build environment: on page 2-4). eccheckvsinst > eccheckvsinst.agent1 eccheckvsinst > eccheckvsinst.agent2 diff eccheckvsinst.agent1 eccheckvsinst.agent2 Before building the Visual Studio project Before you can use ElectricAccelerator to build your Visual Studio project, you must install Visual Studio on each agent host, and then log in and run devenv as the user that owns the respective agent processes (usually ECloudInternalUser1, ECloudInternalUser2, and so on). You can use the psexec tool (downloadable from http://technet.microsoft.com/en-us/sysinternals/bb896649.aspx) to eliminate the need to log in and log out multiple times. Using this tool is more efficient because Visual Studio stores user settings in the registry and creates files in My Documents. Also, ensure you can build your solutions/projects with the Visual Studio setup on each host. If you install Visual Studio after installing ElectricAccelerator, register the Visual Studio add-in by running install_ecaddin<NN>.bat where NN is 70, 71, 80, or 90, depending on your Visual Studio version. If you are using Visual Studio 2005 or later, reduce the number of parallel builds Visual Studio performs: 1. 2. 3. In Visual Studio, select Tools > Options. In the Options dialog, open Projects and Solutions > Build and Run. Set maximum number of parallel project builds to 1.
The Solution Support Add-in Technical Notes contains additional information about using ElectricAccelerator with Visual Studio. Uninstalling Microsoft Visual Studio Uninstall the add-in by running uninstall_ecaddin<NN>.bat where NN is 70, 71, 80, or 90, depending on your Visual Studio version. These bat files are in the ElectricAccelerator bin directory.
Installed Tool Files
3-23
Installing an Apache Server Certificate

Description After installation, you may want to create a new Apache certificate. By default, ElectricAccelerator generates a temporary self-signed certificate during installation. This certificate is used whenever a browser makes an HTTPS connection to the Apache server. During ElectricAccelerator installation, Apache is configured to look for a private key file named $HOSTNAME.key and a certificate named $HOSTNAME.crt. These files are in $DATADIR/apache/conf/ssl.key and $DATADIR/apache/conf/ssl.crt respectively. $DATADIR is the directory where ElectricAccelerator data files were installed. To find these files on Windows, go to
C:/ECloud/i686_win32.
Because the certificate is self-signed, browsers complain that it is an untrusted certificate. Most organizations will want to generate a new certificate signed by a recognized certificate authority (CA) to get rid of the browser warnings. The following list summarizes the process: Generate a new certificate and private key Send the request to the CA Install the signed certificate
Generate a new certificate and private key Locate openssl binary and openssl.cnf in $DATADIR/apache/bin/ssl. Copy openssl.cnf into a temporary directory, then generate a new private key and certificate. Note: Enter the appropriate information for your organization when prompted. The most important field is the Common Name, which is the fully qualified name of the host running the Apache server. This name must match the host portion of the URL used to connect to the ElectricAccelerator web interface.
$ openssl req -config openssl.cnf -new -out $HOSTNAME.csr Loading 'screen' into random state - done Generating a 1024 bit RSA private key .......++++++ .......................................................++++++ writing new private key to 'privkey.pem' Enter PEM pass phrase: Verifying - Enter PEM pass phrase: ----You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields, but you can leave some blank. For some fields, there will be a default value, if you enter '.', the field will remain blank. ----Country Name (2 letter code) []:US State or Province Name (full name) []:California Locality Name (eg, city) []:Mountain View Organization Name (eg, company) []:Electric Cloud Organizational Unit Name (eg, section) []: Common Name (eg, your websites domain name) []:myserver.mycompany.com
Note: The Common Name is the fully qualified name of the host machine where you want the certificate.
Email Address []:[email protected]
Note: This email address should be for the user to contact if there are issues concerning the certificate.
Please enter the following 'extra' attributes to be sent with your certificate request. A challenge password []:
3-24
This information generates a new private key in privkey.pem and a signing request in $HOSTNAME.csr. To use the private key without having to enter a challenge password each time the server starts, issue the following command to strip out the password:
$ openssl rsa -in privkey.pem -out $HOSTNAME.key Enter pass phrase for privkey.pem: writing RSA key
This creates a PEM encoded private key file named $HOSTNAME.key without the password. Send the request to the CA The $HOSTNAME.csr file generated in the previous section is a request for a certificate authority to sign the certificate. When you send this file to the CA, the CA verifies the information inside and sends you a signed certificate in response. The signed certificate includes the original certificate and the signature of the CA. Name the signed certificate '$HOSTNAME.crt'. Install the key and signed certificate Copy the two files, $HOSTNAME.key and $HOSTNAME.crt, into $DATADIR/apache/conf/ssl.key and $DATADIR/apache/conf/ssl.crt, then restart the Apache server. Ensure the $HOSTNAME.key file is readable only by the user running the Apache server process. Also, delete the contents of the temporary directory you created because this directory contains the cryptographic information used to generate the key.
Testing the Cluster Manager Installation

After you provide the license file, launch a web browser and go to localhost (for Windows) or the hosts IP address (for UNIX). If the install was successful, the ElectricAccelerator home page appears.
Uninstalling ElectricAccelerator
Use the ElectricAccelerator uninstaller to remove ElectricAccelerator software components from any machine. Note: The uninstaller removes all ElectricAccelerator components from a machine at the same time. If you are uninstalling as part of an upgrade procedure, follow the instructions for upgrading individual components. See upgrading instructions in Chapter 4 of this document. Uninstalling all ElectricAccelerator components from a Linux or Solaris machine 1. Log in as root and change to the tmp directory by entering # cd /tmp 2. Copy the uninstaller uninstall-accelerator to the /tmp directory by entering: for Linux - # cp /opt/ecloud/uninstall-accelerator /tmp for Solaris - # cp /opt/ecloud/uninstall-accelerator /tmp Invoke the uninstaller by entering ./uninstall-accelerator Enter the default y to confirm the uninstall. Press Enter. When uninstall is complete, a message similar to the following Cluster Manager message will display:
3. 4.
Note: The ElectricAccelerator uninstaller does not remove files created after initial installation. If you want to remove all files, go to the /opt/ecloud directory, which includes the install directory, and delete it manually. Ensure you also remove the file ecagent.conf. The files location for Linux - /etc/sysconfig/ecagent.conf and for Solaris - /etc/ecagent.conf.
Uninstalling ElectricAccelerator
3-25
Uninstalling all ElectricAccelerator components from a Windows machine There are two methods for uninstalling ElectricAccelerator: First method: 1. Go to the Electric Cloud installation directory and click on the uninstall-accelerator.exe file. Note: For Windows systems running Vista or later, the administrator user must right-click the uninstaller and select Run as administrator. 2. After uninstalling ElectricAccelerator, you may want to delete the ECloud directory to ensure all files are deleted.
Second method: 1. 2. 3. 4. From the Control Panel, choose Add or Remove Programs. Select ElectricAccelerator from the list and click Change/Remove to open the uninstaller. Click Yes to confirm the uninstall. If Electric Agent/EFS was installed, you may be prompted to reboot.
Note: The ElectricAccelerator uninstaller will not remove files created after installation. If you want to remove all ElectricAccelerator files, go to the C:\ECloud directory and delete it manually. Performing a Linux/Solaris silent uninstall Silent uninstall is performed by adding a flag to the uninstaller. When you invoke the uninstall command:
./uninstall-accelerator --mode silent
No second opportunity to confirm the uninstall request is displayed. The uninstall begins immediately. Performing a Windows silent uninstall Run the following command to perform a Windows silent uninstall:
uninstall-accelerator.exe /mode silent
3-26
Invisible Body Tag
4
You can upgrade ElectricAccelerator software components using a traditional interfacetext-based for Linux/Solaris and GUI for Windows. You can also upgrade ElectricAccelerator using a silent install. Not all instructions are the same for each platform. Follow the instructions carefully for your particular platform. Ensure a build is not running before beginning a Cluster Manager or Agent upgrade. If you are changing Cluster Manager ports during the upgrade, Electric Cloud recommends closing your browser windows to avoid potential conflicts and to ensure your settings take affect. The Cluster Manager server and agent hosts must run the same version of ElectricAccelerator.
Upgrade Notes
Integrating Cluster Manager with Active Directory When you upgrade from ElectricAccelerator 4.4 or earlier to 4.5 or later, you must modify your Active Directory XML file (the name you selected or ad_template.xml) located in <ECloud install>/<arch>/conf. Change the following:
<bean id="adDirectoryProvider" class="com.electriccloud.security.ldap.ActiveDirectoryProviderImpl">
to this:
<bean id="adDirectoryProvider" class="com.electriccloud.security.ldap.ActiveDirectoryProvider">
Remote database configuration upgrade triggers warning The Cluster Manager can connect to a remote database (for example, MySQL on a different machine), and the user can shut down the local mysql by issuing the /etc/init.d/clustermanager stopmysql command on UNIX or by stopping the mysql service on Windows. During the upgrade, the installer cannot reach the local database (because it is shut down already), so it gives this prompt:
Unable to contact MYSQL database. Please enter a correct username/password: MYSQL Root User (empty=no database migration):
Leaving the value empty allows the installer to finish. Upon completion, a warning message is displayed. This is the expected behavior and does not indicate an actual issue. Duration of database schema upgrade triggers extraneous failure message During the ElectricAccelerator upgrade process, the installer attempts to connect to the Cluster Manager. Because the Cluster Manager handles the database schema upgrade, having a large database may cause the Cluster Manager to take a long time to finish the upgrade. A failure message stating that the Cluster Manager failed to come up may be displayed. This dialog does not indicate an actual failure, it means only that the Cluster Manager is still processing the schema upgrade. The Cluster Manager will load after the schema upgrade completes.
4-1
Upgrading Multiple Agents on Cluster Hosts

To upgrade multiple agents, follow this procedure: 1. 2. Copy installer executables to the <ECloud install>/<arch>/bin directory. From the existing Cluster Manager installation directory, run the following:
ecclusterupgrade
If you want to limit which operating systems to update, run

ecclusterupgrade --targetos=<os> --targetos=<os> indicates which operating system to update, which allows you to update any operating
system type from any operating system by specifying the desired target operating system. Available values are
windows, linux, and solaris.
3.
Depending on your setup, you may require the following options as well:
--agentinstalldir=<path> indicates the agents install location. The upgrade expects that all agents you
want to upgrade have the same install location. If this is not true, you must run the script multiple times using the relevant --agentinstalldir path names. You must specify the --hosts option also to limit the upgrade to those machines that use the non-standard agent install directory.
--installerdir=<path> specifies the location for the installer. You can use this option instead of copying the installer to the bin directory as mentioned in step 1. Generally, the installer is placed in the bin directory. You must specify this option if the installer is not in this directory.
If you have multiple installer versions, you can use:

--installerversion=<version> to select the version you want to use. This option is needed only if there are multiple installer versions in the local/--installerdir location.
or
--installer=<filename> to explicitly select an installer. Use an absolute file name for this option.
Windows 7 Cluster Manager and the administrator account If you run ecclusterupgrade on a Windows 7 Cluster Manager under a user account other than the administrator account, you may encounter a permission denied error. This is due to a Windows 7 issue. The workaround is to run cmd using Run as administrator and then run ecclusterupgrade. Solaris Cluster Manager and ecconfig If you have used ecconfig to change the Cluster Manager/port any time after you initially ran the installer, you must manually update the Cluster Manager/port (where the agent hosts point to) in /opt/ecloud/install.props before running ecclusterupgrade.
4-2
Available ecclusterupgrade options:

Option --admin-password=value Description
Password of the admin user on the Cluster Manager, defaults to 'changeme'. The agent side install directory. You must specify the --hosts option also to limit the upgrade to those machines that use the non-standard agent install directory. The number of hosts to process per iteration. This allows you to break the upgrade of a large cluster into more manageable smaller batches to avoid timeouts. Default is 20, the recommended maximum. Cluster Manager whose hosts are to be upgraded, defaults to localhost:8030:8031 Cluster Manager secure port, defaults to 8031 Query the CM to get the list of hosts, write it to a file, and exit. This page. List of hosts to upgrade. Can be a pattern like host[1-3], host[2,5]. This switch supercedes --cm. The installer executable to use. Use an absolute filename for this option. If the installer is not in the expected directory, you must provide the full path to the installer, even when you specify --installerdir. The directory with the installer executables. The installer version (for example, 5.4.0.12345). This option is needed only if there are multiple installer versions in the local/--installerdir location. The number of minutes to wait for the install on the agent to finish. Default is 20 minutes. Log file to write messages to. By default, messages are printed to: /var/tmp (Linux and Solaris) or C:\ (Windows) in the form of ecloud_node_upgrade_YYYMMDD_HHMMSS.log The host name or IP address of the new Cluster Manager where you want to migrate the upgraded agents. The location where remote install is run. Agent machine OS (windows, linux, solaris)
--agentinstalldir=path
--batchsize=int
--cm=host[:port[:securePort]]
--cm-secure-port=port --gen-hostlist --help --hosts="host1 host2 ..."
--installer=filename
--installerdir=dirname --installerversion=version
--installtimeout=value
--logfile=value
--newcm=hostname/ip
--remotetmpdir=path --targetos=os
User Interface Upgrade Method

Electric Agent/EFS
You can upgrade Electric Agent/EFS software on a single host or upgrade all cluster hosts simultaneously. You may want to review Upgrading Multiple Agents on Cluster Hosts on page 4-2 to upgrade all hosts in a cluster. Note: When upgrading, be sure to run the installer on the Cluster Manager. Also, do not run the installer from a directory path that contains spaces (such as the Windows desktop).
4-3
Upgrading Agents on a single cluster host The Agent/EFS upgrade process for a single host machine is similar to a new Agent/EFS installation, with one very important exception. The following screen examples and explanations illustrate this exception. After invoking the installation wizard, select Electric Agent as illustrated in the next screen.
Click Next to see the next screenElectric Agentwhich is filled-in with your previous configuration information.
Click Next to continue to the next screen. On Windows, if you previously specified an Agent to run as a specific user, the selection is filled-in as you specified. At this point, you can revert to the ElectricAccelerator default user if you need the CSRSS, svchost, or OLE support service(s) for your buildsthese services are not available to you because you previously specified a specific user. On a single host, use of these services requires each agent service to run as a different user.
4-4
To change the service user to allow access to the CSRSS, svchost, and OLE support services, select ECloud Internal User. This means the ECloud user account is used to run agent services. If you do not want to use ElectricAccelerator default accounts, use ecconfig on each agent host to assign distinct users to each agent.
To use the ecconfig option after upgrading your agent machines, refer to Using the ecconfig command-line option. Go to Installing Electric Agent/EFS on page 3-8 to complete the Agent upgrade on a single host machinethe upgrade process from this point forward is the same as the initial Agent/EFS installation. Reboot the agent machine after the upgrade. The installation log file is in the install directorys root, C:\ECloud or /opt/ecloud, by default. Using the ecconfig command-line option Open a command-line window to use ecconfig. The following table is the output from running #ecconfig.exe -help.
Argument -cm value -numagents value Description
Host:port of the Cluster Manager the agent host should point to. This is the number of agents to start <xx>. If you modify numagents, you must restart the agents for your change to take effect. After the restart, the server database is updated and the agents become active. Specify agent usernames and passwords: -agentusers
username1/password1 username2/password2... usernameN/passwordN. Note: You must specify the same
-agentusers value
number of username/password pairs as the number of agents. The argument must be encapsulated in quotes.
-agentuser value
Specify a username and password for a specific agent: -agentuser agentID username/password where agent ID is the numerical ID of the agent to configure (between 1 and numagents).
y or n. Type y to specify this machine is part of an LSF grid or n
-lsfhost value -secureconsole value
for no.
y or n. Type y to secure the agent console port or n for no.
4-5
Argument -tempdir value -help or -?
Description
This is the location where agents should store temp files. Blank for system tempdir. Print this message.
Cluster Manager
Upgrading Cluster Manager follows the same procedure as your initial Cluster Manager installation. See Installing Cluster Manager on page 3-2. Note: If you want to upgrade the Cluster Manager and migrate the database to a different machine, you must first upgrade the Cluster Manager (to update the existing databases schema), then migrate the database to the new machine. Upgrading Cluster Manager 1. Log in as root or Administrator. Locate your copy of the ElectricAccelerator-<version> install file. 2. 3. 4. 5. 6. Double-click ElectricAccelerator-<version> to start the upgrade. The Welcome screen appears after the installation packages are extracted. Proceed with the upgrade installation in the same way you initially installed Cluster Manager. Ensure you type-in the correct value for your Cluster Manager admin password. The encrypted default value is changeme. The upgrade fails if the correct password is not used. Accept the existing Cluster Manager configuration or update your current configuration settings.
The installation log file is in the install directorys root, C:\ECloud or /opt/ecloud, by default.
Electric Make
Upgrading Electric Make To upgrade an Electric Make installation, simply overwrite the existing Electric Make version by installing the new version according to instructions provided in Installing Electric Make on page 3-12
CAUTION
If you are considering an Electric Make uninstall prior to upgrading your current version, use caution. If Electric Make and Cluster Manager are installed on the same machine, you will remove Cluster Manager when you uninstall Electric Make. The ElectricAccelerator Version Compatibility Matrix on page 4-8 contains detailed compatibility information.
Interactive Command-line Upgrade Method

Electric Agent/EFS
You can upgrade Electric Agent/EFS software on a single host or upgrade all cluster hosts simultaneously. You may want to review Upgrading Multiple Agents on Cluster Hosts on page 4-2 to upgrade all hosts in a cluster. Note: After agents on the grid are upgraded, they do not re-register with the Cluster Manager until a build runs. This means the Cluster Manager has old information about the agents and EFS (including outdated version information) until the next build runs and wakes up the agents. Initially, after an upgrade, the install log may show the upgrade has failed, but only until the next build is run.
4-6
Upgrading Agents on a single cluster host 1. Obtain a copy of the installer (ElectricAccelerator-<version>). 2. 3. 4. 5. Log in as root. Run chmod +x on the installer to ensure it is executable. Run ./<installer filename> --mode console to start the ElectricAccelerator upgrade. Enter 1 to select the Electric Agent/EFS package. Press Enter. Enter configuration details for the Agent/EFS upgrade. Note: Use the Cluster Manager default port 8030, or type-in the alternative port you specified during the initial installation. The installer upgrades Electric Agent/EFS using the configuration details you entered, followed by Installation complete when the upgrade completes. 6. You may receive a message to reboot the agent machine after upgrading Agent/EFSrebooting may not be required.
Note: On Linux, the installer dynamically builds the EFS kernel module if it detects it does not have a prebuilt version matching your Linux kernel version. The installation log file is in the install directorys root, /opt/ecloud by default.
Cluster Manager
Upgrading Cluster Manager follows the same procedure as the initial Cluster Manager installation. See Installing Cluster Manager on page 3-14. Upgrading Cluster Manager 1. Obtain a copy of the installer (ElectricAccelerator-<version>). 2. 3. 4. 5. Log in as root. Run chmod +x on the installer to ensure it is executable. Run ./<installer filename> --mode console to start the ElectricAccelerator upgrade. Enter 3 to select the Cluster Manager package. Press Enter. Enter configuration details for the Cluster Manager upgrade. Accept the default listening port you specified during initial Cluster Manager installation. Accept the default database listening port you specified during initial Cluster Manager installation. Migrate data from the current Cluster Manager version to preserve previously generated data. However, if the database schema has changed significantly, migration is not possible and a warning message is displayed. You can migrate data from ElectricAccelerator v2.3 or later. If you want to upgrade the Cluster Manager and migrate the database to a different machine, you must first upgrade the Cluster Manager (to update the existing databases schema), then migrate the database to the new machine. Note: Turning on log rotation may affect Cluster Manager performance. The installer upgrades Cluster Manager using the configuration details you entered, followed by Installation complete when the upgrade completes. The installation log file is in the install directorys root, /opt/ecloud by default.
Interactive Command-line Upgrade Method
4-7
Electric Make
Upgrading Electric Make To upgrade an Electric Make installation, simply overwrite the existing Electric Make version by installing the new version according to instructions provided in Installing Electric Make on page 3-17
CAUTION
If you are considering an Electric Make uninstall prior to upgrading your current version, use caution. If Electric Make and Cluster Manager are installed on the same machine, you will remove Cluster Manager when you uninstall Electric Make. The ElectricAccelerator Version Compatibility Matrix on page 4-8 contains detailed compatibility information.
ElectricAccelerator Version Compatibility Matrix

In general, Electric Cloud tries to maintain the system so that older versions of Electric Make are compatible with newer versions of Cluster Manager and the Agent. However, we do not ensure cross-version compatibility between other components, and we do not ensure newer Electric Make versions will work with older clusters. The following matrix illustrates Electric Clouds compatibility philosophy:
Newer Cluster Manager Older Cluster Manager Newer Electric Make Older Electric Make
Newer Agent
Older Agent
Electric Make Electric Agent Cluster Manager
Yes N/A No
No N/A No
Yes No N/A
No No N/A
No No No
No Yes Yes
Additional Explanation Electric Make and the Agent use a custom protocol to communicate with each other. Electric Cloud evolves this protocol in a backwards compatible manner so older Electric Make versions are compatible with newer Agent versions. This means you can upgrade the cluster anytime you want, then upgrade Electric Make installations at your leisure. Electric Make also uses a custom protocol to communicate with remote instances of itself, for example, during remote parse jobs. This protocol is less tolerant than the Electric Make/Agent protocol. In general, it is best to have the same version of Electric Make on the cluster as you have on your build machineElectric Cloud simplifies this because old versions of Electric Make are preserved on the cluster whenever the cluster is upgraded. For example, if your cluster originally has version 4.5.1 installed and was upgraded to 5.1, the 4.5.1 Electric Make version remains on the clusterin a special directory in the install tree. You do not have to do anything to ensure this version is used when you run a build using a 4.5.1 Electric Make version (the system handles that for you). Note: Old versions are NOT installed! What is already there during upgrades is preserved. So, if you install 5.1 on a fresh system, you will NOT be able to use a 4.5.1 Electric Make with that Agent. Electric Make and the Cluster Manager use yet another protocol to communicate with each other. Again, Electric Cloud evolves this protocol so old Electric Make versions can work with newer Cluster Managers. For example, you should have no problem using a 4.5.x Electric Make version with a 5.x Cluster Manager. Finally, the Agent uses a custom protocol to communicate with the Cluster Manager. Electric Cloud has not tried to maintain compatibility between these two componentsgenerally, if the agent version is close to the Cluster Manager version, it is compatible. However, you cannot use 5.x Agents with a 4.x Cluster Manager, or vice-versa.
4-8
Agent/eMake Backward Compatibility Exception The following table details the only exception to the standard agent/eMake backward compatibility policy. Agents 4.2.1 and later do not work with eMake 4.0.x, 4.1.x, or 4.2.0.
eMake v4.0.0 v4.2.0 eMake v4.3 eMake v4.2.1 and later
eMake v3.x
agent v3.x agent v4.0.0 - v4.2.0 agent v4.2.1 agent v4.3 and later
X X X X X X X X
ElectricAccelerator Version Compatibility Matrix
4-9
4-10
5
This chapter provides information to get you startedin addition to the initial configuration tasks, there is a look at the home page section, and a documentation roadmap for other ElectricAccelerator information and product help. This chapter contains the following sections: Logging In and Licensing A look at the ElectricAccelerator Home page Enabling Resource Management User Authentication LDAP Configuration Active Directory Configuration Setting Up Email Notification Using the Web Interface Documentation roadmap to locate other ElectricAccelerator product information and help
5-1
Logging In and Licensing

From the machine where Cluster Manager is installed, open a browser window and type-in localhost to display the Login screen. If you are accessing the Cluster Manager machine remotely, type-in the machine name, not localhost. If you are not using port 80, use host:port.
Type-in your user name and password. For a new installation, the default admin account user name and password is admin/changeme; for an upgrade, the default admin account user name and password is admin/<previous password>. Click Login. When the Security Alert screen appears, click Yes to proceed or View Certificate to install the certificate.
5-2
If you clicked Yes, the ElectricAccelerator Home page appears next. If you have not installed your ElectricAccelerator license, an advisory message appears in the top-left portion of the web page as shown in the following screen.
On the right-side of this page, click Import License and the Import License page appears.
You should have already received your license file. If not, contact Electric Cloud technical support.
Logging In and Licensing
5-3
Use one of the following methods to install your license: Browse for your license file and click Upload File. Open your ElectricAccelerator license file, copy and paste the text to the Data field and click OK.
After the ElectricAccelerator license is installed, you can get familiar with home page features, complete initial configuration tasks, and begin using ElectricAccelerator.
ElectricAccelerator Home Page

The home page, and all product web pages, provide one-click access to Builds, Agents, Reports, Messages, and Maintenance information and functionsthe tabs across the top of the page are always there for quick navigation.
5-4
Server Information
This section provides at-a-glance information, showing the number of currently running builds, the number of active, inactive, or disabled agents, the license limit, the type of resource manager, and the database type.
Using Comments
Using the Comments section is a convenient way to promote build team communication, track build or hardware issues, assign tasks, or any other information you need to maintain or share in permanent or temporary notes. A Comments section is available on the Build Details, Build Class Details, and Agent Details pages also. To add a new comment on the Home page, click the New Comment link and the New Server Comment page is displayed.
Type-in the information you want to share or track, click OK. Return to the home page to see your new comment displayed in the Comment box. Note: While home page comments are intended for server-specific information, you might want to use this comment section for other general messages or notes, for example, system-wide notices, schedule announcements, task assignments, and so on. Home page comments are available immediately each time you log in or one-click away if you are on another ElectricAccelerator web page.
ElectricAccelerator Home Page
5-5
At any time, you may click Edit Comment or Delete Comment to update or delete a comment. When you click Delete Comment, a message box appears so you can confirm or cancel your delete request. Note: A user may view or add comments only if permissions were granted by an administrator or manager. For more information on using comments for builds, build classes, and agents, click the Help link within the ElectricAccelerator product to view an online help topic on any web page that contains a Comment box. Note: For general web interface navigation, review the Navigating the Web Interface help topic within the online help system.
Enabling Resource Management

The ElectricAccelerator Resource Manager feature allows you to select a subset of available agents to run builds. For example, you might have a build that requires a certain hardware feature. If so, you can instruct ElectricAccelerator to use agents on hosts only containing that hardware. Note: You may choose not to use the Resource Manager feature, but if you use this feature, note that choosing one Resource Manager precludes using the other one. For example, if you choose the Resource Manager for the grid, you cannot use the built-in Resource Manager at the same timeResource Managers are mutually exclusive. The following two Resource Managers are available through the ElectricAccelerator web UI: ElectricAccelerators built in Resource Manager To enable the built in Resource Manager for your build, go to Maintenance > Server Settings. From the Server Settings page, for Resource Manager Type, select built in if you want to use ElectricAccelerators internal Resource Manager. For more information, see ElectricAccelerator online help topics. Resource Manager for LSF grid integration After installation is complete and the steps in Chapter 6, Configuring Cluster Manager for the Grid, have been performed, start or restart Cluster Manager and log in to the Cluster Manager web interface as an administrator. Go to Maintenance > Server Settings. If everything is available, the LSF radio button will be accessible. If this button is not available, review the Accelerator Log fileLSF may not be available to the process running the ElectricAccelerator server. If the LSF radio button is available, select it and Cluster Manager will dynamically request hosts as needed to support running Electric Make. Important: The LSF client must be installed on the Cluster Manager host. Note: Currently, LSF is the only grid Resource Manager available through the web UI. Chapter 6 contains additional information about configuring your environment for use with a grid. Enabling Resource Management provides an additional subtab in the web UI. From any ElectricAccelerator web page, click the Agents tab to see the newly activated Resources subtab. ElectricAccelerators online help system contains more Resource Manager information and help for using the Resources and the Resource Details pages.
Changing Log Locations

You can modify the following parameters in the Cluster Managers accelerator.properties file to change the location of build logs and accelerator logs: ACCELERATOR_BUILD_LOGS_PATH=build_logs ACCELERATOR_LOG=logs/accelerator.log
5-6
Default location for the accelerator.properties file: Linux: /opt/ecloud/i686_Linux/conf Solaris: /opt/ecloud/sun4u_SunOS/conf Windows: C:\ECloud\i686_win32\conf
User Authentication
ElectricAccelerator uses account information from multiple sources. In most cases, the primary account information source is an external LDAP or Active Directory repository: both user and group information is retrieved from the repository. Local users and groups can be defined within ElectricAccelerator.
Getting Started
1. 2. Go to the following directory on the Cluster Manager server:
<ECloud install>/<arch>/conf
Make a copy of the ldap_template.xml file if you intend to use LDAP, or the ad_template.xml file if you prefer to use Active Directory. Save the copy in the conf directory as any name you choose or use the name: securityContext.xml. Still working in conf, open the accelerator.properties file. Locate the following commented-out text string:
#ACCELERATOR_SECURITY_CONTEXT_FILES=conf/securityContext.xml
3.
If you did not name your template copy securityContext.xml, replace securityContext.xml with the filename you chose. Uncomment the #ACCELERATOR_SECURITY_... text string by removing the lead # sign. Comment out ACCELERATOR_SECURITY_CONTEXT_FILES= (which immediately follows the line you uncommented)
4. 5. 6. 7. 8. 9.
Use the LDAP information and examples in the following sections to fill-in your own copy of the LDAP template. Restart the Cluster Manager. After the Cluster Manager is running, log in to the Cluster Manager UI as admin. Go to Maintenance > Permissions. Click Enable User or Enable Group. Search for the desired user or group (or search for * to see all). If you set it up correctly, the requested LDAP users are visible.
10. Select the appropriate users or groups to enable using the corresponding checkbox(es). 11. Ensure that the desired permissions are set for the users or groups. (The online help system contains additional information about permissions.) Note: If you experience permissions issues while reading the ldap_template.xml or ad_template.xml copy, verify that the account that runs the Cluster Manager also has read permission for that file. To diagnose problems that cause Cluster Manager startup issues, including LDAP/Active Directory configuration problems, check <ECloud install>/<arch>/logs/accelerator.log.
Configuring LDAP
A number of options must be customized for any LDAP configuration. The following sample configuration is from the ldap_template.xml file. After the sample, see a list of properties with a description.
User Authentication
5-7
Sample LDAP Configuration

<bean id="ldapDirectoryProvider" class="com.electriccloud.security.ldap.LdapDirectoryProviderImpl"> <property name="providerName" value="LDAP"/> <property name="url" value="ldap://myldaphost/dc=company,dc=com"/> <property name="userBase" value="ou=People"/> <property name="userSearchFilter" value="uid={0}"/> <property name="userSearchSubtree" value="false"/> <property name="userNameAttribute" value="uid"/> <property name="fullUserNameAttribute" value="gecos"/> <property name="emailAttribute" value="mail"/>         </bean>
The following properties configure LDAP mapping:

Property emailAttribute Description
(optional) The attribute in a user record that contains the users email address. If the attribute is not specified, the account name and domain name are concatenated to form an email address. (optional) The attribute in a user record that contains the users full name (first and last name) for display in the UI. If this attribute is not specified or the resulting value is empty, the user's account name is used instead. (optional) The DN of a user who has read-only access to LDAP user and group directories. If this property is not specified, the server attempts to connect as an unauthenticated user. Not all servers allow anonymous read-only access. Note: This user does not need to be an admin user with modify privileges. (optional) If the managerDn property is set, this password is used to authenticate the manager user. This human readable name is displayed in the user interface to identify users and groups that come from this provider. This string is prepended to the basedn to construct the directory DN that contains user records. The attribute in a user record that contains the users account name. This LDAP query is performed in the context of the user directory to search for a user by account name. The string {0} is replaced with the users login ID. Typically, the query compares a user record attribute with the substituted user login ID. This property, if true, searches the entire subtree as identified by context. If false, (the default) then only the level identified by the context is searched. The LDAP server URL is in the form protocol://host:port/basedn. Protocol is either ldap or ldaps (for secure LDAP). The port is implied by the protocol, but can be overridden if it is not at the default location (389 for ldap, 636 for ldaps). The basedn is the path to the top level directory that contains users and groups at this site. This is typically the domain name where each part is listed with a dc= and separated by commas. Note: Spaces in the basedn must be URL encoded (%20). (optional) This property enables certificate verification for LDAPS connections if true.
fullUserNameAttribute
managerDn
managerPassword providerName userBase userNameAttribute userSearchFilter
userSearchSubtree url
verifyCerts
5-8
In addition to user information, the LDAP server can be queried for group information. This query is optional because the local group mechanism can refer to LDAP users as well as local users. However, the following elements can be used to tell the server how to map groups in LDAP:
Property groupBase groupMemberAttributes Description
(optional) This string is prepended to the basedn to construct the directory DN that contains group records. (optional) A comma separated attribute names list that identifies a group member. Most LDAP configurations only specify a single value, but if there is a mixture of POSIX and LDAP style groups in the directory, multiple attributes might be required. (optional) This LDAP query is performed in the groups directory context to identify groups that contain a specific user as a member. There are two common forms of group record in LDAP directories: POSIX style groups where members are identified by account name, and groupOfNames or uniqueGroupOfNames records where members are identified by the full user DN. Both forms are supported, so the query is passed two parameters: {0} is replaced with the full user record DN, and {1} is replaced with the user's account name. (optional) The group record attribute that contains the name of the group. (optional) This LDAP query is performed in the context of the groups directory to enumerate group records.
groupMemberFilter
groupNameAttribute groupSearchFilter
Determining LDAP Mapping

A typical POSIX user record in LDAP looks similar to the example below. To set up a mapping for this record, it is necessary to identify various record components. First, identify the path in the directory that contains user records. In this example, the build user has a distinguished name (dn) of uid=build,ou=People,dc=mycompany,dc=com. This name uniquely identifies the build user account and this path splits into three parts: base dn: dc=mycompany,dc=com user base: ou=People user element: uid=build
The baseDn is the parent of the directory that contains users. This value is combined with the protocol and server to form the URL. In this case, the URL ends up as ldaps://dir/dc=mycompany,dc=com. Next, the userBase is the portion of the path that identifies the directory containing all user account records. This value is used directly as the userBase configuration element. The remaining portion identifies the user without the People directory: uid=build. The user name is replaced in this value with the string {0} to form the userSearchFilter: uid={0}. This query allows the server to search for a users account name by looking for a record with a matching uid attribute. The final mapping step is to identify user record attributes that hold the account name, full user name, and (optionally) the users email address. In this example, the account name is uid (identified earlier), the full user name attribute is gecos, and there is no email attribute. At this point, the server is able to authenticate a user, look up a user by name, and determine the users full name. For many installations this is sufficient. Sample LDAP User Record
# build, People, electric-cloud.com dn: uid=jdoe, ou=People, dc=mycompany,dc=com loginShell: /bin/bash uidNumber: 508 gidNumber: 508 objectClass: account objectClass: posixAccount objectClass: top objectClass: shadowAccount uid: jdoe gecos: John Doe cn: John homeDirectory: /net/filer/homes/build
User Authentication
5-9
Also, you can configure the server to look for LDAP groups that refer to user accounts. A typical group record is shown below. Like a user account, an LDAP group has a distinguished name with a baseDn, a group base, and a group element. In this case, the base dn is still dc=mycompany,dc=com. The groupBase configuration element is ou=Group, and the group name is cn=build_users. The server must identify records in the directory that correspond to groupsit does this by applying the
groupMemberFilter to the records in the groupBase directory. In this case, group records are members of the posixAccount object class, so the filter can be set to objectClass=posixGroup. To display a group by its name, the server must know which attribute represents the group name. In this case, set the groupNameAttribute to cn.
Finally, the server needs a filter to determine which accounts belong to the group and the attribute name that represents a single group member. Group membership can be identified in one of two ways. Either the members are listed by account name, or by their LDAP distinguished name. In this case, POSIX group membership is determined by account name, so set the groupMemberAttributes property to memberUid, and set the groupMemberFilter to memberUid={1}. Sample LDAP Group Record
# build_users, Group, mycompany.com dn: cn=build_users,ou=Group,dc=mycompany,dc=com objectClass: posixGroup objectClass: top gidNumber: 100 memberUid: jdoe memberUid: mary cn: build_users
Sample Active Directory Configuration The following XML element defines parameters needed to connect to an Active Directory server and the query to use for looking up user information.
<bean id="adDirectoryProvider" class="com.electriccloud.security.ldap.ActiveDirectoryProvider"> <property name="providerName" value="ActiveDirectory"/> <property name="url" value="ldap://server/dc=company,dc=com"/> <property name="managerDn" value="cn=myuser,cn=Users,dc=company,dc=com"/> <property name="managerPassword" value="mypw"/> <property name="userBase" value="cn=Users"/> <property name="userSearchFilter" value="(sAMAccountName={0})"/> <property name="userSearchSubtree" value="false"/> <property name="userNameAttribute" value="sAMAccountName"/> <property name="fullUserNameAttribute" value="name"/> <property name="emailAttribute" value="userPrincipalName"/>      <property name="pageSize" value="500"/> </bean>
Additional information
When you upgrade from ElectricAccelerator 4.4 or earlier to 4.5 or later, you must modify your Active Directory XML file (the name you selected or ad_template.xml) located in <ECloud install>/<arch>/conf. Change the following:
<bean id="adDirectoryProvider" class="com.electriccloud.security.ldap.ActiveDirectoryProviderImpl">
to this:
<bean id="adDirectoryProvider" class="com.electriccloud.security.ldap.ActiveDirectoryProvider">
5-10
Setting Up Email Notification

To configure the Cluster Manager to send email notifications through SMTP, define your SMTP connection properties. SMTP connection properties are contained in the conf/accelerator.properties file. The following properties must be defined:
Property Description
ACCELERATOR_MAIL_HOST ACCELERATOR_MAIL_PORT ACCELERATOR_MAIL_PROTOCOL
The name of the SMTP mail server. The mail server port. Typically, this is 25 for SMTP or 465 for Secure SMTP. The mail server protocol. This can be smtp for SMTP or smtps for Secure SMTP.
If your mail server requires an authenticated user to send mail, you must also set the following properties:
Property Description
ACCELERATOR_MAIL_USERNAME ACCELERATOR_MAIL_PASSWORD For example:
The user name required for authentication. The password to use for authentication.
ACCELERATOR_MAIL_HOST=smtp.electric-cloud.com ACCELERATOR_MAIL_PORT=25 ACCELERATOR_MAIL_PROTOCOL=smtp ACCELERATOR_MAIL_USERNAME=cm ACCELERATOR_MAIL_PASSWORD=mypass This example sets up Cluster Manager to send mail as the 'cm' user through the smtp.electric-cloud.com server listening for SMTP connections on port 25. After making changes to the mail configuration, Cluster Manager must be restarted to use the changes.
Configuring the Mail Policy

On the Maintenance > Server Settings page, various aspects of the global email notification policy can be configured. Cluster Manager sends mail notifications when messages are added to the message log. The following settings control how and when mail is sent:
Setting Description
Email Interval Email Item Limit
The number of minutes between email notifications. The maximum number of messages that will be sent in a single email at the end of each interval. If more messages than the limit arrive, they are ignored. The name you use in the From line in the email header. A string prepended to every subject line of each outgoing email. This string can be used to assist with mail filtering.
Email From Email Prefix
Setting Up Email Notification
5-11
User Email Preferences

Each user that logs in to the Cluster Manager web interface can configure which mail notifications to receive. By default, a user receives no email notifications. For users to configure their own mail notifications (for messages and build completions), they must have Modify permission defined in the User field on the Permissions page. The administrator can edit a users permission on the Maintenance > Permissions page. By default, the User field is set to None. To receive notifications about messages in the message log, go to the Messages > Message Policies page. Select the Watch Messages checkbox to enable message notifications. Watch Level controls the minimum severity level of messages that generate a notification. To receive notifications when builds complete, go to the Builds > Build Classes page. For each build class in the list, select the checkbox in the Notify column to control whether the current user is notified when a build of that class completes. Users can selectively enable notifications for a set of build classes that interest them.
Solaris 10 configuration/debugging
In order to get the maximum useful information from any core dumps that may occur under Solaris 10 systems (SPARC and x86-64), run coreadm -G all -I all (as superuser) at any time. This reconfigures the machine (persistently, in /etc/coreadm.conf) to include the maximum information in core dumps.
Using the Web Interface

After verifying your agents are installed correctly and visible to Cluster Manager, setting up build classes, adding any additional users or groups, you can manage various build aspects, view build results, manage agent activity, enable or disable groups of agents, and add comments to specific builds, build classes, or agents.
5-12
Accessing Other ElectricAccelerator Information

The following list is an overview of more product information and help. ElectricAccelerator cmtool Reference and Users Guide includes: An introductory chapter to familiarize you with cmtoolthe ElectricAccelerator command-line tool application A complete list of cmtool commands and arguments Configuring ElectricAccelerator, defining your build, configuring sources/tools Starting a build, Electric Make settings and options Organizing Builds, Build Classes Make compatibility, output, and support Third-party Integration products, including Cygwin and Rational ClearCase Dependency Management, including eDepend, the Ledger file, and managing the history data file Annotation Performance tuning, managing files, running multiple agents Electric Make command-line options and environment variables Using Electrify Latest feature changes, improvements, and known issues Install/upgrade notes Building Visual Studio solutions and projects from within the Visual Studio IDE using Electric Make Converting Visual Studio projects into NMAKE makefiles Online help available from the Help link on each web page Including access to the ElectricAccelerator Electric Make Users Guide and cmtool Reference and Users Guide PDF files Inline help describes what to type in web page fields (accessed by clicking the Show Hide links) Knowledge base articles User forums
ElectricAccelerator Electric Make Users Guide includes:
ElectricAccelerator Release Notes
ElectricAccelerator Visual Studio IDE Add-in Technical Notes includes: ElectricAccelerator Solution Support Add-in Technical Notes includes: Help available within the ElectricAccelerator product includes:
Information on the Electric Cloud Support Web Site (https://electriccloud.zendesk.com/home) includes:
Accessing Other ElectricAccelerator Information
5-13
5-14
6
After Cluster Manager is installed

Log in with the Cluster Manager Service User ID (fully enabled to start and stop LSF jobs) and run a sample LSF job to make certain the user ID is ready.
bsub u [email protected] -x -q <queueName> -J <jobName> ls
If the job runs and results are returned, the user ID should be appropriate to use for Cluster Manager. (If the appropriate result is not returned, you may need to restart the server after making the necessary changes.) Next, update the ElectricAccelerator properties file in the conf directory. Edit the following entries in the accelerator.properties file. LSF Version (Optional): When you change the LSF version, update the HM_LSF_VERSION property and restart the Cluster Manager. For example, to change the LSF version to 7 from 6, the value must be the same as the following:
HM_LSF_VERSION=7
Agent Connect Script Submission Queue (Required): When Cluster Manager needs more hosts, it submits a job to the LSF Master host. The job content runs the agentconnect script on the host selected by the LSF Master host. This is the same as the bsub -q <queue> <script> command. The <queue> is defined in the lsb.queues file for LSF. This queue needs to be set up to support either one of two options: 1) host locking (exclusive), or 2) HJOB_LIMIT=1.
HM_LSF_QUEUE=??????
Agent Connect Script Job Name (Required): This value is the same as the bsub -J parameter. All jobs submitted to LSF from Cluster Manager will have this job nameCluster Manager uses this name to identify jobs it submitted. This name must not be used for other jobs.
HM_LSF_JOB_NAME=eaAgents
Agent Connect Script (Optional): The agent start script is how Cluster Manager requests more hosts from LSF. This script is submitted to LSF through the bsub equivalent API call. The script is installed in the ElectricAccelerator bin directory. Use this setting to identify the script. (This option rarely needs to be changed.)
HM_LSF_WINDOWS_SCRIPT=agentconnect HM_LSF_LINUX_SCRIPT=agentconnect HM_LSF_SOLARIS_SCRIPT=agentconnect
Agent Connect Script Priority (Optional): The agent start script priority is used to pass a priority to LSF when Cluster Manager requests more resources. This value is the same as the bsub -sp parameter.
HM_LSF_USER_PRIORITY=
6-1
Agent Connect Script Project Name (Optional): The agent start script project name is passed to LSF when Cluster Manager requests more resources. This value is the same as the bsub -P parameter.
HM_LSF_PROJECT_NAME=
Agent Connect Script email Address (Optional): This value is the same as the bsub -u parameter. If specified, an email is sent to this address whenever the agentconnect script is terminated.
HM_LSF_EMAIL_ADDRESS=
Agent Connect Script Output (Optional): This value is the same as the bsub -o parameter. If specified, standard output from the agent start script will go to this location. The user ID running Cluster Manager must have create and write access to this file.
HM_LSF_UNIX_OUTPUT_PATH=/tmp/agentRunOut%J.log HM_LSF_WIN_OUTPUT_PATH=C:\windows\temp\...agentRunOut%J.log
Agent Connect Script Error Output (Optional): This value is the same as the bsub -e parameter. If specified, standard output from the agent start script will go to this location. The user ID running Cluster Manager must have create and write access to this file.
HM_LSF_UNIX_ERR_PATH=/tmp/agentRunErr%J.log HM_LSF_WIN_ERR_PATH=C:\windows\temp\...agentRunErr%J.log
Agent Connect Script Initial Wait Interval (Required): Use this option when the agentconnect script is run. The value is the number of seconds a host waits for agents to be activated and assigned to a build. The typical setting is between 10 and 60 seconds. A short setting might not allow enough time for LSF to schedule the job and start the agents. A setting too long and hosts that will never be used can tie up resources.
HM_LSF_INITIAL_WAIT=30
Agent Connect Script Idle Host Interval (Required): This option identifies LSF hosts that are no longer needed. When the ElectricAccelerator Cluster Manager sees a host unused for the number of seconds specified in this setting, it cancels the corresponding LSF job. Typical values for this setting are between 3 and 30 seconds. Use a longer setting if your LSF grid is continuously using ElectricAccelerator.
HM_LSF_IDLE_HOST_TIME=5
Agent Connect Script NotFound Job Cleanup Interval (Required): Use this option to clean up LSF jobs reported as NOTFOUND for the number of seconds specified as the value. There is a case in LSF that queries the LSF job against mbatchd and returns a job is not found result when actually the job is still running. Without this setting, Cluster Manager treats NOTFOUND as an invalid status and removes the job on the Cluster Manager side. This action leads to LSF job synchronization issues. The typical value for this setting is a few seconds more than the value of MBD_REFRESH_TIME if you are using multi-threading mbatchd mode. If you do not encounter the NOTFOUND problem, Zero value for this setting means the NOTFOUND status is treated as an invalid status and the job is removed from the Cluster Manager immediately.
HM_LSF_NOTFOUND_KILL_TIME=15
Agent Connect Script Max Pending Jobs (Required): Use this option to limit the number of jobs the Cluster Manager will leave in a pending state. This option has a distinct impact on your overall build throughput. While builds are running and could use more Accelerator agents for parallel processing, Cluster Manager leaves jobs in the LSF queue in case more hosts become available. The typical setting is 2. If software builds are important and hosts become available quickly, a setting of 5 might be appropriate.
HM_LSF_MAX_PENDING_REQUESTS=2
Agent Connect Script Job Runtime Limit (Optional): This value is the same as the bsub -W parameter. If specified, a job will run for the maximum amount of time specified in this setting before it is terminated.
HM_LSF_RUN_TIME_LIMIT=
6-2
Agent Connect Script Connection Host (Optional): Use this option when the agentconnect script is run. This option overrides the Cluster Manager hostnameneeded on those occasions when the locally determined hostname is incorrect for agents to contact the Cluster Manager because of multiple network interfaces or DNS problems.
HM_LSF_CONNECTION_HOSTNAME=
Setting Up LSF
Two ElectricAccelerator requirements for requesting hosts from LSF: There must be a queue that allows Cluster Manager to submit host exclusive jobs or a queue that specifies
HJOB_LIMIT=1.
Hosts with Electric Agent/EFS installed must be identified to LSF.
The following example shows host groups, a unique queue, and resource mapping to accomplish both requirements. 1. Create a host group to identify Electric Agent/EFS machines Edit the conf/lsbatch/xxxx/configdir/lsb.hosts file. In this file, create a host group that includes all the hosts where you installed Agent/EFS. For example:
Begin HostGroup GROUP_NAME GROUP_MEMBER # Key words eaGroup (blade[1-9]) End HostGroup
2.
Create a queue that limits jobs to the host group Edit the conf/lsbatch/xxxx/configdir/lsb.queues file. In this file, create a queue definition that allows exclusive jobs and limits those jobs to Agent/EFS hosts.
Begin Queue QUEUE_NAME = eaQueue EXCLUSIVE = Y HOSTS = eaGroup DESCRIPTION= Queue to control ElectricAccelerator agents. End Queue
Use the following option if your queue is NOT exclusive:

Begin Queue QUEUE_NAME = eaQueue EXCLUSIVE = N HJOB_LIMIT = 1 HOSTS = eaGroup DESCRIPTION= Queue to control ElectricAccelerator agents. End Queue
If EXCLUSIVE=N, jobs from another queue may also run on the same host. 3. Edit the conf/lsf.cluster.<clustername> file and modify the resource mapping. Begin Host HOSTNAME model blade1 ! blade2 ! type ! ! server 1 1 rlm 3.5 3.5 mem () () swp () () RESOURCES (eaResource) (eaResource)
6-3
4.
Edit the conf/lsf file and add the LSF_STRIP_DOMAIN=.<domain-name>

LSF_STRIP_DOMAIN=.electric-cloud.com
Note: This ensures the hostname returned from the LSF job is the same as the hostname returned from the ElectricAccelerator agent. 5. Set the queue name in the accelerator.properties file Edit the ElectricAccelerator Cluster Manager conf/accelerator.properties file. Set the HM_LSF_QUEUE property to eaQueue.
HM_LSF_JOB_NAME=eaAgents HM_LSF_QUEUE=eaQueue
Note: The queue name (eaQueue) specified in the accelerator.properties file matches the queue name in the lsb.queues file. Also, the host group name (eaGroup) in lsf.queues matches the group name added to the lsb.hosts file. Finally, the host group identifies the machines with Agent/EFS installed. The combination of these steps ensures Cluster Manager and LSF are in agreement on which hosts are available to ElectricAccelerator. You may want to consider imposing limits on ElectricAccelerators use of the grid. LSF queue definitions provide a variety of controlling features. For example, you can limit how many hosts are available to ElectricAccelerator during certain time periods. See your LSF Administrators Guide for more information.
Additional Information
Ensure you have a standard way to construct the LSF resource query string. If not, you may encounter an issue illustrated by the following example: If the LSF query condition is CPU > 8 and OS = windows: User1 may put --emake-resource="cpu>8&&OS==windows" while User2 may put --emake-resource="OS==windows&&cpu>8" (which is the same resource defined in a different order). The Cluster Manager handles these as two different resources, but LSF handles them as the same resource. The issue manifests in this manner: If you submit two builds with the same LSF resource query string (the same CPU arch OS ...), the builds do not appear to share the started agents and they act as totally different builds with two separate resources. In the UI, you can identify the issue by hovering the cursor over the Builds page agent bars and seeing a different Allocated number for these two builds. If they are on the same resource, the Allocated value for both builds would be the same and they would share the agents fairly.
Grid Host Manager

Grid Host Manager allows ElectricAccelerator to communicate and integrate with a host grid such as LSF or Oracle Grid Engine. You must enable Grid Host Manager using cmtool:
cmtool modifyServer --resourceManagerType cloud
After you enable Grid Host Manager, the following scripts become available so you can communicate with the host grid server: checkResource.tcl Checks whether a resource string is valid. Input argument - Resource string in "bsub -R" (same as in --emake-resource) Output - "true" if the string is valid, "false" otherwise.
6-4
initialize.tcl Checks whether the grid setup is ready (for example, already "source profile.lsf" from LSF, can run b* commands, and so on) Input argument - none Output - "true" if the grid setup is ready and initialized, "false" otherwise.
killJob.tcl Kills a grid job based on job ID Input argument - grid job ID Output - none
queryJobs.tcl Queries the status of all grid jobs Input argument - none Output - A string format: job1Id:host1:status,job2Id:host2:status,job3Id:host:status...
submitJob.tcl Submits a grid job Input arguments - Resource string, OS, host:port of the Cluster Manager Output - grid job ID
6-5
6-6
7
This chapter provides additional Windows-specific information.
Agent-Side Application Setup

It is important that applications running on agents are properly initialized for the users that run the agent processes. By default, the users ECloudInternalUser1, ECloudInternalUser2, and so on, own the processes run by agents. Agents can be run as any user, but each agent must have a unique user, which is a requirement for agents to function properly (contact technical support for additional information). This requirement imposes additional setup steps for agent machines because some applications require per user setup (WinZip, Visual Studio 2005 and 2008, Microsoft Office, and so on). Setup is particularly important for applications that display a dialog if they are not properly initialized because this may result in stalled jobs (the application remains in interactive mode until the agent times it out for lack of activity) during the use of eMake. To initialize applications, do one of the following: Use the psexec tool available from Microsoft (http://technet.microsoft.com/en-us/sysinternals/bb897553.aspx) to run the application as different users. This requires that you have the password for the account (for ECloudInternalUser1, and so on, contact technical support for the user password). Log in as each of the configured agent users and run the relevant application to initialize it. Identify which files/registry keys must be set for a user by using Microsofts procmon tool (http://technet.microsoft.com/en-us/sysinternals/bb896645.aspx), creating a .reg file, and copying the user files to create those entities for all users.
Visual Studio
Initializing Visual Studio Use the psexec method to initialize Visual Studio as shown:
psexec -u ECloudInternalUser1 "C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\devenv.exe"
As an alternative, disable profiles for Visual Studio by running this regedit script:
REGEDIT4 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\Profile] "AppidSupportsProfiles"="0"
Microsoft Office
You must run Microsoft Office by using psexec (or logging in directly) because there is no registry setting to initialize Microsoft Office easily. Ensure that the Visual Basic setting for Security is set to Medium or Lower (assuming the build tries to run VB scripts). Find this under Tools > Options > Security > Macro Security.
7-1
WinZip
You must run WinZip by using psexec (or logging in directly) because there is no registry setting to initialize WinZip easily.
MSBuild
Specify configuration information for MSBuild under C:\Program Files\MSBuild. This information must be present on all agents, by either syncing that directory among all machines or by adding that directory to the eMake root.
Antivirus Software
Avoid real-time scans on agent machines. Real-time scans can slow down builds and can lead to unexpected failures due to issues with the antivirus softwares dll injection. Generally, scans do not find anything relevant because all results are also checked on the eMake machine.
Cygwin
Electric Cloud strongly recommends that the install location be the same on all agents. The install location must also be the same on all eMake machines. The mount mode must be the same for all machines.
Additional Information
Make the following changes to agent/EFS hosts: Disable the Windows error reporting service. This avoids popup windows for crashed applications.
For Windows Vista and Windows Server 2008 R2, the installer automatically does the following: Disables the Windows error reporting service. Sets HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\NtfsDisableLastAccessUpdate to 0. The default value for Windows Vista and Windows Server 2008 R2 is 1. Disables User Account Control (UAC) for 64-bit versions. Disabling UAC avoids popup windows for applications that require administrator privileges. If UAC is enabled, application registry access is redirected to each users virtual store, even if it runs under the Administrator account.
FileInfo and Superfetch services Because the FileInfo (used by Superfetch) filter driver issues a couple of calls for each file operation in the EFS driver, it has the potential to slow down the EFS driver. The FileInfo and Superfetch services run on Windows Vista and Windows 7 only (Microsoft officially turned them off in Windows Server 2008 R2). ElectricAccelerator turns the two services off by default. You can choose to leave them running by removing the following two lines from runagent (located in <ECloud install>\<arch>\bin):
catch {service stop sysmain} catch {service stop fileinfo}
and rebooting the machine. Terminating stale processes Certain processes may continue to run on Windows Agent machines. You can choose to terminate all stale processes by adding the following line to runagent (located in <ECloud install>\<arch>\bin):
[efs connect] set terminateStaleProcess 1
7-2
Registry-Specific Information
To allow parallel building of Windows code, ElectricAccelerator virtualizes the registry and the file system. The following sections discuss important registry information.
Registry Use Under Windows

There are two relevant areas of registry use during an ElectricAccelerator build. By default ElectricAccelerator virtualizes HKEY_CLASSES_ROOT (except HKEY_CLASSES_ROOT\Installer and HKEY_CLASSES_ROOT\Licenses). HKEY_CLASSES_ROOT All other keys
HKEY_CLASSES_ROOT This key contains file name extensions and the COM class registration (http://msdn.microsoft.com/en-us/library/ms724475.aspx and http://technet2.microsoft.com/windowsserver/en/library/dd670c1d-2501-4f32-885b-0c6a1ae662f41033.mspx?mfr=true ). Configuration data is stored under the program ids, CLSID, Interface, TypeLib, AppId, and so on. For entities created during the build, this information must be virtualized to all involved agents. The following information is registered for a type library: http://msdn2.microsoft.com/en-us/library/ms221610(VS.85).aspx
\TypeLib\{libUUID} \TypeLib\{libUUID}\major.minor = human_readable_string \TypeLib\{libUUID}\major.minor\HELPDIR = [helpfile_path] \TypeLib\{libUUID}\major.minor\Flags = typelib_flags \TypeLib\{libUUID}\major.minor\lcid\platform = localized_typelib_filename
Other entities that are registered by UUID are registered in different places: http://msdn2.microsoft.com/en-us/library/ms221150(VS.85).aspx A ProgID("ApplicationName") maps to and from a CLSID(GUID). The CLSID maps to the actual ActiveX component ("APP.EXE"). The type library is available from the CLSID:
\CLSID\TypeLib = {UUID of type library} \CLSID\{UUID} = human_readable_string \CLSID\{UUID}\ProgID = AppName.ObjectName.VersionNumber \CLSID\{UUID}\VersionIndependentProgID = AppName.ObjectName \CLSID\{UUID}\LocalServer[32] = filepath[/Automation] \CLSID\{UUID}\InProcServer[32] = filepath[/Automation]
http://msdn2.microsoft.com/en-us/library/ms221645(VS.85).aspx Applications that add interfaces must register the interfaces so OLE can find the appropriate remoting code for interprocess communication. By default, Automation registers dispinterfaces that appear in the .odl file. It also registers remote Automation-compatible interfaces that are not registered elsewhere in the system registry under the label ProxyStubClsid32 (or ProxyStubClsid on 16-bit systems). The syntax of the information registered for an interface is as follows:
\Interface\{UUID} = InterfaceName \Interface\{UUID}\Typelib = LIBID \Interface\{UUID}\ProxyStubClsid[32] = CLSID
All Other Keys Other keys are likely not relevant to the build. HKEY_LOCAL_MACHINE, HKEY_CURRENT_USER, HKEY_USERS, and HKEY_CURRENT_USER are machine specific. If other areas must be virtualized, it is recommended that you add them to the emake-reg-root option.
Registry-Specific Information
7-3
Registry Underlay
When a process in the build requests information from the registry, the EFS first checks if the requested key is already present in its cache. If the key is not present, the EFS relays the request to the agent, which in turn sends the request to eMake. After receiving the response from eMake, the agent loads the key into the EFS cache, subject to the following conditions: If the key does not exist at all in the local registry on the agent host, the value from the eMake response is used unconditionally. If the key exists in the local registry, the value from the local registry is given precedence over the initial value from eMake, but not any value set by prior commands in the build. That is, if the key is modified during the course of the build, the modified value is used in preference of any value from the local registry. The order of precedence is (lowest to highest): value from eMake host registry prior to the start of the build value from the agent host registry, if any value set by an earlier job in the build
The additional checking of precedence enables ElectricAccelerator to interoperate with tools that store host-specific licensing information in the registry. If the agent simply used the value from eMake unconditionally in all cases, such tools would fail to operate correctly. Electric Cloud STRONGLY RECOMMENDS AGAINST running builds locally on agent host machines. Running builds locally on agent machines may add relevant keys to the local machine, which take precedence over the eMake machines keys. If a key that should come from the eMake machine (such as the typelib information for a lib generated during the build) is already present on the agent due to a locally performed build, the wrong information is used, possibly causing a broken build. If an agent machine has locally created keys, remove the typelibs that are created during the build from the registry. Any typelib that has an invalid path name associated with it is a likely candidate for an underlayed lookup. Ideally, typelibs created by a build are known. At this point, it is recommended to check for their existence on the cluster. If an error occurs that indicates the direction of this problem (for example, a library/typelib cannot be found), investigate the failing agents registry.
ExcludeProcessList Registry Entry

You can add a multi-string registry value to the agent host inside HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ElectricFS to exclude processes from interfering with EFS and causing a crash. The ExcludeProcessList entry can list processes from McAfee antivirus (for example, Mcshield.exe and mfevtps.exe) or other antivirus software. Note: Make these registry changes only if the system crashed previously.
Windows Kernel Non-paged Pool Memory

Under high-volume network traffic, the non-paged pool memory in the Windows kernel has the potential to become depleted. This issue in the Windows kernel can be triggered by applications such as MySQL, Java server applications, and so on. Over a period of time, this results in a machine crash. The workaround is to use the 64-bit version of Windows. Though this does not completely resolve the issue, it increases the available memory to a point where crashes are unlikely and infrequent.
7-4
Support for Managed Code/.NET

There are no known limitations with respect to building managed code or .NET code. There are, however, areas to keep in mind: Agents must have the same version of .NET installed. Agents must be on the same service pack level and have the same OS and tool hotfixes installed. The language bar must be enabled on all agent machines, or disabled on all agent machines. Including the Global Assembly Cache in the eMake root is not recommended. Contact technical support for more details.
Glossary of Terms
.TLB file A type library is a binary file containing all type information that is needed to use procedures or classes in DLLs (http://msdn.microsoft.com/en-us/library/ms221060(VS.85).aspx and http://vb.mvps.org/hardcore/html/whatistypelibrary.htm). It corresponds to a registry key hierarchy under HKEY_CLASSES_ROOT, which maps a GUID to an actual file name and defines additional configuration information. .PCH file A precompiled header file is used by the Visual Studio tool chain. It allows the compiler to load just a memory dump of the already-parsed header information, thus reducing compile time drastically. A potential issue exists when using pch files on different machines because the files are sensitive to the program code size of the cl process. This means that when certain system libraries change (due to a hotfix) or additional libraries are dynamically loaded (such as antivirus scanners or the language bar), the pch file may become unusable. .PDB file A program database file contains debugging symbols for object files built using the Visual Studio tool chain. All compiles accessing the same pdb file must be serialized during an ElectricAccelerator build to guarantee correctness, which may slow down builds. .DLL file A dynamically loaded library under Windows is code that is shared among applications (prime examples are the c runtime library and other system libraries) and loaded dynamically when the application starts.
Support for Managed Code/.NET
7-5
7-6

EA Installgd5 4

Uploaded by

Copyright:

Available Formats

EA Installgd5 4

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

EA Installgd5 4

Uploaded by

Copyright:

Available Formats

ElectricAccelerator

Installation and Configuration Guide

Electric Cloud, Inc. 676 W. Maude Avenue Sunnyvale, CA 94085 www.electric-cloud.com

Copyright 2002 - 2011 Electric Cloud, Inc. All rights reserved.

ElectricAccelerator Installation and Configuration Guide

System Requirements and Supported Platforms

Upgrading ElectricAccelerator Components

Initial Configuration Tasks

Configuring Cluster Manager for the Grid

ElectricAccelerator Installation and Configuration Guide

ElectricAccelerator Installation and Configuration Guide

ElectricAccelerator Installation and Configuration Guide

Electric File System (EFS)

ElectricAccelerator Agent (Agent)

Electric Make (eMake)

Understanding Component Interactions

ElectricAccelerator Installation and Configuration Guide

Electric Make and EFS

Electric Make and Cluster Manager

Cluster Manager and Other Components

When to Use the ElectricAccelerator Cluster

ElectricAccelerator Installation and Configuration Guide

System Requirements and Supported Platforms

System Requirements and Supported Platforms

System Requirements and Supported Platforms

Solaris 10 (32- or 64-bit) Solaris 9 (32- or 64-bit)

SP1 and SP2 required

ElectricAccelerator Installation and Configuration Guide

System Requirements and Supported Platforms

System Requirements and Supported Platforms

System Requirements and Supported Platforms

ElectricAccelerator Installation and Configuration Guide

System Requirements and Supported Platforms

In addition, exclude the following programs during agent host installation:

Agents can be installed now.

Third-party Supported Build Tools

System Requirements and Supported Platforms

System Requirements and Supported Platforms

cleartool db_server ClearCase

cleartool db_server ClearCase

cleartool db_server ClearCase cleartool db_server

ElectricAccelerator Installation and Configuration Guide

System Requirements and Supported Platforms

Agent Memory Usage

The "checksum" utility

Default Installation Directories

System Requirements and Supported Platforms

System Requirements and Supported Platforms

Installation Log Locations

Linux and Solaris

Agent Log Locations

Linux and Solaris

Disk Cache Directory and Agent Temporary Storage Location

Linux and Solaris

ElectricAccelerator Installation and Configuration Guide

System Requirements and Supported Platforms

Linux Kernel Performance Note

Planning for Grid Use

Planning for Grid Use