ElectricCommander Installation Guide

(1)

Installation Guide

for version 4.2.1

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

(2)

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, ElectricDeploy, ElectricInsight, and Electric Make are registered trademarks or trademarks of Electric Cloud, Incorporated.

Electric Cloud products—ElectricAccelerator, ElectricCommander, ElectricDeploy, ElectricInsight, and Electric Make—are commonly referred to by their “short names”—Accelerator, Commander, Deploy, Insight, and eMake—throughout 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.

(3)

Chapter 1: ElectricCommander Introduction 1-1

What is ElectricCommander? 1-1

What Makes ElectricCommander Unique? 1-1

Architecture 1-3

Chapter 2: System Requirements and Supported Platforms 2-1

System Requirements and Supported Platforms 2-1 Server, web server, or repository server platforms 2-1

Agent platforms 2-3

Hardware Requirements 2-3

Software Requirements 2-4

Port Usage 2-4

Database Information 2-4

Default Installation Directories 2-5

Log File Locations 2-5

Disk Usage 2-7

Memory Usage 2-7

Server/Agent Compatibility 2-8

The "checksum" utility 2-8

Chapter 3: Installing ElectricCommander 3-1

General Information 3-1

User Interface Installation Method 3-2

Express Server Installation 3-2

Express Agent Installation 3-6

Advanced Installation 3-10

Interactive Command-line Installation Method 3-38 Silent Unattended Installation Method 3-44

Linux Silent Installation Examples 3-47

Windows Silent Installation Examples 3-48 Why Commander installs/requires agents on remote web servers and repository servers 3-49 Installing Agents on Non-Server-Supported Platforms 3-50 UNIX Agent Command-line Installation 3-50

UNIX Agent Silent Installation 3-51

Chapter 4: Upgrading ElectricCommander 4-1

ElectricCommander Upgrade Process 4-1

(4)

Important MySQL Upgrade Note 4-2

Performing a “Clean” Installation 4-2

Upgrading Commander and Adding an Artifact Repository Server 4-3

Linux Upgrade Note 4-3

User Interface Upgrade Method 4-3

Interactive Command-line Upgrade Method 4-6

Silent Unattended Upgrade Method 4-6

Upgrading Agents on Non-Server-Supported Platforms 4-6

Chapter 5: Remote Agent Installation and Upgrade 5-1

Prerequisites 5-1

Publish an Installer to the Artifact Repository 5-1

Upgrading trust on a remote agent 5-2

Chapter 6: Initial Configuration Tasks 6-1

External Database Configuration 6-1

Configuring Commander to Use an Alternate Database 6-2 Using the Web Interface to Set the Database Configuration 6-2 Using ectool to Set the Database Configuration 6-3

Switching to an Alternate Database 6-4

Logging in and Licensing 6-5

About Licenses 6-5

Applying the License Key 6-5

Making the Plugins Directory Universally Accessible 6-6 Configure Commander server, agents, and web servers to point to a universally accessible network

location 6-7

Keep the plugins directory in its default server location and replicate the contents to remote agents

and web servers 6-9

If you have a proxy server in your environment... 6-9

Troubleshooting 6-9

Web Interface Online Help System 6-10

Chapter 7: Uninstalling ElectricCommander 7-1

Uninstalling ElectricCommander 7-1

Windows Uninstall 7-1

UNIX Uninstall 7-1

Chapter 8: Other Related Topics 8-1

Backing up Your Commander Server 8-1

Recommendations 8-1

Prerequisites 8-1

Backup steps 8-1

Restoring Your Commander Server 8-2

Prerequisites 8-3

Apache Web Server or Agent Certificates 8-8

Description 8-8

Generating a signed certificate for the ElectricCommander web server or agent: 8-8

Send the request to the CA 8-8

(5)

Using chkconfig 8-10

Manual Server/Agent Stop and Start 8-11

Solution for Stop 8-11

Solution for Start 8-12

(6)

(7)

What is ElectricCommander?

ElectricCommander is an enterprise-class solution for automating the software build and release process. Commander helps teams make software build, package, test, and deployment tasks more repeatable, more visible, and more efficient.

At its core, ElectricCommander is a web-based system for automating and managing the build and release process. It provides a scalable solution, solving some of the biggest challenges of managing these “back-end” software development tasks.

Challenges solved by ElectricCommander

l Time wasted on script-intensive, manual, home-grown systems that are error prone and do not scale

well, with little or no management visibility or reporting

l Multiple, disconnected build and test systems across locations, resulting in redundant work, the inability

to share/reuse code files across teams, making it painful to manage build and test data

l Slow overall build and release cycles that directly impact release predictability and time-to-market

Commander tackles these problems with a three-tier architecture, AJAX-powered web interface, and first-of-its-kind build and release analytic capabilities for reporting and compliance. With this solution, your developers, release engineers, build managers, QA teams, and managers gain:

l Shared platform for disseminating best practices and reusing common procedures l Ability to support geographically distributed teams

l Continuous integration and greater agility

l Faster throughput and more efficient hardware utilization l Visibility/reporting for better project predictability

l Better software quality by integrating and validating against all target platforms and configurations

What Makes ElectricCommander Unique?

ElectricCommander is the most scalable solution on the market, and only ElectricCommander provides

