Ec Install4 0

ElectricCommander
Installation Guide
for v4.0
Electric Cloud, Inc. 676 W. Maude Avenue Sunnyvale, CA 94085 www.electric-cloud.com
Copyright 2006 - 2011 Electric Cloud, Inc. All rights reserved.

Published September 12, 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, and Electric Make are registered trademarks of Electric Cloud, Incorporated. Electric Cloud productsElectricAccelerator, ElectricCommander, ElectricInsight, and Electric Makeare commonly referred to by their "short names"Accelerator, 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.
ElectricCommander Installation Guide
Contents
Chapter 1
ElectricCommander Introduction
What is ElectricCommander? ................................................................................... 1-1 Challenges solved by ElectricCommander ................................................. 1-1 What Makes ElectricCommander Unique? ........................................................ 1-1 Overview ..................................................................................................... 1-1 Architecture ........................................................................................................ 1-2 Commander simple architectural overview................................................. 1-3 Other configurations.................................................................................... 1-3
Chapter 2
System Requirements and Supported Platforms

System Requirements and Supported Platforms ...................................................... Server, web server, or repository server platforms............................................. Microsoft Windows..................................................................................... Linux ........................................................................................................... Agent platforms .................................................................................................. Hardware Requirements ..................................................................................... Software Requirements ...................................................................................... Port Usage .......................................................................................................... Database Information ......................................................................................... Database growth.......................................................................................... Default Installation Directories .......................................................................... Log File Locations.............................................................................................. For Windows ............................................................................................... For UNIX .................................................................................................... Disk Usage ......................................................................................................... Memory Usage ................................................................................................... Server/Agent Compatibility ............................................................................... The "checksum" utility ....................................................................................... 2-1 2-1 2-1 2-1 2-2 2-3 2-3 2-4 2-4 2-4 2-5 2-5 2-5 2-6 2-6 2-7 2-7 2-7
Chapter 3
Installing ElectricCommander
General Information ................................................................................................. 3-1 User Interface Installation Method ........................................................................... 3-1 Express Server Installation ................................................................................. 3-2 Express Agent Installation.................................................................................. 3-7 Advanced Installation....................................................................................... 3-10 Example 1 - complete ElectricCommander installation............................ 3-11 Example 2 - installing a Commander agent .............................................. 3-17 Example 3 - installing a remote Commander web server ......................... 3-22
3
Contents
Example 4 - Installing a remote repository server and agent ................... Example 5 - installing Commander tools only ......................................... Interactive Command-line Installation Method ..................................................... Express Server .......................................................................................... Express Agent........................................................................................... Advanced - All components ..................................................................... Advanced - Agent only............................................................................. Advanced - Repository Server and agent ................................................. Advanced - Web Server only.................................................................... Advanced - Tools only.............................................................................. Silent Unattended Installation Method .................................................................. Linux Silent Installation Examples.................................................................. All components with default options........................................................ Repository Server and Agent with default options................................... Agent only with default options ............................................................... Web Server only with default options ...................................................... Tools only with default options ................................................................ Windows Silent Installation Examples ............................................................ All components with default options........................................................ Repository Server only with default options ............................................ Agent only with default options ............................................................... Web Server only with default options ...................................................... Tools only with default options ................................................................ Installing Agents on Non-Server-Supported Platforms ......................................... UNIX Agent Command-line Installation......................................................... UNIX Agent Silent Installation ....................................................................... Silent Installation Configuration Parameters by Install Type...................
3-28 3-34 3-37 3-37 3-37 3-38 3-39 3-39 3-40 3-41 3-42 3-44 3-44 3-44 3-44 3-44 3-44 3-44 3-44 3-45 3-45 3-45 3-45 3-46 3-46 3-47 3-48
Chapter 4
Upgrading ElectricCommander
ElectricCommander Upgrade Process...................................................................... Before you begin the upgrade process... ............................................................ Important MySQL Upgrade Note ...................................................................... Performing a Clean Installation...................................................................... Upgrading to Commander 4.0 and the artifact repository server....................... User Interface Upgrade Method............................................................................... Interactive Command-line Upgrade Method ........................................................... Silent Unattended Upgrade Method......................................................................... Upgrading Agents on Non-Server-Supported Platforms ......................................... 4-1 4-1 4-2 4-2 4-2 4-2 4-8 4-8 4-8
Chapter 5
Initial Configuration Tasks

Default MySQL Database Security.......................................................................... External Database Configuration ............................................................................. Configuring Commander to Use an Alternate Database.......................................... Using the Web Interface to Set the Database Configuration ............................. Using ectool to Set the Database Configuration ................................................ Switching to an Alternate Database ......................................................................... Logging in and Licensing ........................................................................................ Applying the License Key ................................................................................. Making the Plugins Directory Universally Accessible ............................................ Configure Commander server, agents, and web servers to point to a universally accessible network location.................................................... Keep the plugins directory in its default server location and replicate the contents to remote agents and web servers ............................................ 5-1 5-1 5-2 5-2 5-3 5-4 5-5 5-5 5-7 5-7 5-8
Contents
If you have a proxy server in your environment... ................................................... 5-9 Troubleshooting.................................................................................................. 5-9 Web Interface Online Help System .......................................................................... 5-9
Chapter 6
Uninstalling ElectricCommander
Uninstalling ElectricCommander ............................................................................. 6-1 Windows Uninstall ............................................................................................. 6-1 UNIX Uninstall .................................................................................................. 6-1
Chapter 7
Other Related Topics

Backing up Your Commander Server ....................................................................... 7-1 Recommendations .............................................................................................. 7-1 Prerequisites ....................................................................................................... 7-1 Backup steps....................................................................................................... 7-1 Restoring Your Commander Server.......................................................................... 7-2 Prerequisites ....................................................................................................... 7-2 Scenario 1: Restore a backup to the same Commander server and database ............................................................................. 7-2 Scenario 2: Keep the same Commander server but switch the database .... 7-3 Scenario 3: Switch the Commander server but keep the same database..... 7-3 Scenario 4: Switch both the Commander server and the database.............. 7-4 Scenario 5: Create a clone of the Commander server and the database...... 7-5 MySQL database commands.............................................................................. 7-6 Notes............................................................................................................ 7-6 Creating a database dump ........................................................................... 7-6 Restoring a database dump.......................................................................... 7-7 Modifying the data to disable schedules and resources .............................. 7-7 Backing up and restoring your repository backingstores ................................... 7-7 Apache Web Server or Agent Certificates................................................................ 7-8 Description ......................................................................................................... 7-8 Generating a signed certificate for the ElectricCommander web server or agent: ............................................................................................. 7-8 Send the request to the CA ................................................................................. 7-8 Install the signed certificate................................................................................ 7-8 Alternate: Generating a new self-signed certificate to update a hostname ........ 7-8 Alternate: Restoring the default configuration ................................................... 7-9 Using chkconfig........................................................................................................ 7-9 Manual Server/Agent Stop and Start ........................................................................ 7-9 Solution for Stop................................................................................................. 7-9 Solution for Start .............................................................................................. 7-10
Chapter 8
Troubleshooting
If the Commander server is unresponsive and displays an OutOfMemory error .............................................................................. 8-1 Installing Commander on a virtual machine (VM) ..................................... 8-1 On Windows, PHP does not handle certain operating system timezones correctly ............................................................................... 8-2
Contents
1
nvisible Body Tag
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 scaleable solution, solving some of the biggest challenges of managing these "back-end" software development tasks. Challenges solved by ElectricCommander 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 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 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: Shared platform for disseminating best practices and reusing common procedures Ability to support geographically distributed teams Continuous integration and greater agility Faster throughput and more efficient hardware utilization Visibility/reporting for better project predictability Better software quality by integrating and validating against all target platforms and configurations
What Makes ElectricCommander Unique?

ElectricCommander is the most scaleable 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. Overview Here are some of the facilities ElectricCommander provides: Artifact Management functionality: 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.
1-1
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. 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. Runs jobs according to schedules you define. You can schedule jobs to run either at particular times or when source code changes are checked in to your source code control system. ElectricCommander integrates with major source code control systems. 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. 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. 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. Allows you to observe jobs as they run and to cancel jobs. A workspace for each joba disk area jobs can use for storage. All ElectricCommander features are available from a command-line tool (ectool), a Perl API, as well as a web interface. 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). Access control: users log into the system and ElectricCommander uses their information to control their activities. ElectricCommander integrates with Active Directory and LDAP repositories. 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. 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. Preflight Build functionalityused by developers to build and test code changes in isolation on their local machines before those changes are committed to a production build A growing number of IDE integrations such as Visual Studio and Eclipse, which enable proactive execution of preflight build and test procedures without requiring developers to leave their IDE.
Architecture
ElectricCommander was architected from the ground up to support enterprise scale software production. Based on a 3-tier architecture, Commander scales to handle large, complex environments. Commanders multi-threaded Java server provides efficient synchronization even under high job volume. The Commander server manages resources, issues commands, generates reports. An underlying database stores commands, metadata, and log files. Agents execute commands, monitor status, and collect results, in parallel across a cluster of servers for rapid throughput.
See the illustrated architecture overview on the next page.
1-2
Commander simple architectural overview
Other configurations Remote web servers or multiple web servers at your current site Remote repository servers or multiple repository servers at your current site Remote database Proxy resources
The next illustration is an example for how you might set up a remote web server installation.
What is ElectricCommander?
1-3
This type 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.
1-4
2
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.

Server, web server, or repository server platforms
Microsoft Windows XP - Service Pack 2 or higher required for hosts running Windows XP Server 2003 - Service Pack 2 recommended but not required Server 2008 and 2008 R2 Windows 7
Server 2008 Windows 7 Note:
Notes:
An administrator may need to disable User Account Control (UAC). If the installer runs under account X, but services will run under account Y, install directories (both program and data) will probably have permissions that prevent Ys access. This applies particularly to data directories. Linux Red Hat Enterprise Linux 4, 32-bit Red Hat Enterprise Linux 5, 32 and 64-bit Red Hat Enterprise Linux 6, 32 and 64-bit SUSE Linux Enterprise Server 10.3, 32 and 64-bit SUSE Linux Enterprise Server 11, 32 and 64-bit Ubuntu 8.04, 32-bit Ubuntu 9, 32 and 64-bit Ubuntu 10, 32 and 64-bit 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.
RHEL 3 Note:
For all Windows versions, 32 and 64-bit are supported.
Notes:
Red Hat Linux 3 is no longer supported as a Commander server or web server machine, but you may continue to use this platform for agents.
2-1
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.
RHEL 5 Note:
If you plan to use ElectricCommander on RHEL5.x, the supported installation method requires the SeLinux configuration to be less restrictiveset 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.
RHEL 6 Note:
If you plan to use Commander on RHEL 6.x, 64-bit, you need to run one or both 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 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. Note: Before attempting any Commander installation, Electric Cloud recommends running both of these commands on your RHEL 6, 64-bit machines. These commands contain 32-bit libraries, omitted by Red Hat, but required for the Commander installation executable file to work.
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.
Ubuntu 9.10 64-bit Note:
Before installing ElectricCommander, you must install Ubuntus 32-bit compatibility layer by running the following command: sudo apt-get install ia32-libs 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.
Agent platforms
All server machines specified for the ElectricCommander server See RHEL 5 note for Commander server above. See RHEL 6 note above for 64-bit installations. See Ubuntu 9.10 64-bit note for Commander server above.
Red Hat Enterprise Linux 2.1 and 3 Red Hat Enterprise Linux 4 (64-bit) Microsoft Windows 2000 Sun Solaris 8, 9 [Architecture: Sparc only] Sun Solaris 10 [Architecture: Sparc and Intel x86]
Solaris 8 Note:
On Solaris 8, the installer will not generate a self-signed certificate for the agent unless OS patch112438-03 is installed on the system. This patch installs a random number generating device in /kernel/drv/random. If you do not have this patch, download it from
http://sunsolve.sun.com/search/document.do?assetkey=1-21-112438-03-1
Reboot the machine after installing this patch to create and initialize the device(s) properly. To verify the patch installed properly, check to see if /kernel/drv/random exists. Install the agent after patch verification.
2-2
HP-UX 11i v1 (11.11) or higher [Architecture: PA-RISC 2.0] Make sure the following patches (or patches superceding these patches) are installed: PHKL_29243, PHSS_39077
HPUX Secure Shell Note:
HP-UX Secure Shell requires that a random number generator be located on the system. It searches for /dev/urandom and /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. Mac OS X 10.4 (Tiger) or higher (Architecture: Intel)
Note: If you plan to use any supported Commander agent as a proxy agent, the proxy agent requires a running SSH v2 server on all proxy target agents. For more information on proxy target agents, see the Configuration and Resource online help topics.
Hardware Requirements
Minimum requirements for either the Windows or Linux machine where the ElectricCommander server is installed: Processor clock rate: 1.5 GHz or higher Memory: 2 GB RAM or more Cores: 2 or more
Software Requirements
To connect to ElectricCommander, your web browser must be one of the following: Microsoft Internet Explorer 7.0 or higher Mozilla Firefox 2.0 or higher. (Firefox versions below v2.0 are not supported.) Chrome 13 or higher
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: Choose different web server ports. Uninstall the existing web server. Disable the existing web server. Reconfigure the existing web server to use another port.
If you are installing the default ElectricCommander MySQL database, and another application is using port 3306, you have 4 options: Choose a different port. Uninstall the existing application. Disable the existing application. Reconfigure the existing application to use another port.
2-3
Port Usage
By default, ElectricCommander uses the following ports: 8000 - ElectricCommander Server 8443 - ElectricCommander Server (SSL port) 80 - ElectricCommander Web Server 443 - ElectricCommander Web Server (SSL port) 3306 - ElectricCommander MySQL Service 7800 - ElectricCommander Agents (by default, this is an HTTPS port) 61613 - Preflight file transfer port, other file transfer, event notifications, or other messaging 8200 - Artifact repository server (by default, this is an HTTPS port)
Other database ports: 1521 - Oracle 11g Release 1, and R2 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 MySQL [default] database on the server machine. AFTER ElectricCommander server installation is complete, you must choose an alternate database before you can begin using Commander. ElectricCommander supports the following alternate databases: Your existing MySQL database if it is MySQL 5.0, 5.1, or 5.5.12 or higher MS SQL Server 2005 with Service Pack 2 and higher, or MS SQL Server 2008, 2008 R2 Oracle 10g R2 (including RAC) Oracle 11g Release 2, R2
If you chose the default Commander database during installation, you may switch to an alternate database at anytime in the future. See Chapter 5, Initial Configuration Tasks for more information. Notes: 1. You will not be able to login 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: Estimate the number of jobs per period, multiply the "job number" estimate by the number of steps estimated per job, 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.
2-4
Default Installation Directories

