Installing the Management Console on Linux on System z

Use the mc-<version>-<build>.tar.gz tar file provided with the installation media to install and configure the Management Console on z/Linux. IBM Installation Manager is not used for this installation.

The console for z/Linux is packaged with the IBM HTTP server, rather than with the Apache web server.

After you install the Management Console, install the agent rpm package (zlinux-bfagent-<version>.rpm) on z/Linux to set up a z/Linux server for Build Forge®. For installation instructions, see Installing the agent on UNIX and Linux systems.

Information needed during installation

During installation you are asked for the following information.
  1. Installation directory
    • Provide an absolute path to the location where you want to install Build Forge®.
  2. Database information
    • Database type that Build Forge® uses (DB2, Oracle, or MySQL)
    • Database server host name
    • Database port number
    • Database name to use
    • Database user name for Build Forge® to use to connect to the database
    • Password for the database user name
    • Location of the client libraries used to access the database
    • Location of the JDBC driver jar file
  3. Application server information
    • Application server to use (the provided Tomcat or a WebSphere® Application Server installation that you have set up)

      If you choose WebSphere Application Server, you provide more information:

      • Location of the Build Forge® services component as it will be installed on WebSphere Application Server. A domain, port, and path to jas are required. Example:
        http://mydomain.com:9080/jas
      • Directory to use for plug-ins, a readable and writeable directory. Currently it is used only when integrating with Rational Team Concert.
      • WAR deployment directory: temporary location for the Build Forge® jas.war file. You deploy it to the application server after installation.
      • Path to the Java executable (java.jar)
      • Temporary storage directory for the services layer. The directory must be readable and writeable. It is used by the services component to store temporary information.
      • HTTP port for the Build Forge® services (default 3966)
      • SSL port for the Build Forge® services (default 49150)
  4. Web server information
    • Web server to use (the provided IBM HTTP server or a web server that you have set up)

      If you choose the provided IHS server, you provide more information about SSL, including whether to use SSL, ports and memory to use, and whether to use an existing secure certificate or create one.

Running the installer

  1. Go to the directory where you extracted the package for the console from the tar file.
  2. Run the following command:
    ./cmdline-install.sh

Example

The following annotated listing shows how the installer steps proceed. This listing is an annotated run and does not reflect an actual installation. Where defaults are available, they are shown in brackets, for example [y]. Press Enter to accept a default.
Install directory [/opt/buildforge]

What database will you be using?
 Enter the # of the database you will use
  1) DB2
  2) Oracle
  3) MySQL
Note: The rest of the listing assumes that Oracle was chosen.
What is your database hostname? 127.0.0.1
What is your database port number? [1521] 
What is your database name? build
What is your database user name? build
What is your database user password? 
Confirm your database user password? 

Would you like this installation to create the Build Forge database schema? (y|n) [y] 
Specify client libraries and information at this point. Depending on your choice of database, you are prompted as follows. Use absolute paths.
Please enter the directory with your database JDBC jar file? 
Note: Enter the absolute path to ojdbc14.jar.
Will you be using the supplied Tomcat app server? (y|n) n
Note: The rest of the listing assumes you are using WebSphere Application Server as your application server.

Enter the full URL used to contact the services layer on your application server: 
       http://mydomain.com:9080/jas
Enter the directory to install the Build Forge Services plugins to: 

Note: This directory must be readable and writable on the application server host. The services component uses it when Rational Team Concert is integrated with Build Forge®.
Specify the war deployment directory:
Note: Specify a directory on the local host. The installer places the jas.war file here when installation is complete. You can then deploy it into your application server.
Enter the path to a jar executable (which should be included in any JDK): 
Note: Enter the path to the .jar file for your database driver.
Enter the temporary storage path for the Services Layer: 
Note: Enter the path to a directory that the services component can use. It must be readable and writeable.
What http port will the Build Forge services layer use? [3966] 

What ssl port will the Build Forge services layer use? [49150] 

Will you be using the supplied Apache web server? (y|n)[y] 
Note: The rest of the listing assumes you entered y.
Would you like Apache to use SSL? (y|n)[n] Enter 'y' to configure Apache for SSL
Note: The rest of the listing assumes you entered y.
What ssl port will Apache use? [443]  
Please enter a memory limit for PHP (in MB): [256]

Would you like to modify or specify a custom SSL certificate? (y|n) [n]  
Note: The rest of the listing assumes you entered y and intend to create a custom certificate.

Do you have an existing secure certificate? (y|n)[n]  

A validity period is required for this cert please enter in [number][period] format