enterprise-class scalability for build and release management. It is easy to install and use on a simple build, yet scales to support the largest and most complex build and test processes. Only ElectricCommander’s multi-threaded Java server provides efficient synchronization even under high job volume.

(8)

ElectricCommander

l Workflow functionality - Use a Workflow to design and manage processes at a higher level than

individual jobs. Workflows allow you to combine procedures into processes to create build-test-deploy lifecycles (for example). A workflow contains states and transitions you define to provide complete control over your workflow process. The Commander Workflow feature allows you to define an unlimited range of large or small lifecycle combinations to meet your needs.

l Continuous Integration Manager (CI Manager) - This feature provides a front-end user interface for

creating, managing, and monitoring continuous integration builds. The Continuous Integration Dashboard provides:

o _{Visually see your running builds, build progress, build status, and historical build outcomes.} o _{Easily accessed “Actions” to configure a continuous integration build.}

o _{Quick configuration of your preferred SCM system.}

o _{A project can contain any number of continuous integration builds, depending on the work you have}

already set up for your procedures/steps to perform.

l Handles resource management - If a resource is overcommitted, ElectricCommander delays some jobs

until others have finished with the resource. You can define pools of equivalent resources and ElectricCommander balances the load across the pool.

l Access control - users log in to the system and ElectricCommander uses their information to control their

activities. Privileges can be set for individuals or groups to ensure the security you need.

l Preflight Build functionality - used by developers to build and test code changes in isolation on their

local machines before those changes are committed to a production build.

l Search, sort, and filter functions to minimize viewing or “wading” through information that is of no interest

to you, giving you quick access to the information you need.

l Records a variety of information about each job, such as the running time and success or failure of each

step. A set of reports is available to provide even more information.

l Email notifications to get important information or data to individuals or groups immediately and on a

regular basis for a particular job or a specific job aspect.

l Powerful and flexible reporting facilities - Various statistics such as the number of compiles or test errors

are collected after each step and recorded in the ElectricCommander database. A variety of reports can be generated from this information.

l Artifact Management - Use artifacts to improve performance across builds, provide better reusability of

components, and improve cross-team collaboration with greater traceability. For example, instead of each developer repeatedly downloading third-party packages from external source, these components can be published and versioned as an artifact. A developer then simply retrieves a specific artifact version from a local repository, guaranteeing a consistent package from build to build.

l All ElectricCommander features are available from a command-line tool (ectool), a Perl API, as well as a

web interface.

l Plugin capability - Commander is built with an extensible UI, enabling easy development of plugins,

including integrations with other tools, custom dashboards, and unique user experiences based on roles.

l Allows you to observe jobs as they run and to cancel jobs. l A workspace for each job - a disk area jobs can use for storage.

l Powerful data model based on properties - Properties are used to store job input data such as the

source code branch to use for the build, to collect data during a job (such as number of errors or warnings), and to annotate the job after it completes (for example, a build has passed QA).

(9)

l Zones and Gateways - A zone (or top-level network) you create, is a way to partition a collection of

agents to secure them from use by other groups. A gateway is a secured connection between two zones when you want to share or transfer information to another zone. For example, you might want a

developers zone and a test zone. The Commander server is a member of the default zone, created during Commander installation.

Architecture

ElectricCommander was architected from the ground up to support enterprise scale software production. Based on a three-tier architecture, Commander scales to handle large, complex environments. Commander’s multi-threaded Java server provides efficient synchronization even under high job volume.

l The Commander server manages resources, issues commands, generates reports. l An underlying database stores commands, metadata, and log files.

l Agents execute commands, monitor status, and collect results, in parallel across a cluster of servers for

rapid throughput.

See the following illustrated architecture overview.

(10)

ElectricCommander

Other configurations

l Remote web servers or multiple web servers at your current site

l Remote repository servers or multiple repository servers at your current site l Remote database

l Proxy resources

The next illustration is an example for how you might set up a remote web server installation.

This remote web server configuration helps prevent network latency. If you have multiple sites, ElectricCommander can be configured in numerous ways to help you work more efficiently.

(11)

and Supported Platforms

This chapter describes hardware and software requirements, disk space usage, file locations, database information, and more for installing and running ElectricCommander on Windows or UNIX systems.

Note: All version requirements for operating systems and databases listed in this chapter are routinely tested and fully supported by Electric Cloud. Newer versions may work or be supported also. Contact Electric Cloud Customer Support if you have any questions.

System Requirements and Supported Platforms

Server, web server, or repository server platforms

Microsoft Windows

l Windows 7, SP1 recommended

l Windows Server 2008 and Windows 2008 R2

l Windows Server 2003 - SP2 recommended but not required

l Windows XP - SP2 or later required for hosts running Windows XP

Notes:

l Windows Server 2008 and Windows 7 Note:

An administrator may need to disable User Account Control (UAC). If the installer runs under account X, but services will run under account Y, installation directories (both program and data) will probably have permissions that prevent Y’s access. This applies particularly to data directories.

l For all Windows versions, 32 and 64-bit are supported.

Linux

l Red Hat Enterprise Linux 6, 32 and 64-bit l Red Hat Enterprise Linux 5, 32 and 64-bit l Red Hat Enterprise Linux 4, 32-bit only

