cbsupport CLI documentation

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.

The cbsupport CLI does not support versions of the product older than 2.107.x (Jenkins weekly 2.96).

For CloudBees CI on modern cloud 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://downloads.cloudbees.com/cbsupport/stable/cbsupport-darwin-amd64 \
  && curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport-darwin-amd64.sha256 \
  && shasum -c cbsupport-darwin-amd64.sha256 \
  && mv cbsupport-darwin-amd64 cbsupport \
  && chmod +x cbsupport
  • Linux:

curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport-linux-amd64 \
  && curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport-linux-amd64.sha256 \
  && sha256sum -c cbsupport-linux-amd64.sha256 \
  && mv cbsupport-linux-amd64 cbsupport \
  && chmod +x cbsupport
  • Windows:

curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport.exe \
  && curl -LO https://downloads.cloudbees.com/cbsupport/stable/cbsupport.exe.sha256 \
  && shasum -c cbsupport.exe.sha256

1.2. Additional Setup

1.2.1. Self signed certificate support

The configuration needs to be done at the level of the bastion host. The cbsupport CLI is loading the certificates configured at OS level. The path to the certificate depends on the OS, find here the lookup path.

1.2.2. CloudBees CI on modern cloud 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.3. 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 standalone 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

Modifying a tenant

Once the ssh-agent is properly configured, you can add, update or remove a tenant by using:

cbsupport context edit

Then follow the on-screen instruction and choose the Manage the cluster information option. The setup will prompt you which Jenkins instance you wish to add the tenant for.

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.4. 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.
Master password loss

If for some reason you lost the master password, you can delete the secrets file. Next time you run the cbsupport CLI, it will ask for a new password (and consequently, will also ask you to input your crendentials). To remove this file, run:

Removing the secret file
rm -f "${HOME}/.cbsupport/secrets.json"
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. To be able to choose this mode you need to run the cbsupport CLI in the advanced mode (--advanced-mode flag).

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. Context

Manage your context. A context is bound to a given setup. For instance, you could have a production and a staging context pointing respectively to your production and staging clusters. By default, you should not have to worry about context, your first setup is automatically pushed into a context called default. You can then choose to delete it, or create a new new one, or update it. The commands available commands are below:

cbsupport context create|delete|describe|edit|get|set

2.5. 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.6. Generating specific information

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

2.6.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.6.2. Generating information for I/O Performance issues

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

cbsupport required-data io

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

2.6.3. 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.6.4. 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.6.5. Generating information for Ingress issues (CloudBees CI on modern cloud platforms)

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.6.6. Generating information for Sidecar Injector issues (CloudBees CI on modern cloud platforms)

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.6.7. 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/InstalltypeKubernetesOther

check

check cluster

version

update

required-data default

1

required-data performance

required-data io

required-data ingress

required-data build

required-data item

required-data sidecar-injector

required-data memory

help

context create

context delete

context describe

context edit

context get

context set

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

4. Known issues and limitations

  • Proxies are not supported

  • On CloudBees CI on modern cloud 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).

  • 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.