Login | Register
My pages Projects Community openCollabNet

cabie
Wiki: Cabie Administration

Wiki: Cabie Administration

Edit this page | Links to this page | Page information | Attachments | Refresh page

 

Prerequisites

In order to access administration functions using the Cabie UI, administration access must be granted by the Cabie super user. Once granted the appropriate permissions, the user with administration access must authenticate themselves to the Cabie UI by [[cabie#cabie_ui_authentication|logging in]].

In conjunction with the Cabie UI, access to the Cabie CLI (cabie.exe, cabie, or cabie.pl depending on the OS) is required at this time to perform certain operations. Access to the CLI may be obtained by the [[|Cabie administrator]]

Request access to the Cabie server machine(s) running jobs that require maintenance directly, or cloning, from the [[|Cabie administrator]]

Cabie Job Administration

all icons in the Cabie UI have hover overs enabled to display their functionality

Cabie CLI usage can be found [[cabie_administration#cabie_cli_command_usage|HERE]]

Job Administration Menu

Once authenticated to the Cabie UI each job menu will have, at a minimum, this set of icons:

With the job name to the right of the set of icons.

Creating a New Job

When the Cabie server is initially configured, it generates sample jobs and build scripts that ease job creation and configuration any of which are available for 'cloning'.

When a job is cloned, all job configuration tables are duplicated in SQL except for the jobs table. The new job name is substituted for the old job name, so if the the naming convention for directories, source code control clients, workspaces or modules follows suit all naming will be correctly handled. Along with SQL tables being altered, all build scripts on the Cabie server are duplicated with the same substitutions for job names happening.

Something the clone function does not do is check out source code. That is up to the person cloning or creating the new job.

Here's the steps that need to be run in order to clone an existing job. For purposes here, the 7-13-2-nightly-mac job will be cloned as a new job called 7-13-3-nightly-mac on macbuild1.example/.com

  • - Obtain the [CLI] - Install the Cabie CLI somewhere in the path on a machine of your choice (your laptop for instance) - In the environment of the machine where the Cabie CLI is installed set the following variable:

    • BLDSERVER=macbuild1.movenetworks.com:9190
    - From the command line run:
    • build describe -n 7-13-2-nightly-mac
    • Find the line that starts with 'Build root' and note the directory without 7-13-2-nightly-mac (/Volumes/build/src)

    - Log into the Cabie server (macbuild1.movenetworks.com) using credentials supplied from the [http://wiki.example.com/doku/doku.php?id=cabie_administration#prerequisites|prerequisites] - cd to the directory noted in step 4 - Create a directory called 7-13-3-nightly-mac - cd to 7-13-3-nightly-mac - Create the accurev workspace:

    • accurev mkws -w cabie.7-13-3-nightly-mac -b <backing stream> -l /Volumes/build/src/7-13-3-nightly-mac

    - Check out the code:
    • accurev update
    - From the same command window used in step 4, run:
    • build clone -n 7-13-2-nightly-mac -c 7-13-3-nightly-mac

The new job has been created, but isn't necessarily ready to run.

The player jobs in particular make use of custom fields so that scripts can be shared, there's no editing of any scripts necessary, however, the build description may need to be changed by [the job]. And custom fields will need to be altered to account for the version change from 7.13.2 to 7.13.3 by [custom fields].

Editing a Job

In order to edit a job, the icon <sub>{{table_edit.png|}}</sub> displayed in the corresponding job menu needs to be clicked. Once clicked the configuration editor for the job will appear. Since the editor associates the table name with the resulting display, the rendered page will result in this as a title bar:

The default action when selected is 'edit record' mode. Clicking on the atachment:table_add.png icon will result in the configuration editor with empty fields, this can be used for adding a new record - there is an easier way to create a new job. For the purposes of this documentation, just use this as an editor for the selected job.

The resulting window will appear like this:

Each value available for editing is pretty self explanatory. The left hand column indicates what the field is for, the right hand column shows the current value for the job. The most common job properties to edit will be:

  • A description for the <job name> job that can be displayed via the web or from the build client

    • Changing this value will result in correct job information being displayed to the end user
  • A value used to indicate to the server if the 7-13-1-nightly-mac job is active or not
    • Setting this value to 'no' will result in the job disappearing from view requiring that it be restored before it can be accessed again
  • A value used to indicate whether email should be sent to a globally defined group for build failures
  • A value used to indicate whether this job will fire off automatically if changes are pending
  • Email address for the group where shame mail will be sent when the build breaks
  • The name of the group the <job name> job is associated with (optional)

Other fields may be edited, but since the easiest way to create a new job is to 'clone' an existing job, most of the job's values will automatically be changed.

As with all forms displayed using the Cabie UI, clicking on 'Submit', then 'Ok' to the popup will update the existing record.

Changing the name of the job, or the server name will result in a new record, but without cloning all other tables, or scripts. It is recommended to not alter the job name or server without knowing absolutely what you are doing!!!!!

Examining via the job editor, other jobs will display a variety of configurations for various source code control systems, bug tracking systems, bug searching in logs.

Creating or Editing a File Exclusion List

There may be occasion where certain files should not trigger a build. If a project checks libraries into a common directory shared by other projects, the each time the project is built, the resulting build would trigger builds for all other projects sharing the resource, they in turn may check in to the shared resource, and just create an endless loop of builds.

The player build for instance, can check in version files. Triggering a build due to a version file change is undesirable since it, in its self, does not affect the functionality of the resulting build. There may also be text files that exist in a tree which development wouldn't want triggering a build when they get updated.

Whatever the reason, excluding files from triggering a build is necessary at times. Cabie has an exclusion table to do just that.

In order to add, or edit existing values in the exclusion table for an existing job, click on the icon. Here's the resulting display (this example is already populated):

This exclusion list doesn't care if the exclusion is a file or directory, all it cares about is the string. In the above example it's ignoring qmp.dat, qmpversion.h, and qsp.js if found at the end of any line. The exclusion string is a [regular expression].

As will all Cabie UI editor functions, when done, click on Submit, then Ok in the popup dialog.

Creating and Editing Promotion Actions

Creating and Editing Custom Fields

In order to create or edit custom fields, click on the icon displayed on the [administration menu] to the left of the job name. What's displayed will look like so (this is a player job example):

If no values exist, there will be a single empty 'Property description:value:'. Each time a value is submitted a new field becomes available.

For the sake of the custom values displayed above, some detail will be provided here. These custom values:

  • feature:0
  • major:7
  • minor:13
  • patch:2
  • scope:0

will all be concatenated together with a build number to represent a binary version, the display order in the custom editor is not important, the variables will be accessed correctly no matter what the display order is, with the resulting Player version looking like this:

071302000002

The last number '2' is the build number. If scope is set to '1', then the resulting build could be used for testing Player upgrades. The only other custom value currently accessed in this example is 'workspace:cabie.7-13-2-nightly-mac_build' and is used to describe the workspace for display purposes. All the custom values may be used by the Cabie server as macros to be expanded when viewing [job characteristics].

The underlying document for build job characteristics looks like this for all player and SDK jobs:

<b>%sccs% server:</b>

%port%

<b>%sccs% basis stream</b>

%client%

<b>%sccs% workspace</b>

%custom:workspace%

<b>%title% additional information:</b> <html> <pre> major: %custom:major% minor: %custom:minor% patch: %custom:patch% scope: %custom:scope% feature: %custom:feature% </pre> </html>

<b>output:</b>

binaries and logs generated on %server% for the %title% job are stored in %output% this same output is made available internally <a href=%url%>here</a>

this job will save at most the last %keeplevel% builds

%title% is %state%. build failure notification to <a href=mailto:%group%>%group%</a> is currently %spam%

<b>job description:</b>

%comment%

<b>questions:</b>

send email to the <a href="mailto:%admin%">Build Admin</a>

Removing a Job

There will a time when the Cabie UI becomes to cluttered with jobs, many of which are no longer active projects. There is no point having to look at them, poll them for changes, and, in the case of a product that may have already shipped, have a build accidentally fire off because someone accidentally checked into the wrong tree (never happens right?)

Any job under the control of Cabie can be removed from view of Cabie server processes and the Cabie UI. To do so is very easy, just click on the icon found on the Cabie Job menu. Removing the job from view of the Cabie server processes and the Cabie UI does not remove any builds, nor does it remove the job configuration. At any point, if necessary, the build can be recovered as discussed in Cabie Server Administration.

Cabie Server Administration

Outside of job administration, the guts of Cabie administration rely on direct access to the build machine. Direct access is limited to a few individuals at Move, and will be covered later. There are a few things that can be seen or done via the Cabie Server Administration Menu, those functions will be discussed here.

Server Administration Menu

Each server menu will have, at a minimum, this set of options:

With the server name to the left of the set of icons.

Restoring a Previously Removed Job

If a job was removed from view of the Cabie server processes and the Cabie UI, then the necessity arises to have to have it operational again (late delivery, bug fixes etc), restoration of the job, along with all of it's characteristics is available to the Cabie administrator.

On the Server Administration Menu, there is an icon, , which when clicked will bring up a display similar to this one

The resulting display has jobs listed alphabetically with a description of the job in the right hand column. In order to restore the job, just click on the job name. When returned to the main display, the job will now be displayed, and active, well at least in the same stat it was in before it was removed.

Cabie Server Configuration Information

Currently there is no editor for the primary Cabie configuration file. It is a generated configuration class that is generated when Cabie is first installed on a server intended to host Cabie. Values are set through the interaction of a configuration script that not only builds the configuration class, but generates the build database, it's tables, then loads initial values into the database tables. Once configured, the only way currently to edit the configuration is to manually edit the configuration class file, shutdown the cabie processes, then restart the cabie processes. It is possible to view loaded values however, through the Server Administration Menu.

To do so, click on the icon. This will be the resulting view (a few values are cut off at the bottom):

Even though you may not be able to edit values, there will be times where being able to view them may come in handy.

Shutting Down the Cabie Server

Shutting down the Cabie server process for an individual server can be accomplished by clicking on the from the Server Administration Menu. On POSIX environments, the build server will shutdown cleanly. For Windows, after clicking on the icon, you need to login to the Windows machine the process is running on, then bring up the taskmanager, search for perl, and kill those processes. This is a Cabie problem, and will be resolved in the near future.

For Mac's needing to create dmg files, a reboot is required due to a limitation of directly accessing the disk service on OS X, required for building dmg images

Cabie CLI Command Usage

accubug:

  • accubug accubug -i issue display basic issue information from accuwork

adduser:

  • adduser -p port -u username -f first -l last [-m mail ] [-g group] Add new user to CM server

authorize:

  • authorize -c computername authorize computername to control builds

authorized:

  • authorized display list of computers authorized to control builds

build:

  • build -n jobname [-j jobno]

buildlog:

  • buildlog -n jobname -t retail|debug [-w] retrieve buildlog of defined job

changed:

  • changed -n jobname -j jobno [-e endjobno] Display list of files updated for job jobno

changestate:

  • changestate -n jobname -j jobno -s status [-k keep]

    Change status for <jobname> build <jobno> -s untested | failedtest | failedbuild | passedtest | failedunit -k keep the build

cleanjob:

  • cleanjob -n jobname -j jobno <-f -r -t testname> Remove all records associated with <jobname> <jobno>. -f forces removal -r rolls back to previous build -t testname remove test semaphores only for <testname> This is permanent - it cannot not be un-done!

clone:

  • clone -n oldjobname -c newjobname Create new job by copying oldjob configuration

commands:

  • commands -l -w Display supported command set

connectlog:

  • connectlog [-l limit] display client connection log [limit to limit number of records]

createjob:

  • createjob -n jobname
    • -p (p4 port/cvs root/svn repository) -c (p4 client/cvs module/svn directory) -r sourceroot -t debug|retail|both -d toolsdir -k keeplevel -s sccs -b browserlink -m global failure notification -C "comment" [-D] dump existing job in cmd line format

debuglog:

  • debuglog -n jobname complete debug log of defined job

deluser:

  • deluser -p port -u username [-f first -l last -g group] Remove user from CM server

describe:

  • describe -n job describe charastics of defined job

disable:

  • disable -n job Disable build job

dumpconfig:

  • dumpconfig Display buildserver configuration loaded from buildconf.pm

dumpschema:

  • dumpschema [-t table] Display buildserver schema information

dumpschema:

  • dumpschema [-t table] Display buildserver schema information

elapsed:

  • elapsed -n job Display elapsed time for current build job

enable:

  • enable -n job [-f -k] Enable build job [-f force semaphore removal] [-k kill running build process] (requires -f)

errorlog:

  • errorlog -n jobname -t retail|debug retrieve errorlog of defined job

free:

  • free -n jobname -j jobno Release locks allowing jobno for build jobname to be deleted by the buildserver

getid:

  • getid Display buildserver process ID

graphjob:

  • graphjob graphjob -n jobname Generate PHP code to be used by the Cabie UI

help:

  • help [command] Display [command] usage

incomplete:

  • incomplete -n jobname [-l limit] Will display (optionally limit) build numbers of failed builds for jobname

instructions:

  • instructions -n jobname instructions for building a defined job locally

joblog:

  • joblog -n jobname complete run log of defined job

jobstate:

  • jobstate Display buildserver job status

keep:

  • keep -n jobname -j jobno [-u username] [-c comment] Keep jobname for build jobno from being automatically deleted

kill:

  • kill -p pid -s signal kill process by PID (see ps) on the server

lastchange:

  • lastchange -n jobname [-l n] display last [n] updates for jobname.

laststart:

  • laststart [-l n] display last [n] buildserver starts

migrate:

  • migrate -n jobname -t server migrate all job configuration for jobname information to new server

nextjob:

  • nextjob -n jobname display updates CM system will make for jobname with next sync

notify:

  • notify -n jobname -f firstjob -l lastjob -c comment Send email with comment to all submitters of jobname from firstjob to lastjob

promote:

  • promote -c comment -n jobname [-h view states] -j jobno Promote jobname jobno for formal testing or release

ps:

  • ps [-t] Build Unix style process table on the server

recover:

  • recover -n jobname Recover active jobs accidentally removed by enable command

rejectlog:

  • rejectlog [-l limit] display client rejection log [limit to limit number of records]

removed:

  • removed display jobs no longer under build server control

removejob:

  • removejob -n jobname [-f] Remove defined job from the buildserver [-f permanent deletion]

restorejob:

  • restorejob -n jobname Add previously defined job back to the buildserver

runstats:

  • runstats -n job Display statistics for [optionally -l] last build jobs -a displays only the average build time -r displays raw time in ticks (seconds) useful for feeding into a script

servers:

  • servers display other build servers

set:

  • set Display build server environment variables

showusers:

  • showusers -n jobname display all users known to the cm system hosting sources for [jobname]

shutdown:

  • shutdown shutdown buildserver processes

status:

  • status -n job Check build status

subscribe:

  • subscribe -n jobname -e emailaddress subscribe for automatic email notification of defined job

subscribers:

  • subscribers -n jobname display email subscription list for a defined job

synclog:

  • synclog -n jobname retrieve synclog of defined job

sysinfo:

  • sysinfo display hardware/software configuration for build server

testserver:

  • testserver -l || <-f server> View status of servers running tests (-l) Free (-f servername) server for testing

<b>teststatus</b>:

  • teststatus -n (jobname|all)
    • [-j jobno] [-l n limit to n records] [-r include running tests] [-p include pending tests] [-c include completed tests]

treeperms:

  • treeperms -n job [-i] -u userid -a|-r|-l (add, remove or list) Authorize/unauthorize checkins to a job To view available groups use -n all -i To view users in a module use -n jobname -l

unauthorize:

  • unauthorize -c machinename remove computername from authorization list

unsubscribe:

  • unsubscribe -n jobname -e emailaddress unsubscribe from automatic email notification of defined job

whatsnew:

  • whatsnew display latest changes made to the build server

xmldump:

  • xmldump -n (jobname|all)
    • [-j jobno] [-s (server|all)] [-l limit] [-f include files] [-c include comments] [-t include test status] [-r include running jobs] [-p include promotion info]

</pre> </html>

Cabie Administration (last edited 2009-02-13 19:11:02 -0700 by ?getsw)