l SUSE Linux Enterprise Server 12.1, 32 and 64-bit

(12)

ElectricCommander

l SUSE Linux Enterprise Server 10.3 and 10.4, 32 and 64-bit

l Ubuntu 10.04 – 12.04, 32 and 64-bit

Notes:

l Do not choose “nobody” for the RHEL user. RHEL does not allow a “su - nobody -c foo.sh”

because it is not a shell account. Using “nobody” prevents the SQL server from starting, which means the default ElectricCommander database is inaccessible.

l RHEL 6 Note:

If you plan to use Commander on RHEL 6.x, 64-bit, you need to run one or all of the following commands before installing Commander:

yum install libstdc++.i686- You must run this command. If you do not run this command, the Commander Apache server will not start and the installer silently fails for any type of Commander installation.

yum install libuuid.i686- Run this command if performing a Commander installation that includes an Apache server. For example, if you are installing Commander agents only, without a web server, you do not need to run this command on each agent machine.

yum install nss-pam-ldapd*.i686- You must run this command (to install 32-bit NSS packages) if using an LDAP account for ownership of the server/web/repository services. If you do not run this command, the Commander Apache server fails to start.

Note: Before attempting any Commander installation, Electric Cloud recommends running all of these commands on your RHEL 6, 64-bit machines. These commands install 32-bit libraries, omitted by Red Hat, but required for the Commander installation executable file to work.

l RHEL 5 Note:

If you plan to use ElectricCommander on RHEL5.x, the supported installation method requires the SeLinux configuration to be less restrictive—set the SeLinux operating mode to “Permissive.” To do this, issue the following command as the root user:

# setenforce 0

Alternatively, the mode can be changed by editing the file /etc/selinux/config and changing the line "SELINUX=enforcing" to "SELINUX=permissive".

Either change requires rebooting the Linux server to have the changes take effect.

l RHEL 4 64-bit Note:

Red Hat Linux 4 64-bit is NOT supported as a Commander server or web server machine, but you may continue to use this platform for agents.

l SUSE Linux Enterprise Server Note:

After installing Commander, run the following command as root: /usr/lib/lsb/install_initd /etc/init.d/commander*

This command ensures the Commander daemons are started in the appropriate sequence after any system restart.

l Ubuntu 10.04 – 12.04 - 64-bit Note:

Before installing ElectricCommander, you must install Ubuntu’s 32-bit compatibility layer by running the following command:

(13)

Note: Steps running with impersonation on Ubuntu run with a PATH environment variable set in /etc/environment. As a side-effect, the ElectricCommander bin directory is not in the PATH in the impersonation context, so calls to tools like ectool and postp fail with a “not found” error.

To fix: Update /etc/environment to include the ElectricCommander bin directory in PATH. For Ubuntu 12.04 64-bit only - Before installing ElectricCommander, you must run the following command (to install 32-bit NSS packages) if using an LDAP account for ownership of the server/web/repository services:

apt-get install libnss-ldap:i386

If you do not run this command, the Commander Apache server fails to start.

Agent platforms

l All server machines specified for the ElectricCommander server

o _{See RHEL 6 Note above for 64-bit installations.} o _{See RHEL 5 Note for Commander server above.}

o _{See Ubuntu 10.04 – 12.04 - 64-bit note for Commander server above.}

l Red Hat Enterprise Linux 4 (64-bit) l Microsoft Windows 2000

l Sun Solaris 9 (Architecture: Sparc only)

Sun Solaris 10 (Architecture: Sparc and Intel x86)

l HP-UX 11i v1 (11.11) or later (Architecture: PA-RISC 2.0)

Make sure the following patches (or patches superceding these patches) are installed: PHKL_29243, PHSS_39077

HP-UX Secure Shell Note:

HP-UX Secure Shell requires that a random number generator be located on the system. It searches for /dev/urandomand /dev/random (in that sequence) on the system and uses the first device it finds. If it fails to locate these two devices, HP-UX Secure Shell uses its own internal random number generator program. By default, HP-UX 11i v2 systems includes these random number devices. These devices can also be obtained for HP-UX 11i v1 by downloading and installing the HP-UX Strong Random Number Generator from http://software.hp.com. HP recommends that Secure Shell users on HP-UX 11i v1 systems install the Strong Random Number Generator product as it significantly speeds up program initialization and execution time for some commands.

l Mac OS X 10.4 (Tiger) or later (Architecture: Intel) l Proxy Agent notes

o _{When using a proxy agent, the proxy target must run an SSH v2 server. For more information on}

proxy target agents, see the Configuration and Resource online help topics.

o _{Running certain commands requiring administrator privileges (for example, net stop xxx) using}

cygwin 1.7 sshd can fail with “access denied” errors. These errors did not occur in cygwin 1.5. The Commander proxy agent relies on sshd being privileged. To set this privilege on cygwin 1.7, you need to run an additional setup script (in addition to ssh-host-config):

cyglsa-config reboot

Hardware Requirements

Minimum requirements for either the Windows or Linux machine where the ElectricCommander server is installed:

(14)

ElectricCommander

l Processor clock rate: 1.5 GHz or higher

l Memory: 2 GB RAM or more (8 GB recommended for small to medium deployments) l Cores: 2 or more (4 cores recommended for small to medium deployments)

