cbsupport is a command-line tool that makes it easy to collect data commonly required for supporting CloudBees products.

Instead of having to follow detailed instructions to run several commands and collect the resulting files, cbsupport provides "one-liners" that automate those steps, reducing the effort required to collect these support data.

The cbsupport CLI can be installed on a shared jump box, the server running CloudBees software or your personal computer. You can install cbsupport in one place and configure it to work with multiple CloudBees products which may be installed elsewhere. By installing cbsupport today, you ensure that you are ready to collect required information, especially in an urgent situation when your CloudBees product is experiencing an issue.

1. Setup

1.1. Retrieving the library

The cbsupport CLI should be installed on a bastion host, ie a host having access to the cluster using http/https.

For CloudBees CI on Modern Platforms, the bastion host should also have kubectl set up with the proper context to access the cluster where the product is installed. For other products, the bastion host should have ssh access to the components of the cluster: Operations Center and Controllers (formerly known as Masters).

From a directory in your PATH:

  • macOS:

curl -LO https://s3.amazonaws.com/cbsupport-binaries/stable/cbsupport-darwin-amd64 \
  && curl -LO https://s3.amazonaws.com/cbsupport-binaries/stable/cbsupport-darwin-amd64.sha256 \
  && shasum -c cbsupport-darwin-amd64.sha256 \
  && mv cbsupport-darwin-amd64 cbsupport \
  && chmod +x cbsupport

  • Linux:

curl -LO https://s3.amazonaws.com/cbsupport-binaries/stable/cbsupport-linux-amd64 \
  && curl -LO https://s3.amazonaws.com/cbsupport-binaries/stable/cbsupport-linux-amd64.sha256 \
  && sha256sum -c cbsupport-linux-amd64.sha256 \
  && mv cbsupport-linux-amd64 cbsupport \
  && chmod +x cbsupport

  • Windows:

curl -LO https://s3.amazonaws.com/cbsupport-binaries/stable/cbsupport.exe \
  && curl -LO https://s3.amazonaws.com/cbsupport-binaries/stable/cbsupport.exe.sha256 \
  && shasum -c cbsupport.exe.sha256

1.2. Additional Setup

1.2.1. CloudBees CI (CloudBees Core) for Modern Platforms

You will need kubectl installed and configured to point to the cluster where CloudBees is installed. You can check that kubectl is properly configured by running:

kubectl get pods --all-namespaces |grep cjoc-0 |wc -l

Return should be at least one, proving that your kubectl installation is pointing to a cluster with an Operation Center running.

1.2.2. Other installations

About the ssh agent

For other installations, you will need to give the cbsupport CLI additional information about your setup. In order to do so, you will need the following information:

  • the hostname of each tenant of your cluster: if it’s a single tenant (ie you are not running an Operation Center) then the command will expect a single hostname. Otherwise, you will have to run the operation once per tenant.

  • the username used to run the Jenkins process on the tenant. Note that you should have the rights to connect using ssh with this username.

About the connection

Currently the cbsupport CLI does not store any ssh credentials and relies on the ssh agent for connection. This means that you should:

  1. add the ssh key to the ssh agent

  2. unlock the key (if needed) on the ssh agent

  3. make sure you can connect directly to the tenant with: ssh ${USERNAME}@${HOSTNAME}

  4. At the moment, only port 22 is supported for the connection
Adding a tenant

Once the ssh-agent is properly configured, you can add a new tenant using:

cbsupport setup tenant add

The setup will prompt you which Jenkins instance you wish to add the tenant for.

Updating a tenant

In case you made a mistake, or a tenant changed (hostname, or username), you can simply update it using:

cbsupport setup tenant update

The setup will prompt you which Jenkins instance you wish to update the tenant for.

Removing a tenant

In case you removed a Master from your cluster, you should also remove the associated tenant. You can do so using:

cbsupport setup tenant remove
About the tenant removal

At the moment, you can only remove a tenant that matches an actual Jenkins instance. It means that if you remove the instance from the Operation Center before removing the tenant from the cbsupport CLI, you won’t be able to see the tenant when running cbsupport setup tenant remove. This issue is logged in our system and we hope to have a fix soon.

In the meantime, a workaround is to directly delete the tenant from the cbsupport CLI configuration file (either under ~/.cbsupport/config.json or $CBSUPPORT_CONFIG).
Checking the status of the cluster

Once the cluster is setup, you can check that the cbsupport CLI can properly connect to all the tenants by running:

cbsupport check cluster

In case one tenant has an issue, you should see the exact error message in the output.

1.2.3. Credential Storage Mode

Two mode for storing credentials are available in the cbsupport CLI.

Encrypted Mode

This is the default one. It does not depend on having any third party installed on the machine and encrypts credentials in a file on the machine. The file is itself protected by a master password. This password (that you need to enter at each run of the cbsupport CLI) generates a SHA256 key using PBKDF2. It should bring enough security for the vast majority of usage.

if you choose this mode, then no additional configuration is required.
Os Store Mode

This mode uses the Os Store to manage the credentials. It requires some third parties installed and configured on the machine on Linux and macOS.

macOS Platform with Os Credential Storage Mode

On macOS: you’ll need docker-credential-osxkeychain. Note that if you have docker installed, you most likely have the docker credential oskeychain installed.

This third party is used to interact with the macOS Keychain to securely store the credentials you provide to the tool.

Linux Platform with Os Credential Storage Mode

On Linux, the cbsupport CLI uses pass to securely store the credentials you provide to the tool.

Installing pass

Follow the official guide for your distribution at Pass: Download

For example, here are simple instructions for Ubuntu / Debian:

sudo apt-get install pass

