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.
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:
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
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
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
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.
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:
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.
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.
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
In the meantime, a workaround is to directly delete the tenant from the cbsupport CLI configuration file (either under
Two mode for storing credentials are available in the cbsupport CLI.
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.|
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.
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.
On Linux, the cbsupport CLI uses
pass to securely store the credentials you provide to the tool.
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
You need a GPG key to encrypt secrets in the password store. If you do not have one you can generate it as follows:
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 (
This is required for the gpg-agent to work properly so that
pass can access you GPG key.
More details on
For more details, please refer to Pass: The Standard Unix Password Manager
The cbsupport CLI provides completion script for bash, zsh and fish.
For bash, the
bash-completion package is a pre-requisite.
Please follow the documentation of the bash-completion package to properly install it.
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.
In case you are an administrator deploying the cbsupport CLI for other users, you can configure the tool ahead of time by running
A few notes:
The Jenkins user should have admin privileges to be able to generate the bundle.
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.
By default the configuration of the tool is persisted at
$HOME/.cbsupport/config.json. The environment variable
CBSUPPORT_CONFIGmay be used to specify the location of the configuration file.
Runs some smoke tests to make sure the cbsupport CLI is correctly installed and configured:
Dumps information about the running cbsupport CLI binary and also will notify in case a new version is available:
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.
In case of a specific issue, Support will ask you to gather more specific data.
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.
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.
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.
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
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
The following command will generate the information that Support needs for diagnosing Memory related issues.
cbsupport required-data memory [–-heapdump=true|false]
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.
Given the previous section, the feature section gives:
setup tenant add
setup tenant update
setup tenant remove
1 Will only generate a bundle and jenkins cluster information but no infrastructure info.
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,
cbsupportcannot create nested directories (ie the directory you provide should be located in an existing directory).
~is not recognized as home by
cbsupporttherefore 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.