Software Requirements

To connect to ElectricCommander, your web browser must be one of the following:

l Microsoft Internet Explorer 7.0 or later l Mozilla Firefox 10.0 or later

(Firefox versions earlier than v10.0 are not supported.)

l Chrome 13 or later

Note: Web browser extensions such as AdBlockPlus for Google Chrome can interfere with the display of Commander web pages. Electric Cloud recommends disabling any ad blocking browser extensions or add an exclusion for Commander web pages.

If you are installing an ElectricCommander server and you have a web server (for example, Apache, IIS) or other application using port 80 and/or 443 on the ElectricCommander host, you have 4 options:

l Choose different web server ports. l Uninstall the existing web server.

l Disable the existing web server.

l Reconfigure the existing web server to use another port.

Port Usage

By default, ElectricCommander uses the following ports:

l 8000 - ElectricCommander Server

l 8443 - ElectricCommander Server (SSL port) l 80 - ElectricCommander Web Server

l 443 - ElectricCommander Web Server (SSL port)

l 6800 - Port used by the ElectricCommander agent for HTTP communication on the localhost network

interface.

l 7800 - ElectricCommander Agents (by default, this is an HTTPS port)

l 61613 - Preflight file transfer port, other file transfer, event notifications, or other messaging l 8200 - Artifact repository server (by default, this is an HTTPS port)

Other database ports:

l 1521 - Oracle 11g Release 1, and R2 l 1433 - Microsoft SQL Server

Tip: Make sure your firewall is open for the ports Commander needs.

Database Information

During ElectricCommander server installation, you can choose NOT to install the built-in [default] database on the server machine. If you did not install the built-in database, after ElectricCommander server installation is complete, you must choose an alternate database before you can begin using Commander (enterprise license required). ElectricCommander supports the following alternate databases:

(15)

l MySQL 5.0, 5.1, or 5.5.12 or later (5.5.12 or later is recommended)

l MS SQL Server 2005 with Service Pack 2 or later, or MS SQL Server 2008, 2008 R2 l Oracle 10g R2 (including RAC)

l Oracle 11g Release 2, R2

IMPORTANT: If you install Commander v4.2.x or later using the built-in Commander database, be advised that this database is not recommended for production systems. Electric Cloud highly recommends using an alternate database in your production Commander environment. You may switch to an alternate database at anytime in the future. Using an alternate database requires a Commander enterprise license.

See Chapter 5,"Initial Configuration Tasks" on page 6-1for more information. Notes:

1. You will not be able to log in until a database is set up.

2. If you are using two different Commander servers, they cannot point to the same database.

Database growth

Expected database growth over time can be correlated with the number of job steps created, using an estimate of 10K per job step.

Note: Database growth is NOT correlated with build logs or build artifacts size. To create a reasonable database growth estimate per period:

l Estimate the number of jobs per period,

l multiply the “job number” estimate by the number of steps estimated per job,

l then multiply that number by 10Kbytes to determine the disk size required for that period of study.

For example: If you run 500 jobs per day with an average of 200 steps per job, or 100K steps per day, your database would grow about 1 GB per day or 90 GB per quarter. Using this example, if you prune jobs older than 30 days, database size could be maintained at about 30 GB.

Default Installation Directories

You can change the installation directories if you need to do so.

l Default for Windows program files: C:\Program Files\Electric Cloud\ElectricCommander l Defaults for Windows data (database, logs, configuration files):

o _{For Windows 2008 or Windows 7}

-C:\ProgramData\Electric Cloud\ElectricCommander

o _{For Windows XP or 2003}

-C:\Documents and Settings\All Users\Application Data\Electric Cloud\ElectricCommander

l UNIX/Mac: /opt/electriccloud/electriccommander

Log File Locations

(16)

ElectricCommander

For Windows

l Agent

o _{Default for Windows XP, 2003}

-C:\Documents and Settings\All Users\Application Data\Electric Cloud\ElectricCommander\logs\agent

o _{Default for Windows 2008, Windows 7}

-C:\ProgramData\Electric Cloud\ElectricCommander\logs\agent

l Server

-C:\Documents and Settings\All Users\Application Data\Electric Cloud\ElectricCommander\logs

-C:\ProgramData\Electric Cloud\ElectricCommander\logs

l Web server

-C:\Documents and Settings\All Users\Application Data\Electric Cloud\ElectricCommander\apache\logs

-C:\ProgramData\Electric Cloud\ElectricCommander\apache\logs

l Repository server

-C:\Documents and Settings\All Users\Application Data\Electric Cloud\ElectricCommander\logs\repository

-C:\ProgramData\Electric Cloud\ElectricCommander\logs\repository

l Installer

-C:\Documents and Settings\All Users\Application Data\Electric Cloud\ElectricCommander\logs

-C:\ProgramData\Electric Cloud\ElectricCommander\logs

For UNIX

l Agent /opt/electriccloud/electriccommander/logs/agent l Server /opt/electriccloud/electriccommander/logs l Web server /opt/electriccloud/electriccommander/apache/logs l Repository server /opt/electriccloud/electriccommander/logs/repository l Installer /opt/electriccloud/electriccommander/logs

(17)