and here is for Fedora / RHEL / CentOS

sudo yum install pass

In case this is not available from your configured repositories, then you can install it from the tarball at https://www.passwordstore.org/ by running sudo make install

Setting pass up

You need a GPG key to encrypt secrets in the password store. If you do not have one you can generate it as follows:

gpg2 --gen-key

You might encounter an issue running this command. If it appears to be hanging, most likely this is because your installation doesn’t generate enough entropy to generate the gpg key, in which case you want to install rngd-utils. For example on Ubuntu / Debina please run:

sudo apt-get install rng-tools

To initialize a password store run the following replacing <gpg_key_id> with your existing key or the one generated above.

pass init <gpg_key_id>

Finally, you want to setup this environment variable in your shell startup script (.bashrc, .zshrc…​):

export GPG_TTY=$(tty)

This is required for the gpg-agent to work properly so that pass can access you GPG key.

More details on pass

For more details, please refer to Pass: The Standard Unix Password Manager

1.3. Autocompletion

The cbsupport CLI provides completion script for bash, zsh and fish.

1.3.1. Prerequisite (bash)

For bash, the bash-completion package is a pre-requisite. Please follow the documentation of the bash-completion package to properly install it.

1.3.2. Installing the script

Once the prerequisite is installed, run cbsupport completion help and follow the instructions.

1.4. Configuration

The cbsupport CLI does not need any other configuration. It will ask for the information it needs when it needs it, then save them for later reuse. It also tries to automatically find the data it needs, but always asks for a confirmation.

Pre configuration

In case you are an administrator deploying the cbsupport CLI for other users, you can configure the tool ahead of time by running cbsupport setup and following the instructions.

A few notes:

  1. The Jenkins user should have admin privileges to be able to generate the bundle.

  2. Do not use the password of the user, but generate a token as indicated in How to (re)generate my Jenkins user token – CloudBees Support.

  3. By default the configuration of the tool is persisted at $HOME/.cbsupport/config.json. The environment variable CBSUPPORT_CONFIG may be used to specify the location of the configuration file.

2. Usage

2.1. Check

Runs some smoke tests to make sure the cbsupport CLI is correctly installed and configured:

cbsupport check

2.2. Version

Dumps information about the running cbsupport CLI binary and also will notify in case a new version is available:

cbsupport version

2.3. Update

Updates the cbsupport CLI binary to the latest available version:

cbsupport update

2.4. Generating the default information

This command will generate the default information that Support needs. In case of doubt, just use this command:

cbsupport required-data default

The command is interactive and will ask for the tenant(s) on which the data gathering should happen.

2.5. Generating specific information

In case of a specific issue, Support will ask you to gather more specific data.

2.5.1. Generating information for Performance issues

The following command will generate the information that Support needs for diagnosing performance issues.

cbsupport required-data performance

The command is interactive and will ask for the tenant(s) on which the data gathering should happen.

2.5.2. Generating information for a Jenkins Build issue

The following command will generate the information (a specific build root directory) that Support needs for diagnosing Build issues.

cbsupport required-data build

The command is interactive and will ask for the tenant containing the build, the item full name and the build number. It also asks for options such as maxDepth, the maximum number of levels to descend from the build directory.

2.5.3. Generating information for a Jenkins Item (Job / Folders) issue

The following command will generate the information (a specific item root directory) that Support needs for diagnosing Item issues.

cbsupport required-data item

The command is interactive and will ask for the tenant containing the item and the item full name. It also asks for options such as maxDepth, the maximum number of levels to descend from the item directory.

2.5.4. Generating information for Ingress issues (CloudBees CI (CloudBees Core) Modern)

The following command will generate the information that Support needs for diagnosing Ingress issues.

cbsupport required-data ingress

The command is interactive and will ask for the namespace in which the Ingress Controller is deployed

2.5.5. Generating information for Sidecar Injector issues (CloudBees CI (CloudBees Core) Modern)

The following command will generate the information that Support needs for diagnosing Sidecar injector issues.

cbsupport required-data sidecar-injector

The command is interactive and will ask for the namespace in which the Sidecar Injector is deployed

2.5.6. Generating information for Jenkins Memory issues

The following command will generate the information that Support needs for diagnosing Memory related issues.

cbsupport required-data memory [–-heapdump=true|false]

The heapdump flag is optional (defaults to false) and drives whether a heapdump will be generated or not. Be aware that, depending on the size of the Heap, heapdumps can be huge and greatly increase the size of generated data. In case of doubt, do not generate the heapdump, Support will ask you specifically to activate the option.

3. Features (matrix per installation type)

Given the previous section, the feature section gives:

Command/Installtype Kubernetes Other

setup

setup tenant add

setup tenant update

setup tenant remove

check

check cluster

version

update

required-data default

1

required-data performance

required-data ingress

required-data build

required-data item

required-data sidecar-injector

required-data memory

help

1 Will only generate a bundle and jenkins cluster information but no infrastructure info.

4. Known issues and limitations

  • Proxies are not supported

  • Self signed certificates are not supported

  • On Cloudbees CI (CloudBees Core) on Modern Platforms, OpenShift is not supported

  • On Cloudbees CI (CloudBees Core) on Modern Platforms, Multicluster is not supported

  • On other installation types, an ssh agent is needed

  • On other installation types, only port 22 is allowed for ssh connections

  • When creating the working directory, cbsupport cannot create nested directories (ie the directory you provide should be located in an existing directory).

  • ~ is not recognized as home by cbsupport therefore you shouldn’t use it when providing path to the CLI.

  • In case the targeted tenant is slow to generate a support bundle, the CLI will keep the connection up without any visual feedback making think it’s stuck.