You can change the installation directories if you need to do so. Default for Windows program files: C:\Program Files\Electric Cloud\ElectricCommander Defaults for Windows data (database, logs, configuration files): For Windows XP or 2003 C:\Documents and Settings\All Users\Application Data\ Electric Cloud\ElectricCommander
For Windows 2008 or Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander
UNIX/Mac: /opt/electriccloud/electriccommander
Log File Locations

The following information is for default "run time" log locations. For Windows Agent Default for Windows XP, 2003 C:\Documents and Settings\All Users\Application Data\ Electric Cloud\ElectricCommander\logs\agent
Default for Windows 2008, Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander\logs\agent
Server Default for Windows XP, 2003 C:\Documents and Settings\All Users\Application Data\ Electric Cloud\ElectricCommander\logs
Default for Windows 2008, Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander\logs
Web server Default for Windows XP, 2003 C:\Documents and Settings\All Users\Application Data\ Electric Cloud\ElectricCommander\apache\logs
Default for Windows 2008, Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander\apache\logs
Repository server Default for Windows XP, 2003 C:\Documents and Settings\All Users\Application Data\ Electric Cloud\ElectricCommander\logs\repository
Default for Windows 2008, Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander\logs\repository
Installer Default for Windows XP, 2003 C:\Documents and Settings\All Users\Application Data\ Electric Cloud\ElectricCommander\logs
Default for Windows 2008, Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander\logs
2-5
For UNIX Agent

/opt/electriccloud/electriccommander/logs/agent
Server
/opt/electriccloud/electriccommander/logs
Web server
/opt/electriccloud/electriccommander/apache/logs
Repository server
/opt/electriccloud/electriccommander/logs/repository
Installer
/opt/electriccloud/electriccommander/logs
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.xmland 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: Server - 10 GB Agents - 100 MB each 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 fee 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. Repository server - If using Artifact Management functionality, you could need 20-30 GB, or more disk space for your repository server. 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. Sizing the repository backingstore For a repository installation, by default, the repository backingstore is the <data-dir>/repository-data directory. You can modify the <data-dir>/conf/repository/server.properties file 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.
2-6
Memory Usage
Memory usage varies depending on whether or not the ElectricCommander server is a dedicated machine. By default, minimum memory usage is 25% of free memory on a 32-bit system or 40% on a 64-bit system, assuming the ElectricCommander server is running on a dedicated machine and usage is light. To adjust the memory level, go to the ElectricCommander directory to modify the
wrapper.java.initmemory.percent and wrapper.java.maxmemory.percent lines in wrapper.conf:
For Windows XP or 2003:

c:\Documents and Settings\All Users\Application Data\Electric Cloud\ ElectricCommander\conf\wrapper.conf
For Windows 2008 or Windows 7 c:\ProgramData\Electric Cloud\ElectricCommander\conf\wrapper.conf
For Linux:
/opt/electriccloud/electriccommander/conf/wrapper.conf
For a repository server: Windows:

c:\Documents and Settings\All Users\Application Data\Electric Cloud\ ElectricCommander\conf\repository\wrapper.conf -orc:\ProgramData\Electric Cloud\ElectricCommander\conf\repository \wrapper.conf
Linux:
/opt/electriccloud/electriccommander/conf/repository/wrapper.conf
Server/Agent Compatibility
All ElectricCommander Agent versions are forward and backward compatible with all ElectricCommander Server versions. For example, an ElectricCommander v3.5 Agent is compatible with an ElectricCommander v4.0 Server; and conversely, an ElectricCommander v3.5 server is compatible with an ElectricCommander v4.0 Agent. Note: ElectricCommander pre-v3.5 agents are no longer supported.
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. On Linux, verify with md5sum --check ElectricCommander-xx.md5 Most Linux installations provide an md5sum command for calculating MD5 message digests. An MD5 utility for Windows can be downloaded at www.fourmilab.ch/md5/.
To use the MD5 checksum utility on a Mac: 1. 2. 3. 4. 5. In Finder, browse to /Applications/Utilities. Double-click on the Terminal icon. A Terminal window appears. In the Terminal window, type: "md5" (followed by a space). Drag the downloaded file from the Finder into the Terminal window. Click in the Terminal window, press the Return key, and compare the checksum displayed on the screen to the one on the download page.
2-7
2-8
3
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 Chapter 4, Upgrading ElectricCommander. 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, 64-bit versions of the Java Runtime Environment and MySQL database are installed automatically. 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:
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 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 (version) Install Wizard, appears with three options as follows:
Express Server
Select this option to install the ElectricCommander server, including the web, repository, and database servers, one agent to run jobs from this machine, and Commander tools.
Express Agent
Select this option to install a Commander agentthis installation also includes Commander tools. Use this option for managed hosts where you intend to run job steps.
3-1
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 the Advanced Installation section for 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 and database servers, one agent to run jobs from this machine, and Commander tools. Double-click the ElectricCommander-<version> file to begin installation.
Select the Express Server installation type. Click Next to continue.
3-2
Note: The following screen example is for Windows only. If you are installing on a Linux machine, see the additional Linux field descriptions below.
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.
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.
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.
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:
User Name - This is the user who owns the Commander server, repository server, and web server processes. Group Name - This is the group that owns the Commander server, repository server, and web server processes. 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. Note: If you select this checkbox, you will not see the following screen with fields to supply your agent service account information.
3-3
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.
Type-in the account User Name and Password. This account is the one used to run the Commander agent service.
blank.
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.
On Linux machines:
User Name - This is the user who owns the Commander agent process. Group Name - This is the group that owns the Commander agent process.
Click Next to continue.
3-4
Review the default settings and your service account selections. Use the Back button to change your service account selections if necessary. Click Next to continue.
Please wait while ElectricCommander is installing all componentsthis process may take fifteen minutes. The Commander server will start when installation is complete.
3-5
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.
3-6
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-46.
Select Express Agent to beginthis installation also installs Tools. Click Next to continue.
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.
3-7
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. Password - Specify the password for the Commander user. The default password for the admin user is changeme. 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 chapter 5, Making the Plugins Directory Universally Accessible on page 5-7.
Create a resource - Check this box to create a resource on the remote Commander server for the agent you are
installing.
Resource Name - Supply the name you would like to use for this resource.
blank.
On Linux machines:
3-8
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 installedthis will take just a few minutes. Click Next to continue.
3-9
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 Install Wizard screen appears, select Advanced to begin.
Click Next to continue. The next screen displays individual components to install. Note: Commander tools are automatically installed with each installation type.
3-10
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 four examples are provided: Installing the ElectricCommander server and all components Installing a Commander agent Installing a remote Commander web server Installing a remote Commander repository server and agent 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.
Select all checkboxes and click Next to continue.
3-11
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.
Supply the host name users need to type into their browser to access the Commander web server. Click Next to continue.
3-12
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.
blank.
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.
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:
User Name - This is the user who owns the Commander server, web server, and repository server processes. Group Name - This is the group that owns the Commander server, web server, and repository server processes. 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. Note: If you select this checkbox, you will not see the following screen with fields to supply your agent service account information.
3-13
blank.
On Linux machines:
3-14
Review default settings and any custom specifications. Use the Back button to modify any information if necessary. Click Next to continue.
Please wait while ElectricCommander installs all components and filesthis process may take fifteen minutes. The Commander server will start when installation is complete.
3-15
the login screen now. Click Finish to complete the installation.
3-16
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-46. Select Agent to beginthis installation also installs Tools.
Commander uses these default directories for installation. Click Browse to specify other directory locations if you prefer to do so.
3-17
Click Next to accept the default locations or the directory locations you specified.
Commander uses the default port displayed on this screen. You can accept this default port specification or type-in an alternate port number. Click Next to continue.
Server Host Name - Type-in the name of the ElectricCommander server that will communicate with this agent. If the remote Commander server is using non-default ports, you must specify the Server Host Name as host:port. 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. Password - Specify the password for the Commander user. The default password for the admin user is changeme.
3-18
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 chapter 5, Making the Plugins Directory Universally Accessible on page 5-7. Create a resource - Check this box to create a resource on the remote Commander server for the agent you are
installing.
Resource Name - Supply the name you would like to use for this resource.
blank.
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.
On Linux machines:
3-19
Review the default and your custom specifications. Use the Back button to modify any information if necessary. Click Next to continue.
Please wait while ElectricCommander installs the agent, tools, and associated files.
3-20
Click Finish to complete the Commander agent installation.
3-21
Example 3 - installing a remote Commander web server 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. As long as the remote workspace is mounted on the web server, 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 twiceonce 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 user's local (remote) site, links to all log files are links to the local users workspace. Because log files are accessed by the web server only, and not the Commander server, both trips across the WAN are eliminated. The Commander web server reads the log file locally, then serves the page to the user whose browser is also local. Note: You can install Commander web servers on any Windows or Linux platform suitable for installing the Commander server. Double-click the ElectricCommander-<version> file to begin installation. On the Advanced installation screen, select Web server to begin.
3-22
This is the name of web server host that users will type into their browser to access ElectricCommander.
3-23
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. Commander User Name - Specify the name of a user on the Commander server. Defaults to the Commander-supplied admin user. Password - Specify the password for the Commander user. The default password for the admin user is changeme. 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 chapter 5, Making the Plugins Directory Universally Accessible on page 5-7.
3-24
Type-in the account User Name and Password. This account is the one used to run the web server service.
blank.
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.
On Linux machines:
User Name - This is the user who owns the web server process. Group Name - This is the group that owns the web server process.
3-25
Verify that all specified information is what you intended or use the Back button to modify a setting. Click Next to continue.
Please wait while ElectricCommander installs a remote web server.
3-26
the login screen now. Click Finish to complete the Commander remote web server installation.
3-27
Example 4 - Installing a remote repository server and 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 and Agent to begin. Note: Electric Cloud recommends installing an agent on the same machine as a repository server. The repository server's backingstore can then be cleaned up by running a job on this agent rather than logging into each remote repository server and running the command manually.
Select all checkboxes and click Next to continue.
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.
3-28
Server Host Name - Type-in the name of the ElectricCommander server that will communicate with this agent. If the remote Commander server is using non-default ports, you must specify the Server Host Name as host:port. 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. Password - Specify the password for the Commander user. The default password for the admin user is changeme.
3-29
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 chapter 5, Making the Plugins Directory Universally Accessible on page 5-7.
Create a resource - Check this box to create a resource on the remote Commander server for the agent you are
installing.
Resource Name - Supply the name you would like to use for this resource. Create a repository - Check this box to create a repository object on the remote Commander server for the
repository server you are installing.