Note: Server logs and agent logs “roll over” periodically so individual logs do not grow too large and older logs are deleted. Roll-over parameters are configurable in conf/logback.xml and conf/agent.conf.

Disk Usage

Disk space usage varies and depends on the quantity and size of the jobs you run. Electric Cloud recommends starting with the following free space recommendations:

l Server - 10 GB l Agents - 5 GB each

o _{Sizing artifact cache directory space on resources}

By default, artifacts are retrieved into the <data-dir>/artifact-cache directory of the agent installation. You can modify the agent.conf file to change the location, or you can specify the cache directory location on each resource known to Commander. Determining how much free space the cache partition needs to accommodate all of your artifact versions can be difficult. Here is one approach to approximate the disk/partition size you need:

For each artifact, estimate how large you think each version will be and how many versions you plan to keep. Compute the total required space to be the sum of version-size * numVersions for each artifact. Add a buffer of 50%. Using your end result, allocate a disk/partition that size and configure the cache as a directory on that disk/partition.

l Repository server - If using Artifact Management functionality, you could need 20-30 GB, or more disk

space for your repository server.

o _{Although a server install includes an artifact repository, Electric Cloud recommends that production}

repository server(s) be installed on different machines than the Commander server. The repository server may do a very large amount of disk and network I/O when transferring artifact versions to and from requesters and this may adversely affect Commander server performance.

o _{Sizing the repository backingstore}

For a repository installation, by default, the repository backingstore is the <data-dir>/repository-datadirectory. You can modify the

<data-dir>/conf/repository/server.propertiesfile or use ecconfigure to update the backingstore location. Determining exactly how much free space the backingstore disk/partition needs to accommodate your artifact versions can be difficult. Here is one approach to approximate the disk size you need:

For each artifact, estimate how large you think each version will be and how many versions you plan to keep. Compute the total required space to be the sum of version-size * numVersions for each artifact. Add a buffer of 50%. Using your end result, allocate a disk/partition that size and configure the repository backingstore as a directory on that disk/partition.

Memory Usage

Memory usage varies depending on whether or not the ElectricCommander server is a dedicated machine.

l By default, minimum memory usage is 20% of free memory on a 32 or 64-bit system, assuming the

ElectricCommander server is running on a dedicated machine.

l By default, for a Commander repository server, minimum memory usage is 10% of free memory. l By default, for a Commander agent, minimum memory usage is 256 MB.

l To adjust the memory level, go to the ElectricCommander directory to modify the

wrapper.java.initmemory.percentand wrapper.java.maxmemory.percent lines in wrapper.conf:

(18)

ElectricCommander

o _{For Windows XP or Windows 2003:}

c:\Documents and Settings\All Users\Application Data\Electric Cloud\ ElectricCommander\conf\wrapper.conf

o _{For Windows 2008 or Windows 7}

c:\ProgramData\Electric Cloud\ElectricCommander\conf\wrapper.conf

o _{For Linux:}

/opt/electriccloud/electriccommander/conf/wrapper.conf

o _{For a repository server:}

l Windows:

c:\Documents and Settings\All Users\Application Data\Electric Cloud\ ElectricCommander\conf\repository\wrapper.conf or c:\ProgramData\Electric Cloud\ElectricCommander\conf\repository\wrapper.conf l Linux: /opt/electriccloud/electriccommander/conf/repository/wrapper.conf

Note: Alternately, using ecconfigure, you can set the initial and maximum memory settings. For example, to set the CommanderServer initial memory percentage to 21% and the maximum memory percentage to 31%, specify:

ecconfigure --serverInitMemory 21 --serverMaxMemory 31

Server/Agent Compatibility

All supported ElectricCommander Agent versions are forward and backward compatible with all supported ElectricCommander Server versions. For example, an ElectricCommander v3.10 Agent is compatible with an ElectricCommander v4.2 Server; and conversely, an ElectricCommander v3.10 Server is compatible with an ElectricCommander v4.2 Agent.

Note: ElectricCommander pre-v3.10 components are no longer supported. If your current Commander installation is a version prior to 3.10, contact Electric Cloud Customer Support for manual instructions to upgrade your installation.

The "checksum" utility

An MD5 checksum file is available on the Electric Cloud FTP site. If you choose to verify that

ElectricCommander 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 Mac operating systems.

l On Linux, verify with md5sum --check ElectricCommander-xx.md5

l Most Linux installations provide an md5sum command for calculating MD5 message digests. l An MD5 utility for Windows can be downloaded at www.fourmilab.ch/md5/.

To use the MD5 checksum utility on a Mac:

1. In Finder, browse to /Applications/Utilities.

2. Double-click the Terminal icon. A Terminal window appears. 3. In the Terminal window, type: “md5” (followed by a space).

(19)

5. Click in the Terminal window, press the Return key, and compare the checksum displayed on the screen to the one on the download page.

(20)

(21)

General Information

This chapter describes all versions of the ElectricCommander installation process.

If you are upgrading a previously installed Commander version, follow the instructions in"Upgrading ElectricCommander" on page 4-1.

Note: You must install Commander on a local drive. Electric Cloud does not support installing the Commander server on a network volume.

The graphical user interface for installation works for both Windows and Linux platforms supporting the Commander server install. See chapter 2,"System Requirements and Supported Platforms", for a list of