Examples: 10Y = 10 years, 6M = 6 months, 350D = 350 daysEnter the validity period for this cert: 

Enter the common name for the certificate (usually the name of the server) [linux142.rtp.raleigh.ibm.com]: 
Please enter your Locality/City: 
Please enter your State/Province:
Please enter your Organization Name: 
Please enter your Organization Unit: 
Please enter your Country from the list below: 
        France
        Taiwan
        Italy
        Germany
        Korea
        United States
        China
        Brazil
        Spain
        Japan
Please enter your Street Address:
A keystore password is required, and must be at least 6 characters long
Please enter a keystore password  

If you use IBM HTTP server rather than Apache as a web server, for additional information about setting it up and enabling SSL, see Using IBM HTTP Server instead of Apache HTTP Server.

Starting the console

  1. Start the Management Console:
    <bfinstall>/rc/buildforge start
  2. Verify that the services component (the Apache Tomcat server) started; open catalina.out and verify that start up messages are logged.
    <bfinstall>/server/tomcat/logs/catalina.out
  3. Open a web browser and enter the fully qualified z/Linux host name. For example: http://myhost.mycompany.com.

    The Management Console starts and displays the login prompt.

  4. Login as root/root.

Installing the license file

The license file for z/Linux is located in the <bfinstall> directory. The license file name is IRBF_license. After installation it contains a text message instructing you to download your actual license file from Passport Advantage.

After you have downloaded the license file and placed it in the <bfinstall> directory, configure Build Forge® to use it:

  1. Start the Management Console.
  2. Log in as root/root.
  3. Select Administration > System.
  4. Locate the License Server setting and set its value to a fully qualified path to the license file.

    For example: <bfinstall>/IRBF_license.

Enabling SSL for the Management Console

You can enable SSL to encrypt the data that is transferred between Build Forge® components:
  • Web browser client and the Apache HTTP server
  • Apache Tomcat Server and the Apache HTTP server
If you answered yes when prompted, the installation program does some of the work needed to enable SSL. To enable SSL, complete the following tasks:
  1. Review Personal Certificates and Keystores.
  2. Configure IBM HTTP server for SSL.
  3. Enable SSL in the Management Console user interface.
  4. Enable debugging for SSL.
Note: Other security features, such as password encryption and Single Sign-On (SSO), are not supported for Build Forge® on z/Linux in this release.

Review Personal Certificates and Keystores

The following keystores are created by the installation program:
Keystore Description
buildForgeKeyStore.p12 Contains a password protected keyEntry (personal certificate with public/private key pair).
buildForgeTrustStore.p12 Contains a password protected trustedCertEntry (certificate with public key only).
buildForgeKey.pem Contains a password protected private key.
buildForgeCert.pem Contains a non-password protected certificate with public key corresponding to the private key in buildForgeKey.pem.
buildForgeCA.pem Initially, contains the same information as buildForgeCert.pem; other peer certificate are added to establish trust.
buildForgeKeyForApache.pem This keystore is needed to enable SSL for the Apache HTTP server. Unlike buildForgeKey.pem, it is not password protected allowing the Apache HTTP server to start up without a password prompt.

For more information about converting an existing PEM certificate and managing certificates, see Managing certificates.

Configure IBM HTTP Server for SSL

See Configuring SSL for IHS in Using IBM HTTP Server instead of Apache HTTP Server. You must change keystore formats and add entries to httpd.conf.

Enable SSL in the Management Console UI

Use the Management Console user interface settings to enable SSL in the Management Console and update the Build Forge® database. You access those settings through Administration > Security. Then, check that the required property values are updated in the bfclient.conf configuration file.

  1. Start Build Forge®.
  2. Log on to the user interface.
  3. Go to Administration > Security.
  4. Change SSL Enabled to Yes.
  5. Click Save.
  6. Click Update Master BFClient.conf.

Enable Debugging for SSL

To debug issues with SSL in the Management Console, complete the following steps to log additional information needed for SSL.

  1. Enable debugging in the engine. Before you start the Build Forge® engine, set the following environment variable:
    export BFDEBUG_SECURITY=1
    1. Restart the Build Forge® engine.
    2. Restart IHS. Restarting IHS enables PHP to use this debug parameter.
  2. Enable debugging in Tomcat. Make the following changes in <bfinstall>/server/tomcat/common/classes/logging.properties:
    1. Add the following line:
      com.buildforge.level = ALL
    2. In the handlers section, change all other levels from FINE to ALL.

    Restart Tomcat to make the changes take effect.


Feedback