Repository Name - Supply the name you would like to use for this repository object.
Type-in the account User Name and Password. This account is the one used to run the Commander repository server service.
blank.
Use the local system account checkbox - check this box if you want the repository server service to run as the local Windows system account. Note: The local system account does not have access to network shares. 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. 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:
User Name - This is the user who owns the Commander repository server process. Group Name - This is the group that owns the Commander repository server process. 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.
3-30
Note: If you select this checkbox, you will not see the following screen with fields to supply your agent service account information. 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.
blank.
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.
On Linux machines:
3-31
Review default settings and any custom specifications. Use the Back button to modify any information if necessary. Click Next to continue.
Please wait while ElectricCommander installs all components and filesthis process may take fifteen minutes. The Commander server will start when installation is complete.
3-32
Click Finish to complete the installation.
3-33
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. Select Advanced to see the following screen and then make sure no checkboxes are selected. Notice the Tools checkbox remains selected by default.
Accept the default installation directory or click Browse to select the directory you prefer. Click Next to continue.
3-34
Verify that the settings are correct or use the Back button to make a change. Click Next to continue.
Please wait while Commander installs Tools files on this machine.
3-35
Click Finish to complete the Commander Tools installation.
3-36
Interactive Command-line Installation Method

Note: A Windows command-line installation is not supported. You can use the interactive command-line installation method for Linux-only installs. If you have X installed, running the installer will bring up the graphical user interface automatically. However, you can use the command-line installation method if you specify ./ElectricCommander-<version> --mode console. Install Commander on a local Linux volume. Electric Cloud does not support installing the Commander server on a network volume. Note: You may install ElectricCommander agent software on 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-46. Express Server
./ElectricCommander-<version> Copyright (c) 2006-2011, Electric Cloud, Inc. All rights reserved. This will install ElectricCommander on your computer. Continue? [n/Y] y Specify the type of setup you would like to perform: expressServer, expressAgent, or advanced. [expressServer] Specify the user the server, web, and/or repository will run as. [] <user> Specify the group the server, web, and/or repository will run as. [] <group> Use the same service account for the agent (not recommended for production systems)? [y/N] n Specify the user the agent will run as. [] <user> Specify the group the agent will run as. [] <group> Installing ElectricCommander... Installing agent... Installing server... Installing tools... Installing web... Installing database-32... Installing jre-32... Installing repository... Copied log file to "/opt/electriccloud/electriccommander/logs" ElectricCommander <version> was successfully installed! Installer log file: /opt/electriccloud/electriccommander/logs/installer.log.
Express Agent
./ElectricCommander-<version> Copyright (c) 2006-2011, Electric Cloud, Inc. All rights reserved. This will install ElectricCommander on your computer. Continue? [n/Y] y Specify the type of setup you would like to perform: expressServer, expressAgent, or advanced. [expressServer] expressAgent Discover the plugins directory from a remote Commander server? [y/n] y Create a resource for the installed agent on a remote Commander server? [y/n] y Specify the host:port of a remote Commander server the agent and/or web server being installed can link to. The port is only required if it is not the default. [] <hostName:port> Specify the user name with which to login to <hostName:port>. [admin] Specify the password for "admin" on <hostName:port>. [] <changeme> Specify the name of the resource to create on <hostName:port>. [myHost] <resourceName>
3-37
Specify the user the agent will run as. [] <user> Specify the group the agent will run as. [] <group> Installing ElectricCommander... Installing agent... Installing tools... Copied log file to "/opt/electriccloud/electriccommander/logs" ElectricCommander <version> was successfully installed! Installer log file: /opt/electriccloud/electriccommander/logs/installer.log.
Advanced - All components

./ElectricCommander-<version> Copyright (c) 2006-2011, Electric Cloud, Inc. All rights reserved. This will install ElectricCommander on your computer. Continue? [n/Y] y Specify the type of setup you would like to perform: expressServer, expressAgent, or advanced. [expressServer] advanced Install a Commander server? [n/Y] y Install a local MySQL database? [n/Y] y Install an Apache web server? [n/Y] y Install a Commander agent? [n/Y] y Install a Commander repository server? [n/Y] y Specify the install directory (for program files and binaries). [/opt/electriccloud/electriccommander] Specify the data directory (for configuration files and logs). [/opt/electriccloud/electriccommander] Specify the server HTTP port. [8000] Specify the server HTTPS port. [8443] Specify the server file transfer port. [61613] Specify the database port. [3306] Specify the web HTTP port. [80] Specify the web HTTPS port. [443] Specify the agent port. [7800] Specify the repository port. [8200] Specify the host name that users will type in their browser to access the web server. [hostName] Specify the user the server, web, and/or repository will run as. [] <user> Specify the group the server, web, and/or web repository will run as. [] <group> Use the same service account for the agent (not recommended for production systems)? [y/N] n Specify the user the agent will run as. [] <user> Specify the group the agent will run as. [] <group> Installing ElectricCommander... Installing agent... Installing server... Installing tools... Installing web... Installing database-32... Installing jre-32... Installing repository... Copied log file to "/opt/electriccloud/electriccommander/logs" ElectricCommander <version> was successfully installed! Installer log file: /opt/electriccloud/electriccommander/logs/installer.log.
3-38
Advanced - Agent only

./ElectricCommander-<version> Copyright (c) 2006-2011, Electric Cloud, Inc. All rights reserved. This will install ElectricCommander on your computer. Continue? [n/Y] y Specify the type of setup you would like to perform: expressServer, expressAgent, or advanced. [expressServer] advanced Install a Commander server? [n/Y] n Install an Apache web server? [n/Y] n Install a Commander agent? [n/Y] y Install a Commander repository server? [n/Y] n Specify the install directory (for program files and binaries). [/opt/electriccloud/electriccommander] Specify the data directory (for configuration files and logs). [/opt/electriccloud/electriccommander] Specify the agent port. [7800] Discover the plugins directory from a remote Commander server? [y/n] y Create a resource for the installed agent on a remote Commander server? [y/n] y Specify the host:port of a remote Commander server the agent and/or web server being installed can link to. The port is only required if it is not the default. [] <hostName:port> Specify the user name with which to login to <hostName:port>. [admin] Specify the password for "admin" on <hostName:port>. [] <changeme> Specify the name of the resource to create on <hostName:port>. [myHost] <resourceName> Specify the user the agent will run as. [] <user> Specify the group the agent will run as. [] <group> Installing ElectricCommander... Installing agent... Installing tools... Copied log file to "/opt/electriccloud/electriccommander/logs" ElectricCommander <version> was successfully installed! Installer log file: /opt/electriccloud/electriccommander/logs/installer.log.
Advanced - Repository Server and agent ./ElectricCommander-<version>

Copyright (c) 2006-2011, Electric Cloud, Inc. All rights reserved. This will install ElectricCommander on your computer. Continue? [n/Y] y Specify the type of setup you would like to perform: expressServer, expressAgent, or advanced. [expressServer] advanced Install a Commander server? [n/Y] n Install an Apache web server? [n/Y] n Install a Commander agent? [n/Y] y Install a Commander repository server? [n/Y] y Specify the install directory (for program files and binaries). [/opt/electriccloud/electriccommander] Specify the data directory (for configuration files and logs). [/opt/electriccloud/electriccommander] Specify the agent port. [7800] Specify the repository server port. [8200]
3-39
Discover the plugins directory from a remote Commander server? [n/Y] y Create a resource for the installed agent on a remote Commander server? [n/Y] y Create a repository object on a remote Commander server? [n/Y] y Specify the host:port of a remote Commander server, the agent, repository server, and/or web server being installed can link to. The port is only required if it is not the default. [] <hostName:port> Specify the user name with which to login to <hostName:port>. [admin] Specify the password for "admin" on <hostName:port>. [] <changeme> Specify the name of the resource to create on <hostName:port>. [upgrade-linux] <resourceName> Specify the name of the repository to create on <hostName:port>. <repositoryName> Specify the user the server, web, and/or repository will run as. [] <user> Specify the group the server, web, and/or repository will run as. [] <group> Use the same service account for the agent (not recommended for production systems)? [n/Y] n Specify the user the agent will run as. [] <user> Specify the group the agent will run as. [] <group> Installing ElectricCommander... Installing tools... Installing jre-32... Installing agent... Installing repository... Copied log file to "/opt/electriccloud/electriccommander/logs" ElectricCommander <version> was successfully installed! Installer log file: /opt/electriccloud/electriccommander/logs/installer.log.
Advanced - Web Server only

./ElectricCommander-<version> Copyright (c) 2006-2011, Electric Cloud, Inc. All rights reserved. This will install ElectricCommander on your computer. Continue? [n/Y] y Specify the type of setup you would like to perform: expressServer, expressAgent, or advanced. [expressServer] advanced Install a Commander server? [n/Y] n Install an Apache web server? [n/Y] y Install a Commander agent? [n/Y] n Install a Commander repository server? [n/Y] n Specify the install directory (for program files and binaries). [/opt/electriccloud/electriccommander] Specify the data directory (for configuration files and logs). [/opt/electriccloud/electriccommander] Specify the web HTTP port. [80] Specify the web HTTPS port. [443] Specify the host name that users will type in their browser to access the web server. <hostName> Discover the plugins directory from a remote Commander server? [y/n] y Specify the host:port of a remote Commander server the agent and/or web server being installed can link to. The port is only required if it is not the default. [] <hostName> Specify the user name with which to login to <hostName:port>. [admin] Specify the password for "admin" on <hostName:port>. [] <changeme>
3-40
Specify the user the server, web, and/or repository will run as. [] <user> Specify the group the server, web, and/or repository will run as. [] <group> Installing ElectricCommander... Installing tools... Installing web... Copied log file to "/opt/electriccloud/electriccommander/logs" ElectricCommander <version> was successfully installed! Installer log file: /opt/electriccloud/electriccommander/logs/installer.log.
Advanced - Tools only

./ElectricCommander-<version> Copyright (c) 2006-2011, Electric Cloud, Inc. All rights reserved. This will install ElectricCommander on your computer. Continue? [n/Y] y Specify the type of setup you would like to perform: expressServer, expressAgent, or advanced. [expressServer] advanced Install a Commander server? [n/Y] n Install an Apache web server? [n/Y] n Install a Commander agent? [n/Y] n Specify the install directory (for program files and binaries). [/opt/electriccloud/electriccommander] Installing tools... Copied log file to "/opt/electriccloud/electriccommander/logs" ElectricCommander <version> was successfully installed! Installer log file: /opt/electriccloud/electriccommander/logs/installer.log.
3-41
Silent Unattended Installation Method