supported Commander server platforms. If X is not running or not available, the Linux user interface installer will run in interactive command-line mode.

For new installs, three options are available: Express Server install, Express Agent install, or Advanced install. The express installs use default values for all settings except service accounts. The advanced install allows you to specify components, directories, ports, and so on.

When installing or upgrading a 64-bit machine, the 64-bit version of the Java Runtime Environment is installed automatically.

If you choose to install the Commander-provided built-in database, be advised that this database is not recommended for production systems. Electric Cloud highly recommends using an alternate database in your production Commander environment (Commander enterprise license required). See"Database Information" on page 2-4for alternate databases supported by Commander.

When installing an agent, repository server, and/or web server, you can enter information for a remote Commander server. That information can then be used to discover the server’s plugins directory and set it accordingly so the local install is in sync with the remote Commander server. During an agent installation, you can create a resource object on the server automatically. Similarly, during a repository installation, you can create a repository object on the server automatically.

This chapter contains three sections, one for each installation method. The three methods for installing Commander are:

l User Interface - this is a set of installation screens that provides click-through automation and prompts

for information you need to supply.

l 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.

(22)

ElectricCommander

l Silent - this is a non-interactive command-line installation. You may find this installation method preferable for installing multiple remote agents.

User Interface Installation Method

Begin each graphical user interface installation by double-clicking the ElectricCommander-<version> file. The first screen, Welcome to the ElectricCommander Installer, appears with three options as follows:

l Express Server

Select this option to install the ElectricCommander server, including the web and repository servers, built-in database, one agent to run jobs from this machine, and Commander tools.

l Express Agent

Select this option to install a Commander agent—this installation also includes Commander tools. Use this option for managed hosts where you intend to run job steps.

l Advanced

This option allows you to select individual components, directories, or ports. For example, you can use this option to install a remote web server only, or you may want to install tools only on developer

machines. Multiple installation combinations are available. See"Advanced Installation" on page 3-10for more information.

Note: Electric Cloud recommends installing the ElectricCommander server first, before installing remote agents or web servers.

Express Server Installation

This installation type installs the ElectricCommander server, including the web server, built-in database, one agent to run jobs from this machine, and Commander tools. Double-click the ElectricCommander-<version> file to begin installation.

Note: The built-in database included with this installation type is not recommended for production systems. Electric Cloud highly recommends using an alternate database in your production Commander environment. You can upgrade to an alternate database at a later time (Commander enterprise license required).

(23)

Click Next to continue.

Note: The following screen example is for Windows only. If you are installing on a Linux machine, see the additional Linux field descriptions below.

l Type-in the account User Name and Password. This account is the one used to run the Commander server, web server, and repository server services.

l Domain - If the user belongs to a domain, enter the domain name in this field. If this is a local user, leave

this field blank.

l Use the local system account checkbox - Check this box if you want the Commander server, repository

server, and web server services to run as the local Windows system account. Note: The local system account does not have access to network shares.

l Use the same account for the agent service checkbox - Check this box if you want the agent on the

Commander server machine to run as the same account. IMPORTANT:

For security reasons in production environments, you may want to use a separate account for the agent service because the server account has permission to read the key file (conf\passkey). The key file is used to decrypt passwords stored in Commander. Using a different account for the agent service ensures that a process running on the agent cannot gain access to the key file.

Note: If you select this checkbox, you will not see the following screen with fields to supply your agent service account information.

On Linux machines:

If you are installing Commander on a Linux server, the information you need to supply is slightly different as follows:

l User Name - This is the user who owns the Commander server, repository server, and web server

processes.

l Group Name - This is the group that owns the Commander server, repository server, and web server

(24)

ElectricCommander

l Use the same account for the agent service checkbox - Check this box if you want the same user and group to own the agent process on the Commander server machine.

IMPORTANT:

For security reasons in production environments, you may want to use a separate user and group for the agent service because the server service has permission to read the key file (conf\passkey). The key file is used to decrypt passwords stored in Commander. Using a different user and group for the agent service ensures that a process running on the agent cannot gain access to the key file.

l Type-in the account User Name and Password. This account is the one used to run the Commander

agent service.

this field blank.

l Use the local system account checkbox - Check this box if you want the Commander agent service to

run as the local Windows system account. Note: The local system account does not have access to network shares.

l User Name - This is the user who owns the Commander agent process.

l Group Name - This is the group that owns the Commander agent process.

(25)

Review the default settings and your service account selections. Use the Back button to change your service account selections if necessary.

Please wait while ElectricCommander is installing all components—this process may take fifteen minutes. The Commander server will start when installation is complete.

(26)

ElectricCommander

Launch a web browser to login to ElectricCommander checkbox - Check this box if you want Commander to open to the login screen now.

Click Finish to complete the installation.

Express Agent Installation

ElectricCommander software must be installed on each agent machine you intend ElectricCommander to use. Double-click the ElectricCommander-<version> file to begin installation.

Note: You may install ElectricCommander agent software on Windows or Linux with this installation method. For Solaris, HP-UX, Mac, or other supported UNIX agent machines, see"Installing Agents on Non-Server-Supported Platforms" on page 3-50.

Select Express Agent to begin—this installation also installs Tools. Click Next to continue.

(27)

