Starting and stopping the Jazz Build Engine

The Jazz® Build Engine processes build requests. You start the build engine from a command line and stop the build engine from the build engine console. If a server is renamed, restart the Jazz Build Engine so that it points to the new repository URL.

Before you begin

The Ant build toolkit and Jazz Build Engine require a user name and password to log in to the Jazz repository. Use the following techniques to help you manage build users:

  • Create a separate build user.
  • Provide JazzUsers repository role permissions.
  • Assign a Build System client access license to the build user.
  • Provide process permissions for Engineering Workflow Management source control and build operations in the project and team areas that are associated with the relevant Jazz Build Engines and their supported build definitions.
  • Use a password file rather than specifying the password directly on the command line or in Ant task invocations. Use the Jazz Build Engine –createPasswordFile option to create an encrypted password file that you can use with Ant tasks and the Jazz Build Engine. For more information, see How can I avoid the build user password from appearing on the command line and in scripts on Jazz.net.
    Note: The password file is not strongly encrypted. Any user with access to the file can potentially decrypt it. Set appropriate operating-system file permissions on the password file to prevent access from anyone other than the user who runs the Jazz Build Engine and the Ant tasks. The main benefit of using a password file instead of the password command-line argument (for the Jazz Build Engine) or password attribute (for Ant tasks) is to avoid the password being repeated in the clear in build scripts and the shell history.

About this task

The following exit codes can be returned when the Jazz Build engine terminates.

Value Status
0 Indicates that the Jazz Build Engine exited without any errors.
1 Indicates that the Jazz Build Engine exited with an error.
2 Indicates that no pre-build participants requested a build.
3 Indicates that the Jazz Build Engine tried to authenticate using Kerberos, but the Kerberos ticket is invalid.
Note: When the Kerberos parameter is present, the command line interface obtains a Kerberos ticket through Windows logon or kinit. Ensure that the Java™ based client is configured through krb5.ini, krb5.conf, or the Java system properties (java.security.krb5.realm and java.security.krb5.kdc system properties; or the java.security.krb5.conf system property).

Procedure

  1. From a command line, navigate to installdir/buildsystem/buildengine/eclipse, where installdir is the Build System Toolkit installation directory.
    Note: When you start the build engine for Windows and Linux® systems, to ensure that the correct JDK is used, you can specify the JDK that is included in the Jazz client by using the -vm command-line argument. For other systems, ensure that the path to the Java executable file that the JAVA_EXE variable indicates in the jbe.sh script is correct. For more information, see What is the recommended JDK on Jazz.net.
  2. Start the Jazz Build Engine:
    1. For Windows systems, type jbe -vm clientinstalldir\jdk\bin\java -repository repositoryURL -userId user id -pass password -engineId engine.
    2. For Linux systems, type jbe.sh -vm clientinstalldir/jdk/bin/java -repository repositoryURL -userId user id -pass password -engineId engine.
    3. For other systems, type jbe.sh -repository repositoryURL -userId user id –pass password -engineId engine.
    • processSingleRequest is a flag. When this flag is specified, Jazz Build Engine will wait for a build request to be submitted to the build queue, pick up the build to process, and then exits the application after processing that build.
    • buildresultUUID <uuid> is a flag. When this flag is specified, Jazz Build Engine will process the build result and exit.
      Note: You can specify only one flag at a time. If a flag is not specified, Jazz Build Engine waits for a build request to be submitted, pick up the build request, process it, and then wait for a new build request.
    • clientinstalldir is the Jazz client installation directory.
    • repositoryURL is the repository URL. Example, https://hostname.example.com:9443/ccm/.
    • user id is a build user name.
    • password is the build user's password.
    • engine is the build engine identifier. For more information, see Creating build engines.
    • -includeEnvironment to include environment variables in the build properties. When this option is specified, a build property is created for each environment variable and added to the build properties for each build processed. The name of the build property is created by concatenating the prefix team.env. to the name of the environment variable. The value of the build property is the value of the environment variable. For example, if an environment variable named HOMEDRIVE is found, which has a value of C:, a build property is created named team.env.HOMEDRIVE that has a value of C:. The build properties that are created with this option override similarly named properties that are defined in the build engine or build definition. Build properties that are defined in the build engine or build definition can reference the properties that are created with this option and substitutions occur to resolve the final value of the property before it is used. For example, if you define a build engine property that is named myProperty with a value of ${team.env.HOMEDRIVE}\path\file.txt, the value of myProperty resolves to C:\path\file.txt when used in an Ant script.
    • -passwordFile password file path, where password file path is the path to an encrypted password file that is created with the -createPasswordFile parameter.
    • -propertyFile property_file_path, where property_file_path is the path to a property file. When this option is specified, the properties that are defined in the property file are added to the build properties for each build that is processed. The build properties that are specified with this option override similarly named properties that are defined in the build engine or build definition. Build properties that are defined in the build engine or build definition can reference a property that is defined in a property file and substitutions occur to resolve the final value of the property before it is used.
    • -repositories repositories file path, where repositories file path is the path to file containing information about one or more repositories and their credentials. The repositories file is created and updated by using scm login and logout commands.
    • -sleepTime seconds, where seconds is the interval of time, in seconds, between build request polling. The default value is 120 seconds. sleepTime is not applicable when you use the singleRequest and buildresultUUID <uuid> flags.
    • -verbose. For detailed logging of build engine activity.
    Note:

    You can authenticate by using any of the following methods:

    • -userId user_id -pass password
    • -userId user_id -passwordFile password_file_path
    • -userId user_id -repositories repositories_file_path
    • -certificateFile certificate_file_path -pass password
    • -smartCard -userId user_id
    • -kerberos
    • -integratedWindows
  3. To stop a build engine, in the build engine console, press (Ctrl + C).
    Note: Avoid running multiple Jazz Build Engine instances on the same machine. For more information, see Running multiple JBE processes on Jazz.net.
  4. Optional: To view all build engine usage options, from the command line, type jbe.
  5. Optional: To find the version of the build engine, from the command line, type jbe version.
  6. Optional: To specify Jazz Build Engine system properties, type -Dname=value after -vmargs. Use any of the following system properties:
    • team.build.abandonOrphans -- whether to check for orphaned builds and abandon them. An orphaned build is one that was started for the same build engine as for the running Jazz Build Engine but which that Jazz Build Engine is no longer running. This can occur if the Jazz Build Engine was interrupted when running the build, or the Jazz Team Server was down or unreachable when the Jazz Build Engine tried to complete the build. Value is true or false. Default is true.
    • team.build.retry -- whether to try service requests again if they fail with a retry error. This can help with build robustness if the Jazz Team Server is under heavy load, or the connection to it is intermittent. Requests are attempted up to 5 times (including the first attempt). Value is true or false. Default is false.
    • team.scm.renameBeforeDelete -- whether to rename the load directory to some other name before deleting it. Applicable only when using Engineering Workflow Management source control and Delete directory before loading is selected in build definition. Value is true or false. Default is false.
    • team.build.abandonCheckInterval - interval of time, in seconds, between which the Jazz Build Engine checks whether the current build it is currently processing has been abandoned. The default value is 30 seconds.