You can run the ElectricCommander installer in unattended (silent) mode with no user interface for either Windows or Linux. Use the arguments in the following list to construct the commands you need for the particular installation you need to perform. For example: server, agent, web server, and so on. See examples for typical installation types following the argument list. This argument list is an excerpt from the installer help text and can be found by running the following command: ElectricCommander-<version> --help From a command line, invoke the following command to begin a silent install: ElectricCommander-<version> --mode silent ...
IMPORTANT
Only limited validity checking is performed on these values during an unattended installation, which means typing errors or other mistakes may manifest themselves in strange ways.
ElectricCommander-<version> --help Usage: ElectricCommander-<version> [options ...] Available Options: --agentPort [ARG] --databasePort [ARG] --dataDirectory [ARG] --force32Bit --help --installAgent --installDatabase --installDirectory [ARG] --installRepository --installServer --installWeb --mode [ARG]
Port used by the installed Commander agent. Port used by the installed MySQL database. Directory used to store configuration files, logs, and database artifacts. Force a 32-bit install, even if the machine is 64-bit. Display this information. Install the Commander agent. Install a local MySQL database to use with the main Commander server. Directory used to store program files and binaries. Install a Commander artifact repository server. Install the main Commander server. Install the local web server and Commander web interface. The mode in which the installer will run. Available values: command-line, silent, or standard If specified, previously installed versions will be ignored, and version <version> will be installed. The host:port for the remote Commander server. The port is optional and can be omitted if the server is using the default HTTP port. Create a repository object on the remote Commander server. Create a resource for the installed agent on the remote Commander server. Set the plugins directory for the installed agent and/or web server to the shared plugins directory defined on the remote Commander server. Discover the ports for the remote Commander server so the web server can connect to it. The password to use when logging in to the remote Commander server.
--overwrite
--remoteServer [ARG]
--remoteServerCreateRepository --remoteServerCreateResource --remoteServerDiscoverPlugins
--remoteServerDiscoverPorts --remoteServerPassword [ARG]
3-42
ElectricCommander-<version> --help Usage: ElectricCommander-<version> [options ...] Available Options: --remoteServerRepository [ARG] --remoteServerResource [ARG] --remoteServerUser [ARG] --repositoryPort [ARG] --response-file [ARG] --save-response-file [ARG] --serverFileTransferPort [ARG] --serverHttpPort [ARG] --serverHttpsPort [ARG] --temp [ARG] --unixAgentGroup [ARG] --unixAgentUser [ARG] --unixServerGroup [ARG] --unixServerUser [ARG] --useSameServiceAccount
The name of the repository to create on the remote Commander server. The name of the resource to create on the remote Commander server. The username to use when logging in to the remote Commander server. Port used by the Commander artifact repository server (default is 8200). A file containing installer responses. A file for writing installer responses to when the installer exists. File transfer port used by the installed Commander server. HTTP port used by the installed Commander server. HTTPS port used by the installed Commander server. Directory used to store temporary files used by the installer. The group the installed Commander agent runs as. The user the installed Commander agent runs as. The group the installed Commander server and/or web server runs as. The user the installed Commander server and/or web server runs as. Use the same account for server and agent services. Not recommended for production systems. Display installer version information. The name users need to type in their browser to access the web server. HTTP port used by the installed web server. HTTPS port used by the installed web server. The domain of the account the installed Commander agent runs as. Run the Commander agent as the local system account. The password of the account the installed Commander agent runs as. The user name of the account the installed Commander agent runs as. The domain of the account the installed Commander server and/or web server run as. Run the Commander server and/or web server as the local system account. The password of the account the installed Commander server and/or web server run as. The user name of the account the installed Commander server and/or web server run as. Do not check that the user running the installer is a direct member of group Administrators.
--version --webHostName [ARG] --webHttpPort [ARG] --webHttpsPort [ARG] --windowsAgentDomain [ARG] --windowsAgentLocalSystem --windowsAgentPassword [ARG] --windowsAgentUser [ARG] --windowsServerDomain [ARG] --windowsServerLocalSystem --windowsServerPassword [ARG] --windowsServerUser [ARG] --windowsSkipAdminCheck
3-43
Linux Silent Installation Examples

The following examples are command strings to use for unattended (silent) installations. The examples are shown with options, each on a separate line for viewing ease. However, you must enter all values on a single line. All components with default options ./ElectricCommander-<version>
--mode silent --installServer --installAgent --installDatabase --installWeb --installRepository --unixServerUser <user> --unixServerGroup <group> --unixAgentUser <user> --unixAgentGroup <group>
Note: Electric Clouds recommends installing an agent along with a repository server. Repository Server and Agent with default options ./ElectricCommander-<version>
--mode silent --installRepository --installAgent --unixAgentUser <user> --unixAgentGroup <group> --unixServerUser <user> --unixServerGroup <group> --unixAgentUser <user> --remoteServer <your existing Commander server>
Agent only with default options ./ElectricCommander-<version>

--mode silent --installAgent --unixAgentUser <user> --unixAgentGroup <group>
Web Server only with default options ./ElectricCommander-<version>

--mode silent --installWeb --remoteServer <your existing Commander server> --unixServerUser <user> --unixServerGroup <group>
Tools only with default options ./ElectricCommander-<version>

--mode silent
Windows Silent Installation Examples

The following examples are command strings to use for unattended (silent) installations. The examples are shown with options, each on a separate line for viewing ease. However, you must enter all values on a single line. All components with default options ElectricCommander-<version>.exe
--mode silent --installServer --installAgent --installDatabase --installWeb --installRepository --windowsServerUser <user> --windowsServerDomain <domain> --windowsServerPassword <password> --windowsAgentUser <user> --windowsAgentDomain <domain> --windowsAgentPassword <password>
3-44
Repository Server only with default options ElectricCommander-<version>.exe

--mode silent --installRepository --installAgent --windowsAgentUser <user> --windowsAgentDomain <domain> --windowsAgentPassword <password> --windowsServerUser <user> --windowsServerDomain <domain> --windowsServerPassword <password> --remoteServer <your existing Commander server>
Agent only with default options ElectricCommander-<version>.exe

--mode silent --installAgent --windowsAgentUser <user> --windowsAgentDomain <domain> --windowsAgentPassword <password>
Web Server only with default options ElectricCommander-<version>.exe

--mode silent --installWeb --remoteServer <your existing Commander server> --windowsServerUser <user> --windowsServerDomain <domain> --windowsServerPassword <password>
Tools only with default options ElectricCommander-<version>.exe

--mode silent
3-45
Installing Agents on Non-Server-Supported Platforms

Currently, the graphical user interface installer for ElectricCommander does not support installing agent platforms that are not supported Commander server platforms also. However, you can install all UNIX-supported agent platforms using the interactive command-line installer or the silent install methods until these other UNIX platforms are part of the new installer. Use the following examples for UNIX agent installations:
UNIX Agent Command-line Installation

(Note: The following information is for non-Linux UNIX installations.) 1. 2. 3. 4. Obtain a copy of commander_<OStype>.bin Login as root.
Run chmod +x ./commander_<OStype>.bin to ensure the installer is executable. Run ./commander_<OStype>.bin to begin the ElectricCommander agent installation on a UNIX machine.
Note: You may install ElectricCommander agent software on a Linux, Solaris, HP-UX, or Mac OS agent machines, regardless of where the ElectricCommander server is installed (Windows or Linux machine). The following is an example (with annotations) of the information you need to install ElectricCommander agents on UNIX machines:
Checking install integrity, please wait... ElectricCommander 4.0.0 for Linux Installer Copyright 2006-2011 ElectricCloud, Inc. All rights reserved. Press CTRL-C to exit the installation at any time. Press Enter to accept default settings. log file: /tmp/commander_install_20081223_120130.log This suite installer can install several different product options. NOTE: The default is to install everything. Which products would you like to install (server, web server, agent, tools):
When you type-in the "agent" option, an agent and tools will be installed. Here are the prompts related to UNIX agent installation:
3-46
Press Enter to begin the Commander UNIX agent installation and you should see the following response:
OK, installing agent. Where would you like the software to be installed? Note: The destination should not be an NFS filesystem. If no directory is specified, by default an electricCloud directory is created in /opt. Enter destination directory (default is /opt): <directory path> Enter a pre-existing user to own installed agent files and run agent processes: Enter a pre-existing group to own installed agent files and run agent processes: Enter the agent port (default is 7800):
Accept the default port or specify a different port to eliminate any contention, depending on your existing system configuration. Press Enter after supplying your information and/or accepting ElectricCommander defaults. When the installation is complete, you will see the following message.
OK: Installation successful!
UNIX Agent Silent Installation

The UNIX installers (non-Linux) also have a command-line interface you can use to do unattended (silent) installations. The interface allows you to specify configuration options on the command line or in a config file. The Linux installer has more options than the installers for platforms that support agent and tools installations only. A few notes before you begin: Specifying the -q option causes the installer to operate in silent mode. Note: Defaults will be used unless overridden in the config file or on the command line. The -f option forces the installer to remove and replace any existing files in the destination directory. Note: This option does not uninstall the previous version, it completely removes the directory and writes a new one. For upgrades, see Chapter 3, "Upgrading ElectricCommander." The --config option can be used to specify a file containing configuration variables and values. The following command-line string uses the config file to override default values on a silent install:
commander_sun4u_SunOS.bin -q -f --config myconfig
Installing Agents on Non-Server-Supported Platforms
3-47
Silent Installation Configuration Parameters by Install Type The following examples are command strings to use for an unattended (silent) installations.
Agent install
EC_INSTALL_TYPE=agent DESTINATION_DIR="/opt" AGENT_USER_TO_RUN_AS=(user for agent files and processes) AGENT_GROUP_TO_RUN_AS=(group for agent) EC_AGENT_PORT=(agent port number)
Tools install
EC_INSTALL_TYPE=tools DESTINATION_DIR="/opt" USER_TO_RUN_AS="user" GROUP_TO_RUN_AS="group"
3-48
4
Invisible Body Tag
ElectricCommander Upgrade Process

You can upgrade ElectricCommander from any 3.5.x version and above. Note: This upgrade process does not support ElectricCommander versions prior to 3.5.x. If you wish to upgrade from ElectricCommander versions prior to 3.5, contact Electric Cloud Customer Support for assistance with upgrading the Commander server.
Before you begin the upgrade process...

The following checklist lists pre-upgrade tasks: If you are upgrading a Commander server, perform maintenance such as, but not limited to, deleting or compressing Commander log files, pruning Commander workspaces, and deleting unused Projects and/or Procedures. If you are upgrading a Commander server, backup your existing Commander data before upgrading. Commander provides a tool (ectool export) to create a complete XML backup of your database. Depending on the database you are using, you may want to use a database-specific backup tool. Note: During an upgrade, certain catastrophic events (like a power failure) may leave the database in an unusable state. For this reason, it is extremely important that you backup your database before proceeding with the upgrade. Backup the Plugins Directory. The default location is the plugins subdirectory within the data directory. Backup files containing your configuration and custom settings to ensure all important settings are preserved. Specifically, within the data directory, backup: Commander server and agent configuration files in the conf subdirectory Apache web server configuration files in the apache/conf subdirectory The local MySQL database configuration file, my.ini, in the mysql subdirectory
If any changes were made to the custom editor or preflight driver script properties (installed by default), you need to backup those files. These properties are stored in the server-level property sheet, which can be viewed in the web UI by accessing the Administration tab/ Server subtab. Custom editors are stored in the nested sheet named ec_customEditors. Preflight driver scripts are stored in the nested sheet named ec_preflight. The upgrade process overwrites default custom editor and preflight driver scripts with current versions. Electric Cloud recommends backing up any custom properties you created by renaming the property. For example, change ec_preflight/clientDrivers/perforce to ec_preflight/clientDrivers/perforce_modified. Backup any other files where you have created custom configurations, specified other custom information, or created any type of modification. The number of Commander files you may have modified is too numerous to list, so you might want to backup the entire Commander data directory and any other miscellaneous files you are unsure whether or not you have changed. For more information about backing up your Commander server, see Chapter 7, Backing up Your Commander Server
4-1
Important MySQL Upgrade Note

If you are upgrading a MySQL database, it may take several hours if you have a significant dataset. DO NOT INTERRUPT THE UPGRADE PROCESSif you do, you can corrupt your database, which means you will need to do a restore from a previous database backup. As an alternative, you can view Upgrade Process status by using "ectool" from a command line: ectool getServerStatus
Performing a Clean Installation

