Table of contents

Administering CloudBees Jenkins Enterprise 2.x


Managing CloudBees Jenkins Enterprise 2.x

Caution

This guide has been superseded by the CloudBees Core Admin Guide.

Managing Your Operations Center Instance

This chapter describes how to manage your Operations Center instance.

Accessing Jenkins CLI

Jenkins CLI allows you to perform a number of activities on items (i.e. jobs or projects configured in your Operations Center instance), as well as agent- and administration-related activies on Operations Center, all from the command line.

The Jenkins CLI feature’s page (of the Operations Center interface) provides access to the Jenkins CLI tool (jenkins-cli.jar), which you can download from this page. This page also contains detailed information about using this tool and its features.

To access Jenkins CLI feature’s page and download the CLI tool:

  1. Access the Manage Jenkins area.

  2. On the Manage Jenkins page, scroll down and click Jenkins CLI.

  3. On the Jenkins CLI page, click the jenkins-cli.jar link to download the CLI tool near the top of this page.

  4. Move the jenkins-cli.jar file to an appropriate location on your operation system’s file system.

Using the Jenkins CLI Tool

Once you have obtained the Jenkins CLI tool (above), to use the CLI tool:

  1. In a terminal/command prompt (window), cd to the directory containing the jenkins-cli.jar file.

  2. Enter the command:

    java -jar jenkins-cli.jar -s http://operations-center-url:port-number/ command

    where:

    • port-number is the HTTP port through which Operations Center is accessible.

    • command is the Jenkins CLI command you want to execute.

    Tip

    To obtain a list of all options (like -s above or -auth for authentication) that can be passed to the
    jenkins-cli.jar command itself, enter the command:

    java -jar jenkins-cli.jar -h

Important Examples of Usage

  • To list all available Jenkins CLI tool commands, enter the command:

    java -jar jenkins-cli.jar -s http://operations-center-url:8888/ help

    which outputs a list of commands followed by indented descriptions, like:

    add-job-to-view
      Adds jobs to view.
    ...
  • To authenticate your Jenkins user when using the Jenkins CLI tool, specify the -auth option with your username and password in the format: username:password.
    For example, enter the command:

    java -jar jenkins-cli.jar -auth username:password -s http://operations-center-url:8888/ version

    which outputs something like:

    2.107.2.2
    Note

    Many Jenkins CLI commands require an authenticated Jenkins user with appropriate permissions, such as the Administer permission.

  • To obtain more information about a particular Jenkins CLI command, specify help followed by the command itself.
    For example, to obtain more information about the plugin-catalog command, enter the command:

    java -jar jenkins-cli.jar -auth username:password -s http://operations-center-url:8888/ help plugin-catalog

    which outputs:

    java -jar jenkins-cli.jar plugin-catalog [VAL] [--delete VAL] [--master VAL] [--push VAL] [--put] [--remove VAL]
    Plugin Catalog Management
     VAL          : Use a catalog name to get its metadata content. A list of
                    catalog names is returned by calling the command without any
                    parameter.
                    plugin-catalog
                    plugin-catalog my-plugin-catalog
     --delete VAL : Use this option to delete a catalog from the available list,
                    whose name is passed as parameter.
                    --delete my-plugin-catalog
     --master VAL : Master item full name (including folders and white spaces,
                    which needs double quotes). Use it in tandem with --push to
                    select the master to push the catalog to.
                    --master my-master --push my-plugin-catalog
     --push VAL   : This option pushes a catalog to a master. Use it in tandem with
                    --master to select the master to apply the catalog to.
                    --master my-master --push my-plugin-catalog
     --put        : Create or update a catalog. It will not be applied to any
                    master, just added to the catalog management.
                    --put < my-plugin-catalog.json
     --remove VAL : Removes the current catalog from a master. The catalog will not
                    be deleted from the available list.
                    --remove my-master-with-a-plugin-catalog

Configuring an Alias for the Jenkins CLI Tool

If you find yourself using the Jenkins CLI tool on a regular basis, configure an alias to save you having to write out the entire command each time.

For instance, assuming you are using on Linux operating systems and/or a Bash [1] command language environment:

  1. cd to the directory containing the jenkins-cli.jar file.

  2. In your favorite text editor, copy and paste the following into a new "alias" file:

    #!/bin/sh
    
    java -jar jenkins-cli.jar -auth username:password -s http://operations-center-url:port-number/ "$@"
  3. Adjust the username, password, operations-center-url and port-number values as required.

  4. Save the alias file with an appropriate file name (e.g. jenkins-cli.sh).
    Note: This alias file assumes that jenkins-cli.jar is located in the same directory.

  5. Make the alias file executable (e.g. chmod a+x jenkins-cli.sh).

  6. Configure the actual alias to your alias file in your appropriate Bash configuration file (i.e .bash_profile or .bashrc), which is usually located in your home directory.
    For example, in your favorite text editor, copy and paste the following line into .bash_profile or .bashrc):

    alias jenkins-cli='/path/to/jenkins-cli.sh'
  7. Edit the /path/to value as required and save the configuration file.

  8. Reload your Bash configuration by entering the appropriate command (based on the file you edited).
    For example, enter the appropriate command:

    • source ~/.bash_profile
      or

    • source ~/.bashrc

From now on, regardless of your current directory, you can enter the command: jenkins-cli, which would actually be:

java -jar jenkins-cli.jar -auth username:password -s http://operations-center-url:port-number/

Therefore, using this alias, the important examples of usage (above) could be simplified to the following:

  • Listing all available Jenkins CLI tool commands:

    jenkins-cli help
  • Retrieving the version of your Operations Center instance:

    jenkins-cli version
  • Obtaining more information about a specific Jenkins CLI command:

    jenkins-cli help plugin-catalog
Note

The remaining Jenkins CLI examples used throughout this guide assume that this alias has been configured.