l Server Host Name - Type-in the name of the ElectricCommander server that will communicate with this

agent. If the remote server is using a non-default HTTP port, you must specify the Server Host Name as host:port.

l Commander User Name - Specify the name of a user on the Commander server who has sufficient

privileges to create a resource. Defaults to the Commander-supplied admin user.

l Password - Specify the password for the Commander user. The default password for the admin user is

changeme.

l Discover the plugins directory checkbox - If you would like the agent machine to have access to the

plugins directory (recommended), check this box. The plugins directory on the Commander server must be “shared” before the agent machine can use “discover” to find the directory. For more information, see

"Making the Plugins Directory Universally Accessible" on page 6-6.

l Create a resource checkbox - Check this box to create a resource on the remote Commander server for

the agent you are installing.

l Trusted checkbox - Check this box to restrict this agent to one Commander server. l Resource Name - Supply the name you would like to use for this resource.

l Create in default zone checkbox - Check this box if you want to create the agent in the default zone. l Agent Gateway URL - Supply the URL of the gateway used to communicate with the Commander

server.

l Zone Name - Supply the zone name used during remote agent and/or remote repository creation.

(28)

ElectricCommander

agent service.

this field blank.

l User Name - This is the user who owns the Commander agent process. l Group Name - This is the group that owns the Commander agent process.

(29)

Review this screen to verify your selections. Use the Back button to change any of your settings if necessary. Click Next to continue.

Please wait while the agent and tools are installed—this will take just a few minutes. Click Next to continue.

(30)

ElectricCommander

Click Finish to complete the agent installation.

Advanced Installation

This installation type provides the flexibility to accept some or all default installation specifications or change them to accommodate your environment.

Double-click the ElectricCommander-<version> file to begin installation.

When the Commander Welcome to the ElectricCommander Installer screen appears, select Advanced to begin.

The next screen displays individual components to install. Notes:

1. Commander tools are automatically installed with each installation type. 2. An agent is automatically installed with a web server or repository server.

(31)

3. The built-in database that you can choose to install is not recommended for production systems. Electric Cloud highly recommends using an alternate database in your production Commander environment. If you choose to install the built-in database, you can upgrade to an alternate database at a later time. If you do not install the built-in database, you must configure Commander to use an alternate database before using Commander. Using an alternate database requires a Commander enterprise license.

You can select one or more options to install at the same time. However, this guide provides examples for the most common ways you might use the Advanced option. The following examples are provided:

l Installing the ElectricCommander server and all components l Installing a Commander agent

l Installing a remote Commander web server, including an agent

l Installing a remote Commander repository server, including an agent l Installing Commander tools

Example 1 - complete ElectricCommander installation

This installation example installs the ElectricCommander server, including the web, repository, and database servers, one agent to run jobs from this machine, and Commander tools. Double-click the

ElectricCommander-<version>file to begin installation.

(32)

ElectricCommander

Commander uses these default directories to install files and components. Click Browse to specify other directory locations if you prefer to do so.

Click Next to accept the default locations or the directory locations you specified.

Commander uses the default ports displayed on this screen.

You can accept these default port specifications or type-in alternate port numbers. Click Next to continue.

(33)

Supply the host name users need to type into their browser to access the Commander web server. Click Next to continue.

server, web server, and repository server services.

(34)

ElectricCommander

l Use the local system account checkbox - Check this box if you want the Commander server, web server, and repository server services to run as the local Windows system account. Note: The local system account does not have access to network shares.

Commander server machine to run as the same account. IMPORTANT:

For security reasons in production environments, you may want to use a separate account for the agent service because the server account has permission to read the key file (conf\passkey). The key file is used to decrypt passwords stored in Commander. Using a different account for the agent service ensures that a process running on the agent cannot gain access to the key file.

l User Name - This is the user who owns the Commander server, web server, and repository server

processes.

l Group Name - This is the group that owns the Commander server, web server, and repository server

processes.

l Use the same account for the agent service checkbox - Check this box if you want the same user and

group to own the agent process on the Commander server machine. IMPORTANT:

For security reasons in production environments, you may want to use a separate user and group for the agent service because the server service has permission to read the key file (conf\passkey). The key file is used to decrypt passwords stored in Commander. Using a different user and group for the agent service ensures that a process running on the agent cannot gain access to the key file.

(35)

agent service.

l Domain - If the user belongs to a domain, enter the domain name in this field. If this is a local user, leave this field blank.

(36)

ElectricCommander

Review default settings and any custom specifications. Use the Back button to modify any information if necessary.

Please wait while ElectricCommander installs all components and files—this process may take fifteen minutes. The Commander server will start when installation is complete.

(37)

Example 2 - installing a Commander agent

ElectricCommander software must be installed on each agent machine you intend ElectricCommander to use. Double-click the ElectricCommander-<version> file to begin installation.

Note: You may install ElectricCommander agent software on Windows or Linux with this installation method. For Solaris, HP-UX, Mac, or other supported UNIX agent machines, see"Installing Agents on Non-Server-Supported Platforms" on page 3-50.

(38)

ElectricCommander

Commander uses these default directories for installation.

Click Browse to specify other directory locations if you prefer to do so.

Click Next to accept the default locations or the directory locations you specified.

(39)