If ElectricCommander v3.5 or later is currently installed on your machine, the installer provides an option to upgrade the existing installation or perform a clean installation, which will overwrite your current installation. Note: If your current Commander installation is a version prior to 3.5, contact Electric Cloud Customer Support for manual instructions to upgrade your installation. A clean installation ignores the current installation and begins the normal installation process described in Chapter 3, Installing ElectricCommander. Current services remain running until you click Next on the Ready to Install screen, so ports and directories being used by the existing installation are not usable by the new installation. If you would like to use the same ports, manually stop the existing services to free the ports. After you click Next on the Ready to Install screen to begin the installation process, existing services are stopped and deleted, the original installation is unregistered, and the new Commander version is installed. Note: Files from your previous Commander version will not be removed or modified and will remain in their original directories.
Upgrading to Commander 4.0 and the artifact repository server

If upgrading from 3.x to 4.0, using the installers GUI or interactive console options, you will be prompted whether or not to add a repository server to your installation. "Silent" installs will not install a repository server on upgrade from 3.x to 4.0.
User Interface Upgrade Method

You will be running the installer, ElectricCommander-<version> [GUI interface], which collects the Commander service account credentials, uninstalls your current release, installs the latest Commander release, configures the system with all property values mined, and restores custom files and data. An install/upgrade log file named installer.log is created in the logs subdirectory in the data directory. After backing up your existing ElectricCommander server, create a folder where you can download the ElectricCommander-<version> installation file. Note: If your current Commander installation is a version prior to 3.5, contact Electric Cloud Customer Support for manual instructions to upgrade your installation.
4-2
Double-click the ElectricCommander-<version> file to begin installationyou will see the "Welcome to the ElectricCommander <version> Install Wizard" screen.
Click Next to upgrade the existing installation. The next two screens are a variation of the same screen. If you are installing a repository server on a machine that has an agent and/or a web server, you are prompt ed to supply all options and the following screen is the one you will see.
Install Repository Server - Check this box if you want to add a repository server to your current installation. Repository Server Port - The port for the repository server to run on. Defaults to 8200. Create repository on Commander server - Check this box to create a repository object on the remote Commander server for the repository server you are installing. Repository Name - Supply the name you would like to use for this repository object.
4-3
Commander Server Host Name - Type-in the name of the ElectricCommander server that will communicate with this repository server. If the server is using a non-default HTTP port, you must specify the Server Host Name as host:port. Commander User Name - Specify the name of a user on the Commander server who has sufficient privileges to create a repository object. Defaults to the Commander-supplied admin user. Password - Specify the password for the Commander user. The default password for the admin user is changeme.
Click Next after filling-in the fields.
If you are installing a repository server on a machine that already has a Commander server installed, the following screen is the one you will see. You are not allowed to create a repository object or specify a user name and password because those actions occur automatically on the local server.
Fill-in the available fields (described above). Click Next to continue.
4-4
If you choose to perform a clean install, see the section, Performing a Clean Installation, above.
Review the upgrade settings. Click Next to continue.
Please wait while your old Commander version is uninstalled. Depending on the installation type and your amount of data, this process may take ten or more minutes.
4-5
Please wait while ElectricCommander is installing all componentsthis process may take fifteen minutes or more depending on the installation type.
the login screen now. (This checkbox appears only when a Commander web server is being upgraded.) Click Finish to complete the upgrade.
If a Commander server is being upgraded, when the installation is complete the server will continue to upgrade the database. You will not be able to log in to the Commander server until the database upgrade is complete. You can view the upgrade status by using "ectool" from a command line: ectool getServerStatus
4-6
After clicking Finish, you may see a web page similar to the following screen if the upgrade is still in progress.
4-7
Interactive Command-line Upgrade Method

A Windows command-line upgrade is not supported. You can use the interactive command-line upgrade method for Linux-only installs. If you have X installed, running the installer will bring up the graphical user interface automatically. However, you can use the command-line upgrade method if you specify:
./ElectricCommander-<version> --mode console.
Note: You may upgrade ElectricCommander agent software on Linux with this method. For Solaris, HP-UX, Mac, or other supported UNIX agent machines, see Upgrading Agents on Non-Server-Supported Platforms on page 4-8. The following example illustrates a Linux command-line upgrade:
./ElectricCommander-<version> Copyright (c) 2006-2011, Electric Cloud, Inc. All rights reserved. This will install ElectricCommander on your computer. Continue? [n/Y] y Upgrade the existing 3.6.0.30596 installation to version <version>? [n/Y] y Install a Commander repository server? [n/Y] y Specify the repository server port. [8200] Installing agent... Installing server... Copied log file to "/opt/electriccloud/electriccommander/logs" ElectricCommander <version> was successfully installed! Installer log file: /opt/electriccloud/electriccommander/logs/installer.log.
If you would prefer to perform a clean install, answer n to the above prompt for upgrading the existing installation and then specify arguments described in Chapter 3, Interactive Command-line Installation Method on page 3-37. For more information about a clean install, see the section, Performing a Clean Installation, on page 4-2.
Silent Unattended Upgrade Method

You can run the ElectricCommander upgrade in unattended (silent) mode with no user interface for either Windows or Linux. From a command line, invoke the following command to begin a silent upgrade:
./ElectricCommander-<version> --mode silent
If you would prefer to perform a clean install, you need to include the --overwrite option in your command and specify arguments described in Chapter 3, Silent Unattended Installation Method on page 3-42. For more information about a clean install, see the section, Performing a Clean Installation, on page 4-2.
Upgrading Agents on Non-Server-Supported Platforms

Note: The information in this section is specifically for non-Linux UNIX agents. Currently, the graphical user interface installer for ElectricCommander does not support upgrading agent platforms that are not supported Commander server platforms also. However, you can upgrade all UNIX-supported agent platforms using the interactive command-line installer or the silent install methods until these other UNIX platforms are part of the new installer. To upgrade a UNIX agent, you must uninstall and re-install the agent software. For uninstall instructions, see Chapter 6, Uninstalling ElectricCommander. For installation instructions, see Chapter 3, Installing Agents on Non-Server-Supported Platforms on page 3-46.
4-8
5
Default MySQL Database Security

During ElectricCommander server installation, if you elected to install the default MySQL database, this database is configured with a database user named commander and with a password, commander. In addition, the MySQL database has an admin user named root with a default password commander. For security, you may choose to change these passwords. To change the MySQL root or commander users password, run the following command:
INSTALL_DIRECTORY/mysql/bin/mysqladmin --defaults-file DATA_DIRECTORY/mysql/my.ini u <user-name> p<current-password> password <new-password>
Replace INSTALL_DIRECTORY and DATA_DIRECTORY with the install and data directories chosen at install time.
External Database Configuration

During ElectricCommander server installation, if you elected not to install the default MySQL database, you need to configure ElectricCommander to recognize your alternate database choice. Currently, you can choose from: Your existing MySQL database if it is MySQL 5.0, 5.1, and 5.5.12 MS SQL Server 2005 with Service Pack 2 and higher, or MS SQL Server 2008, 3008 R2 Oracle 10g R2 (including RAC) Oracle 11g Release 2, R2
Note: Any database you choose to use must be UTF-8 compliant. When the database first starts up, ElectricCommander creates a schema in that database so the database user should be the owner of the ElectricCommander database, allowing it to make such changes. Your database administrator (DBA) must create a database user and database for use specifically by ElectricCommander that includes schema objects like tables, indices, and constraints, all with modify and delete capabilities. Database user The ElectricCommander server interacts with the database using a JDBC driver for each of the databases Commander supports. The first step in any interaction is to present user credentials to the database. This information is stored in the Commander database.properties file as a user name plus a password. The password is stored as an encrypted string, using the passkey generated by the server. Database user privileges The database user that Commander uses must have rights to add or delete rows from the database at all times. At certain defined times, the database user must have rights to create or delete tables, and add or remove a column/indices/constraints to a table. Supported configurations To prevent problems during upgrades and compatibility with future versions, Electric Cloud supports installations only where the database user has rights to create and delete tables at all times. The database must be configured to allow up to 200 open connections.
5-1
MS SQL Server-specific information SQL Server supports two types of user authentication: SQL Server Authentication and Windows Authentication. Because the authentication type influences how information is provided in setDatabaseConfiguration, you need to find out from your DBA which authentication type is required for the user provided. TIP: This information may be particularly important if you are using SQL Server 2005. For SQL Server Authentication, specify the --userName and --password options to
setDatabaseConfiguration.
For Windows Authentication, there are two options: NTLM login - The user name must include the domain name, for example, user@domain.com or domain\user. SSO (single sign on) login - The commander service must be run as the domain user, and the user name must be set to blank (for example, --userName ""). Do not specify a password if using SSO; the server will forward credentials from the service itself. After changing the ElectricCommander database configuration, the server attempts to connect to the database to do the initial schema setup. While the server is attempting to connect and do the initial schema setup, you can use ectool getServerStatus to see if there are problems logging into the database or creating the schema. This command shows log messages from the server bootstrap process. Note: Before the server is completely up, getServerStatus does not require a login session, but after the server is up, it does. Thus, if you issue a getServerStatus call and get a session expired error, the server is up.
Configuring Commander to Use an Alternate Database

If you deselected the database checkbox during installation, you will NOT be able to log in to ElectricCommander until you set up a database configuration pointing to an external database. Use one of the following two methods: Using the web interface Using ectool
Using the Web Interface to Set the Database Configuration
1. 2. 3. 4.
Fill-in your Database Name. Select your Database Type from the drop-down menu. Fill-in the Host Name for your database server. Accept the default Port or supply the port number you need for your database.
5-2
5. 6. 7.
Supply the database User Name the Commander server will use to access your database. Fill-in and confirm the Password for the database user you specified. Click OK after supplying information in all fields.
Note: You may need to consult with your Database Administrator if you do not have all of the information required on this web page. To access the Database Configuration web page at a later time to make modifications or change to the default ElectricCommander database, click the Administration > Database Configuration tabs.
Using ectool to Set the Database Configuration

If you prefer to use the ElectricCommander command-line tool, use the ectool command, setDatabaseConfiguration to change the database configuration. The usage is:
setDatabaseConfiguration
[--databaseType <mysql|sqlserver|Oracle>] [--databaseName <database name>] [--hostName <host name>] [--ignorePasskeyMismatch <Boolean flag>] [--ignoreServerMismatch <Boolean flag>] [--password <password>] [--port <port number>] [--preserveSessions <Boolean flag>] [--userName <user name>] [--customDatabaseDialect <custom database dialect>] [--customDatabaseDriver <custom database driver>] [--customDatabaseUrl <custom database URL>] For example:
ectool setDatabaseConfiguration --databaseType sqlserver --databaseName commander --hostName localhost --port 1433 --userName commander --password commander
The options are:

Option databaseType Description
Selects the database typesupported options are mysql| sqlserver|Oracle The name of your alternate databasethis is not the host name, but the name the DBA gave the database object The host name where your database is running <Boolean flag - 0|1|true|false> - If the server is started with a different passkey, ignore the mismatch if true. Note: This action discards all saved passwords. <Boolean flag - 0|1|true|false> - If the server is started on a different host than where the server previously started, ignore the mismatch if true. The port number used by the database Serverif omitted, port 1433 is used
databaseName
hostName ignorePasskeyMismatch
ignoreServerMismatch
port
Configuring Commander to Use an Alternate Database
5-3
Option preserveSessions
Description
<Boolean flag - 0|1|true|false> - If ignoring a server mismatch, default behavior invalidates all sessions. Setting this flag to true preserves all sessions, allowing the server to reconnect to running jobs. This option is used in combination with ignoreServerMismatch. The user name to use when connecting to the databaseFor MS SQL Server, see the information on the next page regarding support for SQL Server Authentication and Windows Authentication The password to use to connect to the databaseFor MS SQL Server, see the information on the next page regarding support for SQL Server Authentication and Windows Authentication Internal option - use only at the request of Electric Cloud support Internal option - use only at the request of Electric Cloud support Internal option - use only at the request of Electric Cloud support
userName
password
customDatabaseDialect customDatabaseDriver customDatabaseUrl
Switching to an Alternate Database

If you did not deselect the database checkbox during installation and you want to switch to another database now [next month or any time in the future], you can. To configure another database and migrate the existing data to the new database: 1. 2. 3. 4. Export your data by issuing the following command:
ectool export <filename> --compress 1
Set the database configuration using the web interface or ectool as described above. Restart the Commander server by issuing the following command:
ectool shutdownServer --restart 1
Import your data by issuing the following command:

ectool import <filename> --force 1
To disable the default MySQL database: On Windows: Go to Administrative Tools and select Services. Open the ElectricCommander MySQL Service properties and click Stop. Change the startup type to Manual or Disabled. As root, run the following command: /etc/init.d/commanderMySQL stop Disable the service using the default method for your Linux version.
On Linux:
Notes: 1. This process is the same whether or not you are switching from the default database or changing from one alternate database to a different alternate database. 2. If you are using two different Commander servers, they cannot point to the same database.
5-4
Logging in and Licensing

For a new installation, the default admin account user name is admin and the password is changeme. Type these values in the appropriate fields and click Login.
Applying the License Key

If you see one of the following screens, you will know the ElectricCommander license is not installed.
In the first example (above), click Import License. Open the license file in a text editor and copy and paste the license text in the box on the Import License page. See the next screen.
Logging in and Licensing
5-5
Click OK to import the Commander license.
5-6
Making the Plugins Directory Universally Accessible

The Commander server installs all plugins into a configurable location named the Plugins Directory. This directory must be readable by the web server and any agents that need access to the content of one or more plugins. There are two approaches to making plugins universally accessible: Configure the Commander server, agents, and web servers to point to a universally accessible network location Keep the plugins directory in its default server location and replicate the contents to remote agents and web servers
Configure Commander server, agents, and web servers to point to a universally accessible network location
This is the recommended approach because newly installed plugins are immediately available to all agents and web servers. Also, you avoid the overhead of managing multiple plugins directories. A network location for the plugins directory can be set up in one of two ways: 1. Move the plugins directory to a pre-configured network location, accessible by the Commander server and all remote agents and web servers. This approach is recommended if you already have a network file system accessible to the Commander server and all remote agents and web servers. Follow these steps to move the plugins directory: Create an empty directory in the network accessible location. Move the contents of the plugins subdirectory from the Commander server's data directory to this new directory. When running the following commands, replace <PLUGINS> with the Windows path to the shared directory for Windows machines, and the UNIX path to the shared directory for UNIX machines. On the Commander server, issue the following commands.
ectool setProperty /server/settings/pluginsDirectory "<PLUGINS>" ecconfigure --webPluginsDirectory "<PLUGINS>" - only run this command if a web server
was installed on this machine (by default during an Express Server install)
ecconfigure --agentPluginsDirectory "<PLUGINS>" - only run this command if an agent was
installed on this machine (by default during an Express Server install)

ectool setProperty "/server/Electric Cloud/windowsPluginsShare" "<WINDOWS_PLUGINS>" - Replace <WINDOWS_PLUGINS> with the Windows path to the shared
directory. Only run this command if you plan on installing remote Windows agents or web servers.
ectool setProperty "/server/Electric Cloud/unixPluginsShare" "<UNIX_PLUGINS>" - Replace <UNIX_PLUGINS> with the UNIX path to the shared directory. Only
run this command if you plan on installing remote UNIX agents or web servers. When installing remote agents or web servers, you will be prompted to enter information about the Commander server. Select the checkbox to "discover the plugins directory", and the correct location is automatically picked up from the server and set during installation. On remote agents that were already installed, run the following command:
ecconfigure --agentPluginsDirectory "<PLUGINS>"
2.
On remote web servers that were already installed, run the following command:
ecconfigure --webPluginsDirectory "<PLUGINS>"
Leave the plugins in the current location on the Commander server and share that location across the network so remote agents and web servers can obtain access. This approach is recommended only if you do not already have a network location available to the Commander server and all remote agents and web servers. If you do have a universally available network location, moving the plugins directory to this network location as described above is advisable. If your Commander server is a Windows machine, the plugins directory is automatically shared by the name "commander-plugins" during installation. When you install remote agents and web servers on Windows, they will discover this location and be configured to use it. However, if you are installing remote agents or web servers on UNIX machines, follow these steps: Create a Samba mount on a UNIX machine pointing to the plugins share on the Windows machine, //<COMMANDER_SERVER_HOST_NAME>/commander-plugins
Making the Plugins Directory Universally Accessible
5-7
On this same machine, export the Samba mount as a network file system share: * Add the following entry to /etc/exports (replace <EXPORT> with the directory you want to export, /opt/electriccloud/electriccommander/plugins by default): <EXPORT> *(ro,sync) * Start/restart the NFS server Prior to installation on UNIX remote agents and web servers, mount the network file system share to an available directory. Make sure to mount the share to the same directory across all machines, henceforth referred to as <UNIX_PLUGINS>: * Create <UNIX_PLUGINS> * Add the following entry to /etc/fstab (replace <HOST> with the host name of the machine on which the directory has been exported and <EXPORT> with the directory being exported on that machine):
<HOST>:<EXPORT> <UNIX_PLUGINS> nfs defaults 0 0 * Call: mount -a
On the Commander server machine, run the following command:

ectool setProperty "/server/Electric Cloud/unixPluginsShare" "<UNIX_PLUGINS>"
If your Commander server is a Linux machine, the plugins directory is not automatically shared as on Windows. If you are installing remote agents or web servers on other UNIX machines, follow these steps: On the Commander server machine, export the local plugins directory as a network file system share: * Add the following entry to /etc/exports (replace <EXPORT> with the directory you want to export, /opt/electriccloud/electriccommander/plugins by default): <EXPORT> *(ro,sync) * Start/restart the NFS server Prior to installation on UNIX remote agents and web servers, mount the network file system share to an available directory. Make sure to mount the share to the same directory across all machines, henceforth referred to as <UNIX_PLUGINS>: * Create <UNIX_PLUGINS> * Add the following entry to /etc/fstab (replace <HOST> with the host name of the machine on which the directory has been exported and <EXPORT> with the directory being exported on that machine):
<HOST>:<EXPORT> <UNIX_PLUGINS> nfs defaults 0 0 * Call: mount -a
On the Commander server machine, run the following command:

ectool setProperty "/server/Electric Cloud/unixPluginsShare" "<UNIX_PLUGINS>"
If you are installing remote agents or web servers on Windows machines, create a Samba share on the Commander server that's accessible to Windows machines under the name <WINDOWS_PLUGINS>. Then, run the following command:
ectool setProperty "/server/Electric Cloud/windowsPluginsShare" "<WINDOWS_PLUGINS>"
When installing remote agents or web servers, you are prompted to enter information about the Commander server. Select the checkbox to "discover the plugins directory", and the correct location is automatically picked up from the server and set during installation. On remote agents that were already installed, run the following command: ecconfigure --agentPluginsDirectory "<PLUGINS>", replacing <PLUGINS> with the Windows path to the shared directory for Windows machines, and the UNIX path to the shared directory for UNIX machines. On remote web servers that were already installed, run the following command: ecconfigure --webPluginsDirectory "<PLUGINS>", replacing <PLUGINS> with the Windows path to the shared directory for Windows machines, and the UNIX path to the shared directory for UNIX machines.
Keep the plugins directory in its default server location and replicate the contents to remote agents and web servers
This approach is recommended only if you cannot use or configure a network accessible location. The plugins directory can be copied to remote agents and web servers using any file copy mechanism. These copied plugins directories need to be readable by the remote agents and web servers only. Plugins should be copied to a plugins subdirectory within the data directory for each remote agent and web server.
5-8
Every time a new plugin is installed, the server's plugins directory will be updated, and you will need to synchronize the changes across all remote copies.
If you have a proxy server in your environment...

If your Commander server, web server, or repository server is deployed behind a proxy server, which inhibits certain internet access, you need to use ecconfigure to set proxy settings for each server in your installation. To use the following perl scripts, remove the brackets (< >), and replace the bracketed example text with the values you need. To set Commander Server proxy settings:
ec-perl ecconfigure.pl --serverProxyHost <IP_ADDRESS_PROXY> --serverProxyPort <PORT> --serverNoProxyHosts "<HOST1,HOST2>"
To set Repository Server proxy settings:

ec-perl ecconfigure.pl --repositoryProxyHost <IP_ADDRESS_PROXY> --repositoryProxyPort <PORT> --repositoryNoProxyHosts "<HOST1,HOST2>"
To set Web Server proxy settings:

ec-perl ecconfigure.pl --webProxyUrl <http://IP_ADDRESS:PORT> --webNoProxyHosts <HOST1,HOST2,HOST3>
Troubleshooting
To test the proxy settings: For Web Server proxy settings: Go to the Plugin Manager web page and verify the catalog can be viewed and no errors are reported when accessing the catalog URL. For Commander Server proxy settings: Go to the Plugin Manager web page and install a plugin from the catalog.
Note: For proxy settings to work, you must restart all servers where you have applied a proxy setting.
Web Interface Online Help System

Open the ElectricCommander online help system for more information. Click the Help link in the top-right corner of any product web page to see a help topic for that page. When the help system opens, Electric Cloud recommends reviewing the Help table of contents. All Help folders above the Web Interface Help folder are user-guide style help topics that provide more detailed information on each of their subjects. If you generally prefer to use a command-line tool rather than the Commander web interface, you will find complete ectool (the Commander command-line tool) and API (perl script) commands and options within the online help system too.
If you have a proxy server in your environment...
5-9
5-10
6
Use these instructions to uninstall ElectricCommander. Do not use these instructions prior to upgrading to a new ElectricCommander version. To upgrade, see Chapter 4, "Upgrading ElectricCommander" on page 4-1.
Windows Uninstall
To completely uninstall ElectricCommander from a server, web server, agent, or developer machine: If you are using Windows XP or 2003, go to the Control Panel, double-click Add or Remove Programs, find and select ElectricCommander and click Remove. If you are using Windows 2008, or 7, go to the Control Panel and under Programs and Features, select ElectricCommander and click Uninstall.
UNIX Uninstall
To completely uninstall ElectricCommander from a server, web server, agent, or developer machine: Log in as root. For Linux, run the command
/opt/electriccloud/electriccommander/uninstall
For other UNIX platforms, run the command

/opt/electriccloud/electriccommander/uninstaller/uninstall
6-1
6-2
7
Backing up Your Commander Server

Note: During an upgrade, certain catastrophic events (like a power failure) may leave the database in an unusable state. For this reason, it is extremely important that you backup your database before proceeding with an upgrade.
Recommendations
Database dumps are much quicker than full XML exports. While it may not be feasible to run a full XML export on a regular basis (for example, nightly), it is much faster to export all data except jobs by using the --excludeJobs option. Use Commander to perform backups by creating a procedure that runs the export or database dump command.
Prerequisites
Make sure you have plenty of free space available because full database dumps and XML export files can be extremely large. Compress database dumps if they are not compressed by default. Pruning job workspaces Deleting or compressing Commander log files Deleting unused projects and/or procedures Regularly perform maintenance such as, but not limited to:
Backup steps
Backup your existing Commander data frequently. Electric Cloud recommends full regular (nightly) database backups. Depending on the database you are using, you may want to use a database-specific backup tool. Commander also provides a tool (ectool export) to create a complete XML database backup. Two ways to backup your data: Use a database-specific backup tool to create a database dump. Database backup performance is the most reasonable. Database backup (in the case of MySQL for example) must be performed while the database is live, up and running. Note: The Commander server should be shut down when you take a database dump. The database restore operation is fast from a database backup. Note: A database backup can only be restored to the same type of database. If you are planning to switch your database type when you restore from the backup, you must create an XML backup. See the section, MySQL database commands on page 7-6 if you are using a MySQL database. Use ectool export to create a complete XML database backup. Must be used while the Commander server is running.
7-1
This process may take considerably longer than simply backing up the database, but this method is necessary in the following situations: If backing up the database is not an available option. Migrating from one database to another, for example: MySQL to Oracle or SQL Server. If you want a full export in a text form you can search with an editor. The ectool export command is fully documented in the Commander online help system. See the Using ectool and the Commander API help topic. Preserve the passkey file located in the server/conf subdirectory within your data directory. When you restore your server, this passkey must be in place so Commander can decrypt passwords for user impersonation, LDAP, and the database connection. Backup the plugins directory. The plugins directory is stored in a server setting property (/server/settings/pluginsDirectory). If the property does not exist, the server uses the default location, which is the plugins subdirectory in the data directory. The default location for Commander server and agent configuration files is the conf subdirectory in the data directory. The default location for the Apache web server configuration files is the apache/conf subdirectory in the data directory. The default location for the local MySQL database configuration file, my.ini, is the mysql subdirectory in the data directory. Database dump and/or XML export The passkey file The contents of the plugins directory Configuration files
Backup the files containing your custom configurations and settings to ensure all important settings are preserved.
Your backup should contain the following items:
Restoring Your Commander Server