agent. If the remote Commander server is using non-default ports, you must specify the Server Host Name as host:port.

l Password - Specify the password for the Commander user. The default password for the admin user is changeme.

server.

(40)

ElectricCommander

agent service.

this field blank.

(41)

Review the default and your custom specifications. Use the Back button to modify any information if necessary. Click Next to continue.

(42)

ElectricCommander

Click Finish to complete the Commander agent installation.

Example 3 - installing a remote Commander web server, including an agent

ElectricCommander supports multiple workspaces, including those co-located on agents that use them. In this architecture, step log files are created locally so even the largest log files can be captured without a

performance penalty. Step log files can be viewed from the web UI, but with a performance penalty if retrieving those files across the WAN. Remote users, who want to view those particular logs, pay a performance penalty twice—once for the web server to retrieve the file contents and once for the web to send the contents back across the WAN to the browser.

The solution: Install one central Commander server, then install a Commander web server at each remote site, co-located with remote agents and workspaces, allowing remote users to log in through their local web server. Any operations initiated from the remote location, including running a job, are completed by the central Commander server.

When a remote user views the Job Details page, job data is retrieved from the central server. Assuming the job is using a workspace at the remote user’s site, links to all log files effectively refer to local paths. Because log files are accessed by the remote web server’s agent only, and not the Commander server, both trips across the WAN are eliminated. The Commander web server reads the log file locally (via its agent), then serves the page to the user whose browser is also on the same side of the WAN.

Notes:

1. You can install Commander web servers on any Windows or Linux platform suitable for installing the Commander server.

2. For information about why Commander automatically installs an agent with each remote repository server, see"Why Commander installs/requires agents on remote web servers and repository servers" on page 3-49. Double-click the ElectricCommander-<version> file to begin installation. On the Advanced installation screen, select Web server to begin.

(43)

Commander uses these default directories for installation.

Click Browse to specify other directory locations if you prefer to do so.

(44)

ElectricCommander

(45)

l Server Host Name - Type-in the name of the ElectricCommander server that this web server will

communicate with. If the remote Commander server is using non-default ports, you must specify the Server Host Name as host:port.

l Commander User Name - Specify the name of a user on the Commander server. Defaults to the

Commander-supplied admin user.

changeme.

l Discover the plugins directory checkbox - If you would like the web server to have access to the

plugins directory (recommended), check this box. The plugins directory on the Commander server must be “shared” before the web server can use “discover” to find the directory. For more information, see

server.

(46)

ElectricCommander

l Type-in the account User Name and Password. This account is the one used to run the web server

service.

this field blank.

l Use the local system account checkbox - Check this box if you want the web server service to run as the local Windows system account. Note: The local system account does not have access to network shares.

l User Name - This is the user who owns the web server process. l Group Name - This is the group that owns the web server process.

(47)

agent service.

this field blank.

l User Name - This is the user who owns the Commander agent process.

l Group Name - This is the group that owns the Commander agent process.

(48)

ElectricCommander

Verify that all specified information is what you intended or use the Back button to modify a setting. Click Next to continue.

(49)

Click Finish to complete the Commander remote web server installation.

Example 4 - Installing a remote repository server, including an agent

This installation example installs a remote ElectricCommander repository server, an agent to run jobs from this machine, and Commander tools. Double-click the ElectricCommander-<version> file to begin installation. On the Advanced installation screen, select Repository to begin.

Note: Installing an agent on the same machine as a repository server enables the repository server’s backingstore to be cleaned up by running a job on this agent rather than logging into each remote repository server and running the command manually. For information about why Commander automatically installs an agent with each remote web server, see"Why Commander installs/requires agents on remote web servers and repository servers" on page 3-49.

(50)

ElectricCommander

Commander uses these default directories to install files and components. Click Browse to specify other directory locations if you prefer to do so.

(51)

(52)

ElectricCommander

Name as host:port.

changeme.

l Create a repository - Check this box to create a repository object on the remote Commander server for

the repository server you are installing.

l Repository Name - Supply the name you would like to use for this repository object.

server.

(53)

l Domain - If the user belongs to a domain, enter the domain name in this field. If this is a local user, leave this field blank.

l Use the local system account checkbox - Check this box if you want the repository server service to

Commander server machine to run as the same account.

l User Name - This is the user who owns the Commander repository server process. l Group Name - This is the group that owns the Commander repository server process.

l Use the same account for the agent service checkbox - Check this box if you want the same user and

group to own the agent process on the Commander server machine.

agent service.

(54)

ElectricCommander

l Use the local system account checkbox - Check this box if you want the Commander agent service to run as the local Windows system account. Note: The local system account does not have access to network shares.

Review default settings and any custom specifications. Use the Back button to modify any information if necessary.

(55)

Please wait while ElectricCommander installs all components and files—this process may take fifteen minutes. The Commander server will start when installation is complete.

Example 5 - installing Commander tools only

If you need to install Commander tools only on developer or other machines, use this installation method. Open the installer executable file on each machine where you need to install Commander tools.

Double-click the ElectricCommander-<version> file to begin installation.

(56)

ElectricCommander

Accept the default installation directory or click Browse to select the directory you prefer. Click Next to continue.

(57)

Verify that the settings are correct or use the Back button to make a change. Click Next to continue.