Note: All ectool commands used in the following scenarios are fully documented in the Commander online help system. See the Using ectool and the Commander API help topic.
Prerequisites
You must have a backup of your source Commander server (see the preceding Backing up Your Commander Server section). If you are restoring your data to the exact same database or the same database type (for example, from one MySQL database to another MySQL database on a different system), a database backup is sufficient. If you are switching to a different database type, you will need an XML export.
Any activity on the source server after the backup was created will not exist on the destination server. The destination system must have a Commander server already installed and running, and this server must be running the same version or newer version than the source server.
Scenario 1: Restore a backup to the same Commander server and database Use case Restoring your server for a backup because of a catastrophic failure or an unsuccessful upgrade. Steps Make sure you have a backup of the source system. Stop the destination Commander server. For more information, see Manual Server/Agent Stop and Start on page 7-9 for platform-specific commands.
7-2
If you are using a database backup (the source and destination systems must both be using the same type of database), load the database dump into the destination database. This will be done with a command specific to the database you are using. For more information, see MySQL database commands on page 7-6 if you are using a MySQL database.
Start the destination Commander server. If you are using an XML export file, import the data into the destination Commander server, using the
ectool import command.
Restart the destination server by running the following command: ectool shutdownServer --restart 1.
Scenario 2: Keep the same Commander server but switch the database Use cases Switch from the local MySQL installation to an external database. Upgrading to a higher performance system for the database. Steps Make sure you have a backup of the source system. Stop the destination Commander server. For more information, see Manual Server/Agent Stop and Start on page 7-9 for platform-specific commands. Stop and disable the original database. If you are using a database backup (the source and destination systems must both be using the same type of database), load the database dump into the destination database. This is accomplished with a command specific to the database you are using. For more information, see MySQL database commands on page 7-6 if you are using a MySQL database.
Start the destination Commander server. Set the server database configuration to point to the new database. Point to the new database by using the "Database Configuration" help topic in the Commander web interface, or by using ectool setDatabaseConfiguration.
If you are using an XML export file, import the data into the destination Commander server, using the
Restart the destination server by running the following command: ectool shutdownServer --restart 1.
Scenario 3: Switch the Commander server but keep the same database Use case Upgrading to a higher performance system for the Commander server. Steps Make sure you have a backup of the source system. Stop the destination Commander server. For more information, see Manual Server/Agent Stop and Start on page 7-9 for platform-specific commands. Stop and disable the source Commander server. Copy the passkey file from the backup to the destination system (in the server/conf subdirectory in the data directory). Copy the backed-up plugins to the destination system. There are 4 scenarios you may encounter here: If the /server/settings/pluginsDirectory property does not exist, the server will use the default location (the plugins subdirectory in the data directory). Copy the backed-up plugins to that directory on the destination system. The plugins are stored in a local directory valid on both systems. Copy the backed-up plugins to the same directory on the destination system. The plugins are stored in a shared directory valid on both systems. Nothing needs to be done in this case.
7-3
The plugins are stored in a directory not accessible on the destination system.
This can happen if the source and destination systems have different operating systems (Windows to Linux or vice-versa). It may happen if the plugins directory on the source system is on a drive that does not exist on the destination system. Copy the backed-up plugins to a new directory accessible to the destination system. When the server starts, you will need to set the /server/settings/pluginsDirectory property to the new directory and restart the Commander server. Start the destination Commander server. Because we have replaced the passkey, the database password is no longer valid. You need to reset the database password (default: commander) and ignore the passkey mismatch either from the command-line or the web interface. On the command-line, use ectool setDatabaseConfiguration to specify the password and set the --ignoreServerMismatch and --ignorePasskeyMismatch options. In the web interface, you should automatically be redirected to the Database Configuration page. Enter the database password and select the "ignore invalid passkey" checkbox.
Restart the destination server by running the following command: ectool shutdownServer --restart 1. If you copied the plugins directory to a directory that does not match the plugins directory on the source system, you will need to set the /server/settings/pluginsDirectory property to this new directory and restart the Commander server. You can use ectool setProperty to set this value.
Scenario 4: Switch both the Commander server and the database Use case Upgrading to higher performance systems for both the Commander server and the database. Steps Make sure you have a backup of the source system. Stop the destination Commander server. For more information, see Manual Server/Agent Stop and Start on page 7-9 for platform-specific commands. Stop and disable the source Commander server. Stop and disable the original database. Copy the passkey file from the backup to the destination system (in the server/conf subdirectory in the data directory). Copy the backed-up plugins to the destination system. There are 4 scenarios you may encounter here: If the /server/settings/pluginsDirectory property does not exist, the server will use the default location (the plugins subdirectory in the data directory). Copy the backed-up plugins to that directory on the destination system. The plugins are stored in a local directory valid on both systems. Copy the backed-up plugins to the same directory on the destination system. The plugins are stored in a shared directory valid on both systems. Nothing needs to be done in this case. The plugins are stored in a directory not accessible on the destination system.
This can happen if the source and destination systems have different operating systems (Windows to Linux or vice-versa). It may happen if the plugins directory on the source system is on a drive that does not exist on the destination system. Copy the backed-up plugins to a new directory accessible to the destination system. When the server starts, you will need to set the /server/settings/pluginsDirectory property to the new directory and restart the Commander server. If you are using a database backup (the source and destination systems must both be using the same type of database), load the database dump into the destination database.
7-4
This operation is completed with a command specific to the database you are using. For more information, see MySQL database commands on page 7-6 if you are using a MySQL database.
Start the destination Commander server. Because we have replaced the passkey, the database password is no longer valid. You need to reset the database password (default: commander) and ignore the passkey mismatch either from the command-line or the web interface. On the command-line, use ectool setDatabaseConfiguration to specify the password and set the --ignoreServerMismatch and --ignorePasskeyMismatch options. In the web interface, you should automatically be redirected to the Database Configuration page. Enter the database password and select the "ignore invalid passkey" checkbox.
If you are using an XML export file, import the data into the destination Commander server, using the
Restart the destination server by running the following command: ectool shutdownServer --restart 1. If you copied the plugins directory to a directory that does not match the plugins directory on the source system, you will need to set the /server/settings/pluginsDirectory property to this new directory and restart the Commander server. You can use ectool setProperty to set this value.
Scenario 5: Create a clone of the Commander server and the database Use cases Setting up a production-like environment for testing. Maintaining a cluster to fall back to in case the production system goes down. Steps Make sure you have a backup of the source system. Stop the destination Commander server. For more information, see Manual Server/Agent Stop and Start on page 7-9 for platform-specific commands. Copy the passkey file from the backup to the destination system (in the server/conf subdirectory in the data directory). Copy the backed-up plugins to the destination system. There are 4 scenarios you may encounter here: If the /server/settings/pluginsDirectory property does not exist, the server will use the default location (the plugins subdirectory in the data directory). Copy the backed-up plugins to that directory on the destination system. The plugins are stored in a local directory valid on both systems. Copy the backed-up plugins to the same directory on the destination system. The plugins are stored in a shared directory valid on both systems. Both servers must point to different plugin directories. Copy the backed-up plugins to a new directory accessible to the destination system. When the server starts up, you will need to set the /server/settings/pluginsDirectory property to this new directory and restart the Commander server. The plugins are stored in a directory not accessible on the destination system.
This can happen if the source and destination systems have different operating systems (Windows to Linux or vice-versa). It may happen if the plugins directory on the source system is on a drive that does not exist on the destination system. Copy the backed-up plugins to a new directory accessible to the destination system. When the server starts, you will need to set the /server/settings/pluginsDirectory property to the new directory and restart the Commander server. If you are using a database backup (the source and destination systems must both be using the same type of database), load the database dump into the destination database. This operation is completed with a command specific to the database you are using. For more information, see MySQL database commands on page 7-6 if you are using a MySQL database.
If you are using a database backup, you need to disable schedules and/or resources so both servers do not run jobs on the same set of agents.
7-5
Two servers should never talk to the same agent because this will cause incorrect results and timeouts. Disabling schedules prevents jobs from launching unexpectedly. Disabling resources prevents scheduled or manually launched jobs from running on the same agents as the source server. This operation is completed with a command specific to the database you are using. For more information, see MySQL database commands on page 7-6 if you are using a MySQL database.
Start the destination Commander server. Because we have replaced the passkey, the database password is no longer valid. You need to reset the database password (default: commander) and ignore the passkey mismatch either from the command-line or the web interface. On the command-line, use ectool setDatabaseConfiguration to specify the password and set the --ignoreServerMismatch and --ignorePasskeyMismatch options. In the web interface, you should automatically be redirected to the Database Configuration page. Enter the database password and select the "ignore invalid passkey" checkbox.
If you are using an XML export file, you will need to disable schedules and/or resources so both servers do not run jobs on the same set of agents. Two servers should never talk to the same agent because this will cause incorrect results and timeouts. Disabling schedules prevents jobs from being launched unexpectedly. Disabling resources prevents scheduled or manually launched jobs from running on the same agents as the source server. Modify the import file by replacing <resourceDisabled>0</resourceDisabled> with <resourceDisabled>1</resourceDisabled>. Use the ectool import command with the --disableSchedules flag turned on to disable schedules.
Restart the destination server by running the following command: ectool shutdownServer --restart 1. If you copied the plugins directory to a directory that does not match the plugins directory from the source system, you will need to set the /server/settings/pluginsDirectory property to the new directory and restart the Commander server. You can use ectool setProperty to set this value.
MySQL database commands

Use the following commands to create and restore database dumps if you are using the local MySQL installation provided with ElectricCommander. If you are using your own version of MySQL, the commands should still work, although you may need to make modifications. Notes On Linux, your LD_LIBRARY_PATH must be setup correctly to run the command-line tools. In this case, source the bash.profile or csh.profile script located in the install directory (for example, /opt.electriccloud/electriccommander/bash.profile). The commands use the default user name, password, and database name (all commander), as well as the default data directory on a Linux system. If you have used any non-default values, you will need to update the command accordingly.
Creating a database dump Call mysqldump (located in the mysql/bin subdirectory in the install directory) with the following arguments: On Linux:
--single-transaction --user=commander --password=commander --result=commanderBackup.sql --socket=/opt/electriccloud/ electriccommander/mysql/mysql.sock commander
On Windows:
--single-transaction --user=commander --password=commander --result=commanderBackup.sql commander
7-6
Restoring a database dump Call mysql (located in the mysql/bin subdirectory of the install directory) with the following arguments: On Linux:
--user=commander --password=commander --socket=/opt/electriccloud/electriccommander/mysql/mysql.sock commander < commanderBackup.sql
On Windows:
--user=commander --password=commander commander < commanderBackup.sql
Modifying the data to disable schedules and resources Call mysql (located in the mysql/bin subdirectory in the install directory) with the following arguments: On Linux:
--user=commander --password=commander --socket=/opt/electriccloud/electriccommander/mysql/mysql.sock
On Windows:
--user=commander --password=commander
Run the following commands:

use commander; update ec_schedule set disabled = 1; update ec_resource set disabled = 1;
Backing up and restoring your repository backingstores

The Commander repository backingstores contain published artifacts and thus require a backup strategy. The location of a repository backingstore can be found in that repository's installation: See the REPOSITORY_BACKING_STORE setting in <data-dir>/conf/repository/server.properties. If this setting contains a relative path, it is interpreted as relative to <data-dir>. To backup a repository backingstore, you can use whatever backup mechanism you normally employ to back up a directory or file system. Note: Because publish operations could be active during a backup, some artifacts may be partially backed up only. To avoid backing up a partial artifact or artifact version, deactivate the repository server before the backup: To disable a repository object in the Commander server, use the Edit Repository page or the modifyRepository API. Wait for artifact versions in the "publishing" state to transition to "available". During this time, the repository will be unusable for publish and retrieve for: the time it takes for in-progress publishes to complete, and the time it takes to perform the backup.
While this strategy is easy to implement, the cost may be too high. Another possibility is to detect partial artifact versions during backup and skip these directories. If an artifact version directory contains a complete manifest file (parseable xml), it is a complete artifact version. Otherwise, it is a partial artifact version. Some backup systems skip open files during the backup operation. This feature does not skip partial artifacts because the backup of an artifact version may occur after the archive is written, but before the manifest file is written, which means it is still a partial artifact version. When restoring from a backup, disable the repository server in Commander to prevent retrieve operations from downloading partially restored artifact versions.
7-7
Apache Web Server or Agent Certificates

Description
After installation, you may want to create a new Apache web server or agent certificate. By default, ElectricCommander generates a temporary self-signed certificate during web server installation. This certificate is used whenever a browser makes an HTTPS connection to the Apache server. Because the certificate is self-signed, browsers complain it is not a trusted certificate. Most organizations want to generate a new certificate signed by a recognized certificate authority (CA) to remove browser warnings.
Generating a signed certificate for the ElectricCommander web server or agent:

Locate the appropriate certificate signing request file generated during installation: Agent - $DATA_DIR/conf/agent.csr Web Server - $DATA_DIR/apache/conf/server.csr By default, $DATA_DIR is: Linux - /opt/electriccloud/electriccommander/conf Windows 2008 or Windows 7 - C:\ProgramData\Electric Cloud\ElectricCommander\conf Windows XP or 2003 - C:\Documents and Settings\All Users\Application Data\Electric
Cloud\ElectricCommander\conf
Send the request to the CA

The server.csr (or 'agent.csr') file from 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 CA signature.
Install the signed certificate

Replace any existing certificate with the new signed certificate you received from the CA: Agent - $DATA_DIR/conf/agent.crt Web Server - $DATA_DIR/apache/conf/server.crt Restart the service(s)
Alternate: Generating a new self-signed certificate to update a hostname

Locate the ssl configuration file generated during installation: Agent - $DATA_DIR/conf/agentssl.cnf Web Server - $DATA_DIR/agent/conf/serverssl.cnf Locate the hostname configuration at the end of the file:
[ req_distinguished_name ] organizationalUnitName = ElectricCommander agent certificate commonName = <yourNewHostName> [ alt_names ] DNS.1=localhost DNS.2=<newFullyQualifiedHostName> DNS.3=<newAlternateHostName>
Update the commonName and the alternate names list to reflect the names that you will use to access your server. You can add additional names (e.g. for a certificate used with multiple servers in a load balancing scenario) by adding DNS lines with increasing index values.
7-8
Regenerate the signing request and the default self signed certificate:
ecconfigure --generateWebCert 1 --generateAgentCert 1
This command generates and installs new self-signed certificates and restarts the services. If you need to have the new certificates signed, follow the steps above using the new certificates signing request.
Alternate: Restoring the default configuration

If you are missing files or have a broken configuration, you can regenerate all of the files from scratch by deleting the agent.crt and server.crt files then running:
ecconfigure --initial 1 --webHostName <yourWebHostName>
This regenerates the ssl.cnf files, certificates, signing requests and restarts the services.
Using chkconfig
chkconfig is a simple command-line tool for maintaining the /etc/rc[0-6].d directory hierarchy. This tool relieves system administrators from the task of directly manipulating numerous symbolic links in those directories. The Linux chkconfig command can be used to manipulate Commander services running on UNIX platforms. chkconfig - updates and queries runlevel information for system services
chkconfig chkconfig chkconfig chkconfig chkconfig --list [name] --add name --del name [--level levels] name <on|off|reset> [--level levels] name
Examples
(list current settings for the local Commander database service) /sbin/chkconfig commanderMySQL --list commanderMySQLWrapper 0:off 1:off 2:off 3:on 4:off 5:on 6:off (disable autostart on reboot) /sbin/chkconfig commanderMySQL off /sbin/chkconfig commanderMySQL --list commanderMySQLWrapper 0:off 1:off 2:off 3:off 4:off 5:off 6:off
Note that for every service, each runlevel has either a "start" script or a "stop" script. When switching runlevels, init will not re-start an already-started service, and will not re-stop a service that is not running.
Manual Server/Agent Stop and Start

During administrative maintenance, including upgrades, 3rd party software installs, or system maintenance, Commander servers and agents need to be manually stopped and started.
Solution for Stop

To Stop all ElectricCommander agent services: For Windows: go to Control Panel>Administrative Tools>Services. Stop "ElectricCommander Agent" From a command line, type sc stop CommanderAgent For UNIX / MAC: using a shell, logged on as root, type: Linux - "/etc/init.d/commanderAgent stop" Solaris - "/etc/init.d/ecmdrAgent stop" HP-UX - "/sbin/init.d/ecmdrAgent stop" Macintosh - "launchctl stop /Library/LaunchDaemons/ecmdrAgent.plist"
Using chkconfig
7-9
To Stop all ElectricCommander server services: For Windows: go to Control Panel>Administrative Tools>Services

Stop "ElectricCommander Server" Stop "ElectricCommander Web Server" Stop "ElectricCommander Database" Stop "ElectricCommander Repository Server"
sc stop CommanderServer sc stop CommanderApache sc stop CommanderMySQL sc stop CommanderRepository /etc/init.d/commanderServer stop /etc/init.d/commanderApache stop /etc/init.d/commanderMySQL stop /etc/init.d/commanderRepository stop
From a command line, type:
For Linux: using a shell, logged in as root, type:

Solution for Start

To Start all ElectricCommander agent services: For Windows: go to Control Panel>Administrative Tools>Services. Start "ElectricCommander Agent" From a command line, type sc start CommanderAgent For UNIX / MAC: using a shell, logged on as root, type: Linux - "/etc/init.d/commanderAgent start" Solaris - "/etc/init.d/ecmdrAgent start" HP-UX - "/sbin/init.d/ecmdrAgent start" Macintosh - "launchctl start /Library/LaunchDaemons/ecmdrAgent.plist"
Start all ElectricCommander server services: For Windows: go to Control Panel>Administrative Tools>Services

Start "ElectricCommander Database" Start "ElectricCommander Server" Start "ElectricCommander Web Server" Start "ElectricCommander Repository Server"
sc start CommanderMySQL sc start CommanderServer sc start CommanderApache sc start CommanderRepository
From a command line, type:
For Linux: using a shell, logged on as root, type:

/etc/init.d/commanderMySQL start /etc/init.d/commanderServer start /etc/init.d/commanderApache start /etc/init.d/commanderRepository start
7-10
8
Troubleshooting
This chapter contains issues not previously presented or discussed in this guide. All issues do not pertain to the Commander installation processsome are more general in nature. Should you encounter one of these issues, you will find a solution here too. More troubleshooting information can be found in Commander Knowledge Base articles located at
https://electriccloud.zendesk.com/forums/
If the Commander server is unresponsive and displays an OutOfMemory error If the Commander server becomes unresponsive and displays an OutOfMemory error complaining that the server was out of PermGen space, it means the server is not configured properly for a 64-bit JVM.
Workaround:
Change a setting in wrapper.conf. Electric Cloud recommends setting the Java MaxPermSize to a number greater than the default (which is 84m) on 64-bit commander server (java) installation. The file to edit on Linux is:
/opt/electriccloud/electriccommander/conf/wrapper.conf
The file to edit on Windows is:

<ElectricCommander data dir>/conf/wrapper.conf
On Windows 2003 or XP, the data-dir is typically:

C:\Documents and Settings\All Users\Application Data\Electric Cloud\ElectricCommander
On Windows 7 or 2008, the data-dir is typically:

C:\ProgramData\Electric Cloud\ElectricCommander
Add the following line to the end of the existing "wrapper.java.additional" section, being careful to use the next consecutive number (in this example, we had 7 as the last pre-existing sequence number in this section).
wrapper.java.additional.8=-XX:MaxPermSize=128m
After the file has been edited, restart the server to utilize the new value: On Linux: /etc/init.d/commanderServer restart On Windows: use "Services" Installing Commander on a virtual machine (VM) For a local Commander Server and database installation: The Windows installers for Commander 3.6.x, 3.7.x, and 3.8.x may be problematic if attempting to install on a virtual machine (VM), particularly if the VM Manager already has a high disk or CPU load. One symptom of this problem is the error message, "Failed to start service CommanderMySQL".
Workaround:
Try to improve the performance of the VM environment, then delete the folders where the install was attempted. Run the installer again and the results should be better. Note: You may experience performance issues if running both the Commander server and database on a VM.
Troubleshooting
8-1
Troubleshooting
On Windows, PHP does not handle certain operating system timezones correctly On Windows, PHP does not handle certain operating system timezones correctly. If the web server is running on a machine set for one of these timezones, users connected to that web server will see all times displayed as UTC times, instead of the web server timezone.
Workaround:
In the config.php file, set the PHP "timezone_identifier" explicitly. To set the timezone, edit:
C:\Program Files\Electric Cloud\ElectricCommander\apache\htdocs\commander\ config.php
adding the following line anywhere between the opening and closing PHP tags:
date_default_timezone_set("<timezone_identifier>");
For example: To set the timezone for Taipei, you would add:
date_default_timezone_set("Asia/Taipei");
For a complete "List of Supported Timezones", see http://us2.php.net/manual/en/timezones.php
8-2

Ec Install4 0

Uploaded by

Document Information

Original Description:

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

Ec Install4 0

Uploaded by

Copyright:

Available Formats

ElectricCommander

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

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

ElectricCommander Installation Guide

System Requirements and Supported Platforms

Initial Configuration Tasks

ElectricCommander Installation Guide

Other Related Topics

ElectricCommander Installation Guide

ElectricCommander Installation Guide

What Makes ElectricCommander Unique?

See the illustrated architecture overview on the next page.

ElectricCommander Installation Guide

Commander simple architectural overview

ElectricCommander Installation Guide

System Requirements and Supported Platforms

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

System Requirements and Supported Platforms

RHEL 4 64-bit Note:

Commander installer silently fails for any type of Commander installation.

After installing Commander, run the following command as root:

ElectricCommander Installation Guide

System Requirements and Supported Platforms

System Requirements and Supported Platforms

System Requirements and Supported Platforms

ElectricCommander Installation Guide

System Requirements and Supported Platforms

Default Installation Directories

For Windows 2008 or Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander

Log File Locations

Default for Windows 2008, Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander\logs\agent

Default for Windows 2008, Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander\logs

Default for Windows 2008, Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander\apache\logs

Default for Windows 2008, Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander\logs\repository

Default for Windows 2008, Windows 7 C:\ProgramData\Electric Cloud\ElectricCommander\logs

System Requirements and Supported Platforms

System Requirements and Supported Platforms

For UNIX Agent

ElectricCommander Installation Guide

System Requirements and Supported Platforms

For Windows XP or 2003:

For Windows 2008 or Windows 7 c:\ProgramData\Electric Cloud\ElectricCommander\conf\wrapper.conf

For a repository server: Windows:

The "checksum" utility

System Requirements and Supported Platforms

System Requirements and Supported Platforms

ElectricCommander Installation Guide

information you need to supply

installing multiple remote agents.

User Interface Installation Method

Express Server Installation

Select the Express Server installation type. Click Next to continue.

ElectricCommander Installation Guide

User Interface Installation Method

Click Next to continue.

ElectricCommander Installation Guide

User Interface Installation Method

the login screen now. Click Finish to complete the installation.

ElectricCommander Installation Guide

Express Agent Installation

User Interface Installation Method

Click Next to continue.